{"openapi":"3.1.0","info":{"title":"Private Broker API - Overview","version":"1.0.0","description":"# Broker Integration Overview\n\nThis API enables institutional brokers to integrate with our order book exchange platform.\n\n## Architecture\n\n```mermaid\nsequenceDiagram\n    participant Broker\n    participant Gateway as API Gateway\n    participant Engine as Order Book Engine\n    participant MD as Market Data\n    participant WS as WebSocket Stream\n    \n    Note over Broker,WS: Authentication (Keyed BLAKE2b)\n    Note over Broker: Sign request with Keyed BLAKE2b-256\u003cbr/\u003eHeaders: PRE-ACCESS-KEY, PRE-ACCESS-SIGNATURE, PRE-ACCESS-TIMESTAMP\n    \n    Note over Broker,WS: Order Management (REST)\n    Broker-\u003e\u003eGateway: POST /orders (create)\u003cbr/\u003e+ Auth headers + Idempotency-Key\n    Gateway-\u003e\u003eEngine: Submit order\n    Engine--\u003e\u003eGateway: Order accepted\n    Gateway--\u003e\u003eBroker: 201 Order created\n    \n    Broker-\u003e\u003eGateway: PATCH /orders/:id (replace)\u003cbr/\u003e+ Auth headers + Idempotency-Key\n    Gateway-\u003e\u003eEngine: Modify order\n    Engine--\u003e\u003eGateway: Order modified\n    Gateway--\u003e\u003eBroker: 201 Order updated\n    \n    Broker-\u003e\u003eGateway: DELETE /orders/:id (cancel)\u003cbr/\u003e+ Auth headers + Idempotency-Key\n    Gateway-\u003e\u003eEngine: Cancel order\n    Engine--\u003e\u003eGateway: Order cancelled\n    Gateway--\u003e\u003eBroker: 201 Order cancelled\n    \n    Note over Broker,WS: Real-time Streams (WebSocket)\n    Broker-\u003e\u003eWS: Connect /orders stream\n    WS--\u003e\u003eBroker: Order updates (real-time)\n    \n    Broker-\u003e\u003eWS: Connect /market-data stream\n    WS--\u003e\u003eBroker: Book snapshots/diffs + Trades\n    \n    Note over Engine,MD: Internal Flow\n    Engine-\u003e\u003eMD: Publish events to WAL\n    MD-\u003e\u003eWS: Project market data\n```\n\n## Communication Patterns\n\n### REST API\n- **Synchronous** request/response for order operations\n- **Idempotent** via `Idempotency-Key` header\n- **Atomic** operations with immediate feedback\n\n### WebSocket Streams\n- **Real-time** order status updates\n- **Real-time** market data (order book + trades)\n- **Resumable** streams with sequence numbers\n- **Idempotent** delivery (client-side deduplication)\n\n## Key Features\n\n- **Exactly-once semantics** via Write-Ahead Log (NATS JetStream)\n- **Deterministic processing** for reproducibility\n- **Low latency** order execution (p99 \u003c 5ms)\n- **Market data** with monotonic sequence numbers per market\n- **Keyed BLAKE2b-256** authentication for secure API access\n\n## API Specifications\n\n- **REST API**: See `./private-api-broker-openapi.yaml`\n- **WebSocket Streams**: See `./private-api-broker-asyncapi.yaml`\n"},"servers":[],"paths":{},"components":{}}