Changes to V5 API WebSocket Subscription Parameters and URLs

·

As part of OKX's ongoing commitment to platform stability and enhanced user experience, important updates are being introduced to the V5 API WebSocket service. These changes involve both subscription parameters and service URLs for specific trading channels. If you're an API user engaged in algorithmic trading, block trading, or real-time data monitoring, understanding and implementing these adjustments is crucial to maintaining uninterrupted access to key market and order data.

The originally planned update at the end of May 2023 has been postponed to allow more time for integration. The final cutover will now take place during a scheduled maintenance window: from 9:10 AM to 9:50 AM UTC on June 20, 2023. This narrow timeframe ensures minimal disruption while enabling a smooth transition across live and demo environments.

Update 1: Replacement of Subscription Parameter "uly" with "instFamily"

A core change in this update involves the deprecation of the uly subscription parameter. Currently, uly is used to specify the underlying for certain derivative products and is internally mapped to the instFamily parameter. However, after June 20, 2023, using uly will result in a subscription error and no data will be returned.

👉 Upgrade your WebSocket integration now to avoid service disruption.

What You Need to Do

For example, instead of:

{
  "op": "subscribe",
  "args": [
    {
      "channel": "block-tickers",
      "uly": "BTC-USD"
    }
  ]
}

Use:

{
  "op": "subscribe",
  "args": [
    {
      "channel": "block-tickers",
      "instFamily": "BTC-USD"
    }
  ]
}

This change improves consistency across the API suite and aligns with standardized instrument grouping practices. It applies universally—whether you're accessing public market data or private order streams.

Update 2: Migration to New "/business" WebSocket Service URL

In addition to parameter updates, certain high-demand WebSocket channels are being migrated to a dedicated service endpoint: /ws/v5/business. This new URL consolidates advanced trading functionality under a single, optimized infrastructure layer designed for reliability and scalability.

Affected Channels

Only the channels listed below require migration to the new /business URL. All other public and private channels (e.g., order books, trades, basic ticker data) remain unaffected and will continue operating via /public and /private endpoints.

Block Trading Channels

Algo & Strategy Trading Channels

Candlestick Data Channels

These channels are now served exclusively through the /business endpoint in both live and demo environments.

Updated WebSocket Endpoints

Live Trading (Production)

EnvironmentCurrent URL(s)Updated URL
Public & Private

wss://ws.okx.com:8443/ws/v5/public
wss://wsaws.okx.com:8443/ws/v5/private |
wss://ws.okx.com:8443/ws/v5/business
wss://wsaws.okx.com:8443/ws/v5/business |

🔹 The new /business URL supports both public and private channels for the listed services.
🔹 Both domains (ws.okx.com, wsaws.okx.com) are supported for redundancy.

Demo Trading (Testnet)

EnvironmentCurrent URL(s)Updated URL
Public & Private

wss://wspap.okx.com:8443/ws/v5/public?brokerId=9999
wss://wspap.okx.com:8443/ws/v5/private?brokerId=9999 |
wss://wspap.okx.com:8443/ws/v5/business?brokerId=9999 |

🔹 The brokerId=9999 parameter remains required for demo access.

👉 Ensure your WebSocket clients connect to the correct endpoint before June 20.

Recommended Implementation Sequence

To ensure a seamless transition:

  1. First, update all subscription payloads to use instFamily instead of uly.
  2. Then, reconfigure your WebSocket client connections to point to /ws/v5/business for the affected channels.
  3. Test thoroughly in the demo environment before deploying to production.
  4. Monitor logs during the cutover window (June 20, 09:10–09:50 UTC) for any connectivity issues.

Failure to complete both steps may result in data loss, failed subscriptions, or disconnected sessions.

Core Keywords for SEO Integration

To align with search intent and improve discoverability, the following keywords have been naturally integrated throughout this guide:

These terms reflect common queries from developers, quant traders, and institutional users relying on real-time data feeds.

Frequently Asked Questions (FAQ)

Q1: What happens if I don’t update by June 20?

After the cutover, any subscription using the uly parameter or connecting to old URLs (/public, /private) for affected channels will fail. No data will be delivered, which could disrupt trading algorithms or monitoring systems.

Q2: Are all WebSocket channels moving to /business?

No. Only the channels listed in the "Affected Channels" section require migration. Standard market data (like order books and trades) continues to use existing endpoints.

Q3: Do I need separate connections for public and private data under /business?

No. The /business endpoint supports both public and private channels over a single connection when authenticated appropriately.

Q4: Can I test the new setup in advance?

Yes. The updated endpoints are already active in both demo and live environments. You can begin testing immediately using the new URLs and instFamily.

Q5: Is there downtime expected during the update window?

A brief service interruption is possible during the maintenance window (9:10–9:50 UTC). Plan critical operations outside this period if possible.

Q6: Where can I find full API documentation?

Complete reference materials, including JSON schema examples and error codes, are available in the official OKX API documentation portal.

👉 Access comprehensive API tools and documentation resources today.

By proactively adapting to these changes, developers and traders ensure continued access to high-performance trading infrastructure. Staying up-to-date with OKX’s API evolution not only prevents disruptions but also unlocks future enhancements built on a more robust and scalable foundation.