> ## 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 Transfer

> Move value between any combination of fiat and stablecoin endpoints.

## Create Transfer

The Transfers API is the primary way to move value through Thiqwave. Specify a source and a destination — Thiqwave handles the conversion, routing, and settlement automatically.

A transfer can move value between any combination of fiat and stablecoin:

| Source               | Destination          | What happens                            |
| -------------------- | -------------------- | --------------------------------------- |
| Fiat (bank deposit)  | Stablecoin (wallet)  | On-ramp                                 |
| Stablecoin (wallet)  | Fiat (bank account)  | Off-ramp                                |
| Stablecoin (chain A) | Stablecoin (chain B) | Cross-chain bridge                      |
| Stablecoin (token A) | Stablecoin (token B) | Swap                                    |
| Fiat (bank deposit)  | Fiat (bank account)  | Stablecoin-settled cross-border payment |

### Endpoint

```
POST /v1/transfers
```

### Request Headers

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

### Request Body

| Field         | Type   | Required | Description                                                                                        |
| ------------- | ------ | -------- | -------------------------------------------------------------------------------------------------- |
| `quote_id`    | string | Yes      | Quote ID from a prior `/v1/quotes` request. Locks in rates and fees.                               |
| `source`      | object | Yes      | Where value comes from. See Source Object below.                                                   |
| `destination` | object | Yes      | Where value goes. See Destination Object below.                                                    |
| `amount`      | string | Yes      | Amount to transfer. Always a string — e.g., `"1000.00"` for 1000 USDC or `"1000.00"` for 1000 AED. |
| `metadata`    | object | No       | Key-value pairs for your reference.                                                                |

### Source Object

| Field          | Type   | Required    | Description                                                                     |
| -------------- | ------ | ----------- | ------------------------------------------------------------------------------- |
| `currency`     | string | Yes         | Currency code: `AED`, `USD`, `EUR`, `GBP`, `USDT`, or `USDC`.                   |
| `network`      | string | Conditional | Required when currency is a stablecoin. Blockchain network identifier.          |
| `address`      | string | Conditional | Required when currency is a stablecoin. Wallet address to debit from.           |
| `payment_rail` | string | Conditional | Required when currency is fiat. Payment method: `"bank_transfer"`, `"instant"`. |

### Destination Object

| Field            | Type   | Required    | Description                                                            |
| ---------------- | ------ | ----------- | ---------------------------------------------------------------------- |
| `currency`       | string | Yes         | Currency code: `AED`, `USD`, `EUR`, `GBP`, `USDT`, or `USDC`.          |
| `network`        | string | Conditional | Required when currency is a stablecoin. Blockchain network identifier. |
| `address`        | string | Conditional | Required when currency is a stablecoin. Wallet address to credit.      |
| `account_holder` | string | Conditional | Required when currency is fiat. Recipient name.                        |
| `account_number` | string | Conditional | Required when currency is fiat. Bank account number.                   |
| `bank_code`      | string | Conditional | Required when currency is fiat. SWIFT/BIC or local bank code.          |
| `country`        | string | Conditional | Required when currency is fiat. ISO 3166-1 alpha-2 country code.       |

### Examples

