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.

Ratio provides a REST API for partners to request FX quotes, execute swaps, and receive settlement confirmations. This page covers authentication, rate limits, and the complete integration flow.

​
Base URLs

EnvironmentBase URLDescription
Sandboxhttps://api.sandbox.ratiofx.comKaia Kairos testnet. No real funds.
Productionhttps://api.ratiofx.comKaia mainnet. Live funds.
All endpoints are prefixed with /v1/.
Use the sandbox environment to build and test your integration. All stablecoins are test tokens with no real value. Sandbox API keys are issued alongside production keys during onboarding.
Both environments expose identical API endpoints with the same request and response formats.

​
Authentication

Every API request requires two headers:
HeaderValueDescription
AuthorizationBearer {api_key}API key issued during partner onboarding
X-Partner-ID{partner_id}Partner UUID for fee routing and audit trail
Content-Typeapplication/jsonRequired for all request bodies
API keys are 256-bit random tokens issued during onboarding. Sandbox and production keys are separate. Keys rotate on a 90-day cycle, with emergency revocation available. 
curl -X GET "https://api.ratiofx.com/v1/quote?pair=USD-IDR&side=BUY&amount=10000" \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "X-Partner-ID: partner_uuid_xyz"

​
Rate limits

TierRequests per secondBurst
Standard10 req/s20 req burst
Premium50 req/s100 req burst
Rate-limited responses return HTTP 429 with a Retry-After header indicating the number of seconds to wait before retrying.

​
Integration flow

1

Get an indicative quote

Call GET /v1/quote to retrieve a reference price for a currency pair. Use this to display approximate rates to your users before they commit to a trade.Indicative quotes →
2

Request a firm quote

Call POST /v1/firm-quote to lock an executable rate with inventory reservation. The quote carries a hard expiry timestamp — typically 30–60 seconds.Firm quotes →
3

Execute the swap

Call POST /v1/execute with the quote_id from the firm quote. The swap settles atomically on the Kaia blockchain.Executing swaps →
4

Receive settlement confirmation

Settlement status is returned synchronously in the execute response. Ratio also delivers webhook callbacks for asynchronous confirmation.Settlements & webhooks →
Step 1 is optional. You can skip directly to a firm quote if you don’t need to preview pricing for your users.

​
Partner configuration

During onboarding, Ratio configures the following parameters for each partner:
ParameterDescription
Corridors enabledWhich currency pairs the partner can access
Daily volume limitMaximum daily volume per corridor
Monthly volume limitMaximum aggregate monthly volume
Fee tier overridesCustom pricing for specific corridors and tiers (if applicable)
Webhook URLEndpoint for settlement and event callbacks
Wallet whitelistKaia addresses approved for LP deposits and withdrawals
These parameters are managed by Ratio. Contact your account manager to request changes.