Swap

Swap API overview

Onboard companies and move money between fiat and stablecoin
View as Markdown

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, 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.

$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

1

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.

2

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.

3

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.

4

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.

5

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 guide.

Environments

EnvironmentBase URL
Productionhttps://public-api.alphax.com
Sandboxhttps://public-api.demo.alphax.asia

See the Quickstart to run the full flow end to end.