A股实时行情 API 接入教程：TickDB REST ticker、K线与 WebSocket 实测

摘要

接 A 股实时行情 API，不能只看官网写了“支持 A 股”。第一步应该是拿自己的 symbol 跑一遍快照、K 线和 WebSocket 订阅：快照能不能返回，K 线字段能不能核对，WebSocket 能不能完成连接和订阅确认。本文用 TickDB 的 A 股实时行情 API，从 REST ticker 快照、REST kline 历史 K 线到 WebSocket ticker 订阅，展示一套真实终端实测流程。不做行情判断，不做数据源排名，只展示可复现的接入验证方法。

一、这篇文章解决什么问题

很多开发者在评估 A 股实时行情 API 时，容易止步于官网介绍页：“支持 A 股实时行情”几个字看到了，就以为接入问题已经解决。但真正把接口接进脚本、数据库、行情面板或监控系统时，至少要回答三件事：

1. 快照能不能查到？发一个 ticker 请求，能不能拿到600519.SH的最新价、成交量字段和时间戳？
2. K 线字段能不能核对？拉几根日线，time/open/high/low/close/volume/quote_volume是否完整，timestamp 单位是否清楚？
3. WebSocket 能不能完成连接与订阅？能不能收到连接成功和订阅成功确认？

读完这篇文章，你能拿走：

• 三条链路的请求方式、参数和返回结构。
• 每条链路的关键字段核对表。
• 一份“能证明什么 / 不能证明什么”的边界声明。
• 一份可复现的自主验证步骤。

这篇文章不解决什么：不比较数据源优劣，不讨论延迟和 SLA，不涉及投资建议和策略有效性。

二、TickDB A 股实时行情 API 是什么

TickDB 是一个统一实时行情数据 API。对于 A 股接入场景，本文只验证三条基础链路：

注意：REST 使用X-API-KeyHeader 鉴权，WebSocket 使用api_key查询参数鉴权，两者不要混写。

下面逐一跑通这三条链路。每条链路只做最小验证：能发请求、能拿到返回、能核对关键字段。不推导延迟、SLA 或全市场可用性。

三、REST ticker 快照实测

3.1 请求方式

向/v1/market/ticker端点发起 GET 请求，参数symbols传入品种列表，可选参数type指定资产类型。

本次验证请求：symbols=600519.SH,000001.SZ,300750.SZ，type=stock。三个 symbol 分别覆盖上交所和深交所样本标的。

图中价格与 timestamp 为 2026-07-07 本地终端实测样本，仅用于展示 TickDB API 的字段结构和调用链路，不构成实时行情展示、投资建议、延迟/SLA 或生产稳定性承诺。

3.2 返回结构

本次实测 HTTP 200，code=0，message=success。data为数组，返回 3 个 item，每个 item 包含以下字段：

3.3 关键认知

• last_price是字符串类型，客户端应使用Decimal(str(value))解析，避免浮点精度损失。
• timestamp是 13 位毫秒时间戳。这个精度只代表字段格式，不等于延迟、数据新鲜度或高频交易可用性。
• data是数组。即使只请求一个 symbol，也要从数组中取数据，不要假设返回结构是单个对象。
• 对 A 股场景，volume_24h、high_24h、low_24h这类字段应按接口返回字段名记录，文章中不要自行扩展解释它们的统计口径。

四、REST kline 历史 K 线实测

4.1 请求方式

向/v1/market/kline端点发起 GET 请求，参数包括symbol、interval、limit、type等。

本次验证请求：symbol=600519.SH，interval=1d，limit=3，type=stock。

图中 K 线价格、成交量和 timestamp 为 2026-07-07 本地终端实测样本，仅用于展示 TickDB API 的字段结构和调用链路，不构成实时行情展示、投资建议、延迟/SLA 或生产稳定性承诺。

4.2 返回结构

本次实测 HTTP 200，code=0。data.symbol=600519.SH，data.interval=1d。data.klines[]返回 3 条日线，每条含以下字段：

4.3 关键认知

• /v1/market/kline查询的是已结束周期的历史 K 线，不要把它写成实时 K 线。
• close是 K 线字段，last_price是 ticker 字段，两者不能混用。
• klines是数组。本次只验证limit=3的样本结构，不外推全部历史范围、全部周期或全部 A 股品种。

五、WebSocket ticker 订阅实测

5.1 连接方式

WebSocket 端点为：

wss://api.tickdb.ai/v1/realtime?api_key=YOUR_API_KEY

WebSocket 鉴权使用 URL 查询参数api_key，不是 REST 的X-API-KeyHeader。

5.2 订阅方式

连接成功后，发送 ticker 订阅命令。订阅 JSON 使用嵌套结构：

{"cmd":"subscribe","data":{"channel":"ticker","symbols":["600519.SH"]}}

图中为 2026-07-07 本地终端 WebSocket 实测样本，仅用于证明连接建立与订阅确认成功，不构成交易时段推送频率、延迟、SLA 或生产稳定性承诺。

5.3 实测过程

本次实测结果：

1. WebSocket 连接建立成功，收到connected确认。
2. 发送订阅命令后，收到subscribe成功确认。
3. 本次测试发生在 A 股收盘后，未收到后续 ticker 推送；本文只证明连接与订阅确认，不评价交易时段连续推送能力。

5.4 关键认知

• 本次验证的是连接通路、订阅结构和鉴权方式是否正确。
• 交易时段的实时推送频率、延迟和稳定性，需要在盘中另行做连续采样测试。
• WebSocket 的鉴权走 URL 查询参数api_key，REST 的鉴权走X-API-KeyHeader，接入时要分开处理。

