Conventions
Amounts, assets, countries, ids, timestamps, pagination and the headers every integration uses.
Requests and responses
The API speaks JSON over HTTPS. Send Content-Type: application/json with a body, and expect JSON back. Every path starts with /v1 on your environment's base URL. Field names are snake_case, in requests and responses alike.
We add fields and values to responses over time without a new version. Ignore fields you do not know, and treat an unknown value of a state or a code as "something you do not handle yet" rather than an error.
Amounts
Amounts are decimal strings, never JSON numbers, in requests and in responses. A sum of money is an object of an amount and its asset:
{ "amount": "918.58", "asset": "EUR" }Parse amounts into a decimal type (BigDecimal, decimal.Decimal, shopspring/decimal), never into a float. Each asset has a scale, the most decimals an amount in it may carry:
| Assets | Scale | Example |
|---|---|---|
| USDC, USDT, EURC | 6 | "1000.123456" |
| Fiat currencies (EUR, GBP, USD, PKR, ...) | 2 | "918.58" |
An amount with more decimals than its asset's scale is refused with amount_scale; an amount that is not a positive decimal with bad_amount. Trailing zeros are fine: "1000.50" is "1000.5". Responses do not pad amounts to the scale, so "1000" and "0.5" are normal.
Rates are decimal strings too. A rate is how many units of a Leg's destination asset one unit of its source asset buys: "0.92" on a USDC to EUR Leg means 1 USDC buys 0.92 EUR.
Assets and countries
- Assets are ISO 4217 codes for fiat (
EUR,USD,PKR) and tickers for stablecoins (USDC,USDT,EURC). - Countries are ISO 3166-1 alpha-2 codes (
DE,US,PK).
Send both in upper case. A Beneficiary's country and asset are upper-cased for you; other fields, such as source_asset on a quote request, are taken as sent.
Ids
Resource ids (Payouts, Beneficiaries, webhook endpoints, deliveries, events, End Customers) are UUID strings. Some values are opaque tokens: a quote_id (starting qt1.) and a pagination cursor. Store them and send them back exactly; do not parse or build them.
A path id that is not a UUID is refused with invalid_id (400) on most routes. An id that belongs to another account answers 404, the same as one that does not exist.
Timestamps
Timestamps are RFC 3339 strings in UTC, such as "2026-11-12T10:00:20Z". Some carry fractional seconds ("2026-11-12T10:00:20.123456Z"), so parse them with a full RFC 3339 parser.
A quote set carries server_time, the moment we answered. Count a Quote's time left from server_time to expires_at; your server's clock may be off.
Pagination
List endpoints come in three forms.
Cursor pages. GET /v1/payouts and GET /v1/incoming-payouts answer newest first. Pass limit (1 to 100, 50 by default) and, for the next page, the next_cursor of the previous page as cursor. next_cursor is absent on the last page.
curl "$APEX_BASE_URL/v1/payouts?state=completed&limit=100&cursor=eyJjIjoiMjAyNi0xMS0xMl..." \
-H "Authorization: Bearer $APEX_API_KEY"| Endpoint | Items field | Filters |
|---|---|---|
GET /v1/payouts | payouts | state: awaiting_approval, accepted, funded, processing, completed, failed, refunded, cancelled |
GET /v1/incoming-payouts | items | none |
{
"payouts": [{ "id": "7d41f0b2-9c3e-4a85-b6d1-2e8f5a7c9b13", "state": "completed" }],
"next_cursor": "eyJjIjoiMjAyNi0xMS0xMlQxMDowMDoyMFoiLCJpIjoiN2Q0MWYwYjIi..."
}A cursor that no page produced is refused with bad_cursor, a limit out of range with bad_limit, and an unknown state with unknown_state (all 422).
Offset pages. GET /v1/end-customers takes limit (50 by default, at most 500) and offset, and answers a plain array, newest first. It also filters by state and searches names and emails with q.
Whole lists. GET /v1/balances, GET /v1/beneficiaries, GET /v1/deposit-instructions and GET /v1/webhooks answer every item as a plain array. GET /v1/webhooks/{id}/deliveries answers the newest deliveries, limit of them (1 to 100, 50 by default).
Correlation id
Every response carries an X-Correlation-ID header, and every error body repeats it as correlation_id. It identifies the request in our logs. Log it with your own request id, and quote it when you contact support. We assign it; one you send is not used.
Acting for an End Customer
A Platform acts for one of its End Customers by sending the End Customer's id in the Apex-End-Customer header on an ordinary /v1 call:
curl "$APEX_BASE_URL/v1/balances" \
-H "Authorization: Bearer $APEX_API_KEY" \
-H "Apex-End-Customer: 8a3f5d27-c1e9-4b64-9d0a-6e2b7f4c1d93"The call then reads and acts on that End Customer's balances, Beneficiaries and Payouts, under your key's permissions. An id that is not one of your End Customers answers end_customer_not_found (404); a caller that is not a Platform gets not_a_platform (403). The Platforms guide covers End Customers in full.