KuCoin API Python Tutorial (2024)

In this KuCoin API Python tutorial, you will see how to use the Python client for the KuCoin API to retrieve cryptocurrency exchange data from KuCoin. 

The article explains how to create a KuCoin account and get market data, execute traditional operations, and perform various other tasks using the Python KuCoin API client.

What Is KuCoin?

KuCoin is a cryptocurrency exchange platform with more than 10 million users and a presence in more than 200 countries. The platform offers safe and convenient services for buying, selling, and digital trading assets. KuCoin offers margin, futures, and peer-to-peer trading options, and the platform also provides automatic trading services in the form of trading bots. 

Is KuCoin Free?

Signing up with KuCoin is free. Though KuCoin charges trading fees, it has one of the most competitive and transparent fee structures among significant crypto exchanges. 

Based on their trading volume, or 30-day KCS holdings, KuCoin categorizes future trades and spots into levels or tiers ranging from 0 to 12. The fees range from 0.0125% to 0.1% based on the trading level. 

To know more about KuCoin fees, sign-up or log in to your KuCoin account, scroll down to the end of the main page, and click the link for Fees under Services. Here is a direct link to view KuCoin fees. 

Where is KuCoin based?

KuCoin was launched in 2017. Its headquarters are based in Victoria, Seychelles. 

What can I Trade on KuCoin?

KuCoin supports all major cryptocurrencies, e.g., BitCoin (BT), Ethereum (ETH), Tether (USDT), Binance (BNB), Cardano (ADA), etc. Overall, you can trade over 600 cryptocurrencies on KuCoin.  

You can use fiat (USD, GBP, Euros, UAE) to buy cryptocurrencies using their fast buy service, P2P fiat trade, or a credit or debit card.

P2P fiat trade, Fast Buy Service, or with a credit or debit card

Why should I use KuCoin

Following are some reasons you should use KuCoin:

• Low trading fees compared to other major crypto exchanges.
• More than 600 cryptocurrencies are available for trade. 
• You can earn interest by lending cryptocurrency.
• KuCoin offers algorithmic trading services, e.g., bots grid trading, Dollar-cost averaging trading.
• Free Tether (United States Dollar Tether) coins on sign-up.
• Mobile and desktop apps with abundant features and advanced trading tools.
• You can use fiat, credit, and debit cards to buy cryptocurrency.
• It has multiple security layers and supports two-factor authentication like  Google authenticator. The internal risk department ensures the safety of user funds.

Why shouldn’t I use KuCoin?

• KuCoin is not licensed in the USA, severely limiting its usage. Though US users can sign-up with KuCoin, access to many advanced KuCoin features is limited.

• Low trading volume compared to other major crypto exchanges.
• Liquidity issues with smaller coins.
• API delays and bad server latency during high-traffic periods.
• KuCoin user reviews are abysmal, with an average rating of 1.8 stars on Trustpilot. Most users report issues with customer service, withdrawals, and market manipulation. 
• Not beginner-friendly.

Getting Started with Python KuCoin API 

Registration with KuCoin

To register with KuCoin, you have to sign-up for a KuCoin account. 

Go to the KuCoin sign-up Page. You will see the following sign-up form.

You can log in with both your cell number and email address. Select a strong password and then tick the checkbox to agree to terms of use. Hit the “sign-up” button to complete the sign-up process.

Once you sign-up, KuCoin sends you a 6-digit verification code in your email, which you will need to enter to activate your KuCoin account.

Generate your KuCoin API Key

You need an API Key to make interface calls to Python Kucoin Client API. 

To generate your API Key, log in to your KuCoin account and click the circle at the top right corner of the page. Select the “API Management” option from the list. 

You need to complete SMS or Google verification and set up your Trading password before you can generate your API key. Click the green “Edit” links to complete these steps, as shown in the following screenshot. 

After that, you will see the following options. Click the “Create API” button. 

You have to give a name to your API and create an API Passphrase. The API key will be generated by default to perform general KuCoin operations. Enable the “Trade” checkbox if you want to conduct trade operations. 

You can also limit the API calls from a specific IP address.

Click the “Next” button, and enter your Trading Password, the code sent to your email and the Google 2FA code.

KuCoin will send an email containing the link to activate your API. Click the link. You should see this screen once your API key is activated. 

