# 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](/tools/typescript-sdk/deep-dives/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.

```ts
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](/tools/typescript-sdk/deep-dives/order-book) 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](/tools/typescript-sdk/deep-dives/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.

```ts
// 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]`.

```ts
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.

```ts
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](#listcandles).

## What's next

- [Symbols & Pricing](/tools/typescript-sdk/reference/market-data/symbols-and-pricing) — symbol discovery, ticker data, and price feeds
- [Networks & Derivatives](/tools/typescript-sdk/reference/market-data/networks-and-derivatives) — network/token lookups, FX rates, and funding data
- [Order Book Reconstruction](/tools/typescript-sdk/deep-dives/order-book) — how the SDK maintains a live local order book from WebSocket diffs
- [Data Types](/tools/typescript-sdk/deep-dives/data-types) — decimal strings, `bigint` timestamps, and safe arithmetic
- [Full API Specifications](/api-specifications) — complete request/response schemas