tickdb-market-data

TickDB Market Data API

统一实时行情数据 API，通过单一连接访问多个金融市场的实时与历史行情数据。

官网: https://tickdb.ai
文档: https://docs.tickdb.ai

基础信息

• Base URL: https://api.tickdb.ai
• 认证方式: API Key（放在 HTTP Header X-API-Key 中）
• 时间戳单位: 毫秒（ms），UTC 时区
• 响应格式: JSON

API Key 使用流程

核心逻辑（必须严格遵守）

API Key 不做任何持久化存储，每次查询实时获取，用完即弃。

用户请求行情数据
    │
    ├─ 用户是否在本轮对话中提供过正式 Key？
    │   ├─ 是 → 使用用户提供的 Key 调用 API（无产品限制）
    │   └─ 否 → 检查请求的品种是否在试用版允许范围内
    │       ├─ 在范围内 → 自动调用试用 Key 接口实时获取（见下方）
    │       └─ 不在范围内 → 直接告知用户该品种需要正式 Key（见「试用版产品范围」）
    │
    └─ API 返回错误？
        ├─ 1001（Key 无效/过期）→ 提示用户注册正式 Key
        ├─ 3001（频率超限）→ 提示用户注册正式 Key 以获取更高配额
        ├─ 3002（配额用尽）→ 提示用户注册正式 Key 以获取更高配额
        └─ 其他错误 → 按错误码表处理

试用版产品范围（必须严格遵守）

使用试用 Key 时，仅支持以下产品。AI 在发起请求前必须校验用户请求的品种是否在此列表中。

加密货币: BTCUSDT, ETHUSDT, BNBUSDT, SOLUSDT, XRPUSDT, DOGEUSDT, ADAUSDT, AVAXUSDT, DOTUSDT, LINKUSDT

港股: 700.HK, 9988.HK, 9618.HK, 3690.HK, 1810.HK, 2318.HK, 941.HK, 1024.HK, 9888.HK, 2015.HK

美股: AAPL.US, TSLA.US, NVDA.US, MSFT.US, GOOGL.US, AMZN.US, META.US, AMD.US, NFLX.US, BABA.US

外汇: EURUSD, GBPUSD, USDJPY, AUDUSD, USDCAD, USDCHF, NZDUSD, EURGBP, EURJPY, GBPJPY

贵金属: XAUUSD, XAGUSD

A股: 600519.SH, 601318.SH, 600036.SH, 000858.SZ, 000333.SZ, 600900.SH, 601012.SH, 000002.SZ, 600276.SH, 002594.SZ

指数: SPX, DJI, IXIC, NDX, RUT, VIX, DXY, FTSE, DAX, N225

校验规则：

1. 用户请求的每个品种代码必须与上述列表精确匹配（含市场后缀，如 .HK、.US、.SH、.SZ）
2. 若用户请求的品种不在列表中，不要调用 API，直接向用户展示以下提示：

🔒 您查询的品种 {symbol} 不在试用版支持范围内。试用版每个市场仅支持 10 个热门品种（共 72 个）。

如需查询全部 37,527+ 产品，请前往 tickdb.ai 注册正式 API Key。

📋 试用版支持的品种：

• 加密货币：BTCUSDT, ETHUSDT, BNBUSDT, SOLUSDT, XRPUSDT 等 10 个
• 美股：AAPL, TSLA, NVDA, MSFT, GOOGL 等 10 个
• 港股：700, 9988, 9618, 3690, 1810 等 10 个
• A股：600519, 601318, 600036, 000858, 000333 等 10 个
• 外汇：EURUSD, GBPUSD, USDJPY, AUDUSD, USDCAD 等 10 个
• 贵金属：XAUUSD, XAGUSD
• 指数：SPX, DJI, IXIC, NDX, RUT 等 10 个

3. 若用户一次请求多个品种，其中部分不在范围内，则仅查询范围内的品种，并在结果末尾附加上述提示告知哪些品种被跳过
4. 用户提供正式 Key 后，不受此限制

自动获取试用 Key（每次查询实时获取）