Install KuCoin Python API Client

Execute the following pip command on your command terminal to install the Python KuCoin client API.

pip install python-kucoin

Configuring Client Settings

The KuCoin Python Rest API consists of the following main modules:

1. Client: contains generic API calls.
2. User: includes user account-related API calls.
3. Market: API calls to fetch market data, e.g., ticker, symbols, etc.
4. Margin: contains API calls related to margin trading.

This section will show how to configure the client class from the kucoin.client module to execute generic API calls. 

You will see how to use the remaining modules in the upcoming sections. 

To configure API client settings, import the client class from the Kucoin.client module. 

from kucoin.client import Client

You must pass the API Key, the API Secret, and the API Passphrase to the client class constructor. 

I do not recommend storing these values directly inside code variables for security reasons. Instead, I recommend that you keep these values in an encrypted file or an environment variable and fetch them from your code. 

In the following source code, the os.environ class from the Python os module fetches these values and passes them to the client class constructor. 

from kucoin.client import Client
import os
api_key = os.environ['KC-Key']
api_secret = os.environ['KC-Secret']
api_passphrase = os.environ['KC-Passphrase']
client = Client(api_key, api_secret, api_passphrase)

Simple Example Fetching Data using Python KuCoin API 

You can use the Python KuCoin Rest API or WebSockets to execute API calls. 

Furthermore, you can use the kucoin-python library to call the KuCoin Rest API or the generic Python request method.   

KuCoin API kucoin-python Library Example

Let’s see a simple example using the client class object from the kucoin.client module of kucoin-python to get all the available currencies from KuCoin.

# get currencies
listcurrencies = client.get_currencies()
print(currencies[:3])

Output:

Similarly, you can use the get_markets() method from the client class to get market lists. 

# get markets
listmarkets = client.get_markets()
print(markets)

Output:

['USDS', 'BTC', 'KCS', 'ALTS', 'NFT ETF', 'FIAT', 'DeFi', 'NFT', 'Metaverse', 'Polkadot', 'ETF']

You can also use the MarketData class from the market module to get market-related data. 

For instance, the following source code shows how you can get currency information using the get_currencies() method. 

from kucoin.market import market
market = market.MarketData(url='https://api.kucoin.com')
currencies = market.get_currencies()

Python KuCoin API Request Methods Example

The python-kucoin library can be a bit slow, and you may get a timeout exception while retrieving a large amount of information. 

Suppose speed and optimization are a concern. You call the KuCoin Rest API functions using the default Python requests module.

For example, the following source code demonstrates the Python requests module’s get () method to fetch currency information. 

You need to pass the string containing the base URL along with the API call as a parameter to the get() method. 

import requestsimport json
url = 'https://api.kucoin.com'
currencies = requests.get(url + '/api/v1/currencies')
currencies = currencies.json()
print(currencies['data'][:3])

Output:

For more information, please reference the KuCoin Rest API documentation.

Python KuCoin API Websocket Example

You can implement WebSockets to call KuCoin API functions. You can use the KuCoinSocket manager class from the Kucoin.asyncio module. The module implicitly allows you to make asynchronous calls to the KuCoin Rest API.

The following source code demonstrates WebSockets to fetch information about the “ETH=USDT” ticker. 

import asyncio
from kucoin.client import Clientfrom kucoin.asyncio import KucoinSocketManager
api_key = '<api_key>'api_secret = '<api_secret>'api_passphrase = '<api_passphrase>'

async def get_kucoin_data():    global loop
    # callback function that receives messages from the socket    async def handle_evt(msg):        if msg['topic'] == '/market/ticker:ETH-USDT':            print(f'got ETH-USDT tick:{msg["data"]}')
    client = Client(api_key, api_secret, api_passphrase)
    ksm = await KucoinSocketManager.create(loop, client, handle_evt)
    await ksm.subscribe('/market/ticker:ETH-USDT')
    while True:        print("sleeping to keep loop open")        await asyncio.sleep(20, loop=loop)

await(get_kucoin_data())

Output:

Account Management

The user sub-module from the Kucoin.user module contains account management functions. 

How to Create an Account

