Market Data

Market data structures including order books, price types, and position information

PriceType

Enum defining different types of prices used in the framework.

Source: hummingbot/core/data_type/common.py:52

MidPrice · int · default: "1"

Mid-market price (average of best bid and best ask)

BestBid · int · default: "2"

Best (highest) bid price in the order book

BestAsk · int · default: "3"

Best (lowest) ask price in the order book

LastTrade · int · default: "4"

Price of the last executed trade

LastOwnTrade · int · default: "5"

Price of the last trade executed by the bot

InventoryCost · int · default: "6"

Inventory cost price

Custom · int · default: "7"

Custom price type

PositionAction

Enum defining position actions for derivatives trading.

Source: hummingbot/core/data_type/common.py:33

OPEN · str · default: "OPEN"

Open a new position

CLOSE · str · default: "CLOSE"

Close an existing position

NIL · str · default: "NIL"

No position action (for spot trading)

PositionSide

Enum defining position sides for derivatives exchanges.

Source: hummingbot/core/data_type/common.py:40

LONG · str · default: "LONG"

Long position (betting on price increase)

SHORT · str · default: "SHORT"

Short position (betting on price decrease)

BOTH · str · default: "BOTH"

Both long and short positions (for hedge mode)

PositionMode

Enum defining position modes for derivatives exchanges.

Source: hummingbot/core/data_type/common.py:47

HEDGE · str · default: "HEDGE"

Hedge mode - allows simultaneous long and short positions

ONEWAY · str · default: "ONEWAY"

One-way mode - only one position direction at a time

OrderBookMessageType

Enum defining types of order book messages.

Source: hummingbot/core/data_type/order_book_message.py:9

SNAPSHOT · int · default: "1"

Full order book snapshot

DIFF · int · default: "2"

Incremental order book update (diff)

TRADE · int · default: "3"

Trade message

OrderBookMessage

NamedTuple representing an order book message.

Source: hummingbot/core/data_type/order_book_message.py:16

type · OrderBookMessageType

Type of the message (SNAPSHOT, DIFF, or TRADE)

content · Dict[str, any]

Message content containing order book data

timestamp · float

Message timestamp

Properties

update_id · int

Update ID for SNAPSHOT and DIFF messages, -1 for TRADE messages

first_update_id · int

First update ID for DIFF messages, -1 otherwise

trade_id · int

Trade ID for TRADE messages, -1 otherwise

trading_pair · str

Trading pair for the message

asks · List[OrderBookRow]

List of ask (sell) orders

bids · List[OrderBookRow]

List of bid (buy) orders

has_update_id · bool

True if the message has an update ID (SNAPSHOT or DIFF)

has_trade_id · bool

True if the message has a trade ID (TRADE)

OrderBookRow

NamedTuple representing a row in an order book.

Source: hummingbot/core/data_type/order_book_row.py:7

Used to apply changes to OrderBook. OrderBook classes use float internally for better performance over Decimal.

price · float

Price level

amount · float

Order amount at this price level

update_id · int

Update ID associated with this row

ClientOrderBookRow

NamedTuple representing an order book row with Decimal precision.

Source: hummingbot/core/data_type/order_book_row.py:16

Used in market classes where OrderBook values are converted to Decimal for precision.

price · Decimal

Price level (high precision)

amount · Decimal

Order amount at this price level (high precision)

update_id · int

Update ID associated with this row

OrderUpdate

NamedTuple representing an order status update.

Source: hummingbot/core/data_type/in_flight_order.py:39

trading_pair · str

Trading pair for the order

update_timestamp · float

Timestamp of the update (in seconds)

new_state · OrderState

New state of the order

client_order_id · Optional[str] · default: "None"

Client-assigned order identifier

exchange_order_id · Optional[str] · default: "None"

Exchange-assigned order identifier

misc_updates · Optional[Dict[str, Any]] · default: "None"

Additional miscellaneous update information

TokenAmount

Dataclass representing an amount of a specific token.

Source: hummingbot/core/data_type/trade_fee.py:19

token · str

Token symbol (e.g., “BTC”, “USDT”)

amount · Decimal

Amount of the token

Methods

__iter__() · Iterator

Allows unpacking as tuple: token, amount = token_amount

to_json() · Dict[str, Any]

Converts to a JSON-serializable dictionary

from_json(data) · classmethod

Creates a TokenAmount from a JSON dictionary

TradeFeeSchema

Dataclass containing the information needed to build a TradeFee object.

Source: hummingbot/core/data_type/trade_fee.py:39

percent_fee_token · Optional[str] · default: "None"

Token in which the percentage fee is charged (if always charged in a specific token, e.g., BNB on Binance)

maker_percent_fee_decimal · Decimal · default: "0"

Maker fee as a decimal (e.g., 0.001 for 0.1%)

taker_percent_fee_decimal · Decimal · default: "0"

Taker fee as a decimal (e.g., 0.001 for 0.1%)

buy_percent_fee_deducted_from_returns · bool · default: "False"

Whether buy fees are deducted from returns instead of added to costs

maker_fixed_fees · List[TokenAmount] · default: "[]"

Fixed fees charged for maker orders

taker_fixed_fees · List[TokenAmount] · default: "[]"

Fixed fees charged for taker orders

TradeFeeBase

Abstract base dataclass representing a trade fee for a particular order.

Source: hummingbot/core/data_type/trade_fee.py:75

percent · Decimal · default: "0"

Percentage fee as a decimal

percent_token · Optional[str] · default: "None"

Token in which the percentage fee is charged (only set for third-token fees like Binance BNB)

flat_fees · List[TokenAmount] · default: "[]"

List of flat fees (token, amount) tuples

Properties

fee_asset · str

The asset in which the fee is paid (either percent_token or first flat fee token)

Methods

new_spot_fee(fee_schema, trade_type, percent, percent_token, flat_fees) · classmethod

Creates a new spot trading fee instance

new_perpetual_fee(fee_schema, position_action, percent, percent_token, flat_fees) · classmethod

Creates a new perpetual trading fee instance

from_json(data) · classmethod

Creates a TradeFeeBase instance from a JSON dictionary

to_json() · Dict[str, any]

Converts the fee to a JSON-serializable dictionary

fee_amount_in_token(trading_pair, price, order_amount, token, exchange, rate_source) · Decimal

Calculates the fee amount expressed in a specific token

get_fee_impact_on_order_cost(order_candidate, exchange) · Optional[TokenAmount]

Abstract method - returns the impact of the fee on cost requirements for a candidate order

get_fee_impact_on_order_returns(order_candidate, exchange) · Optional[Decimal]

Abstract method - returns the impact of the fee on expected returns from a candidate order

AddedToCostTradeFee

Trade fee that is added to the order cost.

Source: hummingbot/core/data_type/trade_fee.py:251

Inherits from TradeFeeBase. Used when fees are added to the cost of the order (typical for buy orders).

DeductedFromReturnsTradeFee

Trade fee that is deducted from the order returns.

Source: hummingbot/core/data_type/trade_fee.py:292

Inherits from TradeFeeBase. Used when fees are deducted from the returns of the order (typical for sell orders).

MakerTakerExchangeFeeRates

Frozen dataclass representing maker and taker fee rates for an exchange.

Source: hummingbot/core/data_type/trade_fee.py:321

maker · Decimal

Maker fee rate as a decimal

taker · Decimal

Taker fee rate as a decimal

maker_flat_fees · List[TokenAmount]

Flat fees for maker orders

taker_flat_fees · List[TokenAmount]

Flat fees for taker orders