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

# Create Swap

> Convert between stablecoins or transfer across chains.

## Create Swap

Convert between stablecoins and transfer across blockchain networks — also known as on-chain FX. This endpoint handles direct stablecoin-to-stablecoin conversion without fiat intermediaries.

### Endpoint

```
POST /v1/onchain-fx
```

### Request Headers

| Header            | Required | Description                              |
| ----------------- | -------- | ---------------------------------------- |
| `X-API-Key`       | Yes      | Your API key                             |
| `Content-Type`    | Yes      | `application/json`                       |
| `Idempotency-Key` | No       | Unique identifier for idempotent retries |

### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.thiqwave.com/v1/onchain-fx \
    -H "X-API-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: unique_request_id" \
    -d '{
      "quote_id": "quote_3333333333",
      "source_currency": "USDT",
      "source_network": "ethereum",
      "source_address": "0x123456789abcdef123456789abcdef1234567890",
      "destination_currency": "USDC",
      "destination_network": "polygon",
      "destination_address": "0xabcdef123456789abcdef123456789abcdef1234",
      "amount": "1000.00"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.thiqwave.com/v1/onchain-fx', {
    method: 'POST',
    headers: {
      'X-API-Key': 'your_api_key',
      'Content-Type': 'application/json',
      'Idempotency-Key': 'unique_request_id',
    },
    body: JSON.stringify({
      quote_id: 'quote_3333333333',
      source_currency: 'USDT',
      source_network: 'ethereum',
      source_address: '0x123456789abcdef123456789abcdef1234567890',
      destination_currency: 'USDC',
      destination_network: 'polygon',
      destination_address: '0xabcdef123456789abcdef123456789abcdef1234',
      amount: '1000.00',
    }),
  });

  const fx = await response.json();
  console.log(fx);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.thiqwave.com/v1/onchain-fx',
      headers={
          'X-API-Key': 'your_api_key',
          'Idempotency-Key': 'unique_request_id',
      },
      json={
          'quote_id': 'quote_3333333333',
          'source_currency': 'USDT',
          'source_network': 'ethereum',
          'source_address': '0x123456789abcdef123456789abcdef1234567890',
          'destination_currency': 'USDC',
          'destination_network': 'polygon',
          'destination_address': '0xabcdef123456789abcdef123456789abcdef1234',
          'amount': '1000.00',
      }
  )

  fx = response.json()
  print(fx)
  ```
</CodeGroup>

### Request Body

| Field                  | Type   | Required | Description                                                                                                                                |
| ---------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `quote_id`             | string | Yes      | Quote ID from a prior quote request. Locks in conversion rates.                                                                            |
| `source_currency`      | string | Yes      | Stablecoin: USDT or USDC.                                                                                                                  |
| `source_network`       | string | Yes      | Source blockchain network: `ethereum`, `avalanche`, `arbitrum`, `base`, `polygon`, `tron`, `stellar`, `solana`, `xrpl`, `algorand`, `sui`. |
| `source_address`       | string | Yes      | Wallet address to debit stablecoins from.                                                                                                  |
| `destination_currency` | string | Yes      | Stablecoin: USDT or USDC.                                                                                                                  |
| `destination_network`  | string | Yes      | Destination blockchain network.                                                                                                            |
| `destination_address`  | string | Yes      | Wallet address to deliver stablecoins to.                                                                                                  |
| `amount`               | string | Yes      | Amount in human-readable format (e.g., `"1000.00"`).                                                                                       |

### Response

```json theme={null}
{
  "fx_id": "fx_1234567890",
  "quote_id": "quote_3333333333",
  "status": "pending",
  "source_currency": "USDT",
  "source_network": "ethereum",
  "source_address": "0x123456789abcdef123456789abcdef1234567890",
  "source_amount": "1000.00",
  "destination_currency": "USDC",
  "destination_network": "polygon",
  "destination_address": "0xabcdef123456789abcdef123456789abcdef1234",
  "destination_amount": "999.50",
  "exchange_rate": "0.9995",
  "fees": {
    "platform_fee": "0.50",
    "network_fee": "0.00"
  },
  "created_at": "2026-04-09T14:30:00Z",
  "completed_at": null
}
```

### Response Fields

| Field                  | Type           | Description                                                     |
| ---------------------- | -------------- | --------------------------------------------------------------- |
| `fx_id`                | string         | Unique on-chain FX transaction identifier.                      |
| `quote_id`             | string         | Associated quote ID.                                            |
| `status`               | string         | Current status: `pending`, `processing`, `completed`, `failed`. |
| `source_currency`      | string         | Source stablecoin.                                              |
| `source_network`       | string         | Source blockchain network.                                      |
| `source_address`       | string         | Source wallet address.                                          |
| `source_amount`        | string         | Amount in source currency (human-readable).                     |
| `destination_currency` | string         | Destination stablecoin.                                         |
| `destination_network`  | string         | Destination blockchain network.                                 |
| `destination_address`  | string         | Destination wallet address.                                     |
| `destination_amount`   | string         | Amount in destination currency (human-readable).                |
| `exchange_rate`        | string         | Conversion rate (destination per source).                       |
| `fees`                 | object         | Platform and network fees breakdown.                            |
| `created_at`           | string         | ISO 8601 timestamp of creation.                                 |
| `completed_at`         | string \| null | ISO 8601 timestamp of completion.                               |

## On-chain FX States

| Status       | Description                                         |
| ------------ | --------------------------------------------------- |
| `pending`    | FX transaction initiated.                           |
| `processing` | Conversion and transfer in progress.                |
| `completed`  | Stablecoins converted and delivered to destination. |
| `failed`     | FX transaction failed. Check details for reason.    |

## Notes

* Ensure the quote is not expired before creating an FX transaction.
* Source and destination addresses must be valid wallet addresses on their respective blockchains.
* Network fees vary by source and destination blockchain.
* Monitor FX status via the [Get On-chain FX](/api/onchain-fx/get) endpoint or webhooks.