The create_account() method from the UserData class of the user module creates a new account. Behind the scenes, this method makes the /api/v1/accounts HTTP request to the KuCoin APl. 

The create_account() method uses a private endpoint of the KuCoin API. Therefore, you must authenticate the call by passing the API key, API secret, and API passphrase to the UserData class constructor.  

The create_account() method accepts account type (main, trade, and margin) and currency type as parameters. 

The following source code shows how to create a trade account with bitcoin (BTC) currency using the create_account() method. 

from kucoin.user import user
import os
import pandas as pd
api_key = os.environ['KC-Key']
api_secret = os.environ['KC-Secret']
api_passphrase = os.environ['KC-Passphrase']
user = user.UserData(key = api_key, secret = api_secret, passphrase = api_passphrase)
account = user.create_account('trade', 'BTC')

The create_account() method returns the id of the newly created account. 

You will receive an authentication response exception with the error code 400001 if the API key, API secret, or passphrase is missing in your request. 

For more information, please reference the KuCoin Error Codes List.

You can get information such as the account balance of any account via the get_account() method, as shown in the following source code. 

account = user.get_account('62ffff3685037e000158650d')
print(account)

Output:

{'currency': 'BTC', 'balance': '0', 'available': '0', 'holds': '0'}

How to List All Accounts

You can list all of your accounts using the get_account_list() method of the UserData class.

The get_account_list() method returns a list of dictionaries where each item contains information about one account (id, currency, type, balance, holds).  

The following Python program fetches information about all accounts using the get_account_list(). 

To get a better view, the source code below converts the list of dictionaries to a Pandas dataframe. 

from kucoin.user import user
import osimport pandas as pd
api_key = os.environ['KC-Key']
api_secret = os.environ['KC-Secret']
api_passphrase = os.environ['KC-Passphrase']
user = user.UserData(key = api_key, secret = api_secret, passphrase = api_passphrase)
all_accounts = user.get_account_list()
all_accounts = pd.DataFrame.from_dict(all_accounts)
all_accounts.head()

Output:

Get Single Subaccount Info

KuCoin allows you to create up to 100 subaccounts under a single account. You can get information about any specific subaccount using the get_sub_account() method.

The method returns a Python dictionary containing the subaccount name and the details of all the different accounts, e.g., main accounts, trade accounts, and margin accounts. 

from kucoin.user import user
import os
import pandas as pd
api_key = os.environ['KC-Key']
api_secret = os.environ['KC-Secret']
api_passphrase = os.environ['KC-Passphrase']
user = user.UserData(key = api_key, secret = api_secret, passphrase = api_passphrase)
sub_account = user.get_sub_account('63001857c4862600015c2ade')
sub_account.keys()

Output:

dict_keys(['subUserId', 'subName', 'mainAccounts', 'tradeAccounts', 'marginAccounts'])

The following source code shows how you can get detail of your main account using the ‘mainAccounts’ key of the dictionary returned by the get_sub_account() method. 

sub_account['mainAccounts'][0].keys()

Output:

dict_keys(['currency', 'balance', 'available', 'holds', 'baseCurrency', 'baseCurrencyPrice', 'baseAmount', 'tag'])

Get Multiple Subaccounts Info

You can also retrieve information about multiple subaccounts using the get_sub_accounts() method. Notice the “s” at the end of the method name, which distinguishes it from the get_sub_account() method. 

In the following source code, the get_sub_accounts() method returns a list of dictionaries converted to a Pandas dataframe. 

from kucoin.user import user
import os
import pandas as pd
api_key = os.environ['KC-Key']
api_secret = os.environ['KC-Secret']
api_passphrase = os.environ['KC-Passphrase']
user = user.UserData(key = api_key, secret = api_secret, passphrase = api_passphrase)
sub_accounts = user.get_sub_accounts()
sub_accounts = pd.DataFrame.from_dict(sub_accounts)
sub_accounts.head()

Output:

Getting Market Data

The market submodule from the kucoin.market module contains functions to retrieve market-related information, e.g., symbols, tickers, order books, etc. 

How to Get Symbols and Tickers

To get symbols and tickers from KuCoin, you can use the public endpoints of the KuCoin API. 

You don’t have to pass your API key, API secret, or passphrase with public endpoints. 

You only need to pass the base URL of the KuCoin API to the MarketData class of the market module. 

