> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.alphax.asia/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.alphax.asia/_mcp/server.

# Swap API overview

The AlphaX Swap API lets you — a **partner** — onboard companies and open
**payment routes** for them: standing instructions that convert money arriving at
one end and pay it out at the other.

It shares its authentication and company model with the
[Card API](/cards/overview), so if you already integrate cards, only the
resources below are new.

## Authentication & acting for a company

Every request is authenticated with your partner API key in the `X-API-Key`
header. Endpoints that act on a specific company also take an `X-Company-Id`
header — the ULID of the company you are acting for.

```bash
curl https://public-api.alphax.com/v1/payment-routes \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "X-Company-Id: 01KZ2WJKWVFPCVAB6MY106QRZV"
```

`POST /v1/companies` and `GET /v1/companies` do **not** take `X-Company-Id`.
Everything scoped to a single company (verification link, payment routes,
transactions) does.

## What a payment route is

A route is opened once and then left in place. Money that arrives at its source
is converted and paid out at its destination, every time, until you stop using
it. There are two directions:

#### On-ramp

We open a **deposit account** in a fiat currency. What lands there is paid
out as stablecoin to an address you nominate.

#### Off-ramp

We open a **deposit address** on a chain. Stablecoin sent there is paid out
as fiat to a bank account you nominate.

Both are created through the same endpoint, discriminated by `type`.

## The end-to-end flow

#### Onboard a company onto swap

`POST /v1/companies` with `products: ["Swap"]` creates a company, links it
to you, and returns a `swap` block containing the verification link.

#### Verify the company

Send the director to `swap.kycUrl`, or embed it in your own site. Watch
`company.kyc_status_changed` for the outcome — see the
[Verification page](/swap/kyc-page).

#### Open a payment route

`POST /v1/payment-routes` with `type: "onramp"` or `type: "offramp"`. The
company must be **activated** by AlphaX first — until then you get
`403 COMPANY_NOT_ACTIVE`. Watch `company.onboarding_status_changed`.

#### Tell the payer where to send funds

`GET /v1/payment-routes/{id}` returns `depositAddress` plus the full
instructions. Two PDFs are available for the customer's bank.

#### Follow the money

`GET /v1/payment-routes/{id}/transactions`, or `GET /v1/transactions` for
everything at once. `payment_route.transaction.created` pushes the same
object to you as it happens.

## Asynchronous by design

Verification and settlement complete in the background. Rather than polling,
subscribe to **webhooks** — see the [Swap webhooks](/swap/webhooks) guide.

## Environments

| Environment | Base URL                              |
| ----------- | ------------------------------------- |
| Production  | `https://public-api.alphax.com`       |
| Sandbox     | `https://public-api.demo.alphax.asia` |

See the [Quickstart](/swap/quickstart) to run the full flow end to end.