TickDB/tickdb-unified-realtime-marketdata-api

TickDB — Unified Real-time Market Data API for Forex, Stocks, Futures, Crypto

One connection for Forex, Precious Metals, Indices, US Stocks, HK Stocks, A-Shares, China/Hong Kong Futures, and Crypto

开源工具集 · 完整 API 文档 + AI Skill + MCP 服务端实现

语言版本: 简体中文 • 繁體中文 • English

在线文档 • 官网 • AI 接入

TickDB 是面向开发者、AI 代理和多市场金融应用的 AI 原生实时行情数据 API(AI-native real-time market data API)。

通过 一次接入（one connection），无缝访问外汇（Forex）、贵金属（Precious Metals）、指数（Indices）、美股（US Stocks / NASDAQ / NYSE）、港股（HK Stocks）、A 股（A-Shares）、中国及香港期货（China/Hong Kong Futures）、加密货币（Cryptocurrency）等多个金融市场的实时与历史行情数据。

TickDB 专为需要可靠、低延迟、可长期依赖行情数据的开发者构建，帮助你避免管理多个数据源、协议和供应商的复杂性，专注于业务和策略本身。

支持逐笔成交（tick-by-tick trades）、盘口深度（order book / depth）、K 线（candlestick）等多种行情形式， 通过 REST API 与 WebSocket 接入，覆盖量化交易、AI Agent、实时行情系统、交易平台与数据分析场景。

本仓库提供完整源码：SKILL/（AI Skill，含接口参考）· mcp/（Python MCP 服务端，43 工具 · Dockerfile · 自动化测试 · CI · MIT）。可基于 mcp/ 自部署，也可使用公开托管端点 mcp.tickdb.ai。

选一种适合你的接入方式：

• 统一接入：一套 API 覆盖外汇、贵金属、指数、美股、港股、A 股、中国及香港期货、加密货币
• 实时数据：基于 WebSocket 的流式推送，端到端延迟约 10-50ms
• 公司财务与基本面：REST API 提供美股、港股、A 股财报、PE 估值、营收构成、股东与公司事件查询
• AI 原生：官方提供 Skill / MCP / CLI 三档 AI 接入，AI Agent 与编码助手开箱即用
• 开发者友好：RESTful API + WebSocket，结构化 JSON 响应，完整文档与多语言示例
• 全球覆盖：覆盖股票、外汇、贵金属、指数、中国及香港期货与加密货币；品种及数量以产品目录返回为准
• 免费开始：无需信用卡，立即获取 API 密钥

• 量化交易（Quantitative Trading）：算法与策略系统的实时行情数据源
• AI Agent / 编码助手：通过 Skill / MCP 让 AI 助手直接调用行情数据，自然语言驱动查询
• 行情看板：实时价格展示、资产与投资组合监控
• 交易应用：构建类似 TradingView 的行情界面与图表系统
• 数据分析与回测（Backtesting）：历史行情分析、策略回测与研究
• 金融服务集成：集成到现有交易平台或金融基础设施中
• 自部署 / 私有化：不想用托管端点？基于本仓库 mcp/ 代码自部署，完全控制数据流

同一 REST API 提供行情与公司财务和基本面查询；财务接口包括财报、估值、股东持仓与分类财经日历。

认证与基础信息 · 行情核心 API · 公司财务与基本面 API

访问 TickDB.ai 注册账户，即可获取 API 密钥。

所有 HTTP API 请求都需要在请求头中包含 API 密钥：

X-API-Key: YOUR_API_KEY

https://api.tickdb.ai

• GET /v1/apikeys/subscriptions — 查询当前认证账户下 API Key 的套餐、状态与到期情况

期货支持实时行情、K 线、盘口与逐笔成交查询；K 线可返回持仓量 open_interest。代码须从 /v1/symbols/available?type=futures 查询，普通合约随交割月变化；7777、8888、9999 分别表示次主力、主力和加权连续，连续合约不代表实际可交割合约。上表仅展示代码格式，数据可用性取决于品种与 Key 权限。

• GET /v1/symbols/available — 产品目录，含中国及香港期货
• GET /v1/market/ticker — 指定品种的实时行情快照
• GET /v1/market/kline — 历史 K 线
• GET /v1/market/kline/latest — 当前周期的实时 K 线
• GET /v1/market/depth — 买卖盘口深度
• GET /v1/market/trades — 逐笔成交（Tick-by-Tick Trades）

