tickdb/tickdb-unified-realtime-marketdata-api/skill

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 中）
• 时间格式: 按字段解析：多数行情时间戳为毫秒，资金流向为秒，财务日期为 YYYY-MM-DD，日期时间为 RFC3339（保留时区偏移）；交易时段为市场当地时间
• 响应格式: JSON

API Key 使用流程

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

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

用户请求金融数据
    │
    ├─ 用户是否在本轮对话中提供过正式 Key？
    │   ├─ 是 → 使用用户提供的 Key 调用 API（不受试用产品列表限制，仍受 endpoint、市场权限和上游覆盖限制）
    │   └─ 否 → 检查请求的品种是否在试用版允许范围内
    │       ├─ 在范围内 → 自动调用试用 Key 接口实时获取（见下方）
    │       └─ 不在范围内 → 直接告知用户该品种需要正式 Key（见「试用版产品范围」）
    │
    └─ API 返回错误？
        ├─ 1001/1005（Key 无效/过期）→ 检查 Key 或套餐有效期；试用用户可申请正式 Key
        ├─ 3001（频率超限）→ 按 Retry-After 等待，降低频率
        ├─ 3002（配额用尽）→ 等待重置或调整套餐
        ├─ 3009/3010（接口/财务市场未授权）→ 提示使用已开通相应权限的正式 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} 不在试用版支持范围内。试用版共支持 62 个品种：贵金属 2 个，其余所列类别各 10 个。

如需查询试用范围之外的产品，请前往 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 个

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

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

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

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

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

财务接口试用规则：只有试用列表中的美股、港股和 A 股可尝试使用试用 Key 请求 /v1/fundamentals/**。AI 必须先将用户的公司或无后缀代码解析为完整市场代码（如 AAPL.US、700.HK、600519.SH），再按试用列表精确匹配。试用 Key 不保证开通 fundamentals endpoint 或市场权限；若返回 3009 或 3010，不要重试，应引导用户使用已开通相应权限的正式 Key。

错误提示与试用边界

先按本文末尾错误码表说明具体原因和可行的处理方式，不把限流、产品不支持、历史范围限制或接口权限问题统一描述为“Key 失效”。正式 Key 用户应检查已有 Key 和套餐；试用用户遇到权限或配额限制时，可附加 申请正式 API Key 的提示，不保证注册后自动获得所有接口权限。

试用列表保持上述 62 个品种，未包含期货。试用查询分类日历时必须用 symbols 限定到允许的股票，不能通过省略筛选获取全市场数据。市场级行业和市场状态等无单品种筛选的查询，需要正式 Key；产品目录查询可用于发现支持代码，目录可见不代表拥有数据权限。新闻详情只能使用本次允许查询的股票新闻列表返回的 ID。

用户主动提供正式 Key

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

1. 在本轮对话的后续请求中直接使用该 Key，不再自动获取试用 Key
2. Key 仅保留在对话上下文中，不写入任何文件
3. 遇到 1001 错误时检查 Key；1005 检查套餐有效期；1002 检查请求头，不自动将正式 Key 换成试用 Key

API Key 套餐与到期查询

用户询问自己的 Key 套餐、状态或到期时间时，先读取 账户查询参考，使用用户提供的正式 Key 调用 GET /v1/apikeys/subscriptions。这是账户查询，不适用自动获取公共试用 Key 的流程。

API Key 安全规范

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

数据来源标注（必须）

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

API Key 申请指引

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

申请步骤：

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

费用说明：

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

支持渠道：

• 官网：https://tickdb.ai
• 文档：https://docs.tickdb.ai
• 邮箱：support@tickdb.ai
• Telegram：https://t.me/TickDB_Support

AI 调用指南

当用户询问以下问题时，先检查 Key、试用范围和参数要求；财务查询须读取对应参考，再调用接口：

响应数据提取

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

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

K线数据 - 提取OHLCV

// 历史接口 data 是对象；实时接口先按 symbol 选择 data 数组中的一项。
const series = Array.isArray(data) ? data.find(item => item.symbol === symbol) : data
const latest = series?.klines?.at(-1)
// 无 K 线时报告无数据；以下字段仅在 latest 存在时读取。
if (latest) {
  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         // 资金流向

财务基本面 - 提取数据

response.data                // fundamentals 主数据对象
response.data.rows           // 财务报表字段级记录，n 不是行数
response.data.metrics.PE     // 当前市盈率及近一年统计
response.data.points         // 历史PE：[RFC3339时间, 数值] 数组
response.page.next_cursor    // 分红、持股基金、分类日历的顶层游标
// 不假定存在 meta.fetched_at；缺失的数据时间不能以当前时间补造。

财务报表中的数值字段以字符串返回，以避免 JSON 浮点精度丢失。展示或计算前必须显式转换，不要仅根据 JSON 类型推断指标含义。

时间参数处理

市场、代码与产品类型

产品代码以 /v1/symbols/available 实际返回为准。普通期货合约随交割月变化；7777、8888、9999 分别为次主力、主力、加权连续，连续合约不代表实际可交割合约。

type 用于消除代码歧义，不能改变接口的市场覆盖。无歧义时可省略；HTTP 返回 AMBIGUOUS_SYMBOL 时按 data.available_types 选择类型，无法从用户意图确定时再澄清。混合产品类型批量查询不要强制指定同一 type；必要时按类型拆批。后缀冲突返回 2006。

股票基础接口和财务基本面支持美股、港股、A股，具体字段及报告期可用性以实际响应为准，不能把缺失或 null 当作零。

K线周期

API 接口参考

行情快照 (Ticker)

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

端点: GET /v1/market/ticker

参数:

除 symbol、last_price、timestamp 外，字段按条件返回。名称、类型、A股分类、开盘价、昨收、最优买卖价、成交额和美股扩展时段报价可能缺失。24h 字段对加密货币通常为滚动24小时，对传统市场通常为当日或当前交易时段。

返回字段:

示例请求:

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