同花顺金融数据 API 是同花顺面向 AI Agent、量化研究和开发者提供的结构化金融数据服务。平台通过 REST API、MCP Tools、官方 Agent Skill、Python/CLI toolkit、本地 marketdb 提供可编程消费的 A 股基础数据，并将逐步开放类似同花顺"涨停聚焦"的任务型数据能力，减少字段清洗、口径对齐、代码映射和数据拼接等处理成本。

• 官网：https://fuyao.aicubes.cn/
• 文档：https://fuyao.aicubes.cn/docs/
• API Key 管理：https://fuyao.aicubes.cn/admin/

• 服务定位：面向 AI Agent 与量化研究的结构化金融数据服务。
• 接入方式：REST API、MCP Tools、官方 Agent Skill、Python/CLI toolkit。
• 当前数据：A 股行情、代码表、公司行动、财务报表、交易日历、全市场数据导出。
• 本地能力：支持把全市场数据导入 DuckDB，使用 marketdb 做本地查询、研究和回测，并支持增量更新。
• Agent 能力：仓库提供官方 Skill，方便 Agent 按固定规则理解、选择并调用金融数据能力。

登录 同花顺金融数据 API 官网，在 API Key 管理 创建 API Key，然后携带 X-api-key 请求接口。

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

成功响应统一使用 ApiResponse 信封：

{
  "code": 0,
  "message": "success",
  "request_id": "a1b2c3d4",
  "data": {}
}

克隆本仓库后，安装依赖并配置 API Key：

python -m pip install -e .

# 推荐：拷贝 .env.example 为 .env，按需填入 API_KEY  等
cp .env.example .env

常用 命令：

# 标的检索
python toolkit/fuyao/scripts/fuyao.py tickers-search --q "贵州茅台"

# 实时行情快照
python toolkit/fuyao/scripts/fuyao.py prices-snapshot --thscodes 600519.SH

# 利润表
python toolkit/fuyao/scripts/fuyao.py financials-income --thscode 600519.SH --limit 4

Python 调用：

import sys
from pathlib import Path

sys.path.insert(0, str(Path("toolkit/fuyao/scripts").resolve()))

from fuyao_client import tickers_search, prices_snapshot

hit = tickers_search("贵州茅台", limit=1)[0]
snapshot = prices_snapshot([hit["thscode"]])

适用于历史研究、因子分析、回测和大批量 SQL 查询。

1. 从 全市场数据导出 下载 Parquet 文件。
2. 放入 refer-to/data/。
3. 执行初始化。

python bootstrap.py              # 完整初始化：安装 + .env + 建库 + 导入 + 校验
python bootstrap.py --no-import  # 只做安装与建库、跳过导入
python bootstrap.py --force      # 强制重新导入 Parquet

需要的文件（文件名末尾 YYYYMMDD 为快照日期，脚本自动选最新一份）：

• a_share_daily_k_1d_none_10y_<YYYYMMDD>.parquet：全市场 10 年日 K
• a_share_adjustment_factors_event_none_all_<YYYYMMDD>.parquet：复权事件

完成全量导入后，可进行增量更新：

export API_KEY="<your-api-key>"
marketdb update-daily --db data/market.duckdb

查询示例：

marketdb query --db data/market.duckdb \
  --sql "SELECT date, close FROM v_daily_qfq WHERE thscode = '600519.SH' ORDER BY date DESC LIMIT 10"

当你作为 AI Agent 使用本仓库时，按以下顺序读取：

Agent 调用约定：

• API Key 从环境变量 API_KEY 读取，不要写入代码、日志、对话或提交记录。
• 实时、当天、财报、标的目录等数据走 toolkit/fuyao/。
• 历史、大批量、回测类数据优先走 marketdb。
• 大批量、全市场、多年窗口结果不要直接输出到对话上下文；应落盘到 /tmp/*.json 或本地数据文件，只返回摘要和文件路径。
• MCP 客户端按 toolkit/fuyao/docs/mcp-config.md 配置。

更多市场、更多频率、更多任务型数据能力会在后续版本中持续增加。

marketdb/                Python 包：CLI + SDK + DuckDB 数据层
toolkit/                 工具无关 toolkit，适合人和 AI Agent 使用
├── marketdb/            本地 DuckDB 查询 toolkit
└── fuyao/               同花顺远端金融数据 API toolkit
skills/                  官方 Agent Skill
examples/                可运行端到端样例
refer-to/                API/MCP 文档、设计资料、market dumps 放置目录
feature/                 版本迭代工作区
tests/                   pytest 测试套件
bootstrap.py             跨平台一键初始化脚本（幂等）
pyproject.toml           Python 包定义
.env.example             环境变量样例

python -m pytest tests/

当前测试覆盖 schema、Parquet 导入、数据质量、复权因子和新鲜度守门等关键路径。

• API Key 只通过 API_KEY 环境变量形式传入。
• 不要把 API Key 写入代码、README、Issue、提示词或 Git commit。
• 本项目提供金融数据访问与本地分析工具，不提供投资建议。
• 数据权限、可访问 capability、调用频率与使用边界以同花顺金融数据 API 官网和账号授权为准。

• 同花顺金融数据 API 官网
• 快速开始
• API 参考
• 全市场数据导出
• toolkit/README.md
• toolkit/fuyao/README.md
• examples/README.md