#同花顺金融数据服务

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

通过一个统一的 API Key，即可查询 A股最新行情、集合竞价、财务报表、估值、指数、板块、公募基金、公开期货期权资料与行情、涨跌停、炸板、个股异动、热榜和龙虎榜等数据，并将数据接入 AI 工具、Python 研究脚本、量化程序或业务系统。

一站式同花顺官方金融数据能力，覆盖 API、MCP、CLI、Python SDK、本地数据库和 Agent Skill。

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

当前请使用本项目的 API、MCP、CLI、Python SDK 和 Agent Skill 接入金融数据。同花顺AI客户端尚未发布接入本项目数据源的版本，后续版本计划接入，敬请期待。

---

#你可以用它做什么

• 查询一只或多只 A股的最新价格、涨跌幅、成交额等行情数据。
• 获取股票、指数和板块的历史 K 线，用于趋势分析和量化研究。
• 查询上市公司的利润表、资产负债表、现金流量表和财务指标。
• 批量查询 A 股最新市盈率、市净率、市销率和市现率估值快照。
• 获取交易日历、公司行动、复权因子等基础研究数据。
• 查询集合竞价快照、短期基准、涨跌停池、炸板池、连板天梯、个股异动、热榜和龙虎榜。
• 查询公募基金资料、公司、经理、财务、持仓、业绩、公开资讯以及 ETF/LOF 场内行情。
• 查询公开期货期权品种、合约、持仓、仓单、基差、日程、分时和日 K。
• 下载全市场数据，为回测、选股、因子研究和 AI 分析准备数据。
• 让 Claude、Cursor、Windsurf 等支持 MCP 或 Agent Skill 的工具直接调用金融数据。
• 在本地构建 DuckDB 数据库，完成增量同步、SQL 查询、复权计算和文件导出。

---

#30 秒了解

#这是什么

同花顺官方面向 AI Agent、量化研究和开发者提供的 A股金融数据服务。

#有什么数据

覆盖 A股行情、集合竞价、标的目录、公司行动、财务报表与指标、估值、交易日历、指数、板块、公募基金、公开期货期权、涨跌停、炸板、个股异动、热榜、龙虎榜和全市场数据文件。

#怎么使用

可以通过 REST API、托管 MCP、hithink-finance CLI、Python SDK、本地 marketdb 或统一 Agent Skill 接入。

#不知道选哪种方式

优先安装 hithink-finance Skill。Agent 会识别当前环境和任务，在 API、MCP、CLI 与 Python SDK 之间自动选择合适的能力。

---

#按使用场景选择接入方式

---

#数据能力概览

分钟 K、tick、海外行情、宏观数据、新闻公告原文和研报目前不在公开能力范围内。请求未支持的数据时，应明确说明，不使用模拟数据或静态示例冒充真实结果。

---

#快速开始

#1. 获取统一 API Key

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

API、MCP、CLI 和 Python 远端取数共用同一个 API Key。统一推荐保存为用户级环境变量 HITHINK_FINANCE_API_KEY；hithink-finance Skill 也能读取用户级 credentials.env，具体路径与各平台配置命令见 Skill 的 CLI 安装说明。

优先使用隐藏输入或环境变量。也可以把刚获取的 Key 交给 Agent 代为配置；Agent 不应复述 Key，并且只能写入用户级凭据来源，不能写入代码、日志、公开配置或 Git 仓库。

---

#2. 优先安装 hithink-finance Skill

Skill 是 Agent 使用本项目的统一说明书，包含：

• 接入方式选择；
• API、MCP、CLI 和 Python 快速路径；
• 股票名称与代码消歧规则；
• 完整 API 契约镜像；
• 安全与合规要求；
• 大结果落盘和上下文控制规范。

请选择一种安装方式：

1. 优先：通过 npx skills add 安装（推荐）

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

   通过该方式安装后，Skill 会在每个 Agent 会话第一次使用时默认静默检查并更新自身；同一会话不重复检查，无更新或失败时不打扰当前任务。设置 HITHINK_FINANCE_NO_SKILL_UPDATE=1 可关闭自动更新；安装目录与追踪哈希不一致时不会执行。新版本从下一次 Agent 会话开始生效。

2. 无网络条件：从 Skill Hub 安装

   将提示词发送给你的 AI 安装该 Skill：

   请根据 https://skillhub.cn/install/skillhub.md，安装 hithink-finance。
   

如无法使用以上安装方式，也可以把完整的 skills/hithink-finance/ 目录复制到 Agent 文档声明的 Skills 发现目录。

必须保留 references/，不要只复制 SKILL.md。

安装完成后重新打开会话，可以直接描述需求，例如：

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

获取沪深300当前成分股，并将结果保存为本地文件。

