Executing Swaps

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

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

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

Execute a swap

POST /v1/execute

string

required

The quote_id returned from POST /v1/firm-quote. Each quote ID can only be executed once.

number

required

Execution amount in the source currency. Must be less than or equal to the quote’s max_size.

string

required

On-chain Kaia wallet address to receive the output stablecoin.

string

Your internal reference for reconciliation. Included in webhook payloads and settlement records.

Example request

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

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();

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()

Response

{
  "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

string

Unique execution identifier.

string

The firm quote that was executed.

string

Settlement status. SETTLED means the transaction is confirmed on-chain.

number

Actual execution rate.

number

Amount debited in source currency.

number

Amount credited in destination currency.

number

Total platform fee charged, in source currency.

string

Kaia blockchain transaction hash. Independently verifiable on Kaiascan.

string

ISO 8601 timestamp of on-chain settlement.

string

DIRECT or EXTERNAL_RFQ.

string

System state at the time of execution.

Settlement finality

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.

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

Get Started

Features

Architecture

Integration

Partners

Resources

Executing Swaps

Check system state first

State definitions

Execute a swap

Example request

Response

Response fields

Settlement finality

Common error cases

Next step

​Check system state first

​State definitions

​Execute a swap

​Example request

​Response

​Response fields

​Settlement finality

​Common error cases

​Next step

Check system state first

State definitions

Execute a swap

Example request

Response

Response fields

Settlement finality

Common error cases

Next step