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

# Quotes API

> Indicative and firm quote endpoints for the Ratio API.

## GET /v1/quote

Returns a reference price for a currency pair. No inventory is reserved and the rate is not executable — use this to display pricing to your users before they commit.

### Query parameters

<ParamField query="pair" type="string" required>
  Currency pair to quote. Supported values: `USD-IDR`, `USD-SGD`, `MYR-IDR`.
</ParamField>

<ParamField query="side" type="string" required>
  Trade direction. `BUY` or `SELL`.
</ParamField>

<ParamField query="amount" type="number" required>
  Notional amount in the source currency.
</ParamField>

### Response `200 OK`

```json theme={null}
{
  "pair": "USD-IDR",
  "side": "BUY",
  "indicative_rate": 16020.50,
  "mid": 15980.00,
  "spread_bps": 25,
  "timestamp": "2026-02-27T10:00:00Z",
  "quote_type": "INDICATIVE"
}
```

<ResponseField name="pair" type="string">
  Currency pair.
</ResponseField>

<ResponseField name="side" type="string">
  Trade direction.
</ResponseField>

<ResponseField name="indicative_rate" type="number">
  Reference rate. This rate is not executable and carries no expiry.
</ResponseField>

<ResponseField name="mid" type="number">
  Oracle mid-market rate.
</ResponseField>

<ResponseField name="spread_bps" type="number">
  Indicative spread in basis points.
</ResponseField>

<ResponseField name="timestamp" type="string">
  ISO 8601 server timestamp.
</ResponseField>

<ResponseField name="quote_type" type="string">
  Always `INDICATIVE` for this endpoint.
</ResponseField>

<Note>
  Indicative quotes are for display purposes only. To lock a rate for execution, request a firm quote using `POST /v1/firm-quote`.
</Note>

***

## POST /v1/firm-quote

Returns a binding BID/ASK with hard expiry and inventory reservation. You must execute the quote before `expiry_timestamp` or it will expire.

### Request body

<ParamField body="pair" type="string" required>
  Currency pair to quote. Supported values: `USD-IDR`, `USD-SGD`, `MYR-IDR`.
</ParamField>

<ParamField body="side" type="string" required>
  Trade direction. `BUY` or `SELL`.
</ParamField>

<ParamField body="amount" type="number" required>
  Notional amount in the source currency.
</ParamField>

<ParamField body="quote_type" type="string" required>
  Must be `FIRM`.
</ParamField>

<ParamField body="client_ref" type="string">
  Optional partner-side reference for reconciliation (e.g. your internal transaction ID).
</ParamField>

```json theme={null}
{
  "pair": "USD-IDR",
  "side": "BUY",
  "amount": 50000,
  "quote_type": "FIRM",
  "client_ref": "TXN-20260227-001"
}
```

### Response `200 OK`

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

<Warning>
  The quote expires at `expiry_timestamp`. You must call `POST /v1/execute` before that time. Expired quotes return a `QUOTE_EXPIRED` error.
</Warning>

<ResponseField name="quote_id" type="string">
  Unique quote identifier. Pass this to `POST /v1/execute` to settle the swap.
</ResponseField>

<ResponseField name="pair" type="string">
  Currency pair.
</ResponseField>

<ResponseField name="side" type="string">
  Trade direction.
</ResponseField>

<ResponseField name="amount" type="number">
  Notional amount in the source currency.
</ResponseField>

<ResponseField name="bid" type="number">
  Bid price.
</ResponseField>

<ResponseField name="ask" type="number">
  Ask price.
</ResponseField>

<ResponseField name="adjusted_mid" type="number">
  Oracle mid-market rate after inventory adjustment.
</ResponseField>

<ResponseField name="spread_bps" type="number">
  Total spread in basis points.
</ResponseField>

<ResponseField name="expiry_timestamp" type="string">
  ISO 8601 hard expiry for this quote.
</ResponseField>

<ResponseField name="max_size" type="number">
  Maximum executable amount for this quote. Your execution `amount` must not exceed this value.
</ResponseField>

<ResponseField name="allowed_direction" type="string">
  Permitted trade direction under the current system state.
</ResponseField>

<ResponseField name="state_flag" type="string">
  System state at quote time: `NORMAL`, `PROTECT`, or `RESTRICT`.
</ResponseField>

<ResponseField name="execution_path" type="string">
  Routing path used: `DIRECT` or `EXTERNAL_RFQ`.
</ResponseField>

<ResponseField name="fee_breakdown" type="object">
  Full fee transparency for this quote.

  <Expandable title="properties">
    <ResponseField name="tier" type="string">
      Volume tier applied: `MICRO`, `SMALL`, `MEDIUM`, `LARGE`, or `INSTITUTIONAL`.
    </ResponseField>

    <ResponseField name="fixed_fee" type="number">
      Fixed fee in the source currency.
    </ResponseField>

    <ResponseField name="fixed_fee_currency" type="string">
      Source currency code for the fixed fee.
    </ResponseField>

    <ResponseField name="fixed_fee_in_dest" type="number">
      Fixed fee converted to the destination currency.
    </ResponseField>

    <ResponseField name="fixed_fee_dest_currency" type="string">
      Destination currency code for the fixed fee.
    </ResponseField>

    <ResponseField name="variable_fee" type="number">
      Variable fee in the source currency.
    </ResponseField>

    <ResponseField name="variable_fee_bips" type="number">
      Variable fee rate in basis points.
    </ResponseField>

    <ResponseField name="base_spread_bps" type="number">
      Base spread from the partner's fee tier.
    </ResponseField>

    <ResponseField name="total_spread_bps" type="number">
      Total spread including dynamic components.
    </ResponseField>

    <ResponseField name="total_fee_usd" type="number">
      Total platform fee (fixed + variable) in USD.
    </ResponseField>

    <ResponseField name="amount_to_convert" type="number">
      Source amount after fee deduction — the amount actually converted.
    </ResponseField>

    <ResponseField name="is_partner_override" type="boolean">
      `true` if partner-specific rate overrides were applied to this quote.
    </ResponseField>
  </Expandable>
</ResponseField>