quantpylib.standards.portfolio

Fills

apply_fill_trace(**kwargs)

Materialize an archived accepted fill trace without live OMS side effects.

Order

Normalized order state artifact.

Order is the current known state of one venue order, keyed by oid when the exchange order id is known and by cloid (if available) while the order is still local or awaiting acknowledgement. Signed amount encodes side: positive means buy/long-increasing, negative means sell/short-increasing. price is the submitted order price; actual execution prices live on first-class Fill records. price_rule is a matching-engine or gateway rule used to derive a submitted price when no explicit price was supplied.

filled_sz is the non-negative cumulative fill size accepted as local order state. last_fill_sz is the latest local delta in cumulative filled size and is the universal authority for order-update deltas.

Timestamp semantics

• ts_submit_ns: local time when submit or modify was attempted.
• ts_cancel_ns: local time when cancel was attempted.
• ts_exch_ns: exchange order/matching-engine timestamp, if provided.
• ts_update_ns: local time when this order-state mutation was accepted. Duplicate/no-op messages do not advance it or trigger handlers.

Example derived timings

• Submit acknowledgement latency: ack.ts_update_ns - submit.ts_submit_ns on the first exchange acknowledgement (NEW, PARTIAL, FILLED, or REJECTED).
• Cancel acknowledgement latency: cancelled.ts_update_ns - cancel_pending.ts_cancel_ns when a cancel attempt resolves to CANCELLED, FILLED, PARTIAL, REJECTED, or another venue-specific terminal/current status.
• Observed time to first fill: first_fill_update.ts_update_ns - submit.ts_submit_ns, using the first accepted update where filled_sz increases.
• Exchange-to-local update lag: ts_update_ns - ts_exch_ns when the venue timestamp is present and clocks are comparable.

__init__(exc, oid=None, cloid=None, ticker=None, amount=None, price=None, price_rule=None, tif=None, ord_type=None, reduce_only=None, tp=None, sl=None, ord_status=None, filled_sz=Decimal('0'), last_fill_sz=None, ts_submit_ns=None, ts_cancel_ns=None, ts_exch_ns=None, ts_update_ns=None, **kwargs)

Initialize an Order object.

Parameters:

Name	Type	Description	Default
exc	str	Alias for the exchange client.	required
oid	str	The order id. Defaults to None.	None
cloid	str	The client order id. Defaults to None.	None
ticker	str	The ticker symbol. Defaults to None.	None
amount	Decimal	The quantity of contracts. Defaults to None.	None
price	Decimal	The price of the order. Defaults to None.	None
price_rule	str	Exchange-side rule for deriving the order price. Defaults to None.	None
tif	str	The time in force. Defaults to None.	None
ord_type	str	The order type. Defaults to None.	None
reduce_only	bool	Whether the order is a reduce-only order. Defaults to None.	None
tp	Decimal	The take profit price. Defaults to None.	None
sl	Decimal	The stop loss price. Defaults to None.	None
ord_status	str	The order status. Defaults to None.	None
filled_sz	Decimal	The filled size. Defaults to Decimal('0').	Decimal('0')
last_fill_sz	Decimal	The last filled size. Defaults to None.	None
ts_submit_ns	int	Local submit or modify timestamp in nanoseconds.	None
ts_cancel_ns	int	Local cancel-attempt timestamp in nanoseconds.	None
ts_exch_ns	int	Exchange matching-engine/order timestamp in nanoseconds, if provided.	None
ts_update_ns	int	Local timestamp for the latest accepted order update in nanoseconds.	None

as_dict(test=False)

Convert the Order object to a dictionary.

is_alive()

Check if the order is alive.

Orders

__init__(exc, orders=None, delta_handlers=None, copy_to_handlers=True, logger=None)

Initialize an Orders object.

Parameters:

Name	Type	Description	Default
exc	str	Venue/container provenance stamped onto orders.	required
orders	list	The list of orders. Defaults to None.	None
delta_handlers	list	List of coroutine handlers for order updates. Defaults to None.	None
logger	Logger	Structured logger for trace emission. Defaults to None.	None

apply_order_trace(clear_unalived=True, **kwargs)

Materialize an archived accepted order trace without live OMS side effects.

The trace update timestamp is preserved, no logger record is emitted, and delta handlers are not triggered. Staleness, identity, fill-regression, and dead-order rejection rules match upsert_order.

as_dict(test=False)

Convert the Orders object to a dictionary where oid is known.

as_list(test=False)

Convert the Orders object to a list.

ask_level_exists(ticker, price)

Check if an ask level exists.

Parameters:

Name	Type	Description	Default
ticker	str	The ticker symbol.	required
price	Decimal	The price level.	required

bid_level_exists(ticker, price)

Check if a bid level exists.

Parameters:

Name	Type	Description	Default
ticker	str	The ticker symbol.	required
price	Decimal	The price level.	required

cloid_query(cloid)

Get the order by client order id.

Parameters:

Name	Type	Description	Default
cloid	str	The client order id.	required

get_ask_orders(ticker, sort=True, include_pending=True, copy=True, as_dict=False, test=False)

Get the ask orders for a specified ticker, sorted with the head of the list being closest to the top of the book.

Parameters:

