Trait ExecutionClient 

pub trait ExecutionClient
where
    Self: Clone,
{
    type Config: Clone;
    type AccountStream: Stream<Item = UnindexedAccountEvent> + Send;

    const EXCHANGE: ExchangeId;
    const SUPPORTED_KINDS: &'static [InstrumentKindDiscriminant];

    // Required methods
    fn new(config: Self::Config) -> Self;
    fn account_snapshot(
        &self,
        assets: &[AssetNameExchange],
        instruments: &[InstrumentNameExchange],
    ) -> impl Future<Output = Result<UnindexedAccountSnapshot, UnindexedClientError>> + Send;
    fn account_stream(
        &self,
        assets: &[AssetNameExchange],
        instruments: &[InstrumentNameExchange],
    ) -> impl Future<Output = Result<Self::AccountStream, UnindexedClientError>> + Send;
    fn cancel_order(
        &self,
        request: OrderRequestCancel<ExchangeId, &InstrumentNameExchange>,
    ) -> impl Future<Output = UnindexedOrderResponseCancel> + Send;
    fn open_order(
        &self,
        request: OrderRequestOpen<ExchangeId, &InstrumentNameExchange>,
    ) -> impl Future<Output = Order<ExchangeId, InstrumentNameExchange, UnindexedOrderState>> + Send;
    fn fetch_balances(
        &self,
        assets: &[AssetNameExchange],
    ) -> impl Future<Output = Result<Vec<AssetBalance<AssetNameExchange>>, UnindexedClientError>> + Send;
    fn fetch_open_orders(
        &self,
        instruments: &[InstrumentNameExchange],
    ) -> impl Future<Output = Result<Vec<Order<ExchangeId, InstrumentNameExchange, Open>>, UnindexedClientError>> + Send;
    fn fetch_trades(
        &self,
        start: DateTime<Utc>,
        end: DateTime<Utc>,
        instruments: &[InstrumentNameExchange],
    ) -> impl Future<Output = Result<TradesRead<AssetNameExchange, InstrumentNameExchange>, UnindexedClientError>> + Send;

    // Provided methods
    fn validate_config(
        config: &Self::Config,
        instruments: &[ClientInstrument<'_>],
    ) -> Result<(), String> { ... }
    fn cancel_orders<'a>(
        &self,
        requests: impl IntoIterator<Item = OrderRequestCancel<ExchangeId, &'a InstrumentNameExchange>>,
    ) -> impl Stream<Item = UnindexedOrderResponseCancel> + Send { ... }
    fn open_orders<'a>(
        &self,
        requests: impl IntoIterator<Item = OrderRequestOpen<ExchangeId, &'a InstrumentNameExchange>>,
    ) -> impl Stream<Item = Order<ExchangeId, InstrumentNameExchange, UnindexedOrderState>> + Send { ... }
}

Required Associated Constants

const EXCHANGE: ExchangeId

const SUPPORTED_KINDS: &'static [InstrumentKindDiscriminant]

The InstrumentKindDiscriminants this client can trade.

A client works off InstrumentNameExchange strings and never inspects an instrument’s kind, so nothing downstream can infer this from the implementation — routing a Future through a spot-only venue produces a rejected or, worse, misinterpreted order rather than a type error. Declaring the set here lets ExecutionBuilder reject an unsupported instrument set at build time, before any order is sent.

Declare what the venue and this implementation together can actually route, not what the exchange’s product catalogue advertises. A kind the exchange offers but this client builds no request for does not belong in the set.

There is deliberately no default. A new client must state its capabilities rather than inherit a permissive set that would silently admit every kind.

It is a const and not a fn supported_kinds(&self) because ExecutionBuilder validates the instrument set before Self::new is ever called — there is no instance to ask at the point the answer is needed, and deferring validation until after construction would mean standing up a client for a venue the engine is about to reject. A capability set that varies with Self::Config therefore cannot be expressed here; it would need a separate pre-construction hook on the config.

Required Associated Types

type Config: Clone

type AccountStream: Stream<Item = UnindexedAccountEvent> + Send

Required Methods

fn new(config: Self::Config) -> Self

fn account_snapshot( &self, assets: &[AssetNameExchange], instruments: &[InstrumentNameExchange], ) -> impl Future<Output = Result<UnindexedAccountSnapshot, UnindexedClientError>> + Send

Reads the account’s balances, and its open orders and positions for instruments, from the venue.

Besides startup, the engine’s ExecutionManager calls this again on every account-stream reconnect, and emits the result ahead of the new stream’s updates. It is how the engine catches up on what changed while the stream was down.

Order completeness

Each InstrumentAccountSnapshot states through orders_complete whether its orders list is every order open at the venue for that instrument. Set it only when it is true: the engine retires a tracked order that a complete list omits, so a list that can miss an open order (a capped page, an order dropped on conversion, an order reported under an id other than the one it was placed with) must say false. false is always safe; it only forgoes that reconciliation.

fn account_stream( &self, assets: &[AssetNameExchange], instruments: &[InstrumentNameExchange], ) -> impl Future<Output = Result<Self::AccountStream, UnindexedClientError>> + Send

