KuCoin Getting Started: Account, Keys, and First Request (2026)

Getting started overview

This guide provides a structured approach to initiating development with the KuCoin API. It focuses on the fundamental steps required to go from account registration to executing a successful API call. The process involves creating a KuCoin account, securing it, generating API keys, and finally, sending a test request to confirm connectivity and authentication.

KuCoin, established in 2017, offers various trading products including spot, futures, and margin trading, alongside passive income opportunities through staking and lending KuCoin's homepage. The API provides programmatic access to these features, enabling developers to build custom trading bots, integrate market data, or manage accounts.

To ensure a smooth integration, it is recommended to follow the steps sequentially. This includes understanding the requirements for account verification (KYC/AML), implementing robust security measures for API keys, and correctly formatting API requests according to KuCoin's specifications KuCoin API documentation.

The following table summarizes the key steps:

Create an account and get keys

Before interacting with the KuCoin API, you must register a KuCoin account and generate the necessary API credentials. KuCoin requires users to complete a basic registration process, which includes providing an email address or phone number and setting a password KuCoin registration page.

Account Registration and Security

1. Register an Account: Navigate to the KuCoin sign-up page and follow the instructions to create a new account.
2. Enable Two-Factor Authentication (2FA): After registration, immediately enable 2FA using Google Authenticator. This adds a critical layer of security to your account. Access this through your account's security settings.
3. Set a Trading Password: KuCoin requires a separate trading password for sensitive operations, including API key creation and withdrawals. Set this password in your security settings.
4. Complete KYC Verification (Optional but Recommended): While basic API access might not strictly require KYC (Know Your Customer) verification, completing it can increase trading limits and withdrawal caps. Access the KYC verification section in your account profile and follow the steps for identity verification KuCoin KYC page.

Generating API Keys

API keys are your primary method of authenticating with the KuCoin API. Each API key set consists of an API Key, an API Secret, and an API Passphrase.

1. Access API Management: Log in to your KuCoin account. Navigate to your profile icon, then select API Management from the dropdown menu.
2. Create API: Click the Create API button.
3. Configure API Permissions:
   • API Name: Provide a descriptive name for your API key (e.g., "My Trading Bot").
   • API Passphrase: Create a strong passphrase. This is a crucial security component separate from your account login password.
   • Permissions: Carefully select the permissions required for your application. For a first test, "General" (for market data and account info) and "Trade" (for placing orders) are common. Avoid granting "Withdrawal" permissions unless absolutely necessary for your application.
   • IP Whitelist (Highly Recommended): Specify the exact IP addresses from which your API calls will originate. This significantly enhances security by preventing unauthorized access even if your API key is compromised. If your application's IP address is dynamic, consider using a static IP or a VPN service with a dedicated IP. Leaving this blank allows access from any IP, which is a security risk.
4. Confirm Creation: You will be prompted to enter your trading password and 2FA code to confirm the API key creation.
5. Record Credentials: Immediately record your API Key, API Secret, and API Passphrase. The API Secret will only be displayed once during creation. Store these credentials securely, ideally in environment variables or a secure vault, never directly in your codebase.

Your first request

To verify your setup, you will make a simple authenticated API call. A common first request is to retrieve your account's sub-accounts list, which requires authentication but no specific trading permissions beyond basic account access.

API Endpoint and Authentication Details

• Base URL: https://api.kucoin.com
• Endpoint: /api/v1/sub/user (Get Sub-user list) KuCoin Sub-user list documentation
• Method: GET

KuCoin's API uses HMAC SHA256 for signing requests. Each authenticated request requires the following headers:

• KC-API-KEY: Your generated API Key.
• KC-API-SIGN: The signature of your request.
• KC-API-TIMESTAMP: A Unix epoch timestamp in milliseconds.
• KC-API-PASSPHRASE: The passphrase you set for the API key, encrypted with HMAC SHA256 using your API Secret.
• KC-API-KEY-VERSION: (Optional) Set to 2 for the latest API version.

Constructing the Signature

The signature (KC-API-SIGN) is generated by concatenating the timestamp, HTTP method, request path (including query parameters), and request body (if any), then hashing this string with your API Secret using HMAC SHA256. For GET requests without a body, the body component is an empty string.

The KC-API-PASSPHRASE header requires the passphrase to be encrypted. The encryption process involves concatenating the API Passphrase with the timestamp, then hashing this with the API Secret using HMAC SHA256. This is different from the request signature.

Example using cURL (Linux/macOS)

This example demonstrates how to make an authenticated GET request using cURL. You'll need a scripting language (e.g., Python, Node.js) to generate the signature and passphrase headers dynamically.

Python Example for Signature Generation:

import hmac
import hashlib
import time
import base64

API_KEY = "YOUR_API_KEY"
API_SECRET = "YOUR_API_SECRET"
API_PASSPHRASE = "YOUR_API_PASSPHRASE"

# For KC-API-TIMESTAMP header
timestamp = str(int(time.time() * 1000))