Get Symbols

The get_symbol_list() method from the MarketData class returns a list of Python dictionaries containing information about all the currency symbols from KuCoin.  

Behind the scene, the get_symbol_list() method uses the /api/v1/symbols HTTP request to the KuCoin Rest API. 

For better viewing, the following source code converts the list of dictionaries containing symbol information to a Pandas dataframe. 

from kucoin.market import market
import os
import pandas as pd

market = market.MarketData(url='https://api.kucoin.com')
symbols = market.get_symbol_list()
symbols = pd.DataFrame.from_dict(symbols)
symbols.head()

Output:

Get Tickers

Similarly, you can get a list of all tickers using the get_all_tickers() method. The method returns a dictionary containing time and the information about ticker values at that specific time.  

tickers = market.get_all_tickers()
print('Ticker Keys:',tickers.keys())
print('Ticker Time:',tickers['time'])

Output:

Ticker Keys: dict_keys(['time', 'ticker'])Ticker Time: 1660955440049

Ticker Keys: dict_keys(['time', 'ticker'])Ticker Time: 1660955440049

The time value returned by the get_all_tickers() method can be converted into YYYY-MM-DD format using the fromtimestamp method of the datetime module, as shown below:

import datetime
ticker_time = datetime.datetime.fromtimestamp(tickers['time'] / 1e3)
print(ticker_time)

Output:

2022-08-20 02:30:40.049000

The following source code shows the ticker information for various tickers in the form of a Pandas dataframe. 

tickers_values = pd.DataFrame.from_dict(tickers['ticker'])
tickers_values.head()

Output:

You can also retrieve information about a single ticker using the get_ticker() method. You need to pass the ticker symbol to the method. 

The following source code retrieves ticker information for “ETH_USDT” .

ticker = market.get_ticker("ETH-USDT")
print(ticker)

Output:

{'time': 1661001442098, 'sequence': '1633563085062', 'price': '1627.12', 'size': '0.0005875', 'bestBid': '1627.47', 'bestBidSize': '0.6953936', 'bestAsk': '1627.48', 'bestAskSize': '18.9125841'}

How to Get the Order Book

You can retrieve the order book for a particular ticker using the get_aggregated_orderv3() method.

The method returns a dictionary containing time, sequence number, bids, and askings for the ticker.

from kucoin.market import market
import os
import pandas as pd
api_key = os.environ['KC-Key']
api_secret = os.environ['KC-Secret']
api_passphrase = os.environ['KC-Passphrase']
market = market.MarketData(key = api_key, secret = api_secret, passphrase = api_passphrase )
order_book = market.get_aggregated_orderv3('BTC-USDT')
order_book.keys()

Output:

dict_keys(['time', 'sequence', 'bids', 'asks'])

The bids and askings consist of a list of lists containing the price and size for bids and askings.

The following source code prints the price and size of the first five bids retrieved in the previous script. 

order_book['bids'][:5]

Output:

[['21055.9', '1.11646882'], ['21054.8', '0.09403'], ['21054.2', '0.51051'], ['21053.8', '0.00001414'], ['21053.5', '0.06937906']]

How to Get Historical Data

You can get historical data for a particular ticker using the get_trade_histories() method. You need to pass the ticker symbol to the method. 

The method returns past 100 sequences containing the sequence id, time, price, size, and side for the ticker. 

Historical data, currencies, and fiat prices can be retrieved using KuCoin API public endpoints. To access these endpoints, you do not need to pass the API key, API secret, and passphrase to the MarketData class. 

The following source code converts the ticker history returned by the get_trade_histories() method to a Pandas dataframe. 

from kucoin.market import market
import os
import pandas as pd
market = market.MarketData(url='https://api.kucoin.com')
trade_history = market.get_trade_histories('BTC-USDT')
print(len(trade_history))
trade_history = pd.DataFrame.from_dict(trade_history)
trade_history.head()

Output:

How to Get Currencies

You have already seen how to get currencies from KuCoin using the Client class object.

You can also use the get_currencies() method from the  MarketData class to retrieve currencies from KuCoin, as shown in the following source code. 

from kucoin.market import market
import os
import pandas as pd