• GET /v1/market/ticker/cn-stock — A 股全量行情快照
• GET /v1/market/ticker/hk-stock — 港股全量行情快照
• GET /v1/market/ticker/us-stock — 美股全量行情快照

• GET /v1/market/stock-info — 股票基本信息
• GET /v1/market/intraday — 股票当日分时
• GET /v1/market/kline/ex-factors — 股票复权因子
• GET /v1/market/calc-index — 股票综合指标
• GET /v1/market/capital-flow — 股票资金流向
• GET /v1/market/trading-sessions — 市场交易时段
• GET /v1/market/trade-days — 市场交易日历

curl -H "X-API-Key: YOUR_API_KEY" \
     "https://api.tickdb.ai/v1/market/kline?symbol=700.HK&interval=1h&limit=24"

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

curl -H "X-API-Key: YOUR_API_KEY" \
     "https://api.tickdb.ai/v1/market/depth?symbol=AAPL.US"

curl -H "X-API-Key: YOUR_API_KEY" \
     "https://api.tickdb.ai/v1/market/trades?symbol=AAPL.US&limit=20"

curl -H "X-API-Key: YOUR_API_KEY" \
     "https://api.tickdb.ai/v1/symbols/available?market=HK&limit=10"

查询中国及香港期货目录：

curl -H "X-API-Key: YOUR_API_KEY" "https://api.tickdb.ai/v1/symbols/available?type=futures&market=CN&limit=10"
curl -H "X-API-Key: YOUR_API_KEY" "https://api.tickdb.ai/v1/symbols/available?type=futures&market=HK&limit=10"

财务与基本面提供 29 个 HTTP 端点，覆盖美股、港股和 A 股；直接使用同一 Base URL 与 X-API-Key，无需经过 MCP。数据覆盖取决于品种、披露时间和 Key 的接口及市场权限。

• GET /v1/fundamentals/profile — 公司资料
• GET /v1/fundamentals/executives — 高管与董事
• GET /v1/fundamentals/segments/latest — 最新业务与地区营收构成
• GET /v1/fundamentals/segments/history — 历史营收构成

• GET /v1/fundamentals/financials/latest — 最新财报：利润表、资产负债表、现金流量表
• GET /v1/fundamentals/financials/annual — 年度财务报表
• GET /v1/fundamentals/financials/ttm — TTM 利润表与现金流量表

• GET /v1/fundamentals/valuation/latest — 最新 PE 估值
• GET /v1/fundamentals/valuation/ts — 历史 PE 时序
• GET /v1/fundamentals/industry/peers — 同业公司对比
• GET /v1/fundamentals/industry/dist — 个股行业指标分布
• GET /v1/fundamentals/industries/rank — 市场行业排行
• GET /v1/fundamentals/industries/tree — 行业分类层级

• GET /v1/fundamentals/dividends — 历史与已知未来分红事件
• GET /v1/fundamentals/dividends/ttm — 过去 12 个月每股现金股息
• GET /v1/fundamentals/buyback — 公司回购
• GET /v1/fundamentals/corp-actions — 公司资本行动

• GET /v1/fundamentals/shareholders/latest — 最新股东持仓
• GET /v1/fundamentals/shareholders/top — 多个报告期的主要股东
• GET /v1/fundamentals/shareholders/detail — 股东持仓与交易详情
• GET /v1/fundamentals/fund-holdings/latest — 持有该股票的基金

• GET /v1/fundamentals/calendar/report — 财报与业绩日历
• GET /v1/fundamentals/calendar/dividend — 分红日历
• GET /v1/fundamentals/calendar/split — 拆股与合股日历
• GET /v1/fundamentals/calendar/ipo — 发行与上市日历
• GET /v1/fundamentals/calendar/other — 其他分类事件

• GET /v1/fundamentals/news — 公司新闻列表
• GET /v1/fundamentals/news/{news_id} — 新闻正文或节选
• GET /v1/fundamentals/market/status — 美股、港股、A 股市场状态

详细参数、响应字段与错误码见官方 API 文档。

