1. 什麼是 Pionex API?

Pionex API 是一個程式化介面,讓您可以透過自己的程式碼、腳本或第三方工具來控制您的 Pionex 帳戶 —— 完全不需要在 Pionex 網頁應用程式中點按任何按鈕。任何您能在使用者介面上做的事情（查看餘額、下現貨單、啟動網格機器人、開合約倉位、訂閱雙幣投資產品），都可以透過 API 來完成。

API 使用兩種相關的「方言」:

REST — 經典的 HTTP 請求。您問一個問題（GET）或推送一個變更（POST、DELETE），並收到 JSON 格式的回應。最適合用於動作：下這張單、取消那個機器人、顯示我的餘額。
WebSocket — 一條長時間維持的串流連線。伺服器即時將更新推送給您。最適合用於不斷變動的資料：即時價格、訂單簿更新、成交回報。

大多數整合會同時使用兩者：REST 用於「立刻做某件事」， WebSocket 用於「當某件事發生時告訴我」。

要建立 API 金鑰，請參閱第 4.1 節。

適用對象

對象	典型使用場景
入門交易者	唯讀腳本，將投資組合匯入試算表、將成交紀錄寫入檔案，或在機器人結束時發送 Telegram 通知。
量化 / 演算法交易者	自訂策略、回測、做市機器人、統計套利。
開發者與金融科技團隊	將 Pionex 交易嵌入另一個產品、建立報稅工具，或將餘額同步到投資組合儀表板。
進階使用者	同時操作數十個網格機器人、批次取消訂單、執行排程定投任務。

您不需要是資深工程師。如果您能執行 Python 或 JavaScript 腳本，您就能使用 Pionex API。最困難的概念 —— 請求簽名 —— 下面會以淺顯的方式說明，並附上可直接複製使用的範例。

一眼速查

屬性	數值
REST 基礎網址（現貨 / 機器人 / 理財）	`https://api.pionex.com`
REST 基礎網址（合約）	`https://api.pionex.com/uapi/v1`
WebSocket 公開串流	`wss://ws.pionex.com/wsPub`
身分驗證	每個私有請求都使用 HMAC-SHA256 簽名
必要標頭	`PIONEX-KEY`、`PIONEX-SIGNATURE`
回應格式	JSON 信封:`{ result, code, message, data }`
速率限制標頭	`X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset`
使用費用	免費 —— 您只需支付一般交易手續費

2. 您可以建構什麼

API 分為四大類端點。挑選符合您目標的類別；您也可以自由組合使用。

2.1 Trade API —— 現貨交易

最基本、最常用的功能。使用您已持有的資金進行買賣。

查詢所有餘額
列出交易對及其規則(最小下單量、手續費率、小數精度)
下限價單與市價單
取消訂單、列出未成交訂單、查詢訂單歷史
取得近期成交紀錄

2.2 Bot API —— 自動化策略

Bot API 存取權限可透過寄信至 service@pionex.com 申請，並註明您是申請 Bot API 存取權限。

Pionex 的招牌功能。以程式化方式啟動並調整交易機器人。

現貨網格機器人 —— 在價格區間內反覆低買高賣
合約網格機器人 —— 同樣概念，加上槓桿
AI 策略 —— 讓 Pionex 為您建議網格參數
即時調整運行中機器人的獲利率或價格區間
按百分比減倉，或完全停止機器人

2.3 Futures API —— 合約交易

Futures API 為邀請制服務，不開放公開申請。您可以申請「Bot API」來使用合約交易機器人。讀取權限維持公開;不需申請即可使用（仍需 API 金鑰）。

永續合約搭配槓桿(最大倍數依交易對而定)。

注意：Futures API 存取為邀請制。您的帳戶必須已啟用合約功能，合約端點才能運作。

開啟與平倉多頭與空頭部位
設定槓桿與保證金模式（逐倉或全倉）
切換單向或雙向持倉模式
查看未實現盈虧、標記價格、強制平倉價格
拉取資金費率歷史紀錄

2.4 Earn API —— 被動收益（測試版）

提供給偏好穩定收益而非主動交易的使用者的低操作門檻產品。

