ConnectorBase

Base class for all exchange and market connectors

ConnectorBase is the abstract base class that all Hummingbot exchange connectors extend. It provides the fundamental interface for trading operations, balance management, and order execution.

Class Definition

class ConnectorBase(NetworkIterator):
    def __init__(self, balance_asset_limit: Optional[Dict[str, Dict[str, Decimal]]] = None):
        super().__init__()
        self._account_balances = {}  # Dict[asset_name:str, Decimal]
        self._account_available_balances = {}  # Dict[asset_name:str, Decimal]

Core Properties

name · str

Returns the connector name (typically the class name).

display_name · str

Returns the display name for the connector (defaults to name).

ready · bool

Indicates whether the connector is ready to be used. Must be implemented by subclasses.

status_dict · Dict[str, bool]

A dictionary of statuses of various connector components. Must be implemented by subclasses.

in_flight_orders · Dict[str, InFlightOrderBase]

Returns a dictionary of all in-flight orders tracked by this connector. Must be implemented by subclasses.

event_logs · List[any]

Returns a list of all events logged by this connector.

available_balances · Dict[str, Decimal]

Returns the available balance for all assets.

real_time_balance_update · bool

Flag indicating whether the connector provides real-time balance updates.

Balance Management

get_balance

def get_balance(self, currency: str) -> Decimal:
    """
    Returns the total balance for the given currency.
    """

currency · str

The currency (token) name to get balance for.

return · Decimal

Total balance for the given currency.

get_available_balance

def get_available_balance(self, currency: str) -> Decimal:
    """
    Returns available balance for trading. Accounts for in-flight orders and 
    applies balance limits if configured.
    """

currency · str

The currency (token) name.

return · Decimal

Available balance for trading for the specified currency.

get_all_balances

def get_all_balances(self) -> Dict[str, Decimal]:
    """
    Returns total balances of all assets.
    """

return · Dict[str, Decimal]

Dictionary mapping asset names to total balances.

Order Execution

buy

def buy(
    self,
    trading_pair: str,
    amount: Decimal,
    order_type: OrderType,
    price: Decimal,
    **kwargs
) -> str:
    """
    Buys an amount of base asset (of the given trading pair).
    """

trading_pair · str

The market (e.g. BTC-USDT) to buy from.

amount · Decimal

The amount in base token value.

order_type · OrderType

The order type (MARKET or LIMIT).

price · Decimal

The price for the order.

kwargs · **kwargs

Additional parameters (e.g., expiration_ts, position_action).

return · str

The order ID (client_order_id) of the created buy order.

sell

def sell(
    self,
    trading_pair: str,
    amount: Decimal,
    order_type: OrderType,
    price: Decimal,
    **kwargs
) -> str:
    """
    Sells an amount of base asset (of the given trading pair).
    """

Same parameters as buy, but executes a sell order.

return · str

The order ID (client_order_id) of the created sell order.

cancel

def cancel(self, trading_pair: str, client_order_id: str):
    """
    Cancels an order.
    """

trading_pair · str

The market (e.g. BTC-USDT) of the order.

client_order_id · str

The internal order ID.

cancel_all

async def cancel_all(self, timeout_seconds: float) -> List[CancellationResult]:
    """
    Cancels all in-flight orders and waits for cancellation results.
    """

timeout_seconds · float

The timeout at which the operation will be canceled.

return · List[CancellationResult]

List of CancellationResult indicating whether each order was successfully canceled.

Batch Operations

batch_order_create

def batch_order_create(
    self,
    orders_to_create: List[Union[LimitOrder, MarketOrder]]
) -> List[Union[LimitOrder, MarketOrder]]:
    """
    Issues a batch order creation as a single API request for exchanges that 
    implement this feature. The default implementation sends requests one by one.
    """

orders_to_create · List[Union[LimitOrder, MarketOrder]]

List of LimitOrder or MarketOrder objects representing orders to create.

return · List[Union[LimitOrder, MarketOrder]]

List of created orders complete with generated order IDs.

batch_order_cancel

def batch_order_cancel(self, orders_to_cancel: List[LimitOrder]):
    """
    Issues a batch order cancelation as a single API request for exchanges that 
    implement this feature. The default implementation sends requests one by one.
    """

orders_to_cancel · List[LimitOrder]

List of orders to cancel.

Price and Trading Rules

get_price

def get_price(self, trading_pair: str, is_buy: bool, amount: Decimal = s_decimal_NaN) -> Decimal:
    """
    Gets the price for the market trading pair.
    """

trading_pair · str

The market trading pair.

is_buy · bool

Whether to get buy price (True) or sell price (False).

amount · Decimal · default: "NaN"

The amount (optional).

return · Decimal

The price for the trading pair.

get_order_price_quantum

def get_order_price_quantum(self, trading_pair: str, price: Decimal) -> Decimal:
    """
    Returns a price step, the minimum price increment for a given trading pair.
    """

trading_pair · str

The trading pair.

price · Decimal

The price value.

return · Decimal

The minimum price increment.

get_order_size_quantum

def get_order_size_quantum(self, trading_pair: str, order_size: Decimal) -> Decimal:
    """
    Returns an order amount step, the minimum amount increment for a given trading pair.
    """

