跳至主要內容

Pionex API：完整指南

介绍 Pionex API：REST 基础地址 api.pionex.com，WebSocket 地址 wss://ws.pionex.com/wsPub，使用 HMAC-SHA256 签名并通过 PIONEX-KEY / PIONEX-SIGNATURE 请求头进行鉴权，频率限制为每秒 10 次请求，免费使用，支持现货、机器人、合约及理财相关端点。

1. 什麼是 Pionex API？

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

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

  • REST — 經典的 HTTP 請求。您提出一個問題（GET）或推送一項變更（POST、DELETE），並收到 JSON 格式的回應。最適合用於動作：下這張單、取消那個機器人、顯示我的餘額。

  • WebSocket — 一條長時間維持的串流連線。伺服器會即時將更新推送給您。最適合用於不斷變動的資料：即時價格、訂單簿更新，以及成交發生當下的成交回報。

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

如需存取 API 金鑰的建立功能，請參閱 步驟 4.1

誰適合使用 API？

對象

典型使用情境

入門交易者

唯讀腳本，可將您的投資組合匯入試算表、將成交紀錄寫入檔案，或在機器人結束時發送 Telegram 提醒。

量化 / 演算法交易者

自訂策略、回測、造市機器人、統計套利。

開發者與金融科技團隊

將 Pionex 交易功能嵌入另一個產品、建立報稅工具，或將餘額同步到投資組合儀表板。

進階使用者

同時操作數十個網格機器人、批次取消訂單、執行排程的定期定額（DCA）任務。

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

一眼速查

屬性

數值

REST 基礎網址（現貨 / 機器人 / Earn）

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 }

速率限制

每個 IP 與每個帳戶每秒 10 次請求（依權重計算）；超過時回傳 HTTP 429

使用費用

免費 — 您只需支付一般交易手續費

2. 您可以建構什麼

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

2.1 Trade API — 現貨交易

最核心的基本功能。使用您已持有的資金買賣加密貨幣。

  • 查詢您所有的餘額

  • 列出交易對及其規則（最小下單量、手續費率、小數精度）

  • 下限價單與市價單

  • 取消訂單、列出未成交訂單、查詢訂單歷史

  • 取得您近期的成交紀錄（已執行的交易）

2.2 Bot API — 自動化策略

Bot API 對所有帳戶開放 — 無需申請。只要在您的 API 金鑰上啟用 Bot Reading / Bot Trading 權限即可。

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

  • 現貨網格機器人 — 在價格區間內反覆低買高賣

  • 合約網格機器人 — 同樣的概念，加上槓桿

  • AI 策略 — 讓 Pionex 為您建議網格參數

  • 調整運行中機器人的獲利率或價格區間

  • 依百分比減少持倉，或完全取消機器人

2.3 Futures API — 合約交易

帶槓桿的永續合約（最大槓桿倍數依交易對而定）。

透過 API 進行合約直接交易目前無法使用。此功能仍處於內部開發階段，尚未向任何帳戶開放 — 目前沒有任何申請、候補名單或搶先體驗流程。

  • 開啟與平倉多頭與空頭持倉

  • 設定槓桿與保證金模式（逐倉或全倉）

  • 切換單向與雙向（Hedge）持倉模式

  • 查看未實現損益、標記價格、強制平倉價

  • 取得資金費率歷史紀錄

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

為想要收益而非主動交易的使用者所提供的低操作門檻產品。

  • 瀏覽雙幣投資產品

  • 查看目前的執行價、上漲 APY、下跌 APY

  • 訂閱產品、列出進行中的投資、查看歷史紀錄

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

3. 開始之前

您需要準備什麼

  1. 一個狀態良好的 Pionex 帳戶，若您所在的司法管轄區有此要求，需完成完整驗證。

  2. 已啟用雙重身分驗證 — 建立 API 金鑰時必須啟用。

  3. 開發環境 — 任何能發出 HTTPS 請求的工具皆可。Python 3.9+ 或 Node.js 18+ 是最友善的選擇，因為網路上幾乎所有範例都是用其中一種語言寫成的。

  4. 基本熟悉以下事項：

    • JSON（您應該看過 { "key": "value" } 這種格式）

    • 環境變數，或某種能將密鑰放在程式碼之外的方式

    • 在終端機中執行腳本