瀏覽雙幣投資產品
查看目前的執行價、上漲 APY、下跌 APY
訂閱產品、列出進行中的投資、查看歷史紀錄

注意：Earn 端點處於測試版階段，可能並非在所有地區都可使用。

3. 開始之前

您需要準備什麼

一個信譽良好的 Pionex 帳戶，若您的所在地區有要求，則需完成身分驗證。
已啟用雙重身分驗證 —— 建立 API 金鑰時必須。
開發環境 —— 任何能發出 HTTPS 請求的工具皆可。Python 3.9+ 或 Node.js 18+ 是最友善的選擇，因為網路上幾乎所有範例都用這兩種語言寫成。
基本熟悉以下事項：
- JSON（您看過 { "key": "value" } 這種格式）
- 環境變數，或某種能將密鑰放在程式碼之外的方式
- 從終端機執行腳本

您不需要準備什麼

伺服器。您可以從筆記型電腦執行。
付費方案。API 完全免費。
密碼學學位。簽名邏輯大約只有十行程式碼。

心智模型：一個請求如何運作

每個經過身分驗證的呼叫都遵循相同的五步模式：

您建立一個請求網址，例如 GET /api/v1/account/balances?timestamp=...
您從方法、路徑、排序後的查詢參數與請求主體組合出一段「標準訊息」字串。
您用 HMAC-SHA256 與您的 API 密鑰對該字串進行雜湊。這會產生一個簽名。
您發送請求時帶上兩個額外的標頭：PIONEX-KEY 與 PIONEX-SIGNATURE。
Pionex 在伺服器端執行完全相同的雜湊運算並進行比對。如果一致，您就通過了驗證。

關鍵概念：簽名能證明您知道密鑰，但密鑰本身從未透過網路傳輸。

4. 建立您的第一支 API 金鑰

步驟 1 —— 開啟 API 管理頁面

登入 Pionex。
點擊您的個人頭像。
選擇「API 管理」。

App： Click Here

網頁： https://www.pionex.com/zh-tw/my-account/api

步驟 2 —— 建立新的 API 金鑰

點擊「建立 API 金鑰」。系統會要求您填寫：

標籤 —— 取一個具體的名稱，例如 grid-bot-laptop 或 read-only-portfolio。當您之後擁有多支金鑰時，您會慶幸自己這麼做。
權限 —— 請見下節說明。
IP 白名單（選填但強烈建議） —— 限制金鑰只能從特定 IP 位址使用。

步驟 3 —— 謹慎選擇權限

權限	允許做什麼	建議
讀取	查看餘額、訂單、部位、成交	永遠啟用。任何有用的功能都需要。
交易（寫入）	下單與取消訂單、建立 / 調整 / 關閉機器人	僅在您的腳本確實需要交易時啟用。

步驟 4 —— 立即儲存密鑰

當您點擊「確認」後，Pionex 會顯示兩串字串：

API Key（有時稱為 apiKey 或 PIONEX-KEY） —— 算是半公開資訊，類似帳號
Secret —— 只會顯示一次，之後不會再出現。請像對待密碼一樣保護它。如果遺失，您必須刪除這支金鑰並重新建立一支。

請將兩者複製到安全的地方。建議的做法是將它們設定為您的 shell 設定檔中的環境變數，例如：

export PIONEX_KEY="paste_your_api_key_here"
export PIONEX_SECRET="paste_your_secret_here"

警告：絕對不要將金鑰貼到任何會推送到公開或共用儲存庫的原始碼裡。

步驟 5 —— 測試連線（不需要驗證）

在進行任何簽名動作之前，先確認網路是否正常：

curl "https://api.pionex.com/api/v1/common/symbols?symbol=BTC_USDT"

您應該會收到一段 JSON 信封，列出 BTC_USDT 的交易規則。如果這一步失敗，請先修復您的網路或防火牆設定再繼續。如果連基礎都不通，身分驗證的問題會無比難以除錯。

5. 核心概念

5.1 基礎網址

用途	網址
現貨、機器人、理財（REST）	`https://api.pionex.com`
合約（REST）	`https://api.pionex.com/uapi/v1`
公開 WebSocket	`wss://ws.pionex.com/wsPub`

注意：合約的路徑前綴是 /uapi/v1，不是 /api/v1。混淆這兩者是第一天最常犯的錯誤之一。

