Sign in
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

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

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".

user_idstring

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

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 that owns the swap: a business ID prefixed biz_, or the user ID for a personal account.

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.

user_idstring nullable required

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

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"
  }
}

Changes

Changed in 65 of the 74 revisions of this API.14141

  • 78e1ed7366cd2See the full diff
    • ○

      the security scope crypto_wallet:swap was added to the endpoint's security scheme bearerAuth

      api-security-scope-added

    • ○

      the security scope payout:transfer_funds was removed from the endpoint's security scheme bearerAuth

      api-security-scope-removed

  • 73dd0533cd812See the full diff
    • ○

      the security scope crypto_wallet:swap was added to the endpoint's security scheme bearerAuth

      api-security-scope-added

    • ○

      the security scope payout:transfer_funds was removed from the endpoint's security scheme bearerAuth

      api-security-scope-removed

  • 86b97292852d2See the full diff
    • ○

      the security scope crypto_wallet:swap was added to the endpoint's security scheme bearerAuth

      api-security-scope-added

    • ○

      the security scope payout:transfer_funds was removed from the endpoint's security scheme bearerAuth

      api-security-scope-removed

  • c1dceb26e5056See the full diff
    • ○

      the security scope crypto_wallet:swap was added to the endpoint's security scheme bearerAuth

      api-security-scope-added

    • ○

      the security scope payout:transfer_funds was removed from the endpoint's security scheme bearerAuth

      api-security-scope-removed

    • ○

      added the new optional header request parameter Api-Version-Date to all path's operations

      new-optional-request-default-parameter-to-existing-path

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      the request property became optional

      request-property-became-optional

    • ○

      added the required property to the response with the status

      response-required-property-added

  • 7fcefabddb0a2See the full diff
    • ○

      the security scope crypto_wallet:swap was added to the endpoint's security scheme bearerAuth

      api-security-scope-added

    • ○

      the security scope payout:transfer_funds was removed from the endpoint's security scheme bearerAuth

      api-security-scope-removed

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 140d015b99662See the full diff
    • ○

      the security scope crypto_wallet:swap was added to the endpoint's security scheme bearerAuth

      api-security-scope-added

    • ○

      the security scope payout:transfer_funds was removed from the endpoint's security scheme bearerAuth

      api-security-scope-removed

  • 35edb053220a2See the full diff
    • ○

      the security scope crypto_wallet:swap was added to the endpoint's security scheme bearerAuth

      api-security-scope-added

    • ○

      the security scope payout:transfer_funds was removed from the endpoint's security scheme bearerAuth

      api-security-scope-removed

    This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • ac2b9b1c6a002See the full diff
    • ○

      the security scope crypto_wallet:swap was added to the endpoint's security scheme bearerAuth

      api-security-scope-added

    • ○

      the security scope payout:transfer_funds was removed from the endpoint's security scheme bearerAuth

      api-security-scope-removed

  • a88353507eac2See the full diff
    • ○

      the security scope crypto_wallet:swap was added to the endpoint's security scheme bearerAuth

      api-security-scope-added

    • ○

      the security scope payout:transfer_funds was removed from the endpoint's security scheme bearerAuth

      api-security-scope-removed

  • 51933d70d7f52See the full diff
    • ○

      the security scope crypto_wallet:swap was added to the endpoint's security scheme bearerAuth

      api-security-scope-added

    • ○

      the security scope payout:transfer_funds was removed from the endpoint's security scheme bearerAuth

      api-security-scope-removed

Of the 74 revisions, 1 has no diff computed.