同花顺金融数据服务

同花顺金融数据服务（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/
• 仓库文档中心：docs/

---

你可以用它做什么

• 查询一只或多只 A股的最新价格、涨跌幅、成交额等行情数据。
• 获取股票、指数和板块的历史 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 之间自动选择合适的能力。

---

按使用场景选择接入方式

你的需求	推荐方式	说明
想让 AI Agent 自动查询金融数据	hithink-finance Skill	Agent 自动判断使用 API、MCP、CLI 或 Python SDK
想让 Claude、Cursor 等聊天工具快速接入	MCP	配置服务地址和 API Key 后即可在对话中调用
想在 Python、Notebook 中研究股票	Python toolkit/SDK	适合研究脚本、数据处理和自定义取数策略
想把数据接入网站、App 或公司系统	REST API	零依赖 HTTP 接入，适合任意编程语言和服务端系统
想通过终端批量查询、下载和导出数据	CLI	统一远端取数、本地数据库和结构化输出
想长期保存历史行情并用 SQL 研究	marketdb	在本地自动构建和维护 DuckDB 数据库
想获取全市场、长时间范围的大批量数据	CLI / Market Dumps	大结果落盘，避免终端和 Agent 上下文过载

---

数据能力概览

数据 / 能力	可以解决的问题	推荐入口
A股最新行情快照	查询单只、多只或全市场股票的最新价格与交易数据	CLI / API / MCP / Python
A股历史 K 线	获取股票历史走势，支持研究、回测和趋势分析	CLI / marketdb
公司行动与复权	查询分红、送转等公司行动，并生成前复权、后复权数据	CLI / marketdb
财务报表与财务指标	查询利润表、资产负债表、现金流量表和五类财务指标	CLI / API / MCP / Python
标的目录	根据股票名称、代码或关键词查找唯一 thscode	CLI / API / MCP / Python
交易日历	判断交易日、安排数据同步和回测时间	CLI / API / MCP / Python
指数与板块	查询指数和板块目录、成分股、行情及历史 K 线	CLI / API / MCP / Python
同花顺特色数据	获取涨停池、连板、异动、热榜和龙虎榜	CLI / API / MCP / Python
全市场数据导出	下载全量或增量日 K、公司行动等标准数据文件	CLI / Market Dumps
本地 DuckDB	完成数据初始化、同步、校验、修复、SQL 查询和导出	CLI / marketdb

分钟 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. 优先：从 Skill Hub 安装

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

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

2. 通过 Agent Skills 通用安装器安装

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

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

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

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

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

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

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

---

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

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

优先从 npm 安装：

npm install -g @hithink-tech/hithink-finance-cli
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/ 是仓库内唯一的上游 REST 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-a-share：A股行情、财务和特色数据；
• hithink-finance-a-share-index：指数、板块及相关行情；
• hithink-finance-meta：标的检索、能力发现等基础信息。

配置位置、安全方式、意图路由和验证步骤见 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 以官网与账号授权为准。

---

最新变化

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

1. 新增 hithink-finance Node.js CLI

统一提供：

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

推荐直接从 npm 安装。

2. 新增统一 hithink-finance Skill

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

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

3. 仓库升级为 monorepo

Python 项目已迁入 python/。

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

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

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

---

项目结构

docs/                    公共文档中心；docs/api 是上游 REST 契约唯一来源
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/ 是仓库内上游 REST API 契约的唯一来源。
• 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 以官网与账号授权为准。

---