---
title: "Create Swap"
method: POST
path: "/swaps"
tags: ["Swaps"]
---

# Create Swap

`POST /swaps`

Swaps one token for another from the account's wallet, or converts between currencies to pay off a negative balance. Crypto swaps finish in the background — check the swap for its status.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `account_id` string, required — Business or user account ID (biz_* / user_*).
  - `amount` string, nullable — Source token amount. Required for crypto swaps. Optional for fiat pairs: the portion of the negative to_token balance to repay, which must not exceed the debt; omit to repay the full debt.
  - `from_chain` union — Source chain name or chain ID. Defaults to the source token's chain when omitted.
    - string
    - integer
  - `from_token` string, required — Source token contract address or ticker symbol, such as "USDT".
  - `slippage_bps` integer, nullable — Maximum slippage tolerance in basis points.
  - `to_chain` union — Destination chain name or chain ID. Defaults to the destination token's chain when omitted.
    - string
    - integer
  - `to_token` string, required — Destination token contract address or ticker symbol, such as "XAUT".

## Response `201`

swap created

- object
  - `account_id` string, required — Account ID that owns the wallet used for the swap.
  - `amount_in` number, nullable — Fiat pairs only: amount of the funding currency converted. Null while a stablecoin repayment is processing.
  - `amount_out` number, nullable — Fiat pairs only: amount credited in the repaid currency. Null while a stablecoin repayment is processing.
  - `amount_out_expected` string — Expected destination token amount.
  - `amount_out_min` string — Minimum destination amount after slippage.
  - `from_token` object, nullable — Fiat pairs only: the funding currency.
    - `symbol` string
  - `id` string — Swap ID. Poll `GET /swaps/:id` for status.
  - `object` 'swap', required
  - `rate` string — 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_chain` string — Destination chain for the swap.
  - `to_token` object, nullable — Fiat pairs only: the repaid currency.
    - `symbol` string

## Other responses

- `400` — Invalid Parameters
- `403` — Forbidden

## Changes

- **2026-08-04** `ca841fbd6786` — 2 info
  - the security scope `crypto_wallet:swap` was added to the endpoint's security scheme `bearerAuth`
  - the security scope `payout:transfer_funds` was removed from the endpoint's security scheme `bearerAuth`
- **2026-07-31** `099fdc3be422` — 4 warning
  - added the new `complete` enum value to the `status` response property for the response status `201`
  - added the new `failed` enum value to the `status` response property for the response status `201`
  - added the new `queued` enum value to the `status` response property for the response status `201`
  - added the new `working` enum value to the `status` response property for the response status `201`
- **2026-07-26** `60bbb4a6ffbc` — 1 breaking, 7 info
  - the response property `id` became optional for the status `201`
  - added the new optional `header` request parameter `Idempotency-Key`
  - the request property `amount` became nullable
  - the request property `amount` became optional
  - …4 more

[Change history](https://skmtc.dev/whop/apis/whop-api/changes/swaps/post.md)

---

[API](https://skmtc.dev/whop/apis/whop-api.md) · [All operations](https://skmtc.dev/whop/apis/whop-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/whop/whop-api/revisions/ca841fbd6786/schema)