您不需要準備什麼

  • 伺服器。您可以直接在筆記型電腦上執行。

  • 付費方案。API 完全免費。

  • 密碼學學位。簽名邏輯大約只有十行程式碼。

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

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

  1. 您建立一個請求網址，例如 GET /api/v1/account/balances?timestamp=...

  2. 您從方法、路徑、排序後的查詢參數與請求主體組合出一段「標準訊息」字串。

  3. 您使用 API 密鑰，以 HMAC-SHA256 對該字串進行雜湊，這會產生一個簽名。

  4. 您發送請求時帶上兩個額外的標頭：PIONEX-KEY 與 PIONEX-SIGNATURE。

  5. Pionex 在其伺服器端執行完全相同的雜湊運算並進行比對。如果一致，您就通過驗證了。

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

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

步驟 1 — 開啟 API 管理頁面

  • 網頁版：登入後點選您的個人頭像，選擇 API 管理 — 或直接開啟 https://www.pionex.com/zh-tw/my-account/api。

  • 手機 App：App 內沒有內建的 API 選單。請透過網頁開啟 API 管理 — 在手機瀏覽器中開啟 pionex.com，或點選 此處，即可在 App 內開啟該頁面（App 內建網頁檢視）。

在 API 管理頁面中，您也可以編輯既有金鑰的權限、標籤與 IP 白名單，或刪除（撤銷）金鑰。Secret 無法重新產生或重設 — 如果遺失，請刪除該金鑰並建立新的金鑰。

步驟 2 — 建立新的 API 金鑰

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

  • 標籤 — 取一個具體的名稱，例如 grid-bot-laptop 或 read-only-portfolio。當您之後擁有多支金鑰時，您會慶幸自己這麼做。

  • 權限 — 請見下一節。

  • IP 白名單 （選填，但強烈建議） — 限制金鑰只能從特定 IP 位址使用。您可以輸入多個 IP，以逗號分隔。

步驟 3 — 謹慎選擇權限

權限

允許的操作

建議

讀取

查看餘額、訂單、持倉、成交紀錄

請永遠啟用。任何實用功能都需要此權限。

交易（寫入）

下單與取消訂單、建立 / 調整 / 關閉機器人

僅在您的腳本確實需要交易時才啟用。

Bot API 權限

Bot API 金鑰有兩個獨立的開關：

  • Bot Reading（查看機器人訂單、驗證參數），

  • Bot Trading（建立 / 調整 / 取消機器人）。

無需另外申請存取權限 — 在金鑰上啟用您需要的開關即可

步驟 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 基礎網址

用途

網址

現貨、機器人、Earn（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 回應都有這種外層結構：

Success: { "result": true, "data": { ... }, "timestamp": 1783990000000 }
Error: { "result": false, "code": "APIKEY_LOST", "message": "Apikey lost", "timestamp": ... }

code 與 message 只會在發生錯誤時出現，而且錯誤碼通常是字串（例如 APIKEY_LOST、BOT_INVALID_ARGUMENT）。請注意，錯誤 — 包括身分驗證失敗 — 通常會以 HTTP 200 搭配 result: false 的形式回傳，因此請務必檢查 result，而不是只看 HTTP 狀態。

某些帳戶層級的拒絕會使用不同的結構：數值型的 code、一個 reason 字串，且沒有 result 欄位。例如：

{ "code": 40300951, "reason": "P_TRADING_BOT_OPERATION_IS_FORBIDDEN", "message": "Operation is forbidden, banned for account frozen", "data": null }

如果 result 為 false，或是缺少 result 但存在 code，請將該回應視為失敗。

提示：在讀取 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 容許 ±20 秒的時鐘誤差，但不能更多。如果您的機器時鐘不準，簽名就會失敗，並顯示「timestamp out of recv window」。若您看到此訊息，請同步您的系統時鐘。

5.5 狀態碼

代碼

意義

該怎麼做

