openapi: 3.1.0
info:
  title: Private Broker API - Overview
  version: 1.0.0
  description: |
    # Broker Integration Overview

    This API enables institutional brokers to integrate with our order book exchange platform.

    ## Architecture

    ```mermaid
    sequenceDiagram
        participant Broker
        participant Gateway as API Gateway
        participant Engine as Order Book Engine
        participant MD as Market Data
        participant WS as WebSocket Stream
        
        Note over Broker,WS: Authentication (Keyed BLAKE2b)
        Note over Broker: Sign request with Keyed BLAKE2b-256<br/>Headers: PRE-ACCESS-KEY, PRE-ACCESS-SIGNATURE, PRE-ACCESS-TIMESTAMP
        
        Note over Broker,WS: Order Management (REST)
        Broker->>Gateway: POST /orders (create)<br/>+ Auth headers + Idempotency-Key
        Gateway->>Engine: Submit order
        Engine-->>Gateway: Order accepted
        Gateway-->>Broker: 201 Order created
        
        Broker->>Gateway: PATCH /orders/:id (replace)<br/>+ Auth headers + Idempotency-Key
        Gateway->>Engine: Modify order
        Engine-->>Gateway: Order modified
        Gateway-->>Broker: 201 Order updated
        
        Broker->>Gateway: DELETE /orders/:id (cancel)<br/>+ Auth headers + Idempotency-Key
        Gateway->>Engine: Cancel order
        Engine-->>Gateway: Order cancelled
        Gateway-->>Broker: 201 Order cancelled
        
        Note over Broker,WS: Real-time Streams (WebSocket)
        Broker->>WS: Connect /orders stream
        WS-->>Broker: Order updates (real-time)
        
        Broker->>WS: Connect /market-data stream
        WS-->>Broker: Book snapshots/diffs + Trades
        
        Note over Engine,MD: Internal Flow
        Engine->>MD: Publish events to WAL
        MD->>WS: Project market data
    ```

    ## Communication Patterns

    ### REST API
    - **Synchronous** request/response for order operations
    - **Idempotent** via `Idempotency-Key` header
    - **Atomic** operations with immediate feedback

    ### WebSocket Streams
    - **Real-time** order status updates
    - **Real-time** market data (order book + trades)
    - **Resumable** streams with sequence numbers
    - **Idempotent** delivery (client-side deduplication)

    ## Key Features

    - **Exactly-once semantics** via Write-Ahead Log (NATS JetStream)
    - **Deterministic processing** for reproducibility
    - **Low latency** order execution (p99 < 5ms)
    - **Market data** with monotonic sequence numbers per market
    - **Keyed BLAKE2b-256** authentication for secure API access

    ## API Specifications

    - **REST API**: See `./private-api-broker-openapi.yaml`
    - **WebSocket Streams**: See `./private-api-broker-asyncapi.yaml`
servers: []
paths: {}
components: {}