Name	Type	Description	Default
ticker	str	The ticker symbol for which to retrieve ask orders.	required
sort	bool	Whether to sort the orders by price in ascending order. Defaults to True.	True
include_pending	bool	Whether to include locally submitted orders that are not exchange-acknowledged yet. Defaults to True.	True
copy	bool	Whether to return a deep copy of the orders. Defaults to True.	True
as_dict	bool	Whether to return the orders as dictionaries. Defaults to False.	False

get_bid_orders(ticker, sort=True, include_pending=True, copy=True, as_dict=False, test=False)

Get the bid orders for a specified ticker, sorted with the head of the list being closest to top of the book.

Parameters:

Name	Type	Description	Default
ticker	str	The ticker symbol for which to retrieve bid orders.	required
sort	bool	Whether to sort the orders by price in descending order. Defaults to True.	True
include_pending	bool	Whether to include locally submitted orders that are not exchange-acknowledged yet. Defaults to True.	True
copy	bool	Whether to return a deep copy of the orders. Defaults to True.	True
as_dict	bool	Whether to return the orders as dictionaries. Defaults to False.	False

get_orders(ticker=None, copy=True)

Get the snapshot of alive orders.

get_total_ask_amount(ticker, include_pending=True)

Get the total ask amount for a ticker.

Parameters:

Name	Type	Description	Default
ticker	str	The ticker symbol.	required

get_total_bid_amount(ticker, include_pending=True)

Get the total bid amount for a ticker.

Parameters:

Name	Type	Description	Default
ticker	str	The ticker symbol.	required

oid_query(oid)

Get the order by order id.

Parameters:

Name	Type	Description	Default
oid	str	The order id.	required

pending_asks(ticker)

Get the pending ask orders for a ticker sorted with head of list being closest to top of book

Parameters:

Name	Type	Description	Default
ticker	str	The ticker symbol.	required

pending_bids(ticker)

Get the pending bid orders for a ticker sorted with head of list being closest to top of book

Parameters:

Name	Type	Description	Default
ticker	str	The ticker symbol.	required

upsert_order(clear_unalived=True, trigger_handlers=True, **kwargs) async

Insert or update an order with staleness checking to prevent out-of-order updates.

Parameters:

Name	Type	Description	Default
clear_unalived	bool	Remove dead orders from self.orders after update	True
trigger_handlers	bool	Trigger delta handlers after update	True
**kwargs		Order attributes to upsert	{}

Returns:

Name	Type	Description
Order		The accepted order state, or None if the update was rejected
		or a no-op. The mutation classifier is stored on
		self.last_order_event.

Position

__init__(ticker, amount, entry, **kwargs)

Initialize a Position object.

Parameters:

Name	Type	Description	Default
ticker	str	The ticker symbol.	required
amount	Decimal	The quantity of contracts.	required
entry	Decimal	The entry price.	required

as_dict()

Convert the Position object to a dictionary.

get_amount()

Get the signed size of position held.

get_entry()

Get the entry price.

get_entry_value()

Get the entry value.

Positions

__init__(exc, positions=None, delta_handlers=None, logger=None)

Initialize a Positions object.

Parameters:

Name	Type	Description	Default
exc	str	Venue/container provenance stamped onto emitted deltas.	required
positions	dict	The dictionary of positions. Defaults to None.	None
delta_handlers	list	List of coroutine handlers for position updates. Defaults to None.	None
logger	Logger	Structured logger for trace emission. Defaults to None.	None

add_delta_handler(handler)

Add a handler for position updates.

Parameters:

Name	Type	Description	Default
handler	coroutine	The handler for position updates.	required

add_positions(pos_dict, reset=True)

Add a dictionary of positions.

Parameters:

Name	Type	Description	Default
pos_dict	dict	The dictionary of positions.	required
reset	bool	Whether to reset the current positions. Defaults to True.	True

apply_position_trace(ticker, amount, delta, entry, ts_update_ns, fill_entry=None, ts_exch_ns=None, **kwargs)

Materialize an archived accepted position delta without live OMS side effects.

The recorded delta and timestamps are preserved, no logger record is emitted, and delta handlers are not triggered.

as_dict()

Convert the Positions object to a dictionary.

Returns:

Name	Type	Description
dict		The dictionary of positions.

as_list()

Convert the Positions object to a list.

Returns:

Name	Type	Description
list		The list of positions.

get_ticker_amount(ticker)

Get the signed size of a position.

Parameters:

Name	Type	Description	Default
ticker	str	The ticker symbol.	required

get_ticker_position(ticker)

Get the position object of a ticker.

Parameters:

Name	Type	Description	Default
ticker	str	The ticker symbol.	required

update_position(ticker, amount=None, fill_amount=None, entry=None, fill_entry=None, ts_exch_ns=None, ts_update_ns=None, trigger_handlers=True, **kwargs) async

Update a position and broadcast the change to the delta handlers.

Parameters:

Name	Type	Description	Default
ticker	str	The ticker symbol.	required
amount	Decimal	The new position size. Defaults to None.	None
fill_amount	Decimal	The filled size. Defaults to None.	None
entry	Decimal	The new entry price. Defaults to None.	None
fill_entry	Decimal	The filled entry price. Defaults to None.	None
ts_exch_ns	int	Exchange timestamp for the position-changing event.	None
ts_update_ns	int	Local timestamp for accepting this position delta.	None
trigger_handlers	bool	If False, mutate state silently without firing delta handlers. Defaults to True.	True