同花顺金融数据服务

同花顺金融数据服务（hithink-finance） 是由同花顺官方提供和维护的 A 股金融数据服务，面向 AI Agent、量化研究者和应用开发者。

通过统一 API Key，可以查询 A 股行情、集合竞价、财务报表、估值、指数与板块、公募基金、公开期货期权和特色数据，并通过 REST API、MCP、CLI、Python SDK、本地 DuckDB 或 Agent Skill 接入现有工作流。

一站式同花顺官方金融数据能力，覆盖查询、研究、批量导出和 AI Agent 自动调用。

• 官网：https://fuyao.aicubes.cn/
• 在线文档：https://fuyao.aicubes.cn/docs/
• API Key 管理：https://fuyao.aicubes.cn/admin/
• 仓库文档中心：docs/
• 同花顺AI客户端：下载并体验

API、MCP、CLI、Python SDK 和 Agent Skill 适合自主接入；同花顺AI客户端已接入当前数据源，金融数据与分析能力已内置，打开客户端即可使用。

选择接入方式

不确定如何选择时，优先安装 hithink-finance Skill；如果希望直接在终端调用，优先使用 CLI。

数据能力与边界

当前公开方式不提供分钟 K、tick、Level-2、港股或美股行情、宏观数据、新闻公告原文、研报原文、基金申赎交易和投资推荐。标记为“端内专用”的能力已内置于同花顺AI客户端，不通过公开 API、MCP、CLI 或 Python SDK 提供。数据权限及实际可访问能力以官网和账号授权为准；请求未支持的数据时，不使用模拟数据或静态示例冒充真实结果。

快速开始

1. 获取统一 API Key

登录 同花顺金融数据服务官网，进入 API Key 管理 创建 Key。

API、MCP、CLI 和 Python 远端取数共用同一个 API Key。安装 hithink-finance Skill 后，具备本地浏览器操作能力的 Agent 可以在用户扫码一次后完成 Key 签发、安全交接、用户级环境变量、credentials.env、CLI 凭据库和真实请求验证；其他场景可按同一 runbook 逐步操作。具体流程见 首次登录、创建与持久配置。

用户可以直接把 API Key 提供给 Agent 上下文以便代配；Agent 不应复述，并应提示聊天平台可能保留消息记录。Key 不要写入代码、README、Issue、日志、产物或 Git；本地持久化优先使用用户级环境变量、用户级凭据文件、系统凭据库或客户端 Secret。

2. Agent Skill

hithink-finance Skill 是 AI Agent 使用本项目的统一入口，提供接入方式选择、标的消歧、按前端页面组织的 REST 契约、按业务域合并的 MCP 工具文档、安全规则和大结果落盘约定。

推荐通过公开仓库安装：

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

无网络条件下，可以从 Skill Hub 安装；也可以复制完整的 skills/hithink-finance/ 目录。复制时必须保留 references/。

重新打开 Agent 会话后即可直接描述需求：

查询贵州茅台的最新行情，并分析近一年的涨跌幅、最大回撤和均线趋势。

3. CLI

CLI 是人类终端、Agent 和自动化任务的默认推荐入口：

npm install -g @hithink-tech/hithink-finance-cli
hithink-finance auth login
hithink-finance capabilities --format json

常见命令：

# 根据代码或名称查找股票
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

# 初始化本地数据库
hithink-finance data init --format json

# 查询本地前复权日线
hithink-finance db query \
  --sql "SELECT * FROM v_daily_qfq LIMIT 10" \
  --format json

CLI 会为已检测到的 Agent 同步配套领域 Skills。支持目标、自定义目录、修复、移除和手工兜底安装方式见 CLI Skills 管理说明。

仅在参与仓库开发或 npm 暂不可用时从源码验证：

cd hithink-finance-cli
npm ci --ignore-scripts
npm run build
node dist/cli/main.js capabilities --format json

完整命令和生命周期说明见 hithink-finance-cli/README.md。

4. REST API

REST API 适合服务端、自定义语言和零依赖 HTTP 集成。以下示例查询贵州茅台最新行情：

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

