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 datamarket_candlesGET /market/candles/{symbol}x402 · $0.01 / callRead-onlyMCP App

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	Description
`symbol`requiredpath	string	Coin symbol, e.g. 'ETH' or 'BTC'
`interval`query	string	Candle size. Default 1d.`1m5m15m30m1h4h12h1d1w`
`market`query	string	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.`spotperpauto`
`limit`query	integer	Number of candles, newest last. Default 100, max 400.
`days`query	integer	DEPRECATED: trailing window in days; use interval+limit instead. Ignored when interval is given.

Call it

One API key works for MCP, REST and WebSocket; each call uses one unit. Agents without an account can pay per call with x402.

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

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

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);

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)

// 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
  }
}

# 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

A real response captured 2026-11-13. Interactive is the tool's MCP App rendering it, as Claude, ChatGPT and other MCP Apps hosts show it; here it is read-only. JSON is what REST and WebSocket return, and the structuredContent of an MCP call (trimmed for length), with generatedAt for freshness. Text is the report an MCP client hands to a model.

Loading interactive view…

=== 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

{
  "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"
}

Spot & Perp Quotesmarket_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 Historymarket_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 Overviewmarket_overview

The global frame in one read: total market cap, BTC and ETH dominance, Fear & Greed, Altcoin Season.

Top Moversmarket_top_movers

The day's ranked gainers and losers, plus the quieter names already trending more than five percent.

Call Candles from your agent

Get an API key Browse tools

For agents: this page as Markdown · all docs