Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
Lock an executable rate with EIP-712 signature and on-chain calldata
POST /v1/firm-quote
POST /v1/quote, except:
| Field | Type | Required | Description |
|---|---|---|---|
corridor_id | string | Yes | On-chain bytes32 corridor ID from GET /v1/corridors |
from_token | string | Yes | 0x-prefixed ERC-20 address of the input token |
to_token | string | Yes | 0x-prefixed ERC-20 address of the output token |
amount | string | Yes | Decimal display amount of the input token (as a string) |
signer | string | Yes | 0x-prefixed wallet address that will call commitFirmQuote on-chain |
quote_type | string | Yes | Must be FIRM. Missing or non-FIRM values are rejected. |
client_ref | string | No | Partner-supplied idempotency reference. Non-empty, no leading or trailing whitespace, max 128 chars. Any previously used value is rejected with 409. |
approve() the FxEngine contract (execution.contract) to spend the input token for at least amount.in.raw before requesting a firm quote. Quotes expire after quote_expiry_seconds (currently 60s). One-time per token, or use type(uint256).max.{
"success": true,
"data": {
"pair": "USDT-IDRX",
"side": "SELL",
"amount": {
"in": { "display": "1000", "raw": "1000000000", "token": "USDT" },
"out": { "display": "17652861.35", "raw": "1765286135", "token": "IDRX" }
},
"allowed_directions": ["BUY", "SELL"],
"state_flag": "NORMAL",
"quote_type": "FIRM",
"expires_at": 1789549260,
"fee_breakdown": { ... },
"quote": {
"quote_id": "0x3f9c2b7e...de21a",
"corridor_id": "0xf27e3185...fb5b",
"signer": "0xpartner_wallet_address",
"partner": "0xpartner_wallet_address",
"assets": {
"from_asset": "0xd077a400968890eacc75cdc901f0356c943e4fdb",
"to_asset": "0x557b3de669e86365ab07068542d9eeb604a2c0ea",
"from_asset_price": "100000000",
"to_asset_price": "5649"
},
"attributes": {
"state": 0,
"amount_in": "1000000000",
"amount_out": "1767761001",
"spread_bps": "15",
"skew_bps": "-1"
},
"fees": {
"fixed_fee": "564971",
"variable_fee": "700000",
"spread_fee": "2474866"
},
"expires_at": 1789549260,
"nonce": "52947210857365019284756102938475610293847561"
},
"backend_signature": "0x1a2b3c4d5e6f...65_byte_hex_encoded_eip712_signature",
"execution": {
"chain_id": 1001,
"contract": "0xbc925d8d6a3d30ccfe6fc4b6a23a7bcb6fee4ce1",
"method": "commitFirmQuote",
"value": "0",
"calldata": "0x1a2b3c4d...abi_encoded_commitFirmQuote_call"
}
},
"meta": { ... }
}
| Field | Type | Description |
|---|---|---|
backend_signature | string | Hex-encoded EIP-712 signature over the FirmQuote payload, signed by the Ratio backend |
execution.chain_id | integer | 8217 (production) or 1001 (sandbox) |
execution.contract | string | FxEngine proxy contract address |
execution.method | string | Always commitFirmQuote |
execution.value | string | Native token value to send. Currently always "0" |
execution.calldata | string | Hex-encoded calldata for commitFirmQuote(FirmQuote quote, bytes signature) |
quote object mirrors the on-chain FirmQuote struct:
| Field | Type | Description |
|---|---|---|
quote_id | string | bytes32 quote ID: keccak256 of the signer address, nonce and issue timestamp |
partner | string | Partner wallet address — must equal msg.sender when executing on-chain |
assets.from_asset_price / to_asset_price | string | USD prices scaled to 1e8 for contract validation |
attributes.amount_in | string | Full raw input amount including platform fees |
attributes.amount_out | string | Gross output amount before spread |
attributes.spread_bps | string | Spread envelope: base + volatility + liquidity + off_market + state_extra, rounded up. Excludes skew. |
attributes.skew_bps | string | Inventory skew, rounded away from zero. May be negative. |
fees | object | fixed_fee and variable_fee in input-token raw units; spread_fee in output-token raw units |
quote_expiry_seconds (currently 60s). After expiry, the on-chain contract will reject the calldata. Request a new firm quote at current rates.
| HTTP | Description |
|---|---|
400 | Invalid request, amount outside limits, insufficient liquidity |
401 | Authentication failed |
403 | Corridor or signer wallet not enabled for your credential |
409 | Duplicate client_ref or daily volume limit reached |
422 | Malformed request body (plain-text response) |
503 | Quoting temporarily unavailable |