查询宁德时代最近四期利润表和主要盈利指标，注明报告期和数据来源。

---

#3. CLI：人类与 Agent 的默认推荐

CLI 将远端取数、本地数据库、认证、统一 JSON 输出和大结果落盘整合到一个命令入口。

优先从 npm 安装：

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

安装会无感地为本机已检测到的 Agent 同步 CLI 配套 Skills；后续 CLI 升级沿用已保存策略自动更新。默认各 Agent 通过目录链接共享一份内容，不会为未检测到的客户端创建目录。首次只指定部分目标时，在安装前设置环境变量：

$previous = $env:HITHINK_FINANCE_SKILLS_AGENTS
$env:HITHINK_FINANCE_SKILLS_AGENTS = 'codex,workbuddy'
try { npm install -g @hithink-tech/hithink-finance-cli } finally { $env:HITHINK_FINANCE_SKILLS_AGENTS = $previous }

后来新增 Agent 时直接追加，不会移除已有目标：

hithink-finance skills sync --agent claude-code --format json
hithink-finance skills status --format json

详细的支持目标、自定义目录、复制兼容模式、修复与移除规则见 CLI Skills 管理说明。

#CLI 配套 Skills 兜底安装

如果 npm 禁用了安装脚本，优先在 CLI 安装完成后运行 hithink-finance skills sync --repair --format json。如果 CLI 自动同步仍不可用，也可以只为实际使用的 Agent 安装 hithink-finance-cli/skills/ 下的 12 个领域 Skills：

npx skills add https://github.com/HiThink-Tech/Financial-API/tree/main/hithink-finance-cli/skills --skill '*' --agent codex --global --yes --full-depth

将 codex 替换为目标 Agent 的名称；需要多个 Agent 时重复传入 --agent。不要使用 --all，它会把 Skills 安装到该工具支持的全部 Agent 目录。

也可以 clone 仓库或下载 GitHub 源码压缩包，再把 hithink-finance-cli/skills/ 下每个 hithink-finance-* 完整目录直接复制到目标 Agent 的 Skills 发现目录。不要把外层 skills/ 整体嵌套进去，也不要只复制 SKILL.md；各 Skill 的 references/ 必须一并保留。常用 Agent 的目录映射及手工安装边界见 CLI 兜底安装说明。

通过 npx skills 或手工复制的内容不属于 CLI 生命周期托管范围。以后如需改回 hithink-finance skills sync 管理，应先移除这些手工副本，否则 CLI 会将同名目录视为用户内容并保留、报告冲突。

国内用户可使用 npmmirror 镜像加速：

npm install -g @hithink-tech/hithink-finance-cli --registry=https://registry.npmmirror.com

安装完成后验证：

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

• auth login：安全录入 API Key。
• capabilities：查看此版本 CLI 支持的机器可读能力目录。
• --format json：返回稳定、统一的 JSON 格式，方便程序或 Agent 继续处理。

通过 Skill 使用时，Agent 会先复用统一凭据，再通过 stdin 完成 CLI 登录；已有 CLI 凭据需要更新时使用 auth login --api-key-stdin --replace 原子替换，无需用户再次输入。CLI 仍将副本保存在自己的系统凭据库中，因此脱离 Skill 后也可独立使用。

常见命令：

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

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

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

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

完整说明见 hithink-finance-cli/README.md。

---

#4. REST API：适合业务系统和自定义开发

REST API 通过标准 HTTP 请求提供数据，适合：

• 接入网站、App 和后台服务；
• 使用 Java、Go、JavaScript、Python 等任意语言；
• 自定义数据获取和任务编排；
• 将金融数据嵌入已有业务流程。

使用 curl 查询贵州茅台最新行情：

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

仓库内 REST API 契约入口：

• REST API 文档
• 文档全文聚合：https://fuyao.aicubes.cn/llms-full.txt

docs/api/ 按业务域提供原子接口文档；正文从文档源同步，业务域首页帮助选择接口。端内能力在详情页标记并链接统一使用说明。

---

#5. MCP：最快接入 Chat Bot 和 IDE

MCP 适合 Claude Desktop、Cursor、Windsurf 和其他支持 MCP 的客户端。

将以下六个托管端点配置到客户端，并使用 hithink-finance-* 作为服务名称：

{
  "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}"
      }
    },
    "hithink-finance-futures": {
      "type": "http",
      "url": "https://fuyao.aicubes.cn/mcp/futures",
      "headers": {
        "X-api-key": "${HITHINK_FINANCE_API_KEY}"
      }
    },
    "hithink-finance-options": {
      "type": "http",
      "url": "https://fuyao.aicubes.cn/mcp/options",
      "headers": {
        "X-api-key": "${HITHINK_FINANCE_API_KEY}"
      }
    }
  }
}

六个服务分别覆盖：

