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

# 美股历史日线

> 美股历史 OHLCV 日线 —— 用日期窗口筛选，再用 limit/take_from 取有界的一段，含 adjusted close、分红、拆股。

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

<Badge color="green" icon="circle-check">已上线</Badge>
 
<Badge color="gray" size="sm">免费 · daily bars</Badge>

## 它为 Agent 做什么

`equity_historical_prices` 返回单个美股标的（NYSE / NASDAQ）的历史 OHLCV 日线，附 `adjusted_close`、`dividend`、`stock_split`。它是 agent 拿历史价格做收益率、回撤、回测的 **历史价格 primitive** —— 不是用来取最新报价的工具。

用 `start_date` 和/或 `end_date` 先过滤候选窗口，再用 `limit` 和 `take_from` 决定保留哪一端。返回顺序始终是旧到新。**只返回已收盘的交易日**，当日未收盘的 bar 永远不在结果里。

## 返回值

<ResponseField name="data" type="EquityHistoricalResult" required>
  <Expandable title="EquityHistoricalResult 字段">
    <ResponseField name="ticker" type="string" required>
      美股 ticker（如 `AAPL`）。
    </ResponseField>

    <ResponseField name="interval" type="string" required>
      固定 `"1d"`，仅支持日线。
    </ResponseField>

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

      <Expandable title="EquityDailyBar 字段">
        <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="adjusted_close" type="number" required>分红/拆股复权后收盘价。算收益率统一用这个字段。</ResponseField>
        <ResponseField name="dividend" type="number" required>当日分红金额（无分红为 `0`）。</ResponseField>
        <ResponseField name="stock_split" type="number" required>当日拆股比例（无拆股为 `0`）。</ResponseField>
        <ResponseField name="time" type="string" required>交易日（`YYYY-MM-DD`）。</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">固定 `0` —— 本接口免费。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>
<ResponseField name="meta.notice" type="string">仅在候选窗口内的数据多于实际返回条数时出现 —— 也就是结果被 `limit` 截断了。这句话提示 agent 缩小窗口或把查询拆成多次：`More data exists in the requested window than the items returned; narrow the window or split the query to see more.`</ResponseField>

```json title="200 OK · equity_historical_prices" expandable theme={null}
{
  "data": {
    "ticker": "AAPL",
    "interval": "1d",
    "prices": [
      {
        "open": 178.50,
        "high": 182.30,
        "low": 177.80,
        "close": 181.20,
        "volume": 52340000,
        "adjusted_close": 181.20,
        "dividend": 0.24,
        "stock_split": 0,
        "time": "2025-03-28"
      },
      {
        "open": 181.00,
        "high": 183.50,
        "low": 180.20,
        "close": 182.90,
        "volume": 48120000,
        "adjusted_close": 182.90,
        "dividend": 0,
        "stock_split": 0,
        "time": "2025-03-31"
      }
    ]
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 99 }
}
```

## 说明

<Tip>
  **算收益率统一用 `adjusted_close`** —— 它已经处理了分红和拆股。原始 `close` 只在画 K 线图等纯展示场景才适合。
</Tip>

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

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

<Warning>
  **仅美股**（NYSE / NASDAQ）。不含非美股 ADR，不含国际市场。
</Warning>

<Warning>
  **仅日线**。分钟级（`1m`、`5m`、`15m`）不支持。需要 `1h` 常规交易时段 bar，请用 [`equity_intraday_prices`](/zh-CN/api/prices/equity-intraday)。
</Warning>

<Warning>
  **没有实时报价**。当日未收盘的 bar 不在结果里。要拿"最新价"用别的工具。
</Warning>

<Warning>
  覆盖范围很广，但不保证所有标的都有数据。少数流动性差的 ticker 偶尔会返回空。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 不传日期边界 —— 最近 30 个交易日
    {
      "method": "tools/call",
      "params": {
        "name": "equity_historical_prices",
        "arguments": { "ticker": "AAPL", "limit": 30 }
      }
    }

    // 日期窗口内最早 10 根
    {
      "method": "tools/call",
      "params": {
        "name": "equity_historical_prices",
        "arguments": {
          "ticker": "MSFT",
          "start_date": "2025-04-01",
          "end_date": "2025-04-30",
          "limit": 10,
          "take_from": "earliest"
        }
      }
    }
    ```

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

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

    # 不传日期边界 —— 最近的若干根
    resp = requests.get(
        "https://api.llmquantdata.com/api/equity/historical",
        headers=headers,
        params={"ticker": "AAPL", "limit": 30},
    ).json()
    for bar in resp["data"]["prices"]:
        print(f"{bar['time']}  C={bar['close']:.2f}  V={bar['volume']}")

    # 日期窗口内最早 10 根
    resp = requests.get(
        "https://api.llmquantdata.com/api/equity/historical",
        headers=headers,
        params={
            "ticker": "MSFT",
            "start_date": "2025-04-01",
            "end_date": "2025-04-30",
            "limit": 10,
            "take_from": "earliest",
        },
    ).json()
    print(f"Bounded query returned {len(resp['data']['prices'])} bars")
    ```

    ```bash cURL theme={null}
    # 不传日期边界 —— 最近的若干根
    curl "https://api.llmquantdata.com/api/equity/historical?ticker=AAPL&limit=30" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

    # 日期窗口内最早 10 根
    curl "https://api.llmquantdata.com/api/equity/historical?ticker=MSFT&start_date=2025-04-01&end_date=2025-04-30&limit=10&take_from=earliest" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<Accordion title="equity_historical_prices — 请求参数" icon="sliders">
  <ParamField query="ticker" type="string" required>
    美股 ticker（如 `AAPL`、`MSFT`、`BRK.B`、`^GSPC`（S\&P 500 指数））。
  </ParamField>

  <ParamField query="start_date" type="string">
    可选 inclusive 下边界，`YYYY-MM-DD`（如 `2025-04-01`）。
  </ParamField>

  <ParamField query="end_date" type="string">
    可选 inclusive 上边界，`YYYY-MM-DD`。
  </ParamField>

  <ParamField query="limit" type="integer" default={30}>
    边界过滤后最多返回多少个交易日。默认 `30`，最大 `200`。
  </ParamField>

  <ParamField query="take_from" type="string" default="latest">
    当过滤后候选超过 `limit` 时保留哪一端：`latest` 或 `earliest`。输出仍按时间正序。
  </ParamField>

  <Warning>
    `take_from=earliest` 需要 `start_date`。如果同时传两个日期边界，`start_date` 不能晚于 `end_date`。
  </Warning>
</Accordion>

## 相关接口

<Columns cols={2}>
  <Card title="美股盘中行情" icon="clock" href="/zh-CN/api/prices/equity-intraday">
    同一批美股的 `1h` 常规交易时段 bar —— 短窗口搭档。
  </Card>

  <Card title="加密货币历史 K 线" icon="chart-line" href="/zh-CN/api/prices/crypto-historical">
    同样的有界 historical-series 形状，作用在加密货币交易对（含小时级）。
  </Card>

  <Card title="MCP Server 接入" icon="plug" href="/zh-CN/integration/mcp-server">
    60 秒接入 Claude / Cursor / 任意 agent harness。
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.