• 仓库内契约：REST API 文档
• 在线文档：https://fuyao.aicubes.cn/docs/
• 文档全文聚合：https://fuyao.aicubes.cn/llms-full.txt

docs/api/ 按业务域提供单接口页与多接口模块页；字段、参数和错误语义以目标接口小节为准。

5. MCP

MCP 适合 Claude Desktop、Cursor、Windsurf 和其他支持 MCP 的客户端。当前提供六个托管服务：

单个服务的配置结构如下：

{
  "mcpServers": {
    "hithink-finance-a-share": {
      "type": "http",
      "url": "https://fuyao.aicubes.cn/mcp/a-share",
      "headers": {
        "X-api-key": "${HITHINK_FINANCE_API_KEY}"
      }
    }
  }
}

完整配置、安全方式、服务路由和验证步骤见 MCP 接入说明。实际调用或排查参数变化时，以当前连接返回的 tools/list 为准。

6. Python SDK 与 marketdb

安装 Python 子项目：

python -m pip install -e ./python

查询远端数据：

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

初始化并检查本地数据库：

python python/bootstrap.py
marketdb status --json --db data/market.duckdb
marketdb validate --json --db data/market.duckdb

更多说明：

• Python README
• toolkit 路由
• marketdb 文档
• Python 可执行示例

示例与灵感

examples/inspirations/ 提供可以复制使用的 Prompt、预览图和静态 HTML；python/examples/ 提供 SDK、marketdb 和远端数据组合示例。

单股行情与趋势速览

该示例组合展示最新行情、近一年日 K、均线、区间表现和最大回撤。

• 完整说明与 Prompt
• 直接打开静态 HTML

示例用于说明数据组合方式，不是数据能力契约、投资建议或固定视觉标准。

使用约束

• 本项目不设置累计调用次数上限，但调用方应避免短时间集中请求或使用过高并发；触发动态限流后应降低频率和并发度，并在适当延迟后重试。
• 全市场、分页全集、多标的或长时间窗口结果必须落盘，只在终端或对话中展示路径、行数、窗口和摘要。
• 首次使用名称或不完整代码时，应先检索并确认唯一 thscode，不要猜测交易所或指数后缀。
• 历史行情结果应注明时间窗口和复权口径；财务结果应注明报告期。
• 离线文档、测试和帮助信息只能证明支持范围；线上可用性需要通过实际授权请求验证。
• 真实数据不可用时应说明原因，不使用近似数据、静态示例或模拟数据替代。
• 本项目提供金融数据访问和研究数据准备工具，不提供投资建议。

最新变化

项目对外可见的重要变化按时间倒序记录在 CHANGELOG.md，避免在多个入口重复维护易过期的版本摘要。

旧版根级 Python 用户、脚本和 Agent Prompt 请先阅读 Monorepo 版本升级指南；本地数据库和数据文件不需要随代码目录迁移。

项目结构与参与开发

docs/                    公共文档中心；REST 与 MCP 契约和接入说明
skills/hithink-finance/  可独立安装的统一 Agent Skill；包含契约镜像
hithink-finance-cli/     Node.js CLI 子项目，运行时不依赖 Python
python/                  Python SDK、远端 toolkit、marketdb、示例和测试
examples/                monorepo 级示例导航和静态灵感
scripts/                 仓库级维护脚本

详细参数和契约下沉到对应子项目 README 或 docs/。docs/api/ 与 Skill 的 REST 文档均按单接口页和多接口模块页组织，接口可通过独立锚点定位；references/mcp/ 按业务域生成。references/mcp.md 维护接入与业务域入口。契约更新后从仓库根目录运行：

python scripts/sync_skill_contracts.py
python scripts/sync_skill_contracts.py --check
python -m pytest python/tests/

cd hithink-finance-cli
npm run verify

internal/ 和 sdd-docs/ 属于内部治理与开发记录，不是公开使用入口。

文档导航

• 文档中心
• REST API 契约
• MCP 接入说明
• CLI README
• Python README
• Python toolkit
• marketdb 文档
• Agent Skill
• Monorepo 升级指南
• 更新日志

Star History

License

本仓库采用 MIT License。