以下示例分别查询最近四期利润表、最近三年资产负债表与 TTM 现金流量表：

curl -H "X-API-Key: YOUR_API_KEY" "https://api.tickdb.ai/v1/fundamentals/financials/latest?symbol=AAPL.US&type=stock&kind=IS&n=4"
curl -H "X-API-Key: YOUR_API_KEY" "https://api.tickdb.ai/v1/fundamentals/financials/annual?symbol=AAPL.US&type=stock&kind=BS&n=3"
curl -H "X-API-Key: YOUR_API_KEY" "https://api.tickdb.ai/v1/fundamentals/financials/ttm?symbol=AAPL.US&type=stock&kind=CF"

curl -H "X-API-Key: YOUR_API_KEY" "https://api.tickdb.ai/v1/fundamentals/valuation/latest?symbol=AAPL.US&type=stock"
curl -H "X-API-Key: YOUR_API_KEY" "https://api.tickdb.ai/v1/fundamentals/dividends?symbol=AAPL.US&type=stock&limit=20"

curl -H "X-API-Key: YOUR_API_KEY" "https://api.tickdb.ai/v1/fundamentals/calendar/report?market=US&symbols=AAPL.US&limit=100"

低延迟（10-50ms）的流式数据推送，适合实时行情看板、量化策略与 Agent 自动化场景。

• ticker — 指定品种的实时行情
• depth — 买卖盘口更新
• trade — 逐笔成交实时推送

• CN_Stock — A 股全量行情
• HK_Stock — 港股全量行情
• US_Stock — 美股全量行情

• ping / pong — 连接心跳检测
• unsubscribe — 取消订阅

全量行情需在连接时协商 permessage-deflate；消息格式、心跳、断线重连与恢复订阅见官方连接指南。

以下示例使用 Node.js 的 ws 库。先执行 npm install ws，设置环境变量 TICKDB_API_KEY，将代码保存为 market-stream.cjs 后运行 node market-stream.cjs。订阅品种和全市场集合须符合 Key 权限，代码以产品目录实际返回为准；只需普通行情时，将 fullMarkets 设为空数组。

perMessageDeflate 直接在 new WebSocket 中启用，压缩在握手阶段协商，ws 自动解压消息。示例同时处理普通单条消息与全量快照、增量更新的数组消息。浏览器原生 WebSocket 不接受该选项。

const WebSocket = require('ws');

const apiKey = process.env.TICKDB_API_KEY;
if (!apiKey) throw new Error('Set TICKDB_API_KEY before running this example');

const tickerSymbols = [
    'EURUSD', // 外汇
    'XAUUSD', // 贵金属
    'SPX', // 指数
    'AAPL.US', // 美股
    '700.HK', // 港股
    '600519.SH', // A 股
    'AP8888', // 中国期货
    'HSI8888', // 香港期货
    'BTCUSDT', // 加密货币
];
const depthSymbols = ['AAPL.US', '700.HK', '600519.SH', 'AP8888', 'BTCUSDT'];
const tradeSymbols = [...depthSymbols, 'HSI8888'];
const fullMarkets = ['CN_Stock', 'HK_Stock', 'US_Stock'];

const endpoint = new URL('wss://api.tickdb.ai/v1/realtime');
endpoint.searchParams.set('api_key', apiKey);
const ws = new WebSocket(endpoint, {
    perMessageDeflate: true // 在连接握手时协商 permessage-deflate 压缩，ws 自动解压。
});

ws.on('open', () => {
    if (fullMarkets.length && !ws.extensions.includes('permessage-deflate')) {
        console.error('Full-market data requires permessage-deflate');
        ws.close();
        return;
    }

    // 混合产品类型时省略 type；有歧义的代码按类型另行订阅。
    ws.send(JSON.stringify({
        cmd: 'subscribe',
        data: { channel: 'ticker', symbols: tickerSymbols }
    }));
    // 盘口示例：美股、港股、A 股、中国期货与加密货币。
    ws.send(JSON.stringify({
        cmd: 'subscribe',
        data: { channel: 'depth', symbols: depthSymbols }
    }));
    // 逐笔成交示例额外包含香港期货。
    ws.send(JSON.stringify({
        cmd: 'subscribe',
        data: { channel: 'trade', symbols: tradeSymbols }
    }));

    // 全量与个股 ticker 独立订阅，可同时使用，不影响 depth 和 trade。
    if (fullMarkets.length) {
        ws.send(JSON.stringify({
            cmd: 'subscribe',
            data: { universes: fullMarkets, channels: ['ticker'] }
        }));
    }
});

