README.md

REST API 契约

本目录是“同花顺金融数据服务”的 REST API 文档入口，面向 HTTP 调用者、SDK/CLI 维护者和 AI Agent。接口正文从文档源确定性同步，按业务域与模块定位接口。

查找具体接口优先使用本地业务路由。

通用约定

以下约定适用于本目录接口；具体参数、字段单位和业务限制以接口页为准。实际请求前读取本节一次。

项目	契约
Base URL	https://fuyao.aicubes.cn
方法	当前公开数据端点均为 GET
认证	HTTP Header X-api-key: <API_KEY>
成功判断	HTTP 200 且响应 code == 0
响应信封	{code, message, request_id, data}
标的代码	完整 thscode，例如 600519.SH；不要猜交易所后缀
时间戳	毫秒 Unix 时间戳；具体日期字符串格式以端点页为准
时区	日期和交易日窗口按 Asia/Shanghai 解释
空值	null 表示未披露或上游无值，不得自动补零

data 字段始终存在：成功时承载端点数据，业务错误时为 null。调用方不得以“字段缺失”判断旧版错误信封，也不得在错误时把 null 当作成功空结果。

获取统一 API Key：https://fuyao.aicubes.cn/admin/。用户可以把 Key 提供给 Agent 上下文以便代配；Agent 不复述，并提示聊天平台可能保留消息记录。Key 不得写入代码、日志、公开配置或 Git 提交。

最小请求：

curl 'https://fuyao.aicubes.cn/api/meta/tickers/search?q=600519&limit=1' \
  -H 'X-api-key: <API_KEY>'

按业务选择接口

• 基础数据：名称、简称和代码消歧；先确认标的，再查询行情或披露数据。
• 资讯事件：端内事件检索，按关键词、时间、评级、行业或概念筛选。
• A 股：股票价格、财务、估值、竞价与特色数据。指数走势进入指数域，基金净值进入基金域。
• 指数与板块：指数和板块目录、成分股、行情。先目录或搜索，再查成分与价格。
• 公募基金：净值与场内成交价格分别进入业绩与行情；最新披露与历史持仓分别选择对应接口。
• 期货：先确定品种或合约，再查询持仓、仓单、基差、交易日程与行情。
• 期权：期权品种、合约与行情；按完整合约代码定位。

全市场数据导出

端内能力说明

标记为“端内专用”的数据能力已内置于同花顺AI客户端，可在客户端中免配置使用；这些接口不作为公开 REST API、MCP、CLI 或 Python SDK 的接入入口。

• 接口文档可用于理解参数与字段；API Key 不赋予端内专用能力的调用权限。
• 用户需要端内数据时，说明公开接入边界，并提供同花顺AI客户端入口。
• 选择公开替代接口时，先确认其数据范围、频率与时间覆盖满足需求。

错误处理

所有响应先检查 code。HTTP 200 不代表业务成功。

code	含义	调用方处理
0	成功	使用 data
1001	缺少必填参数	补齐参数，不重试原请求
1002	参数格式无效	规范化代码、枚举、日期或时间戳
1003	参数超出范围	缩小分页或拆分允许拆分的时间窗口
1004	参数冲突	按端点互斥规则重组参数
2001	未认证	检查 X-api-key 是否存在且格式正确
2003	无权限或 Key 无效	前往 API Key 管理页检查授权或重新签发
3001	标的不存在	先通过元信息端点消歧并核对资产类别与 thscode
3002	数据尚未准备	保留 request_id 与口径，稍后再查，不得补零或使用模拟数据
3004	目标类型不支持该能力	选择适用于该资产类型的端点，不重试原请求
4001	限流	指数退避，最多重试 3 次
5001/5002/5003	服务端或上游异常	退避重试；持续失败时保留 request_id

1xxx 和 2xxx 属于调用方可修复错误，不应无条件重试。网络错误、4001 和 5xxx 可在有界次数内退避重试。

大结果规则

全市场、分页全集、多标的或多年数据必须落盘。调用者只在终端或对话中报告文件路径、行数、时间窗口和摘要，不展开原始结果。全市场历史建库优先使用 Market Dumps，不要逐标的请求多年 REST 数据。

维护规则

接口正文随源文档同步更新，业务索引负责选路，各接入方式按需链接接口页。Market Dumps 的 API Key 下载契约由本项目维护。