Tips and Tricks for Using the OKX V5 API (1)

The evolution of digital asset trading platforms has brought about significant improvements in both user experience and technical infrastructure. With the launch of its Unified Trading Account system, OKX upgraded its API from version V3 to V5, introducing a more powerful, flexible, and developer-friendly interface. This article explores key changes in the OKX V5 API, highlights essential setup tips before trading, and provides practical guidance for developers integrating with this modern API framework.

Whether you're building automated trading bots, managing multi-account strategies, or simply aiming to streamline your workflow, understanding these foundational aspects will help you maximize efficiency and security.

👉 Discover how seamless API integration can elevate your trading strategy.

Key Changes in the OKX V5 API

Unified API Across All Products

One of the most significant improvements in V5 is the unified API endpoint structure across all product types. Unlike V3, where endpoints were segmented by product (e.g., spot, futures), V5 consolidates order placement and position management under shared endpoints.

For example:

POST /api/v5/trade/order

This single endpoint handles orders for spot, margin, futures, and options. All you need to do is specify the product type (via instType) in the request body. The request and response formats remain consistent regardless of asset class.

✅ Benefit: You no longer need separate models or logic branches for different products—simplifying code maintenance and reducing development overhead.

Streamlined Field Naming Convention

To optimize performance and reduce data payload size, V5 adopts camelCase with concise abbreviations instead of verbose naming used in V3.

Field Description	V5 API (Abbreviated)	V3 API (Verbose)
Currency	`ccy`	`currency`
Instrument ID	`instId`	`instrument_id`
Underlying Index	`uly`	`underlying`
Unrealized PnL	`upl`	`unrealized_pnl`

This change not only reduces bandwidth usage but also improves parsing speed—especially critical for high-frequency applications.

Standard WebSocket Data Compression

V5 introduces support for Per-Message Deflate, a standard WebSocket compression extension. This means incoming messages are automatically compressed at the transport level, eliminating the need for manual decompression as required in V3.

To enable compression:

Ensure your WebSocket client supports permessage-deflate.
When connecting, include the header:
Sec-WebSocket-Extensions: permessage-deflate.

✅ Result: Faster message processing and reduced latency—ideal for real-time market data consumption.

Public vs. Private WebSocket Channels

WebSocket channels are now clearly categorized into two types:

Public Channels: Market data, K-lines, tickers — accessible without authentication.
Private Channels: Account updates, order fills, positions — require login.

Each category uses a different base URL:

Public: wss://ws.okx.com:8443/ws/v5/public
Private: wss://ws.okx.com:8443/ws/v5/private

⚠️ Important: Do not send login requests when connecting to public channels—doing so will cause subscription failures.

Place Orders via WebSocket

In addition to REST APIs, V5 now supports order placement, modification, and cancellation over WebSocket. This allows for lower-latency interactions compared to traditional HTTP round-trips.

Use cases:

High-frequency execution
Real-time strategy adjustments based on streaming data
Synchronized order-book monitoring and trading

👉 Learn how low-latency trading via WebSocket can boost performance.

While detailed implementation is covered in part 2 of this series, developers should already prepare their systems to handle bidirectional communication securely and efficiently.

Authentication: REST & WebSocket Login

Authentication remains largely consistent with V3:

REST API: Sign requests using your API key, passphrase, and timestamp.
WebSocket: Send a login message with signed credentials in JSON format (now using key-value pairs).

Example WebSocket login payload:

{
  "op": "login",
  "args": [
    {
      "apiKey": "your_api_key",
      "passphrase": "your_passphrase",
      "timestamp": "ISO8601_timestamp",
      "sign": "base64_encoded_signature"
    }
  ]
}

This standardized format simplifies integration across languages and frameworks.

Managing Sub-Accounts via API

A powerful addition in V5 is the ability to programmatically manage sub-account API keys from a master account.

Available operations:

Action	Endpoint
Create	`POST /api/v5/users/subaccount/apikey`
Query	`GET /api/v5/users/subaccount/apikey`
Modify	`POST /api/v5/users/subaccount/modify-apikey`
Delete	`POST /api/v5/users/subaccount/delete-apikey`

🔐 Best Practice: Always bind API keys to specific IP addresses to minimize unauthorized access risks—even if the key is compromised.

