美股数据 API 全量接入完整指南：一套 API 覆盖实时行情、盘前盘后、财报日历与 AI 工作流

我早期接美股数据时，以为拿到 AAPL 的实时价格和日线 K 线就够了。REST 调通，K 线能画，看起来一切正常。

后来才发现，盘前盘后的 5.5 小时可交易窗口我完全没覆盖，财报日历是手动维护的，字段名和文档对不上——写代码要反复试错，AI Agent 也调不通数据，因为只有 REST 没有 MCP。

这些坑不是因为接口调不通，而是因为一开始就没看清美股数据到底有几层。

美股数据不是接口问题，是分层问题。

这篇文章要做两件事：第一，把美股数据的五层结构摊开，让你在写第一行接入代码前就能画出数据架构图；第二，以一套统一 API 服务为具体参考，把每一层的实际字段、参数、边界条件讲清楚。读完你就能判断自己的项目需要接哪几层、在哪一层停。

美股数据能力全景图

先看整体结构。从行情到 AI 接入，是一条五层的链路：

┌─────────────────────────────────────────────────────────────┐
│                  Layer 5：AI-native 接入（怎么用）            │
│   REST  │  WebSocket  │  MCP  │  CLI  │  Skill              │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                Layer 4：基本面（公司值多少）                  │
│  财务三表 │ 估值 │ 行业 │ 股东 │ 公司档案                     │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│              Layer 3：公司行动（除权除息、拆股）               │
│  分红 │ 回购 │ 公司行动 │ 除权日                              │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│           Layer 2：事件驱动（什么时候发生什么）                │
│  财报日历 │ 预估/实际 EPS │ 营收预估/实际                     │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│              Layer 1：行情（市场发生了什么）                   │
│  快照 │ K线 │ 盘前盘后 │ 盘口 │ 逐笔 │ 交易时段                │
└─────────────────────────────────────────────────────────────┘

Layer 1 是地基，Layer 2–4 是纵深，Layer 5 是出口。五层缺一层，你的数据管道就会在某个节点断掉。

下面的内容以 TickDB 为参考实现，它的美股能力覆盖了这五层。先建立结构，再看细节。

五层能力速查

这张表的正确读法：不是让你五层全接，而是让你先确认自己的项目在哪一层停。停在 Layer 1 可以，但要知道 Layer 2 的缺口会在财报季暴露。

你是哪类读者

你 → 打开文章
       │
       ├── 个人量化开发者
       │     └─→ Layer 1 + 2 + 最小可用组合
       │
       ├── 小团队数据工程师
       │     └─→ Layer 1–4 + 数据架构建议
       │
       ├── AI 工具使用者
       │     └─→ Layer 5 + Agent 取数工作流
       │
       └── 金融应用团队
             └─→ Layer 5 + 边界 + POC 验收清单

Layer 1：行情——美股从 4AM ET 就开始交易，A 股 9:30 才有第一笔

这是第一层。你接了吗？

A 股 9:30 开盘，9:15 集合竞价，盘前没有连续交易。美股不一样：东部时间 4:00 开始盘前交易，9:30 正式开盘，16:00 收盘，16:00–20:00 盘后交易。

一天 16 个小时有价格。如果你只接 last_price，盘前盘后的价格你完全拿不到，策略漏掉每天 5.5 小时的可交易窗口。

盘前盘后行情数据怎么用 API 接入，和 A 股有什么区别？ 这个问题就在这里展开。

实时快照

我实测了 get_ticker，返回里盘前、盘中、盘后是三个独立嵌套对象：

import requests

API_KEY = "your_api_key"
BASE_URL = "https://api.tickdb.ai/v1"
HEADERS = {"X-API-Key": API_KEY}

resp = requests.get(
    f"{BASE_URL}/market/ticker",
    params={"symbols": "AAPL.US"},
    headers=HEADERS,
)
data = resp.json()["data"][0]