200

成功（仍須檢查 result）

繼續處理

400

參數錯誤

檢查拼字、型別與必填欄位

401

未經授權

API 金鑰或簽名錯誤

403

禁止存取

重新檢查金鑰權限。合約直接交易未向任何帳戶開放 — 沒有可申請的合約存取權限。

429

觸發速率限制

請退避。請見「速率限制」章節。

500

伺服器錯誤

以指數退避重試

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

這是最讓新手感到畏懼的章節，但其實不必如此。一旦您看過一個能運作的範例，其餘就都是機械式的步驟。

6.1 標準訊息

對於每一個需要驗證的請求，您都要建立一段字串：

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

規則：

  1. METHOD 為大寫：GET、POST、DELETE。

  2. PATH 是 URL 路徑，包含開頭的斜線，例如 /api/v1/account/balances。

  3. SORTED_QUERY 是查詢字串，其參數依 key 的字母順序排序並經過 URL 編碼。

  4. BODY 是 POST 請求的 JSON 請求主體，不能有任何空白字元。在 Python 中：json.dumps(separators=(',',':'))。在 JavaScript 中，JSON.stringify(obj) 會產生相同的結果。

  5. 任何值為 None 或 undefined 的參數請完全捨棄。絕對不要送出 key=None。

  6. 即使是 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=(",", ":"))  # no spaces     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 計價的投資組合總價值」所需的一切：

  1. 取得餘額。

  2. 對每個非零的幣種，從公開的 ticker 端點取得目前價格。

  3. 加總 (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/allOrders?symbol=BTC_USDT&limit=100&fromId={lastSeenId}

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

8.5 在送出前驗證訂單

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

  • quantity >= minQuantity

  • quantity <= maxQuantity

  • quantity * price >= minAmount（「最小名目價值」規則）

  • 將 quantity 取至 baseScale 位小數，price 取至 quoteScale 位小數

略過這些檢查，是導致訂單被拒絕、進而產生客服工單的第二大常見原因。

8.6 行情資料端點

全部為公開端點，無需簽名：

  • GET /api/v1/market/klines?symbol=BTC_USDT&interval=1M&limit=100 — K 線

  • GET /api/v1/market/tickers — 所有交易對的 24 小時統計

  • GET /api/v1/market/bookTickers — 最優買賣價

  • GET /api/v1/market/depth?symbol=BTC_USDT&limit=10 — 訂單簿

  • GET /api/v1/market/trades?symbol=BTC_USDT&limit=50 — 最近成交

提示：這些端點同樣接受永續合約交易對（例如 BTC_USDT_PERP）。不存在可用的 /uapi/v1/market/... — 合約行情資料一律透過這些 /api/v1 端點取得。

合約行情資料（同樣為公開）：

  • GET /api/v1/market/fundingRates?symbol=BTC_USDT_PERP&limit=500 — 歷史資金費率。limit 預設為 1，因此請自行設定。以 endTime 往更早的資料翻頁。

  • GET /api/v1/market/indexes?symbol=BTC_USDT_PERP — 目前的指數價格、標記價格與下一次資金費率。

  • GET /api/v1/market/indexKlines 與 GET /api/v1/market/markKlines — 指數與標記價格 K 線。僅提供最新的 K 線：這些端點接受 endTime，但會忽略它。

  • GET /api/v1/market/openInterests — 僅提供目前快照，所有交易對在同一個回應中。它不接受任何參數，並會忽略 symbol。

限制與歷史深度。K 線、指數與標記價格 K 線，以及資金費率的 limit 上限皆為 500；若超過此值，會回傳 MARKET_PARAMETER_ERROR。BTC、ETH 與 SOL 的合約日 K 線可回溯至 2023 年初。日內 K 線最多約 10,000 根，以 1 小時 K 線計大約相當於 14 個月。資金費率可回溯至 2023 年初。

9. 進階主題

9.1 現貨網格機器人

網格機器人是一個參數化策略：選擇一個價格區間與網格線數量。每格獲利由這兩項設定決定。機器人在價格下跌時累積持倉、上漲時賣出，從價格震盪中獲利。

POST /api/v1/bot/orders/spotGrid/create{  "base": "BTC",  "quote": "USDT",  "buOrderData": {    "top": "50000",    "bottom": "40000",    "row": 20,    "gridType": "arithmetic",    "quoteTotalInvestment": "1000"  }}

提示：請先以 POST /api/v1/bot/orders/spotGrid/checkParams 驗證（請求主體相同）— 它會回傳最小與最大投資額、建議滑點與預估手續費，且不會動用任何資金。

資金與風險。現貨網格從不借貸，因此您的最大虧損就是您投入的金額。只有兩個呼叫會為運行中的現貨網格增加資金：investIn，以及帶有 quoteInvest 的 adjustParams。借貸只存在於槓桿網格中，而槓桿網格屬於合約網格。現貨網格的回應會包含 loanAmount、interestAmount、liquidatePrice 與 leverage；在現貨網格上，這些值固定分別為 0、0、0 與 1。

機器人開始運行後，您可以：

  • POST /api/v1/bot/orders/spotGrid/adjustParams — 即時變更價格區間（top/bottom）或網格數量（row）

  • POST /api/v1/bot/orders/spotGrid/investIn — 為運行中的機器人追加資金

  • POST /api/v1/bot/orders/spotGrid/profit — 在不停止機器人的情況下提取已累積的獲利

  • POST /api/v1/bot/orders/spotGrid/cancel — 停止機器人。請在此呼叫上設定 closeSellModel（請見下方的關閉現貨網格）

  • GET /api/v1/bot/orders/spotGrid/aiStrategy?base=BTC&quote=USDT — 取得 AI 建議的參數（注意：是 base 與 quote，不是 symbol）

關閉現貨網格。取消呼叫上的 closeSellModel 決定機器人所持有的幣種如何處理：

  • NOT_SELL（預設） — 將幣種與計價幣按原樣退還。

  • TO_QUOTE — 將幣種賣出換成計價幣。

  • TO_USDT — 將幣種賣出換成 USDT。

請在取消呼叫上設定它。透過 API 取消時，您在建立時設定的 closeSellModel 不會被採用。如果取消呼叫中未帶入此參數，則適用 NOT_SELL。訂單的 closeSellModel 欄位在機器人運行期間顯示建立時的值，取消後則顯示實際套用的值。賣出的數量會向下捨入至該幣種的精度；任何剩餘部分會以幣種形式退還。

讀取已關閉的現貨網格。取消後，GET /api/v1/bot/orders/spotGrid/order 會回報退回的內容：

  • unlockUsdtAmount — 關閉時退還的計價幣：quoteAmountBeforeSell 加上任何已賣出幣種的所得，再扣除交易手續費。

  • baseAmount — 未經賣出而退還的幣種。

  • profitWithdrawn — 機器人運行期間已透過 spotGrid/profit 提取的獲利。它不包含在 unlockUsdtAmount 之中。

機器人整個生命週期的淨結果：unlockUsdtAmount + profitWithdrawn + value of returned baseAmount − quoteTotalInvestment。totalFeeInQuote 與 totalFeeInBase 不包含開始時的買入與關閉時的賣出所產生的手續費。

9.2 合約網格機器人

形式與現貨網格相同，並加上 leverage 參數：

POST /api/v1/bot/orders/futuresGrid/create
{
  "base": "BTC.PERP",       // note the .PERP suffix on base
  "quote": "USDT",
  "buOrderData": {
    "top": "65000", "bottom": "60000", "row": 10,
    "gridType": "arithmetic",
    "trend": "long",          // REQUIRED: long | short | no_trend
    "leverage": 2,
    "quoteInvestment": "100"
  }
}

提示：請先以 POST /api/v1/bot/orders/futuresGrid/checkParams 驗證（請求主體相同 — 這裡同樣必須帶入 trend）— 它會回傳最小 / 最大投資額、預估強制平倉價、保證金分配與手續費，且不會動用任何資金。

機器人開始運行後，您可以：

  • POST /api/v1/bot/orders/futuresGrid/adjustParams — 使用 type=adjust_params 時，可變更價格區間（top/bottom）或網格數量（row）；使用 type=invest_in 時，可追加投資

  • POST /api/v1/bot/orders/futuresGrid/reduce — 在機器人持續運行的同時平掉部分持倉（reduceNum 是整數的網格線數量，不是幣種數量）

  • POST /api/v1/bot/orders/futuresGrid/cancel — 停止機器人；選填的 closeSellModel（TO_QUOTE 或 TO_USDT）決定持倉如何處理

  • GET /api/v1/bot/orders/futuresGrid/order?buOrderId=... — 取得完整訂單詳情（狀態、損益、持倉、強制平倉價）

哪個帳戶為機器人提供資金：futuresGrid/create 會取用 quoteInvestment，其來源為您的主帳戶，而不是合約帳戶或交易帳戶。請先轉入主帳戶，否則請求會因 balance insufficient 而被拒絕。

checkParams 不是保證：通過檢核只代表您的設定格式正確，並不代表 create 一定會成功。請另外確認您的主帳戶餘額足以支付 quoteInvestment。

如果 adjustParams 被拒絕，請先查看 code（見常見問題）。您可能遇到的一種原因是機器人的未實現損益為負 — 網格往往正好在虧損時才需要調整區間。您可以在持倉獲利時重試、在 Pionex App 中修改區間，或在建立時啟用移動網格（Trailing Move）。

9.3 Smart Copy 機器人

API 提供的第三種機器人類型 — 由訊號驅動的合約持倉組合：

  • POST /api/v1/bot/orders/smartCopy/checkParams — 建立前驗證投資額與槓桿限制

  • POST /api/v1/bot/orders/smartCopy/create — 注意此端點使用 snake_case 欄位（bu_order_data、quote_total_investment），且需要一個至少包含一項的 portfolio 陣列（base、signal_type、leverage）

  • GET /api/v1/bot/orders/smartCopy/order?buOrderId=... — 完整訂單詳情，包含各項目的持倉

  • POST /api/v1/bot/orders/smartCopy/cancel — 請求主體使用 bu_order_id

相關：POST /api/v1/bot/signal/listener 會發送自訂交易訊號來驅動這些機器人 — 它需要帳戶啟用（請寄信至 service@pionex.com），以及您 API 金鑰上的「Enable Reading」權限。GET /api/v1/bot/kol/selectCopyTradeList?shareCode=... 會列出精選的 KOL 跟單策略。

訊號監聽器是為訊號提供者而設計的。它會將訊號推送到 Pionex 訊號平台，再由該平台轉發給訂閱了該 signalType（您訊號的 UUID）的每一個 Smart Copy 機器人。

在 data 中：action 為 buy 代表開倉，為 sell 代表平倉。position_size 是以比例表示的目標持倉："1" 代表 100%，"0" 則代表平倉。contracts 是合約數量。

9.4 合約直接交易

請注意 /uapi/v1 路徑前綴：

GET  /uapi/v1/account/balances
GET  /uapi/v1/account/positions
GET  /uapi/v1/account/detail
GET  /uapi/v1/account/leverage?symbol=BTC_USDT_PERP
GET  /uapi/v1/trade/openOrders
GET  /uapi/v1/trade/fills?symbol=BTC_USDT_PERP
GET  /uapi/v1/trade/fundingFee?symbol=BTC_USDT_PERP
GET  /uapi/v1/trade/isolatedMode?symbol=BTC_USDT_PERP

注意：上述所有 GET（讀取）端點，目前任何 API 金鑰皆可使用。寫入操作（合約下單、變更槓桿 / 保證金模式）在合約直接交易仍在開發期間受到限制。

9.5 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.6 WebSocket 基本介紹

wss://ws.pionex.com/wsPub

兩種頻道類別：

  • 公開（不需身分驗證） — ticker、kline、depth、trade

  • 私有（需身分驗證） — 餘額更新、訂單更新、持倉更新

以 JSON 訊息進行訂閱：

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

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

10. 速率限制與可靠性

10.1 您會收到什麼回應

Pionex 不會回傳 X-RateLimit-* 標頭。限制為每個 IP 每秒 10 次請求，以及每個帳戶（私有端點）每秒 10 次請求，且每個端點會依其權重消耗該額度。超過限制會回傳 HTTP 429 — 請先退避再重試。

10.2 如何保持安全

  1. 不要全速輪詢。每 200 毫秒呼叫一次 GET /openOrders 是不必要的；對大多數策略而言，每秒一次就綽綽有餘。

  2. 以 WebSocket 接收由變動驅動的資料。不要為了取得價格 tick 而輪詢 — 直接訂閱即可。

  3. 對 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")

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

11. 常見問題

開始上手

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

答：不需要 — 現貨、Earn 與 Bot API，建立金鑰即可開始；Bot API 只需在金鑰上啟用 Bot Reading / Bot Trading 權限。合約直接交易不向任何帳戶開放，也沒有申請或候補名單，但合約的讀取類端點任何 API 金鑰皆可使用。Earn 端點處於測試版，可能並非每個地區都已啟用。

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

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

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

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

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

答：可以 — 它是標準的 REST/WebSocket API，因此任何能發出已簽名 HTTPS 請求的工具都能與之溝通，包括您自己的腳本、伺服器與第三方工具。至於某個特定的第三方平台是否可用，取決於該平台是否已在其端建置 Pionex 支援 — API 本身不限制誰可以呼叫它，但雙方必須使用相同的整合方式。請查閱該平台自己的文件，確認它是否列出 Pionex，以及它預期您使用哪一種整合方式。在 Pionex 這一端，支援的對接點為本指南中的 Trade/Bot/Wallet/Earn 端點，以及用於 TradingView webhook 的 Signal Bot。

問：我可以將 Pionex API 連接到 Bybit 或 Binance 等其他加密貨幣交易所嗎？

答：不可以。Pionex API 並非用於連接 Bybit、Binance 等其他加密貨幣交易所。它僅設計用於與您自己的 Pionex 帳戶互動 — 下單 / 管理您自己的訂單、機器人和持倉 — 而不用於在其他交易所帳戶之間進行橋接、鏡像或套利交易。

身分驗證

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

答：請依序檢查五件事：

  1. 查詢參數是否依字母順序排序？

  2. timestamp 是否放在查詢字串中，而非請求主體中？

  3. 您簽名的請求主體是否與您送出的請求主體完全一致（沒有多餘的空白字元）？

  4. 您的機器時鐘是否在真實時間的幾秒之內？

  5. 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。以 30,000 美元的價格下 0.0001 BTC 的訂單，名目價值為 3 美元，通常低於一般 10 美元的最小值。

問：我該如何讓下單具備冪等性？
答：將 clientOrderId 設為唯一值（例如 UUID）。如果您以相同的 clientOrderId 重試，Pionex 不會重複建單。

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

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

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

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

機器人

問：我可以建立與 App 裡相同的所有機器人類型嗎？
答：API 恰好開放三種機器人類型：現貨網格、合約網格與 Smart Copy。App 中其他所有機器人類型（Martingale、DCA、Rebalancing、Infinity Grid、TWAP、套利、智慧交易）僅限 UI 使用，沒有 API 端點。

GET /api/v1/bot/orders 只會回傳 API 支援的機器人類型。它們的 buOrderType 值為 spot_grid、futures_grid、future_hedge_grid（全倉合約網格）與 smart_copy。其他類型的機器人不會被回傳，即使它們正在您的帳戶上運行。若將不支援的類型作為篩選條件傳入，會回傳 BOT_INVALID_ARGUMENT。

槓桿網格屬於合約網格，會以 futures_grid 回傳。

簡易合約沒有機器人端點。其持有資產僅會出現在 GET /api/v1/wallet/balancesFull 中，位於 botAccount.detail[] 之下，且帶有 type: "futures_lite"。每筆項目包含 buOrderId、baseList、investmentAmount 與 profit。無法取得狀態、訂單或持倉的詳細資訊。

問：我可以調整運行中的機器人嗎？
答：可以。adjustParams 讓您能夠在不取消的情況下變更價格區間（top/bottom）與網格數量（row），或追加投資。在現貨網格上，您還可以使用 investIn（追加資金）與 profit（提取獲利）；在合約網格上，您可以 reduce 持倉。沒有獲利率參數 — 每格獲利由區間與網格數量決定。

問：我收到 BOT_INTERNAL_ERROR，但看不出原因。
答：請查看 code 欄位。它現在會告訴您屬於以下兩種情況中的哪一種。

code

含義

該怎麼做

BOT_INVALID_ARGUMENT

您的請求被拒絕。message 會說明原因 — 例如 balance insufficient。

修正 message 所指出的問題，然後重新發送。

BOT_INTERNAL_ERROR

我們這邊發生故障。message 固定為 Internal error。

請退避重試。若持續發生，請聯繫客服並提供您的時間戳記。

futuresGrid/create 被拒絕的常見原因，是您主帳戶中的計價幣不足。建立機器人會從您的主帳戶扣款，而不是從合約帳戶或交易帳戶。

如果 BOT_INTERNAL_ERROR 出現在 message 本應說明原因的情況下，請將您的時間戳記提供給客服。

問：reduce 與 cancel 有什麼不同？

答：reduce 會平掉一定百分比的持倉，但機器人會繼續運行。cancel 則會完全停止機器人。

問：aiStrategy 端點實際上在做什麼？
答：它會根據近期波動性，為某個交易對回傳 Pionex 建議的網格參數。請把它當作起點，而非鐵律 — 部署資金前請先自行檢視。

合約

問：如何取得 Futures API 的存取權限？

答：Futures API 直接交易不向任何帳戶開放。它仍在內部開發中，且沒有申請、候補名單或搶先體驗流程 — 無法申請存取權限。

問：透過 API 下合約單時出現「TRADE_TYPE_DENIED: user denied, not in whitelist」，是什麼原因？
答：透過 API 直接進行合約交易（合約下單、變更槓桿或保證金模式）目前尚未向任何帳戶開放。此功能仍在內部開發中，也沒有申請、候補名單或搶先體驗的管道，因此錯誤訊息中的「whitelist」並不代表可以申請開通。目前也沒有公布開放時間。合約的讀取類端點則任何 API 金鑰皆可使用。若想自動化合約交易，目前可以透過 Bot API 建立和管理合約網格機器人，或使用 Signal Bot 以 TradingView webhook 等外部訊號觸發交易。

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

答：

逐倉 — 只有您分配給該持倉的保證金可能虧損。

全倉 — 您整個合約錢包都會作為該持倉的擔保。對學習者而言，逐倉較為安全。

單向與雙向（Hedge）持倉模式？

答：

單向 — 每個交易對只有一個持倉；開反向倉位會減倉或平倉。雙向（Hedge） — 多空可同時並存。大多數交易者應該從單向開始。

問：資金費率如何顯示？

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

Earn

問：雙幣投資有保本嗎？

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

問：我可以提前取消雙幣投資嗎？
答：通常不行。資金會在產品期間內鎖定。請據此規劃您的流動性。

操作面

問：我該規劃什麼樣的速率限制？
答：請以每個 IP 與每個帳戶每秒 10 次請求來規劃（Pionex 不會回傳 X-RateLimit-* 標頭）。一個保守的起點是：每類端點每秒不超過五次請求，並在收到 429 回應時採用指數退避。

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

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

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

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

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

安全性

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

答：

  1. 開啟 API 管理頁面並立即撤銷該金鑰。

  2. 稽核近期活動（訂單，若已啟用則包含提幣）。

  3. 以新的標籤建立新的金鑰。

  4. 在您的程式碼庫與 commit 歷史中搜尋外洩的密鑰，並輪換所有相關憑證。

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

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

問：我可以啟用儲值 / 提幣權限嗎？
答：API 管理中沒有儲值或提幣功能。目前，API 端點僅可用於交易與機器人。

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

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

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

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

12. 故障排除速查表

症狀

最可能的原因

解決方式

每個請求都收到 401

金鑰錯誤或簽名不一致

重新檢查排序順序、請求主體位元組、標頭

只有 POST 才收到 401

請求主體在簽名後被重新序列化

將您簽名過的完全相同字串作為請求主體送出

result: false 並帶有 timestamp 錯誤

時鐘漂移

同步您的系統時間

403

權限未授予

重新檢查金鑰權限。合約直接交易未向任何帳戶開放。

429

觸發速率限制（自最後一次請求起最長 24 小時）

加入退避；降低輪詢頻率

訂單被拒絕 — 最小名目價值

quantity * price < minAmount

提高下單量

訂單被拒絕 — 精度錯誤

小數位過多

取至 baseScale / quoteScale 位數

機器人無法啟動 — BOT_INVALID_ARGUMENT

message 會指出原因，例如 balance insufficient

修正 message 所指出的問題。若為資金問題，請向主帳戶補充資金 — 合約帳戶與交易帳戶不計入

機器人無法啟動 — BOT_INTERNAL_ERROR

我們這邊的故障

退避後重試；若持續發生，請聯繫客服

機器人無法啟動 — P_TRADING_BOT_OPERATION_IS_FORBIDDEN，「account frozen」

帳戶受到限制

請聯繫客服。重試無濟於事

WebSocket 斷線

正常現象，或防火牆閒置逾時

以退避方式重連；每 30 秒 ping 一次

在 curl 中簽名正常，在程式碼中卻不行

程式庫自動編碼了請求主體

送出原始的已簽名位元組

13. 安全最佳實踐

  1. 每個用途使用一支金鑰。更容易撤銷，也更容易稽核。

  2. 最小權限原則。預設為唯讀；僅在需要時才啟用交易權限。

  3. 對任何能動用資金或下單的金鑰設定 IP 白名單。

  4. 絕不記錄密鑰。從請求記錄中移除驗證標頭。

  5. 絕不在用戶端程式碼放入密鑰。瀏覽器、行動應用程式 — 請假設任何送到使用者裝置上的程式碼都是公開可讀的。

  6. 定期輪換。每 90 天是合理的頻率；一有懷疑就立即輪換。

  7. 監控用量。Pionex 會顯示 API 金鑰的用量統計 — 請每週檢視一次。

  8. 檢查程式碼中是否有不慎提交的內容。git-secrets、trufflehog 或 GitHub 密鑰掃描等工具能及早發現外洩。

  9. 在正式環境使用密鑰管理工具：AWS Secrets Manager、HashiCorp Vault、1Password CLI、Doppler — 任何方式都比把明文放在磁碟上好。

  10. 以小額帳戶測試。不要在第一天就把全新的交易機器人對準您的主要帳戶。

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）

在到期時決定採用上漲或下跌 APY 的價格門檻。

15. 接下來去哪裡

建議的學習路徑：

  1. 建立第 7 節中的唯讀投資組合腳本。

  2. 以 clientOrderId 重試機制，下您的第一張 10 美元限價單。

  3. 啟動一個迷你現貨網格機器人（投入 50 美元、價格區間窄），並觀察一週。

  4. 加上 WebSocket 私有頻道，在成交發生時即時記錄。

  5. 在您已操作現貨機器人至少一個月之後，再轉往合約。

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

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

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

API 對合約交易與交易機器人有哪些限制？

Pionex 提供的 API 旨在方便交易活動，但在合約交易與交易機器人的使用上有特定限制。以下是這些限制的詳細說明：

  • 現貨 API（手動交易）

API 目前僅支援現貨交易。這表示使用者可以透過 API 對現貨市場中可交易的資產執行交易。現貨交易是指以當前市價即時交換資產。

  • 合約 API（手動交易）排除事項

合約 API 直接交易不可用 — 它仍在內部開發中，尚未向任何帳戶開放。沒有申請或候補名單流程。可用的替代方案：

  • Bot API：包含支援建立與關閉合約網格機器人，可作為自動化合約策略的暫時性解決方案。

  • Signal Bot：您也可以使用 Signal Bot，根據外部觸發條件或自訂訊號執行交易。

祝您開發順利。

相關文章
是否回答了您的問題？