API Reference
Create Swap [POST]

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

ParameterTypeRequiredDescription
quoteIdstring✅ (without pair)UUID of a swap quote from Quote. Locks the rate.
sourceCurrencystring✅ (without quoteId)Wallet to sell from, e.g. USD. With a quoteId it must match the quote if given.
targetCurrencystring✅ (without quoteId)Wallet to buy into, e.g. NGN. With a quoteId it must match the quote if given.
amountnumber✅ (without quoteId)Amount to sell in minor units of sourceCurrency. With a quoteId it must match the quote.
referencestringYour 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

Wallets/Create Swap [POST]
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:

Wallets/Create Swap at live rate [POST]
{
  "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.

FieldTypeDescription
idstringSwap transaction ID, the same as debitTransactionId
referencestringYour reference, or a generated one
statusstringsuccess, or processing while awaiting approval
sourceCurrencystringWallet debited
targetCurrencystringWallet credited
sourceAmountnumberAmount sold, in minor units
targetAmountnumberAmount bought, in minor units
ratenumberExchange rate applied
debitTransactionIdstringTransaction on the source wallet
creditTransactionIdstringTransaction on the target wallet. Absent while processing
createdAtstringISO 8601 timestamp
🟢 201 - Result example
{
"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

HTTPCodeMeaning
400VALIDATIONMissing pair or amount without a quoteId, or the request disagrees with the quote
400INSUFFICIENT_FUNDSThe source wallet cannot cover the amount
400WALLET_NOT_FOUNDYou have no wallet in the source currency
400RATE_NOT_CONFIGUREDNo rate is configured for the currency pair
400QUOTE_INVALIDThe quoteId is unknown or was issued for a payout
403ACCESS_DENIEDYour company is not permitted to swap
409REFERENCE_EXISTSThis reference was already used for a swap with a different pair or amount. A retry with identical terms returns the original swap instead.
409QUOTE_CONSUMEDThe quote was already executed
410QUOTE_EXPIREDThe quote expired. Create a new one.