# Bulk History (`market_history`)

> Paged spot/perp candles, aggregate open interest, funding or long/short liquidations. Up to 1,000 rows per call with a backward-page cursor, explicit time bounds and a forming-row flag — for historical research and backtests.

- Category: Market data
- MCP tool: `market_history`
- REST: `GET /market/history/{symbol}`
- x402 price: $0.02 per call (USDC on Base)
- HTML: https://www.f1ow.com/docs/tools/market_history

## What it does

Bulk history for one coin, one metric per call, in pages: 'price' (OHLCV candles, spot or perp), 'open_interest' (market-wide aggregate USD), 'funding' (OI-weighted rate, %/8h and annualized) or 'liquidations' (market-wide long/short USD per bucket). Returns up to 'limit' rows (default 200, max 1000) at or before 'end' (default now), oldest first, as compact columns + rows; pass the returned nextEndMs as 'end' to fetch the page before it, and 'start' to stop there. Reach: price is full venue history (spot from 2017, futures from 2019) at 1m–1w; derivatives come from an aggregated feed at 4h (about 180 days back), 6h/8h/12h (about 360 days) or 1d/1w (back to 2020) — use 1d for anything older than six months. The newest row may still be forming (newestForming). Use this to pull history; for a read of what is happening now, use the derivatives_* and research_* tools.

## Parameters

| Name | Type | In | Required | Description |
| --- | --- | --- | --- | --- |
| `symbol` | string | path | yes | Coin symbol, e.g. "BTC". |
| `metric` | string | query | yes | One of: `price`, `open_interest`, `funding`, `liquidations`. |
| `interval` | string | query | no | Bucket size. Price: 1m–1w except 6h/8h, default 1d. Derivatives: 4h, 6h, 8h, 12h, 1d or 1w; default 4h (funding 8h). One of: `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `6h`, `8h`, `12h`, `1d`, `1w`. |
| `market` | string | query | no | Price only: spot (default) or perpetual candles. One of: `spot`, `perp`. |
| `start` | string | query | no | Earliest time to include: ISO-8601 (UTC if no offset) or Unix ms. Paging stops here. |
| `end` | string | query | no | Latest time to include: ISO-8601 or Unix ms. Default now. Pass nextEndMs here to page back. |
| `limit` | integer | query | no | Rows per page, 1–1000. Default 200. |

## Call it

### cURL

```bash
curl "https://mcp.f1ow.com/v1/market/history/BTC?metric=open_interest&interval=1d&limit=30" \
  -H "Authorization: Bearer $F1OW_API_KEY"
```

### MCP

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "market_history",
    "arguments": {
      "symbol": "BTC",
      "metric": "open_interest",
      "interval": "1d",
      "limit": 30
    }
  }
}
```

### TypeScript

```ts
const res = await fetch("https://mcp.f1ow.com/v1/market/history/BTC?metric=open_interest&interval=1d&limit=30", {
  headers: { Authorization: `Bearer ${process.env.F1OW_API_KEY}` },
});
const data = await res.json(); // the tool's result as JSON, typed in the OpenAPI spec
console.log(data);
```

### Python

```python
import os, requests

res = requests.get(
    "https://mcp.f1ow.com/v1/market/history/BTC?metric=open_interest&interval=1d&limit=30",
    headers={"Authorization": f"Bearer {os.environ['F1OW_API_KEY']}"},
)
data = res.json()  # the tool's result as JSON, typed in the OpenAPI spec
print(data)
```

### WebSocket

```jsonc
// wss://mcp.f1ow.com/v1/ws — subprotocol "jsonrpc-2.0", Authorization: Bearer <key>
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "market_history",
    "arguments": {
      "symbol": "BTC",
      "metric": "open_interest",
      "interval": "1d",
      "limit": 30
    }
  }
}

// Or push a fresh result whenever it changes (minimum interval 15 s)
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "subscriptions/subscribe",
  "params": {
    "name": "market_history",
    "arguments": {
      "symbol": "BTC",
      "metric": "open_interest",
      "interval": "1d",
      "limit": 30
    },
    "intervalSeconds": 60
  }
}
```

### x402

```bash
# No account: the first call answers 402 with a PAYMENT-REQUIRED challenge;
# an x402 client pays it in USDC on Base and retries.
curl "https://mcp.f1ow.com/x402/v1/market/history/BTC?metric=open_interest&interval=1d&limit=30"
```

## Sample response

Captured 2026-11-13. The JSON is what REST and WebSocket return and the `structuredContent` of an MCP call (trimmed):

```json
{
  "columns": [
    "timeMs",
    "oiUsd"
  ],
  "count": 28,
  "endMs": 1794557139754,
  "interval": "1d",
  "metric": "open_interest",
  "newestForming": true,
  "note": "The newest row is still forming; the vendor rewrites it until the bucket closes.",
  "rows": [
    [
      1792022400000,
      52691693756
    ],
    [
      1792108800000,
      52521968289
    ],
    [
      1792195200000,
      52090533349
    ],
    [
      1792281600000,
      52274235374
    ],
    [
      1792368000000,
      52748196130
    ],
    [
      1792454400000,
      53562564956
    ],
    "… 22 more"
  ],
  "source": "CoinGlass",
  "symbol": "BTC",
  "units": "market-wide (cross-venue) open interest at the bucket close, USD",
  "generatedAt": "2026-11-13T08:05:40.0107135+00:00"
}
```

Over MCP the text report a model reads comes with it:

```text
BTC open interest, 1d, 28 rows 2026-10-15 00:00 → 2026-11-13 00:00 UTC (CoinGlass) — market-wide (cross-venue) open interest at the bucket close, USD
The newest row is still forming; the vendor rewrites it until the bucket closes.
time_utc,oiUsd
2026-10-15 00:00,52691693756
2026-10-16 00:00,52521968289
2026-10-17 00:00,52090533349
2026-10-18 00:00,52274235374
2026-10-19 00:00,52748196130
2026-10-20 00:00,53562564956
2026-10-21 00:00,55947787989
2026-10-22 00:00,54173016674
2026-10-23 00:00,53575847638
2026-10-24 00:00,54112514872
2026-10-25 00:00,53193603546
2026-10-26 00:00,54218670794
2026-10-27 00:00,54635529075
2026-10-28 00:00,54132009384
2026-10-29 00:00,53452685391
2026-10-30 00:00,53693030562
2026-10-31 00:00,52906757502
2026-11-01 00:00,53103411055
2026-11-02 00:00,53878920611
2026-11-03 00:00,52430828965
2026-11-04 00:00,53187479335
2026-11-05 00:00,52014076734
2026-11-06 00:00,51761207334
2026-11-09 00:00,52162852946
2026-11-10 00:00,51920511741
2026-11-11 00:00,50499091321
2026-11-12 00:00,50949001404
2026-11-13 00:00,47722081269
```

## Related tools

- [Spot & Perp Quotes](https://www.f1ow.com/docs/tools/market_quotes) — Spot and perp mark side by side, with funding, open interest, long/short ratio and the day's liquidations. Five providers merged into one snapshot, cached for thirty seconds.
- [Candles](https://www.f1ow.com/docs/tools/market_candles) — Spot or perpetual OHLCV candles with venue routing and fallback, for the timeframes your analysis needs. For months of paged candles or derivatives series, use Bulk History.
- [Market Overview](https://www.f1ow.com/docs/tools/market_overview) — The global frame in one read: total market cap, BTC and ETH dominance, Fear & Greed, Altcoin Season.
- [Top Movers](https://www.f1ow.com/docs/tools/market_top_movers) — The day's ranked gainers and losers, plus the quieter names already trending more than five percent.