> ## 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.

# 加密货币历史 K 线

> 加密货币交易对的 OHLCV K 线 —— 支持最近 N 根 / 指定时间范围两种模式，含 1h / 4h / 1d / 1w 周期。

<Note icon="sparkles">
  **已暴露为 MCP 工具**：`crypto_historical_klines` —— 在 Claude / Cursor / 任意 MCP 客户端中直接调用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge color="green" icon="circle-check">已上线</Badge>
 
<Badge color="blue" size="sm">每次 1 credit</Badge>

## 它为 Agent 做什么

`crypto_historical_klines` 返回单个加密货币交易对的 OHLCV K 线。它是 agent 拿历史价格做收益率、回撤、技术指标、回测的 **历史价格 primitive** —— 不是用来取最新报价的工具（取最新价用 `crypto_snapshot`）。

同一个接口支持两种查询模式：传 `limit` 取最近 N 根已收盘 candle，或者传 `start_time + end_time` 取一个明确时间窗口。**只返回已收盘的 candle**，当前未收盘的 bar 永远不在结果里。

## 返回值

<ResponseField name="data" type="CryptoHistoricalResult" required>
  <Expandable title="CryptoHistoricalResult 字段">
    <ResponseField name="ticker" type="string" required>
      交易对，`BASE-QUOTE` 格式（如 `BTC-USD`）。
    </ResponseField>

    <ResponseField name="interval" type="string" required>
      K 线周期（`1h` / `4h` / `1d` / `1w`）。
    </ResponseField>

    <ResponseField name="prices" type="CryptoKlineBar[]" required>
      按时间正序返回的 K 线数组。仅含已收盘 candle。

      <Expandable title="CryptoKlineBar 字段">
        <ResponseField name="open" type="number" required>开盘价。</ResponseField>
        <ResponseField name="high" type="number" required>最高价。</ResponseField>
        <ResponseField name="low" type="number" required>最低价。</ResponseField>
        <ResponseField name="close" type="number" required>收盘价。</ResponseField>
        <ResponseField name="volume" type="number" required>基础资产成交量。</ResponseField>
        <ResponseField name="time" type="string" required>K 线开盘时间（ISO 8601 UTC）。</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">本次调用消耗的 credit（固定 `1`）。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</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 }
}
```

## 说明

<Tip>
  要 **最新行情**（价格 + 24h 涨跌）用 `crypto_snapshot`，那是另一个 primitive，不需要拉一串 K 线。`crypto_historical_klines` 只在你需要一系列 bar 时才用。
</Tip>

<Tip>
  首次查询某个 ticker + interval + range 可能较慢。同一窗口的后续查询通常更快。
</Tip>

<Tip>
  需要返回的 bar 数时直接读 `data.prices.length`；`meta` 只保留 credit 和可选 notice。
</Tip>

<Warning>
  **仅现货市场**。合约、永续、资金费率、持仓量都不暴露。
</Warning>

<Warning>
  **不支持分钟级**。`1m`、`5m`、`15m` 都不行 —— 只能用 `1h`、`4h`、`1d`、`1w`。
</Warning>

<Warning>
  **仅返回已收盘 candle**。当前未收盘的 bar 永远不在结果里。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // Recent 模式 —— 最近 30 根日线
    {
      "method": "tools/call",
      "params": {
        "name": "crypto_historical_klines",
        "arguments": { "ticker": "BTC-USD", "interval": "1d", "limit": 30 }
      }
    }

    // Range 模式 —— 明确时间窗口
    {
      "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 模式
    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 模式
    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 模式返回 {len(resp['data']['prices'])} 根 bar")
    ```

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

    # Range 模式
    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>

## 完整参数参考

<Accordion title="crypto_historical_klines — 请求参数" icon="sliders">
  <ParamField query="ticker" type="string" required>
    交易对，`BASE-QUOTE` 格式。例：`BTC-USD`、`ETH-USD`、`SOL-USD`。
  </ParamField>

  <ParamField query="interval" type="string" required>
    K 线周期。可选值：`1h`、`4h`、`1d`、`1w`。不支持分钟级。
  </ParamField>

  <Tabs>
    <Tab title="Recent 模式">
      只传 `limit`（或省略走 interval 默认值）。返回最近 N 根已收盘 candle。

      <ParamField query="limit" type="integer">
        最近多少根 candle。按 interval 自适应默认：`1h` = 24，`4h` = 42，`1d` = 30，`1w` = 12。最大 `200`。
      </ParamField>
    </Tab>

    <Tab title="Range 模式">
      `start_time` 和 `end_time` 必须同时传。返回闭区间内的所有已收盘 candle。

      <ParamField query="start_time" type="string" required>
        起始时间，ISO 8601 UTC（如 `2026-03-01T00:00:00Z`）。必须与 `end_time` 同时使用。
      </ParamField>

      <ParamField query="end_time" type="string" required>
        结束时间，ISO 8601 UTC。必须与 `start_time` 同时使用。
      </ParamField>

      <ParamField query="limit" type="integer">
        可选安全上限（最大 `200`）。Range 模式下 `limit` 只作 guard，真正决定结果的是时间窗口。
      </ParamField>

      <Warning>
        单独传 `start_time` 或 `end_time` 会返回 `400`。
      </Warning>
    </Tab>
  </Tabs>
</Accordion>

## 相关接口

<Columns cols={2}>
  <Card title="加密货币实时快照" icon="bolt" href="/zh-CN/api/prices/crypto-snapshot">
    交易对的当前价格 + 24h 涨跌 —— 只关心"现在"时用这个。
  </Card>

  <Card title="美股历史日线" icon="square-chart-gantt" href="/zh-CN/api/prices/equity-historical">
    同样的 Recent / Range 双模式，作用在美股标的（日线）。
  </Card>
</Columns>