Trading API Overview

The public API is the front door. Users, simulator runs, and Bot Arena traffic all come through versioned /api/v1 routes instead of reaching into engine internals or database tables. That keeps the system inspectable: each accepted command has identity, idempotency, status, and trace data attached.

Reef exposes two product-facing API families:

• venue intake and trading information for orders, command status, participant order state, executions, trade tape, current market data, and scenario settlement evidence
• admin/data for operator-approved administration plus intraday and historical data access

Internal service/control interfaces are not product APIs. They can change faster and should sit behind gRPC/protobuf, durable messaging, or gateway-backed admin/data routes with auth, authorization, audit, and versioning. Canonical policy: docs/API_SURFACE_POLICY.md.

Required Headers (Writes)

Header	Required	Purpose
X-Client-Id	yes	Client identity; missing → 401 CLIENT_ID_REQUIRED
Idempotency-Key	yes	Deduplication key, scoped to (clientId, route, idempotencyKey)
Authorization	per auth hook config	Bearer token/API key, validated by the configured auth hook
X-Correlation-Id	optional	Propagated correlation ID for tracing; generated if absent

What Happens Before A Write Is Accepted

Before an order can enter the venue, Reef checks whether it is well-formed, allowed for the actor, inside protective controls, and safe for the configured risk policy. Only then does it reserve idempotency and publish or capture the command durably.

A rejected command stops early and does not reserve stream intake or publish durable work. A 202 Accepted response means durable intake acknowledged the command; it does not mean matching has finished yet.

Error Envelope

{
  "code": "VALIDATION_ERROR",
  "message": "...",
  "correlationId": "..."
}

Domain rejections (e.g. a business-rule reject) are distinguished from transport/system failures (e.g. 503 runtime unavailable) by status code and code field.

Command Processing Modes

The runtime supports multiple internal processing modes behind the same external contract: sync-result (deterministic compatibility mode), captured-ack (Postgres fallback/A-B baseline), stream-ack (durable stream-backed intake), and accepted-async (diagnostic/no-DB ceiling mode). The active high-throughput venue-core path is Redpanda/Kafka-compatible durable publish, matching-engine direct partition consumption, durable VenueEventBatch publication, and asynchronous materialization/projection. JetStream remains a fallback/comparison provider.

Clients never need to know which provider is active. The public contract stays stable: a mutation returns either a synchronous result or a 202 status pointer, and 202 Accepted always means the configured durable intake mechanism acknowledged the command before the response.

Routes At A Glance

Route	Method	Purpose
/api/v1/orders/submit	POST	Submit a new order
/api/v1/orders/modify	POST	Modify quantity/price of a resting order
/api/v1/orders/cancel	POST	Cancel an order
/api/v1/orders/cancel-by-client-order	POST	Resolve a client-order cancel outside the hot path, then emit a normal cancel
/api/v1/orders/lifecycle-state	POST	Rebuild order lifecycle projection
/api/v1/orders/current	GET	Participant-scoped current own-order state
/api/v1/orders/history	GET	Participant-scoped own-order history
/api/v1/orders/fills	GET	Participant-scoped fills
/api/v1/market-data/snapshots/{instrumentId}	GET	Top-of-book snapshot
/api/v1/market-data/snapshots	POST	Refresh snapshot projection
/api/v1/market-data/depth/{instrumentId}	GET	Bounded depth snapshot
/api/v1/market-data/trades/{instrumentId}	GET	Public trade tape
/api/v1/market-data/bars/{instrumentId}	GET	Intraday OHLCV bars
/api/v1/data/availability	GET	Read-surface availability and freshness inventory
/api/v1/settlement/facts/{scenarioRunId}	GET	Append-only settlement facts for one scenario run
/api/v1/settlement/obligations/{scenarioRunId}	GET	Current settlement obligation state projected from facts
/api/v1/settlement/ledger/{scenarioRunId}	GET	Replayable balances and settlement proof totals
/api/v1/settlement/proof/{scenarioRunId}	GET	Replayable settlement finality proof
/api/v1/settlement/score/{scenarioRunId}	GET	Scenario settlement score/proof summary
/api/v1/commands/{commandId}	GET	Command status lookup

/internal/* routes exist only as local/migration operator tooling and diagnostics — see Internal & Admin Routes. They are not part of the public client contract and must not be exposed raw outside private operator networks.

Learn More

• docs/steering/external-api-boundary.md — full boundary steering (source for this page)
• docs/CURRENT_STATUS.md — which processing mode is active by default today