Product Configuration
Retrieve exchange product configurations using:
👉 GET /api/v5/public/instruments
Real-time updates (e.g., price tick changes, new listings) are pushed via WebSocket's:
👉 Instruments Channel
Market Data
WebSocket Channels
bbo-tbt/books5: Depth snapshots published every 10ms/100ms (no updates during order book inactivity)Incremental Channels:
books(100ms updates)books-l2-tbt/books50-l2-tbt(10ms updates, requires VIP4+ authentication)
Note: All WebSocket connections receive identical order book data synchronized every 10ms.
Account Configuration
Initial Setup
Configure main/sub-accounts via API after creating API keys. Retrieve current settings using:
👉 GET /api/v5/account/config
Key Features
| Feature | Description |
|---|---|
| Account Modes | Spot, Contract, Cross-Margin, Portfolio Margin (web/app only) |
| Position Modes | Buy/Sell Mode (auto open/close) vs Open/Close Mode (simultaneous long/short) |
| Auto-Borrow | Available in Cross-Margin/Portfolio Margin modes only |
Order Management
Trading Modes (tdMode)
| Scenario | Required Value |
|---|---|
| Spot Trading | cash |
| Cross-Margin | cross |
| Isolated Margin | isolated |
WebSocket Workflow
- Subscribe to
Order Channel Place Orders via REST/WebSocket:
{ "instId": "BTC-USDT-SWAP", "tdMode": "cross", "side": "buy", "ordType": "limit", "px": "50912.4", "sz": "1" }- Monitor States:
live→partially_filled→filled/canceled
Pro Tip: Use unique clOrdId (32-char alphanumeric) for easier tracking.
Risk Management
Self-Trade Prevention (STP)
| Mode | Action |
|---|---|
cancel_maker (Default) | Cancels maker order |
cancel_taker | Cancels taker order |
cancel_both | Cancels both orders |
Account & Position Tracking
WebSocket Subscriptions
- Account Updates:
Account Channel - Position Updates:
Positions Channel
Reconciliation
Match tradeId from order fills with position updates. Note:
- Multiple fills may aggregate into single position updates
- Liquidations/ADL don't trigger order updates
System Status
Check exchange operational status via:
👉 GET /api/v5/system/status
FAQ
How often are position updates sent?
Positions push updates on events (opens/closes) and every 5 seconds for full data refresh.
Can I trade the same product with different margin modes?
Yes! You can simultaneously trade a product using both cross/isolated margin by specifying tdMode per order.
What happens during self-trades?
Depends on your STP mode. By default, maker orders are canceled while taker orders proceed.
How to handle API rate limits?
Batch operations support up to 20 orders per request. Use WebSocket for higher efficiency with asynchronous updates.