5.2 回應信封

Pionex 的每一個 JSON 回應都有這種外層結構：

{ "result": true, "code": 0, "message": "success", "data": { } }

result: true —— 成功。查看 data。
result: false —— 失敗。檢查 code 與 message。

提示：在讀取 data 之前一律先檢查 result。即使是 HTTP 200 的回應，在業務邏輯錯誤（例如「餘額不足」）時也可能 result: false。

5.3 交易對命名

市場	格式	範例
現貨	`BASE_QUOTE`	`BTC_USDT`、`ETH_USDT`、`SOL_BTC`
永續合約	`BASE_QUOTE_PERP`	`BTC_USDT_PERP`、`ETH_USDT_PERP`

一律使用底線分隔字元與大寫字母。

5.4 時間戳記

一律使用毫秒自 epoch 起算 —— 不是秒。從 Unix 工具轉過來的人經常犯這個錯誤。
放在查詢字串中，永遠不要放在請求主體中，即使是 POST 請求也一樣。
Pionex 容許幾秒的時鐘誤差，但不會更多。如果您的機器時鐘不準，簽名就會失敗並顯示 timestamp out of recv window。若看到此錯誤，請同步您的系統時鐘。

5.5 狀態碼

代碼	意義	該怎麼做
200	成功(仍須檢查 `result`)	繼續處理
400	參數錯誤	檢查拼字、型別與必填欄位
401	未經授權	API 金鑰或簽名錯誤
403	禁止存取	金鑰沒有所需權限
429	觸發速率限制	暫緩。請見「速率限制」章節。
500	伺服器錯誤	採用指數退避策略重試

6. 驗證：請求簽名如何運作

這是讓新手最害怕的章節。其實不用害怕。一旦您看過一個能運作的範例，其餘就是機械式的套用。

6.1 標準訊息

每個經過驗證的請求，都需要建立一段字串：

{METHOD}{PATH}?{SORTED_QUERY}{BODY}

規則：

METHOD 為大寫：GET、POST、DELETE。
PATH 是 URL 路徑，包含開頭的斜線，例如 /api/v1/account/balances。
SORTED_QUERY 是查詢字串，參數需依照 key 字母順序排序並進行 URL 編碼。
BODY 是 POST 請求的 JSON 主體，不能有任何空白字元。在 Python 中：json.dumps(separators=(',',':'))。在 JavaScript 中，JSON.stringify(obj) 會產生相同結果。
任何值為 None 或 undefined 的參數請完全捨棄。絕對不要送出 key=None。
即使是 POST，timestamp 參數也要放在查詢字串中，而不是主體中。

6.2 範例：簽署一個查詢餘額的請求

請求：

GET /api/v1/account/balances?timestamp=1701234567890

您要簽名的標準訊息：

GET/api/v1/account/balances?timestamp=1701234567890

將該字串與您的密鑰餵入 HMAC-SHA256，取十六進位摘要，並放入 PIONEX-SIGNATURE 標頭中。

6.3 Python 參考實作

import hmac import hashlib import time import os from urllib.parse import urlencode import requests  API_KEY = os.environ["PIONEX_KEY"] API_SECRET = os.environ["PIONEX_SECRET"] BASE_URL = "https://api.pionex.com"  def sign_get(path, params=None):     params = dict(params or {})     params["timestamp"] = int(time.time() * 1000)     query = urlencode(sorted(params.items()))     message = f"GET{path}?{query}"     signature = hmac.new(         API_SECRET.encode(),         message.encode(),         hashlib.sha256,     ).hexdigest()     headers = {         "PIONEX-KEY": API_KEY,         "PIONEX-SIGNATURE": signature,     }     return f"{BASE_URL}{path}?{query}", headers  url, headers = sign_get("/api/v1/account/balances") response = requests.get(url, headers=headers).json() print(response)

6.4 JavaScript / Node.js 參考實作

