Keep Alive

WebSocket trade event push is a long-lived connection service. Clients need to correctly handle WebSocket protocol-level ping/pong, network timeouts, reconnection, and re-authentication after reconnection.

WARNING

The trade push service does not define a business-layer JSON heartbeat message. Do not send custom business heartbeat frames such as { "action": "heartbeat" } or { "type": "ping" } to the connection, and do not expect the server to return a JSON heartbeat event.

Connection keep-alive should use the WebSocket protocol-level ping/pong capability, or the connection state, timeout, and reconnection mechanisms provided by your client SDK or WebSocket library.

Ping / Pong

The WebSocket protocol natively supports ping/pong control frames. Handling varies by runtime environment:

Client Type	Recommendation
Browser WebSocket	The browser automatically responds to server pings at the protocol level. Business code typically cannot send or listen to protocol-level ping/pong directly — just handle open, message, error, and close events.
Server-side clients (Node.js, Java, Go, Python, etc.)	Prefer the built-in ping/pong, read/write timeout, and idle detection capabilities of the WebSocket library. Respond to server pings with a pong promptly; if the library requires the client to initiate pings, configure according to your network environment.
Mobile or poor-network environments	Watch for connection suspension caused by foreground/background switches, network switches, or system power-saving policies. After network recovery, check connection state and reconnect if necessary.

The platform does not require clients to send heartbeats in any fixed JSON format. If your WebSocket library supports protocol-level ping, enable its built-in ping/pong mechanism. If the runtime does not expose protocol-level ping, use connection close events and business message idle detection to determine whether the connection is still healthy.

Periodic Token Refresh

Access tokens issued by OAuth 2.1 have an expiry. To prevent the server from closing the connection due to token expiry, clients should refresh the token before it expires:

1. Record expires_in (validity in seconds) when the token is obtained.
2. Use the Refresh Token to obtain a new Access Token when the token is halfway through its validity period or 5 minutes before expiry.
3. After obtaining the new token, re-send an authentication message on the current WebSocket connection to complete the token update.
4. If the refresh fails (for example, the Refresh Token has also expired), prompt the user to re-authorize.

TIP

Periodic token refresh is a critical step for keeping a long connection alive. Even if the network and WebSocket protocol-level ping/pong are working fine, the server will close the connection once the token expires.

Timeout Handling

Long connections can drop or become unavailable due to:

• Local network switches, proxy or firewall interruptions.
• Client process sleeping, mobile app going to background, system reclaiming network resources.
• Server deployments, scaling events, or maintenance.
• Idle timeout determined by intermediate links or the WebSocket library when no effective reads or writes occur for an extended period.

Recommended timeout strategies:

1. Connection establishment timeout: If the connection does not reach the open state within a reasonable time after initiating, close the attempt and retry.
2. Authentication response timeout: Authentication must be completed after the connection is established. If the authentication request receives no response for an extended time, close the connection and re-establish it.
3. Business message idle detection: If the connection is open but no messages have been received for an extended period, use protocol-level ping/pong to check whether the connection is still healthy. Do not immediately assume the connection is broken just because there are no trade events — trade push is passively triggered and will not produce messages if no trade events occur.

Set specific timeout durations according to the client's network environment, the product's real-time requirements, and the WebSocket library's capabilities.

Reconnection

When a close event is received, the connection encounters an error, authentication fails, or a connection failure is detected locally, the client should re-establish the WebSocket connection.

Recommended reconnection flow:

1. Stop sending new requests on the old connection.
2. Clean up local state for the old connection, such as pending response requests, the connection object, and temporary timers.
3. Reconnect using a backoff strategy to avoid high-frequency retries over a short period.
4. Re-authenticate after the connection is established.
5. After authentication succeeds, the server automatically re-establishes the push channel and continues pushing subsequent events.
6. If you need to catch up on order or fill status during the disconnect period, use REST APIs as needed.

Use exponential backoff or stepped backoff — retry quickly after the first disconnect, then gradually increase wait times after repeated failures, up to a maximum retry interval. Do not retry at high frequency indefinitely when the network is unavailable or the server is continuously rejecting connections.

Re-authentication

The WebSocket push channel is tied to the current connection session. After a disconnect, do not assume the server still retains the authentication state from the old connection.

After every reconnection, restore in this order:

Establish WebSocket connection
  -> Authenticate
  -> Receive push events

Notes:

• Re-authentication is required after every reconnection. Do not reuse the session state of the old connection.
• If the access credentials have expired, refresh them first, then re-establish the connection and re-authenticate.

Supplementing State with REST

WebSocket push is best suited for receiving real-time event notifications — it is not designed to be the sole source for state reconstruction. Use REST APIs in the following scenarios:

Scenario	Recommended Approach
Page first load	Call REST first to query current order and fill state and render the initial screen quickly; then establish the WebSocket connection to receive subsequent events.
After successful reconnection	Use REST to query any order state changes that may have been missed during the disconnect, then continue consuming WebSocket push.
Recovery after a long background period	First check whether the connection is still valid; if reconnection occurred, use REST to catch up on the latest state at the time of recovery.

Common Misconceptions

Misconception	Explanation
Sending a JSON heartbeat packet is sufficient to keep the connection alive	Trade push does not define a business-layer JSON heartbeat protocol. Use the WebSocket protocol-level ping/pong or the connection keep-alive capabilities of your client library.
Push state recovers automatically after a disconnect	This should not be assumed. Re-authenticate after reconnection; events that occurred during the disconnect will not be replayed.
No push messages means the connection is broken	Trade events are passively triggered — no messages will be pushed if no trades occur. This cannot be used to determine that the connection is broken.

Next Steps

• Authentication — Learn about the authentication flow after establishing a connection.
• Subscription — Learn about event push coverage and client implementation recommendations.
• Data Format — Learn about push message structure and fields.
• Error Codes — Troubleshoot authentication and connection errors.