> ## 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 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.