LootX

Instruments, time, and pages

Updated November 7, 2026 This page as PDF

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 — spot or perp. A name with future or option parses, but there is no data for them: such a request gets 400 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: 1793750400000 is November 4, 2026, 00:00 UTC.
  • The request window is half-open [from, to): from is included, to is not. That way adjacent windows join without repeats.
  • Each endpoint has its own defaults: candles without from go back limit steps from to, trades take the last hour, open interest the last day. Without to, 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.
Python
from datetime import datetime, timezone

t0 = int(datetime(2026, 11, 4, tzinfo=timezone.utc).timestamp() * 1000)  # 1793750400000

Response — 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.

JSON
{
  "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:

JavaScript
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.

Python
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-Cursor is the cursor, Link is the ready-made address of the next page (RFC 8288). In CSV the cursor is only in the header; in protobuf, also in the next_cursor field (formats).
HTTP
Link: <https://market-api.lootx.trade/v1/candles?instrument=binance:perp:BTCUSDT&tf=1m&cursor=YzE6MTc5MTMzMTMyMDAwMA>; rel="next"
X-Next-Cursor: YzE6MTc5MTMzMTMyMDAwMA

The 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.