# 三个时段的报价对象
pre = data.get("pre_market_quote", {})
post = data.get("post_market_quote", {})
overnight = data.get("overnight_quote", {})

print("盘前 last_done:", pre.get("last_done"))
print("盘后 last_done:", post.get("last_done"))
print("夜盘 last_done:", overnight.get("last_done"))
print("时间戳:", data.get("timestamp"))

运行后你应该看到：pre_market_quote、post_market_quote、overnight_quote 三个对象，每个包含 last_done、timestamp、volume、quote_volume、high、low、prev_close。时间戳是整数 Unix 毫秒，例如 1789588801000。

注意我用 .get() 处理缺失。盘前盘后对象在非交易时段可能为空，不要假设每个标的、每个时刻都返回相同对象。

交易时段

我调用 GET /v1/market/trading-sessions?market=US，返回 data[0].trading_sessions[]，三段数值区间：

响应没有返回 pre_market、regular、post_market 的文本枚举。你需要在代码里自己做数值映射：

sessions = requests.get(
    f"{BASE_URL}/market/trading-sessions",
    params={"market": "US"},
    headers=HEADERS,
).json()["data"][0]["trading_sessions"]

SESSION_MAP = {1: "pre_market", 2: "post_market", None: "regular"}

for s in sessions:
    name = SESSION_MAP.get(s.get("trade_session"))
    print(f"{name}: {s['begin_time']} - {s['end_time']}")

K 线与历史行情

get_kline 可以取 AAPL 日线，返回 data.klines。复权支持 none、forward、backward。前复权适合实时信号，后复权适合历史比较分析，混用会产生系统性误差。

klines = requests.get(
    f"{BASE_URL}/market/kline",
    params={"symbols": "AAPL.US", "interval": "1d",
            "adjust": "forward", "limit": 20},
    headers=HEADERS,
).json()["data"]["klines"]

for k in klines[-3:]:
    print(k["timestamp"], k["open"], k["close"], k["volume"])

运行后你应该看到：最近 20 根日线，每根含 timestamp、open、high、low、close、volume。

盘口与逐笔

get_order_book 返回多档买卖盘，get_trades 返回逐笔成交。盘口对时延极度敏感，用之前必须验证目标市场的实际可用性，不能从接口存在推断全市场覆盖。本次实测为 L1 盘口，非 Level 2 深度。

Layer 1 的关键认知

如果你只接了 last_price，盘前盘后的 5.5 小时可交易窗口你完全没覆盖。

本层实测边界：以上字段基于 2026-09-17 对 AAPL.US 的单次调用。盘前报价是否从 4:00 ET 起持续可取、每只美股是否返回相同对象，待补测。

自建成本：如果你只需要日线，免费方案可以覆盖。但盘前盘后字段的完整性、trade_session 数值映射、WebSocket 断线重连，自建需要持续维护。到这里停，成本是几小时；要继续到 Layer 2，成本开始按周计算。

Layer 2：事件驱动——财报日历，全市场事件流才是正确打开方式

这是第二层。第一层加第二层，事件驱动策略的基础设施就有了。

我一开始以为财报日历是传入 AAPL 就返回 AAPL 的财报日期。实测发现不是。

TickDB 的 calendar 端点返回的是全市场 report 事件流。我调用：

GET /v1/fundamentals/calendar?market=US&category=report&from=2026-09-17&to=2026-12-31

返回结构是 data.events[]。每个事件包含 category、event_datetime、symbol、event_type、date_type、content、market、counter_name、currency、star，以及 data[]。后者通过 value_type 区分 estimate_eps、estimate_revenue、actual_eps、actual_revenue，数值在 value_raw / value_text。

这反而更强。

按标的查，只能做单标的的事件响应；全市场事件流，可以一次拉全市场，为自己的股票池做批量事件过滤。这才是量化团队真正需要的数据管道设计。

