quantpylib.hft.replay_wrapper

ReplayWrapper implements the wrapper interface consumed by Gateway. It is the client-side transport boundary for deterministic replay.

The wrapper owns:

• native L2, BBA, and trade subscription handlers;
• inbound, outbound latency for different RX/TX paths;
• gateway-compatible execution and query methods; and
• client-side Orders, Fills, and Positions mirrors.

Venue truth remains in ReplayExchange. The authoritative zero-latency truths exist in the exchange through a separate state instance before the delayed private update reaches the local state.

API

quantpylib.hft.replay_wrapper.ReplayWrapper

Implements a simulated exchange through the normal wrapper boundary.

Public subscriptions receive client-route QBN events. REST-style req/ack and private order/fill/position updates have separate inbound/outbound delays.

Parameters:

Name	Type	Description	Default
venue	str	Gateway alias for the simulated venue.	required
runtime	ReplayRuntime	Clock domain and scheduler.	required
exchange	ReplayExchange	Authoritative simulated venue state.	required
order_outbound_latency_ns	int	Client-to-venue order latency.	0
cancel_outbound_latency_ns	int	Client-to-venue cancel latency.	0
response_inbound_latency_ns	int	Venue-to-caller response latency.	0
private_socket_rx_latency	int	Venue-to-mirror private-event latency.	0
live_client	object	Wrapper-compatible metadata client. Initialization loads contract specifications and then closes it.	None

__init__(venue, runtime, exchange, *, order_outbound_latency_ns=0, cancel_outbound_latency_ns=0, response_inbound_latency_ns=0, private_socket_rx_latency=0, live_client=None)

Initialize transport configuration, mirrors, and venue callbacks.

account_fill_subscribe(handler, standardize_schema=1, **kwargs) async

Subscribe to order fill events.

Parameters:

Name	Type	Description	Default
handler	callable	Sync or async fill callback.	required
standardize_schema	int	1 delivers a Fill object; other values deliver its normalized dictionary.	1

account_fill_unsubscribe(**kwargs) async

Unsubscribe to order fill events.

account_fills_get(start_ms=None, end_ms=None, **kwargs) async

Return authoritative fills in a millisecond half-open interval.

Parameters:

Name	Type	Description	Default
start_ms	int	Inclusive exchange-time lower bound.	None
end_ms	int	Exclusive upper bound. Defaults to current replay time.	None

Returns:

Type	Description
	Fills: Unbounded snapshot whose validity watermark equals end_ms converted to nanoseconds.

account_fills_mirror(on_update=None, as_list=True, **kwargs) async

Create or return the client-side fill mirror.

Parameters:

Name	Type	Description	Default
on_update	callable	Awaitable snapshot callback after a newly accepted fill.	None
as_list	bool	Pass a list snapshot instead of the Fills object to on_update.	True
**kwargs		fills_cls_init may configure the container.	{}

Returns:

Type	Description
	Fills: Stateful client fill mirror using the replay clock.

bba_subscribe(ticker, handler, standardize_schema=2, **kwargs) async

Register one native best-bid/ask handler.

Parameters:

Name	Type	Description	Default
ticker	str	Subscription ticker.	required
handler	callable	Sync or async BBAUpdate callback.	required
standardize_schema	int	Must be 2 for native replay events.	2

bba_subscribe_batch(tickers, handlers, standardize_schema=2, **kwargs) async

Register ticker-aligned native BBA handlers as one batch.

Parameters:

Name	Type	Description	Default
tickers	iterable[str]	Subscription tickers.	required
handlers	iterable[callable]	One handler per ticker.	required
standardize_schema	int	Must be 2.	2

bba_unsubscribe(ticker, **kwargs) async

Remove every BBA handler registered for ticker.

Parameters:

Name	Type	Description	Default
ticker	str	Subscription ticker.	required

cancel_open_orders(ticker=None, **kwargs) async

Cancel all open orders, optionally restricted to one ticker.

Parameters:

Name	Type	Description	Default
ticker	str	Ticker filter.	None

Returns:

Type	Description
	list[dict or None]: Authoritative cancellation results.

cancel_order(ticker, oid=None, cloid=None, **kwargs) async

Build and submit one cancellation request.

Parameters:

Name	Type	Description	Default
ticker	str	Venue ticker.	required
oid	str	Exchange order ID.	None
cloid	str	Client order ID fallback.	None

Returns:

Type	Description
	dict or None: Current authoritative order state when found.

