> ## Documentation Index
> Fetch the complete documentation index at: https://docs.llmquantdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Crypto Historical Klines

> OHLCV K-line bars for crypto pairs — recent N or arbitrary time range, with 1h / 4h / 1d / 1w intervals.

<Note icon="sparkles">
  **Available as MCP tool**: `crypto_historical_klines` — call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge color="green" icon="circle-check">Live</Badge>
 
<Badge color="blue" size="sm">1 credit per call</Badge>

## What it does for your agent

`crypto_historical_klines` returns OHLCV candlestick bars for a single crypto pair. Use it as the **historical pricing primitive** an agent reaches for whenever it needs returns, drawdowns, technicals, or backtest data — not for the latest tick (use `crypto_snapshot` for that).

Two query modes share one endpoint: pass `limit` to get the most recent N closed candles, or pass `start_time + end_time` for an exact window. Only **closed candles** are returned — the in-progress candle is never included.

## Response

<ResponseField name="data" type="CryptoHistoricalResult" required>
  <Expandable title="CryptoHistoricalResult fields">
    <ResponseField name="ticker" type="string" required>
      The trading pair in `BASE-QUOTE` format (e.g. `BTC-USD`).
    </ResponseField>

    <ResponseField name="interval" type="string" required>
      Candlestick interval (`1h` / `4h` / `1d` / `1w`).
    </ResponseField>

    <ResponseField name="prices" type="CryptoKlineBar[]" required>
      Klines in chronological order. Closed candles only.

      <Expandable title="CryptoKlineBar fields">
        <ResponseField name="open" type="number" required>Opening price.</ResponseField>
        <ResponseField name="high" type="number" required>High price.</ResponseField>
        <ResponseField name="low" type="number" required>Low price.</ResponseField>
        <ResponseField name="close" type="number" required>Closing price.</ResponseField>
        <ResponseField name="volume" type="number" required>Base-asset trading volume.</ResponseField>
        <ResponseField name="time" type="string" required>Bar open time (ISO 8601 UTC).</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Credits consumed (always `1`).</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>

```json title="200 OK · crypto_historical_klines" expandable theme={null}
{
  "data": {
    "ticker": "BTC-USD",
    "interval": "1d",
    "prices": [
      {
        "open": 87000.50,
        "high": 87500.00,
        "low": 86800.00,
        "close": 87200.00,
        "volume": 1234.56,
        "time": "2026-03-01T00:00:00Z"
      },
      {
        "open": 87200.00,
        "high": 88100.00,
        "low": 87000.00,
        "close": 87950.00,
        "volume": 1456.78,
        "time": "2026-03-02T00:00:00Z"
      }
    ]
  },
  "meta": { "creditsUsed": 1, "remainingCredits": 99 }
}
```

## Notes

<Tip>
  For the **latest tick** (price + 24h change), use `crypto_snapshot` — it's a different primitive and is much cheaper conceptually. Reach for `crypto_historical_klines` only when you need a series of bars.
</Tip>

<Tip>
  The first request for a ticker + interval + range can be slower. Subsequent identical queries usually return faster.
</Tip>

<Tip>
  Use `data.prices.length` when you need the returned bar count; `meta` is reserved for credits and optional notices.
</Tip>

<Warning>
  **Spot markets only.** Futures, perpetuals, funding rates, and open interest are not exposed.
</Warning>

<Warning>
  **No minute-level intervals.** `1m`, `5m`, `15m` are not supported — only `1h`, `4h`, `1d`, `1w`.
</Warning>

<Warning>
  **Closed candles only.** The current in-progress candle is never included.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // Recent mode — last 30 daily candles
    {
      "method": "tools/call",
      "params": {
        "name": "crypto_historical_klines",
        "arguments": { "ticker": "BTC-USD", "interval": "1d", "limit": 30 }
      }
    }

    // Range mode — explicit window
    {
      "method": "tools/call",
      "params": {
        "name": "crypto_historical_klines",
        "arguments": {
          "ticker": "ETH-USD",
          "interval": "1h",
          "start_time": "2026-03-01T00:00:00Z",
          "end_time": "2026-03-02T00:00:00Z"
        }
      }
    }
    ```

    ```python Python (HTTP) theme={null}
    import os, requests

    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    # Recent mode
    resp = requests.get(
        "https://api.llmquantdata.com/api/crypto/historical",
        headers=headers,
        params={"ticker": "BTC-USD", "interval": "1d", "limit": 30},
    ).json()
    for bar in resp["data"]["prices"]:
        print(f"{bar['time']}  C={bar['close']}  V={bar['volume']}")

    # Range mode
    resp = requests.get(
        "https://api.llmquantdata.com/api/crypto/historical",
        headers=headers,
        params={
            "ticker": "ETH-USD",
            "interval": "1h",
            "start_time": "2026-03-01T00:00:00Z",
            "end_time": "2026-03-02T00:00:00Z",
        },
    ).json()
    print(f"Range mode returned {len(resp['data']['prices'])} bars")
    ```

    ```bash cURL theme={null}
    # Recent mode
    curl "https://api.llmquantdata.com/api/crypto/historical?ticker=BTC-USD&interval=1d&limit=30" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

    # Range mode
    curl "https://api.llmquantdata.com/api/crypto/historical?ticker=ETH-USD&interval=1h&start_time=2026-03-01T00:00:00Z&end_time=2026-03-02T00:00:00Z" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## Full parameter reference

<Accordion title="crypto_historical_klines — request parameters" icon="sliders">
  <ParamField query="ticker" type="string" required>
    Trading pair in `BASE-QUOTE` format. Examples: `BTC-USD`, `ETH-USD`, `SOL-USD`.
  </ParamField>

  <ParamField query="interval" type="string" required>
    Candlestick interval. One of `1h`, `4h`, `1d`, `1w`. Minute-level intervals are not supported.
  </ParamField>

  <Tabs>
    <Tab title="Recent mode">
      Pass `limit` only (or omit it for the interval default). Returns the most recent N closed candles.

      <ParamField query="limit" type="integer">
        Number of recent candles. Defaults vary by interval: `1h` = 24, `4h` = 42, `1d` = 30, `1w` = 12. Max `200`.
      </ParamField>
    </Tab>

    <Tab title="Range mode">
      Pass `start_time` and `end_time` together. Returns all closed candles in the inclusive range.

      <ParamField query="start_time" type="string" required>
        Start of time range in ISO 8601 UTC (e.g. `2026-03-01T00:00:00Z`). Must be paired with `end_time`.
      </ParamField>

      <ParamField query="end_time" type="string" required>
        End of time range in ISO 8601 UTC. Must be paired with `start_time`.
      </ParamField>

      <ParamField query="limit" type="integer">
        Optional safety cap on returned bars (max `200`). In Range mode `limit` is only a guard; the time window drives selection.
      </ParamField>

      <Warning>
        Passing only `start_time` or only `end_time` returns a `400` error.
      </Warning>
    </Tab>
  </Tabs>
</Accordion>

## Related

<Columns cols={2}>
  <Card title="Crypto Snapshot" icon="bolt" href="/en/api/prices/crypto-snapshot">
    Latest spot price + 24h stats for a crypto pair — use this when you only need "right now".
  </Card>

  <Card title="Equity Historical Prices" icon="square-chart-gantt" href="/en/api/prices/equity-historical">
    Same Recent / Range shape for US equities at daily granularity.
  </Card>
</Columns>