跳转到主要内容

Pionex API：完整指南

一份对使用者友善的介绍、逐步教学与常见问题集 —— 从您的第一个请求到正式交易上线。

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 完全免费。

  • 密码学学位。签名逻辑大约只有十行代码。

心智模型：一个请求如何运作

每个经过身份验证的呼叫都遵循相同的五步模式：

  1. 您建立一个请求网址，例如 GET /api/v1/account/balances?timestamp=...

  2. 您从方法、路径、排序后的查询参数与请求主体组合出一段「标准消息」字符串。

  3. 您用 HMAC-SHA256 与您的 API 密钥对该字符串进行哈希。这会产生一个签名。

  4. 您发送请求时带上两个额外的标头：PIONEX-KEY 与 PIONEX-SIGNATURE。

  5. Pionex 在服务器端执行完全相同的哈希运算并进行比对。如果一致，您就通过了验证。

关键概念：签名能证明您知道密钥，但密钥本身从未透过网络传输。

4. 建立您的第一支 API 密钥

步骤 1 —— 打开 API 管理页面

  1. 登录 Pionex。

  2. 点击您的个人头像。

  3. 选择「API 管理」。

App： Click Here

网页： https://www.pionex.com/zh-cn/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}

规则：

  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=(",", ":"))  # 不可有空白     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/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 内部。

验证

问：我的签名一直显示无效。该从哪里开始检查？

答：依序检查五件事：

  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。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 一次、以退避方式自动重连、重连时重新订阅所有主题。

问：我该如何订阅多个交易对？

答：传送多则订阅消息，或使用该频道支持的批次订阅形式。每个主题彼此独立。

安全性

问：我认为我的密钥泄露了。我该怎么做？

答：

  1. 打开 API 管理页面立刻撤销该密钥。

  2. 检查近期活动（订单，如有开启提币权限的话也包含提币）。

  3. 以新的标签建立新密钥。

  4. 在您的代码库与 commit 历史中搜索泄露的密钥，并轮换所有相关凭证。

问：我该把 API Key 或密钥提交到 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. 接下来去哪里

建议的学习路径：

  1. 建立第 7 节的只读投资组合脚本。

  2. 用 clientOrderId 重试机制下您的第一张 10 美元限价单。

  3. 启动一个迷你现货网格机器人（50 美元投入、窄价格区间），观察一周。

  4. 加上 WebSocket 私有频道，即时记录成交事件。

  5. 在您已操作现货机器人至少一个月后，再进入合约。

官方 Pionex 文档包含最新端点清单与任何测试版信息：https://www.pionex.com/docs/

如果您对 API 还有其他疑问，我们诚挚邀请您加入 Telegram 群组以取得更好的协助：https://t.me/pionexapi

最后一个小提示：当您撞墙时，最有用的调试步骤几乎总是把您的标准消息字符串与签名，跟一个能正常运作的 curl 示例并排打印出来，找出哪一个字符不一样。那一个字符几乎一定就是 bug 所在。

祝您交易顺利！

这是否解答了您的问题？