700.HK 还是 00700.HK？接港股行情 API，第一处坑就在 symbol

摘要：接港股实时行情 API 时，很多人第一眼只看有没有价格返回。但港股代码经常有两种写法：券商、自选股或旧数据库里可能是 00700，API 示例里可能是 700.HK。真正危险的不是某个写法一定错，而是你没有把“外部代码、请求 symbol、返回 symbol、原始响应”绑定成同一个可追溯对象。本文用 TickDB 对 700.HK 和 00700.HK 做了一次真实 REST 调用，再用通过校验的 700.HK 拉取 K 线，说明港股行情接入的第一道契约为什么不是“有价格”，而是“先确认数据身份”。

!image.png

这篇文章解决什么问题

你接港股行情 API，最容易掉进去的坑，不一定是接口报错。更常见的是：接口成功了，价格也回来了，但你不知道这个价格到底被系统当成了哪个标的。

腾讯控股有人写 700，有人写 00700，接 API 时又可能写成 700.HK 或 00700.HK。人工看一眼当然知道它们大概率指向同一只股票，可一旦进入程序——请求的是哪个 symbol？返回的 symbol 是哪个？入库时保存的是原始写法还是规范化写法？K 线、告警、回测是不是都沿用了同一个身份？出问题时，还能不能拿 raw response 复盘？

港股 API 接入的第一道契约，不是“有没有返回价格”，而是把外部代码、请求 symbol、返回 symbol 和原始响应绑定成同一个可追溯对象。

本文的核心方法论

这篇文章只做一件事：用 TickDB 对 700.HK 和 00700.HK 做一次真实 REST 调用，再用通过校验的 symbol 拉取 K 线，跑通一条港股 symbol 身份校验链路。全文的逻辑结构是——

是什么：一个合格的 symbol 身份契约，必须包含五样东西——外部原始代码、实际请求的 symbol、API 返回的 symbol、原始响应快照、本地检查时间。这五样东西，缺任何一样，数据的身份就无法被程序复查。

为什么：两种写法都能返回成功，正因如此才更危险。失败很容易发现，成功但身份链不清楚，会让数据库、图表、告警和回测各自沿用不同的 symbol，排查时才发现整个系统里没有一条记录能说清楚“这个价格到底是谁的”。

怎么样：先对两种写法分别发 ticker 请求，对比请求 symbol 和返回 symbol 是否一致；再选一个通过校验的 symbol 延伸校验 K 线的 symbol、interval 和 OHLCV 字段。每一步都配真实终端截图、字段核对表和可运行代码。最后给一张最小证据表，你可以直接拿去约束自己的港股数据入口。

读完你能拿走什么

• 一条港股 symbol 身份校验的最小链路：ticker 请求 → symbol 一致性检查 → K 线延伸校验 → 原始快照留痕。
• 一份可直接运行的 Python 校验代码，验请求 symbol 与返回 symbol 是否一致、价格字段是否可解析、timestamp 是否可解释。
• 一张最小证据表，包含外部代码、请求 symbol、返回 symbol、原始快照路径、校验状态和阻断原因，每次接入新数据源或切换品种时直接对照。
• 一套“能证明什么、不能证明什么”的边界声明，帮你区分 symbol 身份校验、交易信号和生产稳定性。

一、符号身份校验：用真实调用代替靠猜测

这次我没有预设答案，而是直接跑了三步：用 TickDB REST ticker 请求 700.HK，同条件请求 00700.HK，选一个通过校验的 symbol 再请求日 K 线。

!image.png

图中为 2026-07-14 11:35 左右本地实测输出，API Key 已脱敏。该截图只证明本轮请求与字段校验结果，不代表所有港股、所有时间段或所有周期均同样表现。

本轮结果有个很重要的点：

注意，这里不能得出“价格冲突”的结论。两次请求不是同一毫秒发生的，价格字段也不是本文要比较的重点。

真正该记下的是：本轮 00700.HK 没有失败，也没有被静默改写成 700.HK；它返回了 00700.HK。 这就把一个常见误区拆开了：问题不是“到底哪个写法一定对”，而是你的系统不能靠猜。你可以在内部选择一种写法作为标准，但必须把原始输入、请求参数、返回 symbol 和 raw response 都留住。

二、为什么“我知道它是腾讯”不等于程序知道