Returns a live stream of account events (fills, order updates, balance changes).

Startup race window

There is an unavoidable gap between the WebSocket subscribe response and the first event being delivered: fills arriving in this window (typically milliseconds, no sub-millisecond guarantee) are silently dropped. account_snapshot reconciles open-order state, but TRADE fills in this window are not recoverable from the stream alone. Callers that require fill completeness at startup must call ExecutionClient::fetch_trades with at least a 1-second lookback after this method returns.

Backpressure

Implementations use unbounded internal channels. If the consumer cannot keep up, events queue in memory rather than being dropped — per library philosophy, OOM crashes are preferable to silent data loss. Consumers requiring backpressure should implement it at their boundary (e.g., bounded channel with overflow policy).

fn cancel_order( &self, request: OrderRequestCancel<ExchangeId, &InstrumentNameExchange>, ) -> impl Future<Output = UnindexedOrderResponseCancel> + Send

Cancel an order at the venue.

Return value

Every request gets exactly one answer, which the engine’s ExecutionManager forwards as the order’s response. An implementation must not swallow a request: a failure to send it, or to read the venue’s answer, is an Err.

• Ok(Cancelled): the venue took the cancel. Whether the order has ended by then depends on the venue; see below.
• Err: the venue refused the cancel, or it could not be sent or answered. The order may still be open, or may have ended some other way, such as by filling. The account stream reports which.

A taken cancel is not always an ended order

Some venues answer a cancel before carrying it out. Until they do, the order is live and can still fill. From those venues Ok(Cancelled) means only that the cancel was accepted, and the account stream reports how the order actually ended, including any fill in between. The engine stops tracking an order on Ok(Cancelled) from any venue.

Binance, Hyperliquid and the mock venue answer once the order is cancelled. Alpaca answers once it has accepted the cancel, and IBKR once the cancel is submitted. The connector comparison lists the same for each connector; the mock venue is not one, so it has no row there.

filled_quantity and time_exchange

Cancelled::filled_quantity is the quantity the venue reported filled where the answer carries one, which Binance’s and the mock venue’s do. Alpaca, IBKR and Hyperliquid answer without it and report zero, which does not mean nothing filled. The fill total comes from the account stream, or from Self::fetch_trades. Likewise time_exchange is the venue’s time where the answer carries one, and the local time the answer arrived otherwise.

fn open_order( &self, request: OrderRequestOpen<ExchangeId, &InstrumentNameExchange>, ) -> impl Future<Output = Order<ExchangeId, InstrumentNameExchange, UnindexedOrderState>> + Send

Place an order on the exchange.

Return value

Every request gets exactly one answer, which the engine’s ExecutionManager forwards as the order’s response. An implementation must not swallow a request: a failure to send it, or to read the venue’s answer, is OpenFailed.

Returns OrderState directly rather than Result<Open, OrderError>:

• OrderState::Active(Open) - order is resting on the order book
• OrderState::Inactive(FullyFilled) - order was immediately filled (includes avg_price when available)
• OrderState::Inactive(Expired) - order ended in the response itself without filling completely, carrying what filled: an IOC or FOK order that found too little liquidity, or one expired by self-trade prevention
• OrderState::Inactive(Cancelled) - order the venue reports cancelled in the response itself, carrying what filled
• OrderState::Inactive(OpenFailed) - order placement failed (API error, connectivity, a rejection the venue reports in the response, etc.)

An implementation returns Expired or Cancelled only when its venue reports the order’s status in the placement response (currently Binance Spot and Margin). The others return Open for such an order, and their account stream reports how it ended.

This design allows immediate fills to carry metadata (e.g., avg_price) that would be lost if we had to infer terminal state from Open::filled_quantity.

fn fetch_balances( &self, assets: &[AssetNameExchange], ) -> impl Future<Output = Result<Vec<AssetBalance<AssetNameExchange>>, UnindexedClientError>> + Send

Fetch current balances for the specified assets.

An empty assets slice is the “return all” sentinel: implementations must return balances for every asset held. When non-empty, only the listed assets are returned.

fn fetch_open_orders( &self, instruments: &[InstrumentNameExchange], ) -> impl Future<Output = Result<Vec<Order<ExchangeId, InstrumentNameExchange, Open>>, UnindexedClientError>> + Send

Fetch currently open orders, optionally filtered by instrument.

An empty instruments slice is the “return all” sentinel: implementations must return open orders across all instruments. When non-empty, only orders for the listed instruments are returned.

fn fetch_trades( &self, start: DateTime<Utc>, end: DateTime<Utc>, instruments: &[InstrumentNameExchange], ) -> impl Future<Output = Result<TradesRead<AssetNameExchange, InstrumentNameExchange>, UnindexedClientError>> + Send

Read the trades (fills) from start to end, both inclusive, optionally filtered by instrument.

An empty instruments slice is the “return all” sentinel: implementations must return trades across all instruments. When non-empty, only trades for the listed instruments are returned.

Bounded, resumable reads

One call is bounded by the venue’s limits, so it may stop before end. TradesRead::resume says whether it did:

