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

Execution is irreversible once confirmed on-chain. Verify the quote_id, amount, and destination_address before submitting.

Request body

string

required

Quote ID from POST /v1/firm-quote. The quote must not have expired.

number

required

Execution amount in the source currency. Must be less than or equal to max_size from the firm quote response.

string

required

Kaia wallet address to receive the output stablecoin.

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

string

Unique execution identifier. Use this for settlement reconciliation and webhook correlation.

string

The firm quote that was executed.

string

SETTLED confirms the swap is confirmed on-chain.

number

Actual execution rate applied to the swap.

number

Amount debited in the source currency.

number

Amount credited in the destination currency, delivered to destination_address.

number

Total platform fee in the source currency.

string

Kaia blockchain transaction hash. Use this to verify settlement on-chain.

string

ISO 8601 timestamp of on-chain settlement.

string

Routing path used: DIRECT or EXTERNAL_RFQ.

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

string

Overall system state, reflecting the highest severity state across all corridors.

object

Per-corridor state detail, keyed by currency pair.

Show properties

string

State for this corridor: NORMAL, PROTECT, RESTRICT, or HALT.

string[]

Permitted trade directions for this corridor. May be ["BUY", "SELL"], ["BUY"], or ["SELL"] depending on state.

number

Age of the latest oracle price in milliseconds.

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.

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.

Overview

Endpoints

POST /v1/execute

Request body

Response `200 OK`

GET /v1/system/state

Response `200 OK`

State definitions

​POST /v1/execute

​Request body

​Response 200 OK

​GET /v1/system/state

​Response 200 OK

​State definitions

POST /v1/execute

Request body

Response `200 OK`

GET /v1/system/state

Response `200 OK`

State definitions