Firm Quotes

A firm quote returns an executable BID/ASK price with a hard expiry timestamp. Unlike indicative quotes, firm quotes reserve inventory — guaranteeing that the quoted rate is available for execution until the quote expires.

When to use

Your user has confirmed they want to execute a transfer
You need a binding rate to display before the final confirmation step
You’re building a two-step flow: preview rate → confirm → execute

Request

POST /v1/firm-quote

string

required

Currency pair to quote. Supported values: USD-IDR, USD-SGD, MYR-IDR.

string

required

Trade direction. BUY or SELL.

number

required

Notional amount in the source currency.

string

required

Must be FIRM.

string

Your internal reference for reconciliation. Included in webhook payloads and settlement records.

Example request

curl -X POST "https://api.ratiofx.com/v1/firm-quote" \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "X-Partner-ID: partner_uuid_xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "pair": "USD-IDR",
    "side": "BUY",
    "amount": 50000,
    "quote_type": "FIRM",
    "client_ref": "TXN-20260227-001"
  }'

const response = await fetch("https://api.ratiofx.com/v1/firm-quote", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_abc123...",
    "X-Partner-ID": "partner_uuid_xyz",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    pair: "USD-IDR",
    side: "BUY",
    amount: 50000,
    quote_type: "FIRM",
    client_ref: "TXN-20260227-001",
  }),
});
const firmQuote = await response.json();

import requests

response = requests.post(
    "https://api.ratiofx.com/v1/firm-quote",
    json={
        "pair": "USD-IDR",
        "side": "BUY",
        "amount": 50000,
        "quote_type": "FIRM",
        "client_ref": "TXN-20260227-001",
    },
    headers={
        "Authorization": "Bearer sk_live_abc123...",
        "X-Partner-ID": "partner_uuid_xyz",
    },
)
firm_quote = response.json()

Response

{
  "quote_id": "QT-8821-USD-IDR",
  "pair": "USD-IDR",
  "side": "BUY",
  "amount": 50000,
  "bid": 15940.00,
  "ask": 16020.00,
  "adjusted_mid": 15980.00,
  "spread_bps": 25,
  "expiry_timestamp": "2026-02-27T10:00:45Z",
  "max_size": 50000,
  "allowed_direction": "BUY",
  "state_flag": "NORMAL",
  "quote_type": "FIRM",
  "execution_path": "DIRECT",
  "fee_breakdown": {
    "tier": "MEDIUM",
    "fixed_fee": 0.633,
    "fixed_fee_currency": "USD",
    "fixed_fee_in_dest": 10000,
    "fixed_fee_dest_currency": "IDR",
    "variable_fee": 10.00,
    "variable_fee_bips": 2,
    "base_spread_bps": 20,
    "total_spread_bps": 25,
    "total_fee_usd": 10.633,
    "amount_to_convert": 49989.37,
    "is_partner_override": false
  }
}

Response fields

string

required

Unique quote identifier. Pass this to POST /v1/execute to execute the swap.

string

Currency pair.

string

Trade direction.

number

Notional in source currency.

number

Bid price — the rate at which the FX Engine buys the base currency.

number

Ask price — the rate at which the FX Engine sells the base currency.

number

Oracle mid-rate after inventory adjustment.

number

Total spread in basis points.

string

ISO 8601 hard expiry. The quote cannot be executed after this time.

number

Maximum executable size for this quote. Your execution amount must not exceed this value.

string

Permitted trade direction under current system conditions.

string

Current system state for this corridor: NORMAL, PROTECT, or RESTRICT.

string

Always FIRM.

string

How the trade will be filled. DIRECT means filled from Ratio’s internal liquidity pools. EXTERNAL_RFQ means the trade size exceeds internal pool depth and will be filled via an external market maker.

object

Full breakdown of all fee components. See below.

Fee breakdown

The fee_breakdown object provides full transparency on all fee components applied to this quote.

string

Volume tier applied to this transaction: MICRO, SMALL, MEDIUM, LARGE, or INSTITUTIONAL.

number

Fixed fee in source currency.

string

Source currency code.

number

Fixed fee converted to destination currency.

string

Destination currency code.

number

Variable fee in source currency.

number

Variable fee rate in basis points.

number

Base spread component from the fee tier.

number

Total spread including all dynamic components.

number

Total platform fee (fixed + variable) in USD equivalent.

number

Source amount after fee deduction. This is the amount converted at the quoted rate.

boolean

Whether partner-specific custom rates were applied to this quote.

Quote expiry

Firm quotes have a short expiry window — typically 30–60 seconds. After expiry:

The quote cannot be executed.
Reserved inventory is released back to the pool.
You must request a new firm quote at current rates.

Always execute before expiry_timestamp. Check the timestamp immediately after receiving the response and alert your users if they are slow to confirm.

Next step

Submit the quote_id to execute the swap on-chain. Execute the swap →

Get Started

Features

Architecture

Integration

Partners

Resources

When to use

Request

Example request

Response

Response fields

Fee breakdown

Quote expiry

Next step

​When to use

​Request

​Example request

​Response

​Response fields

​Fee breakdown

​Quote expiry

​Next step

When to use

Request

Example request

Response

Response fields

Fee breakdown

Quote expiry

Next step