CIFDAQ Open API Documentation
Change Log
2025-07-09
- Added comprehensive Contract Trading API documentation
- Updated WebSocket Contract Order Book Stream with actual response structure including priceStr/amountStr fields
- Updated WebSocket Contract Trade Stream with complete trade data including buyOrderId/sellOrderId
- Updated WebSocket Contract Order Updates Stream with detailed order status and field explanations
- Added Contract Market Data API endpoints (/contract-swap/symbol, /contract-swap/exchange-plate, /contract-swap/latest-trade, /contract-swap/history)
- Updated GET /contract-swap/exchange-plate response structure to match actual implementation with nested ask/bid objects
- Updated GET /contract-swap/latest-trade response structure with actual trade fields
- Added Contract Trading API endpoints for account management and order operations
- Updated GET /contract-swap-wallet/list response to simplified structure with core account fields
- Added complete response examples for contract order operations (open/close/current/position-detail)
- Updated GET /contract-swap-order/current response with detailed order fields and pagination structure
- Updated GET /contract-swap-order/position-detail response with actual position data fields
- Enhanced all contract-related endpoint documentation with detailed field descriptions and data types
- Added comprehensive field documentation tables for all contract API responses
- Updated POST /contract-swap-wallet/trans (Fund Transfer) parameters to match actual implementation: amount, from, to, unit, timestamp, recvWindow
- Translated wallet type descriptions from Chinese to English (Spot Wallet, Contract Wallet, Strategy Wallet, Trading Wallet)
- Updated POST /contract-swap-order/order (Open/Close Position) parameters and response structure to match actual implementation
- Added newClientOrderId parameter and response field for contract order operations
- Updated POST /contract-swap-order/ajust-principal (Adjust Margin) parameters and response structure to match actual implementation
- Corrected parameter names to match actual API: amount, symbol, type, timestamp, recvWindow
- All contract-related interface parameter tables and response examples now synchronized with actual API returns
2025-07-08
- Updated Order Book Push response structure to match actual implementation
- Added symbol field and priceSt/amountSt string format fields to order book data
- Updated Recent Trades response structure for both WebSocket and REST API
- Removed non-existent fields (buyOrderId, sellOrderId, buyTurnover, sellTurnover) from trade data
- Simplified trade response structure to include only: amount, direction, price, symbol, time
- Updated Symbol Thumb API response structure to include missing fields
- Added engineTypeEnum and sort fields to symbol_thumb endpoint
- Enhanced field documentation with detailed comments for all symbol_thumb response fields
- Updated Trade History API response structure to match actual implementation
- Changed direction field from string to integer (0=BUY, 1=SELL) in trade_history endpoint
- Added standard API response wrapper (code, message, totalPage, totalElement, data) to trade_history
- Enhanced WebSocket Account Data Push documentation
- Added detailed authentication requirements for ListenKey generation
- Clarified that timestamp and signature are required for /open/order_update_key endpoint
- Added step-by-step WebSocket subscription instructions
2024-10-19
- Added WebSocket interface to get transaction list
2024-10-18
- Added interface to get transaction list
Introduction
Account Types
Spot Account
Newly registered accounts will have a Spot (SPOT
) account.
Basic Information
API Endpoints
- Base URL:
http://35.244.2.120:6020/open-api
- WebSocket URL:
ws://35.244.2.120:7717/ws/cifdaq
- All responses are in JSON format
HTTP Request Rules
GET
requests: Parameters must be sent in the query stringPOST
andPUT
requests: Parameters must be sent in the request body as JSON- Parameter order doesn't matter
- Query string parameters take priority over request body parameters when duplicated
API Key Setup
- Many endpoints require an API Key for access
- Configure IP whitelist for security when setting up API Key
- Never share your API key/secret with anyone
- Delete and regenerate API key immediately if compromised
API Key Permissions
- Default permissions for new API keys:
Read-Only
,Trade
, andWithdraw
Read-Only
is mandatory and cannot be disabled
Access Restrictions
Rate Limiting
Interval Letters:
S
- SECONDM
- MINUTEH
- HOURD
- DAY
Rate Limit Types:
RAW_REQUESTS
REQUEST_WEIGHT
ORDERS
Violating rate limits returns
429
errorContinued violations after
429
may result in IP ban with418
errorBan duration: 2 minutes to 3 days (progressive)
Retry-After
header indicates wait time
Request Headers
X-MBX-USED-WEIGHT-(intervalNum)(intervalLetter)
: Weight used by current IPX-MBX-ORDER-COUNT-(intervalNum)(intervalLetter)
: Orders used by current account
WebSocket Information
- Maximum 5 messages per second (including PING/PONG frames and JSON messages)
- All trading pairs in streams use UPPERCASE
Authentication
Authentication Types
Type | Description |
---|---|
NONE |
No authentication required |
TRADE |
Requires valid API Key and signature |
MARGIN |
Requires valid API Key and signature |
USER_DATA |
Requires valid API Key and signature |
USER_STREAM |
Requires valid API Key |
MARKET_DATA |
Requires valid API Key |
Note: TRADE
, MARGIN
, and USER_DATA
are SIGNED endpoints
SIGNED Endpoint Security
- Requires
signature
parameter in query string or request body - Uses
HMAC SHA256
algorithm with API-Secret as key - Requires
timestamp
parameter (Unix timestamp in milliseconds) - Request must be sent within 5000ms of timestamp
Data Types and Enums
Order Types:
LIMIT_PRICE
- Limit orderMARKET_PRICE
- Market order
Order Sides:
BUY
- Buy orderSELL
- Sell order
K-Line Intervals:
1min
,5min
,15min
,30min
,60min
,1day
,1week
Spot Trading API
WebSocket Market Data
Stream Subscription/Unsubscription
Subscribe to data streams using WebSocket. Response id
is an unsigned integer for message identification.
Subscribe to Stream
Request:
{
"sub": ["BTCUSDT@Kline_1m"]
}
Unsubscribe from Stream
Request:
{
"cancel": ["BTCUSDT@Kline_1m"]
}
K-Line Data Stream
Stream Name: <symbol>@Kline_<interval>
Intervals: 1min
, 5min
, 15min
, 30min
, 60min
, 1day
, 1week
Response:
{
"closePrice": 27776.08, // Close price (closing price of the K-line)
"count": 330, // Number of transactions (trade count in this K-line)
"highestPrice": 27783.06, // Highest price (highest trade price in this K-line)
"lowestPrice": 27774.98, // Lowest price (lowest trade price in this K-line)
"openPrice": 27774.98, // Open price (opening price of the K-line)
"period": "1min", // K-Line interval (time period of this K-line)
"time": 1685432160000, // Timestamp (K-line start time in milliseconds)
"turnover": 397563.8825656, // Trading volume (total trading volume in quote currency)
"volume": 14.31145 // Trade volume (total trading volume in base currency)
}
24hr Ticker Statistics Stream
Stream Name: <symbol>@ticker
Response:
{
"high": 28447.14, // 24hr high price (highest price in last 24 hours)
"lastDayClose": 0, // Previous day close (closing price of previous day)
"low": 27546.0, // 24hr low price (lowest price in last 24 hours)
"open": 27272.17, // 24hr open price (opening price of current 24hr period)
"price": 27875.6, // Latest price (most recent trade price)
"symbol": "BTC/USDT", // Trading pair symbol (trading pair identifier)
"timestamp": 1685439793093, // Timestamp (time when data was generated)
"turnover": 945039033.2096055,// 24hr volume (total trading volume in quote currency)
"volume": 63.8112 // 24hr volume (total trading volume in base currency)
}
Order Book Stream
Stream Name: <symbol>@plate
Response:
{
"symbol": "SHIB/USDT", // Trading pair symbol (symbol identifier)
"bid": [ // Buy orders (bid side of order book)
{
"price": 1.1337E-5, // Price as number (bid price in numeric format)
"amount": 9195228.8, // Quantity as number (bid quantity in numeric format)
"priceSt": "0.000011337", // Price as string (bid price in string format for precision)
"amountSt": "9195228.80" // Quantity as string (bid quantity in string format for precision)
}
],
"ask": [ // Sell orders (ask side of order book)
{
"price": 1.1338E-5, // Price as number (ask price in numeric format)
"amount": 9195228.8, // Quantity as number (ask quantity in numeric format)
"priceSt": "0.000011338", // Price as string (ask price in string format for precision)
"amountSt": "9195228.80" // Quantity as string (ask quantity in string format for precision)
}
]
}
Trade Stream
Stream Name: <symbol>@trade
Response:
[
{
"amount": 4776700, // Trade quantity (amount of base currency traded)
"direction": "BUY", // Trade direction (BUY/SELL - indicates taker side)
"price": 0.000011339, // Trade price (price at which trade was executed)
"symbol": "SHIB/USDT", // Trading pair symbol (trading pair identifier)
"time": 1751292434716 // Trade timestamp (trade execution time in milliseconds)
}
]
WebSocket Account Data
Account data requires ListenKey authentication for private data streams.
Generate ListenKey
Endpoint: GET /open/order_update_key
Authentication: USER_DATA (requires API Key and signature)
Request Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
timestamp | LONG | YES | Request timestamp (Unix timestamp in milliseconds) |
signature | STRING | YES | HMAC SHA256 signature |
Request Headers:
Header | Type | Required | Description |
---|---|---|---|
X-MBX-APIKEY | STRING | YES | Your API Key |
Response:
{
"code": 0, // Response code (0 = success)
"message": "", // Response message (empty on success)
"data": "vYmf6uHNUKv1+DW77hJQ8g==" // ListenKey (authentication token for WebSocket)
}
Order Updates Stream
Stream Name: <symbol>@orders@<ListenKey>
Order Status Values:
COMPLETED
- Order fully executedCANCELED
- Order cancelled
Response:
{
"amount": 123.0, // Order amount (total order amount)
"direction": "BUY", // Order direction (BUY/SELL)
"newClientOrderId": "311321114341131", // Client order ID (user-defined order identifier)
"memberId": 35084, // Member ID (user account identifier)
"orderId": "E168552607888820", // Order ID (system-generated order identifier)
"price": 1.0, // Order price (order execution price)
"status": "COMPLETED", // Order status (current order state)
"symbol": "BTC/USDT", // Trading pair (trading pair symbol)
"tradedAmount": 0.004541, // Executed amount (amount of order that has been filled)
"turnover": 123.0, // Order turnover (total value of executed portion)
"type": "MARKET_PRICE" // Order type (MARKET_PRICE/LIMIT_PRICE)
}
Important Notes:
- No additional signature required for WebSocket subscription
- Authentication handled via ListenKey
Market Data API
Get K-Line Data
Endpoint: GET /open/history/kline
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
symbol | STRING | YES | Trading pair symbol |
period | STRING | YES | K-line interval |
size | INT | NO | Number of results to return |
Response:
[{
"closePrice": 27776.08, // Close price (K-line closing price)
"count": 330, // Trade count (number of trades in this K-line)
"highestPrice": 27783.06, // High price (highest price in this K-line)
"lowestPrice": 27774.98, // Low price (lowest price in this K-line)
"openPrice": 27774.98, // Open price (K-line opening price)
"period": "1min", // Period (K-line time interval)
"time": 1685432160000, // Timestamp (K-line start time in milliseconds)
"turnover": 397563.8825656, // Turnover (total trading volume in quote currency)
"volume": 14.31145 // Volume (total trading volume in base currency)
}]
Get Trading Pairs
Endpoint: GET /open/symbol_thumb
Response:
[
{
"symbol": "BTC/USDT", // Trading pair symbol (unique identifier for the trading pair)
"open": 41341.97, // 24h open price (opening price 24 hours ago)
"high": 41518.81, // 24h high price (highest price in last 24 hours)
"low": 40728.1, // 24h low price (lowest price in last 24 hours)
"close": 40930.26, // Current price (latest/current price)
"chg": -0.0102, // 24h change percentage (price change percentage in last 24 hours)
"change": -411.71, // 24h change amount (absolute price change in last 24 hours)
"volume": 5.5142, // 24h volume (trading volume in base currency for last 24 hours)
"turnover": 5623362.5318740000000000, // 24h turnover (trading volume in quote currency for last 24 hours)
"lastDayClose": 41341.13, // Previous day close (closing price of previous day)
"usdRate": 40930.26, // USD rate (current USD exchange rate for base currency)
"baseUsdRate": 1, // Base USD rate (USD exchange rate for quote currency)
"zone": 0, // Zone (market zone or region identifier)
"scale": 5, // Price precision (decimal places for price display)
"baseScale": 2, // Quantity precision (decimal places for quantity display)
"timestamp": 1702450378733, // Data timestamp (time when this data was generated)
"coinSymbolLogo": "https://example.com/btc.svg", // Base currency logo (logo URL for base currency)
"baseSymbolLogo": "https://example.com/usdt.svg", // Quote currency logo (logo URL for quote currency)
"coinSymbolName": "Bitcoin", // Base currency name (full name of base currency)
"baseSymbolName": "USDT", // Quote currency name (full name of quote currency)
"priceSize": "0.01", // Minimum price increment (smallest price change allowed)
"engineTypeEnum": "HEDGING", // Engine type (trading engine type, e.g., HEDGING)
"sort": 1 // Display order (sorting priority for display)
}
]
Get Trade History
Endpoint: GET /open/trade_history
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
symbol | STRING | YES | Trading pair symbol |
size | INT | YES | Number of trades to return |
Response:
{
"code": 0, // Response code (0 = success, non-zero = error)
"message": "SUCCESS", // Response message (status description)
"totalPage": null, // Total pages (pagination info, null for this endpoint)
"totalElement": null, // Total elements (total count, null for this endpoint)
"data": [ // Trade data (array of recent trades)
{
"amount": 1310600, // Trade amount (quantity of base currency traded)
"direction": 1, // Trade direction (0 = BUY, 1 = SELL - indicates taker side)
"price": 1.1362E-5, // Trade price (price at which trade was executed)
"symbol": "SHIB/USDT", // Trading pair (symbol for this trade)
"time": 1751292222488 // Trade time (execution timestamp in milliseconds)
}
]
}
Direction Values:
0
- BUY (买入)1
- SELL (卖出)
Trading API
Get Server Time
Endpoint: GET /api/getServerTimestamp
Authentication: NONE
Response:
1499827319559 // Server timestamp (current server time in milliseconds)
Place Order
Endpoint: POST /api/Order
Authentication: TRADE
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
symbol | STRING | YES | Trading pair symbol |
side | ENUM | YES | Order side (BUY/SELL) |
type | ENUM | YES | Order type (LIMIT_PRICE/MARKET_PRICE) |
quantity | DECIMAL | NO | Order quantity |
price | DECIMAL | NO | Order price (required for LIMIT_PRICE) |
newClientOrderId | STRING | NO | Custom client order ID |
recvWindow | LONG | NO | Request window (max 60000ms) |
timestamp | LONG | YES | Request timestamp |
Order Type Requirements:
Order Type | Required Parameters |
---|---|
LIMIT_PRICE |
quantity , price |
MARKET_PRICE |
quantity |
Response:
{
"symbol": "BTCUSDT", // Trading pair (symbol for this order)
"orderId": 28, // Order ID (system-generated unique order identifier)
"orderListId": -1, // OCO order ID (One-Cancels-Other order ID, -1 if not applicable)
"clientOrderId": "6gCrw2kRUAF9CvJDGP16IP", // Client order ID (user-defined order identifier)
"transactTime": 1507725176595, // Transaction time (order acceptance timestamp)
"price": "0.00000000", // Order price (limit price for limit orders)
"origQty": "10.00000000", // Original quantity (initial order quantity)
"executedQty": "10.00000000", // Executed quantity (amount of order that has been filled)
"cummulativeQuoteQty": "10.00000000", // Cumulative quote qty (total value executed in quote currency)
"status": "FILLED", // Order status (current state: NEW, PARTIALLY_FILLED, FILLED, etc.)
"timeInForce": "GTC", // Time in force (order validity: GTC, IOC, FOK)
"type": "MARKET", // Order type (MARKET, LIMIT, etc.)
"side": "SELL" // Order side (BUY or SELL)
}
Cancel Order
Endpoint: DELETE /api/Order
Authentication: TRADE
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
symbol | STRING | YES | Trading pair symbol |
orderId | LONG | NO | System order ID |
newClientOrderId | STRING | NO | Client order ID |
recvWindow | LONG | NO | Request window (max 60000ms) |
timestamp | LONG | YES | Request timestamp |
Note: At least one of orderId
or newClientOrderId
must be provided
Response:
"" // Empty response on successful cancellation
Query Order
Endpoint: GET /api/Order
Authentication: USER_DATA
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
symbol | STRING | YES | Trading pair symbol |
orderId | STRING | NO | System order ID |
newClientOrderId | STRING | NO | Client order ID |
recvWindow | LONG | NO | Request window (max 60000ms) |
timestamp | LONG | YES | Request timestamp |
Response:
{
"symbol": "LTCBTC", // Trading pair (symbol for this order)
"orderId": 1, // Order ID (system-generated order identifier)
"orderListId": -1, // OCO order ID (One-Cancels-Other order ID, -1 if not applicable)
"newClientOrderId": "myOrder1", // Client order ID (user-defined order identifier)
"price": "0.1", // Order price (limit price for the order)
"origQty": "1.0", // Original quantity (initial order quantity)
"executedQty": "0.0", // Executed quantity (amount filled so far)
"cummulativeQuoteQty": "0.0", // Cumulative quote quantity (total value executed)
"status": "NEW", // Order status (NEW, PARTIALLY_FILLED, FILLED, CANCELED, etc.)
"timeInForce": "GTC", // Time in force (GTC=Good Till Cancel, IOC=Immediate Or Cancel, FOK=Fill Or Kill)
"type": "LIMIT", // Order type (LIMIT, MARKET, STOP_LOSS, etc.)
"side": "BUY", // Order side (BUY or SELL)
"stopPrice": "0.0", // Stop price (trigger price for stop orders, 0 if not applicable)
"icebergQty": "0.0", // Iceberg quantity (visible quantity for iceberg orders, 0 if not applicable)
"time": 1499827319559, // Order time (order creation timestamp)
"updateTime": 1499827319559, // Update time (last modification timestamp)
"isWorking": true, // Is working (whether order is still active in order book)
"origQuoteOrderQty": "0.000000" // Original quote quantity (original order value in quote currency)
}
Get Open Orders
Endpoint: GET /api/openOrders
Authentication: USER_DATA
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
symbol | STRING | NO | Trading pair symbol (if not provided, returns all pairs) |
recvWindow | LONG | NO | Request window (max 60000ms) |
timestamp | LONG | YES | Request timestamp |
Response:
[
{
"symbol": "LTC/BTC", // Trading pair (symbol for this order)
"orderId": 1, // Order ID (system-generated order identifier)
"orderListId": -1, // OCO order ID (One-Cancels-Other order ID, -1 if not applicable)
"clientOrderId": "myOrder1", // Client order ID (user-defined order identifier)
"price": "0.1", // Order price (limit price for the order)
"origQty": "1.0", // Original quantity (initial order quantity)
"executedQty": "0.0", // Executed quantity (amount filled so far)
"cummulativeQuoteQty": "0.0", // Cumulative quote quantity (total value executed)
"status": "NEW", // Order status (NEW, PARTIALLY_FILLED, FILLED, CANCELED, etc.)
"timeInForce": "GTC", // Time in force (order validity period)
"type": "LIMIT", // Order type (LIMIT, MARKET, etc.)
"side": "BUY", // Order side (BUY or SELL)
"stopPrice": "0.0", // Stop price (trigger price for stop orders)
"icebergQty": "0.0", // Iceberg quantity (visible quantity for iceberg orders)
"time": 1499827319559, // Order time (order creation timestamp)
"updateTime": 1499827319559, // Update time (last modification timestamp)
"isWorking": true, // Is working (whether order is still active)
"origQuoteOrderQty": "0.000000" // Original quote quantity (original order value)
}
]
Get All Orders
Endpoint: GET /api/allOrders
Authentication: USER_DATA
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
symbol | STRING | YES | Trading pair symbol |
orderId | LONG | NO | Order ID (returns orders >= this ID) |
startTime | LONG | NO | Start time filter |
endTime | LONG | NO | End time filter |
limit | INT | NO | Result limit (default 500, max 1000) |
recvWindow | LONG | NO | Request window (max 60000ms) |
timestamp | LONG | YES | Request timestamp |
Response:
[
{
"symbol": "LTCBTC", // Trading pair (symbol for this order)
"orderId": 1, // Order ID (system-generated order identifier)
"orderListId": -1, // OCO order ID (One-Cancels-Other order ID, -1 if not applicable)
"clientOrderId": "myOrder1", // Client order ID (user-defined order identifier)
"price": "0.1", // Order price (limit price for the order)
"origQty": "1.0", // Original quantity (initial order quantity)
"executedQty": "0.0", // Executed quantity (amount filled so far)
"cummulativeQuoteQty": "0.0", // Cumulative quote quantity (total value executed)
"status": "NEW", // Order status (order state)
"timeInForce": "GTC", // Time in force (order validity)
"type": "LIMIT", // Order type (order execution type)
"side": "BUY", // Order side (buy or sell direction)
"stopPrice": "0.0", // Stop price (trigger price for conditional orders)
"icebergQty": "0.0", // Iceberg quantity (visible portion for iceberg orders)
"time": 1499827319559, // Order time (creation timestamp)
"updateTime": 1499827319559, // Update time (last modification timestamp)
"isWorking": true, // Is working (whether order is active in order book)
"origQuoteOrderQty": "0.000000" // Original quote quantity (original order value in quote currency)
}
]
Account Information
Endpoint: GET /api/account
Authentication: USER_DATA
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
recvWindow | LONG | NO | Request window (max 60000ms) |
timestamp | LONG | YES | Request timestamp |
Response:
[
{
"address": "", // Wallet address (deposit address for this currency)
"balance": 0, // Available balance (current available balance)
"coin": {
"accountType": 0, // Account type (type identifier for this account)
"allBalance": 0, // Total balance (total balance including frozen)
"blockHeight": 0, // Block height (current blockchain height)
"canAutoWithdraw": "", // Auto withdraw permission (whether auto-withdrawal is enabled)
"canRecharge": "", // Deposit permission (whether deposits are allowed)
"canTransfer": "", // Transfer permission (whether transfers are allowed)
"canWithdraw": "", // Withdraw permission (whether withdrawals are allowed)
"cnyRate": 0, // CNY rate (current CNY exchange rate)
"coinType": "", // Coin type (currency type identifier)
"coldWalletAddress": "", // Cold wallet address (cold storage wallet address)
"depositAddress": "", // Deposit address (address for receiving deposits)
"enableRpc": "", // RPC enabled (whether RPC is enabled)
"hasLegal": true, // Legal tender status (whether it's a legal tender)
"hotAllBalance": 0, // Hot wallet balance (total hot wallet balance)
"infolink": "", // Information link (link to additional info)
"information": "", // Additional information (extra details)
"isPlatformCoin": "", // Platform coin status (whether it's a platform coin)
"mainCoinType": "", // Main coin type (parent coin type)
"maxTxFee": 0, // Maximum transaction fee (highest transaction fee)
"maxWithdrawAmount": 0, // Maximum withdrawal amount (max amount per withdrawal)
"minRechargeAmount": 0, // Minimum deposit amount (smallest deposit allowed)
"minTxFee": 0, // Minimum transaction fee (lowest transaction fee)
"minWithdrawAmount": 0, // Minimum withdrawal amount (smallest withdrawal allowed)
"minerFee": 0, // Miner fee (blockchain network fee)
"name": "", // Currency name (full name of currency)
"nameCn": "", // Currency Chinese name (Chinese name of currency)
"sort": 0, // Sort order (display order priority)
"status": "", // Currency status (operational status)
"unit": "", // Currency unit (symbol or unit)
"usdRate": 0, // USD rate (current USD exchange rate)
"withdrawScale": 0, // Withdrawal precision (decimal places for withdrawals)
"withdrawThreshold": 0 // Withdrawal threshold (minimum threshold for withdrawal)
},
"frozenBalance": 0, // Frozen balance (balance locked in orders)
"id": 0, // Account ID (unique account identifier)
"isLock": "", // Lock status (whether account is locked)
"memberId": 0, // Member ID (user account identifier)
"memo": "", // Memo (additional notes or memo)
"toReleased": 0 // To be released (amount pending release)
}
]
Account Trade History
Endpoint: GET /api/myTrades
Authentication: USER_DATA
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
symbol | STRING | YES | Trading pair symbol |
orderId | LONG | NO | Order ID (filter by specific order) |
startTime | LONG | NO | Start time filter |
endTime | LONG | NO | End time filter |
fromId | LONG | NO | Trade ID to start from |
limit | INT | NO | Result limit (default 500, max 1000) |
recvWindow | LONG | NO | Request window (max 60000ms) |
timestamp | LONG | YES | Request timestamp |
Response:
[
{
"symbol": "BNBBTC", // Trading pair (symbol for this trade)
"id": 28457, // Trade ID (unique trade identifier)
"orderId": 100234, // Order ID (associated order identifier)
"orderListId": -1, // OCO order ID (One-Cancels-Other order ID, -1 if not applicable)
"price": "4.00000100", // Trade price (execution price of the trade)
"qty": "12.00000000", // Trade quantity (amount traded in base currency)
"quoteQty": "48.000012", // Quote quantity (amount traded in quote currency)
"commission": "10.10000000", // Commission fee (trading fee charged)
"commissionAsset": "BNB", // Commission asset (currency used for fee payment)
"time": 1499865549590, // Trade time (execution timestamp)
"isBuyer": true, // Is buyer (whether user was the buyer)
"isMaker": false, // Is maker (whether user was the maker)
"isBestMatch": true, // Is best match (whether this was the best price match)
"type": "LIMIT_PRICE", // Order type (type of order that generated this trade)
"amount": 1.0, // Trade amount (total amount of the trade)
"tradedAmount": 1.0, // Traded amount (amount successfully traded)
"turnover": 27570.0, // Trade turnover (total value of the trade)
"status": "COMPLETED", // Trade status (completion status)
"direction": "BUY" // Trade direction (BUY or SELL)
}
]
Contract Trading API
WebSocket Market Data
Stream Subscription
Contract WebSocket streams use similar subscription patterns with different stream names.
Subscribe to Contract Stream
Request:
{
"sub": ["BTCUSDT@Kline_contract_1min"]
}
Unsubscribe from Contract Stream
Request:
{
"cancel": ["BTCUSDT@Kline_contract_1min"]
}
Contract K-Line Stream
Stream Name: <symbol>@Kline_contract_<interval>
Intervals: 1min
, 5min
, 15min
, 30min
, 60min
, 1day
, 1week
Response:
{
"closePrice": 27776.08, // Close price (K-line closing price)
"count": 330, // Trade count (number of trades in this K-line)
"highestPrice": 27783.06, // High price (highest price in this K-line)
"lowestPrice": 27774.98, // Low price (lowest price in this K-line)
"openPrice": 27774.98, // Open price (K-line opening price)
"period": "1min", // Period (K-line time interval)
"time": 1685432160000, // Timestamp (K-line start time in milliseconds)
"turnover": 397563.8825656, // Trading volume (total trading volume in quote currency)
"volume": 14.31145 // Trade volume (total trading volume in base currency)
}
Contract Ticker Stream
Stream Name: <symbol>@ticker_contract
Response:
{
"high": 28447.14, // 24hr high (highest price in last 24 hours)
"lastDayClose": 0, // Previous close (previous day closing price)
"low": 27546.0, // 24hr low (lowest price in last 24 hours)
"open": 27272.17, // 24hr open (opening price of current 24hr period)
"price": 27875.6, // Current price (latest trade price)
"symbol": "BTC/USDT", // Trading pair (contract symbol)
"timestamp": 1685439793093, // Timestamp (data generation time)
"turnover": 945039033.2096055,// 24hr turnover (total trading volume in quote currency)
"volume": 63.8112 // 24hr volume (total trading volume in base currency)
}
Contract Order Book Stream
Stream Name: <symbol>@plate_contract
Response:
{
"symbol": "IMX/USDT", // Trading pair symbol (contract symbol identifier)
"ask": [ // Sell orders (ask side of contract order book)
{
"price": 0.4355, // Price as number (ask price in numeric format)
"amount": 147.27, // Quantity as number (ask quantity in numeric format)
"priceStr": "0.4355", // Price as string (ask price in string format for precision)
"amountStr": "147.27" // Quantity as string (ask quantity in string format for precision)
},
{
"price": 0.4718, // Price as number (ask price in numeric format)
"amount": 401.7, // Quantity as number (ask quantity in numeric format)
"priceStr": "0.4718", // Price as string (ask price in string format for precision)
"amountStr": "401.7" // Quantity as string (ask quantity in string format for precision)
}
],
"bid": [ // Buy orders (bid side of contract order book)
{
"price": 0.4186, // Price as number (bid price in numeric format)
"amount": 317.73, // Quantity as number (bid quantity in numeric format)
"priceStr": "0.4186", // Price as string (bid price in string format for precision)
"amountStr": "317.73" // Quantity as string (bid quantity in string format for precision)
},
{
"price": 0.4185, // Price as number (bid price in numeric format)
"amount": 478.13, // Quantity as number (bid quantity in numeric format)
"priceStr": "0.4185", // Price as string (bid price in string format for precision)
"amountStr": "478.13" // Quantity as string (bid quantity in string format for precision)
}
]
}
Contract Trade Stream
Stream Name: <symbol>@trade_contract
Response:
[
{
"amount": 59.0, // Trade quantity (amount of base currency traded)
"buyOrderId": "1942810185449865216", // Buy order ID (ID of the buy order involved in this trade)
"direction": "SELL", // Trade direction (BUY/SELL - indicates taker side)
"price": 1900.8, // Trade price (price at which trade was executed)
"sellOrderId": "1942810252764250112", // Sell order ID (ID of the sell order involved in this trade)
"symbol": "MKR/USDT", // Trading pair symbol (contract symbol identifier)
"time": 1752037034652 // Trade timestamp (trade execution time in milliseconds)
},
{
"amount": 70.0, // Trade quantity (amount of base currency traded)
"buyOrderId": "1942810180093739008", // Buy order ID (ID of the buy order involved in this trade)
"direction": "SELL", // Trade direction (BUY/SELL - indicates taker side)
"price": 1900.8, // Trade price (price at which trade was executed)
"sellOrderId": "1942810185709912064", // Sell order ID (ID of the sell order involved in this trade)
"symbol": "MKR/USDT", // Trading pair symbol (contract symbol identifier)
"time": 1752037018635 // Trade timestamp (trade execution time in milliseconds)
}
]
Contract Order Updates Stream
Stream Name: <symbol>@orders_contract@<ListenKey>
Order Status Values:
ENTRUST_ING
- Order in progressENTRUST_CANCEL
- Order cancelledENTRUST_FAILURE
- Order failedENTRUST_SUCCESS
- Order successful
Response:
{
"baseSymbol": "USDT", // Settlement currency (currency used for settlement)
"coinSymbol": "BTC", // Base currency (underlying asset)
"contractId": 1, // Contract ID (unique contract identifier)
"contractOrderEntrustId": "CE168553470927350", // Contract order ID (system-generated contract order ID)
"createTime": 1685534709273, // Creation time (order creation timestamp)
"currentPrice": 27100.7, // Current price (market price when order was placed)
"direction": "BUY", // Order direction (BUY for long, SELL for short)
"entrustPrice": 27110, // Order price (limit price for the order)
"entrustType": "OPEN", // Position type (OPEN for opening position, CLOSE for closing)
"isBlast": 0, // Liquidation flag (0 = normal order, 1 = liquidation order)
"isFromSpot": 0, // From spot flag (0 = contract order, 1 = from spot)
"memberId": 35084, // Member ID (user account identifier)
"openFee": 0.1, // Opening fee (fee for opening position)
"patterns": "FIXED", // Margin mode (FIXED = isolated, CROSS = cross margin)
"principalAmount": 100.0, // Margin amount (amount of margin used)
"principalUnit": "USDT", // Margin currency (currency used for margin)
"profitAndLoss": 0, // P&L (current profit and loss)
"shareNumber": 100.0, // Contract value (value per contract)
"status": "ENTRUST_SUCCESS", // Order status (current status of the order)
"symbol": "BTC/USDT", // Contract symbol (trading pair for this contract)
"tradedPrice": 27100.7, // Average price (average execution price)
"tradedVolume": 10, // Filled volume (number of contracts filled)
"triggerPrice": 0, // Trigger price (stop/trigger price, 0 if not applicable)
"triggeringTime": 0, // Trigger time (time when trigger condition was met)
"type": "LIMIT_PRICE", // Order type (LIMIT_PRICE, MARKET_PRICE, etc.)
"volume": 10 // Order volume (total number of contracts ordered)
}
Market Data API
Get Supported Contracts
Endpoint: GET /contract-swap/symbol
Authentication: NONE
Response:
[
{
"id": "1", // Contract ID (unique contract identifier)
"name": "BTC/USDT Perpetual Contract", // Contract name (full descriptive name)
"symbol": "BTC/USDT", // Trading pair (symbol for this contract)
"coinSymbol": "BTC", // Base currency (underlying asset symbol)
"baseSymbol": "USDT" // Quote currency (settlement currency symbol)
}
]
Get Order Book
Endpoint: GET /contract-swap/exchange-plate
Authentication: NONE
Response:
{
"code": 0, // Response code (0 = success)
"data": { // Response data (order book data)
"ask": { // Sell orders (ask side of order book)
"direction": "SELL", // Direction (indicates this is the sell side)
"maxAmount": "757.158", // Maximum quantity (largest order size at this level)
"minAmount": "12", // Minimum quantity (smallest order size at this level)
"highestPrice": "0.000012417", // Highest price (highest ask price in order book)
"lowestPrice": "0.000011376", // Lowest price (lowest ask price in order book)
"symbol": "SHIB/USDT", // Trading pair (contract symbol)
"items": [ // Order book items (individual price levels)
{
"price": 1.1376E-5, // Price as number (ask price in numeric format)
"amount": 530.0, // Quantity as number (ask quantity in numeric format)
"priceStr": "0.000011376", // Price as string (ask price in string format for precision)
"amountStr": "530" // Quantity as string (ask quantity in string format for precision)
},
{
"price": 1.1377E-5, // Price as number (ask price in numeric format)
"amount": 110.0, // Quantity as number (ask quantity in numeric format)
"priceStr": "0.000011377", // Price as string (ask price in string format for precision)
"amountStr": "110" // Quantity as string (ask quantity in string format for precision)
}
]
},
"bid": { // Buy orders (bid side of order book)
"direction": "BUY", // Direction (indicates this is the buy side)
"maxAmount": "757.158", // Maximum quantity (largest order size at this level)
"minAmount": "12", // Minimum quantity (smallest order size at this level)
"highestPrice": "0.000012417", // Highest price (highest bid price in order book)
"lowestPrice": "0.000011376", // Lowest price (lowest bid price in order book)
"symbol": "SHIB/USDT", // Trading pair (contract symbol)
"items": [ // Order book items (individual price levels)
{
"price": 1.1376E-5, // Price as number (bid price in numeric format)
"amount": 530.0, // Quantity as number (bid quantity in numeric format)
"priceStr": "0.000011376", // Price as string (bid price in string format for precision)
"amountStr": "530" // Quantity as string (bid quantity in string format for precision)
}
]
}
}
}
Get Recent Trades
Endpoint: GET /contract-swap/latest-trade
Authentication: NONE
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
symbol | STRING | YES | Trading pair (e.g., BTC/USDT) |
size | INT | YES | Number of trades to return |
Response:
[
{
"symbol": "MKR/USDT", // Trading pair (contract symbol)
"price": 1901.4, // Trade price (execution price of the trade)
"amount": 107.92, // Trade quantity (number of contracts traded)
"buyTurnover": null, // Buy turnover (value of buy side, may be null)
"sellTurnover": null, // Sell turnover (value of sell side, may be null)
"direction": "SELL", // Trade direction (taker side: BUY or SELL)
"buyOrderId": "1942155323041120256", // Buy order ID (ID of buy order, may be null)
"sellOrderId": "1941419078824493056", // Sell order ID (ID of sell order)
"time": 1752041625107 // Trade time (execution timestamp in milliseconds)
}
]
Get Historical K-Line Data
Endpoint: GET /contract-swap/history
Authentication: NONE
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
symbol | STRING | YES | Trading pair (e.g., BTC/USDT) |
from | LONG | YES | Start time (timestamp in milliseconds) |
to | LONG | YES | End time (timestamp in milliseconds) |
resolution | STRING | YES | Time interval (1, 5, 15, 30, 60, 240, 1D, 1W, 1M) |
Response:
[
[
1606838400000, // Timestamp (K-line start time in milliseconds)
604.13, // Open price (opening price of this K-line)
609.11, // High price (highest price in this K-line)
575.0, // Low price (lowest price in this K-line)
589.42, // Close price (closing price of this K-line)
59523720.0480131599 // Volume (total trading volume for this K-line)
]
]
Contract Trading API
Get Contract Account Info
Endpoint: GET /contract-swap-wallet/list
Authentication: USER_DATA
Response:
{
"code": 0,
"message": "SUCCESS",
"data": [
{
"id": 4, // Account ID (unique account identifier)
"balance": "111", // Available balance (account available balance)
"frozenBalance": "0", // Frozen balance (balance locked in orders)
"coin": "USDT", // Currency symbol (account currency)
"unrealizedPL": "2.4236866372" // Unrealized PnL (unrealized profit/loss for positions)
}
]
}
Transfer Funds
Endpoint: POST /contract-swap-wallet/trans
Authentication: TRADE
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
amount | NUMBER | YES | Transfer amount |
from | STRING | YES | From wallet (SPOT/SWAP/STRATEGY/TRADING) |
to | STRING | YES | To wallet (SPOT/SWAP/STRATEGY/TRADING) |
unit | STRING | YES | Currency (currency to transfer) |
timestamp | LONG | YES | Request timestamp |
recvWindow | LONG | NO | Request window (max 60000ms) |
Wallet Types:
Value | ID | Description |
---|---|---|
SPOT | 0 | Spot Wallet |
SWAP | 1 | Contract Wallet |
STRATEGY | 2 | Strategy Wallet |
TRADING | 3 | Trading Wallet |
Response:
{
"code": 0, // Response code (0 = success)
"message": "SUCCESS", // Response message (operation status)
"totalPage": null, // Total pages (pagination info)
"totalElement": null, // Total elements (total count)
"data": null // Response data (null for transfer)
}
Open Position/Close Position
Endpoint: POST /contract-swap-order/order
Authentication: TRADE
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
symbol | STRING | YES | Contract symbol (uppercase) |
direction | STRING | YES | Position direction (BUY/SELL) |
orderType | STRING | YES | Order type (LIMIT/MARKET) |
triggerPrice | NUMBER | YES | Trigger price (0 for market/limit orders) |
price | NUMBER | YES | Order price (0 for market orders) |
leverage | NUMBER | YES | Leverage (1, 10, 20, 30, ..., 100) |
amount | NUMBER | YES | Contract quantity |
newClientOrderId | STRING | NO | Client order ID (user-defined identifier) |
positionReductionIs | STRING | NO | Position reduction flag (default: IS_FALSE,IS_TRUE) |
recvWindow | LONG | NO | Request window (max 60000ms) |
timestamp | LONG | YES | Request timestamp |
Response:
{
"code": 200,
"data": {
"orderId": "96a23b53-52a4-4968-a35c-0e5e1e0ee0fb",
"symbol": "BTCUSDT",
"price": 30000,
"origQty": 1,
"executedQty": 1,
"cummulativeQuoteQty": 30000,
"status": "FILLED",
"direction": "BUY",
"orderType": "LIMIT",
"newClientOrderId": "my-client-order-123",
"transactTime": 1720425600000,
"avgPrice": 30000,
"marginFrozen": 3000,
"triggerPrice": 0,
"positionReductionIs": "IS_FALSE",
"leverage": 10,
"tradedAmount": 30000,
"fees": 18.0,
"profit": 0,
"realizedPnl": 0
},
"msg": "Success"
}
Response Fields:
Field | Type | Description |
---|---|---|
orderId | STRING | Order ID |
symbol | STRING | Contract symbol |
price | NUMBER | Order price |
origQty | NUMBER | Original quantity |
executedQty | NUMBER | Executed quantity |
cummulativeQuoteQty | NUMBER | Cumulative quote quantity |
status | STRING | Order status |
direction | STRING | Order direction (BUY/SELL) |
orderType | STRING | Order type (LIMIT/MARKET) |
newClientOrderId | STRING | Client order ID (if provided) |
transactTime | LONG | Transaction time |
avgPrice | NUMBER | Average price |
marginFrozen | NUMBER | Frozen margin |
triggerPrice | NUMBER | Trigger price |
positionReductionIs | STRING | Position reduction flag |
leverage | NUMBER | Leverage |
tradedAmount | NUMBER | Traded amount |
fees | NUMBER | Trading fees |
profit | NUMBER | Profit |
realizedPnl | NUMBER | Realized PNL |
Get Open Orders
Endpoint: GET /contract-swap-order/current
Authentication: USER_DATA
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
symbol | STRING | YES | Contract symbol |
pageNo | INT | YES | Page number |
pageSize | INT | YES | Records per page |
Response:
{
"code": 0,
"message": "SUCCESS",
"data": {
"content": [
{
"id": "1942844779544969216",
"memberId": 1938142186356458,
"price": 1814.30000000,
"totalOrderAmount": 11.00000000,
"executedAmount": 0E-8,
"maskPrice": 1914.30000000,
"status": "ENTRUST_ING",
"securityDeposit": 11.00000000,
"direction": "BUY",
"orderType": "LIMIT",
"profitLimitPrice": null,
"lossLimitPrice": null,
"triggerPrice": 0E-8,
"leverage": "1",
"userAccountType": "FIXED",
"createTimestamp": 1752045266,
"symbol": "MKR/USDT",
"coinSymbol": "MKR",
"baseCoinSymbol": "USDT",
"positionReductionIs": "IS_FALSE",
"fee": 0E-8,
"averagePrice": null,
"realProfitAndLoss": null
}
],
"totalElements": 1
}
}
Response Fields:
Field | Type | Description |
---|---|---|
id | STRING | Order ID |
memberId | LONG | Member ID |
price | DECIMAL | Order price |
totalOrderAmount | DECIMAL | Total order amount |
executedAmount | DECIMAL | Executed amount |
maskPrice | DECIMAL | Mark price |
status | STRING | Order status (ENTRUST_ING, ENTRUST_CANCEL, etc.) |
securityDeposit | DECIMAL | Security deposit (margin) |
direction | STRING | Order direction (BUY/SELL) |
orderType | STRING | Order type (LIMIT/MARKET) |
profitLimitPrice | DECIMAL | Profit limit price (null if not set) |
lossLimitPrice | DECIMAL | Loss limit price (null if not set) |
triggerPrice | DECIMAL | Trigger price |
leverage | STRING | Leverage multiplier |
userAccountType | STRING | Account type (FIXED/CROSSED) |
createTimestamp | LONG | Creation timestamp |
symbol | STRING | Contract symbol |
coinSymbol | STRING | Base currency symbol |
baseCoinSymbol | STRING | Quote currency symbol |
positionReductionIs | STRING | Position reduction flag (IS_TRUE/IS_FALSE) |
fee | DECIMAL | Order fee |
averagePrice | DECIMAL | Average execution price (null if not executed) |
realProfitAndLoss | DECIMAL | Real profit and loss (null if not executed) |
Cancel Order
Endpoint: POST /contract-swap-order/cancel
Authentication: TRADE
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
entrustId | STRING | YES | Order ID (from order list response) |
Get Position Details
Endpoint: GET /contract-swap-order/position-detail
Authentication: USER_DATA
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
symbol | STRING | YES | Contract symbol |
Response:
{
"code": 0,
"message": "SUCCESS",
"data": [
{
"id": 15,
"memberId": 1938142186356458,
"position": "11",
"canClosePosition": "11",
"price": "1916.39",
"principalAmount": "10.9945",
"usdtProfit": "0",
"pattern": "FIXED",
"leverage": 1,
"coinId": 33,
"symbol": "MKR/USDT",
"liquidationPrice": "0.958195",
"projectedProfit": "-0.0131445058",
"roe": "-0.0011955528",
"directionEnum": "BUY",
"currentPrice": null,
"markPrice": null
}
]
}
Response Fields:
Field | Type | Description |
---|---|---|
id | LONG | Position ID |
memberId | LONG | Member ID |
position | STRING | Current position size |
canClosePosition | STRING | Available position size for closing |
price | STRING | Average entry price |
principalAmount | STRING | Principal amount (margin) |
usdtProfit | STRING | Realized profit/loss in USDT |
pattern | STRING | Position type (FIXED/CROSSED) |
leverage | INT | Leverage multiplier |
coinId | INT | Coin ID |
symbol | STRING | Contract symbol |
liquidationPrice | STRING | Liquidation price |
projectedProfit | STRING | Projected profit/loss |
roe | STRING | Return on equity |
directionEnum | STRING | Position direction (BUY/SELL) |
currentPrice | STRING | Current market price (null if not available) |
markPrice | STRING | Mark price (null if not available) |
Error Codes
Code | Message | Description |
---|---|---|
0 | SUCCESS | Request successful |
1001 | INVALID_SIGNATURE | Invalid signature |
1002 | INVALID_TIMESTAMP | Invalid timestamp |
1003 | INVALID_API_KEY | Invalid API key |
1004 | RATE_LIMIT_EXCEEDED | Rate limit exceeded |
1005 | INSUFFICIENT_BALANCE | Insufficient balance |
1006 | INVALID_SYMBOL | Invalid trading pair |
1007 | INVALID_ORDER_TYPE | Invalid order type |
1008 | ORDER_NOT_FOUND | Order not found |
1009 | POSITION_NOT_FOUND | Position not found |
1010 | MARKET_CLOSED | Market closed |
Adjust Margin
Endpoint: GET /contract-swap-order/ajust-principal
Authentication: USER_DATA
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
symbol | STRING | YES | Contract trading pair symbol (uppercase) |
principal | NUMBER | YES | Margin amount to adjust |
direction | STRING | YES | Adjustment direction |
timestamp | LONG | YES | Request timestamp |
recvWindow | LONG | NO | Request window (max 60000ms) |
Response:
{
"code": 0, // Response code (0 = success)
"message": "SUCCESS", // Response message (operation status)
"totalPage": null, // Total pages (pagination info)
"totalElement": null, // Total elements (total count)
"data": null // Response data (null for adjust margin)
}