Sakurasan
d5516b72d7
- vendor 同花顺官方 SDK 到 backend/sdk（含K线>10年自动切片、重试、拼音首字母检索兜底） - 新增 /api/v2 路由：行情/估值/财务/日历/指数/K线/标的检索 - 股票详情页K线改用 v2 同花顺接口（前复权日K+总手+按昨收涨跌幅） - 密钥仅后端持有，响应/日志无泄露 - 新增 run_local.sh 本地直接拉起（不再依赖 docker）
189 lines
9.1 KiB
Markdown
189 lines
9.1 KiB
Markdown
# 同花顺金融数据 API（HiThink Financial API）接口能力整理
|
||
|
||
> 数据源参考：https://github.com/HiThink-Tech/Financial-API · 文档：https://fuyao.aicubes.cn/docs/quickstart/
|
||
> 本文档整理官方 REST / MCP / CLI / Python / 本地库 各接入方式的能力清单，供后续开发评估使用。
|
||
|
||
## 一句话概览
|
||
|
||
同花顺官方维护的 **A 股金融数据服务**，面向 AI Agent、量化研究和应用开发者。
|
||
一个 API Key 即可访问数据，提供 **六种接入方式**：REST API、托管 MCP、Node.js CLI、Python SDK、
|
||
本地 DuckDB 数据库（marketdb）和 Agent Skill。MIT 许可，约 1.9k stars。
|
||
|
||
**支持**：A股股票、指数与板块、公募基金（含 ETF/LOF）、衍生特色数据（涨跌停/连板/异动/热榜/龙虎榜）、全市场数据导出。
|
||
**暂不支持**：期货、分钟K、tick、海外市场、宏观数据、新闻公告原文、研报原文。
|
||
|
||
---
|
||
|
||
## 认证与调用
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| Base URL | `https://fuyao.aicubes.cn` |
|
||
| 认证 | 请求头 `X-api-key: <your-key>`（与同花顺账号绑定） |
|
||
| Key 获取 | 官网注册 → 「API Key 管理」创建；关闭弹窗后无法再看完整 Key，需妥善保存 |
|
||
| 响应信封 | `{ code, message, request_id, data }`，`code=0` 表示成功（HTTP 恒为 200） |
|
||
| 环境变量 | `HITHINK_FINANCE_API_KEY` |
|
||
| 常见错误 | `2001` Key 缺失/无效；`2003` 无权限需开通 |
|
||
|
||
**Agent 集成（推荐）**：`npx skills add HiThink-Tech/Financial-API --skill hithink-finance -g --yes`
|
||
Agent 会在 API / MCP / CLI / Python 间自动选择合适方式，并对大结果自动落盘。
|
||
|
||
---
|
||
|
||
## 接入方式一览
|
||
|
||
| 方式 | 说明 |
|
||
|------|------|
|
||
| **REST API** | `GET` + `X-api-key`，最通用 |
|
||
| **MCP** | 4 个服务端点，供 AI Agent 直接调用 |
|
||
| **Node.js CLI** | npm 包 `@hithink-tech/hithink-finance-cli` |
|
||
| **Python SDK** | `pip install -e ./python` |
|
||
| **本地 DuckDB** | `marketdb` 本地库，支持增量同步 + SQL + 复权 |
|
||
| **Agent Skill** | 一键安装，自动选择最优接入 |
|
||
|
||
---
|
||
|
||
## REST API 能力清单（GET + X-api-key）
|
||
|
||
### 基础 / 元信息
|
||
|
||
| 接口路径 | 功能 | 主要参数 |
|
||
|----------|------|---------|
|
||
| `/api/meta/tickers/search` | 跨市场标的检索（代码/名称/拼音） | `q`*、`exchange`、`asset_type`、`limit`(≤50) |
|
||
| `/api/meta/tickers/list` | 分页获取代码表 | `asset_type`、`limit`(≤10000)、`offset` |
|
||
|
||
### A股行情
|
||
|
||
| 接口路径 | 功能 | 主要参数 |
|
||
|----------|------|---------|
|
||
| `/api/a-share/prices/snapshot` | 行情快照（单只/多只/全市场） | `thscodes`、`limit`、`offset` |
|
||
| `/api/a-share/prices/historical` | 单只标的日K（窗口≤10年） | `thscode`*、`interval`(1d)、`start`*、`end`*、`adjust`(none/forward/backward)、`offset` |
|
||
| `/api/a-share/auction/snapshot` | 集合竞价快照 | `thscodes`*、`stage`(live/final) |
|
||
| `/api/a-share/auction/short-term-benchmark` | 短线风向标竞价基准 | `date`(yyyy-MM-dd) |
|
||
| `/api/a-share/calendar/trading-days` | 近一年交易日序列 | 无 |
|
||
|
||
### A股财务 / 复权 / 估值
|
||
|
||
| 接口路径 | 功能 | 主要参数 |
|
||
|----------|------|---------|
|
||
| `/api/a-share/financials/income-statements` | 合并利润表多期序列 | `thscode`*、`period`(annual/quarterly)*、`limit`(1-20) 或 `start`+`end` |
|
||
| `/api/a-share/financials/balance-sheets` | 合并资产负债表 | 同上 |
|
||
| `/api/a-share/financials/cash-flow-statements` | 合并现金流量表 | 同上 |
|
||
| `/api/a-share/financials/indicators` | 五类财务指标 | `thscode`*、`report`*(yyyy-1~yyyy-4) |
|
||
| `/api/a-share/corporate-actions/adjustment-factors` | 分红/送股/配股事件流 | `thscode`*、`from`、`to` |
|
||
| `/api/a-share/valuations/snapshot` | 估值快照（PE TTM/MRQ、PB、PS、PCF） | 批量查询 |
|
||
|
||
### 指数与板块
|
||
|
||
| 接口路径 | 功能 | 主要参数 |
|
||
|----------|------|---------|
|
||
| `/api/a-share-index/catalog/ths-index-list` | 同花顺指数清单 | `tag`(cn_concept/region/tszs/industry) |
|
||
| `/api/a-share-index/constituents/ths-stock-list` | 指数成分股 | `thscode`* |
|
||
| `/api/a-share-index/prices/snapshot` | 指数行情快照 | `thscodes`* |
|
||
| `/api/a-share-index/prices/historical` | 指数历史K线（无复权参数） | `thscode`*、`interval`、`start`*、`end`* |
|
||
|
||
### 特色数据（`/api/a-share/special-data/…`）
|
||
|
||
| 接口路径后缀 | 功能 |
|
||
|------|------|
|
||
| `limit-up-pool` | 涨停池（涨停/连板股） |
|
||
| `limit-down-pool` | 跌停池 |
|
||
| `limit-break-pool` | 涨停炸板池 |
|
||
| `limit-up-ladder` | 近30日连板天梯 |
|
||
| `skyrocket-list` | 热度飙升榜 Top30（日榜/小时榜） |
|
||
| `hot-stock-list` | A股热股榜 Top30（24h/小时） |
|
||
| `hot-stock-list-history` | 按自然日历史热股排行 |
|
||
| `hot-stock-rank-trend` | 单股热榜排名走势 |
|
||
| `anomaly-analysis-list` | 当日个股异动原因列表（`tag_codes` 如 `LIMIT_UP,SHARP_FALL`）※仅 REST |
|
||
| `anomaly-analysis-stock` | 按股票批量查异动原因（`thscodes`* ≤50） |
|
||
| `dragon-tiger-list` | 龙虎榜（`board_type` all/org/hot_money、`date`） |
|
||
|
||
### 公募基金（21 项，仅列核心）
|
||
|
||
| 接口路径 | 功能 |
|
||
|----------|------|
|
||
| `/api/fund/profile/**` | 基金基本资料 |
|
||
| `/api/fund/portfolio/holdings` | 定期披露重仓持仓 |
|
||
| `/api/fund/performance/nav` / `returns` / `indicators-historical` | 净值 / 区间收益与同类排名 / 历史业绩指标 |
|
||
| `/api/fund/holders/detail` / `top` | 持有人结构 / 前十大持有人 |
|
||
| `/api/fund/corporate-actions/dividends` | 基金分红记录 |
|
||
| `/api/fund/managers/investment-style` / `performance` / `experience` / `detail` | 经理投资风格 / 业绩 / 经历 / 详情 |
|
||
| `/api/fund/companies/detail` | 基金公司详情 |
|
||
| `/api/fund/diagnostics/detail` | 基金诊断 |
|
||
| `/api/fund/offerings/list` | 新发基金募集列表 |
|
||
| `/api/fund/news/article-list` | 基金资讯（游标分页） |
|
||
| `/api/fund/financials/indicators` / `income-statements` / `balance-sheets` | 基金财务指标 / 利润表 / 资产负债表 |
|
||
| `/api/fund/market/snapshot` / `historical` | ETF 行情快照 / 历史日线（窗口≤5年） |
|
||
|
||
### 全市场数据导出（Market Dumps）
|
||
|
||
| 接口路径 | 功能 |
|
||
|----------|------|
|
||
| `/api/dump/market-dumps/daily-k/download-url` | 全市场 10 年日K Parquet 下载链接 |
|
||
| `/api/dump/market-dumps/daily-k-10d/download-url` | 最近 10 交易日日K Parquet |
|
||
| `/api/dump/market-dumps/adjustment-factors/download-url` | 全量复权因子 Parquet |
|
||
|
||
---
|
||
|
||
## MCP 服务端点（4 个）
|
||
|
||
| 服务 | 端点 |
|
||
|------|------|
|
||
| `hithink-finance-a-share` | `/mcp/a-share` |
|
||
| `hithink-finance-a-share-index` | `/mcp/a-share-index` |
|
||
| `hithink-finance-meta` | `/mcp/meta` |
|
||
| `hithink-finance-fund` | `/mcp/fund` |
|
||
|
||
鉴权：环境变量 `API_KEY` 注入，与 REST 同一 Key。
|
||
|
||
---
|
||
|
||
## CLI（`@hithink-tech/hithink-finance-cli`）
|
||
|
||
| 命令 | 功能 |
|
||
|------|------|
|
||
| `auth login` | 录入 API Key |
|
||
| `capabilities` | 能力目录 |
|
||
| `symbol search --q <代码>` | 标的检索 |
|
||
| `market snapshot --thscodes 600519.SH` | 行情快照 |
|
||
| `financials income --thscode ... --limit 4` | 利润表 |
|
||
| `data init` / `db query --sql "..."` | 初始化本地库 / SQL 查询（视图如 `v_daily_qfq`） |
|
||
|
||
---
|
||
|
||
## Python SDK 与本地 DuckDB
|
||
|
||
```bash
|
||
pip install -e ./python
|
||
python python/bootstrap.py # 初始化本地 DuckDB（marketdb）
|
||
```
|
||
|
||
常用脚本：`fuyao.py tickers-search --q "贵州茅台"`、`fuyao.py prices-snapshot ...`
|
||
marketdb 支持增量同步、SQL 查询、复权计算、数据导出。
|
||
|
||
---
|
||
|
||
## 合规要求
|
||
|
||
- 输出需注明数据源、时间范围与复权口径，标注"非投资建议"
|
||
- 真实数据不可用时不得用模拟数据冒充
|
||
- API Key 不可写入代码、日志或 Git 仓库
|
||
|
||
---
|
||
|
||
## 与我们现有系统的潜在结合点（供后续评估）
|
||
|
||
> 现有数据源依赖腾讯/东方财富/新浪/AkShare，均为非官方抓取，存在限流与反爬问题。
|
||
> 同花顺官方 API 可作**更稳定、结构化的权威数据源**，或补充新能力。
|
||
|
||
| 现有模块 | 同花顺对应能力 | 潜在价值 |
|
||
|----------|--------------|---------|
|
||
| 实时行情 `/api/stock/quote`（腾讯） | `a-share/prices/snapshot` | 官方行情快照，避免腾讯兼容性/抓取风险 |
|
||
| 历史K线 `/api/stock/history`（东财/腾讯） | `a-share/prices/historical`（10年、复权可选） | 权威日K + 明确复权口径，替代被反爬的东财 kline |
|
||
| 财务指标 `/api/stock/financial`（东财） | `a-share/financials/*` + `valuations/snapshot` | 官方三大报表、五类指标、估值快照 |
|
||
| 题材热点 / 热点穿透（东财） | `a-share/special-data/*` 热榜、涨停池、连板天梯 | 官方热榜/涨停/连板数据，可增强题材热度判断 |
|
||
| 核心股追踪 / 每日采集 | `a-share/special-data/dragon-tiger-list`、`hot-stock-*` | 龙虎榜、热股榜可作为核心股采样的补充来源 |
|
||
| 新增能力 | `a-share-index/*`（指数/板块成分）、`fund/*`（基金）、Market Dumps（全市场导出） | 指数行情、基金筛选、本地 marketdb 全市场回测 |
|
||
|
||
> 注意：特色数据（涨停池等）tag_codes 语义、thscode 与现有 code 体系的映射，接入前需先做字段对齐验证。
|