> ## Documentation Index > Fetch the complete documentation index at: https://docs.fairground.fi/llms.txt > Use this file to discover all available pages before exploring further. # GetOrderBook > Returns a simulated aggregated order-book depth for one market: bid and ask price levels, each bucketed by `tickSize` and sorted toward the best price. Resolved by `market_id` or `market_symbol`. ## OpenAPI ````yaml /developers/api-reference/openapi.yaml post /orderbook_service.v1.OrderBookService/GetOrderBook openapi: 3.1.0 info: title: Fairground.Fi API description: | API for the Fairground Perpetuals trading platform. This API uses ConnectRPC which accepts JSON over HTTP POST requests. All service endpoints follow the pattern: `/package.ServiceName/MethodName` version: 1.0.0 contact: name: Forte Service Company url: https://github.com/Forte-Service-Company-Ltd/perpetuals-api-server license: name: Proprietary identifier: UNLICENSED servers: - url: https://api.fairground.fi description: Production API server security: - bearerAuth: [] tags: - name: Trades description: Wallet trade/fill history - name: Markets description: Market configuration and summary endpoints - name: Orderbook description: Orderbook data retrieval - name: Orders description: Order management operations - name: Portfolio description: Aggregated per-wallet portfolio data - name: Positions description: Position management operations - name: Prices description: Oracle price and historical price data paths: /orderbook_service.v1.OrderBookService/GetOrderBook: post: tags: - Orderbook summary: GetOrderBook description: >- Returns a simulated aggregated order-book depth for one market: bid and ask price levels, each bucketed by `tickSize` and sorted toward the best price. Resolved by `market_id` or `market_symbol`. operationId: orderbook_service.v1.OrderBookService.GetOrderBook parameters: - name: Connect-Protocol-Version in: header required: true schema: $ref: '#/components/schemas/connect-protocol-version' - name: Connect-Timeout-Ms in: header schema: $ref: '#/components/schemas/connect-timeout-header' requestBody: content: application/json: schema: $ref: '#/components/schemas/orderbook_service.v1.GetOrderBookRequest' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/orderbook_service.v1.GetOrderBookResponse' example: orderBook: marketId: '1' timestamp: '2026-07-11T14:32:07Z' pageSize: 50 offset: 0 totalOrderCount: 214 levels: 10 tickSize: 10 sizeInUsd: true book: bids: - price: 65400 size: 120000 orderCount: 6 cumulativeTotal: 120000 - price: 65390 size: 85000 orderCount: 4 cumulativeTotal: 205000 asks: - price: 65430 size: 95000 orderCount: 5 cumulativeTotal: 95000 - price: 65440 size: 60000 orderCount: 3 cumulativeTotal: 155000 components: schemas: connect-protocol-version: type: number title: Connect-Protocol-Version enum: - 1 description: Define the version of the Connect protocol. If omitted, use 1. const: 1 default: 1 connect-timeout-header: type: number title: Connect-Timeout-Ms description: Define the timeout, in ms orderbook_service.v1.GetOrderBookRequest: type: object properties: market: description: >- Market to fetch the order book for, by `market_id` or `market_symbol`. oneOf: - type: object title: market_id properties: marketId: type: string format: int64 title: market_id required: - marketId additionalProperties: false - type: object title: market_symbol properties: marketSymbol: $ref: '#/components/schemas/base_objects.v1.MarketSymbol' title: market_symbol required: - marketSymbol additionalProperties: false tickSize: type: number title: tickSize format: float description: |- Price bucket size to group orders into levels. `0` disables bucketing. Otherwise must be a power-of-ten multiple of the market's minimum tick size (`1 / 10^tickDecimals`, from that market's config) — e.g. `0.01`, `0.1`, `1`, `10`. A value below the market's minimum tick is clamped up to that minimum rather than rejected. Any other value (not a power-of-ten step, or negative) returns `INVALID_ARGUMENT`. sizeInUsd: type: boolean title: size_in_usd description: >- Whether to express level sizes in USD notional (`true`) or the underlying asset's units (`false`). levels: type: integer title: levels format: int32 description: >- Maximum number of price levels to return per side. `0` or omitted returns all levels. limit: type: - integer - 'null' title: limit description: >- Maximum number of underlying orders to aggregate before building levels. Defaults to 50. offset: type: - integer - 'null' title: offset description: Number of underlying orders to skip before aggregating. totalOrderCount: type: - integer - 'null' title: total_order_count description: Accepted but currently ignored. title: GetOrderBookRequest required: - market additionalProperties: false orderbook_service.v1.GetOrderBookResponse: type: object properties: orderBook: $ref: '#/components/schemas/base_objects.v1.OrderBook' title: order_book description: Aggregated order book for the requested market. title: GetOrderBookResponse additionalProperties: false base_objects.v1.MarketSymbol: type: object properties: assetSymbol: type: string title: asset_symbol description: |- Underlying asset symbol, e.g. `"BTC"`. Matched case-insensitively and trimmed. quoteSymbol: type: string title: quote_symbol description: |- Quote symbol, e.g. `"PERP"`. Technically optional, but omitting it looks up a market named exactly by `assetSymbol` alone (e.g. `"BTC"`) rather than `"BTC-PERP"`, which will not resolve to any real market. In practice, always set this. title: MarketSymbol additionalProperties: false base_objects.v1.OrderBook: type: object properties: marketId: type: string title: market_id format: int64 description: On-chain market identifier. timestamp: $ref: '#/components/schemas/google.protobuf.Timestamp' title: timestamp description: Time this order book snapshot was generated. pageSize: type: - integer - 'null' title: page_size description: Effective `limit` used for this query (after defaulting to 50). offset: type: - integer - 'null' title: offset description: Effective `offset` used for this query. totalOrderCount: type: integer title: total_order_count description: >- Total number of underlying orders aggregated into `book` (both sides combined), before `levels`/pagination are applied. levels: type: integer title: levels description: >- Number of price levels actually returned per side (the larger of the two sides' lengths after any `levels` cap was applied). tickSize: type: number title: tick_size format: float description: >- Price bucket size used to group orders into levels, echoed back from the request. `0` means no bucketing was applied. sizeInUsd: type: boolean title: size_in_usd description: >- Whether `book` sizes are expressed in USD notional (`true`) or the underlying asset's units (`false`), echoed back from the request's `sizeInUsd`. book: $ref: '#/components/schemas/base_objects.v1.Books' title: book description: Aggregated bid and ask price levels. title: OrderBook additionalProperties: false google.protobuf.Timestamp: type: string examples: - '2023-01-15T01:30:15.01Z' - '2024-12-25T12:00:00Z' format: date-time base_objects.v1.Books: type: object properties: bids: type: array items: $ref: '#/components/schemas/base_objects.v1.Tick' title: bids description: Bid-side price levels, descending by price, best bid first. asks: type: array items: $ref: '#/components/schemas/base_objects.v1.Tick' title: asks description: Ask-side price levels, ascending by price, best ask first. title: Books additionalProperties: false base_objects.v1.Tick: type: object properties: price: type: number title: price format: float description: >- Price for this level, in quote asset units. Bucketed to the request's `tickSize` when one is set (rounded down for bids, rounded up for asks). size: type: number title: size format: float description: >- Aggregated remaining (unfilled) size at this price level in quote asset units notional or the underlying asset's units, depending on the request's `sizeInUsd` flag. orderCount: type: integer title: order_count description: Number of orders aggregated into this price level. cumulativeTotal: type: number title: cumulative_total format: float description: |- Cumulative size from the best price up to and including this level, in the same units as `size`. title: Tick additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````