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

# Settling with Stablecoins

> Use stablecoins as the settlement rail for cross-border and domestic value transfers.

import { CardGroup, Steps, CodeGroup, Note, Tip, Warning } from 'mintlify/components';

## Overview

Thiqwave enables stablecoin settlement for fast, transparent value transfers. Convert fiat to stablecoins, move them on-chain, and convert back to destination fiat — all through the Transfers API. Settlement is significantly faster than traditional banking rails like SWIFT and works for both cross-border and domestic transfers.

## The settlement flow

Stablecoin settlement follows a simple pattern:

**Fiat → Stablecoin → On-chain Transfer → Fiat**

<Steps>
  <Step title="Get a transfer quote">
    Request a quote specifying source and destination currencies. The quote locks in rates and fees for 3 minutes.
  </Step>

  <Step title="Create the transfer">
    Submit the transfer with your quote ID, source (fiat), and destination (fiat). Thiqwave handles the stablecoin conversion and routing internally.
  </Step>

  <Step title="Complete the deposit">
    If your source is fiat, use the `payment_instructions` in the response to complete the bank deposit.
  </Step>

  <Step title="Monitor progress">
    Track the transfer through its lifecycle via `GET /v1/transfers/{id}` or webhooks.
  </Step>
</Steps>

## Getting a transfer quote

Request a quote to see the exact amounts and rates before committing.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.thiqwave.com/v1/quotes" \
    -H "X-API-Key: your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "transfer",
      "source_currency": "AED",
      "destination_currency": "EUR",
      "amount": "1000.00",
      "corridor": "uae"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.thiqwave.com/v1/quotes', {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'transfer',
      source_currency: 'AED',
      destination_currency: 'EUR',
      amount: '1000.00',
      corridor: 'uae'
    })
  });

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

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

  response = requests.post(
      'https://api.thiqwave.com/v1/quotes',
      headers={
          'X-API-Key': 'your-api-key',
          'Content-Type': 'application/json'
      },
      json={
          'type': 'transfer',
          'source_currency': 'AED',
          'destination_currency': 'EUR',
          'amount': '1000.00',
          'corridor': 'uae'
      }
  )

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

### Response

```json theme={null}
{
  "id": "quote_settlement_001",
  "type": "transfer",
  "source_currency": "AED",
  "destination_currency": "EUR",
  "source_amount": "1000.00",
  "destination_amount": "253.00",
  "exchange_rate": "0.2530",
  "fees": {
    "platform_fee": "2.00",
    "network_fee": "0.00"
  },
  "total_fee": "2.00",
  "expires_at": "2026-04-08T12:03:00Z",
  "created_at": "2026-04-08T12:00:00Z"
}
```

<Note>
  The quote shows source amount, destination amount, fees, and exchange rate. Stablecoin routing is handled internally — you only see the fiat-to-fiat conversion. Quotes expire after 3 minutes.
</Note>

## Creating the transfer

Once you have a quote, create the transfer with source and destination details.