#### On-ramp: AED to USDC on Sui

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.thiqwave.com/v1/transfers \
    -H "X-API-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: txn_001" \
    -d '{
      "quote_id": "quote_abc123",
      "source": {
        "currency": "AED",
        "payment_rail": "bank_transfer"
      },
      "destination": {
        "currency": "USDC",
        "network": "sui",
        "address": "0x8a4c5b9e1f3d7a2c6e0b4f8d9a1c3e5f7b2d4a6c8e0f1a3b5d7e9c2a4b6d8f"
      },
      "amount": "1000.00"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.thiqwave.com/v1/transfers', {
    method: 'POST',
    headers: {
      'X-API-Key': 'your_api_key',
      'Content-Type': 'application/json',
      'Idempotency-Key': 'txn_001',
    },
    body: JSON.stringify({
      quote_id: 'quote_abc123',
      source: {
        currency: 'AED',
        payment_rail: 'bank_transfer',
      },
      destination: {
        currency: 'USDC',
        network: 'sui',
        address: '0x8a4c5b9e1f3d7a2c6e0b4f8d9a1c3e5f7b2d4a6c8e0f1a3b5d7e9c2a4b6d8f',
      },
      amount: '1000.00',
    }),
  });

  const transfer = await response.json();
  ```

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

  response = requests.post(
      'https://api.thiqwave.com/v1/transfers',
      headers={
          'X-API-Key': 'your_api_key',
          'Content-Type': 'application/json',
          'Idempotency-Key': 'txn_001',
      },
      json={
          'quote_id': 'quote_abc123',
          'source': {
              'currency': 'AED',
              'payment_rail': 'bank_transfer',
          },
          'destination': {
              'currency': 'USDC',
              'network': 'sui',
              'address': '0x8a4c5b9e1f3d7a2c6e0b4f8d9a1c3e5f7b2d4a6c8e0f1a3b5d7e9c2a4b6d8f',
          },
          'amount': '1000.00',
      },
  )

  transfer = response.json()
  ```
</CodeGroup>

#### Off-ramp: USDT on Ethereum to GBP

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.thiqwave.com/v1/transfers \
    -H "X-API-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: txn_002" \
    -d '{
      "quote_id": "quote_def456",
      "source": {
        "currency": "USDT",
        "network": "ethereum",
        "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
      },
      "destination": {
        "currency": "GBP",
        "account_holder": "Acme Ltd",
        "account_number": "12345678",
        "bank_code": "401276",
        "country": "GB"
      },
      "amount": "500.00"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.thiqwave.com/v1/transfers', {
    method: 'POST',
    headers: {
      'X-API-Key': 'your_api_key',
      'Content-Type': 'application/json',
      'Idempotency-Key': 'txn_002',
    },
    body: JSON.stringify({
      quote_id: 'quote_def456',
      source: {
        currency: 'USDT',
        network: 'ethereum',
        address: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
      },
      destination: {
        currency: 'GBP',
        account_holder: 'Acme Ltd',
        account_number: '12345678',
        bank_code: '401276',
        country: 'GB',
      },
      amount: '500.00',
    }),
  });

  const transfer = await response.json();
  ```

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

  response = requests.post(
      'https://api.thiqwave.com/v1/transfers',
      headers={
          'X-API-Key': 'your_api_key',
          'Content-Type': 'application/json',
          'Idempotency-Key': 'txn_002',
      },
      json={
          'quote_id': 'quote_def456',
          'source': {
              'currency': 'USDT',
              'network': 'ethereum',
              'address': '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
          },
          'destination': {
              'currency': 'GBP',
              'account_holder': 'Acme Ltd',
              'account_number': '12345678',
              'bank_code': '401276',
              'country': 'GB',
          },
          'amount': '500.00',
      },
  )

  transfer = response.json()
  ```
</CodeGroup>

#### Cross-chain bridge: USDC on Solana to USDC on Ethereum

```bash theme={null}
curl -X POST https://api.thiqwave.com/v1/transfers \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: txn_003" \
  -d '{
    "quote_id": "quote_ghi789",
    "source": {
      "currency": "USDC",
      "network": "solana",
      "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
    },
    "destination": {
      "currency": "USDC",
      "network": "ethereum",
      "address": "0x742d35Cc6634C0532925a3b844Bc123e5fA42f9c"
    },
    "amount": "1000.00"
  }'
```

#### Swap: USDT on Ethereum to USDC on Sui

```bash theme={null}
curl -X POST https://api.thiqwave.com/v1/transfers \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: txn_004" \
  -d '{
    "quote_id": "quote_jkl012",
    "source": {
      "currency": "USDT",
      "network": "ethereum",
      "address": "0x123456789abcdef123456789abcdef1234567890"
    },
    "destination": {
      "currency": "USDC",
      "network": "sui",
      "address": "0x8a4c5b9e1f3d7a2c6e0b4f8d9a1c3e5f7b2d4a6c8e0f1a3b5d7e9c2a4b6d8f"
    },
    "amount": "1000.00"
  }'
```

