Create Swap
Swaps one token for another in an account or user’s wallet, or converts between their fiat balances at the mid-market rate. Crypto swaps finish in the background — retrieve the swap to follow its status.
Authorizations
An Account API key, an App API key, an account access token, an account-scoped user token, or a user OAuth token. Prepend the key or token with Bearer, for example Bearer ***************************. See Auth & API keys for how to get each one.
Headers
A unique key that makes this request safe to retry. See Idempotent requests.
255"d9105228-4a08-46b1-8b91-42fed586d383"
Pins the request to a dated API version.
"2026-10-29-8"
Body
Source token contract address or ticker symbol, such as "USDT".
"usd"
Destination token contract address or ticker symbol, such as "XAUT".
"cad"
Business account that makes the swap, prefixed biz_. Provide this or user_id.
"biz_xxxxxxxxxxxxxx"
Source token amount. Required for a crypto pair: a decimal amount, or all to swap the whole from_token balance in the account's wallet, read from the chain when the swap is created (any token but USDT). An amount above that balance is rejected when the balance can be read. For fiat pairs: the amount of from_token to convert at the mid-market rate; omit (along with to_amount) to repay the full negative to_token balance instead.
"100"
Source chain name or chain ID. Defaults to the source token's chain when omitted.
"plasma"
Maximum slippage tolerance in basis points.
50
Fiat pairs only: sizes a partial repayment of the negative to_token balance, denominated in to_token. Must not exceed the debt. Mutually exclusive with amount.
"180.00"
Destination chain name or chain ID. Defaults to the destination token's chain when omitted.
"plasma"
The caller's own user ID, prefixed user_, to swap in their personal account. Provide this or account_id.
Response
swap created
Account that owns the swap: a business ID prefixed biz_, or the user ID for a personal account.
"biz_xxxxxxxxxxxxxx"
swap "swap"
Swap status. Crypto swaps start queued; fiat conversions return complete, or working while a stablecoin repayment settles.
queued, working, complete, failed "queued"
User whose personal account owns the swap, prefixed user_. Null for a business account.
null
Crypto pairs only: the from_token amount the swap spends, as a decimal string. A request for all returns the wallet balance it read.
"100.0"
Fiat pairs only: amount of the source currency converted. Null while a stablecoin repayment is processing.
131.4
Fiat pairs only: amount credited in the destination currency. Null while a stablecoin repayment is processing.
180
Expected destination token amount.
"98.9"
Minimum destination amount after slippage.
"98.4"
Fiat pairs only: the source currency.
Swap ID. Poll GET /swaps/:id for status.
"vault-swap-cwal_xxxxxxxxxxxxxx"
Quoted exchange rate used to create the swap.
"0.989"
Destination chain for the swap.
"ethereum"
Fiat pairs only: the destination currency.

