169 lines
7.1 KiB
Markdown
169 lines
7.1 KiB
Markdown
# 同花顺金融数据服务（hithink-finance）接入指南
|
||
|
||
> 同花顺官方 A 股金融数据服务，一个 API Key 打通行情/财报/估值/特色数据。
|
||
> 官网：https://fuyao.aicubes.cn ｜ GitHub：https://github.com/HiThink-Tech/Financial-API（开源工具链）
|
||
> 更新：2026-08-22 ｜ 状态：✅ 已实测可用（沙箱已配置）
|
||
|
||
## 1. 概述
|
||
|
||
面向 AI Agent、量化研究和应用开发的 A 股数据服务，覆盖：
|
||
|
||
- **行情**：实时快照、历史 K 线、复权因子、公司行动、交易日历
|
||
- **财务**：利润表、资产负债表、现金流量表、财务指标
|
||
- **估值**：市盈率 TTM/MRQ、市净率、市销率、市现率
|
||
- **特色数据**：集合竞价、涨跌停池、炸板池、连板天梯、个股异动、热榜、龙虎榜
|
||
- **指数/板块**：目录、成分股、行情、历史 K 线
|
||
- **公募基金**：资料、公司、经理、财务、持仓、净值、业绩、场内行情
|
||
- **全市场导出**：全量/增量日 K、公司行动等标准数据文件
|
||
|
||
**明确不覆盖**：分钟 K、tick、海外行情、宏观数据、新闻公告原文、研报。
|
||
（请求未支持的数据时明确说明，不得用模拟数据冒充。）
|
||
|
||
## 2. API Key
|
||
|
||
- 申请：https://fuyao.aicubes.cn/admin/ 一键签发
|
||
- 统一环境变量：`HITHINK_FINANCE_API_KEY`（API / MCP / CLI / Python 共用一把 Key）
|
||
- **安全要求**：Key 只写入用户级凭据来源（credentials.env / CLI 凭据库），
|
||
**严禁**写入代码、日志、公开配置或 Git 仓库；Agent 不得复述 Key。
|
||
|
||
家庭环境现状（2026-08-22 已配好）：
|
||
- 沙箱（小五所在环境）：`~/.openclaw/credentials.env`（600 权限）+ CLI 凭据库
|
||
- 小强如需独立使用：向爸爸要 Key，按 4.1 节 `auth login` 配置自己的凭据
|
||
|
||
## 3. 接入方式速览
|
||
|
||
| 场景 | 推荐方式 |
|
||
|------|---------|
|
||
| Agent 自动查数 | hithink-finance Skill（npx skills add HiThink-Tech/Financial-API --skill hithink-finance -g --yes） |
|
||
| Claude/Cursor 对话查数 | MCP（4 个托管端点，见 4.4） |
|
||
| Python/Notebook 研究 | Python SDK（见 4.3） |
|
||
| 网站/App/后端接入 | REST API（见 4.5） |
|
||
| 终端批量查询/导出 | CLI（见 4.1） |
|
||
| 本地长期保存 + SQL 研究 | marketdb / 本地 DuckDB（见 4.2） |
|
||
|
||
## 4. 详细接入
|
||
|
||
### 4.1 CLI（沙箱已装 ✅）
|
||
|
||
```bash
|
||
npm install -g @hithink-tech/hithink-finance-cli --registry=https://registry.npmmirror.com
|
||
hithink-finance auth login # 录入 API Key（--api-key-stdin 支持 stdin）
|
||
hithink-finance capabilities --format json # 查看本版本能力目录
|
||
```
|
||
|
||
常用命令（全部支持 `--format json` 稳定输出）：
|
||
|
||
```bash
|
||
# 按代码/名称/关键词找标的（返回唯一 thscode）
|
||
hithink-finance symbol search --q 600519 --limit 5 --format json
|
||
|
||
# 最新行情快照（单只/多只/全市场）
|
||
hithink-finance market snapshot --thscodes 600519.SH --format json
|
||
|
||
# 历史 K 线
|
||
hithink-finance market history --thscode 600519.SH --kline daily --limit 30 --format json
|
||
|
||
# 财务报表（最近 N 期）
|
||
hithink-finance financials income --thscode 600519.SH --limit 4 --format json
|
||
|
||
# 初始化本地 DuckDB（回测数据库）
|
||
hithink-finance data init --format json
|
||
|
||
# SQL 查询本地前复权日线
|
||
hithink-finance db query --sql "SELECT * FROM v_daily_qfq LIMIT 10" --format json
|
||
```
|
||
|
||
> 具体命令/参数以 `hithink-finance capabilities --format json` 返回的机器可读能力目录为准。
|
||
|
||
### 4.2 本地 DuckDB（marketdb）—— 回测数据方案
|
||
|
||
```bash
|
||
hithink-finance data init # 初始化本地库
|
||
hithink-finance data sync # 增量同步（可定时）
|
||
hithink-finance db query --sql "SELECT ..." --format json # 只读 SQL
|
||
# 导出：data export / dump 相关命令（见 capabilities）
|
||
```
|
||
|
||
适合：长期保存历史行情、复权计算、SQL 因子研究、回测数据集。
|
||
替代/互补现有 quantitative_data 的 Tushare 导入链路（importer.py / incremental_import.py）。
|
||
|
||
### 4.3 Python SDK
|
||
|
||
```bash
|
||
git clone https://github.com/HiThink-Tech/Financial-API
|
||
cd Financial-API && pip install -e ./python
|
||
```
|
||
|
||
```bash
|
||
python python/toolkit/fuyao/scripts/fuyao.py tickers-search --q "贵州茅台"
|
||
python python/toolkit/fuyao/scripts/fuyao.py prices-snapshot --thscodes 600519.SH
|
||
```
|
||
|
||
### 4.4 MCP（Claude Desktop / Cursor / Windsurf）
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"hithink-finance-a-share": {
|
||
"type": "http",
|
||
"url": "https://fuyao.aicubes.cn/mcp/a-share",
|
||
"headers": { "X-api-key": "${HITHINK_FINANCE_API_KEY}" }
|
||
},
|
||
"hithink-finance-a-share-index": {
|
||
"type": "http",
|
||
"url": "https://fuyao.aicubes.cn/mcp/a-share-index",
|
||
"headers": { "X-api-key": "${HITHINK_FINANCE_API_KEY}" }
|
||
},
|
||
"hithink-finance-meta": {
|
||
"type": "http",
|
||
"url": "https://fuyao.aicubes.cn/mcp/meta",
|
||
"headers": { "X-api-key": "${HITHINK_FINANCE_API_KEY}" }
|
||
},
|
||
"hithink-finance-fund": {
|
||
"type": "http",
|
||
"url": "https://fuyao.aicubes.cn/mcp/fund",
|
||
"headers": { "X-api-key": "${HITHINK_FINANCE_API_KEY}" }
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.5 REST API
|
||
|
||
- Base：`https://fuyao.aicubes.cn`，鉴权 Header：`X-api-key`
|
||
- 统一 ApiResponse 信封：业务结果（含错误）HTTP 200 返回，用 `code` 字段分发
|
||
- 路径风格：`/api/<标的宇宙>/<数据类型>/<动作>`，如 `/api/a-share/prices/snapshot`
|
||
- snake_case 字段、显式 currency、毫秒级 Unix 时间戳（LLM-friendly）
|
||
- 完整契约：https://fuyao.aicubes.cn/llms-full.txt ｜ 仓库 docs/api/
|
||
|
||
```bash
|
||
curl 'https://fuyao.aicubes.cn/api/a-share/prices/snapshot?thscodes=600519.SH' \
|
||
-H "X-api-key: $HITHINK_FINANCE_API_KEY"
|
||
```
|
||
|
||
## 5. 与小强现有架构的衔接建议
|
||
|
||
1. **回测数据**：用 marketdb 本地 DuckDB 替代/补充 Tushare 日线导入（现有 importer.py 继续保留，两者可交叉校验）
|
||
2. **实时因子**：行情快照 API 做实时打分；涨跌停池/炸板池/连板天梯做情绪与事件因子
|
||
3. **龙虎榜/异动/热榜**：事件驱动策略的增量数据源（Tushare 免费版这些覆盖弱）
|
||
4. **财报/估值**：`financials` + `valuation` 命令批量拉全市场，喂多因子模型
|
||
5. **全市场导出**：需要全量数据做研究时用 CLI Market Dumps，大结果落盘，避免上下文过载
|
||
|
||
## 6. 实测验证记录（2026-08-22）
|
||
|
||
```json
|
||
{"thscode":"600519.SH","ticker":"600519","volume":3347231,"turnover":4278311000,
|
||
"last_price":1272.83,"price_change":-18.67,"price_change_ratio_pct":-1.445606,
|
||
"open_price":1291.5,"high_price":1291.5,"low_price":1272.01,"prev_price":1291.5}
|
||
```
|
||
|
||
- ✅ auth login：`{"ok":true,"method":"api-key","configured":true}`
|
||
- ✅ capabilities：symbol.search / market.snapshot / market.history / financials.* 等全量可用
|
||
- ✅ 查询：贵州茅台 600519.SH 实时快照正常返回（周六休市=周五收盘数据）
|
||
|
||
## 7. 安全与合规提醒
|
||
|
||
- API Key 只存用户级凭据；不进代码、日志、公开配置、Git 仓库
|
||
- Agent 交互时不得复述 Key；配置 Key 用 stdin 或环境变量
|
||
- 数据仅用于研究/回测用途，遵守同花顺服务条款；不支持也不应伪造范围外数据（分钟K/tick/海外等）
|