Vortex

Vortex is a cross-border payments gateway built on Pendulum. It provides fiat onramps and offramps, cross-chain stablecoin routing, partner APIs, an embeddable widget, an account dashboard, and an integration SDK.

Repository

This is a Bun monorepo.

Workspace	Purpose
apps/api	Express API, ramp engine, provider integrations, PostgreSQL workers
apps/frontend	Public site and embeddable ramp widget
apps/dashboard	Authenticated customer dashboard
apps/rebalancer	Liquidity rebalancing service
packages/shared	Shared contracts, token/network configuration, and signing utilities
packages/kyc	Provider KYC/KYB state machines shared by the two web apps
packages/sdk	Public @vortexfi/sdk integration package
contracts/relayer	Token relayer Solidity project

See MAP.md for detailed wayfinding and docs/README.md for the documentation structure.

Getting started

Requirements: Node.js 18+ and the Bun version declared by packageManager in package.json.

bun install
bun dev

The default development command starts the shared package, API, and widget. Run other surfaces explicitly:

bun dev:dashboard
bun dev:rebalancer

Copy the relevant workspace's .env.example to .env before running code that needs database, provider, chain, or authentication credentials. Never commit real secrets.

Common commands

bun build
bun typecheck
bun verify
bun lint
bun lint:fix
bun test

Useful targeted commands:

bun test:db:start
bun test:api
bun test:frontend
bun test:e2e
bun test:e2e:dashboard
bun test:contracts:relayer

The root scripts in package.json are the canonical command list. Workspace-specific setup and caveats live in their README.md or CLAUDE.md.

Documentation

• docs/security-spec/ is the audit-facing source of truth for security-sensitive behavior.
• docs/api/ contains the public OpenAPI source and partner guides.
• docs/README.md indexes current architecture, product, operations, decisions, incidents, and proposals.
• CLAUDE.md and scoped CLAUDE.md files contain coding-agent rules.

AI integration guidance

The repository includes a Vortex integration skill at .agents/skills/vortex-integration/SKILL.md. When working outside this repository, it can be installed from:

https://github.com/pendulum-chain/vortex/tree/main/.agents/skills/vortex-integration

The published AI-agent integration guide is available at https://api-docs.vortexfinance.co/ai-agent-integration.