import crypto from "node:crypto";  const API_KEY = process.env.PIONEX_KEY; const API_SECRET = process.env.PIONEX_SECRET; const BASE_URL = "https://api.pionex.com";  function signGet(path, params = {}) {   const allParams = { ...params, timestamp: Date.now() };   const query = new URLSearchParams(     Object.entries(allParams).sort(([a], [b]) => a.localeCompare(b))   ).toString();   const message = `GET${path}?${query}`;   const signature = crypto     .createHmac("sha256", API_SECRET)     .update(message)     .digest("hex");   return {     url: `${BASE_URL}${path}?${query}`,     headers: {       "PIONEX-KEY": API_KEY,       "PIONEX-SIGNATURE": signature,     },   }; }  const { url, headers } = signGet("/api/v1/account/balances"); const r = await fetch(url, { headers }); console.log(await r.json());

6.5 簽署 POST 請求

請求主體是標準訊息的一部分。請建立一次、簽名一次，然後將完全相同的位元組作為請求主體送出。

import json  def sign_post(path, body):     timestamp = int(time.time() * 1000)     query = urlencode([("timestamp", timestamp)])     body_str = json.dumps(body, separators=(",", ":"))  # 不可有空白     message = f"POST{path}?{query}{body_str}"     signature = hmac.new(         API_SECRET.encode(),         message.encode(),         hashlib.sha256,     ).hexdigest()     return (         f"{BASE_URL}{path}?{query}",         {             "PIONEX-KEY": API_KEY,             "PIONEX-SIGNATURE": signature,             "Content-Type": "application/json",         },         body_str,     )  url, headers, body_str = sign_post(     "/api/v1/trade/order",     {         "symbol": "BTC_USDT",         "side": "BUY",         "type": "LIMIT",         "quantity": "0.001",         "price": "30000.00",     }, ) requests.post(url, headers=headers, data=body_str).json()

陷阱：如果您讓 HTTP 程式庫重新序列化請求主體（例如使用 requests.post(json=...)），它可能會自行加入空白字元，進而導致您的簽名不一致。請務必送出您實際簽名過的同樣位元組（使用 data=body_str）。

7. 入門教學：讀取您的帳戶

目標：印出您的餘額，以及 BTC_USDT 的交易規則。約 15 分鐘。零風險 —— 使用唯讀金鑰。

步驟 1 —— 取得所有交易對（不需驗證）

import requests r = requests.get(     "https://api.pionex.com/api/v1/common/symbols",     params={"symbol": "BTC_USDT"}, ) print(r.json()["data"]["symbols"][0])

您會學到 minQuantity、minAmount、baseScale 與 makerFeeRate —— 這些都是在您真正下單之前需要的數值。

步驟 2 —— 簽署您的第一個呼叫：帳戶餘額

使用第 6.3 節的 sign_get 輔助函式：

url, headers = sign_get("/api/v1/account/balances") data = requests.get(url, headers=headers).json()  for b in data["data"]["balances"]:     if float(b["free"]) > 0 or float(b["locked"]) > 0:         print(f"{b['coin']}: free={b['free']}, locked={b['locked']}")

如果您看到 401 或 result: false，請回頭檢視身分驗證章節。如果您看到了真正的餘額，您就完成了身分驗證。

步驟 3 —— 結合：以 USDT 計算投資組合總價值

現在您已具備計算「投資組合 USDT 總價值」所需的一切：

取得餘額。
對每個非零的幣種，從公開 ticker 端點取得當前價格。
加總（free + locked） × price。

這是一個完整、安全、唯讀的小專案 —— 非常適合作為入門週末練習。

8. 進階：下單與管理訂單

8.1 下限價單

url, headers, body = sign_post("/api/v1/trade/order", {     "symbol": "BTC_USDT",     "side": "BUY",     "type": "LIMIT",     "quantity": "0.001",     "price": "30000.00",     "clientOrderId": "my-order-001" }) print(requests.post(url, headers=headers, data=body).json())

提示：如果您的程式碼可能會重試，請務必設定 clientOrderId。沒有它，重試可能會建立重複訂單，讓您持有兩個未成交部位而不是一個。

8.2 取消訂單

DELETE /api/v1/trade/order?symbol=BTC_USDT&orderId=123456789

簽名方式與 GET 完全相同（沒有請求主體）。

8.3 列出未成交訂單

GET /api/v1/trade/openOrders?symbol=BTC_USDT

8.4 走訪歷史訂單（分頁）

