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.

​
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.
Execution is irreversible once confirmed on-chain. Verify the quote_id, amount, and destination_address before submitting.

​
Request body

​
quote_id
string
required
Quote ID from POST /v1/firm-quote. The quote must not have expired.
​
amount
number
required
Execution amount in the source currency. Must be less than or equal to max_size from the firm quote response.
​
destination_address
string
required
Kaia wallet address to receive the output stablecoin.
​
client_ref
string
Optional partner-side reference for reconciliation.
{
  "quote_id": "QT-8821-USD-IDR",
  "amount": 50000,
  "destination_address": "0xABC...123",
  "client_ref": "TXN-20260227-001"
}

​
Response 200 OK

{
  "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"
}
​
execution_id
string
Unique execution identifier. Use this for settlement reconciliation and webhook correlation.
​
quote_id
string
The firm quote that was executed.
​
status
string
SETTLED confirms the swap is confirmed on-chain.
​
filled_rate
number
Actual execution rate applied to the swap.
​
source_amount
number
Amount debited in the source currency.
​
destination_amount
number
Amount credited in the destination currency, delivered to destination_address.
​
platform_fee
number
Total platform fee in the source currency.
​
tx_hash
string
Kaia blockchain transaction hash. Use this to verify settlement on-chain.
​
settled_at
string
ISO 8601 timestamp of on-chain settlement.
​
execution_path
string
Routing path used: DIRECT or EXTERNAL_RFQ.
​
state_flag
string
System state at time of execution.

​
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

{
  "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
    }
  }
}
​
system_state
string
Overall system state, reflecting the highest severity state across all corridors.
​
corridors
object
Per-corridor state detail, keyed by currency pair.

​
State definitions

StateMeaning
NORMALFull functionality. Standard spreads. Both directions available.
PROTECTSpreads widened. Maximum size reduced. Both directions still available.
RESTRICTMaximum spread applied. One direction only. Reduced maximum size.
HALTNo new quotes accepted. Existing positions settle normally.
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.