• hithink-finance-a-share：A股行情、财务和特色数据；
• hithink-finance-a-share-index：指数、板块及相关行情；
• hithink-finance-meta：标的检索、能力发现等基础信息。
• hithink-finance-fund：基金资料、公司、经理、披露、财务、净值、收益、资讯、在线回测、通用指标、QDII 额度和场内行情。
• hithink-finance-futures：公开期货资料、持仓、仓单、基差、日程和行情。
• hithink-finance-options：公开期权品种、合约和行情。

配置位置、安全方式、意图路由和验证步骤见 MCP 接入说明。

Skill 已内置工具功能快照。只有在实际调用或排查参数变化时，才需要读取当前 MCP 连接的 tools/list。

---

#6. Python SDK：适合二次开发与量化研究

安装 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 子项目适合：

• Notebook 数据探索；
• 研究脚本；
• 定时取数；
• 自定义分页和重试策略；
• 与 pandas、NumPy、回测框架等工具组合；
• 将远端 API 数据与本地数据库数据一起使用。

完整说明：

• Python README
• toolkit 路由
• Python 可执行示例

---

#7. marketdb：在本地保存和研究历史数据

marketdb 会在本地构建 DuckDB 数据库，适合：

• 保存长期历史行情；
• 自动执行全量初始化和增量更新；
• 查询前复权、后复权和原始行情；
• 构建全市场研究面板；
• 使用 SQL 快速筛选数据；
• 将结果导出为文件；
• 检查和修复本地数据状态。

初始化：

python python/bootstrap.py

查看本地数据库状态：

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"

完整说明见 python/toolkit/marketdb/README.md。

---

#常见使用流程

#场景一：查询一只股票的最新行情

1. 用户提供股票名称或代码。
2. 先通过标的检索确认唯一 thscode。
3. 调用最新行情接口。
4. 返回价格、涨跌幅、成交数据、数据时间和来源。

推荐入口：CLI / API / MCP / Python。

---

#场景二：分析一只股票的历史趋势

1. 将股票名称或不完整代码转换为唯一 thscode。
2. 获取近一年或指定时间范围的历史日 K。
3. 计算区间涨跌幅、均线、波动和最大回撤。
4. 注明时间范围、复权口径、数据源和“非投资建议”。

推荐入口：CLI / marketdb / Python。

---

#场景三：查询上市公司财务数据

1. 确认股票代码。
2. 查询利润表、资产负债表或现金流量表。
3. 根据需求补充财务指标。
4. 明确报告期、数据发布日期和口径。

推荐入口：CLI / API / MCP / Python。

---

#场景四：准备量化研究数据

1. 判断数据范围是否属于全市场、多标的或多年历史数据。
2. 大规模结果使用 CLI 或 Market Dumps 落盘。
3. 使用 marketdb 构建和增量同步本地数据库。
4. 通过 SQL 或 Python 生成研究面板、因子数据和导出文件。

推荐入口：CLI / marketdb / Python。

---

#场景五：让 AI Agent 自动完成取数

1. 安装 hithink-finance Skill。
2. Agent 检测当前环境中可用的 API、MCP、CLI 和 Python 能力。
3. 根据数据新鲜度、任务规模和输出形式选择工具。
4. 对大结果自动落盘，仅在对话中返回路径、行数和摘要。
5. 真实数据不可用时明确报告原因，不使用模拟数据替代。

推荐入口：Skill。

---

#AI Agent 使用约定

进入仓库的 Agent 按以下顺序读取：

1. AGENTS.md
2. skills/hithink-finance/SKILL.md
3. 与实际接入方式对应的一个详细入口

执行时遵守以下规则：

• 用户只提供股票名称、简称或不完整代码时，先消歧为唯一 thscode，不要猜测交易所后缀。
• 最新、当天、财报、指数和特色数据优先使用远端能力。
• 本地已有且足够新的历史行情优先使用 DuckDB，减少重复下载。
• 全市场、多年、多标的或分页全集必须落盘，只在对话中返回文件路径、行数和摘要。
• 输出需要注明数据源、时间范围、报告期和复权口径。
• 真实数据不可用时明确说明原因，不使用模拟数据或静态示例冒充。
• 金融分析结果需要注明“非投资建议”。

---

#示例与灵感

#Python 可执行示例

python/examples/ 提供 SDK、marketdb 和远端数据组合示例。

#金融看板灵感

examples/inspirations/ 提供可以复制使用的 Prompt、预览图和静态 HTML。

#默认示例：单股行情与趋势速览

该示例从一只股票出发，组合展示：

• 最新行情；
• 近一年日 K；
• 均线；
• 区间表现；
• 最大回撤；
• 可以继续追问和探索的研究方向。

查看：

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

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

---

#当前公开能力边界

