Skip to main content

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.

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

StateMeaning
NORMALFull functionality. Standard spreads. Both directions available.
PROTECTSpreads widened. Max size reduced. Both directions still available.
RESTRICTMaximum spread. One direction only. Reduced max size.
HALTNo 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
​
quote_id
string
required
The quote_id returned from POST /v1/firm-quote. Each quote ID can only be executed once.
​
amount
number
required
Execution amount in the source currency. Must be less than or equal to the quote’s max_size.
​
destination_address
string
required
On-chain Kaia wallet address to receive the output stablecoin.
​
client_ref
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"
  }'

​
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

​
execution_id
string
Unique execution identifier.
​
quote_id
string
The firm quote that was executed.
​
status
string
Settlement status. SETTLED means the transaction is confirmed on-chain.
​
filled_rate
number
Actual execution rate.
​
source_amount
number
Amount debited in source currency.
​
destination_amount
number
Amount credited in destination currency.
​
platform_fee
number
Total platform fee charged, in source currency.
​
tx_hash
string
Kaia blockchain transaction hash. Independently verifiable on Kaiascan.
​
settled_at
string
ISO 8601 timestamp of on-chain settlement.
​
execution_path
string
DIRECT or EXTERNAL_RFQ.
​
state_flag
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

ErrorCauseResolution
QUOTE_EXPIREDExecution attempted after expiry_timestampRequest a new firm quote
QUOTE_HALTEDSystem entered HALT state between quote and executionWait for system recovery; monitor GET /v1/system/state
BELOW_MIN_TRANSACTION_SIZEAmount is below the corridor minimumIncrease 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 →