Create Swap
https://sandboxapi.onbrails.com/api/v2/wallets/swaps (opens in a new tab)
Convert between two of your wallets in one call. Most swaps settle before the response returns, with status: "success" and both the debit and credit transactions. Large swaps are held for operations review and return status: "processing" with no creditTransactionId yet, so always check data.status before treating the conversion as complete.
This is the recommended flow for new integrations. Lock a
Quote with purpose: "swap", then pass its
quoteId here. Without a quoteId the swap is priced and executed at the
live rate, and sourceCurrency, targetCurrency and amount become
required.
Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| quoteId | string | ✅ (without pair) | UUID of a swap quote from Quote. Locks the rate. |
| sourceCurrency | string | ✅ (without quoteId) | Wallet to sell from, e.g. USD. With a quoteId it must match the quote if given. |
| targetCurrency | string | ✅ (without quoteId) | Wallet to buy into, e.g. NGN. With a quoteId it must match the quote if given. |
| amount | number | ✅ (without quoteId) | Amount to sell in minor units of sourceCurrency. With a quoteId it must match the quote. |
| reference | string | Your unique reference, used as an idempotency key. Retrying with the same reference and the same pair and amount returns the original swap, so a timed-out request is safe to repeat. The same reference with different terms is rejected with 409 REFERENCE_EXISTS. |
Amounts are in minor units. 100 USD is sent as 10000. This differs from
the two-step Initialize Swap endpoint,
which reports its amounts in major units.
Request
curl --request POST \
--url https://sandboxapi.onbrails.com/api/v2/wallets/swaps \
--header 'Authorization: Bearer YOUR_SECRET_KEY' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"quoteId": "7a9e1c3d-5b2f-4e8a-9c1d-2f3e4a5b6c7d",
"reference": "SWAP-2026-0001"
}
'Alternatively, swap at the live rate without a quote:
{
"sourceCurrency": "USD",
"targetCurrency": "NGN",
"amount": 10000,
"reference": "SWAP-2026-0002"
}Responses
A successful request returns 201 Created. All amounts in the response are in minor units. Swaps above the operations review threshold return status: "processing" with no creditTransactionId until they are approved.
| Field | Type | Description |
|---|---|---|
| id | string | Swap transaction ID, the same as debitTransactionId |
| reference | string | Your reference, or a generated one |
| status | string | success, or processing while awaiting approval |
| sourceCurrency | string | Wallet debited |
| targetCurrency | string | Wallet credited |
| sourceAmount | number | Amount sold, in minor units |
| targetAmount | number | Amount bought, in minor units |
| rate | number | Exchange rate applied |
| debitTransactionId | string | Transaction on the source wallet |
| creditTransactionId | string | Transaction on the target wallet. Absent while processing |
| createdAt | string | ISO 8601 timestamp |
{
"status": true,
"message": "swap executed",
"data": {
"id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
"reference": "SWAP-2026-0001",
"status": "success",
"sourceCurrency": "usd",
"targetCurrency": "ngn",
"sourceAmount": 10000,
"targetAmount": 15000000,
"rate": 1500,
"debitTransactionId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
"creditTransactionId": "c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f",
"createdAt": "2026-11-13T10:32:15.000Z"
}
}Error codes
| HTTP | Code | Meaning |
|---|---|---|
| 400 | VALIDATION | Missing pair or amount without a quoteId, or the request disagrees with the quote |
| 400 | INSUFFICIENT_FUNDS | The source wallet cannot cover the amount |
| 400 | WALLET_NOT_FOUND | You have no wallet in the source currency |
| 400 | RATE_NOT_CONFIGURED | No rate is configured for the currency pair |
| 400 | QUOTE_INVALID | The quoteId is unknown or was issued for a payout |
| 403 | ACCESS_DENIED | Your company is not permitted to swap |
| 409 | REFERENCE_EXISTS | This reference was already used for a swap with a different pair or amount. A retry with identical terms returns the original swap instead. |
| 409 | QUOTE_CONSUMED | The quote was already executed |
| 410 | QUOTE_EXPIRED | The quote expired. Create a new one. |