cancel_wire(ticker, oid=None, cloid=None, **kwargs) async

Build normalized cancellation specifications.

Parameters:

Name	Type	Description	Default
ticker	str	Venue ticker.	required
oid	str	Exchange order ID.	None
cloid	str	Client order ID fallback.	None

Returns:

Name	Type	Description
dict		Mapping containing cancellation specs.

cancel_wire_submit(cancel_wire, **kwargs) async

Send one cancel wire through outbound and response latency.

Parameters:

Name	Type	Description	Default
cancel_wire	dict	Output from cancel_wire().	required

Returns:

Type	Description
	dict or None: Current authoritative order state when found.

cancel_wires_submit(cancel_wires, **kwargs) async

Submit cancellation wires concurrently on the replay runtime.

Parameters:

Name	Type	Description	Default
cancel_wires	iterable[dict]	Normalized cancellation wires.	required

Returns:

Type	Description
	list[dict or None] or None: Results in input order, or None for
	an empty input.

cleanup() async

Remove public subscriptions and private-stream handlers.

contract_specifications(**kwargs) async

Return a shallow copy of loaded contract specifications.

Returns:

Type	Description
	dict[str, dict]: Contract rules keyed by ticker.

dispatch(replay_event) async

Deliver one QBN event through client public subscriptions.

Parameters:

Name	Type	Description	Default
replay_event	ReplayEvent	Client-route event to fan out.	required

Returns:

Name	Type	Description
int		Number of handlers invoked.

get_lot_precision(ticker, **kwargs)

Return configured quantity precision for ticker.

Parameters:

Name	Type	Description	Default
ticker	str	Venue ticker.	required

Returns:

Name	Type	Description
int		Number of decimal quantity places.

Raises:

Type	Description
KeyError	If metadata for ticker has not been loaded.

get_price_precision(ticker, **kwargs)

Return configured price precision for ticker.

Parameters:

Name	Type	Description	Default
ticker	str	Venue ticker.	required

Returns:

Name	Type	Description
int		Number of decimal price places.

Raises:

Type	Description
KeyError	If metadata for ticker has not been loaded.

init_client() async

Load contract metadata from the optional, live metadata client.

is_subscribed(feed_id)

Return whether feed_id has any client-route handlers.

Parameters:

Name	Type	Description	Default
feed_id	FeedId	Public feed identity.	required

Returns:

Name	Type	Description
bool		Whether at least one handler is registered.

l2_book_subscribe(ticker, handler, standardize_schema=2, **kwargs) async

Register one native L2 book handler.

Parameters:

Name	Type	Description	Default
ticker	str	Subscription ticker.	required
handler	callable	Sync or async BookUpdate callback.	required
standardize_schema	int	Must be 2 for native replay events.	2

l2_book_subscribe_batch(tickers, handlers, standardize_schema=2, **kwargs) async

Register ticker-aligned native L2 handlers as one batch.

Parameters:

Name	Type	Description	Default
tickers	iterable[str]	Subscription tickers.	required
handlers	iterable[callable]	One handler per ticker.	required
standardize_schema	int	Must be 2.	2

l2_book_subscriptions()

Return tickers with at least one registered L2 handler.

Returns:

Type	Description
	set[str]: Active L2 subscription tickers.

l2_book_unsubscribe(ticker, **kwargs) async

Remove every L2 handler registered for ticker.

Parameters:

Name	Type	Description	Default
ticker	str	Subscription ticker.	required

limit_order(ticker, amount, **kwargs) async

Build and submit one normalized limit order.

Parameters:

Name	Type	Description	Default
ticker	str	Venue ticker.	required
amount	Decimal	Signed base quantity; positive buys and negative sells.	required
**kwargs		Additional order_wire() fields.	{}

Returns:

Name	Type	Description
dict		Authoritative response after request/response latency.

order_query(oid=None, cloid=None, **kwargs) async

Query exchange for order history by order ID or client ID.

Parameters:

Name	Type	Description	Default
oid	str	Exchange order ID, preferred when supplied.	None
cloid	str	Client order ID fallback.	None

Returns:

Type	Description
	dict or None: Copied authoritative order state when found.

order_updates_subscribe(handler, **kwargs) async

Subscribe to private order updates.

Parameters:

Name	Type	Description	Default
handler	callable	Sync or async normalized order callback.	required

order_updates_unsubscribe(**kwargs) async

Unsubscribe to private order updates.

