基本信息

本页汇总适用于所有 Sparky 永续合约端点的通用约定。

Base URL

Sparky 每条链一套后端。每套部署有独立数据库：余额、持仓、订单、API Key、推荐数据与积分全部按链隔离。域名分配前主机名为占位符。

链	Chain ID	REST Base URL	WebSocket
Avalanche C-Chain	`43114`	`https://api-avax.<sparky-domain>`	`wss://api-avax.<sparky-domain>/ws`
Arbitrum One	`42161`	`https://api-arb.<sparky-domain>`	`wss://api-arb.<sparky-domain>/ws`
BNB Chain	`56`	`https://api-bnb.<sparky-domain>`	`wss://api-bnb.<sparky-domain>/ws`
Avalanche Fuji（测试网）	`43113`	`https://api-fuji.<sparky-domain>`	`wss://api-fuji.<sparky-domain>/ws`
Arbitrum Sepolia（测试网）	`421614`	`https://api-arb-sepolia.<sparky-domain>`	`wss://api-arb-sepolia.<sparky-domain>/ws`

/fapi/v1/*、/fapi/v2/* 与 /futures/data/* 与 Binance 一样挂在域名根路径；原生 API 在 /api/v1/* 下。

内容类型

FAPI GET / DELETE：参数以 URL-encoded 形式放在查询串。
FAPI POST / PUT：业务参数以 JSON body 发送（Content-Type: application/json）；timestamp 与 signature 仍在查询串。这与 Binance 默认"全部走查询串"略有不同，但主流 SDK 两种都支持。
原生 /api/v1/*：JSON body。
响应：application/json。价格、数量等小数以字符串返回；FAPI 时间戳为 int64 Unix 毫秒（原生 API 秒 / 毫秒混用，各页面会注明）。

版本

按路径分版本。Sparky 实现了 /fapi/v1/*，以及 /fapi/v2/balance 与 /fapi/v2/positionRisk。没有 /fapi/v1/balance（404）——默认走 v2 的 SDK 不受影响。

鉴权

接口	方案
`/api/v1/*`	`Authorization: Bearer <JWT>`，来自 `POST /api/v1/auth/login`（EIP-712 登录）
`/fapi/v1/`、`/fapi/v2/` 签名接口	`X-MBX-APIKEY` 请求头 + `timestamp` + `signature` 查询参数（HMAC-SHA256）
公开行情接口（`/fapi/v1/ping`、`time`、`exchangeInfo`、`depth`、`klines`、各 ticker、`premiumIndex`、`fundingRate`、`fundingInfo`、`openInterest`、`/futures/data/*`）	无

API Key

通过 JWT 调用 POST /api/v1/api-keys 创建（见 API Keys）。每个 Key 包含：

字段	用途
`api_key`	64 位十六进制；放在 `X-MBX-APIKEY`
`secret_key`	64 位十六进制；仅创建时返回一次，永不发送给服务端，只用于本地 HMAC
`ip_whitelist`	可选，逗号分隔；按 `X-Forwarded-For` 第一跳比对
`permissions`	`trading,deposit` —— API Key 永远不能提现

每个账户每套部署最多 30 个 Key。PUT /api/v1/api-keys/{id} 可禁用（status: "disabled"），DELETE 删除。

签名

与 Binance Futures 完全一致，只是把 POST/PUT 的 body 规则写明：

收集除 signature 外的所有查询参数，URL-encode 后用 & 串接 → payload。
仅 POST / PUT：把原始请求 body 字符串（将要发送的 JSON 字节本身，不做 URL-encode）追加到 payload 末尾。
signature = hex(HMAC_SHA256(secret_key, payload))。
携带 X-MBX-APIKEY 发送 ?<query>&signature=<hex>。

GET:   payload = "symbol=BTCUSDT&timestamp=1714261234567"
POST:  payload = "timestamp=1714261234567" + '{"symbol":"BTCUSDT","side":"BUY","type":"LIMIT","quantity":"0.01","price":"60000"}'

Sparky 的验签对编码风格宽容：先按收到的（已 URL-encoded）查询串验签；不匹配则把每个 (k, v) URL-decode 后重新拼接再验一次。两条分支使用同一份 secret，不会削弱 HMAC 安全性——只是让那些对原始 orderIdList=[uuid1,uuid2] 签名、再由 HTTP 库做 percent-encoding 的客户端也能通过。新代码请遵循 Binance 规范（对 URL-encoded 形式签名）。

验签失败返回 HTTP 401，使用 Sparky 信封而非 Binance 错误码：

{ "success": false, "error": { "code": "SIGNATURE_INVALID", "message": "..." } }

`error.code`	HTTP	原因
`INVALID_API_KEY`	401	当前部署找不到该 Key
`API_KEY_DISABLED`	401	Key `status != active`
`IP_NOT_ALLOWED`	403	客户端 IP 不在 `ip_whitelist`
`SIGNATURE_INVALID`	401	HMAC 不匹配、缺 `timestamp` 或时间戳越界

时间同步

timestamp 为 Unix 毫秒。
服务端校验 |now − timestamp| ≤ 60 000 ms，且为双向：未来的时间戳同样被拒（Binance 历史上只校验过去一侧）。
recvWindow 会被接受但忽略：60 秒窗口固定在服务端，不能加宽或收窄。
启动时和运行中周期性调用 GET /fapi/v1/time，用 serverTime − localTime 做偏移补偿。

限流

对所有 /fapi/* 与 /futures/data/* 路由生效，采用按墙钟对齐的固定窗口（因此客户端可在窗口边界突发到上限的 2 倍，与 Binance 一致）：

桶	作用域	窗口	上限	响应头
Request weight	公开接口，按客户端 IP	1 分钟	6000	`X-MBX-USED-WEIGHT-1M`
Request weight	签名接口，按 API Key	1 分钟	`standard` 1200 / `ext-mm` 2400 / `house` 6000	`X-MBX-USED-WEIGHT-1M`
Order count	`POST/PUT /fapi/v1/order`、`POST/PUT /fapi/v1/batchOrders`、`POST /fapi/v1/algoOrder`，按 API Key	10 秒	`standard` 50 / `ext-mm` 100 / `house` 200	`X-MBX-ORDER-COUNT-10S`
Order count	同上，按 API Key	1 分钟	`standard` 200 / `ext-mm` 600 / `house` 1200	`X-MBX-ORDER-COUNT-1M`

档位即 Key 的 rate_tier（默认 standard，由 Sparky 运营调整；GET /api/v1/api-keys 可见）。
权重：exchangeInfo 10；depth、klines、ticker/24hr、fundingRate、futures/data/*、allOrders、userTrades、positionRisk、balance、fundingFeeHistory、batchOrders 5；forceOrders 20；income 30；其余路由 1。各页面均标注权重。
撤单（DELETE）不计入下单桶。batchOrders 一次请求按 1 笔计。
签名接口在验签之前还会经过一道按 IP 的预闸（24000/分钟），它只在自己返回的 429 上写响应头。
GET /fapi/v1/exchangeInfo 发布的是 standard 档的上限（REQUEST_WEIGHT 1m、ORDERS 1m、ORDERS 10s）；更高档位的 Key 以响应头为准。
超限 → HTTP 429，正文 {"code":-1003,"msg":"Too many requests."}，响应头带当前计数。被拒的请求不消耗配额（下单被拒时该请求的权重已扣，与 Binance 一致）。Sparky 不会升级为 418，没有 IP 封禁状态，也不发送 Retry-After。请按 X-MBX-USED-WEIGHT-1M 主动控制节奏，而不是等 429。

Symbol

symbol 大小写不敏感，并归一为 Binance 形式。以下输入都会解析为 BTCUSDT：

输入	归一后
`btcusdt`、`BTCUSDT`	`BTCUSDT`
`BTC-USD`、`BTC-USDT`	`BTCUSDT`
`BTC/USDT`、`BTC_USDT`	`BTCUSDT`

只有 BTCUSDT 形式是规范形式（Binance 会拒绝别名）。不在当前部署 market_configs 内的 symbol → -1121 Invalid symbol。实时列表来自 GET /fapi/v1/exchangeInfo；原生 API 的写法见 Symbol 别名。

分片路由

部署可运行多个 pod，每个 symbol 由一个 pod 拥有。落到非 owner pod 的写请求会被透明转发——查询串与签名不变，客户端只连一个固定 Base URL。详见分片路由。

错误响应格式

FAPI 的业务与签名错误使用 Binance 信封：

{ "code": -1021, "msg": "Timestamp outside recv window" }

HTTP	含义	常见 code
`400`	参数 / 业务校验	`-1013`、`-1100`、`-1102`、`-1106`、`-1120`、`-1121`、`-1130`、`-2010`、`-2011`、`-2014`、`-2019`、`-2021`、`-2022`、`-4028`、`-4046`、`-4059`
`401`	鉴权失败	`INVALID_API_KEY`、`API_KEY_DISABLED`、`SIGNATURE_INVALID`（Sparky 信封）
`403`	IP 不允许	`IP_NOT_ALLOWED`（Sparky 信封）
`404`	订单 / 资源不存在	`-2013`、`-1125`
`500`	服务端错误	`-1000`、`-1001`

完整表见错误码。

Base URL​

内容类型​

版本​

鉴权​

API Key​

签名​

时间同步​

限流​

Symbol​

分片路由​

错误响应格式​