Swap balance to USD
Convert a local-currency balance into USD. Required before withdrawing if your shop settles in local currency.
/api/v1/me/balance/swapSelect a stage to see what happens.
/me/balance/swap- Authorization
- Bearer ••••••••
- Accept
- application/json
Prepare the request
Use credentials for the selected environment and complete the required parameters.
Illustrative flow · no data is sent
How this endpoint works
Live quote for converting part of your pay-in balance from a local currency into USD. **The money, exactly.** `rate` is the EFFECTIVE rate — our FX margin is already inside it — so `amountUsd = amount × rate`, full stop. There is no fee line to subtract, no second conversion, and the charge that produced this local balance carried no FX margin either: the margin is taken once, here. A quote is indicative. The rate is read again when you execute, so the executed amount can differ slightly.
Request parameters
Expand a field to see its format and requirements.
fromstringRequired
Currency you are converting FROM (must be one you hold — see balances[] in GET /me/balance).
amountnumberRequired
How much of `from` to convert, in major units.
Integration details
Currency, behavior and additional notes for this operation.
/api/v1/me/balance/swapSecret keyExecutes the conversion atomically: the local amount leaves `available` and the USD lands in `available` in the same database transaction — there is no in-between state where the money is in neither. **This is what makes a withdrawal possible** when your shop settles in local currency, because withdrawals are always in USD. Send an `Idempotency-Key` and a retry replays the original swap instead of converting twice. If you ask for more than you hold, you get `balance_insufficient` with `requested`, `available` and `shortfall` in the currency you are converting from.
curl -X POST "https://sandbox.key2pay.ai/api/v1/me/balance/swap" \
-H "Authorization: Bearer <accessToken>" \
-H "Idempotency-Key: swap-2026-09-23-01" \
-H "Content-Type: application/json" \
-d '{"fromCurrency":"MXN","amount":10000}'{
"swap": {
"id": "bsw_9f2c…",
"fromCurrency": "MXN",
"toCurrency": "USD",
"amount": 10000,
"rate": 0.0531495,
"amountUsd": 531.495,
"localAvailableAfter": 24000,
"usdAvailableAfter": 531.495
}
}/api/v1/me/balance/fund-sandboxSecret key**Sandbox only** — credits your pay-in `available` with test money in the currency you ask for, so you can try the whole loop without waiting for a real settlement cycle: read the balance per currency, swap to USD, request a withdrawal. Use it with a local currency to exercise a shop on the `local` balance model, and with USD for the classic one. In production it returns `fund_sandbox_only`.
curl -X POST "https://sandbox.key2pay.ai/api/v1/me/balance/fund-sandbox" \
-H "Authorization: Bearer <accessToken>" \
-H "Content-Type: application/json" \
-d '{"currency":"MXN","amount":50000}'{
"currency": "MXN",
"amount": 50000,
"balances": [
{ "currency": "USD", "available": 0, "pending": 0, "reserved": 0 },
{ "currency": "MXN", "available": 50000, "pending": 0, "reserved": 0 }
]
}