resp = requests.get(
    f"{BASE_URL}/fundamentals/calendar",
    params={
        "market": "US",
        "category": "report",
        "from": "2026-09-17",
        "to": "2026-12-31",
    },
    headers=HEADERS,
)
events = resp.json()["data"]["events"]

# 按自己的股票池过滤
watchlist = {"AAPL.US", "MSFT.US", "NVDA.US"}
my_events = [e for e in events if e["symbol"] in watchlist]

for e in my_events[:5]:
    metrics = {d["value_type"]: d["value_raw"] for d in e.get("data", [])}
    print(e["symbol"], e["event_datetime"], metrics.get("estimate_eps"))

运行后你应该看到：你的股票池内的财报事件，以及 EPS / 营收的预估和实际值。

注意：本次拉取短窗口达到单次上限 500 条，未在返回集合中找到 AAPL.US。如果你需要 AAPL 的预计财报发布日，也可以从公司行动端点观察 FinancialReport 与 ReportDate 事件。

美股 API 如何同时获取实时行情、财报日历和基本面数据？ 到这里，实时行情有了，财报日历有了，基本面在 Layer 4。

Layer 2 的关键认知

财报日历不是按标的查的，是全市场事件流。这才是事件驱动策略的正确打开方式。

本层实测边界：以上结构基于 2026-09-17 对美股全市场 report 事件的单次调用。AAPL 直属日历样本待补，按标的筛选契约待产品提供。

自建成本：如果你只做单标的，自建一个财报日历手动维护也行。但如果你有股票池，每次财报季都要重新查日期——拉全市场、按 symbol 过滤、处理预估 vs 实际的 value_type 区分、对齐 event_datetime 时区、维护财报季日历更新。这些工程量，自己算。

Layer 3：公司行动——不处理除权跳空，回测结果不可信

这是第三层。

公司行动是价格非市场跳空的来源。除权除息日，股价会向下跳空，这不是市场下跌，是分红除权。如果回测框架不处理，系统会把除权跳空误判为价格下跌信号。

我实测了两个端点：

分红样本包含 AAPL 的现金分红事件。公司行动样本还出现了 FinancialReport 与 ReportDate 事件——可以观察到预计财报发布日。

divs = requests.get(
    f"{BASE_URL}/fundamentals/dividends",
    params={"symbol": "AAPL.US", "limit": 5},
    headers=HEADERS,
).json()["data"]["events"]

for d in divs:
    print(d["ex_date"], d["amount"], d["currency"], d["type"])

运行后你应该看到：AAPL 的历史分红记录，含除权日、金额、币种、分红类型。

注意：本次事件中未观察到结构化 split_ratio 字段。如果你需要拆分比例，需要自己从 act_desc 解析或另找数据源。这是边界。

Layer 3 的关键认知

不处理除权跳空，回测在历史上存在公司行动的时间段结果不可信。

本层实测边界：以上字段基于 2026-09-17 对 AAPL.US 的单次调用。结构化拆分比例字段未验证，不承诺提供。

自建成本：分红和公司行动的数据可以手动维护，但每次财报季、每次除权都要更新。如果你有几十只股票池，这就是持续投入。

Layer 4：基本面——字段名不是你以为的那个

这是第四层。字段名不对，估值比较就是错的。

我第一次调 financials/latest 时用了 period_type=quarter，返回 HTTP 400、业务码 40001，消息是 period_type contains an unsupported value。

后来才发现要用 period_type=q1,q2,q3,q4。

字段名也不是 revenue 和 net_income。实际是 OperatingRevenue、NetProfit、EPS。响应是 data.rows[] 的字段行形式，每行有 field_name、value、fiscal_year、fiscal_period、period_type、period_end、currency、yoy。

resp = requests.get(
    f"{BASE_URL}/fundamentals/financials/latest",
    params={
        "symbol": "AAPL.US",
        "kind": "IS",
        "n": 4,
        "period_type": "q1,q2,q3,q4",
    },
    headers=HEADERS,
)
rows = resp.json()["data"]["rows"]

