Getting started

The Broker API combines REST snapshots and commands with WebSocket change streams.

sequenceDiagram
    participant Client as Broker Client
    participant REST as REST API
    participant WS as WebSocket Streams

    Client->>WS: Connect to resumable streams
    Client->>REST: Load catalogue and state snapshots
    REST-->>Client: Events, markets, orders, positions
    WS-->>Client: Buffered changes
    Note over Client: Merge snapshots and newer stream updates

    Client->>REST: Submit command + Idempotency-Key
    REST-->>Client: Command accepted
    WS-->>Client: Order and accounting updates

Design rules

• REST sends commands and provides snapshots. WebSocket delivers changes. Use REST on startup and for reconciliation. Do not use tight REST polling loops for order state, positions, or the order book.
• Configuration, not constants. Read base URLs, access keys, secret keys, and account IDs from configuration. One broker can serve many accounts, so pass account_id to every account-scoped trading call.
• Decimals are objects. Every price, quantity, and amount is {units, nanos}. Parse these values into a decimal type; never convert them to binary floating point.
• Persist stream positions. Store the last applied seq separately for /orders, /accounting, and /events. Store md_seq separately for every subscribed market.
• Start in the sandbox. Use the sandbox servers first, then switch configured URLs when the integration is ready for production.