美股行情API接入自查清单：能查价格 ≠ 接好了实时数据

能查到 AAPL 的价格，和"接好了实时行情"是两件事。

你把 GET /v1/market/ticker 调通，拿到了 last_price: 308.33，看板上的数字跳了一下。但过了一段时间你发现，这个数字再也没变过。你以为是接口限流了，加了重试——还是不变。最后发现，从第一天起你就用错了端点。

美股行情接入中很多"数据延迟"问题，不是网络慢，是概念没拆开。下面按"边界→参数→排错"三块拆干净。

一、三个边界：REST 快照、WebSocket 推送、交易窗口

做美股接入前，先把这三件事分开。混淆任意两个，都会导致"明明调通了却拿不到想要的数据"。

边界	它是什么	它不是什么
REST 快照	一次 HTTP 请求，返回那一刻的行情切片	不是持续更新的数据流；第二次请求之前，数据不会自己变
WebSocket 推送	建立长连接后，服务端推送连接期间的行情更新	不是"更快的 REST"；断线后不重连，数据就静默丢失，且不应假设断线期间的 tick 会自动回补
交易窗口	美股有盘中、盘前、盘后三段，具体时段见各交易所公告；是否返回盘前/盘后数据以接口文档及实测为准	不是所有接口默认返回全部时段数据；盘前盘后流动性不同，价格代表性也不同

类比：REST 快照像你每隔一段时间拍一张照片；WebSocket 推送像一台一直在录的视频机。照片能证明"那一刻存在"，但不能证明"两次拍照之间发生了什么"。交易窗口则决定了你拍到的到底是正式比赛、热身还是加时赛——三个阶段的"比分"意义不同。

REST 查到了价格 ≠ 数据在自动更新。 如果你只调了 ticker 端点、没建 WebSocket 连接、也没设置轮询，那看板上永远是第一次请求的那一个价格。这不是接口问题，是架构设计问题。

二、四个最容易写错的参数和字段

以下四个错误，每个都能独立导致"调通了但数据不对"。

正确写法	常见错误	为什么错	后果
symbols=AAPL.US	symbol=AAPL.US	ticker 接口参数是复数 symbols，不是单数 symbol	请求不报错但返回空数组，或返回意料之外的品种
response["data"][0]["last_price"]	response["data"][0]["close"]	ticker 快照用 last_price，close 是 K 线接口的字段名	取到 None 或 KeyError，看板价格显示为空
response["data"][0]["timestamp"]	用它推断"数据新鲜度"	timestamp 是行情生成时刻的毫秒 UTC 时间戳，不等于数据到达你服务器的时间	在休市时段，timestamp 是收盘时的时间——数据正确但存在时间差
WebSocket 断线后重连	以为重连就自动补数据	WebSocket 推送的仅是连接期间的行情更新；断线期间的数据是否补回取决于具体实现，不应假设自动回补	回测或监控系统可能出现数据空洞，且不易察觉

核心概念区分：timestamp（字段精度）≠ 数据新鲜度

timestamp 告诉你这笔行情是什么时候生成的，单位毫秒 UTC。数据年龄 = 当前时间与 timestamp 的差值，它不等于任何延迟承诺，也不等同于高频可用性。

在盘中，数据年龄通常较小；在休市时段，timestamp 停在收盘那一刻，而数据年龄持续增长——你请求到的数据"时间戳正确"但"已有一段时间不更新"。把两者混为一谈，就会在周末看到"最新价格"而实际上那是周五收盘价。

三、最小验证代码：一次正确的 REST ticker 查询

下面的代码只做一件事：用正确的参数和字段名，完成一次美股行情快照查询。

安装依赖

pip install requests python-dotenv

代码

import os
import requests
from dotenv import load_dotenv

load_dotenv()
API_KEY = os.getenv("TICKDB_API_KEY")
BASE_URL = "https://api.tickdb.ai"