<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: settlement_001" \
    -d '{
      "quote_id": "quote_settlement_001",
      "source": {
        "currency": "AED",
        "payment_rail": "bank_transfer"
      },
      "destination": {
        "currency": "EUR",
        "account_holder": "Schmidt GmbH",
        "account_number": "DE89370400440532013000",
        "bank_code": "COBADEFFXXX",
        "country": "DE"
      },
      "amount": "1000.00",
      "metadata": {
        "transaction_id": "txn_cross_border_001"
      }
    }'
  ```

  ```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': 'settlement_001'
    },
    body: JSON.stringify({
      quote_id: 'quote_settlement_001',
      source: {
        currency: 'AED',
        payment_rail: 'bank_transfer'
      },
      destination: {
        currency: 'EUR',
        account_holder: 'Schmidt GmbH',
        account_number: 'DE89370400440532013000',
        bank_code: 'COBADEFFXXX',
        country: 'DE'
      },
      amount: '1000.00',
      metadata: {
        transaction_id: 'txn_cross_border_001'
      }
    })
  });

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

  ```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': 'settlement_001'
      },
      json={
          'quote_id': 'quote_settlement_001',
          'source': {
              'currency': 'AED',
              'payment_rail': 'bank_transfer'
          },
          'destination': {
              'currency': 'EUR',
              'account_holder': 'Schmidt GmbH',
              'account_number': 'DE89370400440532013000',
              'bank_code': 'COBADEFFXXX',
              'country': 'DE'
          },
          'amount': '1000.00',
          'metadata': {
              'transaction_id': 'txn_cross_border_001'
          }
      }
  )

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

### Response

```json theme={null}
{
  "id": "txn_01HZ5NM2XDQE8F1G7HKRWS4JV",
  "quote_id": "quote_settlement_001",
  "status": "awaiting_deposit",
  "source": {
    "currency": "AED",
    "payment_rail": "bank_transfer",
    "amount": "1000.00"
  },
  "destination": {
    "currency": "EUR",
    "amount": "253.00"
  },
  "fees": {
    "platform_fee": "2.00",
    "network_fee": "0.00"
  },
  "exchange_rate": "0.2530",
  "payment_instructions": {
    "beneficiary_name": "Thiqwave Limited",
    "beneficiary_account": "1234567890",
    "bank_code": "ABUAAE3D",
    "reference": "txn_01HZ5NM2XDQE8F1G7HKRWS4JV",
    "country": "AE"
  },
  "metadata": {
    "transaction_id": "txn_cross_border_001"
  },
  "created_at": "2026-04-08T12:00:30Z",
  "completed_at": null
}
```

## Transfer lifecycle

Transfers progress through distinct states as they move from fiat source to stablecoin settlement to fiat destination:

| 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.    |

## Tracking transfer progress

Monitor transfers through webhooks. You'll receive notifications at each stage:

```json theme={null}
{
  "type": "transfer.processing",
  "data": {
    "id": "txn_01HZ5NM2XDQE8F1G7HKRWS4JV",
    "status": "processing",
    "updated_at": "2026-04-08T12:01:00Z"
  }
}
```

```json theme={null}
{
  "type": "transfer.settling",
  "data": {
    "id": "txn_01HZ5NM2XDQE8F1G7HKRWS4JV",
    "status": "settling",
    "updated_at": "2026-04-08T12:02:00Z"
  }
}
```

```json theme={null}
{
  "type": "transfer.completed",
  "data": {
    "id": "txn_01HZ5NM2XDQE8F1G7HKRWS4JV",
    "status": "completed",
    "destination_amount": "253.00",
    "completed_at": "2026-04-08T12:05:00Z"
  }
}
```

<Tip>
  Subscribe to all transfer events (`transfer.processing`, `transfer.settling`, `transfer.completed`, `transfer.failed`) to build complete visibility into your cross-border flows.
</Tip>

## Why stablecoin settlement?

**Speed** — Significantly faster than SWIFT and traditional banking rails. Most settlements complete within minutes.

**Transparency** — Track on-chain movement with transaction hashes. Verify every step of the journey.

**Cost efficiency** — Reduced fees compared to traditional correspondent banking.

**Availability** — Works 24/7, including weekends and holidays. No banking hours limitations.

**Reliability** — Blockchain-based finality. Once on-chain, settlement is immutable.

## Use cases

**Cross-border B2B payments** — Pay vendors across different countries without managing multiple bank relationships.

**Marketplace settlements** — Instantly settle funds from one currency zone to another as transactions complete.

**Salary disbursements** — Pay employees across countries with transparent, auditable settlement trails.

**Treasury management** — Move liquidity across regions quickly for optimal capital allocation.

## Error handling

If a transfer fails, you receive a `transfer.failed` webhook event.

| Issue               | Cause                         | Recovery                                                            |
| ------------------- | ----------------------------- | ------------------------------------------------------------------- |
| Invalid destination | Bank details incorrect        | Request a new quote and retry with correct details                  |
| Quote expired       | More than 3 minutes passed    | Get a fresh quote                                                   |
| Insufficient funds  | Source deposit not received   | Complete the bank deposit using `payment_instructions`              |
| Network issue       | On-chain transmission delayed | Monitor via `GET /v1/transfers/{id}`; transfers retry automatically |

## Best practices

* **Always get a quote first** — Understand costs and rates before committing
* **Validate destination details** — Ensure correct bank codes, account numbers, and country codes
* **Use metadata** — Track transfers in your system with transaction IDs
* **Subscribe to webhooks** — React in real-time to transfer progress
* **Handle failures gracefully** — When transfers fail, notify users and offer retry options
* **Use idempotency keys** — Safely retry transfers without creating duplicates

## Next steps

* [Transfers API](/api/transfers/create) — Full endpoint reference
* [Receiving payments](/guides/receiving-payments) — Fund transfers with customer deposits
* [Webhooks](/guides/webhooks) — Set up complete event monitoring