摘要

接入实时行情 API 之前，最常见的错误不是接口调不通，而是把快照当成 K 线、用轮询替代推送、忽略 timestamp 精度导致策略时间错位。本文提供一份可复用的工程检查清单，覆盖数据粒度区分、REST / WebSocket / MCP 协议分工、symbol 格式与字段类型验证、限流重试与鉴权错误码处理，以及日志与授权边界。文中以 TickDB 的 REST、WebSocket、MCP 入口作为验证示例，帮助开发者根据自身场景做选择，而非看排名。

正文

0. 先给答案

选实时行情 API 的正确顺序是：先确定数据粒度和时效要求，再选择协议组合，最后验证字段、时间戳、错误处理和授权。以下清单帮助你逐步完成这三步核验，避免接入后才发现不匹配。

1. 问题场景：选行情 API 时最容易忽略的东西

你打开一家行情数据源的文档，看到“覆盖全球市场”“提供实时数据”，于是注册、拿到 Key、发了一个 GET /ticker?symbol=AAPL。返回 200，有价格，看起来一切正常。

但以下几件事可能正在发生：

• 你拿到的是 15 分钟延迟的快照，不是实时价
• 你用的接口是 K 线查询，close 字段是上一根 K 线的收盘价，不是当前最新成交价
• timestamp 是秒级，但你的策略按毫秒解析，时间偏移了几十倍
• 请求失败时只返回 HTTP 500，没有错误码，你的脚本在盲重试中打光配额

选型的核心之一是确认接口设计能否满足工程场景的关键约束，而不是比谁的文档页数多或覆盖品种广。本文不推荐任何单一数据源，而是给出一份通用检查清单，帮助你在接入前把关键边界核对一遍。

2. 场景决策：先搞清楚你要做什么

不同工程场景对行情数据的需求差异巨大。以下场景决策表帮助你在动手看接口文档之前，先定位自己属于哪种类型。

工程场景	数据粒度需求	推荐协议	典型触发条件
看板展示 / 盘面监控	快照	REST 定时轮询 或 WebSocket 推送	分钟级刷新即够用选 REST，需要盘中实时跳价选 WebSocket
AI Agent 对话查询	快照	MCP	用户用自然语言提问，需要模型自动调用工具获取数据
回测 / 技术指标计算	K 线	REST 批量下载	需要等间隔 OHLCV 序列，一次性拉取全量历史数据
批量数据采集 / ETL	快照或 K 线	REST 分页拉取	定时任务每天拉取全市场数据，关注请求配额和分页逻辑
微观结构 / 成交量分析	逐笔成交	WebSocket 或 REST 历史查询	需要每笔成交的价格、数量、方向，数据量远大于快照
盘口 / 流动性监控	订单簿	WebSocket 增量推送	需要多档 bids/asks 及其变化过程，快照会丢失中间变化

使用方式：先在上表找到自己的场景，记下对应的数据粒度和推荐协议，再去检查数据源是否提供这两种能力。如果一个数据源只提供 REST 而没有 WebSocket，而你的场景需要盘中实时推送，就需要在架构上自己补轮询层。

3. 数据粒度：快照、K 线、逐笔、报价不是一个东西

同样叫“行情数据”，底层的数据粒度完全不同。第一步就是区分以下四类，明确自己需要哪一种。

数据粒度	典型接口名	返回内容	更新方式	典型用途	选错的后果
快照	ticker	最新价、涨跌幅、成交量、最高/最低价	按请求时刻返回切片	AI Agent 单次查询、看盘面板	把 ticker 当 K 线回测：last_price 序列不等间隔，技术指标计算失真
K 线	kline / candlestick	OHLCV 数组，按周期聚合	按 interval 返回历史序列	回测、技术指标计算	已完成 K 线的 close 不等于实时快照；当前未完成 K 线的 close 可能仍在更新
逐笔成交	trades / ticks	每笔成交价格、数量、方向	流式推送或历史查询	微观结构分析、成交量分布	用 ticker 替代逐笔：看不到单笔成交细节和成交方向
报价/订单簿	order_book / depth	多档 bids / asks 价量	快照或增量推送	盘口分析、流动性监控	把订单簿快照当实时推送：盘口变化过程完全丢失

检查方法：读接口文档的字段说明，确认返回字段是否包含 OHLC 聚合（K 线）、单笔成交明细（逐笔）或多档挂单（订单簿）。如果文档只写“行情数据”而不区分粒度，这就是一个需要警惕的信号。

4. 协议分工：REST、WebSocket、MCP 各司其职

拿到数据之后，第二个关键选择是“用什么协议获取数据”。三种协议各有适用场景，没有哪个是万能方案。