market = market.MarketData(url='https://api.kucoin.com' )
# get currenciescurrencies = market.get_currencies()
print(len(currencies))
currencies = pd.DataFrame.from_dict(currencies)
currencies.head()

Output:

You can also retrieve details of a single currency using the get_currency_detail() method.

# get currenciescurrency = market.get_currency_detail(currency = 'BTC')
print(currency)

Output:

{'currency': 'BTC', 'name': 'BTC', 'fullName': 'Bitcoin', 'precision': 8, 'confirms': 2, 'contractAddress': '', 'withdrawalMinSize': '0.001', 'withdrawalMinFee': '0.0005', 'isWithdrawEnabled': True, 'isDepositEnabled': True, 'isMarginEnabled': True, 'isDebitEnabled': True}

How to Get Fiat Prices for Currencies

The get_fiat_price() method returns the fiat prices for all the currencies on the KuCoin exchange. 

The method returns a list of dictionaries containing currency symbols and corresponding fiat prices. 

from kucoin.market import market
import os
import pandas as pd
market = market.MarketData(url='https://api.kucoin.com' )
fiat_prices = market.get_fiat_price()
print(len(fiat_prices))
fiat_prices = pd.DataFrame(fiat_prices.items(), columns=['Currency', 'Fiat Price'])
fiat_prices.head(10)

Output:

Getting Margin Info

The margin submodule from the Kucoin.margin module contains methods that call the margin endpoint of the KuCoin Rest API. 

You can use the MarginData class from the margin module to retrieve margin trading-related information from KuCoin.

How to Get Mark Price

The mark price of a contract is the estimated fair value used for the liquidations and calculations of unrealized PNL (Profit and Loss). The mark price indicates the estimated profit or loss if the contract is closed at a particular time. 

The get_mark_price() method returns the mark price for a particular ticker. The method uses a public endpoint from the Python KuCoin API. Hence, you don’t have to pass the API key, API secret, and the app passphrase to the get_mark_price() method. 

The following source code returns the mark price time and value for “USDT-BTC.”

from kucoin.margin import margin
margin = margin.MarginData(url='https://api.kucoin.com')
mark_price = margin.get_mark_price(symbol='USDT-BTC')
print(mark_price)

Output:

{'symbol': 'USDT-BTC', 'timePoint': 1660952250000, 'value': 4.771e-05}

How to Get Margin Configuration Info

The get_margin_config() method returns the margin configuration info for all the currencies on KuCoin. 

The method returns the list of currencies, the maximum leverage info, the warning debt ratio, and the liquidity debt ratio. 

The following source code demonstrates how to retrieve margin configuration info. 

from kucoin.margin import margin
margin = margin.MarginData(url='https://api.kucoin.com')
margin_config = margin.get_margin_config()
print(margin_config['currencyList'][:5])
print(margin_config['maxLeverage'])
print(margin_config['warningDebtRatio'])
print(margin_config['liqDebtRatio'])

Output:

['XEM', 'MATIC', 'VRA', 'IOTX', 'SHIB']
50.950.97
### ????

How to Get Margin Account Info

You can retrieve information from your margin accounts using the get_margin_account() method. The method uses a private endpoint from the KuCoin API. Therefore, you need to pass your API key, API secret, and passphrase to the MarginData class constructor. 

The get_margin_account method returns a dictionary containing debt ratio and detailed information about all your margin accounts. 

from kucoin.margin import margin
import os
api_key = os.environ['KC-Key']
api_secret = os.environ['KC-Secret']
api_passphrase = os.environ['KC-Passphrase']
margin = margin.MarginData(key = api_key, secret = api_secret, passphrase = api_passphrase)
margin_account = margin.get_margin_account()
margin_account.keys()

Output:

dict_keys(['debtRatio', 'accounts'])

You can retrieve detailed information about all your margin accounts using the “accounts” key from the dictionary returned by the get_margin_account() method. 

import pandas as pd
margin_accounts = pd.DataFrame.from_dict(margin_account['accounts'])
margin_accounts.head()

Output:

How to Get Cross Margin Risk Limit

The get_margin_risk_limit() returns the cross margin risk limit data for your margin account, as shown in the following source code. 

