# 同花顺金融数据服务（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/海外等）