Quick Start

1. Create an API Key

• API Name: Set an easily identifiable name for your key.
• API Permissions: Select the appropriate permissions according to your needs. For security, we recommend granting only the necessary permissions. The default permission is "Read".
• API Expiration: Choose a suitable expiration period.
• IP Address Binding: To maximize the security of your assets, it is highly recommended to bind IP addresses. You can enter up to 10 IP addresses, separated by commas.

⚠️ Important: Back up your Secret Key immediately!

The Secret Key is displayed only at the time of creation. The platform will not store or display it again in any form. Be sure to save it in a secure and reliable place. If it is lost or compromised, you will need to delete the API key and create a new one.

2. Understand API Permissions

• Read: Allows querying private information such as personal orders, balances, and asset history.
• Spot Trading: Allows creating and canceling spot orders.
• Perpetual Contract Trading: Allows creating and canceling contract orders and adjusting position settings.
• Fund Transfer: Allows transferring funds between your Wallet, Spot, and Contract accounts.

3. API Call Example

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

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

API Authentication

API Permissions and Endpoint Categories

Endpoint Authentication Types

• ✅ Public Endpoints (No Signature Required): All endpoints with paths starting with /v1/market/ are public market data endpoints. Anyone can call them directly to get market data without an API key or request signature.
• 🔐 Private Endpoints (Signature Required): All endpoints involving user's personal information, assets, trading, and transfers are private endpoints. Calling these endpoints requires signature authentication using your API key.

Permission to Function Mapping

Detailed Endpoint Breakdown

Market Endpoints (Public, No Signature Required)

• GET /v1/market/trades: Get all assets and trading pairs information.
• GET /v1/market/timestamp: Get the server timestamp.
• GET /v1/market/ticks/{symbol}: Get the latest trade data for a trading pair.
• GET /v1/market/prices: Get the market prices for all currencies (24h).
• GET /v1/market/orderBook/{symbol}: Get the order book depth for a specified trading pair.
• GET /v1/market/indexes: Get the latest prices for all indexes.
• GET /v1/market/indexes/{name}: Get historical prices for a single index.
• GET /v1/market/indexes/indexValue: Get the value of a single index.
• GET /v1/market/indexPrices: Get the latest index prices for perpetual contracts.
• GET /v1/market/errorCodes: Get all error codes.
• GET /v1/market/bars/{symbol}/{type}: Get K-line data for a specified trading pair.
• GET /v1/market/positions: Get total open interest for all users.

User Endpoints (Private, Signature Required)

• GET /v1/users/me: (Read permission required) Get your current login information.

Spot Endpoints (Private, Signature Required)

• GET /v1/spots/orders/{orderId}: (Read permission required) Query order details by ID.
• GET /v1/spots/orders/{orderId}/matches: (Read permission required) Query order trade details by ID.
• GET /v1/spots/orders/open: (Read permission required) Query all your currently open spot orders.
• GET /v1/spots/orders/open/{orderId}: (Read permission required) Query an open order by ID.
• GET /v1/spots/orders/closed: (Read permission required) Query historical orders by month.
• GET /v1/spots/match/clearings: (Read permission required) Paginated query of user order clearing records.
• GET /v1/spots/fee/rate: (Read permission required) Query spot trading fee rates.
• GET /v1/spots/balances: (Read permission required) Query your spot account balances.
• POST /v1/spots/orders: (Spot Trading permission required) Create a new spot order.
• POST /v1/spots/orders/{idOrSymbol}/cancel: (Spot Trading permission required) Cancel specified spot orders.

Contract Endpoints (Private, Signature Required)

• GET /v1/contracts/positions: (Read permission required) Query all your contract positions.
• GET /v1/contracts/positions/{symbol}: (Read permission required) Query a single position by symbol.
• GET /v1/contracts/orders/{orderId}: (Read permission required) Query an order by order ID.
• GET /v1/contracts/orders/{orderId}/matches: (Read permission required) Query order trade records.
• GET /v1/contracts/orders/open: (Read permission required) Query all your currently open contract orders.
• GET /v1/contracts/orders/open/{orderId}: (Read permission required) Query an open order by ID.
• GET /v1/contracts/orders/closed: (Read permission required) Query historical contract orders.
• GET /v1/contracts/match/clearings: (Read permission required) Paginated query of user order clearing records.
• GET /v1/contracts/fund/flows: (Read permission required) Paginated query of user fund flow records.
• GET /v1/contracts/fee/rate: (Read permission required) Query futures trading fee rates.
• GET /v1/contracts/clearings/positions: (Read permission required) Query position clearing history.
• GET /v1/contracts/balances: (Read permission required) Query your contract account balances.
• POST /v1/contracts/orders: (Perpetual Contract Trading permission required) Create a new contract order.
• POST /v1/contracts/orders/{idOrSymbol}/cancel: (Perpetual Contract Trading permission required) Cancel specified contract orders.
• POST /v1/contracts/orders/cancel: (Perpetual Contract Trading permission required) Cancel all contract orders.
• POST /v1/contracts/positions/{symbol}/settings: (Perpetual Contract Trading permission required) Set position mode and leverage.
• POST /v1/contracts/positions/{symbol}/margin: (Perpetual Contract Trading permission required) Adjust margin for a position.

Deposit & Withdrawal Endpoints (Private, Signature Required)

• GET /v1/wallet/withdraws: (Read permission required) Query withdrawal request list.
• GET /v1/wallet/queryWithdrawById: (Read permission required) Query a withdrawal request by ID.
• GET /v1/wallet/flows: (Read permission required) Query wallet account flow information.
• GET /v1/wallet/deposits: (Read permission required) Query deposit log list.

Fund Transfer Endpoints (Private, Signature Required)

• GET /v1/wallet/currencyMappings: (Read permission required) Get currency mapping information.
• GET /v1/wallet/balances: (Read permission required) Query your wallet account balances.
• GET /v1/transfer/{transferId}/request: (Read permission required) Query transfer request information by transfer ID.
• GET /v1/transfer/{transferId}/log: (Read permission required) Query transfer log information by transfer ID.
• GET /v1/transfer/transfer/logs: (Read permission required) Paginated query of transfer log list.
• POST /v1/transfer/request/wallet/to/spots: (Fund Transfer permission required) Transfer from Wallet account to Spot account.
• POST /v1/transfer/request/spots/to/wallet: (Fund Transfer permission required) Transfer from Spot account to Wallet account.
• POST /v1/transfer/request/wallet/to/contracts: (Fund Transfer permission required) Transfer from Wallet account to Contract account.
• POST /v1/transfer/request/contracts/to/wallet: (Fund Transfer permission required) Transfer from Contract account to Wallet account.

Error Code Reference

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

Security and Usage Best Practices

• Keep Your Keys Safe: Your API keys (especially the Secret Key) grant access to operate your account. Treat them like passwords and never share them with anyone or hard-code them in insecure code.
• Use an IP Whitelist: It is highly recommended to bind each of your API keys to specific IP addresses. This significantly reduces the risk of misuse if a key is compromised.
• Principle of Least Privilege: When creating an API key, grant only the minimum permissions required for your application. For example, if an application only needs to read market data, do not grant it trading or transfer permissions.
• Rotate Keys Periodically: Regularly delete old, unused keys and consider periodically replacing active keys to enhance security.
• Be Aware of Official Communications: Do not disclose your key information to anyone claiming to be official BenPay customer support.