六、三条链路先建立最小验证基线

接入 A 股实时行情 API，不建议一开始就讨论入库、告警和策略。先把 REST ticker、REST kline、WebSocket ticker 三条链路跑成一条最小验证基线：请求能跑通、字段能核对、失败能留痕。

本次实测能证明

• REST ticker 端点可用：三个 A 股样本 symbol 均返回结构化快照数据，关键字段可解析。
• REST kline 端点可用：返回指定周期和数量的历史日线，OHLCV 字段完整。
• WebSocket 订阅可用：连接建立成功，订阅命令被正确响应，鉴权方式有效。
• 返回字段可进入程序化校验：symbol、last_price、timestamp、OHLCV 等关键字段可以被脚本逐项检查。

本次实测不能证明

• 不能证明所有 A 股品种在所有时段均可正常返回。
• 不能证明延迟、SLA 或生产稳定性。
• 不能证明 Level 2、逐笔成交或交易信号能力。
• 不能外推交易时段的推送频率和延迟。
• 不能外推全市场覆盖或所有 API 端点可用。
• 不构成任何投资建议。

单次实测的价值不是“证明数据源永远可靠”，而是“建立一条可复核的验证基线”。以后每次更新、切换、排查，都可以拿这条基线做对比。

七、适合场景

三条链路跑通后，只能说完成了最小接入验证基线。不同业务场景还需要继续补自己的稳定性、异常恢复和数据质量检查。

八、自己怎么验证

用你自己的 API Key 和关注品种，按以下步骤复现本文的验证流程。下面代码是最小验证示例；如果要写进生产链路，还需要补异常处理、字段类型校验、Decimal解析、raw snapshot 留痕和failure_reason。

第一步：REST ticker 验证

fromdecimalimportDecimalimportrequests resp=requests.get("https://api.tickdb.ai/v1/market/ticker",headers={"X-API-Key":"YOUR_API_KEY"},params={"symbols":"600519.SH","type":"stock"},timeout=10,)payload=resp.json()items=payload.get("data",[])assertresp.status_code==200assertpayload.get("code")==0assertlen(items)>0assertitems[0]["symbol"]=="600519.SH"Decimal(str(items[0]["last_price"]))

第二步：REST kline 验证

fromdecimalimportDecimalimportrequests resp=requests.get("https://api.tickdb.ai/v1/market/kline",headers={"X-API-Key":"YOUR_API_KEY"},params={"symbol":"600519.SH","interval":"1d","limit":3,"type":"stock"},timeout=10,)payload=resp.json()klines=payload.get("data",{}).get("klines",[])assertresp.status_code==200assertpayload.get("code")==0assertlen(klines)>0first=klines[0]forfieldin["time","open","high","low","close","volume","quote_volume"]:assertfieldinfirst Decimal(str(first["open"]))Decimal(str(first["high"]))Decimal(str(first["low"]))Decimal(str(first["close"]))

第三步：WebSocket 订阅验证

使用wss://api.tickdb.ai/v1/realtime?api_key=YOUR_API_KEY建立连接，发送 ticker 订阅命令：

{"cmd":"subscribe","data":{"channel":"ticker","symbols":["600519.SH"]}}

验证重点不是“立刻收到连续行情”，而是先确认：

• 是否收到connected确认；
• 是否收到subscribe确认；
• 如果在交易时段测试，是否能按自己的采样规则记录后续 ticker 推送；
• 如果没收到推送，日志里是否能区分连接失败、订阅失败、非交易时段、symbol 问题和网络超时。

第四步：核对字段并留痕

对照本文第三至第五节的字段表，逐项核对返回字段的类型、单位和语义。把请求参数、原始返回、检查时间、校验结果、失败原因一起保存下来。这份记录就是你的“验证基线”。

九、常见问题与排错清单

Q1：REST ticker 返回code=0但data为空数组，怎么回事？

空数组可能是合法返回。常见原因包括 symbol 格式有误、type与 symbol 不匹配、该品种不在当前可查询范围内或当前条件下无返回。先检查 symbol 后缀（.SH/.SZ）和type=stock，必要时查阅可用品种列表或官方文档。

Q2：WebSocket 连接成功但收不到数据推送？

先看有没有收到connected和subscribe确认。如果确认都成功，再看测试是否发生在交易时段。本次测试发生在 A 股收盘后，只能证明连接与订阅确认，不能外推交易时段推送表现。如果交易时段仍收不到推送，再检查订阅 JSON 是否为cmd + data + channel + symbols[]的嵌套结构，以及 symbol 是否与文档一致。

Q3：kline 的close和 ticker 的last_price有什么区别？

Kline 的close是某个 K 线周期的收盘价。Ticker 的last_price是行情快照字段。两者语义和时间属性不同，不能混用。

Q4：timestamp 是 13 位毫秒，说明延迟很低吗？

不。13 位毫秒只说明字段精度和单位，不说明数据新鲜度、推送延迟或高频交易可用性。延迟和稳定性需要单独做连续采样、链路监控和统计分析。

Q5：REST 和 WebSocket 的鉴权方式为什么不同？

REST 使用X-API-KeyHeader 鉴权，WebSocket 使用api_keyURL 查询参数鉴权。两种方式各自独立，接入时注意区分，不要将 REST 的 Header 写到 WebSocket 的请求中。

本文 A 股实时行情 API 实测以 TickDB 作为接入示例。接口文档以官方文档为准。

本文为技术实测教程，不构成任何投资建议。