人脑会自动合并信息。看到 00700、700.HK、腾讯控股，你会自然认为它们说的是同一个东西。程序不会。程序只会处理字符串、字段、数组和对象。如果你没有明确写下映射关系，后面任何一步都可能悄悄变成“看起来对，其实不可复查”——用户输入 00700，你的转换函数改成 700.HK，API 返回 00700.HK，数据库主键存了 700.HK，K 线表又用 700.HK，报表展示回 00700。每一步单独看都合理，连起来就可能丢证据。

!image.png

这也是为什么我建议港股接入时，不要只存一个 symbol 字段。至少要把这几件事分开：

不要让“我知道它们是一回事”变成系统里的隐式规则。隐式规则越多，数据错了越难查。

三、可运行代码：先做 fail-closed 的 symbol 校验

下面这段代码就是本次 runner 的核心逻辑压缩版。它不是伪代码：请求路径、鉴权方式、字段检查和 fail-closed 分支都按本次实测逻辑写。

运行前设置环境变量：

export TICKDB_API_KEY="你的 API Key"
python3 hk_symbol_contract_check.py

核心代码：

import os
import requests
from decimal import Decimal, InvalidOperation

BASE_URL = "https://api.tickdb.ai"


def decimal_ok(value):
    try:
        return Decimal(str(value)).is_finite()
    except (InvalidOperation, ValueError):
        return False


def timestamp_ms_ok(value):
    return isinstance(value, int) and len(str(abs(value))) == 13


def get_json(path, params):
    key = os.environ["TICKDB_API_KEY"]
    r = requests.get(
        BASE_URL + path,
        headers={"X-API-Key": key, "Accept": "application/json"},
        params=params,
        timeout=20,
    )
    return r.status_code, r.json()


def validate_ticker(request_symbol):
    status, payload = get_json("/v1/market/ticker", {"symbols": request_symbol})
    if status != 200 or payload.get("code") != 0:
        raise RuntimeError(f"ticker failed: http={status}, payload={payload}")

    rows = payload.get("data")
    if not isinstance(rows, list) or not rows:
        raise RuntimeError("ticker data is empty")

    row = rows[0]
    response_symbol = row.get("symbol")
    if response_symbol != request_symbol:
        raise RuntimeError(
            f"symbol mismatch: request={request_symbol}, response={response_symbol}"
        )
    if not decimal_ok(row.get("last_price")):
        raise RuntimeError("last_price is not decimal")
    if not timestamp_ms_ok(row.get("timestamp")):
        raise RuntimeError("timestamp is not 13-digit milliseconds")

    return row


def validate_kline(symbol):
    status, payload = get_json(
        "/v1/market/kline",
        {"symbol": symbol, "interval": "1d", "limit": "3"},
    )
    if status != 200 or payload.get("code") != 0:
        raise RuntimeError(f"kline failed: http={status}, payload={payload}")

    data = payload.get("data")
    if not isinstance(data, dict):
        raise RuntimeError("kline data is not object")
    if data.get("symbol") != symbol:
        raise RuntimeError(f"kline symbol mismatch: {data.get('symbol')} != {symbol}")
    if data.get("interval") != "1d":
        raise RuntimeError("kline interval mismatch")

    bars = data.get("klines")
    if not isinstance(bars, list) or not bars:
        raise RuntimeError("klines is empty")

    first = bars[0]
    for field in ["time", "open", "high", "low", "close", "volume"]:
        if field not in first:
            raise RuntimeError(f"kline missing field: {field}")
    return bars


if __name__ == "__main__":
    ticker_700 = validate_ticker("700.HK")
    ticker_00700 = validate_ticker("00700.HK")

    # 本轮两种写法都通过 ticker 校验；示例选择 700.HK 继续校验 K 线。
    bars = validate_kline("700.HK")

    print("ticker_700:", ticker_700["symbol"], ticker_700["last_price"], ticker_700["timestamp"])
    print("ticker_00700:", ticker_00700["symbol"], ticker_00700["last_price"], ticker_00700["timestamp"])
    print("kline_first_bar:", bars[0])

这段代码有一个故意保守的地方：只要请求 symbol 和返回 symbol 不一致，它就直接抛错。

有人可能会说，API 返回了另一个等价写法也可以接受。可以，但不要在数据层默认接受。 你应该先把这件事写成明确映射规则，例如 external_code=00700、request_symbol=700.HK、response_symbol=700.HK、mapping_rule=strip_leading_zero_for_internal_symbol、raw_snapshot=...。如果没有这张映射证据，就别让数据静默入库。

四、ticker 通过，不代表 K 线也能直接混用

ticker 和 K 线经常被放在同一个“行情 API”里讨论，但它们不是同一种证据。