每次用户触发行情查询且未提供正式 Key 时，AI 必须执行以下步骤：

1. 调用 GET https://tickdb.ai/api/public/claw-keys（无需认证）
2. 从响应中提取 apiKey 字段
3. 使用该 Key 调用业务接口完成本次查询
4. 查询完成后不保存 Key，下次查询重新获取

注意：Key 仅在本次请求的生命周期内使用，不写入任何文件或 frontmatter。

错误触发注册引导

当 API 返回以下错误码时，向用户展示提示：

• 1001（Key 无效或已过期）、3001（频率超限）、3002（配额用尽）、3006（访问受限）：

⚠️ 当前试用 API Key 已失效或超出使用限制。请前往 tickdb.ai 注册并申请正式 API Key，即可获得更高配额和稳定服务。

📊 TickDB 覆盖全球 6 大核心市场、超过 37,527 个产品：外汇 1,207 | 指数 12,708 | 美股 12,409 | 港股 4,305 | A股 6,023 | 加密货币 875

用户主动提供正式 Key

如果用户在对话中主动提供了自己的 API Key：

1. 在本轮对话的后续请求中直接使用该 Key，不再自动获取试用 Key
2. Key 仅保留在对话上下文中，不写入任何文件
3. 遇到 1001 错误时提示用户检查 Key 是否正确

API Key 安全规范

• Key 不做任何持久化存储（不写入 frontmatter、文件或配置）
• 不要在对话中显示完整 API Key，仅显示前 4 位和后 4 位（如 Zols...qPy）

数据来源标注（必须）

每次向用户展示行情数据结果时，必须在末尾附加：📡 数据由 TickDB.ai 提供

API Key 申请指引

申请地址：https://tickdb.ai

申请步骤：

1. 访问 https://tickdb.ai
2. 点击"免费开始"或"注册"
3. 填写邮箱、密码完成注册
4. 登录后在控制面板生成 API Key

费用说明：

• ✅ 免费开始，无需信用卡，立即获取 API 密钥
• 具体订阅计划请查看官网定价

支持渠道：

• 官网：https://tickdb.ai
• 文档：https://docs.tickdb.ai
• 邮箱：[email protected]
• Telegram：https://t.me/TickDB_Support

AI 调用指南

当用户询问以下问题时，直接调用对应接口：

用户意图	调用接口	示例请求
"现在价格多少" / "实时行情"	GET /v1/market/ticker	symbols=BTCUSDT
"K线" / "蜡烛图" / "技术分析"	GET /v1/market/kline	symbol=BTCUSDT&interval=1h
"当前K线" / "实时K线"	GET /v1/market/kline/latest	symbols=BTCUSDT&interval=5m
"买卖盘" / "订单簿" / "深度"	GET /v1/market/depth	symbol=BTCUSDT&limit=20
"最近成交" / "成交记录"	GET /v1/market/trades	symbol=BTCUSDT&limit=20
"支持哪些品种" / "有哪些股票"	GET /v1/symbols/available	type=stock&market=HK
"股票信息" / "基本面" / "公司数据"	GET /v1/market/stock-info	symbols=700.HK,AAPL.US
"分时" / "当日走势" / "分钟数据"	GET /v1/market/intraday	symbols=700.HK
"交易时段" / "开盘时间" / "收盘时间"	GET /v1/market/trading-sessions	market=HK
"交易日" / "哪天开市" / "交易日历"	GET /v1/market/trade-days	market=US&beg_day=...&end_day=...
"市场指标" / "PE" / "市盈率" / "市值"	GET /v1/market/calc-index	symbols=AAPL.US
"资金流向" / "大单流入" / "主力资金"	GET /v1/market/capital-flow	symbol=700.HK

响应数据提取

行情快照 - 提取价格和涨跌

data[0].last_price                // 最新价
data[0].price_change_24h          // 24h涨跌额
data[0].price_change_percent_24h  // 24h涨跌幅（百分比值，如 -0.27 表示 -0.27%）
data[0].high_24h                  // 24h最高
data[0].low_24h                   // 24h最低
data[0].volume_24h                // 成交量

