# 数据规范 Source: https://docs.tickdb.ai/zh-Hans/data-specification 交易品种命名、时间戳和 K 线间隔规则。 ## 交易品种命名规则 * 外汇：`EURUSD` * 贵金属：`XAUUSD` * 指数：`SPX` * 美股：`AAPL.US` * 港股：`700.HK` * A 股：`000001.SZ`（深圳）、`600000.SH`（上海）、`920186.BJ`（北京） * 中国期货：`BU2609`（普通合约）、`AP7777`（次主力连续）、`AP8888`（主力连续）、`AP9999`（加权连续） * 香港期货：`HSI8888`（恒生指数期货）、`MHI8888`（小型恒生指数期货） * 加密货币：`BTCUSDT` 中国期货使用 `market=CN` 和 `type=futures`。普通合约代码会随交割月份变化；连续合约用于行情跟踪，不代表实际可交割合约。 ## 时间戳 * 时间字段的格式和单位以具体接口的字段说明为准，不应统一按毫秒解析。 * Unix 时间戳通常以毫秒为单位；资金流向接口的时间戳以秒为单位。日期可使用 `YYYY-MM-DD` 格式；日期时间可使用 RFC 3339 标准，如 `2026-09-21T05:30:00Z`。 * Unix 时间戳表示基于 UTC 的时刻；带时区偏移的日期时间字符串应按其偏移量解析。 # 错误码说明 Source: https://docs.tickdb.ai/zh-Hans/errors 接口返回的错误码含义及处理建议。 ## 错误响应约定 * 成功响应的 `code` 为数字 `0` * 错误响应的 `code` 可能是整数或字符串；客户端应先使用 `String(code)` 归一化后再比较 * 不要根据 `message` 文本编写判断逻辑；`message` 用于说明错误，可能随具体场景变化 * HTTP 状态码表示请求层面的结果，`code` 表示具体业务原因，客户端应同时检查两者 ### HTTP API HTTP 错误响应至少包含 `code` 和 `message`，部分接口还会返回 `error` 或 `data`： ```json theme={null} { "code": "2001", "message": "symbol parameter is required", "error": "2001" } ``` 财务与基本面接口通常返回以下结构： ```json theme={null} { "code": 40001, "message": "granularity must be daily or monthly", "data": null } ``` ### WebSocket 建连失败 在 WebSocket 升级完成前发生的鉴权错误是普通 HTTP 错误响应，此时连接尚未建立，客户端不会收到 WebSocket 消息。 | HTTP 状态 | `code` | 含义 | 处理建议 | | ------: | ------------------- | ----------------- | --------------------- | | 401 | `UNAUTHORIZED` | 未提供 API Key | 在连接 URL 中传入 `api_key` | | 401 | `INVALID_TOKEN` | API Key 无效或已失效 | 检查或重新生成 API Key | | 403 | `PERMISSION_DENIED` | 当前 API Key 无权建立连接 | 检查套餐权限或联系支持 | ### WebSocket 建连后错误 连接建立后的订阅或消息错误通过 WebSocket 消息返回，`cmd` 表示触发错误的命令： ```json theme={null} { "cmd": "error", "code": 2001, "message": "Invalid message format", "data": null } ``` ## 错误码速查表 ### 认证错误（1xxx） | 错误码 | HTTP／场景 | 含义 | 处理建议 | | -----: | ------- | ----------- | ------------------- | | `1001` | 401 | API Key 无效 | 检查 API Key 是否正确 | | `1002` | 401 | 未提供 API Key | 在请求头中添加 `X-API-Key` | | `1004` | 403 | 权限不足 | 检查当前套餐权限 | | `1005` | 401 | API Key 已过期 | 续费或升级套餐后重试 | ### 参数错误（2xxx） | 错误码 | HTTP／场景 | 含义 | 处理建议 | | -----: | --------- | --------------------------------- | ------------------------------------- | | `2001` | 400／WS 消息 | 请求参数错误 | 根据 `message` 检查缺失参数、格式或参数组合 | | `2002` | 404／WS 消息 | 交易品种不存在或不受支持 | 使用 `/v1/symbols/available` 查询可用代码 | | `2003` | 400／WS 消息 | 时间范围无效；在部分 WebSocket 订阅中也表示代码存在歧义 | 根据 `message` 和 `data` 修正时间，或补充 `type` | | `2004` | 400 | 请求数量超过接口限制 | 根据对应接口说明减少请求数量 | | `2005` | 400 | 交易产品代码格式不受支持 | 使用数据规范中公开的代码格式 | | `2006` | 400／WS 消息 | 代码后缀与请求的 `type` 冲突 | 修正代码或 `type`，确保二者一致 | | `2008` | 406 | 全量行情请求未启用压缩 | 按接口文档启用 HTTP 响应压缩 | HTTP 请求中的代码歧义返回字符串 `AMBIGUOUS_SYMBOL`；WebSocket 订阅中的代码歧义当前返回数字 `2003`。两者都应根据响应中的 `available_types` 补充 `type`。 ### 访问限制与配额错误（3xxx） | 错误码 | HTTP／场景 | 含义 | 处理建议 | | -----: | --------- | --------------------------- | ---------------------- | | `3001` | 429 | 请求频率超限 | 根据 `Retry-After` 等待后重试 | | `3002` | 403 | 配额已用尽 | 等待配额重置或升级套餐 | | `3003` | 429 | WebSocket 连接数超限 | 关闭不再使用的连接 | | `3004` | 403／WS 消息 | 订阅数量超限 | 取消部分订阅或减少代码数量 | | `3005` | 429 | 该代码短时间内请求过于频繁 | 短暂等待后重试，避免集中重复请求同一代码 | | `3006` | 403 | 当前套餐不支持该交易产品 | 更换产品或调整套餐 | | `3007` | 403 | K 线查询范围超过当前套餐限制 | 缩短历史范围或调整套餐 | | `3008` | 403 | 当前套餐不支持按时间范围查询 K 线 | 改用支持的查询方式或调整套餐 | | `3009` | 403 | 当前 API Key 无权访问该接口 | 检查 API Key 权限或调整套餐 | | `3010` | 403 | 当前 API Key 无权访问该市场的财务与基本面数据 | 更换市场或调整套餐 | | `3011` | 403 | 财务与基本面历史查询深度超过限制 | 缩短历史范围或调整套餐 | | `3012` | 403 | 财务与基本面批量查询数量超过限制 | 减少单次查询的代码数量 | ### WebSocket 频道权限错误（4xxx） 当前公开 WebSocket 连接使用以下 4xxx 错误： | 错误码 | 含义 | 处理建议 | | -----: | ------------------ | ----------------- | | `4005` | 当前 API Key 无权订阅该频道 | 检查 WebSocket 频道权限 | 非法 JSON 和未知命令当前均返回 `cmd="error"`、`code=2001`。`4001–4004` 不属于当前公开接口的返回契约，因此不应依赖这些代码编写客户端逻辑。 ### 服务错误（5xxx） | 错误码 | HTTP／场景 | 含义 | 处理建议 | | -----: | --------- | --------------------- | ----------------- | | `5000` | 500 | 服务器内部错误 | 稍后重试；持续出现时联系支持 | | `5001` | 503 | 市场数据暂不可用 | 稍后重试 | | `5002` | 503 | 服务暂时不可用 | 稍后重试 | | `5003` | 503 | 当前请求暂无可用的数据服务 | 稍后重试，或更换交易产品／查询条件 | | `5004` | 503／WS 消息 | 实时行情暂不可用 | 稍后重试响应中标记为可重试的代码 | | `5005` | 503 | 复权因子暂不可用 | 稍后重试或改用不复权 K 线 | | `5006` | 422 | 当前周期缺少生成复权 K 线所需的基础数据 | 更换周期或改用不复权 K 线 | `5004` 的 WebSocket 订阅响应中，`data` 可能包含以下字段： ```json theme={null} { "channel": "ticker", "symbols": ["700.HK"], "failed_symbols": ["AAPL.US", "BTCUSDT"], "retryable_symbols": ["AAPL.US"], "retryable": true } ``` * `symbols`：已经订阅成功的代码，不要重复订阅 * `failed_symbols`：本次未成功的全部代码 * `retryable_symbols`：可以稍后重试的代码子集 * `retryable`：是否存在可重试代码 ## 字符串错误码 | `code` | 场景 | 处理建议 | | ---------------------------- | ---------------------------- | ----------------------------------- | | `"2001"`、`"2002"`、`"5000"` 等 | 部分 HTTP 接口以字符串返回数字错误码 | 使用 `String(code)` 后按相同数字错误码处理 | | `AMBIGUOUS_SYMBOL` | HTTP 请求中的代码存在多个产品类型 | 根据 `data.available_types` 传入 `type` | | `UNAUTHORIZED` | WebSocket 建连前缺少 API Key | 在连接 URL 中传入 `api_key` | | `INVALID_TOKEN` | WebSocket 建连前 API Key 无效或已失效 | 检查或重新生成 API Key | | `PERMISSION_DENIED` | WebSocket 建连前权限不足 | 检查套餐和连接权限 | ## 财务与基本面接口错误 以下五位错误码适用于标准财务与基本面接口；个股新闻接口可能使用不同的错误映射，应以其实际响应为准。 | 错误码 | HTTP | 含义 | 处理建议 | | ------: | ---: | ------------- | ---------------------- | | `40001` | 400 | 请求参数错误 | 根据 `message` 检查参数格式和组合 | | `40101` | 401 | 身份验证失败 | 检查 API Key | | `40404` | 404 | 请求的资源不存在 | 检查代码、对象 ID 或查询条件 | | `40405` | 404 | 查询条件下没有可用业务数据 | 更换代码、日期范围或查询条件 | | `50001` | 500 | 接口内部错误 | 稍后重试；持续出现时联系支持 | ## 错误处理示例 ### JavaScript ```javascript theme={null} const BASE_URL = 'https://api.tickdb.ai'; const API_KEY = 'YOUR_API_KEY'; async function fetchTicker(symbol) { const url = new URL('/v1/market/ticker', BASE_URL); url.searchParams.set('symbols', symbol); const response = await fetch(url, { headers: { 'X-API-Key': API_KEY } }); let body; try { body = await response.json(); } catch { throw new Error(`HTTP ${response.status}：响应不是 JSON`); } if (!response.ok || String(body.code) !== '0') { const code = String(body.code ?? 'UNKNOWN'); const retryAfter = response.headers.get('Retry-After'); const message = code === '3001' && retryAfter ? `请求频率超限，请在 ${retryAfter} 秒后重试` : body.message || `HTTP ${response.status}`; const error = new Error(message); error.status = response.status; error.code = code; error.retryAfter = retryAfter; error.details = body; throw error; } return body.data; } ``` ### Python ```python theme={null} import requests BASE_URL = 'https://api.tickdb.ai' def fetch_ticker(symbol, api_key): response = requests.get( f'{BASE_URL}/v1/market/ticker', params={'symbols': symbol}, headers={'X-API-Key': api_key}, timeout=10, ) try: body = response.json() except requests.exceptions.JSONDecodeError as exc: raise RuntimeError(f'HTTP {response.status_code}：响应不是 JSON') from exc code = str(body.get('code', 'UNKNOWN')) if not response.ok or code != '0': retry_after = response.headers.get('Retry-After') if code == '3001' and retry_after: message = f'请求频率超限，请在 {retry_after} 秒后重试' else: message = body.get('message') or f'HTTP {response.status_code}' raise RuntimeError(f'[{code}] {message}') return body['data'] ``` # TickDB 文档 Source: https://docs.tickdb.ai/zh-Hans/index 统一实时行情数据 API，支持外汇、指数、美股、港股、A 股、期货和加密货币。 欢迎使用 **TickDB 在线文档**。 TickDB 是一个**面向开发者的统一实时行情数据 API**，通过单一连接即可访问多个金融市场的实时与历史行情数据，帮助你专注于业务和策略本身。 *** ## 什么是 TickDB？ TickDB 专为需要**可靠、低延迟、可长期依赖**行情数据的开发者而构建。 通过 **一次接入（one connection）**，即可无缝访问外汇、贵金属、指数、美股、港股、A 股、期货和加密货币等多个市场的行情数据。 TickDB 支持多种数据形式，包括 **tick 级成交数据、盘口深度（Order Book）、K 线（Candlestick）和全量市场行情**，并提供 **财务与基本面数据、财经日历和市场资讯**。可通过 **REST API 与 WebSocket** 接入，适用于量化交易、实时行情系统、基本面研究、交易平台与数据分析等场景。 *** ## 核心特性 * **统一接入**\ 一套 API 覆盖多个市场和资产类别 * **实时数据**\ 基于 WebSocket 的流式推送，适用于实时行情场景 * **全量行情** 覆盖A股、港股和美股；单次 REST 请求即可获取指定市场的完整行情快照，一次 WebSocket 订阅即可持续接收该市场全部标的的实时行情更新 * **多市场支持**\ 外汇、贵金属、指数、美股、港股、A 股、期货、加密货币 * **财务与基本面** 提供公司资料、财务报表、估值、行业、分红和股东持仓等数据 * **财经日历** 按财报、股息、拆股、新股和其他事件分类查询 * **市场资讯** 提供市场状态、交易时段、交易日历和个股新闻 * **开发者友好**\ REST API + WebSocket，接口清晰、文档完整、示例齐全 * **AI 友好**\ 提供实时行情、财务与基本面、财经日历和市场资讯等结构化数据输入，便于 AI 开展公司分析、市场监控、事件跟踪与研究辅助；支持 Skill、MCP、CLI 多种接入方式 *** ## AI 集成 TickDB 提供三档 AI 原生接入方式，从零配置对话到终端自动化全覆盖。 ### Skill **对话即用，零配置** 通过 [ClawHub](https://clawhub.com) 一键安装，任意 LLM 即可调用 TickDB 行情数据。 ```bash theme={null} npx clawhub@latest install tickdb-market-data ``` * 零注册自动试用 * 72 核心品种免费 * 任意 LLM 通用 ### MCP **永久集成，一次配置** 通过 Hosted MCP Server 接入，兼容 Claude Code、Cursor、Kiro、Zed 等所有 MCP 客户端。 配置示例（以 Claude 为例，路径：`~/.claude/settings.json`）： ```json theme={null} { "mcpServers": { "tickdb": { "type": "http", "url": "https://mcp.tickdb.ai/", "headers": { "X-TickDB-Key": "" } } } } ``` * Hosted mcp.tickdb.ai，无需自部署 * HTTPS + Header 鉴权 * 兼容所有 MCP 协议客户端 * 提供 13 个工具，与 REST API 端点一一对应 ### CLI **终端 & AI Agent 就绪** 全局安装后即可在终端直接查询行情，也适合 Agent 通过 bash-tool 调用。 ```bash theme={null} npm install -g tickdb tickdb config set-key YOUR_API_KEY tickdb ticker BTCUSDT,XAUUSD,AAPL.US ``` * JSON / 表格双输出 * 16 个原生命令 * Bash-tool 友好，适合 Agent 调用 ### llms.txt **为 AI 提供文档上下文** 如需让 AI 助手了解 TickDB 文档，可向其提供以下地址： ```text theme={null} https://docs.tickdb.ai/llms.txt ``` 如需包含全部页面正文的完整版本，请使用： ```text theme={null} https://docs.tickdb.ai/llms-full.txt ``` 详细信息请访问 [TickDB AI 接入](https://tickdb.ai/ai-tools)。 *** ## 典型使用场景 * **量化交易**\ 作为策略与算法系统的实时行情数据源 * **行情看板**\ 实时价格展示、资产与投资组合监控 * **交易应用**\ 构建类似 TradingView 的行情界面与图表系统 * **数据分析与回测**\ 历史行情分析、策略研究与回测 * **基本面研究** 结合财务报表、估值、行业和股东持仓进行公司分析 * **市场监控** 利用全量行情、新闻和财经日历跟踪市场变化与重要事件 * **金融服务集成**\ 集成到现有交易平台或金融基础设施中 *** ## 入门指南 * **快速开始** - 几分钟内开始使用 * **更新日志** - 版本更新记录 ## REST API ### 通用行情接口 * **可用交易品种** - 查询支持的交易品种 * **行情快照** - 实时行情快照 * **K 线查询** - 按周期和时间范围查询 K 线数据 * **实时 K 线** - 当前周期正在形成的 K 线数据 * **盘口深度** - 实时买卖盘口数据 * **逐笔成交** - 逐笔成交记录 ### 股票市场接口 #### 全量行情 A股、港股和美股全市场行情快照 #### 个股行情与指标 股票信息、当日分时、综合指标和资金流向 #### 公司概况 公司资料、高管董事和营收构成 #### 财务报表 近期、年度和 TTM 财务数据及字段字典 #### 估值与行业 最新估值、历史估值、同行对比和行业数据 #### 分红与公司行动 分红、股息 TTM、股票回购和公司行动 #### 股东与机构持仓 股东结构、股东持仓和持股基金 #### 财经日历 财报日历、股息日历、拆股日历、新股日历和其他日历 #### 市场资讯 市场状态、交易时段、交易日历和个股新闻 ## WebSocket 文档 ### 最佳实践 WebSocket 连接、压缩、心跳与断线重连 ### Playground 直接在七个频道页面查看订阅方式与消息格式，包括 A 股、港股、美股全量行情及 ticker、depth、trade、ping。 ## 参考 * **数据规范** - 交易品种命名与格式 * **错误码说明** - 错误码与处理方式 *** **文档版本**: v1.0.3 # 套餐与定价 Source: https://docs.tickdb.ai/zh-Hans/pricing TickDB 提供多种套餐方案，满足从个人开发者到企业级的不同需求。 TickDB 提供灵活的套餐方案，支持月付、季付（-10%）、半年付（-15%）和年付（-20%）。 所有套餐均支持 Skill、MCP 和 CLI 等 AI 接入方式，无需额外付费。 前往官网查看完整定价 → *** ## 通用套餐 | | 免费版 | 基础版 | 专业版 | 企业版 | | ----------------- | -------- | --------- | ---------- | --------------- | | **价格** | 免费 7 天试用 | \$99/月 | \$299/月 | \$899/月 | | **品种范围** | 精选品种 | 全部品种 | 全部品种 | 全部品种 | | **全量查询与订阅** | - | - | - | A 股、港股和美股 | | **订阅额度** | 5 个同时订阅 | 50 个全市场订阅 | 300 个全市场订阅 | 另有 5,000 个全市场订阅 | | **实时报价** | ✅ | ✅ | ✅ | ✅ | | **实时 K 线** | ✅ | ✅ | ✅ | ✅ | | **实时盘口** | - | ✅ | ✅ | ✅ | | **实时成交** | - | ✅ | ✅ | ✅ | | **历史数据** | - | 1 年 | 3 年 | 10 年 | | **WebSocket 连接数** | 1 | 1 | 3 | 10 | | **API 调用频率** | 30 次/分钟 | 60 次/分钟 | 600 次/分钟 | 1,800 次/分钟 | | **财务数据** | - | 基础财务数据 | 专业财务数据 | 专业财务数据 | | **新闻资讯** | - | - | ✅ | ✅ | | **技术支持** | Email | Email | Telegram | Telegram | ## 全量套餐 | | 港股全量 | A 股全量 | 美股全量 | | ----------------- | ---------- | ---------- | ---------- | | **价格** | \$499/月 | \$599/月 | \$699/月 | | **品种范围** | 全部品种 | 全部品种 | 全部品种 | | **全量查询与订阅** | 全部港股 | 全部 A 股 | 全部美股 | | **额外全市场订阅** | 1,000 个 | 1,500 个 | 3,000 个 | | **实时报价** | ✅ | ✅ | ✅ | | **实时 K 线** | ✅ | ✅ | ✅ | | **实时盘口** | ✅ | ✅ | ✅ | | **实时成交** | ✅ | ✅ | ✅ | | **历史数据** | 5 年 | 5 年 | 5 年 | | **WebSocket 连接数** | 5 | 5 | 5 | | **API 调用频率** | 1,200 次/分钟 | 1,200 次/分钟 | 1,500 次/分钟 | | **财务数据** | 专业财务数据 | 专业财务数据 | 专业财务数据 | | **新闻资讯** | ✅ | ✅ | ✅ | | **技术支持** | Telegram | Telegram | Telegram | *** ## 如何选择 * **免费版** — 适合快速体验和功能评估，无需信用卡 * **基础版** — 适合个人开发者和小型项目 * **专业版** — 适合需要专业财务数据、新闻资讯和更高调用额度的量化团队 * **港股全量 / A 股全量 / 美股全量** — 适合需要专业版能力，并进一步聚焦某一股票市场的用户；在专业财务与资讯数据基础上，可一次获取该市场的完整行情快照，并通过一次订阅持续接收全部标的的实时更新 * **企业版** — 适合需要同时覆盖多个股票市场全部标的的用户，提供 A 股、港股和美股全量查询与订阅，以及更高的连接数和调用额度 *** ## 开始使用 1. 访问 [tickdb.ai](https://tickdb.ai) 注册账号 2. 选择适合的套餐（可从免费版开始） 3. 在控制台生成 API Key 4. 参考[快速开始](/zh-Hans/quick-start)接入 API 如需定制方案或有任何疑问，请联系 [support@tickdb.ai](mailto:support@tickdb.ai) 或通过 [Telegram](https://t.me/TickDB_Support) 咨询。 # 快速开始 Source: https://docs.tickdb.ai/zh-Hans/quick-start 在几分钟内开始使用 TickDB。 本指南帮助您在 10 分钟内开始使用 TickDB。 ## 步骤 1：创建 API 密钥 在 [https://tickdb.ai](https://tickdb.ai) 注册并从控制台创建 API 密钥。 ## 步骤 2：身份验证 TickDB 使用 API 密钥身份验证。所有 REST API 请求必须包含以下请求头： ```http theme={null} X-API-Key: YOUR_API_KEY ``` ## 步骤 3：基础 URL ``` https://api.tickdb.ai ``` ## 步骤 4：第一个请求 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/market/ticker?symbols=700.HK,AAPL.US" ``` ### 响应示例 ```json theme={null} { "code": 0, "message": "success", "data": [ { "symbol": "700.HK", "last_price": "543", "volume_24h": "11205874", "high_24h": "557", "low_24h": "543", "price_change_24h": "-9", "price_change_percent_24h": "-1.63", "timestamp": 1773292807000 }, { "symbol": "AAPL.US", "last_price": "260.81", "volume_24h": "26218927", "high_24h": "262.13", "low_24h": "259.55", "price_change_24h": "-0.02", "price_change_percent_24h": "-0.01", "timestamp": 1773259201000 } ] } ``` # 更新日志 Source: https://docs.tickdb.ai/zh-Hans/release-notes TickDB API 文档版本更新记录 ## v1.0.3 (2026-09-21) ### 新增功能 * 新增财务与基本面接口文档，覆盖公司概况、主营构成、财务报表、估值与行业、分红与公司行动、股东与机构持仓、市场资讯与日历。 * 新增 A 股、港股和美股全量行情：REST API 单次请求可获取指定市场的完整行情快照，WebSocket 单次订阅可持续接收该市场全部标的的实时行情更新。 * 新增 K 线复权因子接口及 JavaScript 计算示例，适用于基于不复权 K 线动态生成前复权或后复权数据。 * 增加对香港股票期货和金融期货的支持。 *** ## v1.0.2 (2026-07-16) ### 新增功能 * 产品查询、REST 行情接口和 WebSocket 频道新增中国期货支持，产品类型使用 `type=futures`。 * 新增期货持仓相关字段：K 线 `open_interest`，成交数据 `open_interest_change` 和 `position_effect`。 *** ## v1.0.1 (2026-03-13) ### 新增功能 * **新增股票市场专属接口** * 当日分时数据接口 * 股票详细信息接口 * 交易时段查询接口 * 交易日历查询接口 * 市场指标数据接口 * 资金流向数据接口 ### 重要改进 * **WebSocket 文档重构** * 新增 ping/pong 心跳机制说明 * 更新 ticker 频道消息格式（按市场类型区分字段） * 修正 trade 频道响应格式（包含 trades 数组） * depth 频道新增 A 股支持 * **文档内容优化** * 重新组织 REST API 导航结构 * 完善所有接口的请求参数和返回字段说明 * 更新支持市场标注和示例 * 统一术语翻译 * 优化入门指南和数据规范 *** ## v1.0.0 (2026-01-15) ### 首次发布 提供核心 REST API 和 WebSocket 实时订阅，覆盖外汇、贵金属、指数、美股、港股、A 股、加密货币市场。 * **REST API 接口** * 交易品种查询 * 行情快照 * K 线查询 * 实时 K 线 * 订单簿 * 最近成交 * K 线周期查询 * **WebSocket 频道** * ticker 频道 * depth 频道 * trade 频道 # 综合指标 Source: https://docs.tickdb.ai/zh-Hans/rest/api_calc_index openapi.yaml GET /v1/market/calc-index 获取股票的价格涨跌、成交、资金流向及估值等综合指标。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 指标数据基于实时行情和历史数据计算 ## 支持的市场 | 市场 | 示例 | | -- | ------------------------- | | 美股 | AAPL.US, TSLA.US, MSFT.US | | 港股 | 700.HK, 9988.HK, 3690.HK | | A股 | 600519.SH, 000001.SZ | ## 请求参数 | 参数名 | 是否必须 | 描述 | | ------- | ---- | ---------------------------------------------------------------------------------------------- | | symbols | 是 | 股票代码，多个用逗号分隔，最多50个 | | type | 否 | 产品类型，可选。代码无歧义时无需传递；若返回 `AMBIGUOUS_SYMBOL` 错误，按提示传入对应值即可。可选值：`stock`、`indices`、`crypto`、`forex` | ## 返回字段说明 | 字段名 | 描述 | | --------------------------- | --------- | | 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 | 五分钟涨幅 | # 资金流向 Source: https://docs.tickdb.ai/zh-Hans/rest/api_capital_flow openapi.yaml GET /v1/market/capital-flow 获取股票的资金流向数据，包括主力资金、大单、中单、小单的流入流出情况。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 资金流向数据基于成交量和价格变化计算 * 数据更新频率取决于市场交易活跃度 ## 支持的市场 | 市场 | 示例 | | -- | ------------------------- | | 美股 | AAPL.US, TSLA.US, MSFT.US | | 港股 | 700.HK, 9988.HK, 3690.HK | | A股 | 600519.SH, 000001.SZ | ## 请求参数 | 参数名 | 是否必须 | 描述 | | ------ | ---- | ---------------------------------------------------------------------------------------------- | | symbol | 是 | 股票代码 | | type | 否 | 产品类型，可选。代码无歧义时无需传递；若返回 `AMBIGUOUS_SYMBOL` 错误，按提示传入对应值即可。可选值：`stock`、`indices`、`crypto`、`forex` | ## 返回字段说明 | 字段名 | 描述 | | --------------- | -------------------- | | symbol | 交易产品 | | timestamp | 数据更新时间，Unix 时间戳，单位为秒 | | intraday\_flow | 资金流向数据 | | └─ timestamp | 分钟开始时间，Unix 时间戳，单位为秒 | | └─ inflow | 净流入 | | distribution | 资金分布 | | └─ timestamp | 数据更新时间，Unix 时间戳，单位为秒 | | └─ capital\_in | 流入资金 | |     └─ large | 大单 | |     └─ medium | 中单 | |     └─ small | 小单 | | └─ capital\_out | 流出资金 | |     └─ large | 大单 | |     └─ medium | 中单 | |     └─ small | 小单 | # 盘口深度 Source: https://docs.tickdb.ai/zh-Hans/rest/api_depth openapi.yaml GET /v1/market/depth 获取交易品种的实时买卖盘口数据。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 买盘（bids）按价格降序排列 * 卖盘（asks）按价格升序排列 * 返回档位数量由相应市场实际支持的深度决定 * 时间戳单位为毫秒（UTC） ## 支持的市场 | 市场 | 示例 | 每侧盘口档位 | | ---- | ------------------------------- | ------- | | 美股 | AAPL.US、TSLA.US、MSFT.US | 1档 | | 港股 | 700.HK、9988.HK、3690.HK | 10档 | | A股 | 600519.SH、000001.SZ、920186.BJ | 5档 | | 中国期货 | BU2609、RB8888、AP8888 | 1档 | | 香港期货 | HSI8888、MHI8888、HTI8888 | 10档 | | 加密货币 | BTCUSDT、ETHUSDT、ADAUSDT、OKBUSDT | 最高1000档 | 表中为每侧盘口最高支持档位。不同产品支持的深度可能不同；休市、流动性不足或部分档位无报价时，实际返回档位可能少于表中数量。 ## 请求参数 | 参数名 | 是否必须 | 描述 | | ------ | ---- | -------------------------------------------------------------------------------------------------------- | | symbol | 是 | 交易产品代码 | | type | 否 | 产品类型，可选。代码无歧义时无需传递；若返回 `AMBIGUOUS_SYMBOL` 错误，按提示传入对应值即可。可选值：`stock`、`indices`、`crypto`、`forex`、`futures` | ## 返回字段说明 | 字段 | 说明 | | --------- | -------------------- | | symbol | 交易产品 | | type | 产品类型 | | timestamp | 数据时间戳（毫秒，UTC） | | bids | 买盘数组，每个元素为 \[价格, 数量] | | asks | 卖盘数组，每个元素为 \[价格, 数量] | # 复权因子 Source: https://docs.tickdb.ai/zh-Hans/rest/api_ex_factors openapi.yaml GET /v1/market/kline/ex-factors 获取 A 股、港股和美股的前复权、后复权因子。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 本接口用于自行计算或核对股票历史价格的复权结果；一般查询可直接使用 K 线查询或实时 K 线接口的 `adjust` 参数 * 每个除权除息事件分别返回一条 `forward`（前复权）和一条 `backward`（后复权）因子 * 复权价格计算公式：`复权价格 = 原始价格 × factor_a + factor_b` * 前复权按时间顺序应用 K 线时间之后的因子；后复权按时间倒序应用 K 线时间及之前的因子 * 时间戳单位为毫秒 ## 代码示例 本接口适合已经在本地保存不复权 K 线的场景。存储时只保留一份原始价格数据，查询、回测或绘制图表时再获取复权因子，动态生成前复权或后复权 K 线。这样无需同时保存不复权、前复权和后复权三套数据；发生新的除权除息事件后，也可以使用最新因子重新计算历史价格。 下面的 JavaScript 示例先获取未复权日 K，再查询同一股票的复权因子，并分别动态计算每根 K 线的前复权和后复权收盘价。实际使用时，可以将示例中请求未复权 K 线的部分替换为读取本地数据库。 ```javascript theme={null} const BASE_URL = "https://api.tickdb.ai"; const SYMBOL = "600519.SH"; const API_KEY = process.env.TICKDB_API_KEY; async function get(path, params) { const url = new URL(path, BASE_URL); Object.entries(params).forEach(([key, value]) => { url.searchParams.set(key, String(value)); }); const response = await fetch(url, { headers: { "X-API-Key": API_KEY }, }); if (!response.ok) { throw new Error(`HTTP ${response.status}`); } const result = await response.json(); if (result.code !== 0) { throw new Error(result.message); } return result.data; } function adjustPrice(rawPrice, klineTime, mode, factors) { // 前复权：选择 K 线时间之后生效的 forward 因子。 // 后复权：选择 K 线时间及之前生效的 backward 因子。 const selected = factors.filter( (factor) => factor.adjust === mode && (mode === "forward" ? factor.timestamp > klineTime : factor.timestamp <= klineTime), ); // 前复权从早到晚应用，后复权从晚到早应用。 selected.sort((a, b) => mode === "forward" ? a.timestamp - b.timestamp : b.timestamp - a.timestamp, ); return selected.reduce((price, factor) => { // 每条因子必须按顺序迭代计算： // 复权价格 = 当前价格 × factor_a + factor_b return price * Number(factor.factor_a) + Number(factor.factor_b); }, Number(rawPrice)); } async function main() { // 获取未复权 K 线 const klineData = await get("/v1/market/kline", { symbol: SYMBOL, type: "stock", interval: "1d", adjust: "none", limit: 100, }); const klines = klineData.klines; // 返回结构为 data.data.{symbol}[] const factorData = await get("/v1/market/kline/ex-factors", { symbols: SYMBOL, type: "stock", }); const factors = factorData.data[SYMBOL]; for (const kline of klines) { console.log({ time: kline.time, raw: kline.close, forward: adjustPrice(kline.close, kline.time, "forward", factors), backward: adjustPrice(kline.close, kline.time, "backward", factors), }); } } main().catch(console.error); ``` * **前复权 `forward`**：以近期价格为基准。对一根过往 K 线，选取其时间之后发生的前复权因子，并按时间从早到晚依次应用 * **后复权 `backward`**：以早期价格为基准。对一根 K 线，选取其时间及之前发生的后复权因子，并按时间从晚到早依次应用 * 每应用一条因子，都按 `复权价格 = 当前价格 × factor_a + factor_b` 重新计算一次 * 如果只需要直接取得复权 K 线，无需自行计算，在 K 线查询接口中传入 `adjust=forward` 或 `adjust=backward` 即可 ## 支持的市场 | 市场 | 示例 | | -- | -------------------- | | A股 | 600519.SH, 000001.SZ | | 港股 | 700.HK, 9988.HK | | 美股 | AAPL.US, TSLA.US | ## 请求参数 | 参数名 | 是否必须 | 描述 | | ----------- | ---- | --------------------------- | | symbols | 是 | 股票代码，多个用逗号分隔 | | type | 否 | 产品类型，仅支持 `stock`；代码无歧义时无需传递 | | start\_time | 否 | 开始时间戳，单位为毫秒，包含该时刻 | | end\_time | 否 | 结束时间戳，单位为毫秒，包含该时刻 | ## 返回字段说明 | 字段名 | 描述 | | -------------- | ----------------------------------- | | data | 按股票代码分组的复权因子对象 | | └─ `{symbol}` | 对应股票代码的复权因子数组 | |   └─ timestamp | 因子生效时间戳，单位为毫秒 | |   └─ adjust | 复权方向：`forward` 为前复权，`backward` 为后复权 | |   └─ factor\_a | 复权计算中的乘法因子 | |   └─ factor\_b | 复权计算中的加法因子 | # 当日分时 Source: https://docs.tickdb.ai/zh-Hans/rest/api_intraday openapi.yaml GET /v1/market/intraday 获取股票当日的分时数据，包括每分钟的价格、成交量、成交额等信息。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ✅ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 数据为当日开盘至当前时间的分时数据 * 非交易时段以实际可用数据为准，可能返回已有分时数据，也可能返回空数组。 ## 支持的市场 | 市场 | 示例 | | -- | ------------------------- | | 美股 | AAPL.US, TSLA.US, MSFT.US | | 港股 | 700.HK, 9988.HK, 3690.HK | | A股 | 600519.SH, 000001.SZ | ## 请求参数 | 参数名 | 是否必须 | 描述 | | ------- | ---- | ---------------------------------------------------------------------------------------------- | | symbols | 是 | 股票代码，多个用逗号分隔，最多50个 | | type | 否 | 产品类型，可选。代码无歧义时无需传递；若返回 `AMBIGUOUS_SYMBOL` 错误，按提示传入对应值即可。可选值：`stock`、`indices`、`crypto`、`forex` | ## 返回字段说明 | 字段名 | 描述 | | ------------- | ------------------------ | | symbol | 交易产品 | | type | 产品类型，当前为 `stock` | | lines | 分时数据 | | └─ timestamp | 当前分钟的开始时间，Unix 时间戳，单位为毫秒 | | └─ price | 当前分钟的收盘价格 | | └─ volume | 成交量 | | └─ turnover | 成交额 | | └─ avg\_price | 均价 | # APIKey管理 Source: https://docs.tickdb.ai/zh-Hans/rest/api_key_status openapi.yaml GET /v1/apikeys/subscriptions 无需登录官网，即可查询 API Key 的到期情况，便于定时检查和设置提醒。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ✅ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | 使用自己的 API Key 查询账户名下各 Key 的到期时间和剩余秒数，无需登录官网。 ## 请求参数 该接口不需要查询参数。 ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/apikeys/subscriptions" ``` ## 返回字段说明 以下列出 `data` 中的字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | --------------------- | ------------------------------------------------------------------- | | server\_time | 本次查询的服务器时间，带时区的日期时间字符串。 | | total | 返回的 API Key 数量。 | | api\_keys | 账户名下的 API Key 列表。 | | └─ key\_prefix | API Key 前缀，用于辨认 Key；不是完整密钥。 | | └─ name | API Key 名称。 | | └─ plan | 该 Key 对应的套餐标识。 | | └─ status | Key 状态：`active`（有效）、`expired`（已过期）、`suspended`（已暂停）、`revoked`（已撤销）。 | | └─ expires\_at | 到期时间；未设置到期时间时为 `null`。 | | └─ remaining\_seconds | 距离到期的剩余秒数；已到期时为 `0`，未设置到期时间时为 `null`。 | | └─ created\_at | API Key 创建时间。 | # K 线查询 Source: https://docs.tickdb.ai/zh-Hans/rest/api_kline openapi.yaml GET /v1/market/kline 按周期和时间范围查询 K 线数据。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ✅ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 免费版可查询 K 线，但不支持使用 `start_time` 或 `end_time` 指定时间范围。 * 查询结果的最后一根 K 线可能仍在形成，价格和成交量可能继续变化。 * 适用于技术指标计算。股票数据归档或策略回测时，建议记录查询时间与复权方式；如保存不复权 K 线，可参考[复权因子](./api_ex_factors)动态生成复权价格。复权历史价格可能随公司行动或数据更新调整。 * 若需一次查询多个代码各自的最新 K 线，请使用[实时 K 线](./api_kline_latest)。 * A股、港股和美股统一支持不复权、前复权和后复权 ## 支持的市场 | 市场 | 示例 | | ---- | ------------------------------- | | 外汇 | EURUSD, GBPUSD, USDJPY | | 贵金属 | XAUUSD, XAGUSD | | 指数 | SPX, NDX, DJI | | 美股 | AAPL.US, TSLA.US, MSFT.US | | 港股 | 700.HK, 9988.HK, 3690.HK | | A股 | 600519.SH, 000001.SZ, 920186.BJ | | 中国期货 | BU2609, IC2606, AP8888 | | 香港期货 | HSI8888, MHI8888, HTI8888 | | 加密货币 | BTCUSDT, ETHUSDT, ADAUSDT | ## K 线周期 | `interval` | 周期说明 | | ---------- | ----- | | `1m` | 1 分钟 | | `3m` | 3 分钟 | | `5m` | 5 分钟 | | `15m` | 15 分钟 | | `30m` | 30 分钟 | | `1h` | 1 小时 | | `2h` | 2 小时 | | `4h` | 4 小时 | | `1d` | 1 天 | | `1w` | 1 周 | | `1M` | 1 个月 | `1m` 中的小写 `m` 表示分钟，`1M` 中的大写 `M` 表示月。 ## 请求参数 | 参数名 | 是否必须 | 描述 | | ----------- | ---- | -------------------------------------------------------------------------------------------------------- | | symbol | 是 | 交易产品代码 | | interval | 是 | K线周期，可选值：1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 1d, 1w, 1M | | limit | 否 | 返回记录数，默认 100；大于 1000 时按 1000 处理，非正数使用默认值 100 | | start\_time | 否 | 开始时间戳（毫秒） | | end\_time | 否 | 结束时间戳（毫秒） | | type | 否 | 产品类型，可选。代码无歧义时无需传递；若返回 `AMBIGUOUS_SYMBOL` 错误，按提示传入对应值即可。可选值：`stock`、`indices`、`crypto`、`forex`、`futures` | | adjust | 否 | 复权方式，适用于 A 股、港股和美股。可选值：`none` 不复权、`forward` 前复权、`backward` 后复权；不传时默认不复权（`none`） | ## 返回字段说明 | 字段 | 说明 | | ----------------- | --------------------------------------- | | symbol | 交易产品 | | type | 产品类型 | | interval | K线周期 | | adjust | 实际使用的复权方式：`none`、`forward` 或 `backward` | | klines | K线数据数组 | | └─ time | K线时间戳（毫秒） | | └─ open | 开盘价 | | └─ high | 最高价 | | └─ low | 最低价 | | └─ close | 收盘价 | | └─ volume | 成交量 | | └─ quote\_volume | 成交额，期货通常不返回 | | └─ open\_interest | 持仓量，仅期货返回 | # 实时 K 线 Source: https://docs.tickdb.ai/zh-Hans/rest/api_kline_latest openapi.yaml GET /v1/market/kline/latest 获取当前时间周期内正在形成并实时更新的 K 线数据。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ✅ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 本接口返回当前周期内正在形成的K线数据，数据会随着成交持续更新 * 适用于实时行情图表展示、当前价格监控、分时动态更新 * 不建议用于历史回测、技术指标统计、固定数据存储 * 若需按时间范围查询 K 线，请使用[K 线查询](./api_kline)。 * A股、港股和美股统一支持不复权、前复权和后复权 ## 支持的市场 | 市场 | 示例 | | ---- | ------------------------------- | | 外汇 | EURUSD, GBPUSD, USDJPY | | 贵金属 | XAUUSD, XAGUSD | | 指数 | SPX, NDX, DJI | | 美股 | AAPL.US, TSLA.US, MSFT.US | | 港股 | 700.HK, 9988.HK, 3690.HK | | A股 | 600519.SH, 000001.SZ, 920186.BJ | | 中国期货 | BU2609, IC2606, AP8888 | | 香港期货 | HSI8888, MHI8888, HTI8888 | | 加密货币 | BTCUSDT, ETHUSDT, ADAUSDT | ## K 线周期 | `interval` | 周期说明 | | ---------- | ----- | | `1m` | 1 分钟 | | `3m` | 3 分钟 | | `5m` | 5 分钟 | | `15m` | 15 分钟 | | `30m` | 30 分钟 | | `1h` | 1 小时 | | `2h` | 2 小时 | | `4h` | 4 小时 | | `1d` | 1 天 | | `1w` | 1 周 | | `1M` | 1 个月 | `1m` 中的小写 `m` 表示分钟，`1M` 中的大写 `M` 表示月。 ## 请求参数 | 参数名 | 是否必须 | 描述 | | -------- | ---- | -------------------------------------------------------------------------------------------------------- | | symbols | 是 | 交易产品代码，多个用逗号分隔，最多50个，例如：AAPL.US,00700.HK | | interval | 是 | K线周期，可选值：1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 1d, 1w, 1M | | type | 否 | 产品类型，可选。代码无歧义时无需传递；若返回 `AMBIGUOUS_SYMBOL` 错误，按提示传入对应值即可。可选值：`stock`、`indices`、`crypto`、`forex`、`futures` | | adjust | 否 | 复权方式，适用于 A 股、港股和美股。可选值：`none` 不复权、`forward` 前复权、`backward` 后复权；不传时默认不复权（`none`） | ## 返回字段说明 | 字段 | 说明 | | ----------------- | --------------------------------------- | | symbol | 交易产品 | | type | 产品类型 | | interval | K线周期 | | adjust | 实际使用的复权方式：`none`、`forward` 或 `backward` | | klines | K线数据数组 | | └─ time | K线时间戳（毫秒） | | └─ open | 开盘价 | | └─ high | 最高价 | | └─ low | 最低价 | | └─ close | 收盘价 | | └─ volume | 成交量 | | └─ quote\_volume | 成交额，期货通常不返回 | | └─ open\_interest | 持仓量，仅期货返回 | # 股票信息 Source: https://docs.tickdb.ai/zh-Hans/rest/api_stock_info openapi.yaml GET /v1/market/stock-info 获取股票名称、交易所、币种、股本和每股指标等基础信息。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ✅ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 单次最多查询 500 个股票代码。 * 返回字段会因市场和个股的数据情况而异；条件字段没有可用数据时不会返回。 ## 支持的市场 | 市场 | 示例 | | -- | ------------------------------- | | 美股 | AAPL.US, TSLA.US, MSFT.US | | 港股 | 700.HK, 9988.HK, 3690.HK | | A股 | 600519.SH, 000001.SZ, 300750.SZ | ## 请求参数 | 参数名 | 是否必须 | 描述 | | ------- | ---- | ---------------------------------------------------------------------------------------------- | | symbols | 是 | 股票代码，多个用逗号分隔，最多 500 个 | | type | 否 | 产品类型，可选。代码无歧义时无需传递；若返回 `AMBIGUOUS_SYMBOL` 错误，按提示传入对应值即可。可选值：`stock`、`indices`、`crypto`、`forex` | ## 返回字段说明 | 字段 | 说明 | | ------------------- | ----------------------------------------- | | symbol | 交易产品 | | name\_cn | 中文简体标的名称 | | name\_en | 英文标的名称；港股、美股返回 | | name\_hk | 中文繁体标的名称；港股、美股返回 | | exchange | 标的所属交易所 | | currency | 交易币种（CNY/USD/HKD） | | lot\_size | 每手股数 | | total\_shares | 总股本；数据可用时返回 | | circulating\_shares | 流通股本；数据可用时返回 | | hk\_shares | H股股本；港股及同时发行H股的A股公司返回 | | eps | 每股收益；数据可用时返回 | | eps\_ttm | 最近十二个月每股收益；港股、美股数据可用时返回 | | bps | 每股净资产；数据可用时返回 | | dividend\_yield | 股息率；港股、美股数据可用时返回 | | stock\_derivatives | 支持的衍生品类型数组；`1` 表示期权，`2` 表示轮证，港股、美股数据可用时返回 | | board | A股所属板块或证券分类代码；A股返回 | # 产品查询 Source: https://docs.tickdb.ai/zh-Hans/rest/api_symbols openapi.yaml GET /v1/symbols/available 查询 TickDB 支持的产品，覆盖外汇、指数、美股、港股、A股、中国期货、香港期货、加密货币等市场，产品列表持续增加中。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ✅ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 市场代码不区分大小写 * 除 API 查询外，您也可以登录 [TickDB 官网](https://tickdb.ai) 用户中心，在产品管理页面直接浏览和搜索所有支持的产品 TickDB 用户中心 - 产品查询 ## 市场与产品类型 通过 `market` 和 `type` 参数可以灵活过滤产品，两者可单独或组合使用。 | market | type | 说明 | 产品量级 | | ------ | ------- | --------- | ------- | | GLOBAL | forex | 外汇货币对、贵金属 | 1,200+ | | GLOBAL | indices | 市场指数 | 13,300+ | | GLOBAL | crypto | 加密货币交易对 | 800+ | | US | stock | 美国股票 | 14,300+ | | HK | stock | 香港股票 | 3,300+ | | CN | stock | A股 | 7,500+ | | CN | futures | 中国期货 | 1,000+ | | HK | futures | 香港期货 | 200+ | * `market` 按具体市场过滤，如 `market=CN` 返回A股和中国期货 * `type` 按产品大类过滤，如 `type=stock` 返回 US + HK + CN 全部股票 * 组合使用：`market=HK&type=stock` 仅返回港股 * 组合使用：`market=HK&type=futures` 仅返回香港期货 ## 请求参数 | 参数名 | 是否必须 | 描述 | | ------ | ---- | ------------------------------------------------- | | type | 否 | 产品类型过滤，可选值：stock, crypto, forex, indices, futures | | market | 否 | 市场过滤，可选值：GLOBAL, US, HK, CN | | limit | 否 | 每页返回数量，默认100，最大1000 | | offset | 否 | 分页偏移量，默认0 | ## 返回字段说明 | 字段名 | 描述 | | ------------------ | ---------------------------------------- | | products | 产品数组 | | └─ symbol | 产品代码 | | └─ name | 产品名称 | | └─ market | 市场代码 | | └─ type | 产品类型（stock/crypto/forex/indices/futures） | | └─ currency | 交易币种（CNY/USD/HKD/USDT） | | └─ is\_active | 是否活跃 | | └─ updated\_at | 更新时间，RFC 3339 日期时间字符串，包含时区信息 | | summary | 汇总信息 | | └─ total\_products | 产品总数 | | └─ by\_market | 按市场统计数量 | | └─ by\_type | 按类型统计数量 | | └─ last\_updated | 最后更新时间，RFC 3339 日期时间字符串，包含时区信息 | | pagination | 分页信息 | | └─ limit | 每页数量 | | └─ offset | 偏移量 | | └─ total | 总数 | | └─ count | 当前页返回数量 | # 行情快照 Source: https://docs.tickdb.ai/zh-Hans/rest/api_ticker openapi.yaml GET /v1/market/ticker 获取一个或多个交易品种的实时市场行情数据。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ✅ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 最多可同时查询 50 个交易品种 * `timestamp` 为 Unix 时间戳，单位为毫秒 * 返回顺序与请求中有效交易产品代码的顺序一致 * 除 `symbol`、`last_price`、`timestamp` 外，其余行情字段均根据产品类型、交易时段和数据可用性按条件返回 ## 支持的市场 | 市场 | 示例 | | ---- | ------------------------------- | | 外汇 | EURUSD, GBPUSD, USDJPY | | 贵金属 | XAUUSD, XAGUSD | | 指数 | SPX, NDX, DJI | | 美股 | AAPL.US, TSLA.US, MSFT.US | | 港股 | 700.HK, 9988.HK, 3690.HK | | A股 | 600519.SH, 000001.SZ, 920186.BJ | | 中国期货 | BU2609, IC2606, AP8888 | | 香港期货 | HSI8888, MHI8888, HTI8888 | | 加密货币 | BTCUSDT, ETHUSDT, ADAUSDT | ## 请求参数 | 参数名 | 是否必须 | 描述 | | ------- | ---- | -------------------------------------------------------------------------------------------------------- | | symbols | 是 | 交易产品代码，多个用逗号分隔，最多50个 | | type | 否 | 产品类型，可选。代码无歧义时无需传递；若返回 `AMBIGUOUS_SYMBOL` 错误，按提示传入对应值即可。可选值：`stock`、`indices`、`crypto`、`forex`、`futures` | ## 返回字段说明 | 字段 | 说明 | | --------------------------- | ------------------------------------------------------------------------------------------- | | symbol | 交易产品 | | name | 产品名称；名称信息可用时返回 | | type | 产品类型；产品类型成功识别时返回 | | category | A股产品细分类别，例如 `sh_stock`、`sz_stock`、`bj_stock`、`etf`、`cn_bond`、`cn_index`；仅查询A股市场产品且分类信息可用时返回 | | last\_price | 最新成交价 | | open | 开盘价；行情统计可用时返回。传统市场通常为当日或当前交易时段开盘价，加密货币按对应行情统计窗口返回 | | prev\_close | 昨收或参考价；行情统计可用时返回。传统市场通常为上一交易日或上一交易时段收盘价，加密货币按对应行情统计窗口返回 | | bid\_price | 最优买价；盘口报价可用时返回 | | ask\_price | 最优卖价；盘口报价可用时返回 | | volume\_24h | 累计成交量；数据可用时返回。加密货币通常为滚动24小时成交量，传统市场通常为当日或当前交易时段成交量 | | quote\_volume\_24h | 与 `volume_24h` 相同统计窗口的成交额；成交额数据可用时返回 | | high\_24h | 最高价；数据可用时返回，统计窗口与 `volume_24h` 一致 | | low\_24h | 最低价；数据可用时返回，统计窗口与 `volume_24h` 一致 | | price\_change\_24h | 价格变化；数据可用时返回，统计窗口与 `volume_24h` 一致 | | price\_change\_percent\_24h | 价格变化百分比；数据可用时返回，非空数值保留两位小数 | | timestamp | Unix 时间戳，单位为毫秒 | | pre\_market\_quote | 盘前行情对象；仅支持扩展交易时段的产品（如美股）且盘前行情数据可用时返回 | | ├─ last\_done | 盘前最新成交价 | | ├─ timestamp | 盘前行情时间戳（毫秒，UTC） | | ├─ volume | 盘前成交量 | | ├─ quote\_volume | 盘前成交额；数据可用时返回 | | ├─ high | 盘前最高价 | | ├─ low | 盘前最低价 | | └─ prev\_close | 盘前参考昨收价 | | post\_market\_quote | 盘后行情对象；仅支持扩展交易时段的产品（如美股）且盘后行情数据可用时返回 | | ├─ last\_done | 盘后最新成交价 | | ├─ timestamp | 盘后行情时间戳（毫秒，UTC） | | ├─ volume | 盘后成交量 | | ├─ quote\_volume | 盘后成交额；数据可用时返回 | | ├─ high | 盘后最高价 | | ├─ low | 盘后最低价 | | └─ prev\_close | 盘后参考昨收价 | | overnight\_quote | 夜盘行情对象；仅支持扩展交易时段的产品（如美股）且夜盘行情数据可用时返回 | | ├─ last\_done | 夜盘最新成交价 | | ├─ timestamp | 夜盘行情时间戳（毫秒，UTC） | | ├─ volume | 夜盘成交量 | | ├─ quote\_volume | 夜盘成交额；数据可用时返回 | | ├─ high | 夜盘最高价 | | ├─ low | 夜盘最低价 | | └─ prev\_close | 夜盘参考昨收价 | # A股全量行情 Source: https://docs.tickdb.ai/zh-Hans/rest/api_ticker_cn_stock openapi.yaml GET /v1/market/ticker/cn-stock 获取A股市场当前全量行情快照。 ## 套餐权限 | 套餐 | 可用 | | ----- | :-: | | 免费版 | ❌ | | 基础版 | ❌ | | 专业版 | ❌ | | A 股全量 | ✅ | | 港股全量 | ❌ | | 美股全量 | ❌ | | 企业版 | ✅ | ## 注意事项 * 无需传入请求参数，一次返回当前可用的全部行情记录，不分页。 * 返回范围包括沪深京股票、ETF、指数和债券，可通过 `type` 和 `category` 判断产品类型。 * 响应数据量较大，客户端必须启用 HTTP 响应压缩，并声明支持 `gzip`、`br` 或 `zstd` 中的至少一种格式；未启用压缩时可能返回 `406`。 * `timestamp` 为每条行情的数据时间，使用 Unix 毫秒时间戳。 * `open`、`prev_close` 在对应数据不可用时不会返回。 ## 支持的市场 | 市场 | 示例 | | -- | ------------------------------- | | A股 | 600519.SH, 000001.SZ, 920186.BJ | ## 请求参数 无。 ## 请求示例 ```bash theme={null} curl --compressed \ -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/market/ticker/cn-stock" ``` ## 代码示例 以下 Node.js 22+ 示例声明支持三种压缩格式，并根据响应中的 `Content-Encoding` 自动选择解压方式。 ```javascript theme={null} const https = require("node:https"); const zlib = require("node:zlib"); const decompressors = { gzip: zlib.gunzipSync, br: zlib.brotliDecompressSync, zstd: zlib.zstdDecompressSync, }; const request = https.get("https://api.tickdb.ai/v1/market/ticker/cn-stock", { headers: { "X-API-Key": process.env.TICKDB_API_KEY, "Accept-Encoding": "gzip, br, zstd", }, }, (response) => { const chunks = []; response.on("data", (chunk) => chunks.push(chunk)); response.on("end", () => { if (response.statusCode !== 200) { throw new Error(`请求失败：${response.statusCode}`); } const encoding = response.headers["content-encoding"]; const decompress = decompressors[encoding]; if (!decompress) { throw new Error(`不支持的压缩格式：${encoding}`); } const body = decompress(Buffer.concat(chunks)); const result = JSON.parse(body.toString("utf8")); console.log(`返回 ${result.data.length} 条行情`); console.log(result.data[0]); }); }); request.on("error", console.error); ``` ## 返回字段说明 | 字段 | 说明 | | ------------------------------ | ----------------------------------- | | code | 响应码，`0` 表示成功。 | | message | 响应消息。 | | data | A股市场全量行情数组。 | | └─ symbol | 交易产品代码，包含 `.SH`、`.SZ` 或 `.BJ` 市场后缀。 | | └─ name | 产品名称。 | | └─ type | 产品类型：`stock` 股票类产品、`indices` 指数。 | | └─ category | 产品细分类别，取值说明见下表。 | | └─ last\_price | 最新成交价。 | | └─ open | 当日开盘价；数据不可用时不返回。 | | └─ prev\_close | 上一交易日收盘价；数据不可用时不返回。 | | └─ volume\_24h | 当日累计成交量。 | | └─ quote\_volume\_24h | 当日累计成交额。 | | └─ high\_24h | 当日最高价。 | | └─ low\_24h | 当日最低价。 | | └─ price\_change\_24h | 相对昨收的价格变化。 | | └─ price\_change\_percent\_24h | 相对昨收的价格变化百分比。 | | └─ timestamp | Unix 时间戳，单位为毫秒。 | ### category 取值 | 取值 | 说明 | | ---------- | ------- | | `sh_stock` | 上交所股票。 | | `sz_stock` | 深交所股票。 | | `bj_stock` | 北交所股票。 | | `etf` | ETF。 | | `cn_index` | A股市场指数。 | | `cn_bond` | A股市场债券。 | # 港股全量行情 Source: https://docs.tickdb.ai/zh-Hans/rest/api_ticker_hk_stock openapi.yaml GET /v1/market/ticker/hk-stock 获取港股市场当前全量行情快照。 ## 套餐权限 | 套餐 | 可用 | | ----- | :-: | | 免费版 | ❌ | | 基础版 | ❌ | | 专业版 | ❌ | | A 股全量 | ❌ | | 港股全量 | ✅ | | 美股全量 | ❌ | | 企业版 | ✅ | ## 注意事项 * 无需传入请求参数，一次返回当前可用的全部行情记录，不分页。 * 返回范围以港股为主，并包含当前可用的港股市场指数，可通过 `type` 判断产品类型。 * 响应数据量较大，客户端必须启用 HTTP 响应压缩，并声明支持 `gzip`、`br` 或 `zstd` 中的至少一种格式；未启用压缩时可能返回 `406`。 * `timestamp` 为每条行情的数据时间，使用 Unix 毫秒时间戳。 * `open`、`prev_close` 在对应数据不可用时不会返回。 ## 支持的市场 | 市场 | 示例 | | -- | ------------------------ | | 港股 | 700.HK, 9988.HK, 3690.HK | ## 请求参数 无。 ## 请求示例 ```bash theme={null} curl --compressed \ -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/market/ticker/hk-stock" ``` ## 代码示例 以下 Node.js 22+ 示例声明支持三种压缩格式，并根据响应中的 `Content-Encoding` 自动选择解压方式。 ```javascript theme={null} const https = require("node:https"); const zlib = require("node:zlib"); const decompressors = { gzip: zlib.gunzipSync, br: zlib.brotliDecompressSync, zstd: zlib.zstdDecompressSync, }; const request = https.get("https://api.tickdb.ai/v1/market/ticker/hk-stock", { headers: { "X-API-Key": process.env.TICKDB_API_KEY, "Accept-Encoding": "gzip, br, zstd", }, }, (response) => { const chunks = []; response.on("data", (chunk) => chunks.push(chunk)); response.on("end", () => { if (response.statusCode !== 200) { throw new Error(`请求失败：${response.statusCode}`); } const encoding = response.headers["content-encoding"]; const decompress = decompressors[encoding]; if (!decompress) { throw new Error(`不支持的压缩格式：${encoding}`); } const body = decompress(Buffer.concat(chunks)); const result = JSON.parse(body.toString("utf8")); console.log(`返回 ${result.data.length} 条行情`); console.log(result.data[0]); }); }); request.on("error", console.error); ``` ## 返回字段说明 | 字段 | 说明 | | ------------------------------ | -------------------------------- | | code | 响应码，`0` 表示成功。 | | message | 响应消息。 | | data | 港股市场全量行情数组。 | | └─ symbol | 港股市场代码，例如 `700`。 | | └─ name | 产品名称。 | | └─ type | 产品类型：`stock` 股票类产品、`indices` 指数。 | | └─ last\_price | 最新成交价。 | | └─ open | 当日开盘价；数据不可用时不返回。 | | └─ prev\_close | 上一交易日收盘价；数据不可用时不返回。 | | └─ volume\_24h | 当日累计成交量。 | | └─ quote\_volume\_24h | 当日累计成交额。 | | └─ high\_24h | 当日最高价。 | | └─ low\_24h | 当日最低价。 | | └─ price\_change\_24h | 相对昨收的价格变化。 | | └─ price\_change\_percent\_24h | 相对昨收的价格变化百分比。 | | └─ timestamp | Unix 时间戳，单位为毫秒。 | # 美股全量行情 Source: https://docs.tickdb.ai/zh-Hans/rest/api_ticker_us_stock openapi.yaml GET /v1/market/ticker/us-stock 获取美股市场当前全量行情快照。 ## 套餐权限 | 套餐 | 可用 | | ----- | :-: | | 免费版 | ❌ | | 基础版 | ❌ | | 专业版 | ❌ | | A 股全量 | ❌ | | 港股全量 | ❌ | | 美股全量 | ✅ | | 企业版 | ✅ | ## 注意事项 * 无需传入请求参数，一次返回当前可用的全部行情记录，不分页。 * 响应数据量较大，客户端必须启用 HTTP 响应压缩，并声明支持 `gzip`、`br` 或 `zstd` 中的至少一种格式；未启用压缩时可能返回 `406`。 * `timestamp` 为每条行情的数据时间，使用 Unix 毫秒时间戳。 * 除 `symbol`、`last_price` 和 `timestamp` 外，其余字段根据产品和行情数据可用性返回。 ## 支持的市场 | 市场 | 示例 | | -- | ------------------------- | | 美股 | AAPL.US, TSLA.US, MSFT.US | ## 请求参数 无。 ## 请求示例 ```bash theme={null} curl --compressed \ -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/market/ticker/us-stock" ``` ## 代码示例 以下 Node.js 22+ 示例声明支持三种压缩格式，并根据响应中的 `Content-Encoding` 自动选择解压方式。 ```javascript theme={null} const https = require("node:https"); const zlib = require("node:zlib"); const decompressors = { gzip: zlib.gunzipSync, br: zlib.brotliDecompressSync, zstd: zlib.zstdDecompressSync, }; const request = https.get("https://api.tickdb.ai/v1/market/ticker/us-stock", { headers: { "X-API-Key": process.env.TICKDB_API_KEY, "Accept-Encoding": "gzip, br, zstd", }, }, (response) => { const chunks = []; response.on("data", (chunk) => chunks.push(chunk)); response.on("end", () => { if (response.statusCode !== 200) { throw new Error(`请求失败：${response.statusCode}`); } const encoding = response.headers["content-encoding"]; const decompress = decompressors[encoding]; if (!decompress) { throw new Error(`不支持的压缩格式：${encoding}`); } const body = decompress(Buffer.concat(chunks)); const result = JSON.parse(body.toString("utf8")); console.log(`返回 ${result.data.length} 条行情`); console.log(result.data[0]); }); }); request.on("error", console.error); ``` ## 返回字段说明 | 字段 | 说明 | | ------------------------------ | ----------------------- | | code | 响应码，`0` 表示成功。 | | message | 响应消息。 | | data | 美股市场全量行情数组。 | | └─ symbol | 美股代码，例如 `AAPL`。 | | └─ name | 产品名称；名称信息可用时返回。 | | └─ type | 产品类型。 | | └─ last\_price | 最新成交价。 | | └─ open | 当日开盘价；数据不可用时不返回。 | | └─ prev\_close | 上一交易日收盘价；数据不可用时不返回。 | | └─ volume\_24h | 当日累计成交量；数据不可用时不返回。 | | └─ quote\_volume\_24h | 当日累计成交额；数据不可用时不返回。 | | └─ high\_24h | 当日最高价；数据不可用时不返回。 | | └─ low\_24h | 当日最低价；数据不可用时不返回。 | | └─ price\_change\_24h | 相对昨收的价格变化；数据不可用时不返回。 | | └─ price\_change\_percent\_24h | 相对昨收的价格变化百分比；数据不可用时不返回。 | | └─ timestamp | Unix 时间戳，单位为毫秒。 | # 交易日历 Source: https://docs.tickdb.ai/zh-Hans/rest/api_trade_days openapi.yaml GET /v1/market/trade-days 查询指定市场在特定时间范围内的交易日列表，用于判断某日是否为交易日。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ✅ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 日期格式必须为 YYYYMMDD（如：20260201） * 单次查询的日期范围最多为 31 天 * 开始日期必须在最近一年范围内 * 返回的交易日不包括周末和节假日 * 市场代码不区分大小写 ## 支持的市场 | 市场 | 示例 | | -- | -- | | 美股 | US | | 港股 | HK | | A股 | CN | ## 请求参数 | 参数名 | 是否必须 | 描述 | | -------- | ---- | --------------------------------- | | market | 是 | 市场代码，可选值：`US`、`HK`、`CN` | | beg\_day | 是 | 开始日期，格式：YYYYMMDD，必须在最近一年范围内 | | end\_day | 是 | 结束日期，格式：YYYYMMDD；与开始日期的范围最多为 31 天 | ## 返回字段说明 | 字段 | 说明 | | ----------------- | ----------------------------- | | market | 市场代码 | | trade\_days | 全日交易日列表，使用 YYYYMMDD 格式 | | half\_trade\_days | 半日交易日列表（仅半天交易），使用 YYYYMMDD 格式 | # 逐笔成交 Source: https://docs.tickdb.ai/zh-Hans/rest/api_trades openapi.yaml GET /v1/market/trades 获取交易品种的逐笔成交记录。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * side：买入（buy）/ 卖出（sell）/ 中性（neutral） * 时间戳单位为毫秒（UTC） ## 支持的市场 | 市场 | 示例 | | ---- | ------------------------------- | | 美股 | AAPL.US, TSLA.US, MSFT.US | | 港股 | 700.HK, 9988.HK, 3690.HK | | A股 | 600519.SH, 000001.SZ, 920186.BJ | | 中国期货 | BU2609, IC2606, AP8888 | | 香港期货 | HSI8888, MHI8888, HTI8888 | | 加密货币 | BTCUSDT, ETHUSDT, ADAUSDT | ## 请求参数 | 参数名 | 是否必须 | 描述 | | ------ | ---- | -------------------------------------------------------------------------------------------------------- | | symbol | 是 | 交易产品代码 | | limit | 否 | 返回成交记录数，默认100，最大1000 | | type | 否 | 产品类型，可选。代码无歧义时无需传递；若返回 `AMBIGUOUS_SYMBOL` 错误，按提示传入对应值即可。可选值：`stock`、`indices`、`crypto`、`forex`、`futures` | ## 返回字段说明 | 字段 | 说明 | | ------------------------- | ------------------------------ | | symbol | 交易产品 | | type | 产品类型 | | trades | 成交记录数组 | | └─ id | 成交ID | | └─ price | 成交价格 | | └─ quantity | 成交数量 | | └─ side | 成交方向（`buy`、`sell` 或 `neutral`） | | └─ timestamp | 成交时间（毫秒时间戳，UTC） | | └─ open\_interest\_change | 持仓变化，仅期货返回 | | └─ position\_effect | 持仓影响，仅期货返回；取值见下表 | ### `position_effect` 取值说明 | 类型 | 取值 | | -- | ------------------------------------------------------------- | | 开仓 | `long_open`（多开）
`short_open`（空开）
`both_open`（双开） | | 平仓 | `long_close`（多平）
`short_close`（空平）
`both_close`（双平） | | 换手 | `long_transfer`（多换）
`short_transfer`（空换） | # 交易时段 Source: https://docs.tickdb.ai/zh-Hans/rest/api_trading_sessions openapi.yaml GET /v1/market/trading-sessions 查询一个或全部支持市场的交易时段信息，包括开盘时间、收盘时间等。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ✅ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 返回的时间为各市场的**当地时间** ## 支持的市场 | 市场 | 示例 | | -- | -- | | 美股 | US | | 港股 | HK | | A股 | CN | ## 请求参数 | 参数名 | 是否必须 | 描述 | | ------ | ---- | ----------------------------------- | | market | 否 | 市场代码，可选值：`US`、`HK`、`CN`；不传时返回全部支持市场 | ## 返回字段说明 | 字段 | 说明 | | ----------------- | ------------------------------------------- | | market | 市场（US - 美股市场，HK - 港股市场，CN - A股市场） | | trading\_sessions | 交易时段数组 | | └─ begin\_time | 交易开始时间，格式：hhmm，例如：900 | | └─ end\_time | 交易结束时间，格式：hhmm，例如：1400 | | └─ trade\_session | 交易时段类型（0 - 盘中交易，1 - 盘前交易，2 - 盘后交易，3 - 夜盘交易） | # 股票回购 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_buyback openapi.yaml GET /v1/fundamentals/buyback 获取公司回购计划、执行情况和历史指标。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 估算类回购指标可能为 `null`。 ## 支持的市场 | 市场 | 示例 | | -- | --------- | | 美股 | AAPL.US | | 港股 | 700.HK | | A股 | 600519.SH | ## 请求参数 | 参数 | 是否必须 | 说明 | | -------- | :--: | ----------------- | | `symbol` | 是 | 股票代码 | | `type` | 否 | 产品类型，当前支持 `stock` | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/buyback?symbol=AAPL&type=stock" ``` ## 返回字段说明 以下列出 `data` 中的字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | ------------------------------- | -------------------------------------- | | symbol | 股票代码。 | | currency | 回购金额币种。 | | ttm | 最近 12 个月回购指标。 | | └─ net\_buyback | 净回购额。 | | └─ net\_buyback\_yield | 净回购收益率；可能为 null。 | | └─ buyback\_payout\_ratio | 回购支付率；可能为 null。 | | └─ buyback\_to\_cashflow\_ratio | 回购额与现金流比率；可能为 null。 | | history | 历史年度回购记录。 | | └─ fiscal\_year | 财年。 | | └─ fiscal\_year\_range | 财年日期范围文本，例如 `2024/01/01 - 2024/12/31`。 | | └─ currency | 该年度币种。 | | └─ net\_buyback | 净回购额。 | | └─ net\_buyback\_yield | 净回购收益率；可能为 null。 | | └─ net\_buyback\_growth\_rate | 净回购增长率；可能为 null。 | 返回回购 TTM 指标与历史年度记录。 # 股息日历 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_calendar_dividend openapi.yaml GET /v1/fundamentals/calendar/dividend 查询分红派息事件。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 此接口的事件类别固定为 `dividend`（分红派息），无需传入 `category`。 * `from` 默认为当前 UTC 日期；`to` 默认为 `from` 后 7 天。日期范围两端均包含。 * 默认每页 100 条，最多 500 条。第一页不传 `cursor`；后续保持筛选条件不变，并将上一页的 `page.next_cursor` 原样传入，直到其为 `null`。若首次未传日期，后续页请使用首响应的 `data.from`、`data.to` 固定日期范围。 * API Key 仅允许部分市场时，必须传入已获准的 `market`；无对应事件时返回空 `events` 数组。 ## 支持的市场 | 市场 | 示例 | | -- | -- | | 美股 | US | | 港股 | HK | | A股 | CN | ## 请求参数 | 参数 | 必填 | 说明 | | --------- | :-: | ------------------------------------ | | `from` | 否 | 起始日期，格式 `YYYY-MM-DD` | | `to` | 否 | 结束日期，格式 `YYYY-MM-DD` | | `market` | 否\* | 市场过滤：`US`、`HK`、`CN`；市场受限的 API Key 必填 | | `symbols` | 否 | 股票代码，英文逗号分隔，最多 50 个 | | `limit` | 否 | 每页数量，`1–500`，默认 `100` | | `cursor` | 否 | 下一页游标；第一页不传 | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/calendar/dividend?from=2026-09-21&to=2026-09-28&market=US&limit=100" ``` ## 返回字段说明 成功响应包含顶层 `code`、`data` 和 `page`。 | 字段 | 说明 | | -------------------- | -------------------- | | code | 业务状态码，成功为 `0`。 | | data | 当前页的日期范围和事件数据。 | | └─ from | 查询起始日期，`YYYY-MM-DD`。 | | └─ to | 查询结束日期，`YYYY-MM-DD`。 | | └─ events | 当前页事件列表；无事件时为空数组。 | |   └─ event\_datetime | 事件时间，UTC 日期时间字符串。 | |   └─ market | 所属市场。 | |   └─ symbol | 关联产品代码；不适用时可能为空。 | |   └─ category | 事件细分类别，可能细于请求类别。 | |   └─ event\_type | 事件类型。 | |   └─ content | 事件内容。 | |   └─ counter\_name | 关联名称；可能为 `null`。 | |   └─ currency | 币种；可能为 `null`。 | |   └─ star | 重要程度。 | |   └─ date\_type | 事件日期类型；可能为 `null`。 | |   └─ data | 可选的事件附加数据数组。 | |     └─ key | 附加数据键名。 | |     └─ value\_raw | 原始值；可能为 `null`。 | |     └─ value\_text | 展示值；可能为 `null`。 | |     └─ value\_type | 值类型。 | | page | 分页信息。 | | └─ next\_cursor | 下一页游标；末页为 `null`。 | | └─ limit | 当前分页上限。 | # 新股日历 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_calendar_ipo openapi.yaml GET /v1/fundamentals/calendar/ipo 查询新股发行与上市事件。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 此接口的事件类别固定为 `ipo`（新股发行与上市），无需传入 `category`。 * `from` 默认为当前 UTC 日期；`to` 默认为 `from` 后 7 天。日期范围两端均包含。 * 默认每页 100 条，最多 500 条。第一页不传 `cursor`；后续保持筛选条件不变，并将上一页的 `page.next_cursor` 原样传入，直到其为 `null`。若首次未传日期，后续页请使用首响应的 `data.from`、`data.to` 固定日期范围。 * API Key 仅允许部分市场时，必须传入已获准的 `market`；无对应事件时返回空 `events` 数组。 * 新股事件的 `category` 可能为 `ipo_listing` 或 `ipo_offering`；`issue_price` 在价格可用时返回。 ## 支持的市场 | 市场 | 示例 | | -- | -- | | 美股 | US | | 港股 | HK | | A股 | CN | ## 请求参数 | 参数 | 必填 | 说明 | | --------- | :-: | ------------------------------------ | | `from` | 否 | 起始日期，格式 `YYYY-MM-DD` | | `to` | 否 | 结束日期，格式 `YYYY-MM-DD` | | `market` | 否\* | 市场过滤：`US`、`HK`、`CN`；市场受限的 API Key 必填 | | `symbols` | 否 | 股票代码，英文逗号分隔，最多 50 个 | | `limit` | 否 | 每页数量，`1–500`，默认 `100` | | `cursor` | 否 | 下一页游标；第一页不传 | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/calendar/ipo?from=2026-09-21&to=2026-09-28&market=CN&limit=100" ``` ## 返回字段说明 成功响应包含顶层 `code`、`data` 和 `page`。 | 字段 | 说明 | | -------------------- | ------------------------------ | | code | 业务状态码，成功为 `0`。 | | data | 当前页的日期范围和事件数据。 | | └─ from | 查询起始日期，`YYYY-MM-DD`。 | | └─ to | 查询结束日期，`YYYY-MM-DD`。 | | └─ events | 当前页事件列表；无事件时为空数组。 | |   └─ event\_datetime | 事件时间，UTC 日期时间字符串。 | |   └─ market | 所属市场。 | |   └─ symbol | 关联产品代码；不适用时可能为空。 | |   └─ category | 事件细分类别，可能细于请求类别。 | |   └─ event\_type | 事件类型。 | |   └─ content | 事件内容。 | |   └─ counter\_name | 关联名称；可能为 `null`。 | |   └─ currency | 币种；可能为 `null`。 | |   └─ issue\_price | 新股发行价格；仅相关事件返回，无可用价格时为 `null`。 | |   └─ star | 重要程度。 | |   └─ date\_type | 事件日期类型；可能为 `null`。 | |   └─ data | 可选的事件附加数据数组。 | |     └─ key | 附加数据键名。 | |     └─ value\_raw | 原始值；可能为 `null`。 | |     └─ value\_text | 展示值；可能为 `null`。 | |     └─ value\_type | 值类型。 | | page | 分页信息。 | | └─ next\_cursor | 下一页游标；末页为 `null`。 | | └─ limit | 当前分页上限。 | # 其他日历 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_calendar_other openapi.yaml GET /v1/fundamentals/calendar/other 按类别查询宏观数据、休市、会议等其他财经事件。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 必须传入一种 `category`；财报、股息、拆股和新股事件请使用各自的专用日历接口。 * `from` 默认为当前 UTC 日期；`to` 默认为 `from` 后 7 天。日期范围两端均包含。 * 默认每页 100 条，最多 500 条。第一页不传 `cursor`；后续保持筛选条件不变，并将上一页的 `page.next_cursor` 原样传入，直到其为 `null`。若首次未传日期，后续页请使用首响应的 `data.from`、`data.to` 固定日期范围。 * API Key 仅允许部分市场时，必须传入已获准的 `market`；无对应事件时返回空 `events` 数组。 ## 支持的市场 | 市场 | 示例 | | -- | -- | | 美股 | US | | 港股 | HK | | A股 | CN | ## 请求参数 | 参数 | 必填 | 说明 | | ---------- | :-: | ------------------------------------ | | `from` | 否 | 起始日期，格式 `YYYY-MM-DD` | | `to` | 否 | 结束日期，格式 `YYYY-MM-DD` | | `category` | 是 | 其他事件类别，取值见下表 | | `market` | 否\* | 市场过滤：`US`、`HK`、`CN`；市场受限的 API Key 必填 | | `symbols` | 否 | 股票代码，英文逗号分隔，最多 50 个 | | `limit` | 否 | 每页数量，`1–500`，默认 `100` | | `cursor` | 否 | 下一页游标；第一页不传 | ## category 取值 | 取值 | 说明 | | ------------------------- | -------- | | `macrodata` | 宏观经济数据公布 | | `closed` | 市场休市 | | `meeting` | 会议 | | `merge` | 并购与合并 | | `halt_resume` | 停复牌 | | `special_treatment` | 特别处理 | | `special_treatment_start` | 特别处理开始 | | `special_treatment_end` | 特别处理结束 | | `listing_status` | 上市状态 | | `listing_suspension` | 暂停上市 | | `listing_resumption` | 恢复上市 | | `delisting` | 退市 | | `lockup_expiry` | 限售股解禁 | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/calendar/other?from=2026-09-21&to=2026-09-28&market=US&category=macrodata&limit=100" ``` ## 返回字段说明 成功响应包含顶层 `code`、`data` 和 `page`。 | 字段 | 说明 | | -------------------- | -------------------- | | code | 业务状态码，成功为 `0`。 | | data | 当前页的日期范围和事件数据。 | | └─ from | 查询起始日期，`YYYY-MM-DD`。 | | └─ to | 查询结束日期，`YYYY-MM-DD`。 | | └─ events | 当前页事件列表；无事件时为空数组。 | |   └─ event\_datetime | 事件时间，UTC 日期时间字符串。 | |   └─ market | 所属市场。 | |   └─ symbol | 关联产品代码；不适用时可能为空。 | |   └─ category | 事件细分类别，可能细于请求类别。 | |   └─ event\_type | 事件类型。 | |   └─ content | 事件内容。 | |   └─ counter\_name | 关联名称；可能为 `null`。 | |   └─ currency | 币种；可能为 `null`。 | |   └─ star | 重要程度。 | |   └─ date\_type | 事件日期类型；可能为 `null`。 | |   └─ data | 可选的事件附加数据数组。 | |     └─ key | 附加数据键名。 | |     └─ value\_raw | 原始值；可能为 `null`。 | |     └─ value\_text | 展示值；可能为 `null`。 | |     └─ value\_type | 值类型。 | | page | 分页信息。 | | └─ next\_cursor | 下一页游标；末页为 `null`。 | | └─ limit | 当前分页上限。 | # 财报日历 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_calendar_report openapi.yaml GET /v1/fundamentals/calendar/report 查询财报和业绩公布事件。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 此接口的事件类别固定为 `report`（财报及业绩公布），无需传入 `category`。 * `from` 默认为当前 UTC 日期；`to` 默认为 `from` 后 7 天。日期范围两端均包含。 * 默认每页 100 条，最多 500 条。第一页不传 `cursor`；后续保持筛选条件不变，并将上一页的 `page.next_cursor` 原样传入，直到其为 `null`。若首次未传日期，后续页请使用首响应的 `data.from`、`data.to` 固定日期范围。 * API Key 仅允许部分市场时，必须传入已获准的 `market`；无对应事件时返回空 `events` 数组。 ## 支持的市场 | 市场 | 示例 | | -- | -- | | 美股 | US | | 港股 | HK | | A股 | CN | ## 请求参数 | 参数 | 必填 | 说明 | | --------- | :-: | ------------------------------------ | | `from` | 否 | 起始日期，格式 `YYYY-MM-DD` | | `to` | 否 | 结束日期，格式 `YYYY-MM-DD` | | `market` | 否\* | 市场过滤：`US`、`HK`、`CN`；市场受限的 API Key 必填 | | `symbols` | 否 | 股票代码，英文逗号分隔，最多 50 个 | | `limit` | 否 | 每页数量，`1–500`，默认 `100` | | `cursor` | 否 | 下一页游标；第一页不传 | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/calendar/report?from=2026-09-21&to=2026-09-28&market=US&limit=100" ``` ## 返回字段说明 成功响应包含顶层 `code`、`data` 和 `page`。 | 字段 | 说明 | | -------------------- | -------------------- | | code | 业务状态码，成功为 `0`。 | | data | 当前页的日期范围和事件数据。 | | └─ from | 查询起始日期，`YYYY-MM-DD`。 | | └─ to | 查询结束日期，`YYYY-MM-DD`。 | | └─ events | 当前页事件列表；无事件时为空数组。 | |   └─ event\_datetime | 事件时间，UTC 日期时间字符串。 | |   └─ market | 所属市场。 | |   └─ symbol | 关联产品代码；不适用时可能为空。 | |   └─ category | 事件细分类别，可能细于请求类别。 | |   └─ event\_type | 事件类型。 | |   └─ content | 事件内容。 | |   └─ counter\_name | 关联名称；可能为 `null`。 | |   └─ currency | 币种；可能为 `null`。 | |   └─ star | 重要程度。 | |   └─ date\_type | 事件日期类型；可能为 `null`。 | |   └─ data | 可选的事件附加数据数组。 | |     └─ key | 附加数据键名。 | |     └─ value\_raw | 原始值；可能为 `null`。 | |     └─ value\_text | 展示值；可能为 `null`。 | |     └─ value\_type | 值类型。 | | page | 分页信息。 | | └─ next\_cursor | 下一页游标；末页为 `null`。 | | └─ limit | 当前分页上限。 | # 拆股日历 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_calendar_split openapi.yaml GET /v1/fundamentals/calendar/split 查询拆股、合股等事件。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 此接口的事件类别固定为 `split`（拆股或合股），无需传入 `category`。 * `from` 默认为当前 UTC 日期；`to` 默认为 `from` 后 7 天。日期范围两端均包含。 * 默认每页 100 条，最多 500 条。第一页不传 `cursor`；后续保持筛选条件不变，并将上一页的 `page.next_cursor` 原样传入，直到其为 `null`。若首次未传日期，后续页请使用首响应的 `data.from`、`data.to` 固定日期范围。 * API Key 仅允许部分市场时，必须传入已获准的 `market`；无对应事件时返回空 `events` 数组。 ## 支持的市场 | 市场 | 示例 | | -- | -- | | 美股 | US | | 港股 | HK | | A股 | CN | ## 请求参数 | 参数 | 必填 | 说明 | | --------- | :-: | ------------------------------------ | | `from` | 否 | 起始日期，格式 `YYYY-MM-DD` | | `to` | 否 | 结束日期，格式 `YYYY-MM-DD` | | `market` | 否\* | 市场过滤：`US`、`HK`、`CN`；市场受限的 API Key 必填 | | `symbols` | 否 | 股票代码，英文逗号分隔，最多 50 个 | | `limit` | 否 | 每页数量，`1–500`，默认 `100` | | `cursor` | 否 | 下一页游标；第一页不传 | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/calendar/split?from=2026-09-21&to=2026-09-28&market=US&limit=100" ``` ## 返回字段说明 成功响应包含顶层 `code`、`data` 和 `page`。 | 字段 | 说明 | | -------------------- | -------------------- | | code | 业务状态码，成功为 `0`。 | | data | 当前页的日期范围和事件数据。 | | └─ from | 查询起始日期，`YYYY-MM-DD`。 | | └─ to | 查询结束日期，`YYYY-MM-DD`。 | | └─ events | 当前页事件列表；无事件时为空数组。 | |   └─ event\_datetime | 事件时间，UTC 日期时间字符串。 | |   └─ market | 所属市场。 | |   └─ symbol | 关联产品代码；不适用时可能为空。 | |   └─ category | 事件细分类别，可能细于请求类别。 | |   └─ event\_type | 事件类型。 | |   └─ content | 事件内容。 | |   └─ counter\_name | 关联名称；可能为 `null`。 | |   └─ currency | 币种；可能为 `null`。 | |   └─ star | 重要程度。 | |   └─ date\_type | 事件日期类型；可能为 `null`。 | |   └─ data | 可选的事件附加数据数组。 | |     └─ key | 附加数据键名。 | |     └─ value\_raw | 原始值；可能为 `null`。 | |     └─ value\_text | 展示值；可能为 `null`。 | |     └─ value\_type | 值类型。 | | page | 分页信息。 | | └─ next\_cursor | 下一页游标；末页为 `null`。 | | └─ limit | 当前分页上限。 | # 公司行动 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_corp_actions openapi.yaml GET /v1/fundamentals/corp-actions 查询拆股、并股、配股、代码变更等公司行动事件。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 公司行动事件可跨多个历史日期；`is_recent` 标记近期事件，不代表事件一定发生在查询当天。 ## 支持的市场 | 市场 | 示例 | | -- | --------- | | 美股 | AAPL.US | | 港股 | 700.HK | | A股 | 600519.SH | ## 请求参数 | 参数 | 是否必须 | 说明 | | -------- | :--: | -------------------- | | `symbol` | 是 | 股票代码 | | `type` | 否 | 产品类型，当前支持 `stock` | | `from` | 否 | 起始日期，格式 `YYYY-MM-DD` | | `to` | 否 | 结束日期，格式 `YYYY-MM-DD` | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/corp-actions?symbol=AAPL&type=stock" ``` ## 返回字段说明 以下列出 `data` 中的字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | --------------- | --------------------- | | symbol | 股票代码。 | | events | 公司行动事件列表。 | | └─ event\_id | 事件 ID。 | | └─ action\_code | 行动代码。 | | └─ act\_type | 行动类型。 | | └─ act\_desc | 行动说明。 | | └─ event\_date | 事件日期，格式 `YYYY-MM-DD`。 | | └─ date\_type | 日期类型。 | | └─ date\_zone | 时区。 | | └─ is\_recent | 是否为近期事件。 | 返回事件日期、事件类型、行动代码和事件说明等公司行动信息。 # 分红记录 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_dividends openapi.yaml GET /v1/fundamentals/dividends 查询股票的分红记录，包括历史及已知的未来分红事件，支持日期、类型和分页筛选。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * `amount` 是每股现金分红金额的十进制字符串；非现金分派时可能为 `null`。分页游标位于响应外层 `page`。 ## 支持的市场 | 市场 | 示例 | | -- | --------- | | 美股 | AAPL.US | | 港股 | 700.HK | | A股 | 600519.SH | ## 请求参数 | 参数 | 是否必须 | 说明 | | --------------- | :--: | --------------------------------------- | | `symbol` | 是 | 股票代码 | | `type` | 否 | 产品类型，当前支持 `stock` | | `dividend_type` | 否 | `normal`、`special`、`non_cash`、`unknown` | | `from` | 否 | 起始日期，格式 `YYYY-MM-DD` | | `to` | 否 | 结束日期，格式 `YYYY-MM-DD` | | `limit` | 否 | 单页数量，默认 100，范围 `1–500` | | `cursor` | 否 | 下一页游标 | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/dividends?symbol=AAPL&type=stock&limit=100" ``` ## 返回字段说明 以下列出 `data` 及分页字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | ----------------------------- | ------------------------------------------------- | | symbol | 股票代码。 | | events | 符合筛选条件的分红记录列表。 | | └─ event\_id | 事件 ID。 | | └─ type | 分红类别。 | | └─ distribution\_kind | 分派形式。 | | └─ amount | 每股现金金额；非现金分派时可能为 null。 | | └─ stock\_distribution\_ratio | 每股送股或转增比例；例如 `0.7` 表示每 1 股送转 0.7 股，即每 10 股送转 7 股。 | | └─ currency | 币种。 | | └─ declaration\_date | 公告日，格式 `YYYY-MM-DD`；可能为 `null`。 | | └─ record\_date | 股权登记日，格式 `YYYY-MM-DD`；可能为 `null`。 | | └─ ex\_date | 除权除息日，格式 `YYYY-MM-DD`；可能为 `null`。 | | └─ payment\_date | 支付日，格式 `YYYY-MM-DD`；可能为 `null`。 | | └─ description | 事件说明。 | | └─ detail\_level | 详情级别。 | | page | 响应外层的分页信息。 | | └─ next\_cursor | 下一页游标；末页为空。 | | └─ limit | 当前分页上限。 | 每条记录包含分红类型、每股金额、币种及相关日期；未来日期不代表分红已经完成。 # 股息TTM Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_dividends_ttm openapi.yaml GET /v1/fundamentals/dividends/ttm TTM 指截至统计日的最近 12 个月；查询这段时间内按币种汇总的每股现金股息。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 统计窗口按除息日计算：`ex_date > window_start_exclusive` 且 `ex_date <= as_of_date`；不同币种不合并。 ## 支持的市场 | 市场 | 示例 | | -- | --------- | | 美股 | AAPL.US | | 港股 | 700.HK | | A股 | 600519.SH | ## 请求参数 | 参数 | 是否必须 | 说明 | | -------- | :--: | ---------------------------- | | `symbol` | 是 | 股票代码 | | `type` | 否 | 产品类型，当前支持 `stock` | | `as_of` | 否 | 统计截止日，格式 `YYYY-MM-DD`；默认当前日期 | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/dividends/ttm?symbol=AAPL&type=stock" ``` ## 返回字段说明 以下列出 `data` 中的字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | -------------------------- | -------------------------------- | | symbol | 股票代码。 | | as\_of\_date | TTM 统计截止日，格式 `YYYY-MM-DD`。 | | window\_start\_exclusive | 最近 12 个月窗口的排他起点，格式 `YYYY-MM-DD`。 | | currencies | 按币种分别汇总的现金股息列表。 | | └─ currency | 分红币种。 | | └─ normal\_cash\_dps\_ttm | 普通现金每股股息 TTM。 | | └─ special\_cash\_dps\_ttm | 特别现金每股股息 TTM。 | | └─ total\_cash\_dps\_ttm | 现金每股股息合计；不是股息率。 | | └─ normal\_event\_count | 普通现金分红事件次数。 | | └─ special\_event\_count | 特别现金分红事件次数。 | 按币种返回普通股息、特殊股息、合计现金每股股息及事件数量。统计窗口为截至 `as_of` 的最近 12 个月。 # 高管与董事 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_executives openapi.yaml GET /v1/fundamentals/executives 获取公司当前高管、董事及关键人员列表。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 人员简介可能为空。 ## 支持的市场 | 市场 | 示例 | | -- | --------- | | 美股 | AAPL.US | | 港股 | 700.HK | | A股 | 600519.SH | ## 请求参数 | 参数 | 是否必须 | 说明 | | -------- | :--: | ----------------- | | `symbol` | 是 | 股票代码 | | `type` | 否 | 产品类型，当前支持 `stock` | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/executives?symbol=AAPL&type=stock" ``` ## 返回字段说明 以下列出 `data` 中的字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | ------------ | ------------- | | symbol | 股票代码。 | | total | 人员总数。 | | members | 高管、董事及关键人员列表。 | | └─ name | 姓名。 | | └─ title | 职务。 | | └─ biography | 人物简介。 | 返回公司当前高管、董事或关键人员列表，可用于管理层和公司治理研究。 # 年度财务报表 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_financials_annual openapi.yaml GET /v1/fundamentals/financials/annual 查询最近若干年的利润表、资产负债表或现金流量表指标数据。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * `rows` 是字段级记录；同一年度可能对应多条财务指标。 ## 支持的市场 | 市场 | 示例 | | -- | --------- | | 美股 | AAPL.US | | 港股 | 700.HK | | A股 | 600519.SH | ## 请求参数 | 参数 | 是否必须 | 说明 | | -------- | :--: | ----------------------------------- | | `symbol` | 是 | 股票代码 | | `type` | 否 | 产品类型，当前支持 `stock` | | `kind` | 是 | 报表类型：`IS` 利润表、`BS` 资产负债表、`CF` 现金流量表 | | `n` | 否 | 返回年度数，范围 `1–20` | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/financials/annual?symbol=AAPL&type=stock&kind=IS&n=5" ``` ## 返回字段说明 以下列出 `data` 中的字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | ------------------- | ------------------------------------------------- | | symbol | 股票代码。 | | kind | 报表类型：`IS` 利润表、`BS` 资产负债表、`CF` 现金流量表。 | | rows | 各年度的报表指标记录；同一年度通常有多条。 | | └─ kind | 该记录所属报表类型：`IS` 利润表、`BS` 资产负债表、`CF` 现金流量表。 | | └─ field\_name | 财务字段代码；[查看财务字段字典](./financial_fields_dictionary)。 | | └─ field\_display | 展示名称。 | | └─ indicator\_title | 指标标题。 | | └─ value | 字段数值，以字符串返回。 | | └─ currency | 币种。 | | └─ is\_percent | 是否为百分比字段。 | | └─ fiscal\_year | 财年。 | | └─ fiscal\_period | 报告期。 | | └─ period\_type | 财务周期类型；年度数据通常为 `af`（年度），也可能以 `q4`（第四季度）表示年末报告期。 | | └─ period\_end | 期末日期，格式 `YYYY-MM-DD`。 | | └─ yoy | 同比变化；可能为 null。 | | └─ ratio | 比率；可能为 null。 | 按报表类型返回年度指标数据，适合比较不同年度；`n` 控制年度数。 # 近期财务报表 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_financials_latest openapi.yaml GET /v1/fundamentals/financials/latest 查询最近若干期利润表、资产负债表或现金流量表的指标数据。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * `rows` 是字段级记录；同一期报表通常对应多条记录，`n` 表示期数而非返回行数。 ## 支持的市场 | 市场 | 示例 | | -- | --------- | | 美股 | AAPL.US | | 港股 | 700.HK | | A股 | 600519.SH | ## 请求参数 | 参数 | 是否必须 | 说明 | | ------------- | :--: | ------------------------------------------------------------------------- | | `symbol` | 是 | 股票代码 | | `type` | 否 | 产品类型，当前支持 `stock` | | `kind` | 是 | 报表类型：`IS` 利润表、`BS` 资产负债表、`CF` 现金流量表 | | `n` | 否 | 返回期数，范围 `1–20` | | `period_type` | 否 | 财务周期类型：`q1` 第一季度、`q2` 第二季度、`q3` 第三季度、`q4` 第四季度、`saf` 半年度、`af` 年度；多个值用逗号分隔 | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/financials/latest?symbol=AAPL&type=stock&kind=IS&n=4" ``` ## 返回字段说明 以下列出 `data` 中的字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | ------------------- | ----------------------------------------------------------------- | | symbol | 股票代码。 | | kind | 报表类型：`IS` 利润表、`BS` 资产负债表、`CF` 现金流量表。 | | rows | 最近若干期的报表指标记录；同一期通常有多条。 | | └─ kind | 该记录所属报表类型：`IS` 利润表、`BS` 资产负债表、`CF` 现金流量表。 | | └─ field\_name | 财务字段代码；[查看财务字段字典](./financial_fields_dictionary)。 | | └─ field\_display | 展示名称。 | | └─ indicator\_title | 指标标题。 | | └─ value | 字段数值，以字符串返回。 | | └─ currency | 币种。 | | └─ is\_percent | 是否为百分比字段。 | | └─ fiscal\_year | 财年。 | | └─ fiscal\_period | 报告期。 | | └─ period\_type | 财务周期类型：`q1` 第一季度、`q2` 第二季度、`q3` 第三季度、`q4` 第四季度、`saf` 半年度、`af` 年度。 | | └─ period\_end | 期末日期，格式 `YYYY-MM-DD`。 | | └─ yoy | 同比变化；可能为 null。 | | └─ ratio | 比率；可能为 null。 | 按报表类型返回近期各报告期的指标数据；`n` 控制报告期数，不是指标记录条数。 # 财务数据 TTM Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_financials_ttm openapi.yaml GET /v1/fundamentals/financials/ttm 查询最近四个有效单季汇总的近12个月利润表或现金流量表指标。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * TTM 指滚动近12个月，由最近四个有效单季数据汇总；仅支持利润表 `IS` 和现金流量表 `CF`。 ## 支持的市场 | 市场 | 示例 | | -- | --------- | | 美股 | AAPL.US | | 港股 | 700.HK | | A股 | 600519.SH | ## 请求参数 | 参数 | 是否必须 | 说明 | | -------- | :--: | ------------------------- | | `symbol` | 是 | 股票代码 | | `type` | 否 | 产品类型，当前支持 `stock` | | `kind` | 是 | 报表类型：`IS` 利润表或 `CF` 现金流量表 | TTM 仅对利润表 `IS` 和现金流量表 `CF` 定义，传入资产负债表 `BS` 会返回参数错误。 ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/financials/ttm?symbol=AAPL&type=stock&kind=IS" ``` ## 返回字段说明 以下列出 `data` 中的字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | ------------------- | ------------------------------------------------- | | symbol | 股票代码。 | | kind | 报表类型：`IS` 利润表或 `CF` 现金流量表。 | | rows | 滚动近12个月的财务指标记录。 | | └─ kind | 该记录所属报表类型：`IS` 利润表或 `CF` 现金流量表。 | | └─ field\_name | 财务字段代码；[查看财务字段字典](./financial_fields_dictionary)。 | | └─ field\_display | 展示名称。 | | └─ indicator\_title | 指标标题。 | | └─ value | 对应指标的近12个月汇总值，以字符串返回。 | | └─ currency | 币种。 | | └─ is\_percent | 是否为百分比字段。 | | └─ fiscal\_year | 对应财年。 | | └─ fiscal\_period | 对应报告期。 | | └─ period\_type | `ttm`，表示滚动近12个月的汇总数据。 | | └─ period\_end | 期末日期，格式 `YYYY-MM-DD`。 | | └─ yoy | 同比变化；可能为 null。 | | └─ ratio | 比率；可能为 null。 | 返回最近四个有效单季汇总后的滚动近12个月财务指标。 # 持股基金 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_fund_holdings_latest openapi.yaml GET /v1/fundamentals/fund-holdings/latest 查询哪些基金披露持有指定股票，以及该股票在各基金持仓中的比例；支持分页查询。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ❌ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 持股信息以基金披露日期为准，不一定反映当前交易日持仓；分页信息位于响应外层 `page`。 ## 支持的市场 | 市场 | 示例 | | -- | --------- | | 美股 | AAPL.US | | 港股 | 700.HK | | A股 | 600519.SH | ## 请求参数 | 参数 | 是否必须 | 说明 | | -------- | :--: | ------------------------------------------------- | | `symbol` | 是 | 股票代码 | | `type` | 否 | 产品类型，当前支持 `stock` | | `limit` | 否 | 单页数量，默认 200，范围 `1–500` | | `cursor` | 否 | 分页游标。第一页不传；查询下一页时，填写上一页响应顶层 `page.next_cursor` 的值 | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/fund-holdings/latest?symbol=AAPL&type=stock&limit=3" ``` ## 返回字段说明 以下列出 `data` 及分页字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | ------------------ | ------------------------------------------------ | | symbol | 股票代码。 | | total | 持有该股票的基金记录总数。 | | members | 披露持有该股票的基金列表。 | | └─ fund\_code | 基金代码。 | | └─ fund\_symbol | 标准化基金代码。 | | └─ fund\_name | 基金名称。 | | └─ position\_ratio | 该股票在对应基金持仓中的比例。 | | └─ currency | 币种。 | | └─ report\_date | 报告日期，格式 `YYYY-MM-DD`。 | | page | 响应外层的分页信息。 | | └─ next\_cursor | 下一页游标。非空时原样传入下一次请求的 `cursor`；为 `null` 时表示已到最后一页。 | | └─ limit | 当前分页上限。 | `total` 是符合条件的记录总数，`members` 只包含当前页。查询下一页时，保持 `symbol`、`type` 和 `limit` 不变，将本页响应顶层的 `page.next_cursor` 原样作为下一次请求的 `cursor` 参数；游标是供接口使用的不透明字符串，不需要自行解码或计算。当 `page.next_cursor` 为 `null` 时停止翻页。 以上第一页请求使用 `limit=3`。假设响应顶层的分页信息为： ```json theme={null} { "page": { "next_cursor": "Mw", "limit": 3 } } ``` 则下一页这样请求： ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/fund-holdings/latest?symbol=AAPL&type=stock&limit=3&cursor=Mw" ``` `Mw` 仅是示例；实际请求应使用上一页返回的游标。 # 行业指标排行 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_industries_rank openapi.yaml GET /v1/fundamentals/industries/rank 查询指定市场按行业指标排序的结果。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ❌ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 此接口按 `market` 查询，不使用股票代码；返回的 `industry_counter_id` 可用于行业分类层级接口。 * `market` 不区分大小写，文档中的市场代码统一使用大写形式。 ## 支持的市场 | 市场 | 示例 | | -- | -- | | 美股 | US | | 港股 | HK | | A股 | CN | ## 请求参数 | 参数 | 是否必须 | 说明 | | -------- | :--: | ---------------------------- | | `market` | 是 | 市场代码：`US` 美股、`HK` 港股、`CN` A股 | | `limit` | 否 | 返回条数，默认 50，范围 `1–200` | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/industries/rank?market=US&limit=50" ``` ## 返回字段说明 以下列出 `data` 中的字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | ------------------------ | --------- | | market | 查询市场。 | | indicator | 排行指标。 | | sort\_type | 排序方式。 | | items | 行业指标排行列表。 | | └─ industry\_counter\_id | 行业节点 ID。 | | └─ industry\_name | 行业名称。 | | └─ rank | 名次。 | | └─ value | 行业总市值。 | | └─ change\_percent | 涨跌幅。 | 返回行业 ID、行业名称、排名、行业总市值及变化率；行业 ID 可用于查询行业分类层级。 # 行业分类层级 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_industries_tree openapi.yaml GET /v1/fundamentals/industries/tree 查询指定行业所属的顶层分类及下级行业分类。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ❌ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * `industry_counter_id` 可从行业指标排行获取；不同市场的行业节点不能混用。 * `market` 不区分大小写，文档中的市场代码统一使用大写形式。 ## 支持的市场 | 市场 | 示例 | | -- | -- | | 美股 | US | | 港股 | HK | | A股 | CN | ## 请求参数 | 参数 | 是否必须 | 说明 | | --------------------- | :--: | ---------------------------- | | `market` | 是 | 市场代码：`US` 美股、`HK` 港股、`CN` A股 | | `industry_counter_id` | 是 | 行业节点 ID，可从行业指标排行接口获取 | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/industries/tree?market=US&industry_counter_id=BK%2FUS%2FIN00260" ``` ## 返回字段说明 以下列出 `data` 中的字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | --------------------- | ---------------------- | | market | 查询市场。 | | industry\_counter\_id | 行业节点 ID。 | | top | 所属顶层行业分类。 | | └─ name | 顶层行业名称。 | | └─ market | 顶层行业市场。 | | chain | 当前行业及其下级分类组成的层级结构。 | | └─ name | 节点名称。 | | └─ counter\_id | 行业节点 ID。 | | └─ level | 节点层级。 | | └─ parent\_code | 父节点代码。 | | └─ market | 所属市场。 | | └─ stock\_num | 股票数量。 | | └─ chg | 变动值。 | | └─ ytd\_chg | 年初至今变动值。 | | └─ symbol | 节点关联代码。 | | └─ sharelist\_id | 股票列表 ID。 | | └─ next | 下级行业分类列表；元素递归使用相同节点结构。 | 返回指定行业的顶层归属、当前分类和下级分类，便于查看行业分类关系。 # 行业估值分布 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_industry_dist openapi.yaml GET /v1/fundamentals/industry/dist 获取股票所属行业的估值分布和样本统计。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ❌ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 不同估值指标分别形成一条分布记录；排名和分位值以对应行业样本为准。 ## 支持的市场 | 市场 | 示例 | | -- | --------- | | 美股 | AAPL.US | | 港股 | 700.HK | | A股 | 600519.SH | ## 请求参数 | 参数 | 是否必须 | 说明 | | -------- | :--: | ----------------- | | `symbol` | 是 | 股票代码 | | `type` | 否 | 产品类型，当前支持 `stock` | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/industry/dist?symbol=AAPL&type=stock" ``` ## 返回字段说明 以下列出 `data` 中的字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | -------------- | --------- | | symbol | 股票代码。 | | distributions | 行业估值分布列表。 | | └─ metric | 估值指标代码。 | | └─ value | 当前股票的指标值。 | | └─ low | 行业样本低位。 | | └─ median | 行业样本中位。 | | └─ high | 行业样本高位。 | | └─ rank\_index | 当前排名。 | | └─ rank\_total | 样本总数。 | | └─ ranking | 排名展示值。 | 返回行业估值区间、样本中位数、当前标的排名及样本数量等信息。 # 同行估值对比 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_industry_peers openapi.yaml GET /v1/fundamentals/industry/peers 查询与该股票同行的公司及其估值、每股收益等可比指标。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ❌ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 同业样本和指标可用性随市场、公司而变化；财务比率通常以字符串返回。 ## 支持的市场 | 市场 | 示例 | | -- | --------- | | 美股 | AAPL.US | | 港股 | 700.HK | | A股 | 600519.SH | ## 请求参数 | 参数 | 是否必须 | 说明 | | -------- | :--: | ----------------- | | `symbol` | 是 | 股票代码 | | `type` | 否 | 产品类型，当前支持 `stock` | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/industry/peers?symbol=AAPL&type=stock" ``` ## 返回字段说明 以下列出 `data` 中的字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | --------------------- | ------------------ | | parent\_symbol | 被查询股票代码。 | | peers | 可用于横向比较的同行公司及指标列表。 | | └─ peer\_symbol | 同行公司股票代码。 | | └─ peer\_name | 同行公司名称。 | | └─ currency | 指标币种。 | | └─ pe | 市盈率。 | | └─ eps | 每股收益。 | | └─ bps | 每股净资产。 | | └─ assets | 资产指标。 | | └─ dps | 每股股息。 | | └─ div\_yield | 股息率。 | | └─ div\_payout\_ratio | 派息率。 | | └─ five\_y\_avg\_dps | 五年平均每股股息。 | 返回同行公司的估值、每股收益、每股净资产和股息等指标，便于横向比较。 # 市场状态 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_market_status openapi.yaml GET /v1/fundamentals/market/status 查询不同市场当前的交易阶段和市场时间。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 这是全局接口，不接受 `market` 或 `symbol` 参数；状态随交易时段变化。 ## 支持的市场 | 市场 | 示例 | | -- | -- | | 美股 | US | | 港股 | HK | | A股 | CN | ## 请求参数 该接口不需要查询参数。 ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/market/status" ``` ## 返回字段说明 以下列出 `data` 中的字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | ---------------- | --------------------------------- | | markets | 各市场交易状态列表。 | | └─ market | 市场代码。 | | └─ market\_time | 该市场的当前时间，RFC 3339 日期时间字符串，包含时区信息。 | | └─ trade\_status | 交易状态代码。 | 返回 `CN`、`HK`、`US` 三个市场的市场时间和交易状态。 ### `trade_status` 状态码 不同市场只会返回适用的状态。常见及特殊交易阶段的代码如下： | 市场 | 状态码 | 含义 | | ----- | ----: | ---------- | | CN、HK | `101` | 开市前清算 | | CN、HK | `102` | 开盘集合竞价 | | CN、HK | `105` | 正常交易 | | CN、HK | `106` | 午间休市 | | CN、HK | `107` | 收盘集合竞价 | | CN、HK | `108` | 已收市 | | CN | `120` | 盘后固定价格交易 | | CN、HK | `121` | 半日市收市 | | CN、HK | `122` | 特殊情况下尚未开市 | | CN、HK | `123` | 盘中临时休市 | | US | `201` | 盘前交易 | | US | `202` | 正常交易 | | US | `203` | 盘后交易 | | US | `204` | 已收市 | | US | `205` | 暂停交易 | | US | `206` | 开市前清算及盘前时段 | | US | `207` | 夜盘交易 | | US | `209` | 盘前清算 | | US | `210` | 盘后清算 | # 个股新闻 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_news openapi.yaml GET /v1/fundamentals/news 获取个股新闻列表、发布时间和正文可用状态。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ❌ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 新闻列表不包含正文；使用 `news_id` 查询详情。`from` 和 `to` 必须同时提供或同时省略。 ## 支持的市场 | 市场 | 示例 | | -- | --------- | | 美股 | AAPL.US | | 港股 | 700.HK | | A股 | 600519.SH | ## 请求参数 | 参数 | 是否必须 | 说明 | | -------- | :--: | --------------------- | | `symbol` | 是 | 股票代码 | | `type` | 否 | 产品类型，当前支持 `stock` | | `limit` | 否 | 返回数量，默认 50，范围 `1–200` | | `from` | 否 | 起始日期，格式 `YYYY-MM-DD` | | `to` | 否 | 结束日期，格式 `YYYY-MM-DD` | `from` 和 `to` 必须同时提供或同时省略。 ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/news?symbol=AAPL&type=stock&limit=20" ``` ## 返回字段说明 以下列出 `data` 中的字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | ---------------- | --------------------------- | | symbol | 股票代码。 | | limit | 本次请求的返回条数上限。 | | news | 新闻列表。 | | └─ news\_id | 新闻 ID，可用于查询详情。 | | └─ title | 新闻标题。 | | └─ description | 新闻摘要。 | | └─ published\_at | 发布时间，RFC 3339 日期时间字符串（UTC）。 | | └─ has\_body | 是否有可用正文。 | 新闻列表返回 `news_id`、标题、摘要、发布时间和正文可用状态，不直接内嵌正文。使用 `news_id` 查询新闻详情。 # 新闻详情 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_news_detail openapi.yaml GET /v1/fundamentals/news/{news_id} 根据新闻 ID 查询新闻正文或可用摘要。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ❌ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 使用新闻列表返回的 `news_id` 查询详情。若 `detail_status` 为 `pending`、`blocked` 或 `failed`，`body_text` 和 `body_html` 可能为 `null`；展示 `body_html` 前应安全过滤。 ## 支持的市场 | 市场 | 示例 | | -- | -- | | 美股 | US | | 港股 | HK | | A股 | CN | ## 请求参数 | 参数 | 位置 | 是否必须 | 说明 | | --------- | ---- | :--: | ---------------------- | | `news_id` | path | 是 | 新闻列表返回的不透明文章 ID，按字符串传递 | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/news/6288041" ``` ## 返回字段说明 以下列出 `data` 中的字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | -------------- | --------------------------- | | news\_id | 新闻 ID。 | | title | 新闻标题。 | | description | 新闻摘要。 | | published\_at | 发布时间，RFC 3339 日期时间字符串（UTC）。 | | detail\_status | 正文详情获取状态。 | | content\_scope | 可提供的内容范围；excerpt 表示节选。 | | body\_text | 纯文本正文；不可用时可能为 null。 | | body\_html | HTML 正文；不可用时可能为 null。 | 返回标题、摘要、发布时间、正文状态、内容范围、纯文本正文和 HTML 正文。 `content_scope=excerpt` 表示摘要或节选，不代表完整全文。`body_html` 属于外部内容，展示时应继续执行安全过滤。 # 公司资料 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_profile openapi.yaml GET /v1/fundamentals/profile 获取公司的基本资料、所属市场、行业和上市信息。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 部分资料字段可能为空字符串或 `null`；不要把缺失值当作“无”。 ## 支持的市场 | 市场 | 示例 | | -- | --------- | | 美股 | AAPL.US | | 港股 | 700.HK | | A股 | 600519.SH | ## 请求参数 | 参数 | 是否必须 | 说明 | | -------- | :--: | ----------------- | | `symbol` | 是 | 股票代码 | | `type` | 否 | 产品类型，当前支持 `stock` | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/profile?symbol=AAPL&type=stock" ``` ## 返回字段说明 以下列出 `data` 中的字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | ---------------- | -------------------------------- | | symbol | 标准化股票代码。 | | market | 所属市场。 | | region | 所属地区。 | | company\_name | 公司全称。 | | name | 展示名称。 | | profile | 公司业务简介。 | | address | 地址。 | | office\_address | 办公地址。 | | phone | 联系电话。 | | email | 电子邮箱。 | | website | 公司网站。 | | founded | 成立年份或日期；无数据时为 null。 | | listing\_date | 上市日期，格式 `YYYY-MM-DD`；可能为 `null`。 | | year\_end | 财年结束信息；可能为 null。 | | employees | 员工人数。 | | chairman | 董事长。 | | manager | 主要管理人员。 | | secretary | 公司秘书。 | | legal\_repr | 法定代表人。 | | accounting\_firm | 会计师事务所。 | | legal\_counsel | 法律顾问。 | | category | 公司类别。 | 部分字段会因市场及个股而异；以实际返回为准。 # 历史营收构成 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_segments_history openapi.yaml GET /v1/fundamentals/segments/history 展示历史报告期按业务或地区划分的收入金额和占比。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ❌ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 可查询的历史报告期因公司而异；没有匹配数据时可能返回结构化 `404`。 ## 支持的市场 | 市场 | 示例 | | -- | --------- | | 美股 | AAPL.US | | 港股 | 700.HK | | A股 | 600519.SH | ## 请求参数 | 参数 | 是否必须 | 说明 | | ---------- | :--: | ------------------------------------------------ | | `symbol` | 是 | 股票代码 | | `type` | 否 | 产品类型，当前支持 `stock` | | `category` | 否 | 营收构成维度：`business` 按业务；`regional` 按地区。不传返回全部可用维度。 | | `report` | 否 | 报告周期：`qf` 季度报告、`saf` 半年度报告、`af` 年度报告 | | `limit` | 否 | 返回条数，默认 200，范围 `1–1000` | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/segments/history?symbol=AAPL&type=stock&category=business&limit=200" ``` ## 返回字段说明 以下列出 `data` 中的字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | ----------------- | ------------------------------------------------------ | | symbol | 股票代码。 | | report | 请求指定的报告周期；`qf` 季度报告、`saf` 半年度报告、`af` 年度报告，未指定时可为 null。 | | segments | 历史报告期的营收构成明细。 | | └─ segment\_name | 业务类别或地区名称。 | | └─ category | 该记录所属维度：`business` 按业务，`regional` 按地区。 | | └─ value | 该业务类别或地区的收入金额。 | | └─ total\_revenue | 该报告期总收入。 | | └─ percent | 该业务类别或地区收入占当期总收入的百分比，例如 `79.74` 表示 79.74%。 | | └─ currency | 金额币种。 | | └─ report | 该记录的报告周期：`qf` 季度报告、`saf` 半年度报告、`af` 年度报告。 | | └─ period\_start | 周期开始日期，格式 `YYYY-MM-DD`。 | | └─ period\_end | 周期结束日期，格式 `YYYY-MM-DD`。 | 每条明细对应一个报告期的业务类别或地区。筛选条件没有匹配数据时可能返回结构化 `404`。 # 营收构成 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_segments_latest openapi.yaml GET /v1/fundamentals/segments/latest 展示最近一期按业务或地区划分的收入金额和占比。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ❌ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * `category=business` 按业务查看营收构成，`category=regional` 按地区查看；分类数量因公司而异。 ## 支持的市场 | 市场 | 示例 | | -- | --------- | | 美股 | AAPL.US | | 港股 | 700.HK | | A股 | 600519.SH | ## 请求参数 | 参数 | 是否必须 | 说明 | | ---------- | :--: | ------------------------------------------------ | | `symbol` | 是 | 股票代码 | | `type` | 否 | 产品类型，当前支持 `stock` | | `category` | 否 | 营收构成维度：`business` 按业务；`regional` 按地区。不传返回全部可用维度。 | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/segments/latest?symbol=AAPL&type=stock&category=business" ``` ## 返回字段说明 以下列出 `data` 中的字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | ----------------- | ------------------------------------------ | | symbol | 股票代码。 | | segments | 最近一期营收构成明细。 | | └─ segment\_name | 业务类别或地区名称。 | | └─ category | 该记录所属维度：`business` 按业务，`regional` 按地区。 | | └─ value | 该业务类别或地区的收入金额。 | | └─ total\_revenue | 该报告期总收入。 | | └─ percent | 该业务类别或地区收入占当期总收入的百分比，例如 `79.74` 表示 79.74%。 | | └─ currency | 金额币种。 | | └─ report | 报告周期：`qf` 季度报告、`saf` 半年度报告、`af` 年度报告。 | | └─ period\_start | 周期开始日期，格式 `YYYY-MM-DD`。 | | └─ period\_end | 周期结束日期，格式 `YYYY-MM-DD`。 | 每条明细对应一个业务类别或地区，`value` 为其收入金额，`total_revenue` 为同一报告期的总收入。 # 股东持仓详情 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_shareholder_detail openapi.yaml GET /v1/fundamentals/shareholders/detail 根据股东对象 ID 查询单个股东的持仓和交易明细。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ❌ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * `object_id` 应取自股东持仓接口中 `detail_available=true` 的记录；否则可能返回 `404`。 ## 支持的市场 | 市场 | 示例 | | -- | --------- | | 美股 | AAPL.US | | 港股 | 700.HK | | A股 | 600519.SH | ## 请求参数 | 参数 | 是否必须 | 说明 | | ----------- | :--: | ---------------------------------------- | | `symbol` | 是 | 股票代码 | | `type` | 否 | 产品类型，当前支持 `stock` | | `object_id` | 是 | 来自股东持仓接口且 `detail_available=true` 的对象 ID | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/shareholders/detail?symbol=AAPL&type=stock&object_id=452583" ``` ## 返回字段说明 以下列出 `data` 中的字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | --------------------------------- | ------------------------- | | symbol | 股票代码。 | | object\_id | 股东对象 ID。 | | name | 股东名称。 | | title | 股东或机构标题。 | | holding\_summary | 分报告期的持仓汇总。 | | └─ accum\_buy | 该报告期累计买入数量。 | | └─ accum\_sell | 该报告期累计卖出数量。 | | └─ percent\_stock\_price\_changed | 该报告期股价变化比例，包含百分号。 | | └─ period | 报告期。 | | └─ stock\_price | 该报告期对应股价。 | | holding\_periods | 可用持仓报告期列表。 | | holding\_details | 逐报告期持仓明细。 | | └─ filing\_date | 原始申报日期文本，例如 `2026/05/07`。 | | └─ name | 股东名称。 | | └─ object\_id | 股东对象 ID。 | | └─ percent\_shares\_changed | 持股比例变化，包含百分号。 | | └─ percent\_shares\_held | 持股比例，包含百分号。 | | └─ period | 报告期。 | | └─ shares\_changed | 股份变动数量。 | | └─ shares\_held | 持股数量。 | | trading\_periods | 可用交易统计期间。 | | tradings | 分期间交易汇总。 | | └─ accum\_buy | 该期间累计买入数量。 | | └─ accum\_sell | 该期间累计卖出数量。 | | └─ net\_buy | 该期间净买入数量。 | | └─ period | 交易统计期间。 | | └─ trading\_details | 该期间的交易明细列表。 | 返回股东持仓汇总、持仓期间、持仓明细、交易期间和交易汇总。没有可用详情时可能返回结构化 `404`。 # 最新股东结构 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_shareholders_latest openapi.yaml GET /v1/fundamentals/shareholders/latest 获取当前股东结构快照。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ❌ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 报告日期代表股东数据所属披露期，不一定是当前交易日。 ## 支持的市场 | 市场 | 示例 | | -- | --------- | | 美股 | AAPL.US | | 港股 | 700.HK | | A股 | 600519.SH | ## 请求参数 | 参数 | 是否必须 | 说明 | | -------- | :--: | ----------------- | | `symbol` | 是 | 股票代码 | | `type` | 否 | 产品类型，当前支持 `stock` | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/shareholders/latest?symbol=AAPL&type=stock" ``` ## 返回字段说明 以下列出 `data` 中的字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | ---------------------- | -------------------------- | | symbol | 股票代码。 | | report\_date | 报告日期，格式 `YYYY-MM-DD`。 | | total | 股东记录总数。 | | members | 股东记录列表。 | | └─ shareholder\_name | 股东名称。 | | └─ percent\_of\_shares | 持股比例数值，不含百分号。 | | └─ shares\_changed | 较上一报告期的股份变动数量。 | | └─ report\_date | 该条记录的报告日期，格式 `YYYY-MM-DD`。 | 返回股东名称、持股比例、股份变化和报告日期等当前股东结构信息。 # 股东持仓 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_shareholders_top openapi.yaml GET /v1/fundamentals/shareholders/top 查询主要股东在不同报告期的持股情况、持仓变动及详情可用状态。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ❌ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 响应包含多个报告期的股东记录，不限于十位股东；只有 `detail_available=true` 的 `object_id` 可用于股东详情接口。 ## 支持的市场 | 市场 | 示例 | | -- | --------- | | 美股 | AAPL.US | | 港股 | 700.HK | | A股 | 600519.SH | ## 请求参数 | 参数 | 是否必须 | 说明 | | -------- | :--: | ----------------- | | `symbol` | 是 | 股票代码 | | `type` | 否 | 产品类型，当前支持 `stock` | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/shareholders/top?symbol=AAPL&type=stock" ``` ## 返回字段说明 以下列出 `data` 中的字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | ------------------------------- | -------------------------------- | | symbol | 股票代码。 | | total | 汇总记录数。 | | periods | 可用报告期列表。 | | info | 按报告期分组的股东持仓数据。 | | └─ period | 报告期。 | | └─ share\_holders | 该报告期的股东列表。 | |     └─ object\_id | 股东对象 ID。 | |     └─ name | 股东名称。 | |     └─ shares\_held | 持股数量，以字符串返回。 | |     └─ percent\_shares\_held | 持股比例，包含百分号。 | |     └─ shares\_changed | 股份变动。 | |     └─ percent\_shares\_changed | 持股比例变化，包含百分号。 | |     └─ period | 该条记录的报告期。 | |     └─ filing\_date | 原始申报日期文本，例如 `2026/05/07`。 | | members | 整理后的股东记录。 | | └─ shareholder\_name | 股东名称。 | | └─ shareholder\_type | 股东类型。 | | └─ shares\_held | 持股数量，以字符串返回。 | | └─ percent\_shares\_held | 持股比例数值，不含百分号；无法转换时为 `null`。 | | └─ percent\_shares\_held\_raw | 持股比例原始文本，包含百分号并可保留 `<0.01%` 等表示。 | | └─ percent\_shares\_changed | 持股比例变化数值，不含百分号；无法转换时为 `null`。 | | └─ filing\_date | 申报日期，格式 `YYYY-MM-DD`。 | | └─ report\_date | 报告日期，格式 `YYYY-MM-DD`；可能为 `null`。 | | └─ object\_id | 股东对象 ID。 | | └─ detail\_available | 是否可查询股东详情。 | 返回股东名称、机构类型、持股数量、持股比例、报告日期、`object_id` 和 `detail_available`。 只有 `detail_available=true` 时，对应的 `object_id` 才可用于股东详情接口。 # 最新估值 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_valuation_latest openapi.yaml GET /v1/fundamentals/valuation/latest 获取股票当前市盈率及近一年区间统计。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * 缺少可用估值数据时，单个指标的 `value` 和区间统计可能为 `null`。 ## 支持的市场 | 市场 | 示例 | | -- | --------- | | 美股 | AAPL.US | | 港股 | 700.HK | | A股 | 600519.SH | ## 请求参数 | 参数 | 是否必须 | 说明 | | -------- | :--: | ----------------- | | `symbol` | 是 | 股票代码 | | `type` | 否 | 产品类型，当前支持 `stock` | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/valuation/latest?symbol=AAPL&type=stock" ``` ## 返回字段说明 以下列出 `data` 中的字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | ----------------- | --------------- | | symbol | 股票代码。 | | metrics | 按指标代码组织的估值快照。 | | └─ PE | 市盈率指标。 | |     └─ value | 当前市盈率；可能为 null。 | |     └─ low\_1y | 近一年低位。 | |     └─ median\_1y | 近一年中位。 | |     └─ high\_1y | 近一年高位。 | |     └─ desc | 指标说明；可能为 null。 | 返回当前市盈率（PE）及其近一年低位、中位和高位统计。 # 历史估值 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/api_valuation_ts openapi.yaml GET /v1/fundamentals/valuation/ts 查询市盈率（PE）按日或按月的历史数值。 ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ❌ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 注意事项 * `points` 中每个元素为 `[时间, 指标值]`，不是带字段名的对象；时间是带时区信息的 RFC 3339 字符串。 * 未指定日期范围时，`daily` 默认查询最近一年，`monthly` 默认查询最近五年。查询范围内没有记录时返回 HTTP 404、错误码 `40405`，不是成功的空数组。 ## 支持的市场 | 市场 | 示例 | | -- | --------- | | 美股 | AAPL.US | | 港股 | 700.HK | | A股 | 600519.SH | ## 请求参数 | 参数 | 是否必须 | 说明 | | ------------- | :--: | ------------------------------ | | `symbol` | 是 | 股票代码 | | `type` | 否 | 产品类型，当前支持 `stock` | | `granularity` | 否 | `daily` 或 `monthly`，默认 `daily` | | `from` | 否 | 起始日期，格式 `YYYY-MM-DD` | | `to` | 否 | 结束日期，格式 `YYYY-MM-DD` | ## 请求示例 ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.tickdb.ai/v1/fundamentals/valuation/ts?symbol=AAPL&type=stock&granularity=monthly" ``` ## 返回字段说明 以下列出 `data` 中的字段；外层 `code=0` 表示成功。 | 字段 | 说明 | | ----------- | ------------------------- | | symbol | 股票代码。 | | metric | 估值指标，当前为 `PE`（市盈率）。 | | granularity | 时间粒度：日度或月度。 | | from | 查询范围起始日期，格式 `YYYY-MM-DD`。 | | to | 查询范围结束日期，格式 `YYYY-MM-DD`。 | | points | 历史估值记录；每个元素是 `[时间, 指标值]`。 | | └─ \[0] | RFC 3339 日期时间字符串，包含时区信息。 | | └─ \[1] | 对应指标值，可以是字符串、数值或 `null`。 | 返回市盈率（PE）在查询时间范围内的日度或月度历史数值。 # 财务字段字典 Source: https://docs.tickdb.ai/zh-Hans/rest/fundamentals/financial_fields_dictionary 财务报表接口返回字段代码、指标名称及数值口径说明。 本字典用于匹配以下接口响应中 `rows[].field_name` 的字段代码： * [近期财务报表](./api_financials_latest)：查询近期利润表、资产负债表或现金流量表指标。 * [年度财务报表](./api_financials_annual)：查询年度利润表、资产负债表或现金流量表指标。 * [财务数据 TTM](./api_financials_ttm)：查询滚动近12个月的利润表或现金流量表指标，仅返回可由最近四个有效单季数据汇总的字段。 ## 字段匹配方式 | 响应字段 | 说明 | | ----------------- | ------------------ | | `field_name` | 财务字段代码，用于在下表中匹配指标。 | | `indicator_title` | 指标标题。 | | `field_display` | 指标展示名称，可能包含单位。 | | `value` | 指标数值，以字符串返回。 | | `currency` | 货币金额或每股金额对应的币种。 | | `is_percent` | 是否为百分比字段。 | | `yoy` | 同比变化；可能为 `null`。 | | `ratio` | 比率；可能为 `null`。 | * 货币金额和每股金额的币种以每条记录的 `currency` 为准。 * 百分比字段的 `is_percent` 为 `true`；其他比率或倍数不一定使用百分比表示。 * 字段是否出现以及是否有值取决于公司、市场和报告期的数据覆盖；缺失值不会以 `0` 代替。 * “TTM 适用”表示该字段可出现在财务数据 TTM 响应中，实际是否返回取决于是否存在可汇总的数据。 ## 利润表（IS） | 字段代码 | 指标名称 | 数值口径 | TTM 适用 | | ------------------- | ----- | ---- | :----: | | `EPS` | 每股收益 | 每股金额 | 是 | | `GrossMgn` | 毛利率 | 百分比 | 否 | | `NetProfit` | 净利润 | 货币金额 | 是 | | `NetProfitMargin` | 净利率 | 百分比 | 否 | | `NetProfitMarginDf` | 净利率 | 百分比 | 否 | | `OperatingIncome` | 营业利润 | 货币金额 | 是 | | `OperatingRevenue` | 营业收入 | 货币金额 | 是 | | `ProfitQuality` | 利润含金量 | 百分比 | 否 | | `ROE` | ROE | 百分比 | 否 | | `ROEDf` | ROE | 百分比 | 否 | ## 资产负债表（BS） 资产负债表是特定日期的时点数据，不适用于 TTM 汇总。 | 字段代码 | 指标名称 | 数值口径 | | ---------------- | ------- | ---- | | `AssetTurn` | 资产周转率 | 倍数 | | `AssetTurnDf` | 资产周转率 | 倍数 | | `BPS` | 每股净资产 | 每股金额 | | `CashSTInvest` | 现金及短期投资 | 货币金额 | | `Inventory` | 存货与应收 | 货币金额 | | `LTInvest` | 长期投资 | 货币金额 | | `Leverage` | 权益乘数 | 倍数 | | `NPPE` | 长期投资 | 货币金额 | | `NetDebt` | 净债务 | 货币金额 | | `TotalAssets` | 资产与负债 | 货币金额 | | `TotalLiability` | 资产与负债 | 货币金额 | | `TotalReceiv` | 存货与应收 | 货币金额 | ## 现金流量表（CF） | 字段代码 | 指标名称 | 数值口径 | TTM 适用 | | -------------------- | ------ | ---- | :----: | | `CapEx` | 资本支出 | 货币金额 | 是 | | `NetFinanceCashFlow` | 融资现金流 | 货币金额 | 是 | | `NetFreeCashFlow` | 自由现金流 | 货币金额 | 是 | | `NetInvestCashFlow` | 投资现金流 | 货币金额 | 是 | | `NetOperateCashFlow` | 经营现金流 | 货币金额 | 是 | | `OCFCoverage` | 现金流充裕率 | 百分比 | 否 | | `TotalDebtIssued` | 举债与偿债 | 货币金额 | 否 | | `TotalDebtRepaid` | 举债与偿债 | 货币金额 | 是 | # 盘口深度（Depth） Source: https://docs.tickdb.ai/zh-Hans/websocket/depth ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 支持的市场 支持市场：美股、港股、A股、中国期货、加密货币 ## 订阅 ```json theme={null} { "cmd": "subscribe", "data": { "channel": "depth", "symbols": ["AAPL.US", "BTCUSDT"] } } ``` > `type` 对本次订阅中的全部代码生效。混合订阅不同产品类型时请省略 `type`；仅在代码存在歧义时，按产品类型拆分订阅并传入对应值。 ## 取消订阅 ```json theme={null} { "cmd": "unsubscribe", "data": { "channel": "depth", "symbols": ["AAPL.US"] } } ``` ## 服务器响应 ```json theme={null} { "cmd": "depth", "data": { "symbol": "BTCUSDT", "bids": [ ["43250.50", "0.125"], ["43250.00", "0.250"] ], "asks": [ ["43251.00", "0.180"], ["43251.50", "0.320"] ], "timestamp": 1703123456789 } } ``` ### 字段说明 | 字段 | 类型 | 描述 | | --------- | ------ | --------------- | | symbol | string | 交易品种 | | bids | array | 买盘档位：`[价格, 数量]` | | asks | array | 卖盘档位：`[价格, 数量]` | | timestamp | int | 服务器时间戳（毫秒） | **排序** * `bids`：价格降序 * `asks`：价格升序 # 心跳检测（Ping） Source: https://docs.tickdb.ai/zh-Hans/websocket/ping ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ✅ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | 用于检查连接是否保持可用。发送 `ping` 后，服务端返回 `pong`，其中 `data.timestamp` 为毫秒级 Unix 时间戳。 ## 发送消息 ```json theme={null} {"cmd":"ping"} ``` ## 返回消息 ```json theme={null} {"cmd":"pong","code":0,"message":"pong","data":{"timestamp":1768976158541}} ``` # 实时行情（Ticker） Source: https://docs.tickdb.ai/zh-Hans/websocket/ticker ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ✅ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 支持的市场 支持市场：外汇、贵金属、指数、美股、港股、A股、中国期货、香港期货、加密货币 ## 订阅 ```json theme={null} { "cmd": "subscribe", "data": { "channel": "ticker", "symbols": ["AAPL.US", "BTCUSDT"] } } ``` > `type` 对本次订阅中的全部代码生效。混合订阅不同产品类型时请省略 `type`；仅在代码存在歧义时，按产品类型拆分订阅并传入对应值。 ## 取消订阅 ```json theme={null} { "cmd": "unsubscribe", "data": { "channel": "ticker", "symbols": ["AAPL.US"] } } ``` ## 服务器响应 ticker 消息根据不同市场类型返回不同的字段。 ### 指数 ```json theme={null} { "cmd": "ticker", "data": { "symbol": "SPX", "type": "indices", "last_price": "7342.86", "timestamp": 1779204386000 } } ``` ### 贵金属 ```json theme={null} { "cmd": "ticker", "data": { "symbol": "XAUUSD", "type": "forex", "last_price": "5130.72000", "ask_price": "5131.07000", "bid_price": "5130.37000", "spread": "0.70000", "timestamp": 1773334355000 } } ``` ### 外汇 ```json theme={null} { "cmd": "ticker", "data": { "symbol": "EURUSD", "type": "forex", "last_price": "1.15200", "ask_price": "1.15202", "bid_price": "1.15199", "spread": "0.00003", "timestamp": 1773334426000 } } ``` ### 股票 美股： `trade_session` 仅在盘前、盘后或夜盘等扩展交易时段返回，可选值为 `pre_market`、`post_market`、`overnight`。 ```json theme={null} { "cmd": "ticker", "data": { "symbol": "NVDA.US", "type": "stock", "last_price": "221.25", "volume_24h": "462724", "high_24h": "223.44", "low_24h": "220.04", "trade_session": "overnight", "timestamp": 1779171600000 } } ``` 港股： ```json theme={null} { "cmd": "ticker", "data": { "symbol": "700.HK", "type": "stock", "last_price": "461.4", "volume_24h": "24687716", "high_24h": "468.8", "low_24h": "448.6", "timestamp": 1779171608000 } } ``` A股： ```json theme={null} { "cmd": "ticker", "data": { "symbol": "600519.SH", "type": "stock", "last_price": "1319.01", "volume_24h": "37263", "high_24h": "1329.99", "low_24h": "1318", "price_change_24h": "-3.99", "price_change_percent_24h": "-0.30", "timestamp": 1779171605000 } } ``` 中国期货： ```json theme={null} { "cmd": "ticker", "data": { "symbol": "BU2609", "type": "futures", "last_price": "4309", "bid_price": "4308", "ask_price": "4310", "volume_24h": "37263", "high_24h": "4336", "low_24h": "4278", "timestamp": 1784012398000 } } ``` ### 加密货币 ```json theme={null} { "cmd": "ticker", "data": { "symbol": "BTCUSDT", "type": "crypto", "last_price": "70480.57000000", "volume_24h": "23737.52989000", "high_24h": "71321.00000000", "low_24h": "69205.91000000", "price_change_24h": "-362.06000000", "price_change_percent_24h": "-0.511", "timestamp": 1773335135026 } } ``` ### 字段说明 | 字段 | 类型 | 描述 | 市场 | | --------------------------- | ------ | ------------------------------------------------- | ----------- | | symbol | string | 交易产品代码 | 全部 | | name | string | 产品名称；名称可用时返回 | 部分产品 | | type | string | 产品类型 | 全部 | | category | string | 产品细分类别；分类信息可用时返回 | A股市场产品 | | last\_price | string | 最新价格 | 全部 | | timestamp | int | Unix 时间戳，单位为毫秒 | 全部 | | open | string | 开盘价；对应行情统计可用时返回 | 股票、期货、加密货币等 | | prev\_close | string | 昨收或统计窗口参考价；数据可用时返回 | 股票、期货、加密货币等 | | ask\_price | string | 最优卖价；报价可用时返回 | 外汇、贵金属、期货等 | | bid\_price | string | 最优买价；报价可用时返回 | 外汇、贵金属、期货等 | | spread | string | 买卖价差；报价可用时返回 | 外汇、贵金属 | | volume\_24h | string | 成交量；统计窗口见上文 | 股票、期货、加密货币 | | quote\_volume\_24h | string | 与 `volume_24h` 同一统计窗口的成交额；数据可用时返回 | 股票、加密货币等 | | high\_24h | string | 最高价；统计窗口与 `volume_24h` 一致 | 股票、期货、加密货币 | | low\_24h | string | 最低价；统计窗口与 `volume_24h` 一致 | 股票、期货、加密货币 | | price\_change\_24h | string | 价格变化；统计窗口与 `volume_24h` 一致，数据可用时返回 | 股票、期货、加密货币 | | price\_change\_percent\_24h | string | 价格变化百分比；数据可用时返回 | 股票、期货、加密货币 | | trade\_session | string | 当前扩展交易时段：`pre_market`、`post_market` 或 `overnight` | 美股扩展交易时段 | | quote\_volume | string | 当前扩展交易时段成交额；数据可用时返回 | 美股扩展交易时段 | # A 股全量行情 Source: https://docs.tickdb.ai/zh-Hans/websocket/ticker_cn_stock A 股全量行情订阅；建立 WebSocket 连接时须协商 permessage-deflate 压缩。 ## 套餐权限 | 套餐 | 可用 | | ----- | :-: | | 免费版 | ❌ | | 基础版 | ❌ | | 专业版 | ❌ | | A 股全量 | ✅ | | 港股全量 | ❌ | | 美股全量 | ❌ | | 企业版 | ✅ | 订阅 CN\_Stock 后，先分批接收市场行情快照，再持续接收有变化的行情。 ## 开启 WebSocket 压缩 全量行情订阅必须在 WebSocket 握手阶段成功协商 `permessage-deflate`。这与 REST 接口使用的 `gzip`、`br`、`zstd` 不同，不能通过 `Accept-Encoding` 或订阅消息开启。 * 客户端必须在建立连接时启用 `permessage-deflate`。 * 压缩协商成功后，握手响应的 `Sec-WebSocket-Extensions` 中会包含 `permessage-deflate`。 * 未成功协商压缩时，全量订阅会返回错误码 `2008`；需要开启压缩并重新建立连接。 * 普通浏览器通常会自动协商 WebSocket 压缩；服务端程序应明确开启并检查协商结果。 ## 订阅消息 `universes` 指定一个或多个全市场标识，`channels` 固定传入 `ticker`。 ```json theme={null} { "cmd": "subscribe", "data": { "universes": ["CN_Stock"], "channels": ["ticker"] } } ``` 订阅成功后返回： ```json theme={null} { "cmd": "subscribe", "code": 0, "message": "universe subscription successful", "data": { "universes": ["CN_Stock"], "channels": ["ticker"] } } ``` ## JavaScript 示例 以下 Node.js 示例使用 `ws`，并在连接时明确开启 `permessage-deflate`： ```javascript theme={null} const WebSocket = require("ws"); const market = "CN_Stock"; const ws = new WebSocket( `wss://api.tickdb.ai/v1/realtime?api_key=${process.env.TICKDB_API_KEY}`, { perMessageDeflate: true }, ); ws.on("upgrade", (response) => { const extensions = response.headers["sec-websocket-extensions"] || ""; if (!extensions.includes("permessage-deflate")) { ws.close(); throw new Error("未成功协商 permessage-deflate 压缩"); } }); ws.on("open", () => { ws.send(JSON.stringify({ cmd: "subscribe", data: { universes: [market], channels: ["ticker"], }, })); }); ws.on("message", (raw) => { const message = JSON.parse(raw.toString()); if (Array.isArray(message)) { // 全量快照或增量更新，每个数组最多包含 500 条 ticker 消息 for (const item of message) { console.log(item.data.symbol, item.data.last_price); } return; } // 连接响应、订阅结果、错误或 pong console.log(message); }); ws.on("error", console.error); ``` ## 推送格式 全量行情以 JSON 数组分批推送，每个数组最多包含 500 条 `ticker` 消息： ```json theme={null} [ { "cmd": "ticker", "data": { "symbol": "600519.SH", "name": "贵州茅台", "type": "stock", "last_price": "1300", "timestamp": 1773292807000 } } ] ``` * 首次订阅会收到当前全量快照，快照可能分为多个数组依次发送。 * 完成初始快照后，只推送发生变化的行情，仍使用相同的数组格式。 * 行情字段与相应 REST 全量接口一致：[A 股全量行情](../rest/api_ticker_cn_stock)。 * 同一连接订阅某个市场的全量行情后，该市场已有的单个股票订阅会被取消，避免重复推送。 ## 取消订阅 ```json theme={null} { "cmd": "unsubscribe", "data": { "universes": ["CN_Stock"], "channels": ["ticker"] } } ``` ## 常见错误 | 错误码 | 说明 | | ------ | --------------------------------------- | | `2001` | `universes` 或 `channels` 参数格式错误。 | | `2002` | 全市场标识或频道不受支持。 | | `2008` | 连接未协商 `permessage-deflate`，需要开启压缩后重新连接。 | | `4005` | 当前 API Key 没有对应全量行情订阅权限。 | | `5003` | 对应市场的全量行情订阅暂不可用。 | # 港股全量行情 Source: https://docs.tickdb.ai/zh-Hans/websocket/ticker_hk_stock 港股全量行情订阅；建立 WebSocket 连接时须协商 permessage-deflate 压缩。 ## 套餐权限 | 套餐 | 可用 | | ----- | :-: | | 免费版 | ❌ | | 基础版 | ❌ | | 专业版 | ❌ | | A 股全量 | ❌ | | 港股全量 | ✅ | | 美股全量 | ❌ | | 企业版 | ✅ | 订阅 HK\_Stock 后，先分批接收市场行情快照，再持续接收有变化的行情。 ## 开启 WebSocket 压缩 全量行情订阅必须在 WebSocket 握手阶段成功协商 `permessage-deflate`。这与 REST 接口使用的 `gzip`、`br`、`zstd` 不同，不能通过 `Accept-Encoding` 或订阅消息开启。 * 客户端必须在建立连接时启用 `permessage-deflate`。 * 压缩协商成功后，握手响应的 `Sec-WebSocket-Extensions` 中会包含 `permessage-deflate`。 * 未成功协商压缩时，全量订阅会返回错误码 `2008`；需要开启压缩并重新建立连接。 * 普通浏览器通常会自动协商 WebSocket 压缩；服务端程序应明确开启并检查协商结果。 ## 订阅消息 `universes` 指定一个或多个全市场标识，`channels` 固定传入 `ticker`。 ```json theme={null} { "cmd": "subscribe", "data": { "universes": ["HK_Stock"], "channels": ["ticker"] } } ``` 订阅成功后返回： ```json theme={null} { "cmd": "subscribe", "code": 0, "message": "universe subscription successful", "data": { "universes": ["HK_Stock"], "channels": ["ticker"] } } ``` ## JavaScript 示例 以下 Node.js 示例使用 `ws`，并在连接时明确开启 `permessage-deflate`： ```javascript theme={null} const WebSocket = require("ws"); const market = "HK_Stock"; const ws = new WebSocket( `wss://api.tickdb.ai/v1/realtime?api_key=${process.env.TICKDB_API_KEY}`, { perMessageDeflate: true }, ); ws.on("upgrade", (response) => { const extensions = response.headers["sec-websocket-extensions"] || ""; if (!extensions.includes("permessage-deflate")) { ws.close(); throw new Error("未成功协商 permessage-deflate 压缩"); } }); ws.on("open", () => { ws.send(JSON.stringify({ cmd: "subscribe", data: { universes: [market], channels: ["ticker"], }, })); }); ws.on("message", (raw) => { const message = JSON.parse(raw.toString()); if (Array.isArray(message)) { // 全量快照或增量更新，每个数组最多包含 500 条 ticker 消息 for (const item of message) { console.log(item.data.symbol, item.data.last_price); } return; } // 连接响应、订阅结果、错误或 pong console.log(message); }); ws.on("error", console.error); ``` ## 推送格式 全量行情以 JSON 数组分批推送，每个数组最多包含 500 条 `ticker` 消息： ```json theme={null} [ { "cmd": "ticker", "data": { "symbol": "700", "name": "腾讯控股", "type": "stock", "last_price": "543", "timestamp": 1773292807000 } } ] ``` * 首次订阅会收到当前全量快照，快照可能分为多个数组依次发送。 * 完成初始快照后，只推送发生变化的行情，仍使用相同的数组格式。 * 行情字段与相应 REST 全量接口一致：[港股全量行情](../rest/api_ticker_hk_stock)。 * 同一连接订阅某个市场的全量行情后，该市场已有的单个股票订阅会被取消，避免重复推送。 ## 取消订阅 ```json theme={null} { "cmd": "unsubscribe", "data": { "universes": ["HK_Stock"], "channels": ["ticker"] } } ``` ## 常见错误 | 错误码 | 说明 | | ------ | --------------------------------------- | | `2001` | `universes` 或 `channels` 参数格式错误。 | | `2002` | 全市场标识或频道不受支持。 | | `2008` | 连接未协商 `permessage-deflate`，需要开启压缩后重新连接。 | | `4005` | 当前 API Key 没有对应全量行情订阅权限。 | | `5003` | 对应市场的全量行情订阅暂不可用。 | # 美股全量行情 Source: https://docs.tickdb.ai/zh-Hans/websocket/ticker_us_stock 美股全量行情订阅；建立 WebSocket 连接时须协商 permessage-deflate 压缩。 ## 套餐权限 | 套餐 | 可用 | | ----- | :-: | | 免费版 | ❌ | | 基础版 | ❌ | | 专业版 | ❌ | | A 股全量 | ❌ | | 港股全量 | ❌ | | 美股全量 | ✅ | | 企业版 | ✅ | 订阅 US\_Stock 后，先分批接收市场行情快照，再持续接收有变化的行情。 ## 开启 WebSocket 压缩 全量行情订阅必须在 WebSocket 握手阶段成功协商 `permessage-deflate`。这与 REST 接口使用的 `gzip`、`br`、`zstd` 不同，不能通过 `Accept-Encoding` 或订阅消息开启。 * 客户端必须在建立连接时启用 `permessage-deflate`。 * 压缩协商成功后，握手响应的 `Sec-WebSocket-Extensions` 中会包含 `permessage-deflate`。 * 未成功协商压缩时，全量订阅会返回错误码 `2008`；需要开启压缩并重新建立连接。 * 普通浏览器通常会自动协商 WebSocket 压缩；服务端程序应明确开启并检查协商结果。 ## 订阅消息 `universes` 指定一个或多个全市场标识，`channels` 固定传入 `ticker`。 ```json theme={null} { "cmd": "subscribe", "data": { "universes": ["US_Stock"], "channels": ["ticker"] } } ``` 订阅成功后返回： ```json theme={null} { "cmd": "subscribe", "code": 0, "message": "universe subscription successful", "data": { "universes": ["US_Stock"], "channels": ["ticker"] } } ``` ## JavaScript 示例 以下 Node.js 示例使用 `ws`，并在连接时明确开启 `permessage-deflate`： ```javascript theme={null} const WebSocket = require("ws"); const market = "US_Stock"; const ws = new WebSocket( `wss://api.tickdb.ai/v1/realtime?api_key=${process.env.TICKDB_API_KEY}`, { perMessageDeflate: true }, ); ws.on("upgrade", (response) => { const extensions = response.headers["sec-websocket-extensions"] || ""; if (!extensions.includes("permessage-deflate")) { ws.close(); throw new Error("未成功协商 permessage-deflate 压缩"); } }); ws.on("open", () => { ws.send(JSON.stringify({ cmd: "subscribe", data: { universes: [market], channels: ["ticker"], }, })); }); ws.on("message", (raw) => { const message = JSON.parse(raw.toString()); if (Array.isArray(message)) { // 全量快照或增量更新，每个数组最多包含 500 条 ticker 消息 for (const item of message) { console.log(item.data.symbol, item.data.last_price); } return; } // 连接响应、订阅结果、错误或 pong console.log(message); }); ws.on("error", console.error); ``` ## 推送格式 全量行情以 JSON 数组分批推送，每个数组最多包含 500 条 `ticker` 消息： ```json theme={null} [ { "cmd": "ticker", "data": { "symbol": "AAPL.US", "name": "Apple Inc.", "type": "stock", "last_price": "200", "timestamp": 1773292807000 } } ] ``` * 首次订阅会收到当前全量快照，快照可能分为多个数组依次发送。 * 完成初始快照后，只推送发生变化的行情，仍使用相同的数组格式。 * 行情字段与相应 REST 全量接口一致：[美股全量行情](../rest/api_ticker_us_stock)。 * 同一连接订阅某个市场的全量行情后，该市场已有的单个股票订阅会被取消，避免重复推送。 ## 取消订阅 ```json theme={null} { "cmd": "unsubscribe", "data": { "universes": ["US_Stock"], "channels": ["ticker"] } } ``` ## 常见错误 | 错误码 | 说明 | | ------ | --------------------------------------- | | `2001` | `universes` 或 `channels` 参数格式错误。 | | `2002` | 全市场标识或频道不受支持。 | | `2008` | 连接未协商 `permessage-deflate`，需要开启压缩后重新连接。 | | `4005` | 当前 API Key 没有对应全量行情订阅权限。 | | `5003` | 对应市场的全量行情订阅暂不可用。 | # 逐笔成交（Trade） Source: https://docs.tickdb.ai/zh-Hans/websocket/trade ## 套餐权限 | 套餐 | 可用 | | --------------- | :-: | | 免费版 | ❌ | | 基础版 | ✅ | | 专业版 | ✅ | | 全量套餐（A 股、港股、美股） | ✅ | | 企业版 | ✅ | ## 支持的市场 支持市场：美股、港股、A股、中国期货、香港期货、加密货币 ## 订阅 ```json theme={null} { "cmd": "subscribe", "data": { "channel": "trade", "symbols": ["700.HK", "BTCUSDT"] } } ``` > `type` 对本次订阅中的全部代码生效。混合订阅不同产品类型时请省略 `type`；仅在代码存在歧义时，按产品类型拆分订阅并传入对应值。 ## 取消订阅 ```json theme={null} { "cmd": "unsubscribe", "data": { "channel": "trade", "symbols": ["700.HK"] } } ``` ## 服务器响应 港股、美股和加密货币使用成交数组结构： ```json theme={null} { "cmd": "trade", "data": { "symbol": "700.HK", "type": "stock", "trades": [ { "id": "20950", "price": "553.000", "quantity": "100", "side": "buy", "timestamp": 1773371154000 } ] } } ``` A股、中国期货和香港期货每条消息推送一笔成交，字段直接位于 `data`。A股示例： ```json theme={null} { "cmd": "trade", "data": { "symbol": "600519.SH", "type": "stock", "price": "1252.48", "quantity": "7", "side": "sell", "timestamp": 1789958062000 } } ``` 香港期货还会返回成交 ID： ```json theme={null} { "cmd": "trade", "data": { "id": "7687812613106827271", "symbol": "HSI8888", "type": "futures", "price": "24907", "quantity": "1", "side": "buy", "timestamp": 1789958359020 } } ``` 中国期货还可能返回持仓变化信息： ```json theme={null} { "cmd": "trade", "data": { "symbol": "BU2609", "type": "futures", "price": "4309", "quantity": "1", "side": "sell", "timestamp": 1784012398000, "open_interest_change": 0, "position_effect": "short_transfer" } } ``` ### 字段说明 字段名中的 `24h` 不代表所有市场都按滚动 24 小时统计：加密货币通常采用滚动 24 小时，股票和期货通常采用当日或当前交易时段口径。除 `symbol`、`last_price`、`timestamp` 外，字段按产品类型和数据可用性返回。 | 字段 | 类型 | 描述 | | --------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | data.symbol | string | 交易品种 | | data.type | string | 产品类型 | | data.trades | array | 成交记录数组；港股、美股和加密货币返回 | | data.trades\[].id | string | 成交 ID | | data.trades\[].price | string | 成交价格 | | data.trades\[].quantity | string | 成交数量 | | data.trades\[].side | string | `buy`（买入）、`sell`（卖出）或 `neutral`（中性） | | data.trades\[].timestamp | int | 成交时间戳（毫秒） | | data.id | string | 成交 ID；香港期货返回 | | data.price | string | 单笔成交价格；A股、中国期货和香港期货返回 | | data.quantity | string | 单笔成交数量；A股、中国期货和香港期货返回 | | data.side | string | 单笔成交方向；A股、中国期货和香港期货返回 | | data.timestamp | int | 单笔成交时间戳（毫秒）；A股、中国期货和香港期货返回 | | data.open\_interest\_change | int \| null | 持仓变化；仅中国期货在数据可用时返回 | | data.position\_effect | string | 持仓影响；仅中国期货在数据可用时返回：`long_open`（多开）、`short_open`（空开）、`both_open`（双开）、`long_close`（多平）、`short_close`（空平）、`both_close`（双平）、`long_transfer`（多换）、`short_transfer`（空换） | # 最佳实践 Source: https://docs.tickdb.ai/zh-Hans/websocket/websocket_quickstart WebSocket 连接、压缩、心跳与断线重连。 TickDB WebSocket 地址为 `wss://api.tickdb.ai/v1/realtime`，建立连接时通过查询参数 `api_key` 传入密钥。不要把长期有效的 API Key 写入公开的前端代码或日志。 ## 连接管理 * **压缩**：全量行情订阅必须在握手时协商 `permessage-deflate`。Node.js 客户端应显式启用，并在连接建立后检查协商结果；普通浏览器通常会自动发起协商。`Accept-Encoding` 不是 WebSocket 压缩开关。 * **心跳**：客户端会自动回应服务端的 WebSocket 协议级 Ping，无需高频发送应用层消息。示例每 60 秒发送一次 `{"cmd":"ping"}`，用于客户端主动检查连接；20 秒内未收到 `pong` 时结束失活连接。 * **断线重连**：按下表分档等待，不加入随机延迟。达到最后一档后持续按该档间隔重连；连接成功后重置计数，下次断线重新从第一档开始。 * **恢复订阅**：每次重新建立连接后重新发送订阅消息；全量行情会再次发送初始快照。鉴权、权限或压缩配置错误应先修正，不应无限重试。 * **消息格式**：普通频道通常返回单条消息；全量行情以数组分批推送，每批最多 500 条 `ticker` 消息。 | 连续重连次数 | 每次等待 | | ------- | ---- | | 第 1～3 次 | 1 秒 | | 第 4～6 次 | 5 秒 | | 第 7 次起 | 30 秒 | 代码中的 `RECONNECT_STAGES` 把“等待时间”和“该档次数”配成一组；可按需要增减档位，最后一档使用 `Infinity` 表示一直按该间隔重连。 ## Node.js 示例 先安装 `ws`：`npm install ws`。设置环境变量 `TICKDB_API_KEY` 后运行以下代码；若还设置 `TICKDB_UNIVERSE=CN_Stock`、`HK_Stock` 或 `US_Stock`，则改为订阅对应市场的全量行情。示例中的 60 秒应用层心跳和 20 秒超时可按应用需要调整。 ```javascript theme={null} const WebSocket = require("ws"); const apiKey = process.env.TICKDB_API_KEY; const universe = process.env.TICKDB_UNIVERSE; if (!apiKey) throw new Error("Set TICKDB_API_KEY first"); if (universe && !["CN_Stock", "HK_Stock", "US_Stock"].includes(universe)) { throw new Error("Invalid TICKDB_UNIVERSE"); } let attempts = 0; let stopped = false; const RECONNECT_STAGES = new Map([ [1_000, 3], // 等待 1 秒，最多 3 次 [5_000, 3], // 等待 5 秒，最多 3 次 [30_000, Infinity] // 此后每次等待 30 秒 ]); function reconnectDelay(attempt) { for (const [delayMs, count] of RECONNECT_STAGES) { if (attempt <= count) return delayMs; attempt -= count; } } function connect() { const url = new URL("wss://api.tickdb.ai/v1/realtime"); url.searchParams.set("api_key", apiKey); const ws = new WebSocket(url, { perMessageDeflate: true }); let heartbeat; let pongTimeout; ws.on("unexpected-response", (_request, response) => { if ([401, 403].includes(response.statusCode)) stopped = true; console.error("WebSocket handshake failed:", response.statusCode); response.resume(); ws.terminate(); }); ws.on("open", () => { attempts = 0; if (universe && !ws.extensions.includes("permessage-deflate")) { stopped = true; console.error("Full-market subscriptions require permessage-deflate"); ws.close(); return; } const subscription = universe ? { cmd: "subscribe", data: { universes: [universe], channels: ["ticker"] } } : { cmd: "subscribe", data: { channel: "ticker", symbols: ["BTCUSDT"] } }; ws.send(JSON.stringify(subscription)); // 每次重连后重新订阅 heartbeat = setInterval(() => { if (ws.readyState !== WebSocket.OPEN || pongTimeout) return; ws.send(JSON.stringify({ cmd: "ping" })); pongTimeout = setTimeout(() => ws.terminate(), 20_000); }, 60_000); }); ws.on("message", (raw) => { let message; try { message = JSON.parse(raw.toString()); } catch { return; } for (const item of Array.isArray(message) ? message : [message]) { if (item.cmd === "pong") { clearTimeout(pongTimeout); pongTimeout = undefined; } else if (item.cmd === "ticker") { console.log(item.data.symbol, item.data.last_price); } else if (item.cmd === "error") { console.error("Subscription error:", item.code, item.message); if (["2008", "4005"].includes(String(item.code))) { stopped = true; ws.close(); } } } }); ws.on("error", (error) => console.error("WebSocket error:", error.message)); ws.on("close", () => { clearInterval(heartbeat); clearTimeout(pongTimeout); if (stopped) return; setTimeout(connect, reconnectDelay(++attempts)); }); } connect(); ``` 不同频道的订阅命令与响应字段，请直接查看 [实时行情](./ticker)、[盘口深度](./depth)、[逐笔成交](./trade) 和 [Ping](./ping) 页面。全量行情的压缩与推送格式见 [A 股](./ticker_cn_stock)、[港股](./ticker_hk_stock)和[美股](./ticker_us_stock)页面。