# 字段行形式，需要按 field_name 过滤
for r in rows:
    if r["field_name"] in ("OperatingRevenue", "NetProfit", "EPS"):
        print(r["fiscal_year"], r["fiscal_period"], r["field_name"], r["value"])

运行后你应该看到：AAPL 最近四个季度的利润表，以字段行形式呈现收入、净利润、EPS。

P/E 不在利润表里。我另行调用 /v1/fundamentals/valuation/latest?symbol=AAPL.US，实际路径是 data.metrics.PE.value。

val = requests.get(
    f"{BASE_URL}/fundamentals/valuation/latest",
    params={"symbol": "AAPL.US"},
    headers=HEADERS,
).json()["data"]["metrics"]

print("PE:", val["PE"]["value"])

所以我现在养成了一个习惯：先调 financials/fields 查字段字典，再写代码。

Layer 4 的关键认知

字段名不对，估值比较就是错的。先查字段字典，再写代码。

本层实测边界：以上字段基于 2026-09-17 对 AAPL.US 的单次调用。字段字典以官方接口文档为准。

自建成本：财务数据可以手动整理，但财年起点不同、GAAP vs non-GAAP 口径不同、报告期对齐、币种统一——这些工程量，自己算。

美股财务字段的 5 个常见错误

这张表是我踩过的坑。按文档写代码会出错，这是对的写法。

这张表就是收藏的理由。下次写代码前先看一眼。

Layer 5：AI-native 接入——只有 REST 的金融数据，LLM 工作流会断连

这是第五层。五层齐了，这就是美股数据的全貌。

Agent 工作流中的行情数据，必须在模型推理之前到位。让模型用记忆猜价格，是把分析过程变成幻觉生成过程。

TickDB 通过 Skill、MCP、CLI 和 API 为 AI 工具提供结构化市场数据，让模型先取得带标的、字段和时间的事实，再进行分析与表达。

REST

13 条路径，覆盖行情、基本面、日历。标准 HTTP 接口，X-API-Key 认证。研究、回测、批量拉取的首选。

WebSocket

我实测了连接和订阅格式。订阅体是：

{"cmd":"subscribe","data":{"channel":"ticker","symbols":["AAPL.US"]}}

连接 URL 是 wss://api.tickdb.ai/v1/realtime?api_key=[REDACTED]。我收到了两条控制确认：cmd="connected"、code=0；以及 cmd="subscribe"、code=0、data.channel="ticker"。

随后等待窗口未收到 ticker 数据消息。所以这篇文章只展示握手和订阅格式。推送字段、频率、盘前盘后推送行为，等我在美股交易时段补测后再写。

生产级 WebSocket 必须实现重连逻辑，区分正常断线和密钥过期（close code 1008）。

MCP

Hosted MCP 的 get_ticker 协议层实测成功。JSON-RPC tools/call 的工具名是 get_ticker，参数是 symbols/type，结果外层是 content[].text。

# MCP 工具调用（协议层示意）
{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
        "name": "get_ticker",
        "arguments": {"symbols": "AAPL.US", "type": "stock"}
    }
}

注意：这是协议层实测，不是 AI 聊天界面中的工具调用证据。我不声称 Claude / Cursor 等 AI 客户端已调用。

CLI

CLI 是 AI Agent 和工作流的命令行入口，官方提供 16 个原生命令。本次未运行实际数据命令，原因是安全策略拒绝将密钥传给临时下载的 npm 包。所以我不展示 CLI 输出。这是边界。

Skill

72 个核心美股标的 AI 直接查询。

Layer 5 的关键认知

AI 工作流中的行情数据，必须在模型推理之前到位。让模型用记忆猜价格，就是把分析过程变成幻觉生成过程。

本层实测边界：WebSocket 仅验证握手和订阅确认，推送字段待补测；MCP 仅验证协议层 tools/call，不声称 AI 客户端已调用；CLI 本次未验证。

