---
title: "Price Candles"
method: GET
path: "/market/candles/{symbol}"
tags: ["market"]
---

# Price Candles

`GET /market/candles/{symbol}`

## Request

- Base URL: `https://mcp.f1ow.com/v1`
- URL: `https://mcp.f1ow.com/v1/market/candles/{symbol}`
- Auth: one of:
  - HTTP bearer
  - none

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' (Binance, Bybit, then CoinGecko/CoinMarketCap), 'perp' (Hyperliquid, Bybit, then Binance futures — 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.

## Path parameters

- `symbol` string, required: Coin symbol, e.g. 'ETH' or 'BTC'

## Query parameters

- `interval` '1m' | '5m' | '15m' | '30m' | '1h' | '4h' | '12h' | '1d' | '1w': Candle size. Default 1d.
- `market` 'spot' | 'perp' | 'auto': 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.
- `limit` integer: Number of candles, newest last. Default 100, max 400.
- `days` integer: DEPRECATED: trailing window in days; use interval+limit instead. Ignored when interval is given.

## Response `200`

The result.

- object
  - `data` object
    - `coinId` string: Identifier the answering provider queried
    - `interval` string: Candle size actually delivered, e.g. '4h'
    - `market` string: 'spot' or 'perp' — which market the series describes
    - `source` string: Provider that answered
    - `lastCandleIsPartial` boolean: True when the newest candle is still forming; exclude it from indicator math
    - `candles` object[]
      - `timestampMs` integer: Candle open time, Unix epoch milliseconds
      - `asOfAt` string: Candle open time, ISO-8601 UTC
      - `openUsd` number: Open price, USD
      - `highUsd` number: High price, USD
      - `lowUsd` number: Low price, USD
      - `closeUsd` number: Close price, USD
      - `volumeUsd` number: Traded volume, USD notional; omitted when the source has none
  - `text` string, required: Human-readable rendering of the result.
  - `meta` ResponseMeta
    - `generatedAt` string, date-time: When the data was produced (source timestamp where the provider has one), ISO 8601 UTC

## Other responses

- `400`: An argument is missing or invalid.
- `401`: No credential was sent.
- `402`: x402 route: a priced call without a valid payment (challenge in the base64 PAYMENT-REQUIRED header). Metered routes: the account balance or access period is spent.
- `403`: The credential was rejected.
- `500`: Unexpected server error.
- `502`: The data source could not answer.

---

[API](https://skmtc.dev/f1ow/apis/f1ow-api.md) · [All operations](https://skmtc.dev/f1ow/apis/f1ow-api/llms.txt) · [OpenAPI document](https://skmtc.dev/f1ow/apis/f1ow-api/revisions/6974f25b6067?raw)