约定

HTTP

• 除非另有说明，响应为 JSON。
• 时间戳为 Unix 毫秒，除非 FIX 使用 UTC 时间戳字段。
• Query / JSON 字段大小写与网关及 Postman 保持一致（交易类多为 camelCase；部分法币/migration 为 snake_case — 以 OpenAPI 示例为准）。

鉴权类别

类别	何时	Header	签名
公开	无 @SignAuth	需要 Host 解析 org；Postman 中 API Key 可选	否
仅 API Key	@SignAuth(validKeyOnly=true)	x-ptrader-apikey	否
HMAC 签名	@SignAuth（交易/账户等）	x-ptrader-apikey	是（signature，通常还需 timestamp）

行情路径别名

MktDataApiController 同时映射：

• /openapi/quote/v1/...（Postman / 本文档优先）
• /openapi/v1/...（同一批 handler）

[NEEDS-CONFIRMATION: 双别名是否长期保证]

错误体形状

{ "code": -1022, "msg": "Signature for this request is not valid." }

见 错误码。

文档标记

标记	含义
[NEEDS-CONFIRMATION: …]	事实未完全核实；勿当作生产承诺
Illustrative / 示意	来自 Postman/代码的示例，请以实盘响应校验
待确认清单	后端 / 文档作者 backlog

排除项

请勿调用或文档化：

• /merchant-api/*
• /broker/v1/public/security/create-api-key-v2、/openapi/v1/tool/create-api-key-v2
• 管理端 / Exchange-Web BFF API