# For KC-API-PASSPHRASE header
# The passphrase itself is encrypted with the API Secret
passphrase_bytes = API_PASSPHRASE.encode('utf-8')
secret_bytes_passphrase = API_SECRET.encode('utf-8')

pre_hash_passphrase_string = timestamp + API_PASSPHRASE
passphrase_signature = hmac.new(secret_bytes_passphrase, pre_hash_passphrase_string.encode('utf-8'), hashlib.sha256).hexdigest()


# For KC-API-SIGN header
method = "GET"
endpoint = "/api/v1/sub/user"
body = "" # No body for GET requests

pre_hash_string = timestamp + method + endpoint + body

secret_bytes = API_SECRET.encode('utf-8')
signature = hmac.new(secret_bytes, pre_hash_string.encode('utf-8'), hashlib.sha256).hexdigest()

print(f"Timestamp: {timestamp}")
print(f"Passphrase Signature: {passphrase_signature}")
print(f"Request Signature: {signature}")

Once you have the timestamp, passphrase_signature (for KC-API-PASSPHRASE), and signature (for KC-API-SIGN), you can construct your cURL command:

curl -X GET \
  'https://api.kucoin.com/api/v1/sub/user' \
  -H 'KC-API-KEY: YOUR_API_KEY' \
  -H 'KC-API-SIGN: GENERATED_REQUEST_SIGNATURE' \
  -H 'KC-API-TIMESTAMP: GENERATED_TIMESTAMP' \
  -H 'KC-API-PASSPHRASE: GENERATED_PASSPHRASE_SIGNATURE' \
  -H 'KC-API-KEY-VERSION: 2' \
  -H 'Content-Type: application/json'

Replace YOUR_API_KEY, GENERATED_REQUEST_SIGNATURE, GENERATED_TIMESTAMP, and GENERATED_PASSPHRASE_SIGNATURE with the values generated by your script.

A successful response will return a JSON object containing information about your sub-users, similar to:

{
  "code": "200000",
  "data": [
    {
      "userId": "...",
      "subName": "...",
      "type": "...",
      "status": "..."
    }
  ]
}

An HTTP status code of 200 OK and a code of 200000 in the response body indicates success.

Common next steps

After successfully making your first API call, you can proceed with more advanced integrations:

1. Explore Market Data: Utilize public endpoints to fetch real-time market data, such as order books, candlesticks, and trade history KuCoin Market Data API. This is crucial for any trading strategy.
2. Place Orders: Implement endpoints for placing spot, margin, or futures orders. Pay close attention to order types (limit, market, stop-limit) and their respective parameters KuCoin Trading API.
3. Manage Accounts: Develop functionality to query account balances, order history, and trade records.
4. Integrate with SDKs: For faster development, consider using one of KuCoin's official or community-supported SDKs (Python, Java, Node.js, Go, C#) KuCoin SDK documentation. SDKs abstract away the complexity of signature generation and HTTP requests.
5. Implement Webhooks: For real-time notifications about account activity or order changes, investigate KuCoin's webhook capabilities, if available, or consider polling relevant endpoints at appropriate intervals. For general webhook best practices, consult resources like Twilio's webhook security guide.
6. Error Handling and Rate Limiting: Design your application to gracefully handle API errors and respect KuCoin's rate limits to avoid being temporarily blocked. Consult the KuCoin Rate Limit documentation for details.

Troubleshooting the first call

Encountering issues during your initial API call is common. Here's a checklist for troubleshooting:

• Incorrect API Key/Secret/Passphrase: Double-check that your API Key, API Secret, and API Passphrase are copied correctly. Remember the API Secret is only shown once upon creation.
• Signature Mismatch: The most frequent issue. Ensure your signature generation logic precisely matches KuCoin's requirements. Verify the order of concatenation (timestamp + method + path + body), the correct HTTP method, and that the request path includes any query parameters. The API Passphrase signature also needs careful construction.
• Timestamp Issues: The KC-API-TIMESTAMP must be a Unix epoch timestamp in milliseconds and should be reasonably synchronized with KuCoin's server time. Significant time differences can lead to authentication failures.
• IP Whitelist Restrictions: If you enabled an IP whitelist, ensure the IP address from which your request originates is included in your KuCoin API key settings. If your IP is dynamic, this can be a frequent cause of issues.
• Missing or Incorrect Headers: Verify that all required headers (KC-API-KEY, KC-API-SIGN, KC-API-TIMESTAMP, KC-API-PASSPHRASE) are present and correctly formatted.
• Permissions: Ensure the API key has the necessary permissions for the endpoint you are trying to access. For example, a key without "Trade" permission cannot place orders.
• Network Issues: Check your internet connection and ensure no firewalls are blocking outgoing requests to api.kucoin.com.
• Server-Side Errors: KuCoin's API documentation lists common error codes KuCoin Error Codes. Review the error message returned in the API response to diagnose the problem. A 401 Unauthorized typically points to an authentication issue (key, secret, signature, timestamp, passphrase).
• Using the Correct Base URL: Ensure you are using the correct base URL for the KuCoin API (https://api.kucoin.com).