> ## Documentation Index
> Fetch the complete documentation index at: https://dexbuilder.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 认证与签名

> 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` 生成的十六进制签名 |

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

## API 签名字符串生成

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

```text theme={null}
Request Method + "\n" +
Request URL + "\n" +
Query String + "\n" +
HexEncode(SHA512(Request Payload)) + "\n" +
Timestamp
```

最终签名：

```text theme={null}
SIGN = HexEncode(HMAC_SHA512(API Secret, Signature String))
```

### Request Method

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

```text theme={null}
GET
POST
PUT
DELETE
```

### Request URL

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

例如：

```text theme={null}
/api/v1/dex_futures/usdt/orders
```

### Query String

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

例如：

```text theme={null}
status=finished&limit=50
```

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

```text theme={null}
""
```

### Request Payload

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

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

```text theme={null}
cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
```

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

### Timestamp

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

```text theme={null}
1541993715
```

## GET 请求签名示例

假设请求：

```text theme={null}
GET /api/v1/dex_futures/usdt/orders?status=finished&limit=50
```

则签名原文为：

```text theme={null}
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 无对应操作权限 |

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

## WebSocket 认证与签名

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

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

私有频道签名原文：

```text theme={null}
channel=<channel>&event=<event>&time=<timestamp>
```

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

```text theme={null}
SIGN = HexEncode(HMAC_SHA512(API Secret, Signature String))
```

> [!WARNING]
>
> API Secret 仅用于本地生成签名，不通过 WebSocket 发送。

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.