order_wire(ticker, amount, price=None, price_rule=None, tif=markets.TIME_IN_FORCE_GTC, reduce_only=False, cloid=None, **kwargs) async

Build the normalized wire representation for a limit order.

Parameters:

Name	Type	Description	Default
ticker	str	Venue ticker.	required
amount	Decimal	Signed base quantity.	required
price	Decimal	Limit price.	None
price_rule	str	Exchange-side price derivation rule.	None
tif	str	Normalized time in force.	TIME_IN_FORCE_GTC
reduce_only	bool	Whether execution may only reduce exposure.	False
cloid	str	Client order ID.	None

Returns:

Name	Type	Description
dict		Mapping containing normalized order specs.

order_wire_submit(order_wire, **kwargs) async

Send one order wire through outbound and response latency.

Parameters:

Name	Type	Description	Default
order_wire	dict	Output from order_wire().	required

Returns:

Name	Type	Description
dict		Authoritative exchange order state.

order_wires_submit(order_wires, **kwargs) async

Submit order wires concurrently on the replay runtime.

Parameters:

Name	Type	Description	Default
order_wires	iterable[dict]	Normalized order wires.	required

Returns:

Type	Description
	list[dict] or None: Responses in input order, or None for an
	empty input.

orders_get(**kwargs) async

Return an authoritative snapshot of open venue orders.

Returns:

Type	Description
	dict[str, dict]: Open orders keyed by exchange order ID.

orders_mirror(on_update=None, as_list=True, **kwargs) async

Keeps a live, in memory local mirror copy of the account open orders.

Parameters:

Name	Type	Description	Default
on_update	callable	Awaitable snapshot callback after each accepted private order update.	None
as_list	bool	Pass a list snapshot instead of the Orders object to on_update.	True
**kwargs		orders_cls_init may configure the container.	{}

Returns:

Type	Description
	Orders: Stateful client order mirror using the replay clock.

orders_peek(as_dict=True, **kwargs)

Read the initialized client order mirror without I/O.

Parameters:

Name	Type	Description	Default
as_dict	bool	Return normalized dictionary state instead of the Orders container.	True

Returns:

Type	Description
	dict or Orders: Current client-mirror state.

positions_get(**kwargs) async

Return an snapshot of current non-zero positions.

Returns:

Type	Description
	dict[str, dict]: Positions keyed by ticker.

positions_mirror(on_update=None, as_dict=True, **kwargs) async

Keeps a live, in memory local mirror copy of the account open positions.

Parameters:

Name	Type	Description	Default
on_update	callable	Awaitable snapshot callback after each private position mutation.	None
as_dict	bool	Pass dictionary snapshots to on_update. When true, preserve the gateway convention of returning None; when false, return the Positions object.	True
**kwargs		positions_cls_init may configure the container.	{}

Returns:

Type	Description
	Positions or None: Mirror object when as_dict=False.

positions_peek(as_dict=True, **kwargs)

Read the initialized client position mirror without I/O.

Parameters:

Name	Type	Description	Default
as_dict	bool	Return normalized dictionary state instead of the Positions container.	True

Returns:

Type	Description
	dict or Positions: Current client-mirror state.

rand_cloid(start='', end='', **kwargs)

Return a deterministic process-local replay client order ID.

Parameters:

Name	Type	Description	Default
start	str	Optional prefix.	''
end	str	Optional suffix.	''

Returns:

Name	Type	Description
str		Monotonically numbered client order ID.

subscriptions()

Return an immutable snapshot of all public subscription handlers.

Returns:

Type	Description
	dict[tuple[str, str], tuple[callable, ...]]: Handlers keyed by
	(feed_type, ticker).

trades_subscribe(ticker, handler, standardize_schema=2, **kwargs) async

Register one native public-trade handler.

Parameters:

Name	Type	Description	Default
ticker	str	Subscription ticker.	required
handler	callable	Sync or async TradeUpdate callback.	required
standardize_schema	int	Must be 2 for native replay events.	2

trades_subscribe_batch(tickers, handlers, standardize_schema=2, **kwargs) async

Register ticker-aligned native trade handlers as one batch.

Parameters:

Name	Type	Description	Default
tickers	iterable[str]	Subscription tickers.	required
handlers	iterable[callable]	One handler per ticker.	required
standardize_schema	int	Must be 2.	2

trades_unsubscribe(ticker, **kwargs) async

Remove every public-trade handler registered for ticker.

Parameters:

Name	Type	Description	Default
ticker	str	Subscription ticker.	required