trading_pair · str

The trading pair.

order_size · Decimal

The order size value.

return · Decimal

The minimum amount increment.

quantize_order_price

def quantize_order_price(self, trading_pair: str, price: Decimal) -> Decimal:
    """
    Applies trading rule to quantize order price.
    """

trading_pair · str

The trading pair.

price · Decimal

The price to quantize.

return · Decimal

The quantized price that conforms to exchange rules.

quantize_order_amount

def quantize_order_amount(self, trading_pair: str, amount: Decimal) -> Decimal:
    """
    Applies trading rule to quantize order amount.
    """

trading_pair · str

The trading pair.

amount · Decimal

The amount to quantize.

return · Decimal

The quantized amount that conforms to exchange rules.

Async Methods

get_quote_price

async def get_quote_price(
    self,
    trading_pair: str,
    is_buy: bool,
    amount: Decimal
) -> Decimal:
    """
    Returns a quote price (or exchange rate) for a given amount.
    """

trading_pair · str

The market trading pair.

is_buy · bool

True for buy order, False for sell order.

amount · Decimal

The order amount.

return · Decimal

The quoted price.

get_order_price

async def get_order_price(
    self,
    trading_pair: str,
    is_buy: bool,
    amount: Decimal
) -> Decimal:
    """
    Returns the price required for order submission. This price could differ 
    from the quote price (e.g. for an exchange with order book).
    """

Same parameters as get_quote_price.

return · Decimal

The price to specify in an order.

all_trading_pairs

async def all_trading_pairs(self) -> List[str]:
    """
    List of all trading pairs supported by the connector.
    """

return · List[str]

List of trading pair symbols in the Hummingbot format.

Balance Calculations

in_flight_asset_balances

def in_flight_asset_balances(
    self,
    in_flight_orders: Dict[str, InFlightOrderBase]
) -> Dict[str, Decimal]:
    """
    Calculates total asset balances locked in in_flight_orders including fee (estimated).
    For BUY orders: quote asset balance locked.
    For SELL orders: base asset balance locked.
    """

in_flight_orders · Dict[str, InFlightOrderBase]

Dictionary of in-flight orders.

return · Dict[str, Decimal]

Dictionary of tokens and their balance locked in orders.

order_filled_balances

def order_filled_balances(self, starting_timestamp: float = 0) -> Dict[str, Decimal]:
    """
    Calculates total asset balance changes from filled orders since the timestamp.
    """

starting_timestamp · float · default: "0"

The starting timestamp to filter order filled events.

return · Dict[str, Decimal]

Dictionary of tokens and their balance changes.

estimate_fee_pct

def estimate_fee_pct(self, is_maker: bool) -> Decimal:
    """
    Estimates the trading fee for maker or taker type of order.
    """

is_maker · bool

Whether to get trading fee for maker (True) or taker (False) order.

return · Decimal

An estimated fee in percentage value.

Lifecycle Methods

start

def start(self, clock: Clock, timestamp: float):
    """
    Starts the connector with the given clock.
    """

tick

def tick(self, timestamp: float):
    """
    Called automatically by the clock for each tick (1 second by default).
    """

stop_tracking_order

def stop_tracking_order(self, order_id: str):
    """
    Stops tracking an in-flight order.
    """

Utility Methods

split_trading_pair

@staticmethod
def split_trading_pair(trading_pair: str) -> Tuple[str, str]:
    """
    Splits a trading pair into base and quote assets.
    """

trading_pair · str

The trading pair to split (e.g., “BTC-USDT”).

return · Tuple[str, str]

Tuple of (base_asset, quote_asset).

Usage Example

from hummingbot.connector.connector_base import ConnectorBase
from decimal import Decimal
from hummingbot.core.data_type.common import OrderType

class MyExchangeConnector(ConnectorBase):
    @property
    def ready(self) -> bool:
        return self._trading_pairs_ready and self._account_balances_ready
        
    @property
    def status_dict(self) -> Dict[str, bool]:
        return {
            "trading_pairs_initialized": self._trading_pairs_ready,
            "account_balances_initialized": self._account_balances_ready,
        }
        
    def buy(self, trading_pair: str, amount: Decimal, 
            order_type: OrderType, price: Decimal, **kwargs) -> str:
        # Implement buy order logic
        order_id = self._create_order(trading_pair, True, amount, order_type, price)
        return order_id
        
    def sell(self, trading_pair: str, amount: Decimal,
             order_type: OrderType, price: Decimal, **kwargs) -> str:
        # Implement sell order logic
        order_id = self._create_order(trading_pair, False, amount, order_type, price)
        return order_id

Market Events

The connector emits the following market events:

• ReceivedAsset
• BuyOrderCompleted
• SellOrderCompleted
• WithdrawAsset
• OrderCancelled
• OrderFilled
• OrderExpired
• OrderFailure
• TransactionFailure
• BuyOrderCreated
• SellOrderCreated
• FundingPaymentCompleted
• RangePositionLiquidityAdded
• RangePositionLiquidityRemoved
• RangePositionUpdateFailure