协议	获取方式	适用场景	不适合场景
REST	客户端发起 HTTP 请求，服务端返回 JSON	定时轮询、批量下载、回测数据准备、AI Agent 单次查询	盘中持续推送、专业低延迟场景
WebSocket	服务端主动推送，客户端保持长连接	盘中实时行情、逐笔成交、报价更新	历史数据查询、低频率轮询
MCP	AI 编码环境中的标准化工具调用	Claude Code、Cursor 等 AI Agent 对话式查询	持续推送、大批量下载、需要原生 SDK 的场景

核心认知：REST 是“问一次，给一次”；WebSocket 是“持续推”；MCP 是“让 AI 帮你问”。三者不是替代关系，是协作关系。一个同时覆盖历史回补和盘中监控的数据架构通常会涉及 REST 和 WebSocket 两种路径——REST 做历史回补和定时检查，WebSocket 做实时驱动。MCP 则可以作为 AI Agent 的统一查询层，让模型在对话中直接调用行情工具。对于低频轮询场景，仅用 REST 也完全够用。

选择数据源时，检查它是否提供你需要的协议组合。如果只提供 REST 而没有 WebSocket，需要在架构上自己补轮询层。

5. 接入前检查清单（核心章节）

以下检查项覆盖字段格式、错误处理、鉴权和日志。每一项都附带“错误假设 / 后果 / 正确验证”对照。

5.1 symbol 格式

错误假设：以为所有数据源都用同样的品种代码格式。
后果：填入 "茅台" 或 "600519" 无法识别，或返回其他市场的同名品种。

市场	TickDB 中的 symbol 格式示例（不代表全行业通用格式）
A 股	600519.SH、300750.SZ
港股	700.HK、9988.HK
美股	AAPL.US、TSLA.US

正确验证：不同数据源的 symbol 格式规范不同。取一份目标数据源的 symbol 列表样本，确认前缀、分隔符、交易所后缀规则。如果文档没有给出格式说明，直接发一个已知品种的请求来确认实际格式。

5.2 字段类型

错误假设：价格返回的是数值类型，可以直接参与计算。
后果：用 float 接收字符串价格导致精度丢失，或者直接做 last_price > 100 比较时，字符串比较产生意外结果。

正确验证：检查返回 JSON 中价格字段是否带引号。如果 last_price 是 "1675.00" 而非 1675.00，计算时必须用高精度数值类型（如 Python Decimal），避免浮点累积误差。

5.3 timestamp 精度

错误假设：所有接口的 timestamp 都是毫秒级。
后果：秒级时间戳被按毫秒解析，时间偏移 1000 倍。策略中计算数据新鲜度时，2 秒前的数据被判定为 2000 秒前，信号完全错位。

# 两个时间戳相差 1000 倍，但都是合法返回
{"timestamp": 1718323200}      # 秒
{"timestamp": 1718323200000}   # 毫秒

正确验证：查看文档中 timestamp 字段的精度说明；如果没有，用当前时间戳反向推算——13 位为毫秒，10 位为秒。不同端点（ticker / kline / trades）的精度可能不同，不要跨端点假设一致。

跨数据源场景的额外提醒：当同时使用 A 数据源（秒级 timestamp）和 B 数据源（毫秒级 timestamp）时，合并计算前需要显式规范化。规范化的核心动作是：识别每个数据源 timestamp 的位数 → 将秒级转换为毫秒（×1000）或反向 → 统一后再做时间对齐。如果跳过这个步骤，两个数据源的同一时刻会被解析为相差 1000 倍的时间点，信号对齐完全失效。

5.4 限流与重试

错误假设：请求失败时重试即可，不需要关注返回头。
后果：遇到 HTTP 429 时盲重试，连续触发限流，IP 被临时封禁。

正确验证：确认接口是否在限流时返回 Retry-After 响应头，或返回体中包含明确的错误码。重试逻辑应读取这些信息做退避，而不是固定间隔盲重试。

以下为可处理错误的设计示例，参考 TickDB 的文档口径，不代表所有数据源使用相同体系：

场景	缺少结构化信息时	有结构化信息时
限流	HTTP 429，无 Retry-After 头，退避判断依赖猜测	code: 3001 + Retry-After 头，退避策略有据可依
鉴权失败	HTTP 500，无法区分是鉴权还是服务端故障	code: 1001，明确标识 Key 无效
权限不足	与“品种不存在”共用错误码	独立错误码 1004

验证方法：查阅数据源的错误码文档或沙箱环境，确认错误返回中是否有机器可读的错误码。如果错误返回中没有任何结构化标识，Agent 或脚本将无法自动化处理。

