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.

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
​
pair
string
required
Currency pair to quote. Supported values: USD-IDR, USD-SGD, MYR-IDR.
​
side
string
required
Trade direction. BUY or SELL.
​
amount
number
required
Notional amount in the source currency.
​
quote_type
string
required
Must be FIRM.
​
client_ref
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"
  }'

​
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

​
quote_id
string
required
Unique quote identifier. Pass this to POST /v1/execute to execute the swap.
​
pair
string
Currency pair.
​
side
string
Trade direction.
​
amount
number
Notional in source currency.
​
bid
number
Bid price — the rate at which the FX Engine buys the base currency.
​
ask
number
Ask price — the rate at which the FX Engine sells the base currency.
​
adjusted_mid
number
Oracle mid-rate after inventory adjustment.
​
spread_bps
number
Total spread in basis points.
​
expiry_timestamp
string
ISO 8601 hard expiry. The quote cannot be executed after this time.
​
max_size
number
Maximum executable size for this quote. Your execution amount must not exceed this value.
​
allowed_direction
string
Permitted trade direction under current system conditions.
​
state_flag
string
Current system state for this corridor: NORMAL, PROTECT, or RESTRICT.
​
quote_type
string
Always FIRM.
​
execution_path
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.
​
fee_breakdown
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.
​
fee_breakdown.tier
string
Volume tier applied to this transaction: MICRO, SMALL, MEDIUM, LARGE, or INSTITUTIONAL.
​
fee_breakdown.fixed_fee
number
Fixed fee in source currency.
​
fee_breakdown.fixed_fee_currency
string
Source currency code.
​
fee_breakdown.fixed_fee_in_dest
number
Fixed fee converted to destination currency.
​
fee_breakdown.fixed_fee_dest_currency
string
Destination currency code.
​
fee_breakdown.variable_fee
number
Variable fee in source currency.
​
fee_breakdown.variable_fee_bips
number
Variable fee rate in basis points.
​
fee_breakdown.base_spread_bps
number
Base spread component from the fee tier.
​
fee_breakdown.total_spread_bps
number
Total spread including all dynamic components.
​
fee_breakdown.total_fee_usd
number
Total platform fee (fixed + variable) in USD equivalent.
​
fee_breakdown.amount_to_convert
number
Source amount after fee deduction. This is the amount converted at the quoted rate.
​
fee_breakdown.is_partner_override
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 →