Bitunix#

How to Use Bitunix#

Bitunix integration in Lumibot supports only perpetual futures trading. Spot trading is not supported.

Account Funding and Cash Calculation:

You must transfer funds to the Futures section of your Bitunix account. Money in the spot wallet will not be available for trading.
For accurate calculation of available cash, it is strongly recommended to deposit USDT into your Bitunix Futures account. If you deposit crypto (e.g., BTC), it will not register as available cash for order sizing, though it can still be used as margin by Bitunix.

Environment Variables

Set the following environment variables in your .env file or system environment:

BITUNIX_API_KEY=your_bitunix_api_key
BITUNIX_API_SECRET=your_bitunix_api_secret

Setting Leverage for Bitunix Orders#

You can specify the leverage for a Bitunix futures order by setting the leverage attribute on the Asset object before creating the order. If not set, the default leverage configured at the broker will be used.

Example: Setting Leverage on a Bitunix Futures Order

from lumibot.entities import Asset, Order

asset = Asset("HBARUSDT", Asset.AssetType.CRYPTO_FUTURE, leverage=10)
order = self.create_order(
    asset=asset,
    quantity=100,
    side=Order.OrderSide.BUY,
    order_type=Order.OrderType.LIMIT,
    limit_price=0.18
)
submitted_order = self.submit_order(order)
if submitted_order:
    self.log_message(f"Placed order: ID={submitted_order.identifier}, Status={submitted_order.status}")

Example Usage#

Below are practical examples using the Bitunix broker in Lumibot, based on the bitunix_futures_example.py strategy.

Placing a Limit Order for a Futures Contract

from lumibot.entities import Asset, Order

asset = Asset("HBARUSDT", Asset.AssetType.CRYPTO_FUTURE)
asset.leverage = 5  # Example: set leverage to 5x
order = self.create_order(
    asset=asset,
    quantity=100,
    side=Order.OrderSide.BUY,
    order_type=Order.OrderType.LIMIT,
    limit_price=0.18
)
submitted_order = self.submit_order(order)
if submitted_order:
    self.log_message(f"Placed order: ID={submitted_order.identifier}, Status={submitted_order.status}")

Closing a Position

# Wait for a few seconds if needed
import time
time.sleep(10)
self.close_position(asset)

Cancelling Open Orders

orders = self.get_orders()
for order in orders:
    if order.asset.symbol == "HBARUSDT" and order.asset.asset_type == Asset.AssetType.CRYPTO_FUTURE and order.status in [
        Order.OrderStatus.NEW, Order.OrderStatus.SUBMITTED, Order.OrderStatus.OPEN, Order.OrderStatus.PARTIALLY_FILLED
    ]:
        self.cancel_order(order)
        self.log_message(f"Order {order.identifier} cancellation submitted.")

Checking Available Cash

cash = self.get_cash()
self.log_message(f"Current cash {cash}")

Note

For best results, ensure all funds in your Bitunix Futures account are in USDT. Crypto balances may not be counted as available cash for order sizing.

Documentation#

class lumibot.brokers.bitunix.Bitunix(config, max_workers: int = 1, chunk_size: int = 100, connect_stream: bool = True, poll_interval: float | None = None, data_source=None)

Bases: Broker

A broker class that connects to the Bitunix exchange for crypto futures trading.

This broker is designed specifically for Bitunix’s perpetual futures API. It supports submitting, tracking, and closing positions for crypto futures contracts (e.g., BTCUSDT perpetual). The broker uses Bitunix’s REST API for all trading operations.

Key Features: - Only supports crypto futures (TRADING_MODE must be “FUTURES”). - Uses Bitunix’s “flash close” endpoint to close open futures positions instantly at market price. - All positions and orders are managed using Bitunix’s API conventions. - Not suitable for spot trading or non-futures assets.

Notes: - The close_position method will use Bitunix’s flash close endpoint, which is faster and more reliable for closing futures positions than submitting a regular market order. - All asset symbols should be the full Bitunix symbol (e.g., “BTCUSDT”). - Leverage and margin settings are managed per-symbol as needed.

ASSET_TYPE_MAP = {'crypto': ['crypto'], 'crypto_future': ['future'], 'forex': [], 'future': ['future'], 'option': [], 'stock': []}

DEFAULT_POLL_INTERVAL = 5

LUMIBOT_DEFAULT_QUOTE_ASSET = USDT

cancel_order(order: Order): Cancels a FUTURES order.

close_position(strategy_name: str, asset: Asset, fraction: float = 1.0)

Close all or part of an existing position using a reduce‑only market order (tradeSide=”CLOSE”).

Parameters:

strategy_name (str) – Name of the strategy that owns the position.
asset (Asset) – The asset whose position should be closed.
fraction (float, optional) – Fraction of the position to close (0 < fraction ≤ 1). Defaults to 1 (full close).

Returns:

The submitted order, or None if no position exists.

Return type:

Optional[Order]

do_polling(): Polls Bitunix for order status updates and dispatches events.

get_historical_account_value(start_date=None, end_date=None, frequency=None) → dict: Not implemented: Bitunix does not support historical account value retrieval.

get_quote_asset()

get_time_to_close(): Return the remaining time for the market to close in seconds

get_time_to_open(): Return the remaining time for the market to open in seconds

get_timestamp()

is_market_open()

Determines if the market is open.

Parameters:: None –
Returns:: True if market is open, false if the market is closed.
Return type:: boolean

Examples

>>> self.is_market_open()
True

sell_all(strategy_name, cancel_open_orders: bool = True, strategy=None, is_multileg: bool = False): Override sell_all to use flash_close_position for futures.

ws_url: Private websocket endpoint for authenticated Bitunix futures streams.

Bitunix.get_time_to_close(): Return the remaining time for the market to close in seconds

Bitunix.get_time_to_open(): Return the remaining time for the market to open in seconds

Bitunix.get_timestamp()

Bitunix.is_market_open()

Determines if the market is open.

Parameters:: None –
Returns:: True if market is open, false if the market is closed.
Return type:: boolean

Examples

>>> self.is_market_open()
True

Bitunix.close_position(strategy_name: str, asset: Asset, fraction: float = 1.0)

Close all or part of an existing position using a reduce‑only market order (tradeSide=”CLOSE”).

Parameters:

strategy_name (str) – Name of the strategy that owns the position.
asset (Asset) – The asset whose position should be closed.
fraction (float, optional) – Fraction of the position to close (0 < fraction ≤ 1). Defaults to 1 (full close).

Returns:

The submitted order, or None if no position exists.

Return type:

Optional[Order]