GET /api/v1/trade/orders?symbol=BTC_USDT&limit=100&fromId={lastSeenId}

持續以您看到的最後一筆訂單的 fromId 呼叫，直到回傳的筆數少於 limit 為止。

8.5 在送出前驗證訂單

從 /common/symbols 您取得了這些欄位。請在客戶端使用它們做驗證：

quantity >= minQuantity
quantity <= maxQuantity
quantity * price >= minAmount（「最小名目價值」規則）
將 quantity 取至 baseScale 位小數，price 取至 quoteScale 位小數

跳過這些檢查是訂單被拒絕的第二大常見原因。

9. 進階主題

9.1 現貨網格機器人

網格機器人是一個參數化策略：選擇價格區間、網格線數量以及每格獲利率。機器人在價格下跌時累積部位、上漲時賣出，從價格震盪中獲利。

python

url, headers, body = sign_post("/api/v1/bot/orders/spotGrid/create", {     "symbol": "BTC_USDT",     "gridNumber": "20",     "lowerPrice": "40000",     "upperPrice": "50000",     "profitRate": "5",     "investmentAmount": "1000",     "side": "SELL" })

機器人運行後您可以：

POST /api/v1/bot/orders/spotGrid/adjustParams —— 即時調整區間或獲利率
POST /api/v1/bot/orders/spotGrid/reduce —— 平掉部分百分比的部位
POST /api/v1/bot/orders/spotGrid/cancel —— 停止機器人
GET /api/v1/bot/orders/spotGrid/aiStrategy?symbol=BTC_USDT —— 取得 AI 建議的參數

9.2 合約網格機器人

形式與現貨網格相同，加上 leverage（槓桿）參數：

POST /api/v1/bot/orders/futuresGrid/create {   "symbol": "BTC_USDT_PERP",   "leverage": "10",   ... }

注意：合約功能需要您的帳戶已啟用合約權限。

9.3 合約交易

注意路徑前綴是 /uapi/v1:

GET  /uapi/v1/account/balances GET  /uapi/v1/account/positions POST /uapi/v1/account/leverage POST /uapi/v1/trade/isolatedMode POST /uapi/v1/trade/order GET  /uapi/v1/trade/fundingFee

請在開倉之前先設定槓桿與保證金模式。在持倉狀態下變更槓桿是受限的。

9.4 Earn —— 雙幣投資（測試版）

GET  /api/v1/earn/dual/openProducts?symbol=BTC POST /api/v1/earn/dual/invests   { "productId": "...", "amount": "0.5" } GET  /api/v1/earn/dual/balances

訂閱前請先閱讀執行價、上漲 APY 與下跌 APY。資金會在產品期間內被鎖定。

9.5 WebSocket 基本介紹

wss://ws.pionex.com/wsPub

兩種頻道類別：

公開（不需身分驗證） —— ticker、kline、depth、trade
私有（需身分驗證） —— 餘額更新、訂單更新、部位更新

以 JSON 訊息進行訂閱：

{ "op": "SUBSCRIBE", "topic": "TRADE", "symbol": "BTC_USDT" }

重要：WebSocket 連線會中斷。請將您的客戶端包裝在「重連 + 退避」的迴圈中，並在重連時重新訂閱所有主題。

10. 速率限制與可靠性

10.1 您會收到什麼

每個回應都包含以下標頭：

X-RateLimit-Limit: 5000 X-RateLimit-Remaining: 4999 X-RateLimit-Reset: 1639485600

當 Remaining 降到 0，您會收到 HTTP 429，直到 Reset 為止。

10.2 如何保持安全

不要全速輪詢。每 200 毫秒呼叫一次 GET /openOrders 是不必要的；對大多數策略而言，每秒一次就夠了。
以 WebSocket 接收事件驅動資料。不要為了拉取價格 tick 而輪詢 —— 訂閱即可。
對 429 與 5xx 回應實作指數退避：

import time, random  def with_backoff(fn, max_attempts=6):     for i in range(max_attempts):         r = fn()         if r.status_code not in (429, 500, 502, 503):             return r         sleep = (2 ** i) + random.random()         time.sleep(sleep)     raise RuntimeError("max retries exceeded")