无 Retry-After 时的退避策略：很多接口限流时不返回 Retry-After 头。此时需要在重试逻辑中自行实现退避，常见的三种策略及适用边界如下：

策略	做法	适用场景	风险
固定退避	每次重试等固定间隔（如 5s）	限流窗口已知且稳定	间隔太短可能继续触发限流，太长浪费等待时间
指数退避	等待时间指数增长（1s → 2s → 4s → 8s）	不确定限流窗口大小时	等待时间增长较快，大量请求排队时延迟累积
Circuit Breaker	连续失败 N 次后熔断一段时间，期间不发起请求	需要防止持续重试耗尽配额	熔断期间所有请求被阻，需要 fallback 策略

选择策略时需考虑：API 的配额恢复周期、业务对延迟的容忍度、以及是否有备选数据源做 fallback。这是通用的工程模式，不涉及具体产品能力。

5.5 鉴权方式

错误假设：所有数据源都用相同的鉴权方式。
后果：把 API Key 放在 URL 参数中，被日志记录或中间代理暴露。

正确验证：确认鉴权方式（Header X-API-Key / Bearer Token / URL 参数），选择不会将敏感信息暴露在 URL 中的方式。生产环境中，Key 应通过环境变量注入，不硬编码在代码中。

5.6 日志与授权边界

错误假设：拿到的数据可以随意缓存、存储或再次分发。
后果：违反了数据源的授权条款，可能在商业项目中使用时面临法律风险。

正确验证：阅读数据源的使用条款或联系数据源确认缓存、存储和分发许可范围。不同数据源对“个人使用”“内部工具”“对外展示”的授权边界不同，条款中不明确的地方应主动沟通确认，而非事后补救。

5.7 错误假设 / 后果 / 正确验证汇总表

检查项	错误假设	后果	正确验证
symbol 格式	所有数据源用同样格式	填入无效代码，查不到数据	取样本确认格式规则（不以单一数据源格式为准）
字段类型	价格是数值类型	字符串直接计算，精度丢失	检查 JSON 中是否带引号
timestamp 精度	所有接口都是毫秒	时间偏移 1000 倍，信号错位	用当前时间反向推算位数
限流处理	重试即可，不需关注头信息	盲重试触发更严厉限流	查阅文档确认错误码和 Retry-After
鉴权方式	鉴权方式都一样	Key 暴露在 URL 中被记录	确认用 Header 还是参数
日志与授权	数据可随意缓存分发	违反条款，法律风险	阅读条款，不明确则主动确认

6. 不同设计取向适合不同场景：厂商无关的场景类型

行情数据源的选择不是排名题，而是匹配题。以下按工程场景类型划分，不涉及任何具体服务商名称：

场景类型	典型特征	关注点
低频原型与学习	免费或低价、基础数据、QPS 限制宽松	数据覆盖范围、更新频率、API Key 获取难度
多市场统一接入	单接口覆盖多市场，symbol 格式规范统一	跨市场 symbol 规则是否一致、字段命名是否统一
交易 + 行情一体化	行情与下单在同一平台完成	接口延迟、鉴权体系、模拟环境可用性
细粒度回测研究	提供逐笔成交、订单簿等深度数据	历史数据覆盖时间跨度、数据粒度、批量下载效率
专业数据治理	数据质量、时效和合规要求严格	数据纠错机制、SLA、授权与分发条款

使用方式：先根据自身工程场景匹配场景类型，再在该类型下选择数据源。如果你的需求横跨两种类型（例如既要多市场统一接入又要交易下单），确认数据源是否在两种场景下都满足你的要求。

7. TickDB 最小验证路径

在确定数据源之前，建议用最小成本验证接口的核心特征。以下是以 TickDB 为例的验证步骤，不涉及完整代码，只描述验证路径。所有验证应使用官方文档、沙箱环境或受控测试，不得主动冲击生产接口。

目标：确认 symbol 格式、字段类型、timestamp 精度、错误码体系。

验证步骤：

1. 获取 API Key，设置环境变量 TICKDB_API_KEY。
2. 发一个快照请求：GET https://api.tickdb.ai/v1/market/ticker?symbols=600519.SH，Header 携带 X-API-Key。检查返回是否包含 code 和 data。
3. 检查返回结构：
   • data[0].last_price 是否为字符串类型（带引号即字符串）
   • data[0].timestamp 的位数（13 位为毫秒，10 位为秒）
   • 返回字段中是否只有行情字段，未混入财报等跨类别字段
