基本信息
本页汇总 Rocky 永续合约所有端点都适用的基础约定。
Base URL
| 环境 | Base URL |
|---|---|
| Devnet | https://api.rocky.exchange |
| Mainnet | https://api.rocky.exchange |
Content-Type
- Web v1 请求体：
application/json - FAPI（
/fapi/*）：参数以 URL-encoded 形式放在 query string 中。若发送了 URL-encoded 请求体，它会被拼进签名载荷，但 handler 只从 query string 读取参数。FAPI 不接受 JSON 请求体。 - Query string：标准 URL-encoded
- 响应：
application/json（/healthz、/readyz返回text/plain） - 价格、数量等 decimal 值一律以字符串返回；时间戳为 int64 Unix 毫秒
版本管理
路径版本化。破坏性变更走新版本号（/v1 → /v2），旧版本保留到下一个 major 发布。
限流
所有 /fapi/* 路由均已启用限流（与现货 /api/v3/* 共用同一限流器），采用按 wall-clock 对齐的固定窗口：
| 桶 | 范围 | 窗口 | 上限 | Header |
|---|---|---|---|---|
| 请求权重 | 公开接口，按客户端 IP | 1 分钟 | 6000 | X-MBX-USED-WEIGHT-1M |
| 请求权重 | 签名接口，按 API key | 1 分钟 | standard 1200 / ext-mm 2400 / house 6000 | X-MBX-USED-WEIGHT-1M |
| 订单计数 | POST /fapi/v1/order，按 API key | 10 秒 | standard 50 / ext-mm 100 / house 200 | X-MBX-ORDER-COUNT-10S |
| 订单计数 | POST /fapi/v1/order，按 API key | 1 分钟 | standard 200 / ext-mm 600 / house 1200 | X-MBX-ORDER-COUNT-1M |
- 档位取自 key 的
rate_tier（未经管理员修改时为standard）。 - 请求权重：
exchangeInfo10；depth、klines、trades、ticker/24hr5；其余路由均为 1。各页面均标注了权重。 - 签名接口在鉴权前还会经过一道按 IP 的权重闸门，24000/分钟（仅在其自身返回
429时写入 header）。 - 超限 → HTTP
429，响应{"code":-1003,"msg":"Too many requests."}并附上述计数 header。Rocky 不会升级为418、不保存 IP 封禁状态，也不返回Retry-After。窗口为固定窗口而非滑动窗口，因此客户端在窗口 边界处最多可突发至上限的 2 倍。
鉴权
| 接口 | 方式 |
|---|---|
/v1/* | Authorization: Bearer <session_token>，由 POST /v1/wallet/verify 签发；不存在 user_id query 参数 |
/fapi/v1/*、/fapi/v2/* | X-MBX-APIKEY header + signature 参数（HMAC-SHA256；ED25519 类型 key 用 Ed25519） |
X-MBX-APIKEY须为 1~256 个[A-Za-z0-9_-]字符，否则返回-2014（HTTP 400）。key 未知或已吊销 →-2015（HTTP 401）。- 签名载荷 = URL-encoded 的 query string，若发送了 URL-encoded 请求体则再拼接
&与请求体，并去掉末尾的&signature=<sig>（取最后一个signature=）。请按实际发送的参数与顺序签名。 - HMAC key：
signature为用 API secret 对载荷做 HMAC-SHA256 后的小写 hex。ED25519key：signature为对同一载荷的 Ed25519 签名的 base64（标准或 URL-safe 字母表均可，允许 percent-encoding）。不匹配 →-1022（HTTP 401）。 - 缺少
signature或timestamp→-1102（HTTP 400）。
签名细节见 FAPI 下单流程。
时间同步
- 所有
timestamp单位都是 Unix 毫秒。 - 签名请求需满足
|now − timestamp| ≤ recvWindow；默认recvWindow = 5000，上限60000。 recvWindow必须是0..=60000范围内的整数，否则 →-1100（HTTP 400）。timestamp超出窗口 →-1021（HTTP 401）。
交易对
FAPI 接口的入参与返回均使用标准形式（BTCUSDT、ETHUSDT、CCUSDT）；Web v1 接口使用 Rocky 内部形式（BTC-PERP、ETH-PERP、CC-PERP）。FAPI 接口收到其他 symbol → -1100（HTTP 400）。见 通用枚举定义。