Events API

Domain events: fills, funding, liquidation, and settlement.

Fill

Fill dataclass

to_dict

to_dict() -> dict[str, Any]

Return a log/serialization-friendly dict.

from_dict classmethod

from_dict(data: Mapping[str, Any]) -> Fill

Construct a Fill from a mapping (e.g., exchange fill JSON).

create classmethod

create(
    *,
    order_id: str,
    instrument_id: str,
    side: OrderSide | str,
    quantity: Quantity | Decimal | str,
    price: Price | Decimal | str,
    timestamp_ms: TimestampMs | int,
    fee: Money | Decimal | str = Decimal(0)
) -> Fill

Create Fill with keyword-only arguments for safety.

All parameters must be passed by name, preventing positional argument order mistakes that are common with the regular constructor.

Example

fill = Fill.create( ... order_id="o1", ... instrument_id="BTC-USD", ... side=OrderSide.BUY, ... quantity=Decimal("1"), ... price=Decimal("10000"), ... timestamp_ms=1234567890, ... )

from_exchange_fill classmethod

from_exchange_fill(
    exchange: str,
    raw: Mapping[str, Any],
    *,
    market: str | None = None
) -> Fill

Construct a Fill from a raw exchange payload.

Known keys (fallbacks are used if a key is missing): - id | fill_id | trade_id | order_id -> order_id - symbol | instrument | instrument_id -> instrument_id - side (BUY/SELL) -> side - qty | size | quantity -> quantity - price -> price - fee | commission -> fee (defaults to 0) - ts | timestamp | time | timestamp_ms -> timestamp_ms

FillBuilder

FillBuilder

Fluent builder for creating fills.

Example

fill = ( ... FillBuilder() ... .order("order-123") ... .instrument("BTC-PERP") ... .buy("1.5") ... .at_price("10000") ... .with_fee("10") ... .at_time(1234567890000) ... .build() ... )

order

order(order_id: str) -> 'FillBuilder'

Set order ID.

instrument

instrument(instrument_id: str) -> 'FillBuilder'

Set instrument ID.

buy

buy(quantity: Decimal | str | float) -> 'FillBuilder'

Set as buy with quantity.

sell

sell(quantity: Decimal | str | float) -> 'FillBuilder'

Set as sell with quantity.

with_side

with_side(side: OrderSide | str) -> 'FillBuilder'

Set side.

with_quantity

with_quantity(
    quantity: Decimal | str | float,
) -> "FillBuilder"

Set quantity.

at_price

at_price(price: Decimal | str | float) -> 'FillBuilder'

Set fill price.

with_fee

with_fee(fee: Decimal | str | float) -> 'FillBuilder'

Set fee.

at_time

at_time(timestamp_ms: int) -> 'FillBuilder'

Set timestamp.

build

build() -> Fill

Build the fill.

FundingEvent

FundingEvent dataclass

LiquidationEvent

LiquidationEvent dataclass

SettlementEvent

SettlementEvent dataclass

FeeEvent

FeeEvent dataclass

Explicit fee charged to an account.

amount

Positive fee size (e.g. Decimal("1.5") for a 1.5 USDT fee). From the account's point of view this is a cash outflow.

signed_amount

Signed representation from the account's perspective (negative = cash paid out).

signed_amount property

signed_amount: Money

Return fee as a signed cash-flow (negative = outflow).

Event Hooks

EventBus

EventBus

Simple event bus for pub/sub pattern.

Example

bus = EventBus() @bus.on("fill") ... def handle_fill(fill): ... print(f"Received fill: {fill}") bus.emit("fill", fill=my_fill)

on

on(
    event: str, handler: EventHandler | None = None
) -> EventHandler

Register a handler for an event.

Can be used as decorator or direct call

@bus.on("fill") def handler(fill): ...

or

bus.on("fill", handler)

off

off(
    event: str, handler: EventHandler | None = None
) -> None

Remove handler(s) for an event.

If handler is None, removes all handlers for the event.

emit

emit(event: str, **kwargs: Any) -> None

Emit an event to all registered handlers.

clear

clear() -> None

Remove all handlers.

on

on

on(
    event: str, handler: EventHandler | None = None
) -> EventHandler

Register a global event handler.

Example

@on("fill_applied") def log_fill(fill, portfolio): print(f"Applied {fill}")

off

off

off(
    event: str, handler: EventHandler | None = None
) -> None

Remove global event handler(s).

emit

emit

emit(event: str, **kwargs: Any) -> None

Emit a global event.