API Reference — FX Engine

All requests require authentication via Bearer token issued during partner onboarding.

Authentication

Header	Value	Description
Authorization	Bearer {api_key}	API key issued during partner onboarding
Content-Type	application/json	All bodies are JSON
X-Partner-ID	{partner_id}	Required for fee routing and audit trail

GET /v1/quote — Indicative Price

Returns a wide reference price. No inventory reservation, no expiry.

// Request
GET /v1/quote?pair=USD-IDR&side=BUY&amount=10000

// Response
{
  "pair": "USD-IDR",
  "side": "BUY",
  "indicative_rate": 16020.50,
  "mid": 15980.00,
  "spread_bps": 25,
  "timestamp": "2026-02-27T10:00:00Z",
  "quote_type": "INDICATIVE"
}

POST /v1/firm-quote — Executable Quote

Returns a firm BID/ASK with hard expiry and inventory reservation.

Field	Type	Required	Description
pair	string	Yes	Currency pair
side	string	Yes	BUY or SELL
amount	number	Yes	Notional in source currency
quote_type	string	Yes	Must be FIRM
client_ref	string	No	Partner-side reference for reconciliation

// Request
{
  "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
  }
}

execution_path field

When a trade is routed to External RFQ due to size, this field returns EXTERNAL_RFQ instead of DIRECT. The requester is informed transparently that the trade will be filled via an external market maker.

Response Fields

Field	Type	Description
quote_id	string	Unique quote identifier
pair	string	Currency pair
side	string	Trade direction
amount	number	Notional in source currency
bid	number	Bid price
ask	number	Ask price
adjusted_mid	number	Oracle mid after skew adjustment
spread_bps	number	Total spread in basis points
expiry_timestamp	string	ISO 8601 quote expiry
max_size	number	Maximum executable size
allowed_direction	string	Permitted trade direction
state_flag	string	Current system state for corridor
quote_type	string	FIRM
execution_path	string	DIRECT or EXTERNAL_RFQ
fee_breakdown	object	Resolved fee tier and all fee components. See Volume-Tiered Fee Schedule.
fee_breakdown.tier	string	Tier name applied (e.g., "MICRO", "SMALL", "MEDIUM")
fee_breakdown.fixed_fee	number	Fixed fee in source currency
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 fee tier
fee_breakdown.total_spread_bps	number	Total spread including dynamic components
fee_breakdown.total_fee_usd	number	Total platform fee (fixed + variable) in USD
fee_breakdown.amount_to_convert	number	Source amount after fee deduction
fee_breakdown.is_partner_override	boolean	Whether partner-specific rates were applied

POST /v1/execute — Execute a Firm Quote

Submits a firm quote for on-chain execution. Atomic and irreversible once confirmed.

Field	Type	Required	Description
quote_id	string	Yes	Quote ID from firm-quote
amount	number	Yes	Must be ≤ quote max_size
destination_address	string	Yes	On-chain wallet for output stablecoin
client_ref	string	No	Partner-side reference

// Response
{
  "execution_id": "EX-9910-USD-IDR",
  "quote_id": "QT-8821-USD-IDR",
  "status": "SETTLED",
  "filled_rate": 16020.00,
  "source_amount": 50000,
  "destination_amount": 801000000,
  "platform_fee": 52.00,
  "batch_id": "BATCH-101",
  "tx_hash": "0xKAIA...ABC",
  "settled_at": "2026-02-27T10:00:32Z",
  "execution_path": "DIRECT",
  "state_flag": "NORMAL"
}

GET /v1/system/state — Current System State

{
  "system_state": "NORMAL",
  "corridors": {
    "USD-IDR": { "state": "NORMAL", "allowed_directions": ["BUY","SELL"], "oracle_age_ms": 380 },
    "USD-SGD": { "state": "NORMAL", "allowed_directions": ["BUY","SELL"], "oracle_age_ms": 210 },
    "MYR-IDR": { "state": "PROTECT", "allowed_directions": ["BUY","SELL"], "oracle_age_ms": 520 }
  }
}

Error Codes

For the complete error code reference, see the Unified Error Codes page.