> ## Documentation Index
> Fetch the complete documentation index at: https://docs.houdiniswap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST CEX Exchange

> Initiates an exchange transaction, including sender and receiver information, transaction status, quoted amounts, and token details.

<Danger>
  Deprecation of the REST v1 swap endpoints begins on September 30, 2026. Please migrate to the Partner API v2. Dashboard and authentication endpoints remain on v1 GraphQL and are not affected. [Read the migration guide](https://docs.houdiniswap.com/migration/v1-to-v2)
</Danger>

# POST CEX Exchange

Initiates an exchange transaction, including sender and receiver information, transaction status, quoted amounts, and token details. This information is useful for tracking and managing token exchange.

## Endpoint

```text theme={null}
POST /exchange
```

**Request Body:** A JSON object containing `Exchange` details.

<Warning>
  The `ip`, `userAgent`, and `timezone` fields are mandatory for compliance purposes.
</Warning>

## Request Fields

| Field         | Type    | Required | Description                                                                      |
| ------------- | ------- | -------- | -------------------------------------------------------------------------------- |
| `amount`      | number  | Yes      | Amount to be exchanged (example: `1`)                                            |
| `from`        | string  | Yes      | Symbol of the input token (example: `ETH`)                                       |
| `to`          | string  | Yes      | Symbol of the output token (example: `BNB`)                                      |
| `addressTo`   | string  | Yes      | Destination address                                                              |
| `anonymous`   | boolean | Yes      | Indicates if the transaction is anonymous (example: `false`)                     |
| `ip`          | string  | Yes      | User IP address. Used for fraud prevention only                                  |
| `userAgent`   | string  | Yes      | User userAgent browser string                                                    |
| `timezone`    | string  | Yes      | User browser timezone (example: `UTC`)                                           |
| `receiverTag` | string  | No       | Optional receiver tag (example: `123`)                                           |
| `walletId`    | string  | No       | User's wallet identifier                                                         |
| `useXmr`      | string  | No       | Use XMR if `true`, or use another token for the anonymous transaction if `false` |
| `filters`     | object  | No       | Rotation and provider filtering options. See below                               |

### Filters Object

| Field                 | Type      | Default | Description                                                                                                                                   |
| --------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `rotatePayoutWallets` | boolean   | `false` | Enable payout wallet rotation. Deprioritizes recently-used provider paths                                                                     |
| `deviationThreshold`  | number    | `5`     | Maximum price deviation percentage allowed when rotating                                                                                      |
| `rotationLookback`    | number    | `10`    | Number of recent orders to check for path deduplication                                                                                       |
| `onlySwaps`           | string\[] | all     | Restrict to specific providers (e.g., `["cl", "ss"]`). See [Provider Codes](/developer-hub/core-concepts/payout-wallet-rotation#how-it-works) |

<Note>
  When `rotatePayoutWallets` is enabled, any provided `inQuoteId` and `outQuoteId` are discarded. The system forces a fresh re-quote with rotation applied to ensure the new path is used.
</Note>

## Example Request

```json theme={null}
POST /exchange
Content-Type: application/json

{
  "amount": 1,
  "from": "ETH",
  "to": "BNB",
  "addressTo": "0x000000000000000000000000000000000000dead",
  "anonymous": true,
  "ip": "0.0.0.0",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
  "timezone": "UTC",
  "useXmr": false,
  "filters": {
    "rotatePayoutWallets": true,
    "deviationThreshold": 5,
    "rotationLookback": 10
  }
}
```

## Example Response

```json theme={null}
{
  "houdiniId": "mNev2KrGikabTvge75GMwM",
  "created": "2025-02-21T15:32:53.821Z",
  "senderAddress": "0xabb5ac5c686d1614172ac1292519e78ad6c520f5",
  "receiverAddress": "0x000000000000000000000000000000000000dead",
  "anonymous": false,
  "expires": "2025-02-21T16:02:53.821Z",
  "status": 0,
  "inAmount": 1,
  "inSymbol": "ETH",
  "outAmount": 4.189816,
  "outSymbol": "BNB",
  "senderTag": "",
  "receiverTag": "",
  "notified": false,
  "eta": 5,
  "inAmountUsd": 2802.42,
  "inCreated": "2025-02-21T15:32:53.822Z",
  "quote": {
    "amountIn": 1,
    "amountOut": 4.189816,
    "min": 0.001,
    "max": 17.841,
    "path": "ff"
  },
  "outToken": {
    "id": "USDT",
    "name": "Tether",
    "symbol": "USDT",
    "network": {
      "name": "Ethereum Mainnet",
      "shortName": "ETH",
      "addressValidation": "^(0x)[0-9A-Fa-f]{40}$",
      "memoNeeded": false,
      "explorerUrl": "https://etherscan.io/tx/",
      "addressUrl": "https://etherscan.io/address/",
      "priority": 1,
      "kind": "evm",
      "chainId": 1
    },
    "color": "#26a17b",
    "keyword": "usdt usdterc20 tether usdteth erc-20 erc20 eth",
    "displayName": "USDT (ETHEREUM)",
    "chain": 1,
    "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
    "hasMarkup": true,
    "networkPriority": 2,
    "icon": "https://...",
    "hasFixed": true,
    "hasFixedReverse": true
  },
  "inToken": {
    "id": "BNB",
    "name": "BNB",
    "symbol": "BNB",
    "network": {
      "name": "Binance Smart Chain",
      "shortName": "BSC",
      "addressValidation": "^(0x)[0-9A-Za-z]{40}$",
      "memoNeeded": false,
      "explorerUrl": "https://bscscan.com/tx/",
      "addressUrl": "https://bscscan.com/address/",
      "priority": 6,
      "kind": "evm",
      "chainId": 56,
      "icon": "http://127.0.0.1:3000/assets/networks/BSC.png"
    },
    "color": "#FFFFFF",
    "keyword": "BNB BNB Binance Smart Chain evm BNB BNB bsc Binance Smart Chain",
    "displayName": "BNB (BSC)",
    "chain": 56,
    "networkPriority": 1,
    "icon": "http://127.0.0.1:3000/assets/tokens/BNB-BSC.png",
    "hasFixed": false,
    "hasFixedReverse": false
  }
}
```

## Response Fields

| Field             | Type    | Description                                                                         |
| ----------------- | ------- | ----------------------------------------------------------------------------------- |
| `houdiniId`       | string  | Unique identifier for the exchange transaction                                      |
| `created`         | string  | Timestamp of when the transaction was created                                       |
| `senderAddress`   | string  | **Address to send funds to**                                                        |
| `receiverAddress` | string  | Address of the receiver                                                             |
| `anonymous`       | boolean | Indicates if the transaction is anonymous                                           |
| `expires`         | string  | Expiration timestamp of the transaction                                             |
| `status`          | number  | Status code of the transaction                                                      |
| `inAmount`        | number  | Amount sent in the exchange                                                         |
| `outAmount`       | number  | Amount received in the exchange                                                     |
| `inSymbol`        | string  | Symbol of the input token                                                           |
| `outSymbol`       | string  | Symbol of the output token                                                          |
| `senderTag`       | string  | *(Optional)* Sender tag                                                             |
| `receiverTag`     | string  | *(Optional)* Receiver tag                                                           |
| `notified`        | boolean | Indicates if the user has been notified                                             |
| `eta`             | number  | Estimated time of arrival (in minutes)                                              |
| `inAmountUsd`     | number  | Input amount converted to USD                                                       |
| `inCreated`       | string  | Timestamp when the input was created                                                |
| `quote`           | object  | Details of the exchange quote (amounts, min/max limits, path). See QuoteDTO         |
| `outToken`        | object  | Details of the output token. See [TokenDTO](https://api-partner.houdiniswap.com/#/) |
| `inToken`         | object  | Details of the input token. See [TokenDTO](https://api-partner.houdiniswap.com/#/)  |

<Note>
  After receiving the response, send the exact `inAmount` of the `inSymbol` token to the `senderAddress` to initiate the swap.
</Note>