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 对所有账户开放，无需申请。只需在 API 密钥上启用 Bot Reading / Bot Trading 权限即可。

Pionex 的招牌功能。以程序化方式启动并调整交易机器人。

现货网格机器人 —— 在价格区间内反复低买高卖
合约网格机器人 —— 同样概念，加上杠杆
AI 策略 —— 让 Pionex 为您建议网格参数
实时调整运行中机器人的收益率或价格区间
按百分比减仓，或完全停止机器人

2.3 Futures API —— 合约交易

Futures API 的下单功能目前不可用，仍处于内部开发阶段，尚未向任何账户开放，也没有任何申请、候补或抢先体验流程。合约自动化交易请改用「Bot API」（合约网格）或「Signal Bot」。读取类端点维持公开，任何 API 密钥均可使用。

永续合约搭配杠杆（最大倍数依交易对而定）。

注意：Futures API 下单功能不可用，仍处于内部开发阶段，尚未向任何账户开放。读取类端点（余额、持仓、挂单、成交、资金费率、保证金模式、杠杆）任何 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 管理页面

网页版： 登录后点击个人头像,选择 API 管理;或直接打开 API 管理网页 https://www.pionex.com/zh-cn/my-account/api
手机 App： App 内没有专门的 API 菜单入口。请通过网页打开 API 管理 —— 在手机浏览器打开 pionex.com,或点击 点此打开,即可在 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 基础网址

用途	网址
现货、机器人、理财（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 位小数

跳过这些检查是订单被拒绝的第二大常见原因。

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 端点获取。

9. 进阶主题

9.1 现货网格机器人

网格机器人是一个参数化策略：选择价格区间、网格线数量以及每格收益率。机器人在价格下跌时累积仓位、上涨时卖出，从价格震荡中获利。

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",   ... }

注意：合约网格机器人通过 Bot API 提供，无需另外申请合约权限，只需在 API 密钥上启用 Bot Trading 权限。

哪个账户为机器人提供资金：创建合约网格机器人时，投资金额会从您的主账户扣除，而不是合约账户或交易账户。请先将资金转入主账户，否则请求会被拒绝并返回 balance insufficient。

checkParams 不是成功保证：通过校验只代表参数格式正确，并不代表 create 一定成功。请另外确认主账户余额足以支付投资金额。

如果 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 可推送自定义交易信号来驱动这些机器人。

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 您会收到什么

每个响应都包含以下请求头：

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 内部。

问：我可以将 Pionex API 连接到 Bybit 或 Binance 等其他加密货币交易所吗？

答：不可以。Pionex API 并非用于连接 Bybit、Binance 等其他加密货币交易所。它仅用于与您自己的 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 对该交易对建议的网格参数。请把它当作起点，而非铁律 —— 部署资金前请自行查看。

问：我收到 BOT_INTERNAL_ERROR，但看不出原因。

答：请查看 code 字段，它现在会告诉您属于以下两种情况中的哪一种。

code	含义	处理方式
`BOT_INVALID_ARGUMENT`	请求被拒绝。`message` 会说明原因，例如 `balance insufficient`。	按 `message` 的提示修正后重新发送。
`BOT_INTERNAL_ERROR`	我们这边出现故障。`message` 固定为 `Internal error`。	请退避重试。若持续出现，请联系客服并提供时间戳。

合约网格创建被拒绝的常见原因，是主账户中计价币种余额不足。创建机器人会从主账户扣款，而不是合约账户或交易账户。

如果 message 本应说明原因，却仍然返回 BOT_INTERNAL_ERROR，请联系客服并提供时间戳。

合约

问：如何申请合约 API 访问权限？

答：合约 API 下单功能对所有账户均不可用，仍处于内部开发阶段，没有任何申请、候补或抢先体验流程，联系客服也无法开通。若您在合约下单端点收到 403 错误，这是预期行为。读取类端点（余额、持仓、挂单、成交、资金费率、保证金模式、杠杆）任何 API 密钥均可使用；合约自动化交易请改用 Bot API（合约网格）或 Signal Bot。

问：逐仓与全仓保证金的差别是什么？

答：逐仓 —— 只有您分配给该仓位的保证金会亏损。全仓 —— 您整个合约钱包都会为该仓位作为担保。新手建议从逐仓开始，较为安全。

问：单向 vs 双向持仓模式？

答：单向 —— 每个交易对只有一个仓位；开反向仓位会减仓或平仓。双向 —— 多空可同时存在。大多数交易者应该从单向开始。

问：资金费率如何显示？

答：周期性结算（通常每八小时一次，但请查验交易对）。使用 GET /uapi/v1/trade/fundingFee 拉取历史记录。

Earn

问：双币投资有保本吗？

答：没有。它有「下跌 APY」作为收益下限，但本金本身有风险。订阅前请阅读每个产品的详细说明。

问：我可以提前取消双币投资吗？

答：通常不行。资金会在产品期间内锁定。请依此规划流动性。

运维

问：我该规划什么样的速率限制？

答：请查看 X-RateLimit-Limit 了解您账户的限制。一个保守的起点是：每类端点每秒不超过 5 次请求，并在 429 时采用指数退避。

问：我该如何处理 5xx 错误？

答：用指数退避加上抖动进行重试。重点是：重试 POST 之前，先查询状态以确认先前的请求是否实际成功 —— 服务器错误并不总是代表动作失败了。

问：我的 WebSocket 一直断线。是哪里出了问题吗？

答：这在网络层级是正常的。请实现：每 30 秒 ping 一次、以退避方式自动重连、重连时重新订阅所有主题。

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

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

安全性

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

答：

打开 API 管理页面立刻撤销该密钥。
检查近期活动（订单，如有开启提币权限的话也包含提币）。
以新的标签创建新密钥。
在您的代码库与 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` 位数
机器人无法启动 — `BOT_INVALID_ARGUMENT`	`message` 会说明原因，例如 `balance insufficient`	按 `message` 的提示修正。若为余额问题，请向主账户充值 —— 合约与交易账户不计入
机器人无法启动 — `BOT_INTERNAL_ERROR`	我们这边的故障	退避重试；若持续出现请联系客服
WebSocket 断线	正常现象或防火墙闲置超时	采用退避方式重连；每 30 秒 ping 一次
在 curl 中签名正常，在代码中却不行	库自动编码请求体	发送原始已签名字节

13. 安全最佳实践

每个用途使用一个密钥。更容易撤销、更容易审计。
最小权限原则。默认为只读；仅在需要时启用 Trade。
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：完整指南