Skip to main content
POST
TypeScript

Authorizations

Authorization
string
header
required

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

Idempotency-Key
string

A unique key that makes this request safe to retry. See Idempotent requests.

Maximum string length: 255
Example:

"d9105228-4a08-46b1-8b91-42fed586d383"

Api-Version-Date
string

Pins the request to a dated API version.

Example:

"2026-10-29-8"

Body

application/json
from_token
string
required

Source token contract address or ticker symbol, such as "USDT".

Example:

"usd"

to_token
string
required

Destination token contract address or ticker symbol, such as "XAUT".

Example:

"cad"

account_id
string

Business account that makes the swap, prefixed biz_. Provide this or user_id.

Example:

"biz_xxxxxxxxxxxxxx"

amount
string | null

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.

Example:

"100"

from_chain

Source chain name or chain ID. Defaults to the source token's chain when omitted.

Example:

"plasma"

slippage_bps
integer | null

Maximum slippage tolerance in basis points.

Example:

50

to_amount
string | null

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.

Example:

"180.00"

to_chain

Destination chain name or chain ID. Defaults to the destination token's chain when omitted.

Example:

"plasma"

user_id
string

The caller's own user ID, prefixed user_, to swap in their personal account. Provide this or account_id.

Response

swap created

account_id
string
required

Account that owns the swap: a business ID prefixed biz_, or the user ID for a personal account.

Example:

"biz_xxxxxxxxxxxxxx"

object
enum<string>
required
Available options:
swap
Example:

"swap"

status
enum<string>
required

Swap status. Crypto swaps start queued; fiat conversions return complete, or working while a stablecoin repayment settles.

Available options:
queued,
working,
complete,
failed
Example:

"queued"

user_id
string | null
required

User whose personal account owns the swap, prefixed user_. Null for a business account.

Example:

null

amount
string | 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.

Example:

"100.0"

amount_in
number | null

Fiat pairs only: amount of the source currency converted. Null while a stablecoin repayment is processing.

Example:

131.4

amount_out
number | null

Fiat pairs only: amount credited in the destination currency. Null while a stablecoin repayment is processing.

Example:

180

amount_out_expected
string

Expected destination token amount.

Example:

"98.9"

amount_out_min
string

Minimum destination amount after slippage.

Example:

"98.4"

from_token
object | null

Fiat pairs only: the source currency.

id
string

Swap ID. Poll GET /swaps/:id for status.

Example:

"vault-swap-cwal_xxxxxxxxxxxxxx"

rate
string

Quoted exchange rate used to create the swap.

Example:

"0.989"

to_chain
string

Destination chain for the swap.

Example:

"ethereum"

to_token
object | null

Fiat pairs only: the destination currency.