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

# Executing Swaps

> Submitting a firm quote for atomic on-chain settlement

Once you have a firm quote, submit it for execution. The swap settles atomically on the Kaia blockchain — either both sides complete or neither does. Settlement is immediate and irreversible.

## Check system state first

Before executing, you can verify corridor availability with the system state endpoint:

```
GET /v1/system/state
```

```json theme={null}
{
  "system_state": "NORMAL",
  "corridors": {
    "USD-IDR": {
      "state": "NORMAL",
      "allowed_directions": ["BUY", "SELL"],
      "oracle_age_ms": 380
    },
    "USD-SGD": {
      "state": "NORMAL",
      "allowed_directions": ["BUY", "SELL"],
      "oracle_age_ms": 210
    },
    "MYR-IDR": {
      "state": "PROTECT",
      "allowed_directions": ["BUY", "SELL"],
      "oracle_age_ms": 520
    }
  }
}
```

### State definitions

| State      | Meaning                                                             |
| ---------- | ------------------------------------------------------------------- |
| `NORMAL`   | Full functionality. Standard spreads. Both directions available.    |
| `PROTECT`  | Spreads widened. Max size reduced. Both directions still available. |
| `RESTRICT` | Maximum spread. One direction only. Reduced max size.               |
| `HALT`     | No new quotes accepted. Existing positions settle normally.         |

<Tip>
  Poll `GET /v1/system/state` proactively rather than waiting for `503` errors. This lets you disable corridors in your UI before users encounter failures.
</Tip>

## Execute a swap

```
POST /v1/execute
```

<ParamField body="quote_id" type="string" required>
  The `quote_id` returned from `POST /v1/firm-quote`. Each quote ID can only be executed once.
</ParamField>

<ParamField body="amount" type="number" required>
  Execution amount in the source currency. Must be less than or equal to the quote's `max_size`.
</ParamField>

<ParamField body="destination_address" type="string" required>
  On-chain Kaia wallet address to receive the output stablecoin.
</ParamField>

<ParamField body="client_ref" type="string">
  Your internal reference for reconciliation. Included in webhook payloads and settlement records.
</ParamField>

### Example request

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://api.ratiofx.com/v1/execute" \
    -H "Authorization: Bearer sk_live_abc123..." \
    -H "X-Partner-ID: partner_uuid_xyz" \
    -H "Content-Type: application/json" \
    -d '{
      "quote_id": "QT-8821-USD-IDR",
      "amount": 50000,
      "destination_address": "0xABC...123",
      "client_ref": "TXN-20260227-001"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.ratiofx.com/v1/execute", {
    method: "POST",
    headers: {
      "Authorization": "Bearer sk_live_abc123...",
      "X-Partner-ID": "partner_uuid_xyz",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      quote_id: "QT-8821-USD-IDR",
      amount: 50000,
      destination_address: "0xABC...123",
      client_ref: "TXN-20260227-001",
    }),
  });
  const result = await response.json();
  ```

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

  response = requests.post(
      "https://api.ratiofx.com/v1/execute",
      json={
          "quote_id": "QT-8821-USD-IDR",
          "amount": 50000,
          "destination_address": "0xABC...123",
          "client_ref": "TXN-20260227-001",
      },
      headers={
          "Authorization": "Bearer sk_live_abc123...",
          "X-Partner-ID": "partner_uuid_xyz",
      },
  )
  result = response.json()
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "execution_id": "EX-9910-USD-IDR",
  "quote_id": "QT-8821-USD-IDR",
  "status": "SETTLED",
  "filled_rate": 16020.00,
  "source_amount": 50000,
  "destination_amount": 801000000,
  "platform_fee": 52.00,
  "tx_hash": "0xKAIA...ABC",
  "settled_at": "2026-02-27T10:00:32Z",
  "execution_path": "DIRECT",
  "state_flag": "NORMAL"
}
```

### Response fields

<ResponseField name="execution_id" type="string">
  Unique execution identifier.
</ResponseField>

<ResponseField name="quote_id" type="string">
  The firm quote that was executed.
</ResponseField>

<ResponseField name="status" type="string">
  Settlement status. `SETTLED` means the transaction is confirmed on-chain.
</ResponseField>

<ResponseField name="filled_rate" type="number">
  Actual execution rate.
</ResponseField>

<ResponseField name="source_amount" type="number">
  Amount debited in source currency.
</ResponseField>

<ResponseField name="destination_amount" type="number">
  Amount credited in destination currency.
</ResponseField>

<ResponseField name="platform_fee" type="number">
  Total platform fee charged, in source currency.
</ResponseField>

<ResponseField name="tx_hash" type="string">
  Kaia blockchain transaction hash. Independently verifiable on [Kaiascan](https://kaiascan.io).
</ResponseField>

<ResponseField name="settled_at" type="string">
  ISO 8601 timestamp of on-chain settlement.
</ResponseField>

<ResponseField name="execution_path" type="string">
  `DIRECT` or `EXTERNAL_RFQ`.
</ResponseField>

<ResponseField name="state_flag" type="string">
  System state at the time of execution.
</ResponseField>

## Settlement finality

<Warning>
  Execution is irreversible. Once the response returns `"status": "SETTLED"`, the transaction is finalised on the Kaia blockchain. There is no possibility of reversal, partial settlement, or clawback.
</Warning>

The `tx_hash` can be independently verified on the Kaia block explorer.

## Common error cases

| Error                        | Cause                                                 | Resolution                                               |
| ---------------------------- | ----------------------------------------------------- | -------------------------------------------------------- |
| `QUOTE_EXPIRED`              | Execution attempted after `expiry_timestamp`          | Request a new firm quote                                 |
| `QUOTE_HALTED`               | System entered HALT state between quote and execution | Wait for system recovery; monitor `GET /v1/system/state` |
| `BELOW_MIN_TRANSACTION_SIZE` | Amount is below the corridor minimum                  | Increase amount to meet the minimum for this corridor    |

See [Error handling](/integration/error-handling) for the complete error reference.

## Next step

Settlement status is also delivered asynchronously via webhook. Set up your webhook handler to receive real-time confirmations.

[Settlements & webhooks →](/integration/settlements-webhooks)