Instruments, time, and pages
1Instruments, time, and pages
Three rules common to every endpoint: instrument name as venue:market:SYMBOL, time in Unix milliseconds UTC, and pagination via next_cursor.
Every API endpoint speaks the same language: an instrument is named identically across exchanges and sources, time is always Unix milliseconds UTC, and long responses page with a cursor. Here are those three rules, once and in detail.
Instrument name
An instrument is written as venue:market:SYMBOL:
| Example | What it is |
|---|---|
binance:perp:BTCUSDT |
BTC USDT-margined perpetual on Binance |
bybit:spot:ETHUSDT |
ETH/USDT spot on Bybit |
hyperliquid:perp:BTC |
BTC perp on Hyperliquid — that exchange calls a perp a coin |
coinbase:spot:BTC-USD |
BTC/USD spot on Coinbase — with a hyphen, as the exchange itself does |
lighter:perp:BTCUSDC |
BTC perp on Lighter, settled in USDC |
hyperliquid:perp:AAPLUSDC.XYZ |
Apple stock on Hyperliquid’s xyz deck (HIP-3 market); not every endpoint has its data |
- venue — the exchange in lowercase:
binance,bybit,okx,bitget,gate,mexc,bingx,kucoin,hyperliquid,aster,lighter,kraken,coinbase,upbit, and others. Which exchange has which data type varies; the full list is in/v1/instruments. - market —
spotorperp. A name withfutureoroptionparses, but there is no data for them: such a request gets400 unsupported_instrument. - SYMBOL — base and quote together, uppercase:
BTCUSDT,ETHUSDC. The exceptions are Hyperliquid and Coinbase, as in the table.
An invalid name form is 400 bad_instrument. A valid name but an endpoint that doesn’t know that market or exchange is 400 unsupported_instrument with param: "instrument". Only /v1/candles and /v1/series check the symbol, and not always: a pair the source doesn’t have can get 400 unsupported_instrument with param: "symbol" there, and when the source fails, an empty 200. Other endpoints don’t check the symbol against the registry: a typo or a pair whose name passes the exchange, market, and quote checks gets a 200 with no rows. Check the name against the registry; for refusal conditions and exceptions, see the errors page.
Time
- Time everywhere is Unix milliseconds UTC, an integer:
1793750400000is November 4, 2026, 00:00 UTC. - The request window is half-open
[from, to):fromis included,tois not. That way adjacent windows join without repeats. - Each endpoint has its own defaults: candles without
fromgo backlimitsteps fromto, trades take the last hour, open interest the last day. Withoutto, it means “now”. - The step (
tf) is a number with a suffix:1s,30s,1m,5m,1h,4h,1d. Which steps an endpoint accepts is in its description.
from datetime import datetime, timezone
t0 = int(datetime(2026, 11, 4, tzinfo=timezone.utc).timestamp() * 1000) # 1793750400000Response — a table by columns
Rows arrive not as an array of objects but as a table: column names once, rows as arrays of values in the same order. That makes the response several times shorter.
{
"instrument": "binance:perp:BTCUSDT",
"columns": ["ts", "open", "high", "low", "close"],
"rows": [[1793750400000, 104250.5, 104262.0, 104241.1, 104255.3]],
"next_cursor": null
}Turn it into familiar objects with one line:
const records = body.rows.map((r) => Object.fromEntries(body.columns.map((c, i) => [c, r[i]])));A response may gain fields — don’t rely on their order and don’t fail on an unknown field. The column order within the table is set by columns.
Pages
If a response doesn’t fit in one page, it contains next_cursor. Pass it as cursor= with the same other parameters — you get the next page. next_cursor: null means there are no more pages.
import os, requests
URL = "https://market-api.lootx.trade/v1/trades"
HEAD = {"Authorization": f"Bearer {os.environ['LOOTX_API_KEY']}"}
params = {"instrument": "binance:perp:BTCUSDT", "from": 1793750400000, "to": 1793754000000}
rows = []
while True:
page = requests.get(URL, params=params, headers=HEAD, timeout=30).json()
rows += page["rows"]
if not page.get("next_cursor"):
break
params["cursor"] = page["next_cursor"]- The cursor is an opaque string: inside is only a continuation position. The gateway doesn’t check the other parameters against those from the first page: with different parameters, the page will be built from this position using them. So pass the cursor with the same
instrument,tf,to,limit, and the rest.400 bad_cursor— only if the cursor is corrupted. - Candles are cut into pages along the step grid, and for trades, all records of the same millisecond go to one page: there are no repeats or gaps at the seam.
- Most endpoints paginate from old to new. Exception: liquidity wall history pages from new to old.
- In any format, the next page is also in the headers:
X-Next-Cursoris the cursor,Linkis the ready-made address of the next page (RFC 8288). In CSV the cursor is only in the header; in protobuf, also in thenext_cursorfield (formats).
Link: <https://market-api.lootx.trade/v1/candles?instrument=binance:perp:BTCUSDT&tf=1m&cursor=YzE6MTc5MTMzMTMyMDAwMA>; rel="next"
X-Next-Cursor: YzE6MTc5MTMzMTMyMDAwMAThe address in Link is the same request with a new cursor: you can follow it without assembling anything. The last page carries no Link or X-Next-Cursor headers.
Headers worth logging
| Header | Why |
|---|---|
X-Request-Id |
the request number; the same as request_id in the error body. Send it to support |
X-RateLimit-Remaining |
how many requests are left in the tightest limit — details |
X-Cache |
present only on responses the gateway can cache (closed ranges): HIT — from gateway memory, MISS — from the source. The gateway remembers closed ranges for up to 10 minutes. Other responses don’t have this header |
RateLimit |
remaining and seconds until reset across all plan windows — details |
The gateway sets X-Request-Id itself on every response; that is the number by which we can find the request.
Compression
Responses are compressed if the client asks: Accept-Encoding: gzip or br. curl asks with --compressed; requests and browsers do it on their own. The heatmap binary (HMP1/HMP2) is not compressed — it is already dense.
The daily plan volume is counted by the body before compression: a request costs the same with or without compression, and compression saves only time and traffic.
https://docs.lootx.trade/en/market-api/conventions