Broker Fast API Service

1. Introduction

KuCoin has launched the Fast API Service, enabling broker users to seamlessly connect to a broker’s website or application through KuCoin OAuth 2.0 login. With a one-click authorization flow, users can securely link their KuCoin accounts to third-party applications without the need to manually create or bind an API key (Version 3) or passphrase. No manual API key creation or passphrase setup is required.

Once authorized, an API key is automatically generated and linked to the broker platform with default permissions for:

Spot Trading

Futures Trading

KuCoin Earn Access

Supported Use Cases

Payouts to KuCoin Users: Generate deposit addresses for seamless fund transfers to KuCoin users. Suitable for airdrop aggregators and arbitrage solutions.

Pay with KuCoin: Enable users to pay with their KuCoin accounts across third-party apps and DeFi ecosystems. Ideal for payment apps, DeFi bridges, and Web3 gateways.

Trading Integration: Integrate KuCoin trading into your platform for efficient trade execution. Suitable for trading bots and portfolio trackers.

Accounting & Audit: Export trading and transaction data for accounting, auditing, and financial reporting.

2. Preparation before Integration

To utilize the KuCoin Fast API Service, Broker partners need to prepare the below three parts and submit from this form.

Broker’s full IP list for requesting KuCoin’s Fast API Service. This is the IP that the Broker server requests to our KuCoin fast api service server.

Broker’s full IP list for trading.

Redirect URL(s) after KuCoin's OAuth login.

Once the broker provides the above, KuCoin will send the broker's unique client_id

3. Fast API Service

Broker users can use KuCoin Oauth login to authorize brokers obtaining their api key. Authentication and authorization are mandatory for every permission creation action in FastAPI 2.0.
Users can now customize API permissions based on their actual needs during authorization, including:

Read-only permission

Spot Trading permission

Margin Trading permission

Futures Trading permission

Earn permission

Flexible transfers permission

Withdrawal permission

Unified account permission

This gives users greater transparency and control over account authorization while helping brokers support more diverse business scenarios.

4. OpenAPI Demo

4.1 OAuth Demo [Old Version]

URl ：https://www.kucoin.com/_oauth/resource/ucenter/outer/api-key/add
method ：POST
content-type ：application/json
header:
"Authorization":"bearer {token}"
parameter:
no parameter needed

{
	"success": true,
	"code": "200",
	"msg": "success",
	"retry": false,
	"data": {
    	"apiName": "",
    	"apiKey": "",
    	"secret": "",
    	"passphrase": "",
    	"brokerId": "",
    	"authGroup": API_COMMON,API_FUTURES,API_SPOT,API_EARN,API_TRANSFER,API_MARGIN,
    	"ipWhiteList": ""
	}
}

Errors：

Repeated apiName

The number of user’s apiKey reaches to the maximum level

4.2 Oauth New Demo [Suggested]

If you are a new broker partner of KuCoin, we recommend using our new demo environment directly, as it is our latest version and provides the most up-to-date features and infrastructure.
Please note that if you are operating broker services on a KuCoin local site, you will be required to use this version.

URl ：https://www.kucoin.com/_oauth/resource/cyber-truck-vault/v2/outer/api-key/add
method ：POST
content-type ：application/json
header:
"Authorization":"bearer {token}"

{
"authGroupMap": {
"API_COMMON": true,
"API_SPOT": true,
"API_MARGIN": true,
"API_FUTURES": true,
"API_EARN": true,
"API_TRANSFER": true,
"API_WITHDRAW_OAUTH": false
},
"isAddressbookOnly": false
}

{
"success": true,
"code": "200",
"msg": "success",
"retry": false,
"data": {
"apiName": "",
"apiKey": "",
"secret": "",
"passphrase": "",
"brokerId": "",
"authGroup": API_COMMON,API_FUTURES,API_SPOT,API_EARN,API_TRANSFER,API_MARGIN,
"ipWhiteList": ""
}
}

Errors：

Repeated apiName

The number of user’s apiKey reaches to the maximum level

5. Authorization Code Mode

KuCoin offers authorization code mode only. With authorization, the broker provides client_secret to get authorization code. access token and refresh token can be retrieved based on authorization codes. Broker saves keys and interacts with the KuCoin OAuth2.0 server.