可以批次就批次。需要查詢 50 筆訂單狀態嗎？以一次大 limit 的 GET /trade/orders 呼叫處理，而不是 50 次個別查詢。

11. 常見問題

開始上手

問：我需要申請 API 權限嗎？

答：現貨、機器人、Earn —— 不需要。建立金鑰後即可開始。合約方面，API 為邀請制；您的帳戶必須已啟用合約權限。Earn 端點處於測試版，可能並非所有地區皆可使用。

問：API 是免費的嗎？

答：是的。您只需支付一般交易手續費（費率與網站上相同）。

問：我可以從瀏覽器使用嗎？

答：可以，但要小心。瀏覽器無法保管密鑰 —— 任何人檢視您的網頁原始碼都能讀到。請將簽名邏輯放在您控制的後端，或僅在用戶端使用唯讀金鑰並嚴格設定 IP 與 origin 限制，且絕對不要把擁有 Trade 權限的金鑰部署到用戶端。

問：哪一種程式語言最好？

答：Python 和 JavaScript 擁有最多範例。任何能進行 HTTPS 與 HMAC-SHA256 的語言都行：Go、Rust、Java、C#、PHP、Ruby。簽名邏輯在任何語言中都約十行。

問：我可以使用 Pionex API 連接外部平台嗎？

答：很遺憾，目前並不支援連接外部平台，僅能用於 Pionex 內部。

驗證

問：我的簽名一直顯示無效。該從哪裡開始檢查？

答：依序檢查五件事：

查詢參數是否依字母順序排序？
timestamp 是否放在查詢字串中，而非主體中？
您簽名的主體是否與您送出的主體完全一致（無多餘空白）？
您的機器時鐘是否在真實時間幾秒之內？
PIONEX-KEY 與 PIONEX-SIGNATURE 標頭是否都存在，且沒有互換？

問：為什麼 POST 請求的 timestamp 也要放在查詢中？

答：這是 Pionex 定義標準訊息規則的方式。這是慣例，沒有商量餘地。如果您放進主體中，簽名就會不一致。

問：我可以在不停機的情況下輪換金鑰嗎？

答：可以 —— 建立一支新金鑰、將它部署到您的程式碼中，然後撤銷舊金鑰。兩支金鑰在重疊期間都會同時有效。

問：我可以擁有多支金鑰嗎？

答：可以。建議為每個用途建立一支金鑰（bot-prod、dashboard-readonly、dev-laptop）。出狀況時撤銷可以做到精準切除。

交易

問：quantity 與 amount 有什麼差別？

答： quantity 是基礎幣的數量（例如 0.5 BTC）。amount 是計價幣的價值（例如 25,000 USDT）。/common/symbols 的 minQuantity 與 minAmount 同時強制這兩者：訂單必須同時滿足這兩項。

問：我的訂單一直被以「最小名目價值」為由拒絕。

答：quantity * price 必須至少等於 minAmount。0.0001 BTC 在 30,000 美元的價格下等於 3 美元名目價值，通常低於 10 美元的最小值。

問：我該如何讓下單具備冪等性？

答：將 clientOrderId 設為唯一值（例如 UUID）。如果您以相同的 clientOrderId 重試，Pionex 不會重複建單。

問：限價單可能部分成交嗎？