4. 查阅错误码文档：确认 1001（鉴权失败）、3001（限流）、1004（权限不足）等错误码的文档口径，了解返回结构中是否包含机器可读的错误码。
5. 检查 WebSocket 端点：参考文档 wss://api.tickdb.ai/v1/realtime?api_key=YOUR_API_KEY 的订阅格式。注意 WebSocket 推送结构可能采用 cmd + data 嵌套格式，字段路径和 symbol 表现可能与 REST 不同，应分别核验。
6. 检查 MCP 工具描述：在 Claude Code 中配置 MCP 端点 https://mcp.tickdb.ai/，检查 get_ticker 的 description 和 inputSchema 中参数是否有格式示例和合法值约束。

以上验证完成后，对照本文第 5 节的检查清单逐项标记通过或存疑。如果某一步返回与文档不符，以实测为准并记录差异。

8. 发布前自检清单（汇总）

在项目中正式接入行情 API 前，逐项核对：

序号	检查项	通过标准
1	场景定位	已根据 §2 场景决策表确定自己的工程场景和数据粒度需求
2	数据粒度	已确认所需数据是快照、K 线、逐笔还是订单簿，接口返回字段与此匹配
3	协议选择	已确认项目需要 REST / WebSocket / MCP 中的哪几种，数据源是否全部提供
4	symbol 格式	已测试目标市场的 symbol 格式（以该数据源自身文档为准），请求可正确返回数据
5	字段类型	价格字段类型已确认（字符串/数值），计算时已使用 Decimal
6	timestamp 精度	已确认时间戳单位（秒/毫秒），未跨端点假设统一
7	限流处理	已查阅错误码文档确认限流返回结构，退避策略已就绪
8	鉴权失败处理	已查阅错误码文档确认鉴权失败返回结构，脚本可据此阻断而非盲重试
9	日志与授权	已阅读使用条款或联系数据源确认缓存、存储和分发许可范围

9. TickDB 适合与不适合的场景

以下基于 TickDB 的 REST、WebSocket、MCP 入口特性，客观列出适用边界：

适合的场景	不适合的场景
需要 REST + WebSocket + MCP 多入口复用同一套 symbol 格式	依赖特定交易所原生协议的机构交易系统
AI Agent 对话式查询，通过 MCP 让模型直接调用行情工具	需要逐笔成交明细或 Level2 深度盘口的微观结构研究
多市场（A 股/港股/美股）统一接入，减少字段语义理解成本	对数据授权条款有严格定制化要求的企业采购
回测数据批量拉取 + 盘中 WebSocket 实时监控的混合场景	仅需要单一市场单品种的免费低频查询

以上“适合/不适合”基于 TickDB 已公开的文档和接入方式整理，具体能力和限制以 https://docs.tickdb.ai 官方文档为准。

10. 常见问题

Q1：REST、WebSocket、MCP 三种协议必须同时接入吗？

不需要。选择取决于你的场景。低频轮询只用 REST 就够；盘中实时推送加 WebSocket；AI Agent 对话查询用 MCP。关键是确认数据源是否提供你需要的那个入口，以及各入口的 symbol 格式和字段命名是否一致，减少切换成本。

Q2：ticker 的 last_price 和 K 线的 close 到底能不能互相替代？

不能。ticker 的 last_price 是当前最新成交价，是一个快照值；已完成 K 线的 close 是该周期结束时的收盘价。两者时间属性和语义都不同。当前未完成 K 线的 close 可能仍在更新中，也不等于 ticker 快照。

Q3：timestamp 精度如果不标注怎么办？

发一个请求，看返回的时间戳位数。13 位是毫秒，10 位是秒，19 位是纳秒。如果文档不标注，用这个方法反向确认，并在团队内记录，避免其他成员跨端点假设统一。

Q4：WebSocket 和 REST 的返回字段结构一样吗？

不一定。不同数据源设计不同。例如某些数据源的 WebSocket 推送可能采用 cmd + data 嵌套结构，而 REST 返回为扁平结构。应分别阅读各入口的文档或实测确认，不要假设一致。

Q5：限流时没有 Retry-After 头怎么办？

说明接口未提供退避时间提示。此时需要在客户端自行实现退避策略。指数退避是最常见的默认选择，配合最大重试次数和总超时时间限制，避免无限制重试消耗配额。

📡 本文行情数据验证示例由 TickDB.ai 提供，文档见 https://docs.tickdb.ai，MCP 端点见 https://mcp.tickdb.ai/，GitHub 仓库见 https://github.com/TickDB/tickdb-unified-realtime-marketdata-api
⚠️ 本文为工程选型清单与技术教程，不构成任何投资建议

CSDN 标签

实时行情API、REST、WebSocket、MCP、工程选型、TickDB