KuCoin Futures Trading Bot in Python

This guide shows how to build a KuCoin Futures trading bot in Python with LumiBot, for both AI agent trading and algorithmic trading. LumiBot connects to KuCoin Futures through CCXT, the open source library that talks to more than 100 crypto exchanges. You will create a KuCoin Futures account and API key, connect it, and run two examples: a simple algorithmic trading bot and an agentic trading bot where an AI agent makes the calls.

KuCoin Futures at a glance

CCXT exchange id

kucoinfutures

Markets

Perpetual swaps, Dated futures

Testnet (sandbox)

No

Credentials

API key, API passphrase (CCXT calls it password), API secret

Live data streams

prices, order book, trades, candles, your orders, your balance

CCXT request spacing

about 7.5 ms between requests

Official site

https://futures.kucoin.com/

API docs

https://docs.kucoin.com

What is KuCoin Futures?

KuCoin Futures is the futures side of the KuCoin crypto exchange. It offers perpetual contracts that are USDT-margined or coin-margined (settled in the coin itself, like BTC).

Sign up for KuCoin Futures

  1. Create a KuCoin account on the website and finish identity verification.

  2. Turn on Google two-factor authentication and set a trading password. KuCoin asks for your trading password, an email code and a Google code when you create an API key.

  3. KuCoin Futures has no testnet in CCXT, so plan to start with a very small live position.

Open a KuCoin Futures account

Create a KuCoin Futures API key

  1. Log in, click your avatar and open API Management.

  2. Click Create API and pick API Trading (not Link Third-Party Applications).

  3. Enter an API name and make up a passphrase. Save the passphrase, because KuCoin cannot recover it.

  4. Turn on the permissions (see below) and add your bot’s IP address to the whitelist.

  5. Finish the security check with your trading password, email code and Google code.

  6. Copy the API key and secret right away and store them with the passphrase.

Which permissions to turn on: Turn on General (read access) and Futures (futures trading). Leave withdrawals off. KuCoin says you must add an IP address to the whitelist before you can turn on the trading permissions.

Warning

Never turn on withdrawals for a KuCoin Futures trading bot key. Bind the key to your server’s IP address when KuCoin Futures lets you, keep the secret out of your code and out of Git, and delete the key if it ever leaks.

Connect KuCoin Futures to LumiBot

The simplest way: put these lines in a .env file next to your strategy. LumiBot loads the file, sees TRADING_BROKER=kucoinfutures and connects to KuCoin Futures for you, so your strategy needs no broker code.

TRADING_BROKER=kucoinfutures
KUCOINFUTURES_API_KEY=your_apiKey
KUCOINFUTURES_API_PASSPHRASE=your_password
KUCOINFUTURES_API_SECRET=your_secret

LumiBot reads exactly the fields CCXT needs for KuCoin Futures (apiKey, password, secret). If one is missing, LumiBot stops at start-up and names the variable you still need.

You can also build the broker in code. This is handy when one script talks to more than one exchange, or when you need extra CCXT options. The keys in the config are CCXT’s own credential names for KuCoin Futures:

import os

KUCOINFUTURES_CONFIG = {
    "exchange_id": "kucoinfutures",
    "apiKey": os.environ.get("KUCOINFUTURES_API_KEY"),
    "password": os.environ.get("KUCOINFUTURES_API_PASSPHRASE"),
    "secret": os.environ.get("KUCOINFUTURES_API_SECRET"),
    "sandbox": False,  # no sandbox for this exchange
}

from lumibot.brokers import Ccxt

broker = Ccxt(KUCOINFUTURES_CONFIG)
# then: MyStrategy(broker=broker, ...)

Either way, LumiBot turns on CCXT’s built-in rate limiting for you.

Testing on KuCoin Futures

KuCoin Futures has no sandbox in CCXT. Test with a very small position first, leave KUCOINFUTURES_SANDBOX unset, and in a code config set "sandbox": False.

Algorithmic trading example: a simple KuCoin Futures bot

CCXT lists no spot market for KuCoin Futures, so this example trades a perpetual contract. It opens one small long BTC position worth about 50 USDT and then holds it. It is a starting point to check that your keys, balances and orders work. If the exchange’s minimum order is larger, raise the amount. If your account uses hedge mode, add position_side="long" to create_order.

from lumibot.entities import Asset
from lumibot.strategies import Strategy


class KucoinfuturesOpenOneLong(Strategy):
    """Open one small long BTC perpetual position, then hold it."""

    def initialize(self):
        self.sleeptime = "1H"
        self.set_market("24/7")  # crypto trades all day, every day

    def on_trading_iteration(self):
        # The full CCXT symbol keeps the settlement currency clear.
        contract = self.broker.get_asset("BTC/USDT:USDT")
        if self.get_position(contract) is not None:
            return  # already holding the position
        price = self.get_last_price(contract)
        if price:
            # Each contract covers contract.multiplier BTC; size the order to about 50 USDT.
            quantity = round(50 / (price * contract.multiplier), 6)
            order = self.create_order(contract, quantity, "buy")
            self.submit_order(order)