def get_us_stock_ticker(symbols: list[str]) -> list[dict]:
    """
    查询美股实时行情快照。
    正确用法：
    - 参数名是 symbols（复数），不是 symbol
    - 返回字段用 last_price，不是 close
    - timestamp 是毫秒 UTC，不直接等于数据新鲜度
    - 根响应是对象，行情数组在 response["data"] 中
    """
    resp = requests.get(
        f"{BASE_URL}/v1/market/ticker",
        params={"symbols": ",".join(symbols)},  # symbols，复数
        headers={"X-API-Key": API_KEY},
        timeout=10
    )
    data = resp.json()

    if data.get("code") != 0:
        raise RuntimeError(f"API 错误: code={data.get('code')}")

    results = []
    # response["data"] 是数组，不是 response["data"]["products"]
    for item in data["data"]:
        results.append({
            "symbol": item["symbol"],
            "last_price": item["last_price"],  # ticker 用 last_price，不是 close
            "timestamp_ms": item["timestamp"],  # 毫秒 UTC，不做 ×1000 转换
            "volume_24h": item.get("volume_24h")
        })
    return results

if __name__ == "__main__":
    tickers = get_us_stock_ticker(["AAPL.US"])
    for t in tickers:
        print(f"{t['symbol']}: last_price={t['last_price']}, timestamp_ms={t['timestamp_ms']}")

真实返回结构示例（示意性数据）

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "symbol": "AAPL.US",
      "type": "stock",
      "last_price": "308.33",
      "timestamp": 1779825600000
    }
  ]
}

核心是参数名和字段名的准确性，不是请求次数。 上面这段代码把美股 ticker 查询中最容易出错的三个点全部卡住了：symbols 复数、response["data"] 数组路径、last_price 字段名。任何一个写错，都不会报语法错误——它们会在生产环境静默返回空数据或错误字段。

四、排错清单：5 分钟自查

跑完上面代码后，如果你的看板仍然"数据不对"，按下面顺序逐一排查：

序号	检查项	正确结果	如果不对，优先查什么
1	端点是否正确	GET /v1/market/ticker	确认没写成 /v1/market/kline 或其他端点
2	参数名是 symbols	URL 中为 symbols=AAPL.US	全局搜索 symbol=，全部替换为 symbols=
3	取字段用的是 last_price	代码中为 item["last_price"]	确认没写成 close（那是 K 线字段）
4	数据路径正确	response["data"][0]["symbol"] 能读到值	根响应是对象，确认访问了 data 键再取数组元素，不要写成 response["data"]["data"] 或直接对根响应取下标
5	timestamp 是毫秒	13 位数字	不做 ×1000 转换；不把 timestamp 当延迟指标
6	数据不更新	检查是否只有 REST 没建 WebSocket	REST 是一次快照，持续更新必须建 WebSocket 或设置轮询
7	非交易时段价格不变	检查美股交易时段	盘前、盘中、盘后时段见各交易所公告；周末和节假日无交易
8	WebSocket 数据有空洞	断线期间数据可能不自动回补	重连后需通过 REST 补拉缺失区间的数据，或查阅接口文档确认回放能力

五、当"接好一家"变成"接好四家"

上面的排查清单覆盖了单市场美股场景。如果你同时需要 A 股、港股和期货数据，跨市场的 symbol 格式、字段语义和交易时段差异会让排查清单翻倍。

能力维度	具体实现	解决的工程问题
多市场统一 symbol 格式	api.tickdb.ai 的 ticker 接口统一处理 AAPL.US、700.HK、600519.SH	不需要为每个市场写一套 symbol 校验正则
统一字段语义	所有市场的 ticker 均使用 last_price 和 timestamp（毫秒 UTC）	前端取数字段只需写一次，不会因市场不同而报 KeyError
统一错误处理体系	接口均返回标准业务码，HTTP 层可能伴随 429；错误处理逻辑可统一覆盖 HTTP 429 与业务码 3001	限流恢复策略只需实现一套，降低因市场差异导致的静默失败

如果你已经在 AI 编码环境中工作，TickDB 也提供 MCP 端点 https://mcp.tickdb.ai，可直接在 Claude Code、Cursor 等工具中调用行情数据，无需手写 REST 客户端。更多细节见 docs.tickdb.ai。

---

一个反直觉的问题：你用 GET /v1/market/ticker 在周六上午 10:00 查到了 AAPL 的 last_price: 308.33，timestamp 显示的是周五 16:00:00 ET 的毫秒时间戳。这个价格是"实时数据"吗？你的看板应该怎么标识它？欢迎在评论区留下你的判断逻辑。

---

本文仅讨论行情数据接入与工程实现，不构成任何投资建议。所有示例数据均为假设案例。

---

标签

TickDB / 美股行情 API / REST API / WebSocket / 实时数据 / AAPL / 工程接入 / 排错清单