GET /v1/orderbook

Retrieve historical order book snapshots with optional incremental diffs.

Min Tier: Free | Credits: 50 base + 5 per row returned

Parameters

Parameter	Type	Required	Default	Description
`api-key`	string	Yes	—	Your API key.
`symbol`	string	Yes	—	Asset symbol (e.g. `BTC`, `ETH`).
`source`	string	Yes	—	Data source. One of `binance_spot`, `binance_futures`, `hyperliquid`, `kalshi`, `polymarket`.
`start`	string	No	—	ISO 8601 start time (inclusive).
`end`	string	No	—	ISO 8601 end time (exclusive).
`depth`	integer	No	20	Number of price levels per side. Range: 1–100.
`limit`	integer	No	100	Number of snapshots to return. Range: 1–1000.
`after`	string	No	—	Cursor for pagination. Pass `meta.next_cursor` from a previous response.
`include_diffs`	boolean	No	false	Include incremental diffs between snapshots. Requires Business tier.

Response

Field	Type	Description	Sources
`timestamp`	string	ISO 8601 snapshot time.	All
`symbol`	string	Asset symbol.	All
`source`	string	Data source identifier.	All
`mid_price`	number	Midpoint between best bid and best ask.	All
`spread`	number	Absolute spread (best ask − best bid).	All
`bids`	array	Array of `[price, size]` tuples, sorted descending by price.	All
`asks`	array	Array of `[price, size]` tuples, sorted ascending by price.	All
`imbalance`	number	Order book imbalance ratio. Positive values indicate bid-heavy books. Range: −1 to 1.	All
`is_full_snapshot`	boolean	`true` for full snapshots, `false` for incremental diffs.	All
`diff_since_last`	object \| null	Incremental changes since the previous snapshot. Only present when `include_diffs=true`.	All (Business)

The diff_since_last object contains:

Field	Type	Description
`bids_added`	array	New or updated bid levels as `[price, size]` tuples.
`bids_removed`	array	Removed bid price levels.
`asks_added`	array	New or updated ask levels as `[price, size]` tuples.
`asks_removed`	array	Removed ask price levels.

Response Headers

Header	Description
`X-Credits-Used`	Credits consumed by this request.
`X-Credits-Remaining`	Credits remaining in your billing cycle.
`X-Rows-Returned`	Number of snapshots in the response.
`X-Rows-Capped`	`true` if the result set was truncated by your plan's row limit.

Example

cURL

curl "https://kwery-api.com/v1/orderbook?api-key=YOUR_KEY&symbol=BTC&source=binance_futures&depth=10&start=2026-03-08T12:00:00Z&end=2026-03-08T13:00:00Z&limit=5"

Python

import requests

resp = requests.get("https://kwery-api.com/v1/orderbook", params={
    "api-key": "YOUR_KEY",
    "symbol": "BTC",
    "source": "binance_futures",
    "depth": 10,
    "start": "2026-03-08T12:00:00Z",
    "end": "2026-03-08T13:00:00Z",
    "limit": 5,
})
data = resp.json()

TypeScript

const params = new URLSearchParams({
  "api-key": "YOUR_KEY",
  "symbol": "BTC",
  "source": "binance_futures",
  "depth": "10",
  "start": "2026-03-08T12:00:00Z",
  "end": "2026-03-08T13:00:00Z",
  "limit": "5",
});
const res = await fetch(`https://kwery-api.com/v1/orderbook?${params}`);
const data = await res.json();

Example Response

{
  "data": [
    {
      "timestamp": "2026-03-08T12:00:00Z",
      "symbol": "BTC",
      "source": "binance_futures",
      "mid_price": 94285.25,
      "spread": 0.50,
      "bids": [
        [94285.00, 2.340],
        [94284.50, 5.120],
        [94284.00, 3.780]
      ],
      "asks": [
        [94285.50, 1.890],
        [94286.00, 4.560],
        [94286.50, 2.910]
      ],
      "imbalance": 0.12,
      "is_full_snapshot": true,
      "diff_since_last": null
    },
    {
      "timestamp": "2026-03-08T12:00:05Z",
      "symbol": "BTC",
      "source": "binance_futures",
      "mid_price": 94290.00,
      "spread": 0.50,
      "bids": [
        [94289.75, 3.100],
        [94289.25, 4.870],
        [94288.75, 2.640]
      ],
      "asks": [
        [94290.25, 2.210],
        [94290.75, 3.980],
        [94291.25, 5.430]
      ],
      "imbalance": -0.05,
      "is_full_snapshot": true,
      "diff_since_last": null
    }
  ],
  "meta": {
    "symbol": "BTC",
    "source": "binance_futures",
    "depth": 10,
    "returned": 5,
    "next_cursor": "eyJ0IjoiMjAyNi0wMy0wOFQxMjowMDoyNVoifQ",
    "has_more": true
  }
}

Tier Access

Plan	History Depth	Diffs
Free	14 days	No
Pro	30 days	No
Business	Full history	Yes (`include_diffs=true`)

Errors

Status	Code	When
400	`invalid_symbol`	The `symbol` parameter is missing or not recognized.
400	`invalid_source`	The `source` parameter is missing or not recognized.
400	`invalid_time_range`	`start` is after `end`, or the range exceeds your plan's history depth.
401	`unauthorized`	Missing or invalid `api-key`.
403	`tier_restricted`	Your plan does not support the requested feature (e.g. `include_diffs` on Pro).
429	`rate_limited`	You have exceeded your plan's request rate. Retry after the `Retry-After` header value.