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

# Swaps API

> Swap execution and system state endpoints for the Ratio API.

## POST /v1/execute

Submits a firm quote for atomic on-chain settlement. The swap settles on the Kaia blockchain and the output stablecoin is delivered to the destination address you specify.

<Warning>
  Execution is irreversible once confirmed on-chain. Verify the `quote_id`, `amount`, and `destination_address` before submitting.
</Warning>

### Request body

<ParamField body="quote_id" type="string" required>
  Quote ID from `POST /v1/firm-quote`. The quote must not have expired.
</ParamField>

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

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

<ParamField body="client_ref" type="string">
  Optional partner-side reference for reconciliation.
</ParamField>

```json theme={null}
{
  "quote_id": "QT-8821-USD-IDR",
  "amount": 50000,
  "destination_address": "0xABC...123",
  "client_ref": "TXN-20260227-001"
}
```

### Response `200 OK`

```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"
}
```

<ResponseField name="execution_id" type="string">
  Unique execution identifier. Use this for settlement reconciliation and webhook correlation.
</ResponseField>

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

<ResponseField name="status" type="string">
  `SETTLED` confirms the swap is confirmed on-chain.
</ResponseField>

<ResponseField name="filled_rate" type="number">
  Actual execution rate applied to the swap.
</ResponseField>

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

<ResponseField name="destination_amount" type="number">
  Amount credited in the destination currency, delivered to `destination_address`.
</ResponseField>

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

<ResponseField name="tx_hash" type="string">
  Kaia blockchain transaction hash. Use this to verify settlement on-chain.
</ResponseField>

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

<ResponseField name="execution_path" type="string">
  Routing path used: `DIRECT` or `EXTERNAL_RFQ`.
</ResponseField>

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

***

## GET /v1/system/state

Returns the current operating state for each corridor. Call this endpoint before requesting quotes to verify corridor availability, or use it to power status indicators in your UI.

### Response `200 OK`

```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
    }
  }
}
```

<ResponseField name="system_state" type="string">
  Overall system state, reflecting the highest severity state across all corridors.
</ResponseField>

<ResponseField name="corridors" type="object">
  Per-corridor state detail, keyed by currency pair.

  <Expandable title="properties">
    <ResponseField name="corridors.{pair}.state" type="string">
      State for this corridor: `NORMAL`, `PROTECT`, `RESTRICT`, or `HALT`.
    </ResponseField>

    <ResponseField name="corridors.{pair}.allowed_directions" type="string[]">
      Permitted trade directions for this corridor. May be `["BUY", "SELL"]`, `["BUY"]`, or `["SELL"]` depending on state.
    </ResponseField>

    <ResponseField name="corridors.{pair}.oracle_age_ms" type="number">
      Age of the latest oracle price in milliseconds.
    </ResponseField>
  </Expandable>
</ResponseField>

### State definitions

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

<Note>
  When a corridor is in `HALT` state, `POST /v1/firm-quote` returns a `QUOTE_HALTED` error for that corridor. Use this endpoint to monitor recovery before retrying.
</Note>