Configuring Your Trading Account

After setting up sub-accounts and keys, configure each account’s behavior to match your strategy.

Retrieve Account Configuration

Use this endpoint to check current settings:

GET /api/v5/account/config

Returns:

Account mode
Position mode
Auto-borrow settings
Options Greeks calculation method (PA/BS)

Account Mode

OKX offers three account modes:

Spot Only
Spot & Derivatives
Cross-Currency Margin

⚠️ Note: Changing account mode must be done manually via the web interface—not through API.

Position Mode

Choose between:

Single-Position Mode: Hold either long or short at a time. The system auto-manages open/close logic.
Dual-Position Mode: Maintain both long and short positions simultaneously (traditional “buy/sell” model).

Set via:

POST /api/v5/account/set-position-mode

❗ Requirement: All existing positions must be closed before switching.

Auto-Borrow (Cross-Currency Margin)

Enables automatic borrowing across currencies when margin is insufficient. Currently configurable only via the OKX website.

Options Greeks: PA vs BS

You can select the calculation model for options Greeks:

PA (Portfolio Approach)
BS (Black-Scholes Model)

Set via:

POST /api/v5/account/set-greeks

This choice affects risk evaluation accuracy—especially important for advanced options strategies.

Margin Modes: Isolated vs Cross

With Unified Account, you can now use both isolated and cross margin modes simultaneously on the same instrument.

Unlike V3, there's no dedicated API to set margin mode globally. Instead, you define it per order during submission using the tdMode parameter:

cross: Cross-margin
isolated: Isolated-margin
cash: Cash (for spot)

This granular control enables dynamic risk allocation across trades.

Managing Leverage Settings

Leverage is no longer set globally—it’s defined per product and context.

Get Current Leverage

GET /api/v5/account/leverage-info

Supports multiple scenarios:

Spot margin trading
Futures (delivery & perpetual)
Options

Set Leverage

POST /api/v5/account/set-leverage

Used programmatically to pre-configure leverage before entering trades.

Example Use Case

Assume:

Account Mode: Cross-Currency Margin
Position Mode: Single-direction
Target Leverage: 3.0x
Instruments:
- Spot: BTC-USDT, EOS-USDT, LTC-BTC, LTC-USDT
- Futures: BTC-USD-210319, BTC-USD-210326, BTC-USD-210625
- Perpetual: BTC-USD-SWAP

Step-by-step Setup:

Spot/Margin Pairs: Set leverage by currency (BTC, USDT, EOS, LTC)
Futures Contracts: Leverage applies per underlying (BTC-USD). One request covers all delivery contracts with that underlying.
Perpetual Swap: Requires a separate request—even if underlying is the same.

Total: 6 API calls → 8 instruments configured.

This modular approach gives precise control without over-provisioning risk.

Frequently Asked Questions (FAQ)

Q: Can I change account mode via API?
A: No. Account mode changes must be made manually through the OKX website for security reasons.

Q: Does leverage setting apply automatically to all contracts?
A: No. Delivery and perpetual swaps have independent leverage settings—even with the same underlying asset.

Q: Can I use WebSocket for all order operations?
A: Yes. V5 supports full order lifecycle management over WebSocket—including place, amend, cancel—for reduced latency.

Q: Is IP binding mandatory for API keys?
A: Not mandatory, but strongly recommended to enhance security and prevent unauthorized access.

Q: How does single-position mode affect trading logic?
A: It simplifies execution—you specify direction and size; the system handles opening or closing accordingly.

Q: Where can I find updated V5 API documentation?
A: Always refer to the official OKX V5 API Docs for the latest specifications and endpoints.

👉 Access powerful tools and documentation to supercharge your trading.

Final Thoughts

The OKX V5 API represents a major leap forward in functionality, consistency, and developer experience. By unifying endpoints, optimizing payloads, and expanding capabilities like sub-account management and WebSocket trading, it empowers traders and developers alike to build robust, scalable solutions.

In part 2 of this series, we’ll dive into advanced topics such as real-time order book syncing, handling trade execution notifications, and reconciling positions using streaming data—so stay tuned.

As OKX continues to refine its Unified Trading Account system, always ensure your integrations align with the latest API standards.