> ## Documentation Index > Fetch the complete documentation index at: https://docs.omnibook.xyz/llms.txt > Use this file to discover all available pages before exploring further. # L2 orderbook (bids-only, both sides) > Bids only, both sides (api.md §4.4). `yes` = YES bids at YES-space ticks; `no` = NO bids at NO-space ticks; each best-first. A NO bid at `t` *is* the YES ask at `100 − t` — asks are derivable, never sent. Level entries are `[tick, aggregate_qty]`; per-order data is never published. ## OpenAPI ````yaml /api-spec/venue-openapi.yaml get /v1/markets/{market_id}/orderbook openapi: 3.1.0 info: title: Exchange API — REST lane version: 1.0.0 summary: Client-facing REST surface for the binary prediction-market exchange. description: > The client-visible REST contract of the API lane — the normative source is `specs/api.md`; the request-ingress mechanics are in `specs/gateway.md`. ## Conventions (api.md §1) - **Versioning:** every path is under `/v1/`. Unknown *request* fields are rejected (`400 unknown_field`); clients MUST ignore unknown *response* fields (additive changes are non-breaking). - **Numbers:** prices are integer **ticks** (1–99, cents); quantities are integer shares; money is integer cents. u64-domain values (`order_id`, `client_order_id`, `seq`, cents amounts, timestamps) render as decimal **strings**; u32-and-below render as JSON numbers. Floats never appear. - **Timestamps:** `ts`/`*_ts` fields are nanoseconds since the Unix epoch as decimal strings — the sequencer's stamp, untranslated. - **`as_of_seq`:** every read response carries the stream sequence number its answer is current as of. Two reads with the same `as_of_seq` describe one consistent instant. - **Pagination:** list endpoints take `limit` (default 100, max 1000) and an opaque `cursor`; responses echo `cursor` for the next page (empty string when exhausted). ## Authentication (api.md §2, gateway.md §4–§5) Every request — there is no anonymous surface — carries three headers: `DX-ACCESS-KEY`, `DX-ACCESS-TIMESTAMP` (Unix ms), and `DX-ACCESS-SIGNATURE` (base64 HMAC-SHA256 over the canonical string `timestamp + "\n" + METHOD + "\n" + path?query + "\n" + body`, ±5000 ms replay window). Keys carry scopes `read` (GETs) and `trade` (order/withdrawal mutations); the required scope per operation is given in `x-required-scope`. Rate limits are per-key token buckets (read 100/s +200 burst; write 50/s +100 burst) answered with `429` + `Retry-After`. ## Execution outcomes are not errors (api.md §5) Post-only cross, FOK infeasible, IOC remainder, STP and max-cost-infeasible arrive as a **successful** placement response with `status: "canceled"` and a `reason` — they are the order's history, not a protocol failure. Only the reject taxonomy in §5 maps to non-2xx. x-other-lanes: websocket: endpoint: wss://{host}/v1/ws spec: specs/api.md §7, specs/ws.md note: >- AsyncAPI territory — subscribe/unsubscribe command envelope, public channels (orderbook_delta, trades, ticker) and the private `user` channel with snapshot+resume. Not modelled in this OpenAPI document. mcp: endpoint: POST /v1/mcp spec: specs/mcp.md note: >- JSON-RPC 2.0 agent lane exposing the same reads/writes as MCP tools. Described by its own tool schema, not OpenAPI. servers: - url: https://api.raeth.exchange description: >- Production. Every request is authenticated — there is no anonymous access, including market data. See Authentication. security: - DxAccessKey: [] DxAccessTimestamp: [] DxAccessSignature: [] tags: - name: Exchange description: Exchange-wide control state (api.md §3). - name: Markets description: Market metadata, orderbooks and public tape (api.md §4). - name: Portfolio (read) description: Key-scoped balance, positions, fills and orders (api.md §6.1–6.3, 6.6). - name: Orders (write) description: >- Order placement, cancel, decrease, batch and mass-cancel (api.md §6.5–6.10). - name: Funding description: Deposit address and withdrawals (api.md §6A). - name: Admin description: > Control-plane operator actions (specs/admin.md). Served on a SEPARATE listener from every path above — see the operation's own `servers` override; the top-level `servers` block does not reach it. externalDocs: description: Normative API surface specification (REST + WebSocket). url: specs/api.md paths: /v1/markets/{market_id}/orderbook: get: tags: - Markets summary: L2 orderbook (bids-only, both sides) description: | Bids only, both sides (api.md §4.4). `yes` = YES bids at YES-space ticks; `no` = NO bids at NO-space ticks; each best-first. A NO bid at `t` *is* the YES ask at `100 − t` — asks are derivable, never sent. Level entries are `[tick, aggregate_qty]`; per-order data is never published. operationId: getOrderbook parameters: - $ref: '#/components/parameters/MarketIdPath' - name: depth in: query description: Levels per side. required: false schema: type: integer default: 10 minimum: 1 maximum: 99 responses: '200': description: The L2 book (api.md §4.4). content: application/json: schema: $ref: '#/components/schemas/Orderbook' example: market_id: 1 'yes': - - 47 - 1200 - - 46 - 800 'no': - - 52 - 950 - - 51 - 400 as_of_seq: '182390' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/MissingScope' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' components: parameters: MarketIdPath: name: market_id in: path required: true schema: type: integer schemas: Orderbook: type: object description: Bids only, both sides (api.md §4.4). properties: market_id: type: integer 'yes': type: array items: $ref: '#/components/schemas/OrderbookLevel' description: YES bids at YES-space ticks best-first: null 'no': type: array items: $ref: '#/components/schemas/OrderbookLevel' description: NO bids at NO-space ticks best-first: null as_of_seq: $ref: '#/components/schemas/U64String' required: - market_id - 'yes' - 'no' - as_of_seq OrderbookLevel: type: array description: '[tick, aggregate_qty] — qty is a JSON number (per golden vector).' prefixItems: - $ref: '#/components/schemas/Tick' - type: integer description: aggregate shares at the level minItems: 2 maxItems: 2 U64String: type: string description: A u64-domain value rendered as a decimal string (api.md §1). pattern: ^[0-9]+$ example: '182390' ErrorEnvelope: type: object description: The uniform error body (api.md §5). properties: error: type: object properties: code: type: string description: lowercase snake_case reject/gateway code. num: type: - integer - 'null' description: >- The u16 reject code; non-null iff origin is `core` or `port` drawing from the shared registry (funding-port rejects carry a null num). origin: type: string enum: - core - port - gateway message: type: string details: type: - object - 'null' required: - code - num - origin - message - details required: - error responses: Unauthorized: description: Missing or invalid signature (`unauthorized`, origin gateway). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: unauthorized num: null origin: gateway message: unauthorized details: null MissingScope: description: >- Key lacks the required scope (`missing_scope`), or a risk reject (`per_market_limit`, `user_suspended`, `reduce_only_violation`, …). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: missing_scope num: null origin: gateway message: missing_scope details: null NotFound: description: >- `market_not_found`, `unknown_order`, `unknown_withdrawal`, or `not_found`. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: unknown_order num: 260 origin: core message: unknown_order details: null RateLimited: description: Token bucket empty (`rate_limited`). Retry after the header interval. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: rate_limited num: null origin: gateway message: rate_limited details: null securitySchemes: DxAccessKey: type: apiKey in: header name: DX-ACCESS-KEY description: The API key id (decimal string). DxAccessTimestamp: type: apiKey in: header name: DX-ACCESS-TIMESTAMP description: Request timestamp, Unix milliseconds (decimal). ±5000 ms replay window. DxAccessSignature: type: apiKey in: header name: DX-ACCESS-SIGNATURE description: > base64(HMAC-SHA256(secret, "timestamp\nMETHOD\npath?query\nbody")). For the WS handshake the body is empty and the path is `/v1/ws`. ````