自建成本：自己包装 REST 为 AI 可调用工具，需要处理认证、字段标准化、错误码、工具描述，且没有标准化 MCP 入口。自建不是不能做，是每次上游字段变更都要同步维护。

项目阶段路径表

不同阶段的人，不需要接同一套数据。

五层验收清单

对照这张表，逐层确认自己的项目需要哪几层：

把这张表填完，你的美股数据架构图就出来了。

文末的 Python 五层验收脚本，复制后填入 API Token，运行后观察各层是否返回预期字段。

结尾

美股数据不是接口问题，是分层问题。

接入前先确认项目需要哪几层，漏接事件驱动层是最常见的低成本规避错误。

你现在就能做的一件事：打开自己的策略代码，对照上面的五层验收清单，看看每一层数据你是否已经接入或明确不需要。然后复制文末的验收脚本跑一遍，你会知道自己缺了哪一层。

关于本文参考的统一数据服务

本文全程以 TickDB 作为参考实现，把美股数据的五层能力落到具体的接口、字段和边界。

它适合什么人？

• 个人量化开发者：第一次接美股数据，想用一套 API 把五层都接上，不想自己拼多源。
• 小团队数据工程师：要建数据管道，先看清美股数据有几层，再决定用哪一层。
• AI 工具使用者：想让 Agent 取到带时间戳的结构化数据，而不是靠模型记忆猜价格。
• 金融应用团队：需要多市场统一接入、断线重连、错误码规范的工程化数据层。

它不适合什么人？

• 已经有完整的数据管道，只想替换其中某一个接口的团队——本文的能力对照仍然有用，但不一定需要换整套服务。
• 只需要免费方案就能覆盖全部需求的场景——本文全篇讨论的是“自建数据层的成本有多高”，如果你的自建成本极低，不需要额外付费。

如果决定试一下，怎么开始？

先按五层验收清单，列出自己策略实际需要的数据层。然后从最小可用组合入手——多数个人量化开发者只需要 Layer 1（K 线含复权 + 实时快照 + 盘前盘后）+ Layer 2（财报日历）。跑通之后再决定是否扩展到 Layer 3–5。

附：五层验收脚本

"""
US-FULL-01 五层验收脚本
运行前填入你的 API Key
"""

import requests

API_KEY = "your_api_key"
BASE_URL = "https://api.tickdb.ai/v1"
HEADERS = {"X-API-Key": API_KEY}


def check_layer_1():
    """Layer 1: 实时行情 + 盘前盘后"""
    try:
        data = requests.get(
            f"{BASE_URL}/market/ticker",
            params={"symbols": "AAPL.US"},
            headers=HEADERS,
        ).json()["data"][0]
        has_pre = "pre_market_quote" in data
        has_post = "post_market_quote" in data
        print(f"Layer 1: {'PASS' if has_pre and has_post else 'FAIL'}")
        return has_pre and has_post
    except Exception as e:
        print(f"Layer 1: FAIL - {e}")
        return False


def check_layer_2():
    """Layer 2: 财报日历"""
    try:
        events = requests.get(
            f"{BASE_URL}/fundamentals/calendar",
            params={"market": "US", "category": "report",
                    "from": "2026-09-17", "to": "2026-12-31"},
            headers=HEADERS,
        ).json()["data"]["events"]
        print(f"Layer 2: {'PASS' if len(events) > 0 else 'FAIL'} ({len(events)} events)")
        return len(events) > 0
    except Exception as e:
        print(f"Layer 2: FAIL - {e}")
        return False


def check_layer_3():
    """Layer 3: 公司行动与股息"""
    try:
        events = requests.get(
            f"{BASE_URL}/fundamentals/dividends",
            params={"symbol": "AAPL.US", "limit": 5},
            headers=HEADERS,
        ).json()["data"]["events"]
        print(f"Layer 3: {'PASS' if len(events) > 0 else 'FAIL'} ({len(events)} events)")
        return len(events) > 0
    except Exception as e:
        print(f"Layer 3: FAIL - {e}")
        return False


