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

TickDB Research ·

摘要

接 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 ticker查询实时行情快照，适合一次性查询、字段核对和落库前验证X-API-Key Header
REST kline查询已结束周期的历史 K 线，适合回测数据准备和字段口径核对X-API-Key Header
WebSocket ticker订阅 ticker 行情频道，适合行情面板、监控告警和持续更新链路验证api_key URL 查询参数

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

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

三、REST ticker 快照实测

3.1 请求方式

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

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

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

3.2 返回结构

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

字段本次核对方式本次核对结果
symbol与请求逐字符比对与请求一致
name检查是否存在非空
type检查资产类型为 stock
last_price用 Decimal(str(value)) 解析可解析为有限数值
volume_24h按返回字段名记录并做数值解析可解析为有限数值，具体统计口径以官方文档为准
high_24h按返回字段名记录并做数值解析可解析为有限数值，具体统计口径以官方文档为准
low_24h按返回字段名记录并做数值解析可解析为有限数值，具体统计口径以官方文档为准
price_change_24h按返回字段名记录并做数值解析可解析为有限数值，具体统计口径以官方文档为准
price_change_percent_24h按返回字段名记录并做数值解析可解析为有限数值，具体统计口径以官方文档为准
timestamp检查整数类型和位数13 位毫秒时间戳

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。

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

4.2 返回结构

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

字段本次核对方式本次核对结果
time检查整数类型和位数13 位毫秒时间戳
open用 Decimal(str(value)) 解析可解析为有限数值
high用 Decimal(str(value)) 解析，并校验 OHLC 关系high >= open/low/close
low用 Decimal(str(value)) 解析，并校验 OHLC 关系low <= open/high/close
close用 Decimal(str(value)) 解析可解析为有限数值
volume用 Decimal(str(value)) 解析可解析为有限数值
quote_volume用 Decimal(str(value)) 解析可解析为有限数值

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-Key Header。

5.2 订阅方式

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

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

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

5.3 实测过程

本次实测结果：

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

5.4 关键认知

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

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

image.png 接入 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 端点可用。
  • 不构成任何投资建议。

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

七、适合场景

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

场景核心链路说明
A 股行情面板REST ticker + WebSocket快照用于首屏加载，WebSocket 用于实时更新链路
自选股监控WebSocket适合做持续更新链路，但需要自行补断线重连、心跳和异常告警
量化研究脚本REST kline + REST ticker回测前用 kline，盘中样本核对用 ticker
AI Agent 查询行情MCP / 工具调用 / REST 示例AI Agent/MCP 场景可通过工具调用获取结构化行情，具体调用路径以官方文档为准
数据落库前字段核对REST ticker + kline逐字段校验类型、单位、语义和异常分支

八、自己怎么验证

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

第一步：REST ticker 验证

from decimal import Decimal
import requests

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", [])
assert resp.status_code == 200
assert payload.get("code") == 0
assert len(items) > 0
assert items[0]["symbol"] == "600519.SH"
Decimal(str(items[0]["last_price"]))

第二步：REST kline 验证

from decimal import Decimal
import requests

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", [])
assert resp.status_code == 200
assert payload.get("code") == 0
assert len(klines) > 0

first = klines[0]
for field in ["time", "open", "high", "low", "close", "volume", "quote_volume"]:
    assert field in first

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-Key Header 鉴权，WebSocket 使用 api_key URL 查询参数鉴权。两种方式各自独立，接入时注意区分，不要将 REST 的 Header 写到 WebSocket 的请求中。

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

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

相关文章

Python 获取 A 股实时行情：HTTP 200 到手后，先验 symbol、last_price 和 timestamp 再入库

摘要 你用 Python 接入了 A 股实时行情接口，第一次请求返回 HTTP 200 和 ，价格看起来正常。但接口返回成功不等于数据可用—— 可能是空数组、symbol 可能跟请求不一致、 可能是无法解析的字符串、timestamp 语义可能跟你想的不一样。本文给出一套首次接入后的字段校验流程：先看懂返回结构，再逐字段检查 symbol、价格和 timestamp，最后用 raw_snapsho

TickDB Research ·

A股美股港股行情看板Demo三天、上线三个月：拆解7个返工点

同一张行情表，寒武纪的成交额自己算是5,414万元，接口给的是54.20亿元，差了100倍，原因只是一个单位。行情看板三天就能接通，上线后的返工，几乎都来自界面上说不清“自己是什么”的数字。 本文依据上交所、港交所的一手文件，加上10月12日盘中对7类资产的实测，给你四样东西： 一张“价格身份证”：每个数字上线前要答的5个问题 7个返工点逐条拆：钱在哪里算错、为什么会错 一份可以直接发给数据…

TickDB Research ·

拆解美股夜盘数据5个口径：12月6日起美股进入23小时交易

同一只苹果股票，同一个周六中午，三个“最新价”，1万股持仓估值差出 9,500 美元。12月6日起，美股将进入近23小时交易：夜盘数据的5个口径不说清，日K线、收益率、风控和对账都会悄悄算错。 本文依据纳斯达克、SEC、DTCC、FINRA 等一手文件，加上30只美股（含9只中概股）的实测数据，给你四样东西： 一张“北京时间 × 美股夜盘”全景图（含11月1日夏令时切换前后） 5个口径逐条拆…

TickDB Research ·

港股数据源选型：踩一个回测就假（富途/IBKR/TickDB）

回测里某个港股策略表现稳定，实盘跑了一个月，收益差了将近一半。 不是完全对不上，是那种“差异不大但一直在”的偏差。团队排查了三周——策略逻辑、滑点模型、手续费、执行延迟，全部查过。最后发现问题在数据层：数据源返回的港股代码是“700”，而团队数据库里存的是“00700”。两个格式查出来的数据，部分重叠，部分不重叠。回测用的样本，比实际可交易的样本少了一批。 这不是某个操作失误，是港股数据接入…

TickDB Research ·

A股休市10天，港股跌了，美联储还要开会，APEC即将落地深圳——8号开盘，你盘清楚了几件事？

后天开盘。10月8日，A股恢复交易。你手里的A股仓位，价格停在9月30日；但如果你同时持有港股、美股、QDII，这10天它们一直在动——港股10月2日就开盘了，美股全程正常交易。 这篇文章要说的不是“A股休市了”。有仓位的人都知道A股休市。它要说的是： 同一段时间里，你的三个市场仓位在动，你的信息却只跟得上一个。 核心概念是 信息时态差 ——港股和美股的信息是连续的，每天有K线；A股的信息是…

TickDB Research ·