if __name__ == "__main__":
    # LumiBot reads TRADING_BROKER and the keys from your .env file.
    strategy = KucoinfuturesOpenOneLong(quote_asset=Asset("USDT", asset_type=Asset.AssetType.CRYPTO))
    strategy.run_live()

Agentic trading example: an AI agent that trades on KuCoin Futures

Agentic trading means an AI agent reads the market and decides what to do. In this example one LumiBot agent looks at prices and your KuCoin Futures account, then places the orders itself. There is no Python logic in between: you set the rules in plain English in the prompt, such as what it may trade and how big each order can be. This follows the same pattern as LumiBot’s AI trading team examples.

from lumibot.entities import Asset
from lumibot.strategies import Strategy


class KucoinfuturesAITrader(Strategy):
    """One AI agent researches the market and places the trades itself."""

    def initialize(self):
        self.sleeptime = "4H"
        self.set_market("24/7")
        self.agents.create(
            name="trader",
            model="openai/gpt-6-luna",
            reasoning_effort="high",
            allow_trading=True,
            system_prompt=(
                "You manage a small crypto account on KuCoin Futures. "
                "You may trade the BTC/USDT:USDT perpetual contract (asset_type 'crypto_future'), long or short, or stay flat. "
                "Before every order, call account_portfolio, account_positions and "
                "market_last_price for that exact symbol in the same run. "
                "Keep each order under 10% of the account value. "
                "Explain each decision in one short paragraph."
            ),
        )

    def on_trading_iteration(self):
        self.agents["trader"].run(
            task_prompt="Review recent BTC/USDT:USDT prices and your current position, then decide whether to buy, sell or hold.",
            context={"exchange": "KuCoin Futures", "quote": "USDT", "date": self.get_datetime().isoformat()},
        )


if __name__ == "__main__":
    # LumiBot reads TRADING_BROKER and the keys from your .env file.
    strategy = KucoinfuturesAITrader(quote_asset=Asset("USDT", asset_type=Asset.AssetType.CRYPTO))
    strategy.run_live()

The agent needs a model key such as OPENAI_API_KEY in your environment. See the AI agents quickstart for models, tools and memory.

What you can trade on KuCoin Futures through CCXT

Market

Listed by CCXT

Spot

No

Margin

No

Perpetual swaps

Yes

Dated futures

Yes

Options

Not listed by CCXT

CCXT lists these order features for KuCoin Futures: market orders, limit orders, stop orders, stop-loss orders, take-profit orders, editing open orders, canceling orders.

For perpetual contracts, use the full CCXT symbol so the settlement currency is clear, for example BTC/USDT:USDT. See the CCXT guide for contract quantities, position modes and leverage.

KuCoin Futures tips

  • CCXT has two KuCoin ids. Use kucoinfutures for perpetual futures like BTC/USDT:USDT and kucoin for spot like BTC/USDT. Keys for both come from the same KuCoin API Management page; turn on the permission for what you trade.

  • Every KuCoin key needs three values: API key, secret and passphrase. Put the passphrase in KUCOINFUTURES_API_PASSPHRASE (or "password" in a code config).

  • Add an IP whitelist. KuCoin’s help center says trading keys with no IP address can be deleted, or lose trading permission, after 30 days without use. Keys with only General permission do not expire.

  • KuCoin says coin-margined contracts such as BTC/USD:BTC are settled in their own coin (BTC here), while USDT-margined contracts like BTC/USDT:USDT are settled in USDT.

Frequently asked questions

Can I build a KuCoin Futures trading bot in Python?

Yes. Install LumiBot (pip install lumibot), set your KuCoin Futures keys and use the kucoinfutures CCXT exchange id as shown above.

Does KuCoin Futures have a testnet?

No testnet is set up for KuCoin Futures in LumiBot. Start with a small amount, and in a code config set "sandbox": False.

Which API permissions does a KuCoin Futures bot need?

Turn on General (read access) and Futures (futures trading). Leave withdrawals off. KuCoin says you must add an IP address to the whitelist before you can turn on the trading permissions.

Can an AI agent trade on KuCoin Futures by itself?

Yes. The agentic example above gives one agent permission to trade. You control what it may trade and how much through its prompt.

Can I trade KuCoin Futures perpetual futures with LumiBot?

CCXT lists perpetual swaps for this exchange. Use the full contract symbol, such as BTC/USDT:USDT.

Is LumiBot free?

Yes. LumiBot is open source on GitHub at https://github.com/Lumiwealth/lumibot. You pay only your exchange’s trading fees and, for AI agents, your model provider.

Run it in the cloud with BotSpot

Do not want to keep a computer running for your KuCoin Futures bot? BotSpot is the hosted home for LumiBot strategies and AI trading agents: build with AI, backtest, connect a broker, and watch every trade with logs and alerts.

Try BotSpot

Sources