快速入门

1. 创建 API 密钥

• API 名称: 为您的密钥设置一个易于识别的名称。
• API 权限: 根据您的需求勾选相应权限。为安全起见，我们建议您仅授予必要的权限。权限默认为“读取”。
• API 有效期: 选择一个合适的有效期。
• IP 地址绑定: 为了最大限度地保障您的资产安全，强烈建议您绑定 IP 地址。您可以填写最多10个 IP 地址，并用英文逗号隔开。

⚠️ 重要提示：请立即备份您的私有密钥！

私有密钥 (Secret Key) 仅在创建时显示一次，平台不会以任何形式再次存储或展示它。请务必将其保存在安全可靠的地方。如果遗忘或泄露，您需要删除该 API 密钥并重新创建一个。

2. 理解 API 权限

• 读取: 允许查询个人订单、余额、资产流水等私有信息。
• 现货交易: 允许创建和取消现货订单。
• 永续合约交易: 允许创建和取消合约订单，调整仓位设置等。
• 资金划转: 允许在您的钱包账户、现货账户和合约账户之间进行资金划转。

3. API 调用示例

curl -X GET 'https://dex-api.benpay.com/v1/market/timestamp'

{ 
"success": true,
 "data": 1754024820000 
}

API 认证机制

API 权限与接口分类

接口的认证类型

• ✅ 公开接口 (无需签名): 所有路径以 /v1/market/ 开头的接口均为公开行情接口。任何人都可以直接调用它们来获取市场数据，无需 API 密钥和请求签名。
• 🔐 私有接口 (需要签名): 所有涉及用户个人信息、资产、交易和划转的接口均为私有接口。调用这些接口必须使用您的 API 密钥进行签名认证。

权限与接口功能映射关系

接口分类详解

行情接口 (公开，无需签名)

• GET /v1/market/trades: 获取所有资产及交易对信息。
• GET /v1/market/timestamp: 获取服务器时间戳。
• GET /v1/market/ticks/{symbol}: 获取交易对最新成交数据。
• GET /v1/market/prices: 获取所有币种的市场价格（24小时）。
• GET /v1/market/orderBook/{symbol}: 获取指定交易对的深度订单薄。
• GET /v1/market/indexes: 获取所有指数的最新价格。
• GET /v1/market/indexes/{name}: 获取单个指数的历史价格。
• GET /v1/market/indexes/indexValue: 获取单个指数的值。
• GET /v1/market/indexPrices: 获取永续合约的最新指数价格。
• GET /v1/market/errorCodes: 获取所有错误码。
• GET /v1/market/bars/{symbol}/{type}: 获取指定交易对的 K 线数据。
• GET /v1/market/positions: 获取当前所有用户未平仓头寸的总额。

用户接口 (私有，需签名)

• GET /v1/users/me: (需读取权限) 获取您当前的登录信息。

现货接口 (私有，需签名)

• GET /v1/spots/orders/{orderId}: (需读取权限) 根据 ID 查询订单详情。
• GET /v1/spots/orders/{orderId}/matches: (需读取权限) 根据 ID 查询订单的成交详情。
• GET /v1/spots/orders/open: (需读取权限) 查询您当前所有未成交的现货订单。
• GET /v1/spots/orders/open/{orderId}: (需读取权限) 根据 ID 查询活动订单。
• GET /v1/spots/orders/closed: (需读取权限) 按月查询历史现货订单。
• GET /v1/spots/match/clearings: (需读取权限) 分页查询用户订单的清算记录。
• GET /v1/spots/fee/rate: (需读取权限) 查询现货交易手续费率。
• GET /v1/spots/balances: (需读取权限) 查询您的现货账户余额。
• POST /v1/spots/orders: (需现货交易权限) 创建一笔新的现货订单。
• POST /v1/spots/orders/{idOrSymbol}/cancel: (需现货交易权限) 取消指定的现货订单。

合约接口 (私有，需签名)

