Broker Fast API Service

1. Introduction

KuCoin is going to launch the Fast API Service which allows broker users to connect to the broker’s website/app via KuCoin OAuth2.0 login, an one-click authorization linked to third-party applications. The significant improvement with Fast API service is to generate enhanced security of the trading and simplify the way to connect KuCoin and Broker.

No extra passphrase or API key (version3) is required to be manually binded with the broker's bot. The OAuth connection will automatically create an API key and automatically connect to the broker. The key has default permissions with spot trading, futures trading, as well as getting access to KuCoin Earn.

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

Once the broker provides the above three, 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 trading and reading general trading-related information. No withdrawal authorization allowed.

4. OpenAPI Demo

URL ：https://www.kucoin.com/_oauth/resource/ucenter/outer/api-key/add

method：POST
Content-Type：application/x-www-form-urlencoded
header: "Authorization":"bearer {token}"
Body Params: no parameter needed

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

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

Params
Response Type	Please use the autorization_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
}

Please don’t encode the redirect URL.

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

Method: GET

Params	is_required	Description
Grant_type	Yes	grant_type=authorization_code
Code	Yes
Redirect_url	Yes
Client_id	Yes	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
}

Please don’t encode the redirect URL.

7.3 Refresh A Token

URI: https://www.kucoin.com/_oauth/refresh-token
Method: POST
Content-Type：application/x-www-form-urlencoded

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

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
}

7.4 Verify A Token (WIP)

URI：https://www.kucoin.com/_oauth/validate-access-token
Method: POST
Content-Type：application/x-www-form-urlencoded

Params:

Field	Type	Description
access_token	Yes	Access token

Response:

Field	Type	Description
access_token	String	Access token
is_valid	boolean	true/false

Broker Fast API Service

1. Introduction#

2. Preparation before Integration#

3. Fast API Service#

4. OpenAPI Demo#

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#

7.2 Request A Token#

7.3 Refresh A Token#

7.4 Verify A Token (WIP)#

1. Introduction

2. Preparation before Integration

3. Fast API Service

4. OpenAPI Demo

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

7.2 Request A Token

7.3 Refresh A Token

7.4 Verify A Token (WIP)