# Candles (`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.

- Category: Market data
- MCP tool: `market_candles`
- REST: `GET /market/candles/{symbol}`
- MCP App: hosts that support MCP Apps render the result as an interactive view
- x402 price: $0.01 per call (USDC on Base)
- HTML: https://www.f1ow.com/docs/tools/market_candles

## What it does

OHLC(V) candle history for a coin by symbol (e.g. 'ETH', 'BTC'). 'interval' picks the candle size (1m|5m|15m|30m|1h|4h|12h|1d|1w, default 1d); 'limit' the number of candles (default 100, max 400); 'market' picks the series — 'spot' (major exchange spot books, then market aggregators), 'perp' (major perpetual venues — perpetual marks), or 'auto' (default: spot preferred; perp when spot fails, or when spot's history is shorter than the request and than 210 candles while perp's is materially longer — e.g. a coin whose spot pair listed recently). spot/perp are hard constraints and error rather than substitute. The response labels the market, interval and source actually delivered, includes USD volume when the source carries it, and flags a still-forming last candle.

## Parameters

| Name | Type | In | Required | Description |
| --- | --- | --- | --- | --- |
| `symbol` | string | path | yes | Coin symbol, e.g. 'ETH' or 'BTC' |
| `interval` | string | query | no | Candle size. Default 1d. One of: `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `12h`, `1d`, `1w`. |
| `market` | string | query | no | Which market's series: spot exchange trades, perpetual-futures marks, or auto (spot preferred; perp when spot fails or its history is too short). Default auto. One of: `spot`, `perp`, `auto`. |
| `limit` | integer | query | no | Number of candles, newest last. Default 100, max 400. |
| `days` | integer | query | no | DEPRECATED: trailing window in days; use interval+limit instead. Ignored when interval is given. |

## Call it

### cURL

```bash
curl "https://mcp.f1ow.com/v1/market/candles/BTC?interval=4h&market=perp&limit=50" \
  -H "Authorization: Bearer $F1OW_API_KEY"
```

### MCP

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "market_candles",
    "arguments": {
      "symbol": "BTC",
      "interval": "4h",
      "market": "perp",
      "limit": 50
    }
  }
}
```

### TypeScript

```ts
const res = await fetch("https://mcp.f1ow.com/v1/market/candles/BTC?interval=4h&market=perp&limit=50", {
  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/candles/BTC?interval=4h&market=perp&limit=50",
    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_candles",
    "arguments": {
      "symbol": "BTC",
      "interval": "4h",
      "market": "perp",
      "limit": 50
    }
  }
}

// Or push a fresh result whenever it changes (minimum interval 15 s)
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "subscriptions/subscribe",
  "params": {
    "name": "market_candles",
    "arguments": {
      "symbol": "BTC",
      "interval": "4h",
      "market": "perp",
      "limit": 50
    },
    "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/candles/BTC?interval=4h&market=perp&limit=50"
```

## Sample response

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

```json
{
  "candles": [
    {
      "asOfAt": "2026-11-05T04:00:00.0000000+00:00",
      "closeUsd": 80355,
      "highUsd": 80775,
      "lowUsd": 80285,
      "openUsd": 80509,
      "timestampMs": 1793851200000,
      "volumeUsd": 156364778.46495
    },
    {
      "asOfAt": "2026-11-05T08:00:00.0000000+00:00",
      "closeUsd": 80399,
      "highUsd": 80636,
      "lowUsd": 80233,
      "openUsd": 80359,
      "timestampMs": 1793865600000,
      "volumeUsd": 156830443.61633
    },
    {
      "asOfAt": "2026-11-05T12:00:00.0000000+00:00",
      "closeUsd": 76044,
      "highUsd": 80400,
      "lowUsd": 75538,
      "openUsd": 80400,
      "timestampMs": 1793880000000,
      "volumeUsd": 2069600083.75488
    },
    {
      "asOfAt": "2026-11-05T16:00:00.0000000+00:00",
      "closeUsd": 76370,
      "highUsd": 77036,
      "lowUsd": 75672,
      "openUsd": 76047,
      "timestampMs": 1793894400000,
      "volumeUsd": 1276101643.488
    },
    {
      "asOfAt": "2026-11-05T20:00:00.0000000+00:00",
      "closeUsd": 76078,
      "highUsd": 76423,
      "lowUsd": 75189,
      "openUsd": 76370,
      "timestampMs": 1793908800000,
      "volumeUsd": 834850793.80466
    },
    {
      "asOfAt": "2026-11-06T00:00:00.0000000+00:00",
      "closeUsd": 75890,
      "highUsd": 76400,
      "lowUsd": 75760,
      "openUsd": 76078,
      "timestampMs": 1793923200000,
      "volumeUsd": 277894880.8062
    },
    "… 44 more"
  ],
  "coinId": "BTC",
  "interval": "4h",
  "lastCandleIsPartial": true,
  "market": "perp",
  "source": "Hyperliquid",
  "symbol": "BTC",
  "generatedAt": "2026-11-13T08:00:00.0000000+00:00"
}
```

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

```text
=== BTC — 4h × 50 candles (perp, Hyperliquid) ===
Window 2026-11-05 04:00 → 2026-11-13 08:00 UTC | change -14.73% | close $80509.00 → $68648.00
Range $67474.00 – $80775.00 | last close 9% of range
Volume (last closed candle) $1.20B vs 20-candle avg $567.49M (2.1x)
Last candle (2026-11-13 08:00) is still forming — partial, not a closed 4h

Last 14 candles:
2026-11-11 04:00  O $73747.00  H $74096.00  L $73456.00  C $74076.00  V $369.44M
2026-11-11 08:00  O $74076.00  H $74170.00  L $73527.00  C $73963.00  V $414.91M
2026-11-11 12:00  O $73962.00  H $74478.00  L $73360.00  C $73951.00  V $764.81M
2026-11-11 16:00  O $73951.00  H $74750.00  L $73890.00  C $74376.00  V $461.70M
2026-11-11 20:00  O $74377.00  H $74778.00  L $73432.00  C $73979.00  V $503.39M
2026-11-12 00:00  O $73980.00  H $74180.00  L $73549.00  C $73771.00  V $233.73M
2026-11-12 04:00  O $73772.00  H $73829.00  L $73379.00  C $73622.00  V $113.18M
2026-11-12 08:00  O $73623.00  H $73661.00  L $72750.00  C $72930.00  V $319.29M
2026-11-12 12:00  O $72929.00  H $73127.00  L $71227.00  C $71708.00  V $1.50B
2026-11-12 16:00  O $71701.00  H $72214.00  L $71401.00  C $71666.00  V $784.05M
2026-11-12 20:00  O $71667.00  H $71675.00  L $71090.00  C $71448.00  V $425.87M
2026-11-13 00:00  O $71448.00  H $71507.00  L $68521.00  C $68927.00  V $1.49B
2026-11-13 04:00  O $68928.00  H $69351.00  L $67474.00  C $68560.00  V $1.20B
2026-11-13 08:00  O $68560.00  H $68675.00  L $68540.00  C $68648.00  V $8.32M
```

## 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.
- [Bulk History](https://www.f1ow.com/docs/tools/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.
- [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.