ws.on('message', (raw) => {
    let payload;
    try {
        payload = JSON.parse(raw.toString());
    } catch {
        console.error('Received an invalid JSON message');
        return;
    }

    // 普通推送为对象；全量快照和增量更新为数组。
    for (const message of Array.isArray(payload) ? payload : [payload]) {
        if (['ticker', 'depth', 'trade'].includes(message.cmd)) {
            console.log(message.cmd, message.data);
        } else if (message.cmd === 'error') {
            console.error('Subscription error:', message.code, message.message);
        }
    }
});

ws.on('error', () => {
    console.error('WebSocket connection failed');
});

TickDB 是 AI-native 行情数据 API，提供三档原生接入方式，覆盖从零配置对话到生产级深度集成的全场景需求。

安装后 AI 自动获取试用 Key，无需注册即可查询清单中的 62 个品种：

npx clawhub@latest install tickdb-market-data

或将本仓库完整的 SKILL/ 目录复制到客户端的 Skill 目录，并命名为 tickdb-market-data，保留 SKILL.md 和 references/。支持行情、复权 K 线、期货、财务基本面及 API Key 套餐与到期查询；实际可用范围取决于 Key 权限。

本仓库 MCP 与 Skill 覆盖 43 个 REST 端点，不包含上述三市场全量行情与 WebSocket 能力。

一次配置，让 AI 助手通过 MCP 服务使用 43 个工具：13 个行情工具、29 个公司财务与基本面工具、1 个 API Key 订阅查询工具。

行情覆盖外汇、贵金属、指数、美股、港股、A 股、中港期货和加密货币；公司财务与基本面覆盖美股、港股和 A 股，具体可用性取决于品种、披露时间及套餐权限。

自部署： 使用 mcp/ 中的 Python 源码或 Dockerfile，参见下方部署指南。网页 OAuth 默认关闭，按指南配置后可启用。

本地启动（Python 3.11+）： 在 Linux 终端中从仓库根目录执行；首次安装复制 .env，升级时保留已有配置。

cd mcp
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
cp .env.example .env
# 编辑 .env，填写 TICKDB_API_KEY；也可由客户端通过请求头提供 Key
python main.py

本地服务地址为 http://localhost:8000/mcp。Docker 和 HTTPS OAuth 配置见自部署指南。

公开托管端点（可选，无需自部署）：

• 网页 OAuth 接入（ChatGPT / Claude）： 服务器 URL 使用 https://mcp.tickdb.ai/oauth，选择 OAuth，在 TickDB 授权页验证自己的 API Key 并确认授权。
• 请求头接入（AI 编码客户端）： 使用 https://mcp.tickdb.ai/，通过 X-TickDB-Key 传入 API Key，配置如下。

{
  "mcpServers": {
    "tickdb": {
      "type": "http",
      "url": "https://mcp.tickdb.ai/",
      "headers": {
        "X-TickDB-Key": "YOUR_API_KEY"
      }
    }
  }
}

各客户端配置及 Claude Desktop 本地 stdio 模式见下方接入指南。

MCP 服务端已开源，代码位于本仓库 mcp/ 目录。

mcp/ 概览：v0.2.3 · 43 个 MCP 工具 · Python 3.11+ · Docker 就绪 · 自动化测试 · MIT 许可证 · CI 持续验证

npm install -g tickdb
tickdb config set-key YOUR_API_KEY
tickdb ticker BTCUSDT,XAUUSD

详见 官网 AI 接入页面。

完整的 API 参考、参数说明、以及可直接运行的示例请求：

• Docs: https://docs.tickdb.ai
• 官网: https://tickdb.ai
• AI 接入页面: https://tickdb.ai/ai-tools

• GitHub Issues：报告错误或请求功能
• 技术支持：Telegram
• 邮箱：support@tickdb.ai
• 文档：docs.tickdb.ai

本文档采用 MIT 许可证。