• None: every fill in the span the venue still holds was read.
• Some(t): call again with start = t and the same end to read on. That read can return again fills the previous one returned, so match them by instrument and TradeId.

The caller owns the loop, and with it how many calls, and how long, it spends on a span. A start after end is an empty span, read as no trades and resume: None.

Venue limits

resume: None covers what the venue still holds, which can be less than the span:

• IBKR returns the current trading day’s executions only.
• Hyperliquid keeps only each wallet’s 10,000 most recent fills.

Binance needs instruments: an empty slice reads nothing. Each client documents its limits.

Errors

Truncated when a read cannot advance, because more fills share the span’s first moment than one call can read past.

The fee asset (AssetNameExchange) may be quote, base, or third-party (e.g., BNB). Use fees.fees_quote for quote-equivalent value when available.

Provided Methods

fn validate_config( config: &Self::Config, instruments: &[ClientInstrument<'_>], ) -> Result<(), String>

Checks config against the instruments this client is about to be built to trade, before Self::new is called. Err names what is wrong.

SUPPORTED_KINDS rejects a kind the client cannot route at all. This catches what only the config knows: a per-instrument entry that is invalid, or that disagrees with the instrument it is keyed to, such as a contract registered as a stock for an instrument modelled as an option. Each such entry would otherwise be skipped or acted on silently once the client runs.

The default accepts every config. Override it when Self::Config carries per-instrument detail.

ExecutionBuilder calls it, after checking SUPPORTED_KINDS, with the instruments registered on this client’s exchange. A client constructed by calling new directly is not checked; call this first to get the same check.

fn cancel_orders<'a>( &self, requests: impl IntoIterator<Item = OrderRequestCancel<ExchangeId, &'a InstrumentNameExchange>>, ) -> impl Stream<Item = UnindexedOrderResponseCancel> + Send

fn open_orders<'a>( &self, requests: impl IntoIterator<Item = OrderRequestOpen<ExchangeId, &'a InstrumentNameExchange>>, ) -> impl Stream<Item = Order<ExchangeId, InstrumentNameExchange, UnindexedOrderState>> + Send

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl ExecutionClient for AlpacaClient

const EXCHANGE: ExchangeId = ExchangeId::AlpacaBroker

const SUPPORTED_KINDS: &'static [InstrumentKindDiscriminant]

type Config = AlpacaConfig

type AccountStream = Pin<Box<dyn Stream<Item = AccountEvent<ExchangeId, AssetNameExchange, InstrumentNameExchange>> + Send>>

impl ExecutionClient for BinanceMargin

const EXCHANGE: ExchangeId = ExchangeId::BinanceMargin

const SUPPORTED_KINDS: &'static [InstrumentKindDiscriminant]

type Config = BinanceMarginConfig

type AccountStream = Pin<Box<dyn Stream<Item = AccountEvent<ExchangeId, AssetNameExchange, InstrumentNameExchange>> + Send>>

impl ExecutionClient for BinanceSpot

const EXCHANGE: ExchangeId = ExchangeId::BinanceSpot

const SUPPORTED_KINDS: &'static [InstrumentKindDiscriminant]

type Config = BinanceSpotConfig

type AccountStream = Pin<Box<dyn Stream<Item = AccountEvent<ExchangeId, AssetNameExchange, InstrumentNameExchange>> + Send>>

impl ExecutionClient for HyperliquidClient

const EXCHANGE: ExchangeId = ExchangeId::HyperliquidPerp

const SUPPORTED_KINDS: &'static [InstrumentKindDiscriminant]

type Config = HyperliquidConfig

type AccountStream = Pin<Box<dyn Stream<Item = AccountEvent<ExchangeId, AssetNameExchange, InstrumentNameExchange>> + Send>>

impl ExecutionClient for HyperliquidSpotClient

const EXCHANGE: ExchangeId = ExchangeId::HyperliquidSpot

const SUPPORTED_KINDS: &'static [InstrumentKindDiscriminant]

type Config = HyperliquidConfig

type AccountStream = Pin<Box<dyn Stream<Item = AccountEvent<ExchangeId, AssetNameExchange, InstrumentNameExchange>> + Send>>

impl ExecutionClient for IbkrClient

const EXCHANGE: ExchangeId = ExchangeId::Ibkr

const SUPPORTED_KINDS: &'static [InstrumentKindDiscriminant]

type Config = IbkrConfig

type AccountStream = Pin<Box<dyn Stream<Item = AccountEvent<ExchangeId, AssetNameExchange, InstrumentNameExchange>> + Send>>

impl<FnTime> ExecutionClient for MockExecution<FnTime>

where FnTime: Fn() -> DateTime<Utc> + Clone + Send + Sync,

const EXCHANGE: ExchangeId = ExchangeId::Mock

const SUPPORTED_KINDS: &'static [InstrumentKindDiscriminant]

type Config = MockExecutionClientConfig<FnTime>

type AccountStream = Pin<Box<dyn Stream<Item = AccountEvent<ExchangeId, AssetNameExchange, InstrumentNameExchange>> + Send>>