Authentication

Generating an API Key

Before being able to sign any requests, you must create an API key via the KuCoin website. Upon creating a key you need to write down 3 pieces of information:

Key

Secret

Passphrase

The Key and Secret are generated and provided by KuCoin and the Passphrase refers to the one you used to create the KuCoin API. Please note that these three pieces of information can not be recovered once lost. If you lost this information, please create a new API key.

API KEY PERMISSIONS

You can manage the API permission on KuCoin’s official website. Please refer to the documentation below to see what API key permissions are required for a specific route.

Creating a Request

All private REST requests must include the required headers listed below. You may also include optional headers when applicable.

Header	Required	Description
KC-API-KEY	Yes	Your API key, provided as a string.
KC-API-SIGN	Yes	The Base64-encoded signature generated for the request.
KC-API-TIMESTAMP	Yes	The timestamp of the request in milliseconds.
KC-API-PASSPHRASE	Yes	The passphrase specified when the API key was created.
KC-API-KEY-VERSION	Yes	The API key version. This value can be checked on the API Management page.
Content-Type	Yes	All requests and responses use the `application/json` content type.
X-SITE-TYPE	No	Used to specify the site/region for public APIs. If not provided, the default value is `global`. For Australia site users, set this value to `australia` to ensure the returned data corresponds to the Australia site. For WebSocket connections, this header is also required during the token acquisition step when site differentiation is needed.

Signing a Message

For the header of KC-API-SIGN:

Use API-Secret to encrypt the prehash string {timestamp+method+endpoint+body} with sha256 HMAC. The request body is a JSON string and need to be the same with the parameters passed by the API.

Encode contents by base64 before you pass the request.

For the KC-API-PASSPHRASE of the header:

Encrypt passphrase with HMAC-sha256 via API-Secret.

Encode contents by base64 before you pass the request.

Note:

The encrypted timestamp shall be consistent with the KC-API-TIMESTAMP field in the request header.

The body to be encrypted shall be consistent with the content of the Request Body.

The Method should be UPPER CASE.

For GET, DELETE request, all query parameters need to be included in the request url. e.g. /api/v1/deposit-addresses?currency=XBT. The body is "" if there is no request body (typically for GET requests).

For the POST request, all query parameters need to be included in the request body with JSON. (e.g. {"currency":"BTC"}). Do not include extra spaces in JSON strings.

When generating signature, the URL must use the content that has not been URL-encoded to participate in the signature.
For example: When the url is /api/v1/sub/api-key?apiKey=67b3&subName=test&passphrase=abc%21%40%2311
, the url content participating in the signature should be the original information /api/v1/sub/api-key?apiKey=67b3&subName=test&passphrase=abc!@#11

Code Examples

Python

PHP

Gateway Timestamp

Gateway Timestamp is a pair of timestamps generated by the Gateway to mark the inbound and outbound moments of the same request at the Gateway boundary:

Boundary	Meaning	WebSocket Response (Body)	REST Response (Header)
Inbound	The request arrives at the Gateway	`inTime`	`x-in-time`
Outbound	The response is sent from the Gateway	`outTime`	`x-out-time`

Notes

The Gateway-side processing duration can be approximated by outTime - inTime (WebSocket) or x-out-time - x-in-time (REST). The unit depends on the enabled precision.

Precision Control

Use the following parameters to control Gateway Timestamp precision.

Protocol	Control Parameter	Parameter Location	Affected Response Location	Affected Fields	Default Unit
REST	`kc-enable-ns`	Request Header	Response Header	`x-in-time`, `x-out-time`	Microseconds (µs)
WebSocket	`enable_ns`	WSS Query Parameter	Response Body	`inTime`, `outTime`	Milliseconds (ms)

Remarks

REST: x-in-time and x-out-time are returned in the Response Header and may be included in responses for any REST API. The 5- prefix only indicates that the timestamp pair is generated by the Gateway. Currently, only the Gateway-side inbound and outbound timestamps are provided.

WebSocket: inTime and outTime are in the Response Body and may be returned by request-response Pro WebSocket APIs such as Add/Cancel Order.

For Colo customers using UTA accounts, inTime and outTime are returned in nanoseconds by default, so enable_ns=true is not required.

Enable Nanoseconds

RESTful API

Set kc-enable-ns: true in the request header to return x-in-time and x-out-time in nanoseconds.

Request Example:

Response Example (Response Header):

WebSocket Add/Cancel Order API

Add enable_ns=true to the WebSocket connection URL to return inTime and outTime in nanoseconds.

Request Example:

wss://wsapi.kucoin.com/v1/private?apikey=689***2b6&timestamp=1768878266952&sign=H/G***%3D&passphrase=aLs***3D&enable_ns=true

Response Example (Response Body):

{
    "code": "200000",
    "data": {
        "clientOid": "32dd404b1d724df59ee6f2bd8e8909f60522e89f",
        "orderId": "403363205159706624",
        "tradeType": "FUTURES",
        "ts": 1768982484257000000
    },
    "id": "1b7ac024f4ee42e48d41104c10a21732",
    "inTime": 1768982484219053000,       // Inbound Timestamp
    "op": "uta.order",
    "outTime": 1768982484257824000,      // Outbound Timestamp
    "userRateLimit": {
        "limit": 2000,
        "remaining": 1999,
        "reset": 30000
    }
}

Authentication

Authentication#

Generating an API Key#

API KEY PERMISSIONS#

Creating a Request#

Signing a Message#

Code Examples#

Gateway Timestamp#

Precision Control#

Enable Nanoseconds#

RESTful API#

WebSocket Add/Cancel Order API#

Authentication

Generating an API Key

API KEY PERMISSIONS

Creating a Request

Signing a Message

Code Examples

Gateway Timestamp

Precision Control

Enable Nanoseconds

RESTful API

WebSocket Add/Cancel Order API