How to use the KuCoin API for trading bots? (Developer Tools)

Authentication Mechanism

1. KuCoin API requires HMAC-SHA256 signature generation for all private endpoints. The signature is derived from a concatenation of timestamp, HTTP method, endpoint path, and optional request body.

2. Each request must include three headers: KC-API-KEY, KC-API-TIMESTAMP, and KC-API-SIGN. The timestamp must be within 5 seconds of KuCoin’s server time.

3. The API key pair must be generated from the KuCoin user interface under API Management. Permissions should be restricted to only necessary scopes such as “Trade”, “Account”, or “Withdraw”.

4. Secret keys are never transmitted over the wire. They remain local to the bot environment and are used solely for signing outgoing requests.

5. IP whitelisting is enforced by default for newly created API keys. Developers must register trusted IPs in advance to avoid 401 unauthorized responses.

Order Lifecycle Management

1. Placing an order uses the POST /api/v1/orders endpoint with parameters like symbol, side (buy/sell), type (limit/market/stop), and size or price.

2. Market orders require only size and side; limit orders mandate both price and size. Stop orders introduce additional fields like stopPrice and stop.

3. Active orders can be queried via GET /api/v1/orders?status=active, returning paginated results with order IDs, status, filled size, and remaining size.

4. Canceling a single order uses DELETE /api/v1/orders/{order-id}, while bulk cancellation targets multiple IDs using DELETE /api/v1/orders?symbol=BTC-USDT.

5. Order execution status is tracked through WebSocket feeds or polling the GET /api/v1/fills endpoint, which returns trade history including fee amounts and timestamps.

Market Data Integration

1. Public ticker data is retrieved via GET /api/v1/market/orderbook/level2_20?symbol=BTC-USDT, delivering top 20 bid/ask levels with price, size, and sequence number.

2. Real-time updates are supported through KuCoin’s WebSocket v2 channel /market/ticker:{symbol}, where clients subscribe using JSON messages containing topic and privateChannel flags.

3. Historical kline data is fetched with GET /api/v1/market/candles?symbol=ETH-USDT&interval=1min&startAt=1698777600&endAt=1698781200, supporting intervals from 1 minute to 1 day.

4. Symbols list and trading pair details are available at GET /api/v2/symbols, including baseCurrency, quoteCurrency, priceIncrement, and minSize constraints.

5. Depth snapshots include sequence numbers enabling delta synchronization. Clients must validate sequence continuity to avoid missed updates or stale order book states.

Rate Limiting and Error Handling

1. KuCoin enforces strict rate limits: 100 requests per second for public endpoints and 20 per second for private endpoints on standard API keys.

2. Exceeding limits triggers HTTP 429 responses with Retry-After headers indicating mandatory backoff duration in milliseconds.

3. Common error codes include 400 (invalid parameter), 401 (authentication failure), 403 (insufficient permissions), and 404 (symbol not found).

4. All error responses contain standardized JSON bodies with code, message, and sometimes suggestion fields—e.g., {'code':'400100','msg':'Invalid symbol'}.

5. Idempotency keys are required for order placement to prevent duplicate submissions; they must be unique UUIDs sent in the KC-API-REQ-ID header.

Frequently Asked Questions

Q: Can I use the same API key across multiple bot instances?A: Yes, but concurrent requests exceeding rate limits will result in throttling. Shared keys also increase security risk if compromised.

Q: Why does my signed request return “Invalid signature” even with correct timestamp and secret?A: Most often due to incorrect string canonicalization—missing newline characters between components, improper UTF-8 encoding of the request body, or trailing whitespace in the prehash string.

Q: Do WebSocket connections support reconnection with state resynchronization?A: Yes, KuCoin provides sequence numbers in every message. Upon reconnect, clients should request a new snapshot and discard any messages with sequence numbers lower than the last processed one.

Q: Is margin or futures trading supported via the same REST API?A: No. Margin and futures operations require separate API bases: https://api.kucoin.com/api/v1/margin and https://futures.kucoin.com/api/v1/contracts/active, each with distinct authentication and endpoints.