OKX V5 API Trading Guide: Tips for Orders and Positions

·

The OKX V5 API introduces a suite of advanced features and refined trading capabilities, designed to enhance your automated and programmatic trading experience. This guide provides essential tips and strategies for leveraging the V5 API effectively, covering order placement, position management, and data synchronization.

Introduction to OKX V5 API

With the launch of OKX's Unified Account system, the API has been upgraded from V3 to V5. This upgrade brings significant improvements in functionality, flexibility, and performance. While our previous guide covered the differences between V3 and V5 and initial account setup, this article dives into practical trading techniques using the V5 API.

Key enhancements include:

Understanding Trading Modes

In the Unified Account system, you can trade the same instrument in both isolated and cross margin modes simultaneously. Each order must specify its trading mode using the tdMode field.

Common scenarios and required tdMode values:

You can also set the instType parameter to ANY to subscribe to order updates across all product types.

Note: The order channel does not provide an initial full data snapshot. Updates are pushed only when order status changes (e.g., from open to canceled).

To retrieve pending orders before subscribing, use the REST API:

GET /api/v5/trade/orders-pending

Placing Orders

Once subscribed to the order channel, you can place orders for instruments like BTC-USDT-SWAP. The V5 API supports both REST and WebSocket protocols for order placement.

REST API Order Placement

Use the following REST endpoint to place orders. The server responds with an order ID (ordId).

Example request:

{
  "id": "NEWtestBTC012",
  "op": "order",
  "args": [{
    "side": "buy",
    "instId": "BTC-USDT-SWAP",
    "tdMode": "cross",
    "ordType": "limit",
    "px": "50000",
    "sz": "0.001"
  }]
}

Example response:

{
  "id": "NEWtestBTC012",
  "op": "order",
  "code": "0",
  "msg": "",
  "data": [{
    "ordId": "123456789",
    "clOrdId": "NEWtestBTC012",
    "tag": "",
    "sCode": "0",
    "sMsg": ""
  }]
}

Upon full order execution, you'll receive a WebSocket push with the order status updated to filled, along with relevant trade details including the tradeId field.

WebSocket Order Placement

WebSocket offers real-time order placement without polling. After authenticating your private WebSocket connection, send order requests similarly to the REST structure.

Account and Position Data Management

WebSocket Subscription for Account Data

The accounts channel provides initial full data snapshots for currencies with non-zero equity (eq), available margin (availEq), or available balance (availBal).

Example snapshot for a cross-margin account with BTC and USDT:

{
  "event": "snapshot",
  "arg": { "channel": "account", "ccy": "BTC,USDT" },
  "data": [{
    "uTime": "1614857751636",
    "totalEq": "100000.00",
    "details": [{
      "ccy": "BTC",
      "eq": "5.00000000",
      "availEq": "4.50000000"
    }, {
      "ccy": "USDT",
      "eq": "50000.00",
      "availBal": "49500.00"
    }]
  }]
}

For spot trading, availBuy represents the quote currency, while availSell represents the base currency.

👉 Explore real-time account monitoring tools

Managing Positions

The V5 API unifies position data across all products. WebSocket subscriptions are recommended for real-time updates.

WebSocket Position Subscriptions

Subscribe to position updates using various dimensions. For BTC-USDT-SWAP positions, send one of these requests after authenticating:

Position Data Push Mechanisms

Position IDs

Each position has a unique ID (posId) generated from mgnMode + posSide + instId + ccy. This ID persists even after closing and reopening a position.

REST API for Positions

Retrieve non-zero positions via:

GET /api/v5/account/positions

Query by:

Note: Querying by posId returns data even for closed positions, unlike WebSocket.

Reconciling Orders and Positions

Use the tradeId field from order fills to reconcile with position updates. Newer trades have higher tradeId values.

Considerations:

Compare both tradeId and position quantity (or update time uTime) for accurate reconciliation.

Example sequence analysis:

SeqChannelDataReconciled Pos
1orderfillSz=20, side=buy, tradeId=15020
2positionspos=20, tradeId=150, uTime=161485975163620
3positionspos=18, tradeId=151, uTime=161485975263718
4orderfillSz=2, side=sell, tradeId=15118
7positionspos=10, tradeId=163, uTime=161485975503710

Observations:

👉 Get advanced position management strategies

Frequently Asked Questions

What is the difference between isolated and cross margin in V5 API?
Isolated margin restricts margin to a single position, while cross margin shares margin across positions. Specify using the tdMode field when ordering.

How do I get real-time order updates?
Subscribe to the order channel via WebSocket. Note: no initial snapshot is provided; use GET /api/v5/trade/orders-pending to get current open orders first.

Why are my order pushes not matching position updates?
Multiple orders may aggregate into one position push. Also, liquidations and ADL events don't generate order pushes but do update positions. Always compare both tradeId and uTime.

How often do position updates occur?
Event-triggered pushes occur on changes, while scheduled pushes occur every 10 seconds for all non-zero positions.

Can I retrieve historical positions?
Yes, using the REST API with posId parameter returns data even for closed positions, unlike WebSocket.

What is the advantage of using WebSocket over REST?
WebSocket provides real-time, bidirectional communication without polling, reducing latency and API rate limit consumption.

Conclusion

Mastering the OKX V5 API enables sophisticated algorithmic trading strategies within the Unified Account system. Key takeaways include:

As OKX continues to enhance its trading system, always refer to the latest V5 API documentation for updates. These techniques will help you trade more effectively and build robust automated systems.