快速入门

创建 API 密钥

在“API管理”页面创建密钥时，您需要配置以下信息：

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

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

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

理解 API 权限

在创建 API 密钥时，您可以分配四种不同的权限：

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

API 调用示例

您可以通过调用一个无需密钥的公开接口来测试 API 的连通性，例如获取服务器时间戳：

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

调用成功将返回服务器的毫秒级时间戳，证明您已成功连接到 BenPay DEX API 服务。

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

API 认证机制

为了保障您账户的安全，所有访问私有数据（如个人账户信息、交易操作等）的 API 请求都必须经过签名认证。

Base URL: https://dex-api.benpay.com

认证流程概览

您需要将特定的请求信息与您的 私有密钥 (Secret Key) 结合，使用 HMAC SHA256 算法生成一个唯一的签名。然后，将此签名以及您的 访问密钥 (API Key) 等信息放入请求头 (Headers) 中发送给服务器。服务器会以同样的方式生成签名并进行比对，若一致则验证通过。

所有需要认证的私有接口，都必须在 HTTP 请求头 (Headers) 中包含以下信息：

Header	描述	示例值
API-KEY	您的访问密钥 (Access Key)。	AAAAACcVAAABnztMqrATYmlG5XNpNnyY
API-TIMESTAMP	当前的 UTC 时间戳（毫秒）。	1751876801442
API-SIGNATURE-METHOD	签名算法，固定为 HmacSHA256。	HmacSHA256
API-SIGNATURE-VERSION	签名版本，固定为 1。	1
API-Signature	根据规则生成的动态请求签名。	aea0677b6b...

想了解完整的签名步骤和代码实现？

请访问我们的 开发者中心-签名机制，获取详细的说明和代码示例。

API 权限与接口分类

接口的认证类型

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

权限与接口功能映射关系

您在“API管理”界面创建密钥时选择的权限，决定了您可以访问哪些私有接口。

您在UI界面选择的权限	对应的私有接口功能分类 (在开发者中心)	核心用途
读取 (Read)	用户接口 (GET)、现货接口 (GET)、合约接口 (GET)、出入金接口 (GET)、资金划转接口 (GET)	查询个人账户信息、订单状态、资产余额、历史记录等。
现货交易 (Spot Trading)	现货接口 (POST)	创建和取消现货订单。
永续合约交易	合约接口 (POST)	创建/取消合约订单，调整仓位和保证金等。
资金划转	资金划转接口 (POST)、出入金接口 (POST)	在不同账户间转移资金，以及执行提现操作。

接口分类详解

以下是各功能分类下的接口列表。如需查看完整的请求/响应参数，请访问 开发者中心 或对应的 Swagger 文档。

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

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: (需资金划转权限) 从合约账户划转至钱包账户。

错误码参考

当您的 API 请求出现问题时，响应体中 success 字段会为 false，并包含 error 和 errorMessage 字段以帮助您定位问题。

错误响应示例：

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

常见错误码汇总：

errorCode	errorMessage	中文说明
PARAMETER_INVALID	Parameter error: the request parameter is invalid.	请求参数错误。
SIGNATURE_INVALID	Signature error: the signature is invalid.	签名无效。
SIGNATURE_EXPIRED	Signature error: the signature is expired.	签名已过期，请检查您的时间戳。
HEADER_INVALID	Header error: the request header is invalid.	请求头无效。
AUTH_APIKEY_INVALID	Authenticate error: API key is invalid.	API Key 无效。
AUTH_IP_FORBIDDEN	Authenticate error: IP forbidden.	当前 IP 地址未在白名单中，访问被拒绝。
ACCOUNT_NO_ENOUGH_BALANCE	Account error: no enough balance.	账户余额不足。
ORDER_NOT_FOUND	Order error: the specific order not found.	未找到指定的订单。
ORDER_EXCEEDED	Order error: order exceeds the maximum active limit.	活动订单数量超过上限。
USER_HAS_NO_PERMISSION	Permission error: user has no permission.	该 API Key 没有执行此操作的权限。
AUTH_APIKEY_INVALID	Api Key not allow to request this uri.	API Key不能访问此uri。

如需查看完整的错误码列表，请访问 开发者中心-错误码。

安全与使用规范

请务必遵守以下安全规范，以保护您的账户和资产安全。

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