KUCOIN API Guide: Websocket Integration for Real-Time Data

Introduction

The KUCOIN REST API enforces strict access frequency controls, making Websocket the preferred method for retrieving real-time data. Establishing a single Websocket connection and subscribing to multiple channels provides optimal efficiency.

👉 Discover advanced API integration techniques

Key Components

1. Connection Token Application

Before initiating a Websocket connection:

• Obtain a token valid for 24 hours
• Tokens remain active during continuous sessions
• Recommended to refresh tokens daily

2. Establishing Connection

Upon successful connection establishment:

• System sends welcome message
• Connection activates only after receiving welcome message

{
 "id": "hQvf8jkno",
 "type": "welcome"
}

Critical Parameters:

• connectId: Unique client-generated identifier
• privateChannel: Set to true for topic-specific private messages

3. Connection Maintenance

Implement regular ping messages to maintain TCP connection:

Ping Example:

{
 "id": "1545910590801",
 "type": "ping"
}

Server Response (Pong):

{
 "id": "1545910590801",
 "type": "pong"
}

👉 Learn professional connection management strategies

Data Subscription

4. Channel Subscription

Subscribe to market data channels with these parameters:

Spot Market Example:

{
 "id": 1545910660739,
 "type": "subscribe",
 "topic": "/market/ticker:BTC-USDT,ETH-USDT",
 "privateChannel": false,
 "response": true
}

Futures Market Example:

{
 "id": 1545910660739,
 "type": "subscribe",
 "topic": "/market/ticker:XBTUSDM",
 "privateChannel": false,
 "response": true
}

Successful Acknowledgment:

{
 "id": "1545910660739",
 "type": "ack"
}

5. Unsubscribing Channels

Terminate subscriptions using similar parameters:

Spot Market Unsubscribe:

{
 "id": "1545910840805",
 "type": "unsubscribe",
 "topic": "/market/ticker:BTC-USDT,ETH-USDT",
 "privateChannel": false,
 "response": true
}

Futures Market Unsubscribe:

{
 "id": "1545910840805",
 "type": "unsubscribe",
 "topic": "/market/ticker:XBTUSDM",
 "privateChannel": false,
 "response": true
}

Best Practices

• Maintain regular ping intervals
• Implement token rotation every 24 hours
• Utilize batch subscriptions for efficiency
• Monitor connection status via welcome/pong messages

FAQ Section

Q1: How often should I refresh my connection token?
A: Refresh tokens every 24 hours for security, though they remain valid during active connections.

Q2: What happens if my ping interval is too long?
A: Extended intervals may cause server-side disconnection. Match your ping frequency to the server's pingInterval.

Q3: Can I subscribe to multiple currency pairs simultaneously?
A: Yes, separate multiple trading pairs with commas in the topic parameter.

Q4: How do I verify my subscription succeeded?
A: Set response=true to receive acknowledgment messages from the server.

Q5: What's the difference between private and public channels?
A: Private channels deliver account-specific data while public channels provide market-wide information.

Q6: How quickly should I reconnect after disconnection?
A: Implement immediate reconnection logic with exponential backoff for rate-limited scenarios.