认证与签名

PerpDEX REST API 与 WebSocket API 的权限、认证及签名规则

​

认证与签名

​

API 权限

创建 API Key 时，需要根据使用场景配置对应权限。

权限	可执行操作
只读	查询订单、持仓、账户信息、个人成交记录等
读写	在只读权限基础上，可下单、撤单、改单及管理持仓

所有 GET 操作属于读请求；下单、撤单、改单及其他非 GET 操作属于写请求。

使用时需要注意：

• PerpDEX 目前不支持 Broker API，使用独立的 API Key 进行服务端调用与认证。
• 交易类接口需要 API Key 具备对应的读写权限。
• 建议为 API Key 配置 IP 白名单，减少密钥泄露后的风险。
• API Secret 仅用于本地生成签名，不应发送给服务端，也不应写入前端代码。

​

API 签名请求要求

调用需要认证的接口时，请按以下步骤构造请求：

1. 创建 API Key，并确认已配置正确权限。
2. Header KEY 设置为 API Key。
3. Header Timestamp 设置为当前 Unix 秒级时间戳，与服务器时间差不得超过 60 秒。
4. 根据当前请求生成签名，并将结果写入 Header SIGN。
5. 如果 API Key 配置了 IP 白名单，请确保调用服务器 IP 已加入白名单。

请求 Header：

Header	必填	说明
KEY	是	API Key
Timestamp	是	Unix 时间戳，单位秒
SIGN	是	HMAC-SHA512 生成的十六进制签名

服务器时间与客户端时间偏差过大时会返回认证错误。建议调用服务器保持 NTP 时间同步。

​

API 签名字符串生成

签名原文按以下顺序拼接，每个部分之间使用换行符 \n：

Request Method + "\n" +
Request URL + "\n" +
Query String + "\n" +
HexEncode(SHA512(Request Payload)) + "\n" +
Timestamp

最终签名：

SIGN = HexEncode(HMAC_SHA512(API Secret, Signature String))

​

Request Method

请求方法必须使用大写，例如：

GET
POST
PUT
DELETE

​

Request URL

只包含请求 Path，不包含协议、域名和端口，并包含 /api/v1 前缀。

例如：

/api/v1/dex_futures/usdt/orders

​

Query String

使用请求 URL 中实际发送的 Query String，并保持参数顺序一致，不重新排序。

例如：

status=finished&limit=50

没有 Query 参数时使用空字符串：

""

​

Request Payload

对实际发送的 Request Body 原文执行 SHA512，再取十六进制结果。

没有 Request Body 时，对空字符串进行 SHA512，其结果为：

cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e

如果请求 Body 为 JSON，请以最终实际发送的 JSON 字符串计算 Hash。字段顺序、空格或换行变化都会导致 Payload Hash 变化。

​

Timestamp

使用与 Header Timestamp 完全一致的值，例如：

1541993715

​

GET 请求签名示例

假设请求：

GET /api/v1/dex_futures/usdt/orders?status=finished&limit=50

则签名原文为：

GET
/api/v1/dex_futures/usdt/orders
status=finished&limit=50
cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
1541993715

其中：

• 第一行：Request Method
• 第二行：Request URL
• 第三行：Query String
• 第四行：空 Request Body 的 SHA512
• 第五行：Timestamp

随后使用 API Secret 对整个签名原文执行 HMAC-SHA512，得到 SIGN。

​

POST 请求签名注意事项

POST / PUT 等带 Request Body 的接口，需要确保：

• 用于计算 SHA512 的 Body 与实际发送 Body 完全一致。
• Content-Type 与接口要求一致，通常为 application/json。
• Query String 即使为空，也必须在签名原文中保留对应的空行。
• 不要对已经拼接好的签名字符串额外做 URL Encode。

​

常见认证错误

Label	常见原因
INVALID_KEY	API Key 不存在、已失效或填写错误
IP_FORBIDDEN	调用 IP 不在 API Key 白名单
READ_ONLY	使用只读 Key 调用了写接口
INVALID_SIGNATURE	签名原文或 API Secret 不正确
MISSING_REQUIRED_HEADER	缺少 KEY、Timestamp 或 SIGN
REQUEST_EXPIRED	Timestamp 与服务器时间偏差超过允许范围
FORBIDDEN	当前账户或 Key 无对应操作权限

不要在工单、聊天记录、截图或日志中公开 API Secret。若 API Secret 已泄露，应立即停用当前 API Key 并重新创建。

​

WebSocket 认证与签名

公开 WebSocket 频道无需认证。订阅订单、用户成交、持仓、余额等私有频道时，需要在请求中携带 auth：

{
  "time": 1700000000,
  "channel": "futures.orders",
  "event": "subscribe",
  "payload": ["<user_id>", "BTC_USDT"],
  "auth": {
    "method": "api_key",
    "KEY": "<API_KEY>",
    "SIGN": "<SIGN>"
  }
}

私有频道签名原文：

channel=<channel>&event=<event>&time=<timestamp>

使用 API Secret 执行 HMAC-SHA512，并将结果编码为十六进制：

SIGN = HexEncode(HMAC_SHA512(API Secret, Signature String))

API Secret 仅用于本地生成签名，不通过 WebSocket 发送。

WebSocket 账户交易 API 的请求签名与频道订阅签名不同，具体以「账户交易 API」页面为准。