def check_layer_4():
    """Layer 4: 基本面季报"""
    try:
        rows = requests.get(
            f"{BASE_URL}/fundamentals/financials/latest",
            params={"symbol": "AAPL.US", "kind": "IS",
                    "n": 4, "period_type": "q1,q2,q3,q4"},
            headers=HEADERS,
        ).json()["data"]["rows"]
        fields = {r["field_name"] for r in rows}
        ok = "OperatingRevenue" in fields and "NetProfit" in fields
        print(f"Layer 4: {'PASS' if ok else 'FAIL'}")
        if not ok:
            print("  提示：检查字段名是否为 OperatingRevenue/NetProfit，"
                  "参数是否为 q1,q2,q3,q4")
        return ok
    except Exception as e:
        print(f"Layer 4: FAIL - {e}")
        print("  提示：period_type 不能用 quarter，要用 q1,q2,q3,q4")
        return False


def check_layer_5():
    """Layer 5: AI-native 接入（MCP 协议层）"""
    print("Layer 5: 需单独配置 X-TickDB-Key 进行 MCP 测试")
    print("  参考：JSON-RPC tools/call，工具名 get_ticker，参数 symbols/type")
    return None


if __name__ == "__main__":
    print("=" * 50)
    print("美股数据五层验收")
    print("=" * 50)
    results = {
        "Layer 1": check_layer_1(),
        "Layer 2": check_layer_2(),
        "Layer 3": check_layer_3(),
        "Layer 4": check_layer_4(),
        "Layer 5": check_layer_5(),
    }
    print("=" * 50)
    passed = sum(1 for v in results.values() if v is True)
    print(f"通过: {passed}/4 (Layer 5 需单独测试)")
    print("对照五层结构，确认你的项目需要哪几层。")

附录 A：接口示例

附录 B：错误码速查

附录 C：常见问题

Q：财报日历为什么不能按标的查？

A：TickDB 的 calendar 端点返回全市场事件流，通过 symbol 字段过滤。这反而更适合做股票池的批量事件过滤。如果你需要 AAPL 的预计财报发布日，可以从公司行动端点观察 FinancialReport 与 ReportDate 事件。

Q：字段名为什么和文档不一样？

A：我实测时发现 revenue 返回空，实际字段是 OperatingRevenue；net_income 实际是 NetProfit。建议先调 financials/fields 查字段字典，再写代码。

Q：WebSocket 推送字段为什么没写？

A：我实测了连接和订阅确认，但在等待窗口未收到 ticker 推送。推送字段、频率、盘前盘后推送行为，等美股交易时段补测后再写。

Q：CLI 为什么没写实测？

A：本次未运行 CLI 实际数据命令，原因是安全策略拒绝将密钥传给临时下载的 npm 包。CLI 是 AI Agent 和工作流的命令行入口，官方提供 16 个原生命令。

Q：MCP 示例能在 Claude / Cursor 里直接用吗？

A：MCP 协议层 tools/call 实测成功，但我不声称 Claude / Cursor 等 AI 客户端已调用。实际接入需要配置 X-TickDB-Key。

附录 D：实测证据索引

文中实测数据来自 2026-09-17 的 API 调用，样本标的为 AAPL.US。字段名、参数和接口行为以官方接口文档为准。WebSocket 推送字段、CLI 命令输出、AAPL 直属财报日历样本待补测。单次调用只证明本次密钥、样本、参数和时间；不证明持续可用性、完整覆盖、性能或投资结论。

通过 TickDB API 获取实时行情数据

一个 API 接入外汇、加密货币、美股、港股、A股、贵金属和全球指数的实时行情。支持 WebSocket 低延迟推送，免费开始使用。