Market data
Read instruments, candles, the latest price, the order book, trades and volume clusters.
Every call on this page needs the market:read scope. Prices and sizes are
decimal strings, times are UTC milliseconds.
Find an instrument
An instrument has an address: exchange:market:symbol, for example
binance:futures:BTCUSDT. The symbol is written the way the exchange writes
it, so take it from the catalogue.
page = terminal.instruments(exchange="binance", market="futures", q="BTC", limit=50)
for item in page.data:
print(item.instrument, item.tick_size, item.lot_size)To read the whole catalogue page by page, use iter_instruments() in Python
and iterInstruments() in TypeScript.
Candles
candles = terminal.candles("binance:futures:BTCUSDT", "1m", limit=500)
for candle in candles.data:
print(candle.ts, candle.open, candle.high, candle.low, candle.close, candle.volume)| Argument | Meaning |
|---|---|
interval | 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w, 1M. The full list is in intervals(). |
limit | Number of bars, up to 2000. The default is 500. |
end | Right boundary in UTC milliseconds. The default is now. |
Bars come oldest first, and ts is the opening time of a bar. To load older
history, pass the ts of the oldest bar you have as end.
Latest price
A snapshot holds the best bid and ask, the last trade, the mark price and the 24-hour ticker of an instrument.
snapshot = terminal.snapshot("binance:futures:BTCUSDT")
print(snapshot.best_bid, snapshot.best_ask, snapshot.mark_price)A field is empty until its data arrives. See the first call.
Order book
book = terminal.orderbook("binance:futures:BTCUSDT", depth=20)
print(book.bids[0], book.asks[0])depth is the number of levels on each side: from 1 to 200, 50 by default.
Bids go from the best price down, asks from the best price up. A level is a
price and a size.
Recent trades
trades = terminal.trades("binance:futures:BTCUSDT", limit=200)
newer = terminal.trades("binance:futures:BTCUSDT", since_ts=trades.data[-1].ts)Trades come oldest first. The terminal keeps the last 1000 trades of an
instrument. ts is the time the terminal received the trade, exchange_ts
is the time of the exchange.
Volume clusters
A cluster bucket is the volume traded at each price during one interval.
clusters = terminal.clusters("binance:futures:BTCUSDT")
for bucket in clusters.data:
print(bucket.ts, bucket.volume, bucket.buy_volume, bucket.sell_volume)
for level in bucket.levels:
print(level.price, level.buy_volume, level.sell_volume)The answer holds up to ten latest buckets, oldest first. The interval is the
one chosen for the instrument in the terminal, 5m by default. It cannot be
changed through the API; clusters.interval tells which one is in use.
The first call
The latest price, the order book, trades and clusters are read from the terminal's memory. If the instrument is not open in the terminal, the first call subscribes to it on the exchange and waits up to 3 seconds for data. The terminal then keeps the subscription for 30 seconds, so the next calls answer at once.
| What happens | What you get | What to do |
|---|---|---|
| The data has not fully arrived | A snapshot with some empty fields | Call again in a few seconds |
| The order book is not ready in 3 seconds | 503 unavailable | Call again |
| Clusters are not computed yet | 409 not_active | Call again in a few seconds |
| Too many instruments, or too many new ones a second | 429 rate_limited | Slow down, see Limits |
To follow prices continuously, use the stream instead of repeated calls.
Which connection is used
The terminal may have several connections to the same exchange and market.
Each call accepts an optional connection_id. Without it the terminal uses
the enabled trading connection, and the read-only one if there is none. The
answer always names the connection that was used.
What is not available
Data of the Moscow Exchange (MOEX) is not served: every call for a moex:
instrument answers 501 unsupported.