同花顺金融数据服务

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

通过统一 API Key，可以查询 A 股行情、集合竞价、财务报表、估值、指数与板块、公募基金、公开期货期权、特色数据及 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客户端已接入当前数据源，金融数据与分析能力已内置，打开客户端即可使用。

选择接入方式

Agent 和终端任务优先使用 CLI 及其内置 Skills；REST 文档与 HTTP 接口选路使用 hithink-finance，MCP 配置及工具调用使用 hithink-finance-mcp。

数据能力与边界

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

快速开始

1. 选择认证方式

CLI 默认推荐 OAuth：先运行 hithink-finance auth status --format json 复用当前有效凭据；首次登录使用 hithink-finance auth login --method oauth，按提示完成浏览器授权。

REST、MCP、Python 及 CLI 的 API Key 方式共用在 API Key 管理 获取的 Key。选择此方式后，Agent 可完成 Key 签发、安全交接、用户级持久配置和真实请求验证。具体流程见 API Key 创建与持久配置。

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

2. Agent Skill

按实际接入方式使用独立 Skill：

各自安装或分发时保留完整目录及 references/。MCP 契约按业务分类组织，每个工具保留包含参数、返回字段和关联结构的独立小节，可以独立使用。

CLI 配套领域 Skills 随 npm 包安装，并由 CLI 发布到用户级共享目录，再链接到已安装 Agent：

npm install -g @hithink-tech/hithink-finance-cli
hithink-finance skills status --format json

CLI 的业务请求由宿主按内置 Skill 的 description 直接选择领域。CLI 配套 Skills 的同步规则见 CLI 文档。

重新打开 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 的客户端。按七个数据域提供接入配置，连接后以实时 tools/list 确认可用工具：

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

{
  "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，不要猜测交易所或指数后缀。
• 历史行情结果应注明时间窗口和复权口径；财务结果应注明报告期。
• 离线文档、测试和帮助信息只能证明支持范围；线上可用性需要通过实际授权请求验证。
• 真实数据不可用时应说明原因，不使用近似数据、静态示例或模拟数据替代。
• 本项目提供金融数据访问和研究数据准备工具，不提供投资建议。

最新变化

• CLI 与 Python toolkit 新增涨停统计、个股机构与营业部记录、严重异动、竞价机会及 A 股和港股新股入口；热榜支持按条数查询。对应 REST/MCP 与 Agent Skill 契约同步更新。

项目对外可见的重要变化按时间倒序记录在 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/。REST 页面同步到 hithink-finance；MCP 工具按业务分类合并到 hithink-finance-mcp，每个工具小节包含参数、返回字段和关联结构。契约更新后从仓库根目录运行：

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 升级指南
• 更新日志

License

本仓库采用 MIT License。