Copy page

Market Data

TypeScript SDK — Market Data: Books, Trades & Candles

Order book snapshots, public trade history, and OHLCV candlestick data. All methods are on client.marketData. All methods in this group are public (no authentication required) and backed by GET requests, so they auto-retry on transient failures (429, 502, 503, 504).

Prices, quantities, and amounts are decimal strings. See Data Types for safe handling.

getCurrentOrderBook

GET /v1/book/{symbol} · Public

Returns the current order book as two arrays of bid and ask price levels. Each level includes a price, amount, and timestamp — all as strings.

Code
const book = await client.marketData.getCurrentOrderBook(
  { symbol: "BTCUSD" },
  { limit_bids: 10, limit_asks: 10 },
);
for (const bid of book.bids) {
  console.log(bid.price, bid.amount); // "50123.45" "0.5"
}
for (const ask of book.asks) {
  console.log(ask.price, ask.amount); // "50125.00" "1.2"
}

The second argument (query params) is optional. Available query parameters:

Parameter	Type	Default	Description
limit_bids	number	50	Max bid levels to return. 0 = full book.
limit_asks	number	50	Max ask levels to return. 0 = full book.

Tip: This endpoint returns a point-in-time snapshot. For a continuously-updated local order book, use the SDK's client.orderBook(symbol) helper — see Order Book Reconstruction for how it applies WebSocket depth diffs to stay synchronized.

Caveat: Prices and quantities are returned as strings, not numbers. Treating them as floats risks precision loss. See Data Types.

listTrades

GET /v1/trades/{symbol} · Public

Returns public trade history for a symbol, sorted newest first. Each request returns at most 500 records and is limited to seven calendar days of data.

Code
// Most recent 50 trades (default)
const trades = await client.marketData.listTrades({ symbol: "BTCUSD" });

// Trades after a specific timestamp, limited to 100
const filtered = await client.marketData.listTrades(
  { symbol: "BTCUSD" },
  { timestamp: 1700000000, limit_trades: 100 },
);

for (const t of filtered) {
  console.log(t.tid, t.price, t.amount, t.type); // 5335307668 "50124.50" "0.274" "buy"
}

Available query parameters:

Parameter	Type	Default	Description
timestamp	number	—	Only return trades after this timestamp (seconds or ms since epoch). 90-day hard limit.
since_tid	number	—	Only return trades after this trade ID. Overrides timestamp if both are set. Use 0 for earliest available data.
limit_trades	number	50	Maximum trades to return (up to 500).
include_breaks	boolean	false	Whether to include broken (reversed) trades.

Tip: To poll for new trades (forward pagination), pass the highest tid from your last batch as since_tid. The API returns trades with IDs strictly greater than the value you provide, so you won't see duplicates. Note that tid in the response is a bigint while since_tid in the query is typed as number — convert with Number(trade.tid) for values within safe integer range, or use trade.tid.toString() and parse back if needed.

Note: This endpoint is limited to seven calendar days of data. Contact Gemini for access to extended market data.

listCandles

GET /v2/candles/{symbol}/{time_frame} · Public

Returns OHLCV (open, high, low, close, volume) candlestick data. Each candle is an array of [timestamp, open, high, low, close, volume].

Code
const candles = await client.marketData.listCandles({
  symbol: "BTCUSD",
  time_frame: "1h",
});
for (const [timestamp, open, high, low, close, volume] of candles) {
  console.log({ timestamp, open, high, low, close, volume });
  // { timestamp: 1559755800000, open: 7781.6, high: 7820.23, ... }
}

Supported time_frame values:

Value	Interval
"1m"	1 minute
"5m"	5 minutes
"15m"	15 minutes
"30m"	30 minutes
"1h"	1 hour
"6h"	6 hours
"1d"	1 day

Note: Candle values (open, high, low, close, volume) are numbers in this endpoint's response, not strings. This differs from most other market data endpoints.

listDerivativeCandles

GET /v2/derivatives/candles/{symbol}/{time_frame} · Public

Returns OHLCV candlestick data for perpetual derivative pairs. Currently only the "1m" time frame is supported.

Code
const candles = await client.marketData.listDerivativeCandles({
  symbol: "BTCGUSDPERP",
  time_frame: "1m",
});
for (const [timestamp, open, high, low, close, volume] of candles) {
  console.log({ timestamp, open, high, low, close, volume });
}

Note: Only "1m" is available for derivative candles. Passing any other time frame will result in an error. For spot candles with more time frames, use listCandles.

What's next

• Symbols & Pricing — symbol discovery, ticker data, and price feeds
• Networks & Derivatives — network/token lookups, FX rates, and funding data
• Order Book Reconstruction — how the SDK maintains a live local order book from WebSocket diffs
• Data Types — decimal strings, bigint timestamps, and safe arithmetic
• Full API Specifications — complete request/response schemas