🧭 核心功能与定位

Financial-API 是同花顺（HiThink）官方维护的 A股数据服务，旨在通过统一的 API Key，为开发者和 AI 系统提供标准化的金融数据访问能力。

覆盖的数据能力：

  • 行情数据：单只/多只股票的最新价格、涨跌幅、成交额，以及历史日 K 线。
  • 财务数据：上市公司的利润表、资产负债表、现金流量表及各类财务指标。
  • 估值数据：批量查询市盈率（PE）、市净率（PB）、市销率（PS）和市现率（PCF）。
  • 市场特色数据：集合竞价快照、涨跌停/炸板池、连板天梯、个股异动、热榜和龙虎榜。
  • 指数与板块：指数和板块的目录、成分股及其行情。
  • 公募基金：基金资料、公司、经理、财务、持仓、业绩、资讯及场内 ETF/LOF 行情。
  • 基础数据：交易日历、公司行动（分红/送转）、复权因子和标的目录。

接入方式：
数据可通过多种方式获取，以适应不同场景：

  • Agent Skill（推荐）：为 AI 助手提供统一接口，自动选择最佳调用方式。
  • REST API：标准 HTTP 接口，适合任何编程语言和系统集成。
  • MCP (Model Context Protocol)：适合 Claude Desktop、Cursor 等支持 MCP 的客户端。
  • CLI：终端命令行工具，适合批量查询和数据导出。
  • Python SDK：适合数据研究和二次开发。
  • marketdb：在本地构建 DuckDB 数据库，方便用 SQL 进行历史数据研究。

📦 快速开始

1. 获取 API Key

访问 同花顺金融数据服务官网，在 API Key 管理页面 创建你的专属 Key。建议将其设置为用户级环境变量 HITHINK_FINANCE_API_KEY。

2. 安装 Agent Skill（最推荐）

Skill 是 AI 代理使用本服务的说明书。在支持 npx 的环境中执行：

1
npx skills add HiThink-Tech/Financial-API --skill hithink-finance -g --yes

安装后，你可以在与 AI 助手的对话中直接提出需求，例如：

“查询贵州茅台的最新行情，并分析近一年的涨跌幅。”
“获取沪深300当前成分股，并将结果保存为本地文件。”

3. 使用 CLI（适合终端操作）

CLI 将所有数据能力和本地数据库整合到一个命令中。从 npm 全局安装：

1
npm install -g @hithink-tech/hithink-finance-cli

登录并验证：

1
2
hithink-finance auth login
hithink-finance capabilities --format json

常见查询示例：

1
2
3
4
5
6
7
8
# 搜索股票
hithink-finance symbol search --q 600519 --limit 5 --format json

# 查询最新行情
hithink-finance market snapshot --thscodes 600519.SH --format json

# 查询利润表
hithink-finance financials income --thscode 600519.SH --limit 4 --format json

4. 直接使用 REST API

通过 curl 调用，适合无 Node.js 环境的系统：

1
2
curl 'https://fuyao.aicubes.cn/api/a-share/prices/snapshot?thscodes=600519.SH' \
  -H 'X-api-key: <你的API_KEY>'

5. 使用 Python SDK

克隆仓库后在项目根目录安装：

1
python -m pip install -e ./python

然后通过脚本调用：

1
2
python python/toolkit/fuyao/scripts/fuyao.py tickers-search --q "贵州茅台"
python python/toolkit/fuyao/scripts/fuyao.py prices-snapshot --thscodes 600519.SH

⚙️ 高级配置：本地数据市场 (marketdb)

对于需要长期保存历史数据并进行复杂 SQL 分析的用户，项目提供了 marketdb 工具来构建本地 DuckDB 数据库。

  1. 初始化数据库：

    1
    python python/bootstrap.py

  2. 查看状态与查询：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    # 查看数据库状态
    marketdb status --json --db data/market.duckdb

    # 查询前复权日线数据
    marketdb query \
      --json \
      --db data/market.duckdb \
      --sql "SELECT date, close FROM v_daily_qfq
             WHERE thscode='600519.SH'
             ORDER BY date DESC LIMIT 10"

📋 配置 MCP 服务器

如果你使用支持 MCP 的客户端（如 Claude Desktop、Cursor），可以在其配置文件中加入以下托管端点（使用你的 API Key）：

1
2
3
4
5
6
7
8
9
10
{
  "mcpServers": {
    "hithink-finance-a-share": {
      "type": "http",
      "url": "https://fuyao.aicubes.cn/mcp/a-share",
      "headers": { "X-api-key": "${HITHINK_FINANCE_API_KEY}" }
    }
    // 可类似添加 -index, -meta, -fund 等端点
  }
}

❓ 常见注意事项

  • 数据权限：具体可访问的数据范围和调用频率以官网账号授权为准。
  • 数据时效性：实时行情和特色数据（如涨跌停）使用远端 API；历史数据建议使用本地 marketdb 缓存以提高效率。
  • 大结果处理：查询全市场或多年数据时，结果集可能很大。建议使用 CLI 或市场数据导出功能，将结果保存为文件，避免终端或 Agent 上下文过载。
  • 代码消歧：用户输入股票名称或简称时，务必先通过标的检索功能（symbol search）确认唯一的 thscode，不要猜测交易所后缀。
  • 安全规范：API Key 只能通过安全方式（环境变量、凭据文件）传递，绝不能写入代码、日志或提交到 Git 仓库。

总结

Financial-API 为 A股金融数据访问提供了官方、统一且灵活的解决方案。部署的核心是获取 API Key，然后根据你的工作场景选择最适合的接入方式：AI 用户优先安装 Skill；终端用户使用 CLI；开发者可集成 REST API 或 Python SDK；需要进行复杂历史数据分析则推荐使用 marketdb。请务必遵守其安全规范，并注意数据权限和结果集大小。