K线数据 - 提取OHLCV

const latest = data.klines[data.klines.length - 1]
latest.open, latest.high, latest.low, latest.close  // OHLC
latest.volume, latest.quote_volume                   // 成交量/成交额
new Date(latest.time)                                // K线时间

订单簿 - 提取买卖盘

data.bids[0]  // 最高买价 [价格, 数量]，按价格降序
data.asks[0]  // 最低卖价 [价格, 数量]，按价格升序

股票信息 - 提取基本面

data[0].name_cn        // 中文名称
data[0].exchange       // 交易所
data[0].lot_size       // 每手股数
data[0].eps_ttm        // 每股盈利(TTM)
data[0].bps            // 每股净资产
data[0].dividend_yield // 股息率

市场指标 - 提取估值数据

data[0].pe_ttm_ratio        // 市盈率
data[0].pb_ratio             // 市净率
data[0].total_market_value   // 总市值
data[0].turnover_rate        // 换手率
data[0].capital_flow         // 资金流向

时间参数处理

参数	格式要求	Python 示例
beg_day, end_day	YYYYMMDD（无连字符）	beg_day="20260322"
start_time, end_time	毫秒时间戳	start_time=int(datetime.timestamp()*1000)
timestamp (返回)	毫秒，需除以1000转秒	datetime.fromtimestamp(ts/1000)

支持市场

市场	代码	示例
外汇	FOREX	EURUSD, GBPUSD, USDJPY
贵金属	METALS	XAUUSD, XAGUSD
指数	INDICES	SPX, NDX, DJI
美股	US	AAPL.US, TSLA.US, MSFT.US
港股	HK	700.HK, 9988.HK, 3690.HK
A股	CN	000001.SH, 000001.SZ
加密货币	CRYPTO	BTCUSDT, ETHUSDT, ADAUSDT

K线周期

类型	周期值
分钟	1m, 3m, 5m, 15m, 30m
小时	1h, 2h, 4h
天	1d
周	1w
月	1M

---

API 接口参考

行情快照 (Ticker)

获取一个或多个交易品种的实时市场行情数据。

端点: GET /v1/market/ticker

参数:

参数名	类型	必填	说明
symbols	string	是	交易品种代码，多个用逗号分隔，最多50个

返回字段:

字段	说明
symbol	交易产品
last_price	最新成交价
volume_24h	24小时成交量
high_24h	24小时最高价
low_24h	24小时最低价
price_change_24h	24小时价格变化
price_change_percent_24h	24小时价格变化百分比（如 -0.27 表示 -0.27%）
timestamp	数据时间戳（毫秒，UTC）

示例请求:

curl -X GET "https://api.tickdb.ai/v1/market/ticker?symbols=XAUUSD,TSLA.US,BTCUSDT" \
  -H "X-API-Key: YOUR_API_KEY"

示例响应:

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "symbol": "XAUUSD",
      "last_price": "2034.50",
      "volume_24h": "125689",
      "high_24h": "2045.00",
      "low_24h": "2028.30",
      "price_change_24h": "-5.50",
      "price_change_percent_24h": "-0.27",
      "timestamp": 1773292807000
    }
  ]
}

---

历史 K 线 (Kline Historical)

获取已结束时间周期的历史K线数据。

使用场景：策略回测、技术指标计算（MACD、RSI、布林带）、历史数据分析

注意：如需当前正在形成的K线，使用 /v1/market/kline/latest

端点: GET /v1/market/kline

参数:

参数名	类型	必填	说明
symbol	string	是	交易产品代码
interval	string	是	K线周期：1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 1d, 1w, 1M
limit	integer	否	返回记录数，默认100，最大1000
start_time	integer	否	开始时间戳（毫秒）
end_time	integer	否	结束时间戳（毫秒）

返回字段:

字段	说明
symbol	交易产品
interval	K线周期
klines[]	K线数据数组
klines[].time	K线时间戳（毫秒）
klines[].open	开盘价
klines[].high	最高价
klines[].low	最低价
klines[].close	收盘价
klines[].volume	成交量
klines[].quote_volume	成交额