6. Use of Token

6.1 Differences between tokens

After the broker calls the token exchange endpoint through authorization code, there will be two types of tokens.

access token : Used for the broker to call KuCoin OpenAPI endpoint.

refresh token : Used for obtaining a new access token when the previous one expires.

6.2 How to use tokens

After the broker completes the authorization and obtains the token, it will be able to call the KuCoin OpenAPI endpoint through the access token. When requesting, broker needs to carry the following information in the request header:

Header Parameters	Required	Descriptions
Authorization	Yes	Fill in the access token as bearer to this field.

6.3 Token validity

access token : Valid within 1 hour

refresh token : Valid within 3 days
If the access token expires, the endpoint will no longer be accessible. If the refresh token is still within the valid period, the broker needs to call the refresh token endpoint to obtain a new pair of access token and refresh token. The new access token can continue to be used. When a new access token is retrieved via refresh token, the old access token cannot be used regardless of whether it has expired or not.

7. OAuth Controller API Design

URI:
http://www.kucoin.com/oauth?response_type=code&client_id=XXXX&redirect_uri=XXX&scope=OAUTH_CREATE_API&state=123

Method: GET

Parmas：

Parmas	Descriptions
Response Type	Please use the authorization_code mode
Client_id	Unique identity of the broker
Redirect_url	Broker website
Scope	Scope of access_token
State	Brokers can determine what you need here. But this is a compulsory field. You can put your system’s user ID here

Response ：

    "success": true, 
    "code": "668*********c711", 
    "msg": "success.", 
    "retry": false, 
    "data": null
   "state": XXX

💡

Tips: please don’t encode the redirect URL.

Users can log in to their KuCoin account using their registered email address or phone number and grant the agreed permissions to authorize the broker to access the corresponding functionalities.

If a broker requires withdrawal permission from users, the broker should independently guide users to select and authorize the withdrawal permission during the authorization process.

7.2 Request A Token

URI: https://www.kucoin.com/_oauth/access-token?grant_type=authorization_code&code=xxxxxxxxxx&redirect_uri=https://www.xxxxxxxxxxxxx.com&client_id=xxxxxxxxx

Methond: GET

Params:

Params	is_required	Description
Grant_type	Compulsory	grant_type=authorization_code
Code	Compulsory
Redirect_url	Compulsory
Client_id	Compulsory	Unique identity of the broker

Response:

    "access_token":"",  	//access token received from user authorization
    "token_type":"bearer"     //token type, extension point to facilitate the addition of more secure tokens in the future
    "expires_in":3600,  	//token expiration time, in seconds
    "refresh_token":,   	//token used to obtain a new access token after the access token expires
    "scope": ["", ""]   	//scope of permissions for the access token
}

Tips: please don’t encode the redirect URL.

7.3 Refresh A Token

URI：https://www.kucoin.com/_oauth/refresh-token
Method: POST
Params:

Body Params	is_required	Description
Grant_type	Compulsory	authorization_code
Refresh_token	Compulsory	Token used to refresh the authentication
Scope	Compulsory

response：

    "access_token":"",  	//token used to access resources
    "token_type":"bearer",  //token type, an extension point to facilitate the addition of more secure tokens in the future, such as MAC (Message Authentication Code). Bearer indicates a token that does not contain any information
    "expires_in":3600,  	//token expiration time, in seconds
    "refresh_token":,   	//token used to obtain a new access token after the access token expires
    "scope": [""OAUTH_CREATE_API""]  //scope of permissions for the access token
}

8. Withdraw Use Case

8.1. Security Setup and Broker page redirect

Step 1: Security Verification Check
If the user’s account security level is insufficient (for example, if 2FA is not enabled), KuCoin will return a security setup link to the broker, allowing the user to complete the required verification steps. The API error response will return a message similar to the following:
"You need to bind more factors to continue this operation. Please visit the following link: https://xxx.kucoin.xxx/account/security/g2fa"

Step 2: Add Redirect Parameters (Optional)
When presenting the security setup link to users, brokers may append the following parameters to support automatic redirection after the security setup is completed:

client_id: Broker/Supplier ID

redirect_uri: The URL to redirect the user back to after completion (pay attention to the URL-encoded)