答：可以。請觀察 filledQuantity 與 status(PARTIALLY_FILLED）。使用 WebSocket 訂單更新頻道取得即時狀態。

問：有測試或沙盒端點嗎？

答：Pionex 目前沒有公開的沙盒環境。標準做法是：先以唯讀金鑰開發，然後在低流量的交易對上以 quantity = minQuantity 的微小真實訂單做煙霧測試。

機器人

問：我可以建立與應用程式裡相同的所有機器人類型嗎？

答：現貨網格與合約網格透過 API 開放使用。某些專門的機器人（例如 DCA 變體與智能交易）可能僅在 UI 中提供。請查閱最新的官方文件以了解目前的支援範圍。

問：我可以調整運行中的機器人嗎？

答：可以。adjustParams 讓您能夠在不取消的情況下變更 profitRate、lowerPrice 與 upperPrice（合約網格還可調整 leverage）。

問：reduce 與 cancel 有什麼不同？

答：reduce 關閉部位的一部分百分比，但機器人會繼續運行。cancel 則完全停止機器人。

問：aiStrategy 端點實際上在做什麼？

答：它根據近期波動性，回傳 Pionex 對該交易對建議的網格參數。請把它當作起點，而非鐵律 —— 部署資金前請自行檢視。

合約

問：如何申請合約 API 存取權限？

答：合約 API 採邀請制，需由我們的團隊進行人工審核。如果您在合約端點收到 403 錯誤，可能是因為您的帳戶尚未開通，或您的 API 金鑰缺少合約的 Trade 權限。如需申請存取權限，請聯繫我們的客服團隊。

問：逐倉與全倉保證金的差別是什麼？

答：逐倉 —— 只有您分配給該部位的保證金會虧損。全倉 —— 您整個合約錢包都會為該部位作為擔保。學習者建議從逐倉開始，較為安全。

問：單向 vs 雙向持倉模式？

答：單向 —— 每個交易對只有一個部位；開反向倉位會減倉或平倉。雙向 —— 多空可同時存在。大多數交易者應該從單向開始。

問：資金費率如何顯示？

答：週期性結算（通常每八小時一次，但請查驗交易對）。使用 GET /uapi/v1/trade/fundingFee 拉取歷史紀錄。

Earn

問：雙幣投資有保本嗎？

答：沒有。它有「下跌 APY」作為收益下限，但本金本身有風險。訂閱前請閱讀每個產品的詳細說明。

問：我可以提前取消雙幣投資嗎？

答：通常不行。資金會在產品期間內鎖定。請依此規劃流動性。

操作面

問：我該規劃什麼樣的速率限制？

答：請查看 X-RateLimit-Limit 了解您帳戶的限制。一個保守的起點是：每類端點每秒不超過 5 次請求，並在 429 時採用指數退避。

問：我該如何處理 5xx 錯誤？

答：用指數退避加上抖動進行重試。重點是：重試 POST 之前，先查詢狀態以確認先前的請求是否實際成功 —— 伺服器錯誤並不總是代表動作失敗了。

問：我的 WebSocket 一直斷線。是哪裡出了問題嗎？

答：這在網路層級是正常的。請實作：每 30 秒 ping 一次、以退避方式自動重連、重連時重新訂閱所有主題。

問：我該如何訂閱多個交易對？

答：傳送多則訂閱訊息，或使用該頻道支援的批次訂閱形式。每個主題彼此獨立。

安全性

問：我認為我的密鑰外洩了。我該怎麼做？

答：

開啟 API 管理頁面立刻撤銷該金鑰。
稽核近期活動（訂單，如有開啟提幣權限的話也包含提幣）。
以新的標籤建立新金鑰。
在您的程式碼庫與 commit 歷史中搜尋外洩的密鑰，並輪換所有相關憑證。

問：我該把金鑰或密鑰提交到 git 嗎？

答：絕對不要。請使用環境變數、.env 檔案（放入 .gitignore）或密鑰管理工具。如果不小心提交了，請立即輪換金鑰 —— git 歷史是永久的。

問：我該啟用提幣權限嗎？

答：幾乎永遠不要。唯一合理的使用情境是搭配硬體鎖、IP 白名單基礎建設的資金庫自動化作業。對大多數使用者而言，答案是否定的。

問：我可以以 IP 限制金鑰嗎？

答：可以 —— 對任何擁有 Trade 權限的金鑰強烈建議。設定您的伺服器或工作站的 IP 位址。

問：Pionex 看得到我的密鑰嗎？

答：Pionex 儲存的是單向雜湊值，而非明文。他們以與您產生簽名相同的方式來驗證您的簽名。這就是為什麼密鑰只能向您顯示一次。

12. 故障排除速查表

症狀	最可能原因	解決方式
每個請求都收到 401	金鑰或簽名不一致	重新檢查排序、主體位元組、標頭
只在 POST 時收到 401	主體在簽名後被重新序列化	將您已簽名的字串原樣作為主體送出
`result: false` 加上 timestamp 錯誤	時鐘漂移	同步系統時間
403	權限未授予，或合約尚未啟用	重新檢查金鑰權限；申請合約權限
429	觸發速率限制	加入退避；降低輪詢頻率
訂單被拒絕 —— 最小名目價值	`quantity * price < minAmount`	提高下單量
訂單被拒絕 —— 精度錯誤	小數位過多	取至 `baseScale` / `quoteScale` 位數
機器人無法啟動	網格區間無效或餘額不足	驗證參數；檢查餘額
WebSocket 斷線	正常現象或防火牆閒置逾時	採用退避方式重連；每 30 秒 ping 一次
在 curl 中簽名正常，在程式碼中卻不行	程式庫自動編碼主體	送出原始已簽名位元組

13. 安全最佳實踐

每個用途使用一支金鑰。更容易撤銷、更容易稽核。
最小權限原則。預設為唯讀；僅在需要時啟用 Trade；絕對不要隨意啟用 Withdraw。
IP 白名單：對任何能動到資金或下單的金鑰皆應設定。
絕不記錄密鑰。從請求 log 中去除驗證標頭。
絕不在用戶端程式碼放入密鑰。瀏覽器、行動應用程式 —— 假設任何送到使用者裝置的程式碼都是公開可讀的。
定期輪換。每 90 天是合理的頻率；懷疑外洩時立即輪換。
監控用量。Pionex 會顯示 API 金鑰用量統計 —— 每週檢視一次。
檢查程式碼是否有不慎提交的內容。git-secrets、trufflehog 或 GitHub 密鑰掃描等工具能及早發現外洩。
正式環境使用密鑰管理工具：AWS Secrets Manager、HashiCorp Vault、1Password CLI、Doppler —— 任何方式都比明文檔案好。
以小額帳戶測試。不要在第一天就把全新的交易機器人對著您的主帳戶啟動。

14. 詞彙表

術語	定義
API key / Secret	您 API 的帳號密碼組合。密鑰用來簽署請求；key 用來識別您的身分。
HMAC-SHA256	一種加密金鑰雜湊函數。相同輸入 + 相同密鑰會產生相同輸出，但無法從輸出推回密鑰。
標準訊息（Canonical message）	您與 Pionex 雙方對其進行雜湊以比對簽名的同一段確切字串。
計價幣（Quote currency）	交易對中的第二個資產（BTC_USDT 中的 USDT）。
基礎幣（Base currency）	交易對中的第一個資產（BTC_USDT 中的 BTC）。
名目價值（Notional）	`quantity × price` —— 該筆交易以美元（或計價幣）計算的價值。
Maker / Taker	Maker 提供流動性（您的訂單留在簿上）。Taker 移除流動性（您的訂單與簿上既有訂單撮合）。
標記價格（Mark price）	Pionex 用於合約的參考價格，用於計算強制平倉與未實現盈虧。
資金費率（Funding fee）	永續合約多空雙方之間的週期性款項。
強制平倉價（Liquidation price）	槓桿部位被強制平倉的價格。
冪等（Idempotent）	一個可安全重試的操作 —— 相同輸入產生相同結果。使用 `clientOrderId` 達成下單冪等性。
速率限制（Rate limit）	在被節流前每個時間窗口可發出的最大請求數。
WebSocket	一條持久、雙向的連線 —— 適合推播通知。
執行價（Strike price，Earn）	決定到期時 UP / DOWN APY 的價格門檻。

15. 接下來去哪裡

建議的學習路徑：

建立第 7 節的唯讀投資組合腳本。
用 clientOrderId 重試機制下您的第一張 10 美元限價單。
啟動一個迷您現貨網格機器人（50 美元投入、窄價格區間），觀察一週。
加上 WebSocket 私有頻道，即時記錄成交事件。
在您已操作現貨機器人至少一個月後，再進入合約。

官方 Pionex 文件包含最新端點清單與任何測試版資訊：https://www.pionex.com/docs/

如果您對 API 還有其他疑問，我們誠摯邀請您加入 Telegram 群組以取得更好的協助：https://t.me/pionexapi

最後一個小提示：當您撞牆時，最有用的除錯步驟幾乎總是把您的標準訊息字串與簽名，跟一個能正常運作的 curl 範例並排印出來，找出哪一個字元不一樣。那一個字元幾乎一定就是 bug 所在。

祝您交易順利！

Pionex API：完整指南