An FX quote is a price, and an exchange is the act of taking it. Together they turn money in one balance into money in another, at a rate you can hold. A payout across currencies doesn't use them: it is priced with a pricing quote, and an fxq_ ID is never valid there.
Name the pair and fix one side
source_currency is the currency you give up and destination_currency the one you receive. Fix exactly one side with source_amount or destination_amount, and Anton computes the other. Sending both is a validation error.
Amounts are decimal strings at the currency's precision: two places for USD, none for JPY, six for USDC. More places is 422 amount_precision_invalid.
You need an account in the destination currency. Without one, an exchange fails with 422 no_buy_account. Fund your balance covers getting one; in the sandbox a deposit creates it.
Lock the price or only look at it
For a price with no write at all, GET /v1/fx/rates takes the same fields as query parameters and returns an indicative quote with locked: false. Fix at most one side; with none, you get the price of one unit of the destination currency. Today the list holds the one quote for your pair.
Request a quote
The quote carries both amounts, the customer_rate you get, the mid_market_rate it was built from, a fee and an expires_at. A retry with the same Idempotency-Key and body returns the original quote.
curl -X POST \ https://api.antonpayments.dev/v1/fx/quotes \ -H "Authorization: DPoP $ANTON_ACCESS_TOKEN" \ -H "DPoP: $DPOP_PROOF" \ -H "Idempotency-Key: fxq-A-1042" \ -H "Content-Type: application/json" \ -d '{ "source_currency": "USD", "destination_currency": "EUR", "destination_amount": "500.00", "locked": true, "metadata": { "order_ref": "A-1042" } }'
markup_basis_points is the markup on the mid-market rate. A locked quote is active until it is used, expired or cancelled. An indicative quote is always active.
Execute the exchange
Send the quote's id as quote_id. A quote executes once, and only before its expires_at.
{
"quote_id": "fxq_dbvm07aukoh6sl1ll14g",
"metadata": { "order_ref": "A-1042" }
}To skip the quote, send source_currency, destination_currency and destination_amount instead, and Anton quotes and executes in one step. quote_id can't be combined with those fields. The one-step form gives you no look at the rate first, so use it when you don't need one.
The exchange has its own ID, starting fxx_, and a status of completed, pending or failed. It carries the quote_id, both amounts and the rate you got. Fetch it with GET /v1/fx/exchanges/{id}, or list your exchanges with GET /v1/fx/exchanges, filtered by status or by a currency on either side.
Wait for the event
The outcome reaches you as an event, so you needn't poll. fx.exchange.created, fx.exchange.completed and fx.exchange.failed carry the exchange object, and fx.quote.created carries the quote. Track payouts with webhooks covers subscribing and verifying them.
When it goes wrong
quote_id names no quote of yours.expires_at. Request a new one and execute it straight away.locked: true, the default.Idempotency-Key.Retry-After, then retry.Idempotency
Quotes and exchanges both require an Idempotency-Key. Build it from your own record so a retry after a timeout returns what you already made instead of converting twice. Idempotency has the rest.