Swaps

Create Swap

Changed on

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.

post/swaps

Request

  • Base URL: https://api.whop.com/api/v1
  • URL: https://api.whop.com/api/v1/swaps
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer
    • HTTP bearer

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

  • 507636677fe9Revision changes
    • info

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

    • info

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

  • c3b5561c6176Revision changes
    • info

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

    • info

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