系列文章第 3 篇：TickDB REST 快速开始：完成第一次可核验的行情查询

这是 TickDB 实时行情接入系列的第 3 篇。前一篇解决“接入路径怎么选”，本文解决“REST 第一次查询”。 很多开发者第一次接行情数据，卡住的不是“有没有 API”，而是另一个更实际的问题：

先说结论：第一次验证，只跑通一条 REST 快照请求

第一次使用 TickDB REST API，不需要先搭复杂工程。你可以先完成一个可核验闭环：准备 API Key，向 GET https://api.tickdb.ai/v1/market/ticker 传入真实 symbols，再确认响应中能找到目标 symbol、last_price 与 timestamp。

本文只处理这一条 REST 行情快照查询链路：请求怎样发出、结果怎样检查、首次失败怎样定位。示例用于验证数据读取入口和响应结构，不延伸到其他接入方式或业务结论。

第一次验证前，先明确成功标准

一次返回 success 还不够。首次验证值得保存的，是“我发了什么请求、得到什么结构、凭什么判断读对”的证据。

最小可运行示例：Python 标准库完成一次查询

运行前提：

1. 安装 Python 3。
2. 已获得当前有效的 TickDB API Key。
3. 在本地终端设置环境变量，不要将真实 Key 写入代码、截图或仓库。

export TICKDB_API_KEY='<your-api-key>'
python3 tickdb_first_ticker_check.py

将下列代码保存为 tickdb_first_ticker_check.py。它是首次验证用的最小可运行示例：会阻断鉴权失败，提示 symbol 问题，并在出现限流信号时停止请求、展示退避依据；它不是生产部署代码。

#!/usr/bin/env python3
import json
import os
import sys
from datetime import datetime, timezone
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import Request, urlopen

BASE_URL = "https://api.tickdb.ai/v1/market/ticker"
SYMBOLS = ["AAPL.US", "BTCUSDT"]


def stop(message):
    print(f"FAILED: {message}", file=sys.stderr)
    raise SystemExit(1)


api_key = os.environ.get("TICKDB_API_KEY", "")
if not api_key or api_key == "<your-api-key>":
    stop("请先在本地设置有效的 TICKDB_API_KEY。")

url = f"{BASE_URL}?{urlencode({'symbols': ','.join(SYMBOLS)})}"
request = Request(url, headers={"X-API-Key": api_key}, method="GET")

try:
    with urlopen(request, timeout=10) as response:
        http_status = response.status
        retry_after = response.headers.get("Retry-After")
        raw_body = response.read().decode("utf-8", "replace")
        try:
            payload = json.loads(raw_body)
        except json.JSONDecodeError:
            stop("响应不是可解析的 JSON。")
except HTTPError as error:
    http_status = error.code
    retry_after = error.headers.get("Retry-After")
    raw_body = error.read().decode("utf-8", "replace")
    try:
        payload = json.loads(raw_body)
    except json.JSONDecodeError:
        payload = {}
except (URLError, TimeoutError) as error:
    stop(f"网络请求未完成：{error}")

code = payload.get("code")
message = payload.get("message", "")

if http_status == 429 or code == 3001:
    stop(f"请求受到频率限制；Retry-After={retry_after or '响应未提供'}。请退避后再试。")
if code == 1001:
    stop("API Key 无效或已过期，请更换当前有效 Key 后再试。")
if code == 1002:
    stop("请求未携带 API Key，请检查 X-API-Key Header。")
if code == 2002:
    stop("symbol 未被识别，请先核对当前可用品种代码。")
if http_status >= 400 or code != 0:
    stop(f"请求失败：HTTP {http_status}, code={code}, message={message}")

rows = payload.get("data")
if not isinstance(rows, list) or not rows:
    stop("请求成功但 data 为空；请保留原始响应并核对 symbol。")

for row in rows:
    if not all(field in row for field in ("symbol", "last_price", "timestamp")):
        stop("响应记录缺少本次验证所需字段。")
    try:
        timestamp_ms = int(row["timestamp"])
    except (TypeError, ValueError):
        stop("timestamp 不是本次验证可读取的整数值。")
    timestamp_utc = datetime.fromtimestamp(timestamp_ms / 1000, tz=timezone.utc).isoformat()
    print(json.dumps({
        "symbol": row["symbol"],
        "last_price": row["last_price"],
        "timestamp": timestamp_ms,
        "timestamp_utc": timestamp_utc
    }, ensure_ascii=False))

这里刻意只打印本次核验需要的字段：ticker 的价格读取字段是 last_price，timestamp 在该接口中按毫秒 UTC 解释。代码不对行情字段做计算，也不从一次快照推导额外结论。

脱敏实测输出：只保留验证所需字段

下面的字段摘录继承自 S00 母资产在 2026-05-27 留存的 REST 实测记录：请求使用上述 ticker 端点与 AAPL.US,BTCUSDT，真实 API Key 已移除。该摘录用于复核响应结构；其中数值只代表当次返回的快照。

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

看到这类响应后，首次验证可以按三项收口：

1. code 为 0，表示本次请求成功返回。
2. data 是数组，且其中出现本次查询的 symbol。
3. 每条目标记录均能读取 last_price 与 timestamp，并保留原始摘录供复核。

第一次查询失败，按这张表处理

首次验证的目标是尽快定位请求链路，而不是把失败藏进无限重试。

本文证明什么，不证明什么

系列导航

官方验证入口

• TickDB REST 行情快照文档：

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

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