API

Binance Spot-shaped, with the changes in decisions.md D-6. The generated OpenAPI document (/v1/openapi.json, committed at docs/openapi.json) is the exact contract; this page is the map. Signing is in auth.md.

Hosts

Conventions

• GET and DELETE take query parameters; POST, PUT and PATCH take a JSON body.
• Amounts, prices and quantities are decimal strings at the asset's precision ("0.00100000"). Ids are numbers. Times are ms (X-ZAAR-TIME-UNIT: MICROSECOND for µs is reserved, not yet served).
• Enums are UPPER_SNAKE strings, as in Binance (LIMIT, GTC, PARTIALLY_FILLED).
• Errors: HTTP 4xx/5xx with {"code": -1121, "msg": "Invalid symbol."}. Codes follow Binance's numbering where the meaning matches (see zaar-api/src/error.rs, published in the docs).
• Rate limits: request weight per key and per IP (token buckets refilled continuously, default 6000 per minute each; exchangeInfo weighs 20, depth 5–250 by limit, history lists 20–25, most others 1), reported in X-ZAAR-USED-WEIGHT-1M; over the limit → HTTP 429, -1003.
• Every response carries X-ZAAR-VERSION (the build's git sha, dev locally).
• Security type of each endpoint: NONE, or the scope it needs (READ, TRADE, …). Signed endpoints act on the account in X-ZAAR-ACCOUNT; a user key whose user has exactly one account may omit it.
• Fee rates and shares are decimal fractions with 6 places ("0.001000" = 0.1%).
• Ticker endpoints return one object when symbol is given, else an array of every market.
• History endpoints (trades, historicalTrades, klines, ticker/*, allOrders, myTrades, transfers, closed orders in GET /v1/order) read the SQLite projection. They wait (up to 2 s) for it to include every entry that was durable when the request arrived, so a client reads its own writes.

Endpoints

General and market data (NONE)

Trading (TRADE, READ)

Accounts and transfers (READ, TRANSFER) — new vs Binance

Org (USERS_MANAGE, KEYS_MANAGE, ORG_ADMIN) — new

Admin (NETWORK_ADMIN) — new

WebSocket /v1/ws

JSON text frames, Binance-style. Requests:

{"id": 1, "method": "SUBSCRIBE", "params": ["btc-usd@trade", "btc-usd@depth", "btc-usd@kline_1m"]}
{"id": 2, "method": "UNSUBSCRIBE", "params": ["btc-usd@trade"]}
{"id": 3, "method": "LIST_SUBSCRIPTIONS"}
{"id": 4, "method": "session.logon", "params": {"apiKey": "...", "timestamp": 0, "signature": "..."}}
{"id": 5, "method": "userDataStream.subscribe", "params": {"account": 7}}

Also session.status, session.logout and userDataStream.unsubscribe {subscriptionId?}. Replies: {"id", "result"} for the stream methods, {"id", "status": 200, "result"} for session.* and userDataStream.*; any error is {"id", "status", "error": {"code", "msg"}}. session.logon signs the request payload of auth.md with METHOD = WS, path = /v1/ws and empty query, account and body; userDataStream.subscribe needs READ over the account (decided by the core).

Market streams arrive as {"stream": "btc-usd@trade", "data": {...}}. Symbols are lowercase in stream names.

Depth sync. Update ids are journal sequence numbers, so they are not contiguous per market: U/u are the first/last seq that changed this book in the event and pu is the u of the previous event for the same market (as on Binance futures). To keep a local book: open the stream, fetch GET /v1/depth (its lastUpdateId = L), drop events with u <= L; the first applied event must have pu <= L and each later one pu = the previous u; otherwise refetch.

User stream events arrive as {"subscriptionId": 0, "event": {...}}, in Binance shapes plus A (the account id): executionReport (every order change; x = NEW, TRADE, CANCELED, EXPIRED, REJECTED), outboundAccountPosition (balances touched by a command), balanceUpdate (mint, burn, transfer, import; signed d) and transfer (ZAAR: the transfer record for those kinds).

Each connection has a bounded outgoing queue; a client that cannot keep up is disconnected and must reconnect and resync. The server pings every 20 s and closes connections silent for 60 s.

Reserved for v1.1: order placement over WebSocket (order.place etc.), amend keep-priority, order lists, SBE binary encoding.