当前公开能力主要覆盖：

• A股最新行情快照；
• A股历史日 K；
• 标的目录；
• 公司行动与复权；
• 财务报表与指标；
• 交易日历；
• 指数与板块；
• 涨停、连板、异动、热榜和龙虎榜；
• 全市场日 K 与公司行动数据文件；
• 本地 DuckDB 数据同步和研究。

当前暂不公开提供：

• 分钟 K；
• tick 数据；
• 海外市场行情；
• 宏观经济数据；
• 新闻和公告原文；
• 研报原文。

数据权限和可访问 capability 以官网与账号授权为准。同花顺AI客户端尚未发布接入本项目数据源的版本；资金流向等更多数据与分析能力计划在后续版本接入，可前往同花顺AI客户端了解产品，敬请期待。

---

#调用频率与限流

本项目不设置累计调用次数上限。为保障服务稳定，请调用方根据实际业务需要合理安排请求，避免在短时间内集中发起大量请求或使用过高并发。

服务可能根据实际运行情况动态调整限流策略。如触发限流，请主动降低请求频率和并发度，并在适当延迟后重试。

---

#最新变化

当前 monorepo 版本包含五项关键变化，完整历史见 CHANGELOG.md。

#1. 扩展集合竞价、特色数据与公募基金能力

REST API、MCP、CLI 与 Python SDK 新增集合竞价快照/短期基准、跌停池、炸板池，以及 21 项基金公司、经理、业绩、财务、资讯、发行与历史持仓能力。

#2. 新增公募基金能力

REST API、MCP、CLI 与 Python SDK 统一支持基金资料、披露持仓、净值、区间收益、持有人结构、ETF/LOF 快照和 ETF 历史日线。

#3. 新增 hithink-finance Node.js CLI

统一提供：

• 远端数据查询；
• 本地 DuckDB；
• 稳定 JSON 输出；
• 能力发现；
• 环境诊断；
• 数据初始化、更新、校验和修复。

推荐直接从 npm 安装。

#4. 新增统一 hithink-finance Skill

原根目录中的通用、REST、MCP 和 CLI Setup Skills 已合并为一个可以独立安装的入口，统一覆盖：

• API；
• MCP；
• CLI；
• Python SDK；
• 安全与大结果处理规范。

#5. 仓库升级为 monorepo

Python 项目已迁入 python/。

旧版用户和 Agent 需要先按照 Monorepo 版本升级指南 更新：

• editable 安装路径；
• 脚本路径；
• CI 配置；
• Prompt 中的仓库路径。

本地数据库和 .env 不需要迁移。

---

#项目结构

docs/                    公共文档中心；按业务域组织 REST/MCP 原子文档
skills/hithink-finance/  可独立安装的统一 Agent Skill；包含契约镜像
hithink-finance-cli/     Node.js CLI 子项目，运行时不依赖 Python
python/                  唯一 Python 项目根
├── marketdb/            本地 DuckDB CLI 与 Python SDK
├── toolkit/fuyao/       远端数据 Python client 与脚本
├── toolkit/marketdb/    本地数据使用文档
├── examples/            Python 可执行示例
└── tests/               Python 测试
examples/                monorepo 级示例导航和静态灵感
scripts/                 仓库级维护脚本

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

---

#文档与契约治理

• 根 README 负责产品介绍、接入导航和完整能力总览。
• 详细参数下沉到对应子目录 README 或 docs/。
• docs/api/ 与 docs/mcp/ 的原子正文从文档源确定性同步；本项目维护业务分类与访问引导。
• skills/hithink-finance/references/api.md、references/api/、references/mcp.md 与 references/mcp/ 由 python scripts/sync_skill_contracts.py 生成，确保 Skill 独立发布时仍然自包含。
• Python 和 CLI 文档只维护各自的运行方式、命令和适配语义，不重复维护上游字段契约。
• 旧版迁移以 Monorepo 版本升级指南 为准。

---

#验证

在仓库根目录执行：

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

验证 Node.js CLI：

cd hithink-finance-cli
npm run verify

---

#安全与合规

• 所有远端方式共用 API Key。
• API Key 只能通过安全输入、用户级环境变量或凭据文件、stdin、系统凭据库或客户端 Secret 传入。
• 不要把 API Key 写入代码、README、Issue、Prompt、日志、产物或 Git commit。
• 全市场、多年、多标的等大结果必须落盘，避免终端、日志和 Agent 上下文泄露或膨胀。
• 不使用模拟数据、示例数据或静态内容冒充真实金融数据。
• 本项目提供金融数据访问和研究数据准备工具，不提供投资建议。
• 数据权限和可访问 capability 以官网与账号授权为准。

---

#文档导航

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

---

#Star History

---

#License

本仓库采用 MIT License。