The introduction of OKX's Unified Account trading system brought a significant upgrade from the V3 to the V5 API, offering more robust and comprehensive functionality. This guide explains the key changes in the V5 API and provides practical tips for configuring your account before you begin trading.
Key Changes in the V5 API
Unified API for All Products
A major improvement is the consolidation of all product types under a single API endpoint. Unlike the V3 API, which required different endpoints for different products, the V5 API uses a unified structure for actions like placing orders or checking positions.
For example, to place an order for any product, you now send a POST request to:/api/v5/trade/order
You simply specify the product type within the request body. This means you no longer need to build separate data models for each product type, streamlining the development process.
Streamlined Naming Convention
The V5 API adopts a camelCase naming style for its fields and uses more abbreviations. This reduces the amount of data transmitted, saving bandwidth and minimizing memory overhead.
Here’s a comparison of some common fields:
| Field Description | V5 API Field | V3 API Field |
|---|---|---|
| Currency | ccy | currency |
| Instrument ID | instId | instrument_id |
| Underlying Index | uly | underlying |
| Unrealized PnL | upl | unrealized_pnl |
Standardized WebSocket Data Compression
The V5 API utilizes the standard "Per-Message Deflate" extension for WebSocket compression. This eliminates the need for the manual decompression required in V3. To use this feature, ensure your client enables this extension. The request header should include permessage-deflate once activated.
Separate Public and Private WebSocket Channels
WebSocket channels are now categorized into two distinct types:
- Public Channels: For market data, such as tickers and K-lines.
- Private Channels: For account-specific information, like positions and balances.
Each channel type has a different URL. Crucially, you must not send a login request when connecting to a public channel, or the subscription will fail.
WebSocket Trading
Beyond REST API, the V5 API now supports placing, amending, and canceling orders directly via WebSocket connections. This can provide lower latency for high-frequency trading strategies. 👉 Explore advanced trading methods
Authentication Methods
REST API authentication remains unchanged from V3; you add a signature to the request header. WebSocket authentication is also similar but now uses a key-value pair format for the login request.
Creating Subaccount API Keys
The V5 API allows you to perform CRUD (Create, Read, Update, Delete) operations on subaccount API keys directly from the main account.
| Action | Endpoint |
|---|---|
| Create | POST /api/v5/users/subaccount/apikey |
| Query | GET /api/v5/users/subaccount/apikey |
| Update | POST /api/v5/users/subaccount/modify-apikey |
| Delete | POST /api/v5/users/subaccount/delete-apikey |
For enhanced security, it is highly recommended to bind your API keys to specific IP addresses during creation.
Configuring Your Account
After creating subaccounts and API keys, the next critical step is to configure each account's trading parameters.
Checking Account Configuration
You can retrieve the current configuration of any account or subaccount using:
GET /api/v5/account/config
This returns information on:
- Account Mode
- Position Mode
- Auto-Borrow settings (for Cross-Margin mode)
- Greek display setting (PA or BS) for options.
Selecting an Account Mode
The Unified Account system offers several modes: (i) Simple, (ii) Single-currency Margin, and (iii) Multi-currency Margin. Changing your account mode requires manual confirmation and can only be done via the OKX website.
Understanding Position Modes
The system introduces a new One-Way Position Mode while retaining the classic Two-Way Position Mode.
| Mode | Description |
|---|---|
| One-Way (Netting) | You can only hold a single long or short position per instrument. The exchange automatically opens or closes positions based on your order quantity. |
| Two-Way (Hedging) | You can simultaneously hold both long and short positions for the same instrument. |
You can set the position mode via API:
POST /api/v5/account/set-position-mode
Note: You must close all existing positions before switching modes.
Auto-Borrow and Greek Settings
The Auto-Borrow feature, available in Multi-currency Margin mode, is managed exclusively on the website. Similarly, the option to set Greeks to be displayed as PA (Position Asset) or BS (Black-Scholes) is done via a familiar API endpoint: POST /api/v5/account/set-greeks.
Managing Margin and Leverage
The Unified Account system offers flexible isolated and cross-margin trading. You can trade the same instrument using different margin modes simultaneously. Consequently, the V5 API does not have a dedicated endpoint for setting the margin mode at the underlying index level. Instead, you specify the margin mode (isolated or cross) for each individual order when you place it.
Leverage Setup
Retrieving Leverage Information
To check current leverage settings, use:
GET /api/v5/account/leverage-info
Leverage is not set globally; different leverage values can be applied to various products and scenarios.
Setting Leverage
After assessing your current leverage, you can adjust it to fit your trading strategy:
POST /api/v5/account/set-leverage
By using these two APIs, you can programmatically set the leverage for each instrument before executing trades.
Practical Example:
Assume you have the following setup and requirements:
- Account Mode: Multi-currency Margin
- Position Mode: One-Way
Target Leverage: 3.0 for the following instruments:
- Spot: BTC-USDT, EOS-USDT, LTC-BTC, LTC-USDT
- Futures: BTC-USD-210319, BTC-USD-210326, BTC-USD-210625
- Swap: BTC-USD-SWAP
- Margin Mode: Cross for all
For spot and margin trading, leverage is set at the currency level. You would extract the currencies (BTC, USDT, EOS, LTC) and set leverage for each.
Example request body to set leverage for BTC to 3.0 (affecting selling BTC-USDT and buying LTC-BTC):
{
"ccy": "BTC",
"lever": "3",
"mgnMode": "cross"
}Similar requests would be made for USDT, EOS, and LTC.
Next, set leverage for the futures contracts. Since BTC-USD-210319, BTC-USD-210326, and BTC-USD-210625 share the same underlying index (BTC-USD), setting the leverage for one of them will apply to all futures with that underlying.
Finally, set leverage for the swap contract. Even though it shares the same underlying, leverage for perpetual swaps and futures are managed independently. A separate request is required:
{
"instId": "BTC-USD-SWAP",
"lever": "3",
"mgnMode": "cross"
}After sending these 6 API requests, the leverage setup for your 8 instruments is complete.
Frequently Asked Questions
What is the main advantage of the V5 API's unified endpoint?
The unified endpoint simplifies development by allowing you to use a single API structure for all product types. This reduces code complexity and maintenance, as you no longer need unique models for spot, futures, or swaps.
Can I use both isolated and cross margin on the same instrument?
Yes, the Unified Account system allows you to have positions on the same instrument using different margin modes simultaneously. You specify the desired mode (isolated or cross) when placing each individual order.
Why must I use the website to change my account mode?
Changing your account mode (e.g., from Simple to Multi-currency Margin) can significantly affect your risk and margin calculations. Requiring this action on the website ensures users manually confirm they understand these changes, adding a layer of safety.
How does One-Way position mode differ from Two-Way mode?
In One-Way mode, your orders simply increase or decrease your net position. In Two-Way mode, you can hold opposing long and short positions simultaneously for hedging purposes. The mode determines how your orders are interpreted by the system.
Is WebSocket compression enabled by default?
No, the "Per-Message Deflate" compression for WebSocket data is not automatic. You must configure your client to request and enable this extension during the WebSocket handshake to benefit from reduced data transfer.
What is the best practice for API key security?
The most crucial practice is to bind your API keys to specific IP addresses. This restricts access so that even if the key is compromised, it cannot be used from an unauthorized server location.
Summary
By applying these tips and tricks, you can effectively use the new V5 API to manage subaccounts and configure critical settings like position modes and leverage to match your trading style. These steps ensure your account is optimized and secure before you start live trading.
Please note that OKX continuously improves its Unified Account system, so some details may change. Always refer to the official V5 API documentation for the most current specifications.