---
title: "GetOrderBook"
method: POST
path: "/orderbook_service.v1.OrderBookService/GetOrderBook"
tags: ["Orderbook"]
---

# GetOrderBook

`POST /orderbook_service.v1.OrderBookService/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`.

## Headers

- `Connect-Protocol-Version` 1, required — Define the version of the Connect protocol. If omitted, use 1.
- `Connect-Timeout-Ms` number — Define the timeout, in ms

## Request body

- OrderbookServiceV1GetOrderBookRequest
  - `market` union, required — Market to fetch the order book for, by `market_id` or `market_symbol`.
    - object
      - `marketId` string, int64, required
    - object
      - `marketSymbol` BaseObjectsV1MarketSymbol, required
        - `assetSymbol` string — Underlying asset symbol, e.g. `"BTC"`. Matched case-insensitively and trimmed.
        - `quoteSymbol` string — 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.
  - `tickSize` number, float — 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` boolean — Whether to express level sizes in USD notional (`true`) or the underlying asset's units (`false`).
  - `levels` integer — Maximum number of price levels to return per side. `0` or omitted returns all levels.
  - `limit` integer, nullable — Maximum number of underlying orders to aggregate before building levels. Defaults to 50.
  - `offset` integer, nullable — Number of underlying orders to skip before aggregating.
  - `totalOrderCount` integer, nullable — Accepted but currently ignored.

## Response `200`

Success

- OrderbookServiceV1GetOrderBookResponse
  - `orderBook` BaseObjectsV1OrderBook
    - `marketId` string, int64 — On-chain market identifier.
    - `timestamp` string, date-time
    - `pageSize` integer, nullable — Effective `limit` used for this query (after defaulting to 50).
    - `offset` integer, nullable — Effective `offset` used for this query.
    - `totalOrderCount` integer — Total number of underlying orders aggregated into `book` (both sides combined), before `levels`/pagination are applied.
    - `levels` integer — Number of price levels actually returned per side (the larger of the two sides' lengths after any `levels` cap was applied).
    - `tickSize` number, float — Price bucket size used to group orders into levels, echoed back from the request. `0` means no bucketing was applied.
    - `sizeInUsd` boolean — Whether `book` sizes are expressed in USD notional (`true`) or the underlying asset's units (`false`), echoed back from the request's `sizeInUsd`.
    - `book` BaseObjectsV1Books
      - `bids` BaseObjectsV1Tick[] — Bid-side price levels, descending by price, best bid first.
        - `price` number, float — 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` number, float — 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` integer — Number of orders aggregated into this price level.
        - `cumulativeTotal` number, float — Cumulative size from the best price up to and including this level, in the same units as `size`.
      - `asks` BaseObjectsV1Tick[] — Ask-side price levels, ascending by price, best ask first.
        - `price` number, float — 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` number, float — 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` integer — Number of orders aggregated into this price level.
        - `cumulativeTotal` number, float — Cumulative size from the best price up to and including this level, in the same units as `size`.

---

[API](https://skmtc.dev/fairground/apis/fairground-fi-api.md) · [All operations](https://skmtc.dev/fairground/apis/fairground-fi-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fairground/fairground-fi-api/revisions/be66e6dc0ac0/schema)