from kucoin.margin import margin
import osimport pandas as pd
api_key = os.environ['KC-Key']
api_secret = os.environ['KC-Secret']
api_passphrase = os.environ['KC-Passphrase']
margin = margin.MarginData(key = api_key, secret = api_secret, passphrase = api_passphrase)
margin_risk_limit = margin.get_margin_risk_limit(marginModel='cross')
margin_risk_limit = pd.DataFrame.from_dict(margin_risk_limit)
margin_risk_limit.head()

Output:

Trading with Python Kucoin API

The trade submodule module from the Kucoin.trade module provides functions for the trade endpoint of the KuCoin API. 

You can use methods from the TradeData class of the trade module to execute various trade operations on KuCoin.

How to Place a New Order

You can use the create_market_order() method to place a new order. You pass the ticker symbol, the order transaction type (buy or sell), and the order size as parameters to the method.

The create_market_order() makes the /api/v1/orders HTTP request to the KuCoin API server. The request rate limit for this request is 45 times/3s.

The function returns the order id. The following source code shows how to place a new buy order of size 2 for “BTC-USDT.”

Execute a Trade Based on a Particular Condition

You may want to conduct transactions based on a particular condition. 

For instance, you may want to buy or sell a particular currency when its price hits a certain threshold. 

In the following Python code, we write a basic trading bot. The code consists of a while loop that iterates every 2 seconds. The loop keeps track of the price of “ETH-USDT.” If the price of “ETH-USDT” drops to less than 1629, a new order is placed to buy “ETH-USDT.”

import time
from datetime import datetime
import os
api_key = os.environ['KC-Key']
api_secret = os.environ['KC-Secret']
api_passphrase = os.environ['KC-Passphrase']
market = market.MarketData(url='https://api.kucoin.com')
trade = trade.TradeData( key = api_key, secret = api_secret, passphrase = api_passphrase )
while True:
  ticker = market.get_ticker("ETH-USDT")
  now = datetime.now()
  print("ETH price at", now.strftime("%H:%M:%S"), "=", ticker['price']) 
  time.sleep(2)
    if float(ticker['price']) < 1629:
        order = trade.create_market_order('ETH-USDT', 'buy', size='2')

Output:

ETH price at 15:47:34 = 1629.75
ETH price at 15:47:36 = 1629.76
ETH price at 15:47:39 = 1630.13
ETH price at 15:47:41 = 1629.55
ETH price at 15:47:44 = 1629.55

How to Cancel an Order 

You can use the cancel_order() method to cancel an order. The request rate limit for this call is 60 times/3s.

order.cancel_order(orderId)

Frequently Asked Questions

What are KuCoin Shares?

KuCoin shares (KCS) are Etherium tokens that can be used on the KuCoin exchange to buy and sell a wide range of cryptocurrencies. 

Holders of these tokens can stake them and get dividend rewards. Furthermore, holders of KSC get discounts on trading fees, fast-track customer support, and other exclusive perks reserved for KCS holders. 

Does KuCoin report to IRS?

Currently, the KuCoin operations are not licensed in the USA; hence, it doesn’t have to report to IRS. However, the company states that it may disclose personal data at the request of government authorities. Therefore, you should report any income you generate from KuCoin to tax authorities. 

How do you see gains and losses on KuCoin?

To keep track of your crypto profits and losses in KuCoin, go to https://futures.kucoin.com/.

Click “Assets” from the top-right corner of the page, and then select the “USDT” or “Coin” option, as shown in the screenshot below:

Click the “Asset Overview” link on the following page. 

Select the “PNL History” link from the sidebar on the following page. You will see the profit and loss report of your USDT or Coins.  

What are the other clients Available for the KuCoin API

Apart from the Python KuCoin client, the following are the other clients available for the KuCoin API

• Java SDK
• PHP SDK
• Go SDK
• Nodejs SDK

Conclusion

KuCoin is one of the fastest-growing crypto exchanges that almost doubled its trading volume in the first of 2022 compared with the same period in 2021. KuCoin provides developer APIs you can leverage to develop software such as trading dashboards and trading bots. 

This tutorial teaches how the Python KuCoin API retrieves information and conducts trading operations on KuCoin. You can build upon the concepts learned in this tutorial to develop a range of trading applications for KuCoin. The next step would be to create your Python trading bot that passively makes you profit from KuCoin.