• GET /v1/contracts/positions: (需读取权限) 查询您所有的合约仓位。
• GET /v1/contracts/positions/{symbol}: (需读取权限) 根据 Symbol 查询单个仓位。
• GET /v1/contracts/orders/{orderId}: (需读取权限) 根据订单 ID 查询订单。
• GET /v1/contracts/orders/{orderId}/matches: (需读取权限) 查询订单成交记录。
• GET /v1/contracts/orders/open: (需读取权限) 查询您当前所有未成交的合约订单。
• GET /v1/contracts/orders/open/{orderId}: (需读取权限) 根据 ID 查询活动订单。
• GET /v1/contracts/orders/closed: (需读取权限) 查询历史合约订单。
• GET /v1/contracts/match/clearings: (需读取权限) 分页查询用户订单的清算记录。
• GET /v1/contracts/fund/flows: (需读取权限) 分页查询用户资金流水记录。
• GET /v1/contracts/fee/rate: (需读取权限) 查询期货交易手续费率。
• GET /v1/contracts/clearings/positions: (需读取权限) 查询仓位清算历史记录。
• GET /v1/contracts/balances: (需读取权限) 查询您的合约账户余额。
• POST /v1/contracts/orders: (需永续合约交易权限) 创建一笔新的合约订单。
• POST /v1/contracts/orders/{idOrSymbol}/cancel: (需永续合约交易权限) 取消指定的合约订单。
• POST /v1/contracts/orders/cancel: (需永续合约交易权限) 取消全部合约订单。
• POST /v1/contracts/positions/{symbol}/settings: (需永续合约交易权限) 设定仓位模式与杠杆。
• POST /v1/contracts/positions/{symbol}/margin: (需永续合约交易权限) 对一个仓位调整保证金。

出入金接口 (私有，需签名)

• GET /v1/wallet/withdraws: (需读取权限) 查询提现请求列表。
• GET /v1/wallet/queryWithdrawById: (需读取权限) 根据 ID 查询提现请求。
• GET /v1/wallet/flows: (需读取权限) 查询钱包账户流水信息。
• GET /v1/wallet/deposits: (需读取权限) 查询充值日志列表。

资金划转接口 (私有，需签名)

• GET /v1/wallet/currencyMappings: (需读取权限) 获取币种映射相关信息。
• GET /v1/wallet/balances: (需读取权限) 查询您的钱包账户余额。
• GET /v1/transfer/{transferId}/request: (需读取权限) 根据转账 ID 查询转账请求信息。
• GET /v1/transfer/{transferId}/log: (需读取权限) 根据转账 ID 查询转账日志。
• GET /v1/transfer/transfer/logs: (需读取权限) 分页查询转账日志列表。
• POST /v1/transfer/request/wallet/to/spots: (需资金划转权限) 从钱包账户划转至现货账户。
• POST /v1/transfer/request/spots/to/wallet: (需资金划转权限) 从现货账户划转至钱包账户。
• POST /v1/transfer/request/wallet/to/contracts: (需资金划转权限) 从钱包账户划转至合约账户。
• POST /v1/transfer/request/contracts/to/wallet: (需资金划转权限) 从合约账户划转至钱包账户。

错误码参考

{
"success": false, 
"data": null,
"error": "HEADER_INVALID",
"errorField": "API-TIMESTAMP",
"errorMessage": "Header API-TIMESTAMP is not accurate."
 }

安全与使用规范

• 妥善保管密钥： 您的 API 密钥（尤其是 Secret Key）拥有操作您账户的权限。请像对待密码一样保管它们，切勿泄露给任何人或在不安全的代码中硬编码。
• 使用 IP 白名单： 强烈建议为您的每一个 API 密钥绑定固定的 IP 地址。这能极大地降低密钥泄露后被盗用的风险。
• 遵循最小权限原则： 在创建 API 密钥时，只授予您应用所需的最小权限。例如，如果一个应用只需要查询市场数据，就不要授予它交易或划转的权限。
• 定期更换密钥： 定期删除不再使用的旧密钥，并可以考虑周期性地更换仍在使用的密钥，以提升安全性。
• 留意官方信息： 请勿将您的密钥信息透露给任何自称是 BenPay 官方客服的人员。