Demo link after URL:
construction:https://www.kucoin.com/account/security/g2fa?client_id=demo_client_id&redirect_uri=https%3a%2f%2fwww.kucoin.com

Step 3: User Completes Security Setup
Once the user clicks the link, they will be redirected to the KuCoin webpage to complete the required security verification setup. After the setup is completed, the user will be automatically redirected back to the broker’s designated page.

8.2. Withdrawal Endpoint

Please be aware that the withdrawal for OAuth Service is an independent withdrawal endpoint under the broker section.
URI：https://api.kucoin.com/api/v2/broker/withdrawal

Method: POST

Headers:

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.

Params:

Header	Required	Description
currency	Compulsory	currency
address	Compulsory	Withdrawal address
amount	Compulsory	Withdrawal amount. Must be a positive number and a multiple of the specified amount precision.
withdrawType	Compulsory	Withdrawal type, ADDRESS (withdrawal address), UID, MAIL (email), PHONE (mobile phone number). Note: If you withdraw by uid/mail/phone, there will be rate limits: 3 times/10 seconds, 50 times/24 hours (calculated on a rolling basis based on the first request time)
chain	Optional	The chainId of currency, For a currency with multiple chains, it is recommended to specify the chain parameter instead of using the default chain; you can query the chainId through the response of the GET /api/v3/currencies/{currency} interface.
isInner	Optional	Internal withdrawal or not. Default: False
remark	Optional	Remark
feeDeductType	Optional	Withdrawal fee deduction type. If you don't specify the feeDeductType parameter, when the balance in your main account is sufficient to support the withdrawal, the system will initially deduct the transaction fees from your main account. But if the balance in your main account is not sufficient to support the withdrawal, the system will deduct the fees from your withdrawal amount. For example: Suppose you are going to withdraw 1 BTC from the KuCoin platform (transaction fee: 0.0001BTC), if the balance in your main account is insufficient, the system will deduct the transaction fees from your withdrawal amount. In this case, you will be receiving 0.9999BTC.

response fields:

Header	Required	Description
withdrawalId	Optional	Withdrawal ID, a unique ID for a withdrawal
transactionId	Optional	transaction id, a unique ID for a validation transaction
allFactors	Optional	All 2FA factors need to be verified during the validation transaction
sentFactors	Optional	2FA factors sent to user side, only include those factors that need to be sent

Get 2FA factors response:

    "code": "200000",
    "data": {
        "transactionId": "sample transactionId",
        "allFactors": [
            ["GAV", "EMV"]
        ],
        "sentFactors": [
            ["EMV"]
        ]
    }
}
withdraw success response：
{
    "code": "200000",
    "data": {
        "withdrawalId": "sample withdrawalId"
    }
}

Withdraw success response:

    "code": "200000",
    "data": {
        "withdrawalId": "sample withdrawalId"
    }
}

9. Fee Structure

Trading & Withdrawal Fees: Standard trading and withdrawal fees apply. Please refer to the fee schedule here: KuCoin VIP Fee Schedule

OAuth Service Fee: For deposit and withdrawal transactions initiated via the Fast API OAuth Service, KuCoin will charge an OAuth service fee based on transaction volume.

Deposit	Withdrawal
0 USDT per transaction	10% of withdrawal amount，Minimum fee: equivalent of 1 USDT per withdrawal，Maximum fee: equivalent of 30 USDT per withdrawal

Thank you for your time and attention.
The KuCoin Broker Team
Telegram: @KuCoin_Broker

1. Introduction#

2. Preparation before Integration#

3. Fast API Service#

4. OpenAPI Demo#

4.1 OAuth Demo [Old Version]#

The OAuth Demo is an older version and is still available for our existing broker partners. However, we recommend switching to the new version if you are comfortable, as it provides the latest features and improvements.#

4.2 Oauth New Demo [Suggested]#

5. Authorization Code Mode#

6. Use of Token#

6.1 Differences between tokens#

6.2 How to use tokens#

6.3 Token validity#

7. OAuth Controller API Design#

7.1 OAuth Login Page and Permission Editing#

7.2 Request A Token#

7.3 Refresh A Token#

8. Withdraw Use Case#

8.1. Security Setup and Broker page redirect#

8.2. Withdrawal Endpoint#

9. Fee Structure#