Integration Overview

Ratio provides a REST API for partners to request FX quotes and verify on-chain settlements. The API follows a CeDeFi architecture — quoting and compliance run off-chain through this API, while settlement happens on-chain when the partner submits a transaction directly to the Kaia blockchain.

Ratio never takes custody of partner funds. The partner’s wallet signs and submits all settlement transactions. Funds move only at the moment of on-chain execution.

Base URLs

Environment	URL	Chain
Sandbox	`https://sbx.ratiofx.com/api/router`	Kaia Kairos testnet (`1001`)
Production	`https://app.ratiofx.com/api/router`	Kaia mainnet (`8217`)

Endpoint paths (e.g. /v1/corridors) are appended to the base URL. The /api/router prefix is not part of the HMAC string-to-sign — sign /v1/... paths only.

Authentication

Every API request must be signed using HMAC-SHA256. This provides authentication, integrity verification, and replay protection.

Header	Value
`x-ratio-api-key`	Your public API key (starts with `rk_`)
`x-ratio-timestamp`	Current Unix timestamp in seconds. Rejected if more than 30s from server time.
`x-ratio-request-id`	POST only. Unique replay-protection ID (alphanumeric, hyphens, underscores; max 128 chars). Each ID can only be used once within 60s.
`x-ratio-signature`	HMAC-SHA256 of the string-to-sign, keyed with your API secret. Lowercase hex (64 chars).
`Content-Type`	`application/json` (required for POST requests)

Credentials

Issued during onboarding as a pair:

API Key — public identifier, sent in x-ratio-api-key.
API Secret — HMAC signing key. Server-side only, never transmitted after issuance. Store in a secret manager, Vault, KMS, or HSM — never in frontend code, public repos, logs, or CI output.

String-to-sign

Direct concatenation, no separators. GET requests:

{timestamp}{method}{path}

POST requests (includes x-ratio-request-id):

{timestamp}{request_id}{method}{path}{body}

Component	Description
`timestamp`	Same value as `x-ratio-timestamp` (Unix seconds, as string)
`request_id`	Same value as `x-ratio-request-id`. POST only — omit for GET
`method`	`GET` or `POST`
`path`	Request path including query string, starting at `/v1` (e.g. `/v1/corridors`)
`body`	Raw JSON body for POST; empty string for GET

# String-to-sign:
1789549200GET/v1/corridors

# String-to-sign:
1789549200req-1789549200-7f3c9a1ePOST/v1/firm-quote{"corridor_id":"0xf27e...","from_token":"0xd077...","to_token":"0x557b...","amount":"1000","signer":"0xPARTNER","quote_type":"FIRM"}

API endpoints

Method	Endpoint	Description
`POST`	`/v1/quote`	Indicative quote (not executable)
`POST`	`/v1/firm-quote`	Firm executable quote with EIP-712 signature and on-chain calldata
`GET`	`/v1/executions`	Execution lookup or paginated history
`GET`	`/v1/corridors`	Available corridors, token addresses, limits, fee tiers, risk state
`GET`	`/v1/rates`	Current oracle mid-market rates
`GET`	`/v1/reports/daily-summary`	Daily reconciliation summary

There is no /v1/execute endpoint. Execution happens on-chain — the partner submits the commitFirmQuote transaction directly to the FxEngine contract using calldata returned by POST /v1/firm-quote.

Integration flow

Discover corridors

Call GET /v1/corridors to get corridor_id, token addresses, fee tiers, and risk state for each supported pair.

Get an indicative quote

Call POST /v1/quote with corridor_id, from_token, to_token, amount, and signer. Returns a reference price with full fee breakdown.

Approve the input token

One-time per token: from your wallet, approve() the FxEngine contract to spend the input token. Do this before requesting the firm quote you will execute — firm quotes expire after 60 seconds.

Request a firm quote

Call POST /v1/firm-quote to lock an executable rate. Returns an EIP-712 signed payload and ready-to-submit calldata.

Execute on-chain

Send a transaction to the FxEngine contract using the execution.calldata from the firm quote response. The swap settles atomically in that transaction.

Verify settlement

Call GET /v1/executions?quote=0x... to confirm settlement and retrieve execution details.

For a runnable end-to-end script covering every step, see the Full Example.

Response format

All responses follow a consistent envelope: Success:

{
  "success": true,
  "data": { ... },
  "meta": {
    "request_id": "req_1789549200123456789",
    "timestamp": "2026-09-16T09:00:00Z"
  }
}

Error:

{
  "success": false,
  "error": {
    "code": "CORRIDOR_NOT_AUTHORIZED",
    "message": "this partner credential is not authorized for the requested corridor",
    "corridor": null,
    "details": {}
  },
  "meta": {
    "request_id": "req_1789549205987654321",
    "timestamp": "2026-09-16T09:00:05Z"
  }
}

Partner configuration

During onboarding, Ratio configures the following for each partner:

Parameter	Description
API credentials	API key (`rk_...`) + API secret pair
Wallet whitelist	Kaia addresses registered with swap permission
Corridors enabled	Which corridors the credential may quote
Fee tier / pricing mode	Standard tiered or fixed input-rate pricing
Volume limits	Per-corridor min/max per transaction in USD, and daily volume limits

Get Started

Features

Architecture

Integration

Partners

Resources

Integration Overview

Base URLs

Authentication

Credentials

String-to-sign

API endpoints

Integration flow

Response format

Partner configuration

​Base URLs

​Authentication

​Credentials

​String-to-sign

​API endpoints

​Integration flow

​Response format

​Partner configuration

Base URLs

Authentication

Credentials

String-to-sign

API endpoints

Integration flow

Response format

Partner configuration