Quickstart
Send your first sandbox payout, from an API key to a completed Payout.
This guide sends 1000 USDC from your sandbox balance to a company in Germany, which receives 918.58 EUR. It takes six calls. You need a sandbox account whose standing is active and a person on it with the Customer admin role.
Set two environment variables first. The sandbox base URL comes with your account.
export APEX_BASE_URL="<your sandbox base URL>"
export APEX_API_KEY="ak_test_..."Get a test key
In the Customer panel, open API keys and choose Create key. Give it a name such as Quickstart and these permissions:
- Read balances, payouts and beneficiaries (
customer:read) - Create and cancel payouts (
customer:payouts:create) - Register beneficiaries (
customer:beneficiaries:write)
The key is shown once, as ak_test_ followed by two random parts. Store it in your secret store, then check that it works:
curl "$APEX_BASE_URL/v1/customer" \
-H "Authorization: Bearer $APEX_API_KEY"{
"id": "5f8c2a91-3e4b-4d6a-9c1f-7b2e8d4a6c30",
"legal_name": "Tom Trading Inc",
"type": "business",
"country": "US",
"standing": "active",
"providers": ["bvnk", "zerohash"],
"kind": "direct"
}providers lists the Providers that have approved your account. A route can only use those Providers.
Check your balance
curl "$APEX_BASE_URL/v1/balances" \
-H "Authorization: Bearer $APEX_API_KEY"[
{
"asset": "USDC",
"available": "1000",
"held": "0",
"held_at": [{ "provider": "bvnk", "available": "1000", "held": "0" }]
}
]available is what you can send now. held is set aside for Payouts on their way. held_at splits each balance by the Provider that holds it. A Payout is paid from one Provider's part only, so the routes you are offered depend on where your money is. See Balances and deposits.
Funding your sandbox balance
GET /v1/deposit-instructions?asset=USDC tells you where to deposit. In sandbox the Providers are simulated and the addresses are placeholders, so nothing sent to them arrives. Ask your account team to credit test funds to your sandbox balance.
Create or pick a Beneficiary
List the Beneficiaries you already have and pick one whose state is verified, with the country and currency you want to pay:
curl "$APEX_BASE_URL/v1/beneficiaries" \
-H "Authorization: Bearer $APEX_API_KEY"Or register a new one. A company in Germany paid in euro needs iban and name in details:
curl -X POST "$APEX_BASE_URL/v1/beneficiaries" \
-H "Authorization: Bearer $APEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"kind": "external",
"party_type": "business",
"name": "Muster GmbH",
"country": "DE",
"asset": "EUR",
"details": { "iban": "DE89370400440532013000", "name": "Muster GmbH" }
}'{
"id": "c1e7b3a9-4d2f-4a6e-8b05-9f3d2c7e1a84",
"kind": "external",
"state": "pending_verification",
"party_type": "business",
"name": "Muster GmbH",
"country": "DE",
"asset": "EUR",
"details": { "iban": "••••3000", "name": "Muster GmbH" },
"available": true,
"created_at": "2026-11-12T09:41:07Z",
"updated_at": "2026-11-12T09:41:07Z"
}The details a destination needs follow its country and currency: iban and name for euro in a SEPA country, account_number, sort_code and name for pounds in GB, account_number, routing_number and name for dollars in the US. A field no route to that destination asks for is refused with beneficiary_fields_invalid. Account numbers come back masked to their last four characters. See Beneficiaries for every kind and destination.
New Beneficiaries wait for review
A Beneficiary you register starts in pending_verification. Our compliance team verifies it, in sandbox too, and you can pay it once its state is verified. Subscribe to beneficiary.updated to hear about it as soon as it happens.
Ask for quotes
Send the amount, the asset it leaves your balance in, the Beneficiary and the purpose of the payment. The destination country and currency are the Beneficiary's, so you do not send them.
curl -X POST "$APEX_BASE_URL/v1/quotes" \
-H "Authorization: Bearer $APEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"source_asset": "USDC",
"amount": "1000",
"beneficiary_id": "c1e7b3a9-4d2f-4a6e-8b05-9f3d2c7e1a84",
"purpose": "services",
"preference": "fastest"
}'Prop
Type
The sandbox offers two routes to a German IBAN: SEPA Instant and SEPA Credit Transfer. Both deliver 918.58 EUR; SEPA Credit Transfer takes about a day longer. The response below is trimmed to the first Quote.
{
"quote_set_id": "6e2a9c4f-8b1d-4f37-a5c2-1d9e7b3f0a52",
"quotes": [
{
"quote_id": "qt1.eyJkIjoiNmUyYTljNGYtOGIxZC00ZjM3...",
"send": { "amount": "1000", "asset": "USDC" },
"receive": { "amount": "918.58", "asset": "EUR" },
"fees": [
{ "provider": "bvnk", "component": "provider", "amount": { "amount": "1", "asset": "USDC" } },
{ "provider": "bvnk", "component": "provider", "amount": { "amount": "0.5", "asset": "EUR" } }
],
"rates": [
{ "provider": "bvnk", "rate": "0.92" },
{ "provider": "bvnk", "rate": "1" }
],
"providers": ["bvnk"],
"settlement_seconds": 120,
"estimated_arrival": "2026-11-12T10:02:00Z",
"expires_at": "2026-11-12T10:01:00Z",
"labels": ["fastest"]
}
],
"server_time": "2026-11-12T10:00:00Z"
}Read the numbers Leg by Leg: the conversion takes a 1 USDC fee, so 999 USDC is converted at 0.92 into 919.08 EUR, and the SEPA Instant payout takes 0.5 EUR. The Beneficiary receives 918.58 EUR. Every fee is in the asset its Leg takes. A service_fee line appears when your pricing includes our fee.
labels marks the Quote that delivers the most (cheapest) and the one that settles soonest (fastest). A Quote is valid until expires_at, about a minute in sandbox. Count the time left from server_time, not from your own clock.
When no Quote can be offered, the call still answers 201 with an empty quotes list and an unavailable_reason:
unavailable_reason | What to do |
|---|---|
beneficiary_not_verified | Wait until the Beneficiary is verified. |
onboarding_required | A Provider on every route has not approved your account yet. Contact your account team. |
funds_at_other_provider | You hold the amount, but not at the Provider the routes start from. Deposit at a Provider listed in deposit_at. |
amount_out_of_range | The amount is outside what the routes take. Try another amount. |
temporarily_unavailable | The route is paused for a while. Try again later. |
no_route | No route can take this payment. |
Accept a quote
Create a Payout from the quote_id before it expires. Send an Idempotency-Key header: a value you generate once for this payout and send again, unchanged, on every retry. See Idempotency.
curl -X POST "$APEX_BASE_URL/v1/payouts" \
-H "Authorization: Bearer $APEX_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 3f6c1d2e-8a4b-4c9d-b1e7-5a2f9c8d0e13" \
-d '{ "quote_id": "qt1.eyJkIjoiNmUyYTljNGYtOGIxZC00ZjM3..." }'{
"id": "7d41f0b2-9c3e-4a85-b6d1-2e8f5a7c9b13",
"state": "processing",
"send": { "amount": "1000", "asset": "USDC" },
"receive": { "amount": "918.58", "asset": "EUR" },
"fees": [
{ "provider": "bvnk", "component": "provider", "amount": { "amount": "1", "asset": "USDC" } },
{ "provider": "bvnk", "component": "provider", "amount": { "amount": "0.5", "asset": "EUR" } }
],
"rates": [
{ "provider": "bvnk", "rate": "0.92" },
{ "provider": "bvnk", "rate": "1" }
],
"beneficiary": {
"id": "c1e7b3a9-4d2f-4a6e-8b05-9f3d2c7e1a84",
"name": "Muster GmbH",
"country": "DE",
"party_type": "business"
},
"delivered_to": "bank_account",
"legs": [
{ "index": 0, "provider": "bvnk", "from": "USDC", "to": "EUR", "state": "pending" },
{ "index": 1, "provider": "bvnk", "from": "EUR", "to": "EUR", "state": "pending" }
],
"initiated_by": { "actor": "customer", "kind": "api_key", "id": "a3d9e1f4-6b2c-4e8a-9f17-2c5b8d1e4a60" },
"initiated_by_you": true,
"cancellable": false,
"created_at": "2026-11-12T10:00:20Z",
"updated_at": "2026-11-12T10:00:20Z"
}The new Payout's state is one of:
processing: your balance covered it, the amount is held, and the route is running.awaiting_approval: your approval rules hold it for a second person, who approves it in the Customer panel. An API key never approves.accepted: your balance at the route's first Provider does not cover it yet. It waits for funds and is cancelled if its Quote expires first, so fund your balance before you send.
A Quote turns into one Payout only. Accepting it again with a different Idempotency-Key answers quote_already_used (409). Until a Payout is funded (accepted or awaiting_approval) you can cancel it with POST /v1/payouts/{id}/cancel.
Follow it to the end
By webhook (recommended). Register an endpoint for payout.updated and we send you the full Payout on every state change. See Webhooks.
By polling. Read the Payout until it reaches a final state. Poll every few seconds at most and back off over time.
curl "$APEX_BASE_URL/v1/payouts/7d41f0b2-9c3e-4a85-b6d1-2e8f5a7c9b13" \
-H "Authorization: Bearer $APEX_API_KEY"{
"id": "7d41f0b2-9c3e-4a85-b6d1-2e8f5a7c9b13",
"state": "completed",
"receive": { "amount": "918.58", "asset": "EUR" },
"legs": [
{ "index": 0, "provider": "bvnk", "from": "USDC", "to": "EUR", "state": "completed", "settled_at": "2026-11-12T10:01:04Z" },
{ "index": 1, "provider": "bvnk", "from": "EUR", "to": "EUR", "state": "completed", "settled_at": "2026-11-12T10:02:11Z" }
],
"timeline": [
{ "state": "accepted", "at": "2026-11-12T10:00:20Z", "by": { "actor": "customer", "kind": "api_key", "id": "a3d9e1f4-6b2c-4e8a-9f17-2c5b8d1e4a60" } },
{ "state": "funded", "at": "2026-11-12T10:00:20Z", "by": { "actor": "customer", "kind": "api_key", "id": "a3d9e1f4-6b2c-4e8a-9f17-2c5b8d1e4a60" } },
{ "state": "processing", "at": "2026-11-12T10:00:20Z", "by": { "actor": "customer", "kind": "api_key", "id": "a3d9e1f4-6b2c-4e8a-9f17-2c5b8d1e4a60" } },
{ "state": "completed", "at": "2026-11-12T10:02:11Z", "by": { "actor": "system" } }
]
}completed, refunded and cancelled are final. failed is not: our operations team either retries the failed Leg, which takes the Payout back to processing, or refunds it to your balance (refunded). A failed Payout carries failure, which names the Leg that failed and a code.