Reserve Pool Risk API Reference

The following API endpoints expose Reserve Pool risk state data to partner dashboards, internal monitoring systems, and operations tooling. All endpoints require Bearer token authentication as documented in the FX Engine.

GET /v1/reserve/risk-status — Current VaR Status

Returns the current risk assessment snapshot for all corridors. Use for real-time monitoring dashboards and ops tooling.

Request:

GET /v1/reserve/risk-status
Authorization: Bearer {token}

Response:

{
  "snapshot_time": "2026-02-27T10:05:00Z",
  "reserve_capital_usd": 4850000,
  "portfolio_var_usd": 142500,
  "portfolio_var_pct": 2.94,
  "overall_status": "NORMAL",
  "corridors": {
    "USD-IDR": {
      "inventory_units": 30000000,
      "waop": 16000,
      "oracle_mid": 16050,
      "gross_exposure_usd": 1875,
      "unrealised_pnl_usd": -3.12,
      "var_1d_usd": 1820,
      "var_pct_of_capital": 0.038,
      "concentration_pct": 12.4,
      "status": "NORMAL",
      "oldest_batch_age_hours": 4.2
    },
    "USD-SGD": {
      "status": "NORMAL"
    },
    "MYR-IDR": {
      "status": "PROTECT",
      "var_pct_of_capital": 5.8,
      "breach_type": "VAR_WARNING"
    }
  },
  "last_emergency_rfq": null
}

Response Fields:

Field	Type	Description
snapshot_time	ISO 8601	Timestamp of the snapshot used for this calculation
reserve_capital_usd	number	Total USD-equivalent value of all Reserve Pool assets
portfolio_var_usd	number	Portfolio VaR in USD (after diversification discount)
portfolio_var_pct	number	Portfolio VaR as percentage of reserve capital
overall_status	string	Worst status across all corridors: NORMAL, PROTECT, RESTRICT, HALT
corridors	object	Per-corridor breakdown with full risk metrics
last_emergency_rfq	object or null	Details of last emergency RFQ if one has occurred

GET /v1/reserve/batches — Open Rebalancing Batches

Returns all open rebalancing batches with their WAOP, accumulated inventory, unrealised PnL, and lifecycle status.

Request:

GET /v1/reserve/batches?corridor=USD-IDR&status=OPEN
Authorization: Bearer {token}

Query Parameters:

Parameter	Required	Description
corridor	No	Filter by corridor (USD-IDR, USD-SGD, MYR-IDR)
status	No	Filter by status: OPEN, CLOSED, EMERGENCY_CLEARED

Response:

{
  "batches": [
    {
      "batch_id": "BATCH-101",
      "corridor": "USD-IDR",
      "status": "OPEN",
      "inventory_units": 30000000,
      "waop": 16000,
      "current_oracle_mid": 16050,
      "unrealised_pnl_usd": -93.75,
      "gross_exposure_usd": 1875,
      "swap_count": 42,
      "opened_at": "2026-02-27T06:00:00Z",
      "oldest_swap_at": "2026-02-27T06:05:00Z"
    }
  ]
}

POST /v1/reserve/emergency-rfq — Manual Emergency RFQ Trigger

Allows the operations team to manually trigger an Emergency RFQ for a corridor without waiting for an automated threshold breach. Requires ops-level authentication scope.

Request:

POST /v1/reserve/emergency-rfq
Authorization: Bearer {ops_token}
Content-Type: application/json

{
  "corridor": "USD-IDR",
  "reason": "Manual risk reduction — large one-sided flow detected",
  "price_floor_override_bps": 75
}

Request Fields:

Field	Required	Description
corridor	Yes	Target corridor for emergency clearance
reason	Yes	Free-text reason for manual trigger (logged to audit trail)
price_floor_override_bps	No	Override default 50 bps tolerance. Must be between 10–300 bps.

Response:

{
  "rfq_id": "EMRFQ-2026-0227-001",
  "corridor": "USD-IDR",
  "status": "DISPATCHED",
  "total_inventory_units": 30000000,
  "waop": 16000,
  "price_floor": 15988,
  "timeout_seconds": 60,
  "mm_recipients": ["binance", "wintermute", "otc_partner_1"],
  "dispatched_at": "2026-02-27T10:15:00Z"
}

POST /v1/reserve/state-override — Manual State Override

Allows the operations team to manually set the FX Engine state for a corridor. Used for post-emergency recovery or pre-emptive risk management.

Request:

POST /v1/reserve/state-override
Authorization: Bearer {ops_token}
Content-Type: application/json

{
  "corridor": "USD-IDR",
  "target_state": "PROTECT",
  "reason": "Manual override post-emergency clearance",
  "override_duration_minutes": 60
}

Request Fields:

Field	Required	Description
corridor	Yes	Target corridor
target_state	Yes	NORMAL, PROTECT, RESTRICT, or HALT
reason	Yes	Free-text reason for override (logged to audit trail)
override_duration_minutes	No	Auto-revert to previous state after duration. Omit for permanent override.

Response:

{
  "corridor": "USD-IDR",
  "previous_state": "RESTRICT",
  "new_state": "PROTECT",
  "override_id": "OVERRIDE-2026-0227-003",
  "expires_at": "2026-02-27T11:15:00Z",
  "set_by": "ops_admin@ratio.com"
}

Error Codes

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