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:

Read-Only

Spot Trading

Spot Margin Trading

Futures Trading

KuCoin Earn

Flexible Transfer

If the broker requires a customized default permission set—for example, Read-Only access only, OAuth withdrawal permission, or another combination of permissions—the broker should contact their Account Manager to arrange a dedicated permission group.

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 Fast API 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. Authorization Code Mode

KuCoin offers authorization code mode only. Access token and refresh token can be retrieved based on authorization codes. The broker saves keys and interacts with the KuCoin OAuth2.0 server.

5. Use of Token

5.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.

5.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.

5.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.

6. 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：

Response Type	Please use the autorization_code mode
Client_id	Unique identity of the broker
Redirect_url	Broker website Tips: please don’t encode the redirect URL.
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

After the user completes authorization, KuCoin redirects the user to the broker’s redirect_uri with the authorization result and permission information.

Example:

When withdrawal permission is not enabled: redirect_url?code=XXX&state=XXX&API_COMMON=true&API_SPOT=true&API_MARGIN=true&API_FUTURES=true&API_EARN=true&API_TRANSFER=true&API_WITHDRAW_OAUTH=false

When withdrawal permission is enabled:
redirect_url?code=XXX&state=XXX&API_COMMON=true&API_SPOT=true&API_MARGIN=true&API_FUTURES=true&API_EARN=true&API_TRANSFER=true&API_WITHDRAW_OAUTH=true&isAddressbookOnly=false

The authorization result includes the following permission fields:

{ 

  "code": "668*********c711", 
   
  "state": XXX
  "authGroupMap": {
    "API_COMMON": true,
    "API_SPOT": true,
    "API_MARGIN": true,
    "API_FUTURES": true,
    "API_EARN": true,
    "API_TRANSFER": true,
    "API_WITHDRAW_OAUTH": true
  },
  "isAddressbookOnly": false
}

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

If a broker requires withdrawal permission from users, the broker should either:

Guide users to select and authorize the withdrawal permission during the authorization process; or

Contact the Account Manager in advance to configure a default permission group.

When configuring the authGroupMap, please ensure that the permissions are mapped accordingly based on the permissions selected and granted by the user.

The user’s authorization details will then be shared with the broker through the OAuth login and permission-editing URL callback, specifically via the authGroupMap and isAddressbookOnly fields. When requesting the user’s API key later, please pass these fields exactly as they are returned in KuCoin’s response, without modifying their content.

Note:

If the user does not enable withdrawal permission, API_WITHDRAW_OAUTH will be returned as false.

When API_WITHDRAW_OAUTH=false, isAddressbookOnly will not be returned in the callback.

In this case, the broker must not pass isAddressbookOnly when requesting the user’s API key. Passing this field when it is not returned will result in an error.

If withdrawal permission is enabled, isAddressbookOnly will be returned and must also be passed exactly as received when creating the API key.

6.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:

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.

6.3 Refresh A Token

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

Method: POST

Params:

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
}

6.4 Oauth - Get User API Key

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}"

parameter: //The parameters for this step are the same as the permission group parameters selected by the user in section 7.2
{
"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
}

response:
{
"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

7. Withdraw Use Case

7.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.

7.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:

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.
memo	Optional	Address remark (memo/tag). Leave this field empty if no remark is required. When withdrawing to an external platform or wallet, please confirm with the receiving address whether a memo/tag is required. Failure to provide the correct memo/tag may result in the receiving platform being unable to credit your funds.
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:

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"
    }
}

8. 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

For the latest OAuth withdrawal service fee structure, please refer to: https://www.kucoin.com/announcement/en-oauth-withdrawal-service-fee

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

Broker Fast API Service

1. Introduction#

2. Preparation before Integration#

3. Fast API Service#

4. Authorization Code Mode#

5. Use of Token#

5.1 Differences between tokens#

5.2 How to use tokens#

5.3 Token validity#

6. OAuth Controller API Design#

6.1 OAuth Login Page and Permission Editing#

6.2 Request A Token#

6.3 Refresh A Token#

6.4 Oauth - Get User API Key#

7. Withdraw Use Case#

7.1. Security Setup and Broker page redirect#

7.2. Withdrawal Endpoint#

8. Fee Structure#