API 参考
同花顺金融数据API 以一套 REST 接口对外提供能力，并同时通过 MCP Tools 暴露给 AI Agent 工具链。
两种调用方式共享同一套后端 capability，数据语义完全一致。所有业务响应（含错误）统一返回 HTTP 200，
业务结果经响应信封的 code 字段表达。
接口分组
| 分组 | 路径前缀 | 说明 |
|---|---|---|
| 价格数据 (prices) | /api/a-share/prices | A 股行情快照与历史 K 线。 |
| 全市场数据导出 (market-dumps) | /dump/market-dumps | 价格数据子模块：A 股全市场历史日 K 与复权因子 Parquet 文件下载链接。 |
| 标的检索与目录 (tickers) | /api/meta/tickers | 跨市场标的检索与代码表批量获取。 |
| 公司行动 (corporate-actions) | /api/a-share/corporate-actions | A 股复权因子事件流（分红 / 送股 / 配股）。 |
| 财务报表 (financials) | /api/a-share/financials | A 股整体合并利润表 / 资产负债表 / 现金流量表多期序列。 |
| 交易日历 (calendar) | /api/a-share/calendar | A 股近一年交易日序列（含毫秒戳与 yyyyMMdd）。 |
| 同花顺指数列表和成分股 (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 | 业务数据容器，按接口而定；错误时可能省略。 |
data.timestamp | long | 数据时间戳（毫秒）。 |
data.item | array | 业务数据列表。 |
错误码
| code | 含义 | 典型场景 |
|---|---|---|
0 | 成功 | - |
1001 | 缺少必填参数 | start / end / q / thscode 漏传。 |
1002 | 参数格式错误 | exchange 不在 SH / SZ / BJ。 |
1003 | 参数取值越界 | limit <= 0；historical / financials 的 [start, end] 窗口超过 10 年。 |
1004 | 参数冲突 | financials 同时传 start/end 与 limit；仅传 start 或仅传 end（半开区间）。 |
2001 | 未认证 | X-api-key 缺失或无效。 |
2003 | 权限不足 | API Key 无权调用该 capability。 |
4001 | 频率超限 | 超过约定 QPS。 |
5001 | 服务内部错误 | 服务端未知错误。 |
5002 | 上游服务超时 | 数据源响应超时。 |
5003 | 数据源不可用 | 上游服务暂时不可用或返回非 0 状态。 |
MCP 接入
上述 REST capability 同时暴露为 MCP Tools，供 AI Agent 调用。 工具命名、参数与返回值见 MCP 工具概览。