Sign in
latestOpenAPI 3.1.02026-08-153864115.7 MB

c301132dbfd7

Swaps

Create Swap

Swaps one token for another from the account's wallet, or converts between fiat currencies in the account's ledger at the mid-market rate. Crypto swaps finish in the background — check the swap for its status.

post/swaps

Headers

Idempotency-Keystring
Example:d9105228-4a08-46b1-8b91-42fed586d383

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

Request body

account_idstring required

Business or user account ID (biz_* / user_*).

amountstring nullable

Source token amount. Required for crypto swaps. 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.

from_tokenstring required

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

slippage_bpsinteger nullable

Maximum slippage tolerance in basis points.

to_amountstring nullable

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.

to_tokenstring required

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

Example request

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "amount": "100",
  "from_chain": "plasma",
  "from_token": "usd",
  "slippage_bps": 50,
  "to_amount": "180.00",
  "to_chain": "plasma",
  "to_token": "cad"
}

Response

swap created

account_idstring required

Account ID that owns the wallet used for the swap.

amount_innumber nullable

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

amount_outnumber nullable

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

amount_out_expectedstring

Expected destination token amount.

amount_out_minstring

Minimum destination amount after slippage.

idstring

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

object'swap' required
ratestring

Quoted exchange rate used to create the swap.

status'queued' | 'working' | 'complete' | 'failed' required

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

to_chainstring

Destination chain for the swap.

Example response

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "amount_in": 131.4,
  "amount_out": 180,
  "amount_out_expected": "98.9",
  "amount_out_min": "98.4",
  "from_token": {
    "symbol": "usd"
  },
  "id": "vault-swap-cwal_xxxxxxxxxxxxxx",
  "object": "swap",
  "rate": "0.989",
  "status": "queued",
  "to_chain": "ethereum",
  "to_token": {
    "symbol": "cad"
  }
}