!image.png

ticker 回答的是：这个 symbol 当前快照是什么？K 线回答的是：这个 symbol 在某个周期里的 OHLCV 样本是什么？本轮实测里，700.HK 的 1d K 线返回了 3 根，第一根样本为：

这一步的意义不是证明“腾讯控股某天怎样走”，而是证明：你可以把 ticker 的 symbol 校验，继续延伸到 K 线的 symbol、interval 和 OHLCV 字段校验。 如果 ticker 用 00700.HK，K 线用 700.HK，那也不是不行，但你必须解释两者的关系。否则，后面做行情面板、历史图表、回测样本或 AI 分析时，问题会变得更难查。

五、港股接入时，我建议最少留这张表

如果你正在把港股行情接进自己的系统，不管用的是 TickDB 还是其他数据源，建议先建立一张最小证据表：

这张表不复杂，但它把一个关键责任说清楚了：行情数据入库前，先证明它是谁。 有了这层，后面讨论价格、成交量、K 线周期、告警、回测才有意义。没有这层，越往后做，越像在一堆看似正确的字段上搭楼。

六、TickDB 在这里解决的是哪一层

这篇文章不是在讨论“哪个港股值得买”，也不是在比较行情软件。本文用 TickDB，是因为它适合做这种程序化验证：REST 用 X-API-Key 鉴权，ticker 可以查实时快照，kline 可以拉历史 K 线，返回里有 symbol、价格字段和时间字段，方便写成校验脚本。

更重要的是，TickDB 是一套统一行情数据 API：同一套入口覆盖外汇、贵金属、指数、美股、港股、A 股、加密货币等市场，并提供 REST、WebSocket、MCP、Skill、CLI 等不同接入方式。这对开发者的价值在于：你可以先在港股里把 symbol → ticker → kline → raw snapshot 的证据链跑通，再把同样的校验习惯迁移到 A 股、美股或其他市场，而不是每接一个市场就重新发明一套数据身份规则。

这次样本的范围也很清楚：它验证的是 700.HK、00700.HK 的 ticker，以及 700.HK 的 3 根日 K。 你把这套方法放进生产系统时，还要继续补重试、限流、告警、日志、数据落库和权限管理；行情数据入口解决的是“数据能被取到、解释和复查”，不替代投资判断。

七、FAQ

Q1：700.HK 和 00700.HK 到底应该用哪个？

不要只靠习惯决定。本文这次实测里，两种写法都返回成功，并且返回 symbol 分别保持原写法。你的系统可以选择一种内部标准，但必须把原始代码、请求 symbol、返回 symbol 和 raw response 留下来。真正要避免的是静默改写。

Q2：如果 00700.HK 和 700.HK 都能返回，为什么还要校验？

正因为都能返回，才更要校验。失败很容易发现，成功但身份链不清楚更危险。你需要知道数据库、图表、告警和回测到底沿用了哪个 symbol。

Q3：ticker 的 last_price 能不能直接当 K 线 close？

不建议。ticker 是快照，K 线是周期样本。ticker 的 last_price 回答“此刻最新价”，K 线的 close 回答“某个周期的收盘价”。它们可以互相核对，但不能混成同一个字段。

Q4：TickDB 更适合什么样的用户？

如果你只是偶尔看一眼港股价格，普通行情软件就够了。TickDB 更适合把行情数据接进研究脚本、行情面板、AI 工具、数据管道或多市场监控系统的人。它的优势是用一套 API 接入多市场，并提供结构化字段和多种接入方式，方便你把数据身份、时间和 raw response 留下来。

Q5：官方资料在哪里看？

可以从 TickDB 官方 GitHub 仓库开始看：https://github.com/TickDB/tickdb-unified-realtime-marketdata-api 。具体端点和字段以 TickDB Docs 与你当天实测为准。写进生产系统前，建议用自己的 symbol 重跑一遍 ticker、kline 和异常分支。

最后

港股行情 API 接入，第一步不要急着问价格准不准。先问一个更底层的问题：这条数据的身份，我能不能复查？

你请求的是 700.HK，返回是不是 700.HK？你请求的是 00700.HK，返回是不是 00700.HK？如果后续 K 线换成了另一种写法，系统里有没有留下映射证据？这些问题都回答清楚以后，价格字段、K 线字段、告警和回测才有资格继续往下走。

本文只讨论港股行情 API 的 symbol 身份、ticker/K线字段校验和工程留痕，不构成任何投资建议。

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

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