#### Fiat-to-fiat (stablecoin sandwich): AED to EUR

```bash theme={null}
curl -X POST https://api.thiqwave.com/v1/transfers \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: txn_005" \
  -d '{
    "quote_id": "quote_mno345",
    "source": {
      "currency": "AED",
      "payment_rail": "bank_transfer"
    },
    "destination": {
      "currency": "EUR",
      "account_holder": "Schmidt GmbH",
      "account_number": "DE89370400440532013000",
      "bank_code": "COBADEFFXXX",
      "country": "DE"
    },
    "amount": "5000.00"
  }'
```

### Response

```json theme={null}
{
  "id": "txn_01HZ5NM2XDQE8F1G7HKRWS4JV",
  "quote_id": "quote_abc123",
  "status": "pending",
  "source": {
    "currency": "AED",
    "payment_rail": "bank_transfer",
    "amount": "1000.00"
  },
  "destination": {
    "currency": "USDC",
    "network": "sui",
    "address": "0x8a4c5b9e1f3d7a2c6e0b4f8d9a1c3e5f7b2d4a6c8e0f1a3b5d7e9c2a4b6d8f",
    "amount": "271.50"
  },
  "fees": {
    "platform_fee": "2.50",
    "network_fee": "0.10"
  },
  "exchange_rate": "0.2715",
  "payment_instructions": {
    "beneficiary_name": "Thiqwave Limited",
    "beneficiary_account": "1234567890",
    "bank_code": "ABUAAE3D",
    "reference": "txn_01HZ5NM2XDQE8F1G7HKRWS4JV",
    "country": "AE"
  },
  "metadata": {},
  "created_at": "2026-04-13T10:30:00Z",
  "completed_at": null
}
```

<Note>
  `payment_instructions` is only present when the source is fiat and requires a bank deposit. Use these details to complete the transfer.
</Note>

### Response Fields

| Field                  | Type           | Description                                     |
| ---------------------- | -------------- | ----------------------------------------------- |
| `id`                   | string         | Unique transfer identifier.                     |
| `quote_id`             | string         | Associated quote.                               |
| `status`               | string         | Current status (see Transfer States below).     |
| `source`               | object         | Source details including resolved amounts.      |
| `destination`          | object         | Destination details including resolved amounts. |
| `fees`                 | object         | Fee breakdown.                                  |
| `exchange_rate`        | string         | Applied conversion rate.                        |
| `payment_instructions` | object or null | Bank deposit instructions (fiat source only).   |
| `metadata`             | object         | Your metadata.                                  |
| `created_at`           | string         | ISO 8601 creation timestamp.                    |
| `completed_at`         | string or null | ISO 8601 completion timestamp.                  |

### Transfer States

| Status             | Description                                                         |
| ------------------ | ------------------------------------------------------------------- |
| `pending`          | Transfer created, awaiting processing or deposit.                   |
| `awaiting_deposit` | Fiat source: waiting for bank deposit (use `payment_instructions`). |
| `processing`       | Funds received, conversion and routing in progress.                 |
| `settling`         | On-chain settlement or fiat delivery in progress.                   |
| `completed`        | Transfer complete — funds delivered to destination.                 |
| `failed`           | Transfer failed. Details available via webhooks or GET endpoint.    |

### Amount Format

The Transfers API uses human-readable string amounts for simplicity (e.g., `"1000.00"` for 1000 AED). The granular endpoints (pay-ins, payouts) use smallest-unit integers (e.g., `50000` for 500 AED). Both formats are valid within their respective endpoints.

### Payment Rails

* `"bank_transfer"` — Standard bank transfer (wire, SWIFT). Available in all corridors.
* `"instant"` — Instant payment networks where available (e.g., IPP in UAE). Faster settlement, may have different fee structure.

### Notes

* All transfers require a valid, non-expired quote.
* For fiat sources, complete the bank deposit using the `payment_instructions` in the response.
* Monitor transfer status via `GET /v1/transfers/{id}` or webhooks.
* Use `Idempotency-Key` to safely retry transfers without creating duplicates.