API 参考
同花顺金融数据API 以一套 REST 接口对外提供能力，并同时通过 MCP Tools 暴露给 AI Agent 工具链。
两种调用方式共享同一套后端 capability，数据语义完全一致。所有业务响应（含错误）统一返回 HTTP 200，
业务结果经响应信封的 code 字段表达。
接口分组
| 分组 | 路径前缀 | 说明 |
|---|---|---|
| 价格数据 (prices) | /api/a-share/prices | A 股行情快照与历史 K 线。 |
| 全市场数据导出 (market-dumps) | /dump/market-dumps | 价格数据子模块：A 股全市场 10 年日 K、最近 10 交易日日 K 与复权因子 Parquet 文件下载链接。 |
| 标的检索 | /api/meta/tickers/search | 按 thscode / ticker / 名称检索 A 股、指数与基金标的。 |
| 标的列表获取 | /api/meta/tickers/list | 按规范化资产类型分页获取代码表。 |
| 基金 | /api/fund | 基金资料、重仓股、净值、收益、持有人结构与行情数据。 |
| 除复权 (corporate-actions) | /api/a-share/corporate-actions | A 股复权因子事件流（分红 / 送股 / 配股）。 |
| 财务报表 (financials) | /api/a-share/financials | A 股整体合并利润表 / 资产负债表 / 现金流量表多期序列。 |
| 财务指标数据 | /api/a-share/financials/indicators | A 股成长、盈利、偿债、营运、现金流五类财务指标。 |
| 交易日历 (calendar) | /api/a-share/calendar | A 股近一年交易日序列（含毫秒戳与 yyyyMMdd）。 |
| 特色数据 (special-data) | /api/a-share/special-data | A 股涨跌停数据、同花顺热榜、个股异动原因与龙虎榜。 |
| 同花顺指数列表和成分股 (a-share-index) | /api/a-share-index | 同花顺指数列表与成分股清单（同时支持沪深 300 等标准指数）。 |
通用约定
- Base URL：
https://fuyao.aicubes.cn。 - 必需请求头：
X-api-key: <your-api-key>，缺失或无效返回code=2001；API Key 无权访问该 capability 返回code=2003。 - 实体标识统一使用
thscode（如600519.SH），不接受纯代码ticker（如600519）。 - 时间戳字段统一为毫秒级 Unix 时间戳（
long），时区按Asia/Shanghai。
响应信封
所有接口返回统一的 ApiResponse 信封：
{
"code": 0,
"message": "success",
"request_id": "a1b2c3d4e5f6789012345678abcdef01",
"data": {
"timestamp": 1716105600000,
"item": [ ]
}
}
| 字段 | 类型 | 说明 |
|---|---|---|
code | integer | 业务结果码，0 表示成功，非 0 表示业务错误。 |
message | string | 结果描述。 |
request_id | string | 请求追踪 ID。 |
data | object | null | 业务数据容器，按接口而定；错误时固定保留，可能为 null。 |
data.timestamp | long | 数据时间戳（毫秒）。 |
data.item | array | 业务数据列表。 |
错误码
| code | 含义 | 典型场景 |
|---|---|---|
0 | 成功 | - |
1001 | 缺少必填参数 | start / end / q / thscode 漏传。 |
1002 | 参数格式错误 | thscode 含逗号，或日期格式错误。 |
1003 | 参数取值越界 | 枚举非法、limit <= 0，或历史查询窗口超过接口上限。 |
1004 | 参数冲突 | financials 同时传 start/end 与 limit；仅传 start 或仅传 end（半开区间）。 |
2001 | 未认证 | X-api-key 缺失或无效。 |
2003 | 权限不足 | API Key 无权调用该 capability。 |
3001 | 标的不存在 | 找不到目标标的。 |
3002 | 数据未就绪 | 标的存在，但暂无可用业务数据。 |
3004 | 标的类型不支持该能力 | 该标的类型不支持所请求的能力。 |
4001 | 频率超限 | 超过约定 QPS。 |
5001 | 服务内部错误 | 服务端未知错误。 |
5002 | 上游服务超时 | 数据源响应超时。 |
5003 | 数据源不可用 | 上游服务暂时不可用或返回非 0 状态。 |
MCP 接入
上述 REST capability 同时暴露为 MCP Tools，供 AI Agent 调用。 工具命名、参数与返回值见 MCP 工具概览。