# Getting started

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

```mermaid
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.