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

# Overview

> Getting started with the Ratio API

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

| Environment    | Base URL                          | Description                         |
| -------------- | --------------------------------- | ----------------------------------- |
| **Sandbox**    | `https://api.sandbox.ratiofx.com` | Kaia Kairos testnet. No real funds. |
| **Production** | `https://api.ratiofx.com`         | Kaia mainnet. Live funds.           |

All endpoints are prefixed with `/v1/`.

<Tabs>
  <Tab title="Sandbox">
    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.
  </Tab>

  <Tab title="Production">
    Production access is granted after successful sandbox testing and certification. All transactions involve real stablecoins and settle on-chain.
  </Tab>
</Tabs>

Both environments expose identical API endpoints with the same request and response formats.

## Authentication

Every API request requires two headers:

| Header          | Value              | Description                                  |
| --------------- | ------------------ | -------------------------------------------- |
| `Authorization` | `Bearer {api_key}` | API key issued during partner onboarding     |
| `X-Partner-ID`  | `{partner_id}`     | Partner UUID for fee routing and audit trail |
| `Content-Type`  | `application/json` | Required 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.

```bash theme={null}
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

| Tier         | Requests per second | Burst         |
| ------------ | ------------------- | ------------- |
| **Standard** | 10 req/s            | 20 req burst  |
| **Premium**  | 50 req/s            | 100 req burst |

Rate-limited responses return HTTP `429` with a `Retry-After` header indicating the number of seconds to wait before retrying.

## Integration flow

<Steps>
  <Step title="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 →](/integration/indicative-quotes)
  </Step>

  <Step title="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 →](/integration/firm-quotes)
  </Step>

  <Step title="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 →](/integration/executing-swaps)
  </Step>

  <Step title="Receive settlement confirmation">
    Settlement status is returned synchronously in the execute response. Ratio also delivers webhook callbacks for asynchronous confirmation.

    [Settlements & webhooks →](/integration/settlements-webhooks)
  </Step>
</Steps>

<Note>
  Step 1 is optional. You can skip directly to a firm quote if you don't need to preview pricing for your users.
</Note>

## Partner configuration

During onboarding, Ratio configures the following parameters for each partner:

| Parameter                | Description                                                     |
| ------------------------ | --------------------------------------------------------------- |
| **Corridors enabled**    | Which currency pairs the partner can access                     |
| **Daily volume limit**   | Maximum daily volume per corridor                               |
| **Monthly volume limit** | Maximum aggregate monthly volume                                |
| **Fee tier overrides**   | Custom pricing for specific corridors and tiers (if applicable) |
| **Webhook URL**          | Endpoint for settlement and event callbacks                     |
| **Wallet whitelist**     | Kaia addresses approved for LP deposits and withdrawals         |

These parameters are managed by Ratio. Contact your account manager to request changes.