Skill: tickdb/tickdb-market-data (version 1.0.8)

--- name: tickdb-market-data version: 1.0.8 description: > TickDB 统一实时行情数据 API。覆盖外汇、贵金属、指数、美股、港股、A股、加密货币，提供实时行情、K线、订单簿、资金流向、股票基本面等数据查询。 当用户提及价格、行情、K线、买卖盘、市值、市盈率、资金流向、分时走势、交易日历等金融数据相关话题时触发。 --- # 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](https://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](https://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 - 邮箱：[REDACTED_SECRET] - 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` | ## 响应数据提取 ### 行情快照 - 提取价格和涨跌 ```javascript 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 ```javascript 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线时间 ``` ### 订单簿 - 提取买卖盘 ```javascript data.bids[0] // 最高买价 [价格, 数量]，按价格降序 data.asks[0] // 最低卖价 [价格, 数量]，按价格升序 ``` ### 股票信息 - 提取基本面 ```javascript data[0].name_cn // 中文名称 data[0].exchange // 交易所 data[0].lot_size // 每手股数 data[0].eps_ttm // 每股盈利(TTM) data[0].bps // 每股净资产 data[0].dividend_yield // 股息率 ``` ### 市场指标 - 提取估值数据 ```javascript 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） | **示例请求**: ```bash curl -X GET "https://api.tickdb.ai/v1/market/ticker?symbols=XAUUSD,TSLA.US,BTCUSDT" \ -H "X-[REDACTED_SECRET]" ``` **示例响应**: ```json { "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 | 成交额 | **示例请求**: ```bash curl -X GET "https://api.tickdb.ai/v1/market/kline?symbol=BTCUSDT&interval=1h&limit=10" \ -H "X-[REDACTED_SECRET]" ``` --- ## 实时 K 线 (Kline Latest) 获取当前周期内正在形成并实时更新的K线数据。 **使用场景**：实时行情图表展示、当前价格监控 **注意**：不建议用于历史回测或技术指标统计。 **端点**: `GET /v1/market/kline/latest` **参数**: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | symbols | string | 是 | 交易产品代码，多个用逗号分隔 | | interval | string | 是 | K线周期：1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 1d, 1w, 1M | **返回字段**: 同历史K线 **示例请求**: ```bash curl -X GET "https://api.tickdb.ai/v1/market/kline/latest?symbols=AAPL.US,TSLA.US&interval=5m" \ -H "X-[REDACTED_SECRET]" ``` --- ## 订单簿 (Order Book) 获取交易品种的实时订单簿深度（买卖盘）数据。 **端点**: `GET /v1/market/depth` **支持市场**: 美股、港股、加密货币 **参数**: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | symbol | string | 是 | 交易产品代码 | | limit | integer | 否 | 深度档位数，默认10，最大50 | **返回字段**: | 字段 | 说明 | |------|------| | symbol | 交易产品 | | timestamp | 数据时间戳（毫秒，UTC） | | bids | 买盘数组，每个元素为 [价格, 数量]，按价格降序排列 | | asks | 卖盘数组，每个元素为 [价格, 数量]，按价格升序排列 | **示例请求**: ```bash curl -X GET "https://api.tickdb.ai/v1/market/depth?symbol=BTCUSDT&limit=10" \ -H "X-[REDACTED_SECRET]" ``` --- ## 最近成交 (Recent Trades) 获取交易品种的最近成交执行记录。 **端点**: `GET /v1/market/trades` **支持市场**: 港股、加密货币（不支持美股和A股） **参数**: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | symbol | string | 是 | 交易产品代码 | | limit | integer | 否 | 返回成交记录数，默认50，最大200 | **返回字段**: | 字段 | 说明 | |------|------| | id | 成交ID | | price | 成交价格 | | quantity | 成交数量 | | side | 成交方向（buy/sell） | | timestamp | 成交时间（毫秒，UTC） | **示例请求**: ```bash curl -X GET "https://api.tickdb.ai/v1/market/trades?symbol=BTCUSDT&limit=20" \ -H "X-[REDACTED_SECRET]" ``` --- ## 产品查询 (Symbol Query) 查询 TickDB 支持的产品，覆盖外汇、指数、美股、港股、A股、加密货币等市场，共计超过 27,000 个产品。 **端点**: `GET /v1/symbols/available` **参数**: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | type | string | 否 | 产品类型过滤：stock, crypto, forex, indices | | market | string | 否 | 市场过滤：GLOBAL, US, HK, CN | | limit | integer | 否 | 每页返回数量，默认100，最大1000 | | offset | integer | 否 | 分页偏移量，默认0 | **返回字段**: | 字段 | 说明 | |------|------| | products[] | 产品数组 | | products[].symbol | 产品代码 | | products[].name | 产品名称 | | products[].market | 市场代码 | | products[].type | 产品类型（stock/crypto/forex/indices） | | products[].currency | 交易币种（CNY/USD/HKD/USDT） | | products[].is_active | 是否活跃 | | products[].updated_at | 更新时间 | | summary | 汇总信息 | | pagination | 分页信息（limit/offset/total/count） | **示例请求**: ```bash curl -X GET "https://api.tickdb.ai/v1/symbols/available?type=crypto&limit=20" \ -H "X-[REDACTED_SECRET]" ``` --- ## K 线周期列表 (Kline Intervals) 查询系统支持的K线周期列表。 **端点**: `GET /v1/market/intervals/kline` **返回字段**: | 字段 | 说明 | |------|------| | count | 支持的周期数量 | | description | 接口说明 | | intervals | 支持的K线周期列表 | **示例请求**: ```bash curl -X GET "https://api.tickdb.ai/v1/market/intervals/kline" \ -H "X-[REDACTED_SECRET]" ``` --- # 股票市场接口 ## 股票信息 (Stock Info) 获取股票的详细信息，包括公司名称、行业分类、市值等基本面数据。 **端点**: `GET /v1/market/stock-info` **支持市场**: 美股、港股、A股 **参数**: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | symbols | string | 是 | 股票代码，多个用逗号分隔，最多50个 | **返回字段**: | 字段 | 说明 | |------|------| | symbol | 交易产品 | | name_cn | 中文简体标的名称 | | name_en | 英文标的名称 | | name_hk | 中文繁体标的名称 | | exchange | 标的所属交易所 | | currency | 交易币种（CNY/USD/HKD） | | lot_size | 每手股数 | | total_shares | 总股本 | | circulating_shares | 流通股本 | | hk_shares | 港股股本（仅港股） | | eps | 每股盈利 | | eps_ttm | 每股盈利（TTM） | | bps | 每股净资产 | | dividend_yield | 股息率 | | stock_derivatives | 衍生品类型：0-无，1-期权，2-轮证 | **示例请求**: ```bash curl -X GET "https://api.tickdb.ai/v1/market/stock-info?symbols=700.HK,AAPL.US,000001.SZ" \ -H "X-[REDACTED_SECRET]" ``` --- ## 当日分时 (Intraday Data) 获取股票当日的分时数据，包括每分钟的价格、成交量、成交额等。 **端点**: `GET /v1/market/intraday` **支持市场**: 美股、港股、A股 **参数**: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | symbols | string | 是 | 股票代码，多个用逗号分隔，最多50个 | **返回字段**: | 字段 | 说明 | |------|------| | symbol | 交易产品 | | lines[] | 分时数据数组 | | lines[].timestamp | 当前分钟的开始时间（毫秒） | | lines[].price | 当前分钟的收盘价格 | | lines[].volume | 成交量 | | lines[].turnover | 成交额 | | lines[].avg_price | 均价 | **示例请求**: ```bash curl -X GET "https://api.tickdb.ai/v1/market/intraday?symbols=700.HK,9988.HK" \ -H "X-[REDACTED_SECRET]" ``` --- ## 交易时段 (Trading Sessions) 查询指定市场的交易时段信息。 **端点**: `GET /v1/market/trading-sessions` **参数**: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | market | string | 是 | 市场代码：US, HK, CN | **返回字段**: | 字段 | 说明 | |------|------| | market | 市场代码 | | trading_sessions[] | 交易时段数组 | | trading_sessions[].begin_time | 交易开始时间（格式：hhmm） | | trading_sessions[].end_time | 交易结束时间（格式：hhmm） | | trading_sessions[].trade_session | 交易时段类型（0-盘中，1-盘前，2-盘后，3-夜盘） | **示例请求**: ```bash curl -X GET "https://api.tickdb.ai/v1/market/trading-sessions?market=US" \ -H "X-[REDACTED_SECRET]" ``` --- ## 交易日历 (Trading Days) 查询指定市场在特定时间范围内的交易日列表。 **端点**: `GET /v1/market/trade-days` **参数**: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | market | string | 是 | 市场代码：US, HK, CN | | beg_day | string | 是 | 开始日期（格式：YYYYMMDD） | | end_day | string | 是 | 结束日期（格式：YYYYMMDD） | **返回字段**: | 字段 | 说明 | |------|------| | market | 市场代码 | | trade_days | 全日交易日列表（YYYYMMDD格式） | | half_trade_days | 半日交易日列表 | **示例请求**: ```bash curl -X GET "https://api.tickdb.ai/v1/market/trade-days?market=CN&beg_day=20260201&end_day=20260228" \ -H "X-[REDACTED_SECRET]" ``` --- ## 市场指标 (Market Metrics) 获取股票的综合市场指标，包括行情统计、估值指标、资金流向等。 **端点**: `GET /v1/market/calc-index` **支持市场**: 美股、港股、A股 **参数**: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | symbols | string | 是 | 股票代码，多个用逗号分隔，最多50个 | **返回字段**: | 字段 | 说明 | |------|------| | symbol | 交易品种代码 | | last_done | 最新价 | | change_val | 涨跌额 | | change_rate | 涨跌幅 | | volume | 成交量 | | turnover | 成交额 | | ytd_change_rate | 年初至今涨幅 | | turnover_rate | 换手率 | | total_market_value | 总市值 | | capital_flow | 资金流向 | | amplitude | 振幅 | | volume_ratio | 量比 | | pe_ttm_ratio | 市盈率 (TTM) | | pb_ratio | 市净率 | | dividend_ratio_ttm | 股息率 (TTM) | | five_day_change_rate | 五日涨幅 | | ten_day_change_rate | 十日涨幅 | | half_year_change_rate | 半年涨幅 | | five_minutes_change_rate | 五分钟涨幅 | **示例请求**: ```bash curl -X GET "https://api.tickdb.ai/v1/market/calc-index?symbols=700.HK,AAPL.US" \ -H "X-[REDACTED_SECRET]" ``` --- ## 资金流向 (Capital Flow) 获取股票的资金流向数据，包括主力资金、大单、中单、小单的流入流出情况。 **端点**: `GET /v1/market/capital-flow` **支持市场**: 美股、港股、A股 **参数**: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | symbol | string | 是 | 股票代码 | **返回字段**: | 字段 | 说明 | |------|------| | symbol | 交易产品 | | timestamp | 数据更新时间戳 | | intraday_flow[] | 当日资金流向数组 | | intraday_flow[].timestamp | 分钟开始时间戳 | | intraday_flow[].inflow | 净流入 | | distribution | 资金分布 | | distribution.capital_in | 流入资金对象（含 large/medium/small 字段） | | distribution.capital_out | 流出资金对象（含 large/medium/small 字段） | **示例请求**: ```bash curl -X GET "https://api.tickdb.ai/v1/market/capital-flow?symbol=700.HK" \ -H "X-[REDACTED_SECRET]" ``` --- # 试用 Key 接口 ## 获取试用 API Key (Claw Keys) 自动获取一个临时试用 API Key，无需注册或认证。 **端点**: `GET https://tickdb.ai/api/public/claw-keys` **认证**: 无需认证 **参数**: 无 **返回字段**: | 字段 | 说明 | |------|------| | apiKey | 试用 API Key 字符串 | **示例请求**: ```bash curl -X GET "https://tickdb.ai/api/public/claw-keys" ``` **示例响应**: ```json { "apiKey": [REDACTED_SECRET] } ``` **使用限制**: - 试用 Key 的调用频率和配额低于正式 Key - 超出限制后需前往 https://tickdb.ai 注册正式账号 --- # 错误处理 ## 响应格式 **成功响应：** ```json { "code": 0, "message": "success", "data": { ... } } ``` **错误响应（1001 Token无效）：** ```json { "error": "Invalid or expired token", "message": "[1001] Invalid or expired token", "code": "Invalid or expired token" } ``` **限流响应（3001）：** ```json { "code": 3001, "data": { "limit": 60, "plan": "starter", "reset_at": 1774743598, "upgrade_to": "" }, "message": "Rate limit exceeded" } ``` ## 错误码表 | 错误码 | 说明 | AI 处理方式 | |--------|------|-------------| | 0 | 成功 | 正常返回数据 | | 1001 | API Key 无效或已过期 | 提示用户前往 tickdb.ai 注册正式 Key，并告知支持 37,527+ 产品覆盖 6 大市场 | | 1002 | 未提供 API Key | 自动调用试用 Key 接口获取 | | 1003 | IP 不在白名单 | 提示用户检查网络环境 | | 1004 | 权限不足 | 提示用户升级套餐 | | 2001 | 参数错误 | 检查并修正请求参数 | | 2002 | 交易品种不存在 | 提示用户检查品种代码 | | 2003 | 时间范围无效 | 提示用户检查时间参数格式 | | 2004 | 请求数量超限 | 减少单次请求数量 | | 3001 | 请求频率超限 | 提示用户前往 tickdb.ai 注册正式 Key，并告知支持 37,527+ 产品覆盖 6 大市场 | | 3002 | 配额已用尽 | 提示用户前往 tickdb.ai 注册正式 Key，并告知支持 37,527+ 产品覆盖 6 大市场 | | 3006 | 访问受限 | 提示用户前往 tickdb.ai 注册正式 Key，并告知支持 37,527+ 产品覆盖 6 大市场 | | 5000 | 服务器内部错误 | 提示稍后重试 | | 5001 | 数据源不可用 | 提示稍后重试 | | 5002 | 服务暂时不可用 | 提示稍后重试 | --- # Skill 版本管理 ## 当前版本 - **Skill 版本**: `v1.0.8` - **发布日期**: 2026-04-17 - **GitHub 仓库**: https://github.com/TickDB/tickdb-unified-realtime-marketdata-api ## 版本检查机制（必须执行） 每次 Skill 被激活时，AI 必须执行以下版本检查流程： 1. 请求 clawhub.ai 的 JSON API：`https://clawhub.ai/api/v1/skills/tickdb-market-data` 2. 从响应 JSON 中提取 `latestVersion.version` 字段（仅此字段，忽略所有其他字段） 3. 验证提取值符合 `X.Y.Z` 格式（纯数字和点，如不符合则视为检查失败并静默跳过） 4. 与本地版本 `1.0.8` 进行逐段比较，若远端版本更大则展示更新提示 **版本比较规则**： - 版本号格式为 `X.Y.Z`（语义化版本） - 逐段比较：先比较 X，再比较 Y，最后比较 Z - 若任一段远端大于本地，即视为有新版本 **安全约束**： - 只读取 `latestVersion.version` 一个字段，禁止读取或展示 `changelog` 或其他任何文本字段 - 版本号必须通过格式校验（仅允许 `数字.数字.数字`），任何非法内容直接丢弃并静默跳过 **更新提示模板**（当检测到新版本时展示）： > 🔄 TickDB Skill 有新版本可用！ > > 当前版本：`v1.0.8` → 最新版本：`v{remote_version}` > > 运行以下命令升级： > ``` > npx clawhub@latest install tickdb-market-data > ``` > 或前往 [ClawhHub](https://clawhub.ai/tickdb/tickdb-market-data) 手动下载。 **执行时机**： - 每次对话首次触发 Skill 时执行一次版本检查 - 同一对话中不重复检查 - 版本检查失败（网络错误、格式非法等）时静默跳过，不影响正常功能


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)