响应信封
成功响应固定为data + _meta 两段：
error 一段（形状见错误处理）。每个响应（无论成败）都带 request_id，反馈问题时请附上它。
- 字段命名统一
snake_case。 - 金额类字段以
_usd后缀标注单位。 - 缺数据的字段返回
null，不会伪装成0或空串。 - 未知的查询参数不会被静默忽略，而是返回
400 VALIDATION_ERROR——拼错参数名能立刻被发现。
分页
列表与历史类端点使用游标分页：- 首次请求带
limit（各端点有默认值与上限，见 Reference）； - 响应的
_meta.next_cursor非空时，原样作为cursor参数请求下一页； next_cursor缺失即最后一页。
cursor 是不透明字符串：不要解析、不要构造、不要跨端点复用。非法或过期的 cursor 返回 400。
时间
- 输入：ISO 8601。允许 date-only（
YYYY-MM-DD）；携带时间部分时必须带时区偏移（如2026-08-06T14:30:00-04:00），不接受无时区的裸时间。 - 输出：时间戳一律携带时区偏移或为 UTC（
Z后缀），可直接解析比较。 - 市场语义：美股市场数据按 ET（America/New_York）交易日组织。date-only 输入在市场语境下按 ET 日历日理解；个别端点的窗口边界细节在其参数说明中单独定义。
- 披露类数据（国会、财报、机构持仓）以披露时间与事件时间双时间轴呈现，字段含义见各端点 Reference。
标的与合约代码
- 股票标的使用大写美股代码（如
SPY、AAPL）。写法不合法返回400 TICKER_INVALID；写法合法但不在服务范围返回404或503（区别见数据新鲜度）。 - 期权合约使用 OSI 格式（如
SPY260620C00450000）。 - 指数类标的的支持范围因端点而异，以 Reference 与
GET /v1/discover为准。
幂等与重试
全部数据端点为GET，天然幂等，可安全重试。重试策略见数据新鲜度的程序模式小抄与限流规则。
浏览器与 CORS
API Key 面向服务端与本地程序设计，不建议在浏览器前端直接使用（Key 会暴露给页面访问者）。浏览器场景请使用产品页面本身。版本与兼容
- 当前版本
v1，体现在路径前缀/v1/。 - 新增响应字段、新增可选参数、新增端点均为非破坏性变更，随时可能发生——你的解析代码应忽略未知字段。
- 删除/重命名字段、改变既有语义属破坏性变更：会提前 90 天在 changelog 预告后才生效。