# FAQs

> **更新时间：** 2026-04-14 <br/>
> **文档摘要：** 本指南旨在协助开发者快速接入 WEEX 合约 API，解决权限配置、频率限制及交易过程中的常见技术问题。

---

## 1. 账号与权限配置

### API Key 权限类型说明

在创建 API Key 时，请根据您的业务需求勾选对应的权限选项：

| 权限名称         | 描述                                             | 适用场景            |
|:-------------|:-----------------------------------------------|:----------------|
| **Readonly** | **只读权限**。仅允许调用查询类接口（如获取余额、持仓、成交历史）。无法进行任何交易操作。 | 资产监控、账单同步、行情分析。 |
| **Futures**  | **合约交易权限**。仅允许在合约市场开平仓、设置止盈止损及查询合约仓位。          | 合约对冲、高频合约策略。    |

<strong>注：权限相互独立，如需进行合约交易操作，请确保已勾选 Futures 权限。</strong>

### 为什么我的 API 权限被禁用或报错 API Restricted？
* **风控触发：** 若账户触发平台安全风控（如异常登录、高频无效请求），API 权限可能被自动禁用。
* **解禁流程：** 请联系客服。
* **生效时间：** 新创建或修改权限后的 API Key，通常需要 **15 分钟** 左右在系统全局生效。

### 创建 API Key 时的安全建议
* **Passphrase (口令)：** 设置 API Passphrase 时 **不可包含特殊符号**（仅限字母+数字）。
* **IP 白名单：** 建议开启 IP 白名单以增强安全性。

---

## 2. 频率限制 (Rate Limits)

WEEX 对不同类型的接口设有严格的权重限制，以确保系统稳定性。若超过限制，系统将返回 `HTTP 429` 错误。

| 业务类型          | 操作类型       | 频率限制               |
|:--------------|:-----------|:-------------------|
| **合约交易**      | 下单 (Order) | 300次 / 分钟          |
| **网络连接**      | REST接口     | 500 权重 / 10s / 每IP |
| **WebSocket** | 最大连接数      | 20                 |

---

## 3. 模拟下单接口 (NEW: Paper Trading)

为了方便开发者进行策略调试及对冲模式测试，WEEX 已正式上线 **模拟下单接口**。您可以在不消耗真实资产的情况下，全面模拟交易流程。

### 新增 Demo 接口列表：
* **获取账户余额**：查看账户模拟资金 (SUSDT)。 <br/> `GET /capi/v3/sim/balance`
* **获取全部持仓**：支持查看多空双向（对冲模式）持仓。 <br/> `GET /capi/v3/sim/position/allPosition`
* **下单接口**：支持市价、限价等多种下单指令。 <br/> `POST /capi/v3/sim/order`
* **获取历史订单**：追踪及分析历史模拟交易记录。 <br/> `GET /capi/v3/sim/order/history`

---

## 4. 常见技术问题 (Q&A)

### Q1: 为什么下单返回 `-1052` (Insufficient permissions)？
**答：** 该错误通常由以下原因引起：
1. **权限勾选：** 未在 API 管理页面勾选“合约”交易权限。
2. **交易对不支持：** 部分合约交易对目前暂不支持 API 下单。
3. **接口版本：** 建议优先使用 **V3 接口**，V1/V2 将下架。

### Q2: 为什么 WebSocket 连接返回 403 错误？
**答：** 建立 WebSocket 连接时，**必须在 Header 中包含 `User-Agent` 信息**（内容可自定义）。若缺少该字段，请求将被防火墙拦截。

### Q3: 撤单返回 `-1054`？
**答：** 订单不存在。通常是撤单时提供的单号错误。

### Q4: 如何获取全部可交易的 Symbol（币对）？
**答：** 访问 [获取合约交易对接口](/zh-CN/products/futures/Market_API/GetApiTradingSymbols)。

### Q5: 请求返回 404？
**答：** 检查路径。例如获取所有仓位应使用 `GET /capi/v3/account/position/allPosition`。

### Q6: 更改杠杆会触发 WebSocket 推送吗？
**答：** 会。仅下单、平仓和调整保证金会触发更新。

### Q7: 支持 TradingView 或 FIX API 吗？
**答：** 目前均不支持。

---

## 5. 常见问题

- **Q1：如何获取API相关问题的技术支持？**

  A : 可以加入官方API技术支持群来反馈API问题，管理员会答复您。https://t.me/+7jac6zttXxZjOTRl

- **Q2：API接口的限频规则是什么？**

  A : 1. 各api端口频率限制规则在文档有标注；2. 各API接口的限频互相独立计算；

- **Q3：API 接口中的 symbol 是否区分大小写？**

  A : symbol 区分大小写，必须全部使用大写。

- **Q4：如果我忘记了API key的passphrase怎么办？**

  A : API key的passphrase不支持更改。需要您重新创建API key。

---

## 6. 更多支持 (Technical Support)

如果您在开发过程中遇到无法解决的技术难题，可以通过以下渠道获取支持：

* **官方 API 文档：** [WEEX API Documentation](/zh-CN/products/futures/changelog)
* **Telegram 技术对接群：**
    * **[WEEX API 技术对接群 (中文)](https://t.me/+7jac6zttXxZjOTRl)**
    * **[WEEX API Tech Support (English)](https://t.me/+Y72JdNeHcUw3NWQ1)**

---

:::tip 开发者提示
1. API 交易涉及高风险，请务必在代码中做好完善的错误处理逻辑。
2. 严禁将 API Key 和 Secret Key 泄露给第三方。
3. 本文档内容可能随系统升级而调整，请以最新的官方 API 文档为准。
:::