Struct Trade 

#[non_exhaustive]
pub struct Trade<AssetKey, InstrumentKey> {

    pub id: TradeId,
    pub order_id: OrderId,
    pub instrument: InstrumentKey,
    pub strategy: StrategyId,
    pub time_exchange: DateTime<Utc>,
    pub side: Side,
    pub price: Decimal,
    pub quantity: Decimal,
    pub order_filled_quantity: Option<Decimal>,
    pub fees: AssetFees<AssetKey>,
    pub origin: TradeOrigin,
    pub position_side: Option<Side>,
    pub client_order_id: Option<ClientOrderId>,
    pub time_source: TimeSource,
}

One execution: a fill the venue reported, or one the engine settled itself.

#[non_exhaustive], so a field can be added without breaking a caller. Outside this crate, build one with Trade::new and the with_* methods, and change a copy by assigning its public fields.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

id: TradeId

order_id: OrderId

instrument: InstrumentKey

strategy: StrategyId

time_exchange: DateTime<Utc>

When the fill happened, as the venue stamped it, unless time_source says this host’s clock filled it in.

side: Side

price: Decimal

quantity: Decimal

The size of this execution.

order_filled_quantity: Option<Decimal>

The order’s cumulative filled quantity as of this execution, as the venue reported it – not the size of this execution, which is Trade::quantity.

A fill carries two facts: that an execution happened, and what it left the order at. A consumer that tracks order state needs both, and they arrive together or not at all. Where the venue supplies the second, carrying it here lets the order be advanced from the fill itself rather than from a separate message that may never come.

Advancing from a cumulative is idempotent: re-applying the same fill, or applying two out of order, cannot double-count, because the receiver takes the greater of what it holds and what is reported rather than adding to a running total.

None means the venue’s fill payload does not carry it, and the order’s state must be learned some other way – an order snapshot, or a reconciliation fetch. It is not a claim that nothing is filled. Known producers, as of writing:

Source	Reports it
Binance Spot / Margin WebSocket executionReport	yes (z)
Binance Spot / Margin fill recovery after a disconnect	yes, rebuilt from the order’s executions; None where that lookup failed or ran out of time
Binance Spot / Margin fetch_trades (myTrades REST)	no
Alpaca WebSocket trade_updates	yes (order.filled_qty)
Alpaca account-activities REST	yes (cum_qty)
Interactive Brokers ExecutionData	yes (cumulative_quantity)
Hyperliquid userFills	no
SimulatedVenue	yes

#[serde(default)] so trades serialised before this field existed still deserialise, as None.

fees: AssetFees<AssetKey>

origin: TradeOrigin

Why the fill happened, as far as its producer can tell. See TradeOrigin for what each venue reports.

#[serde(default)] so trades serialised before this field existed still deserialise, as TradeOrigin::Order.

position_side: Option<Side>

The side of the position the fill applies to, when the venue names one: Side::Buy for a long, Side::Sell for a short.

A venue in hedge mode, holding a long and a short in one instrument at once, names the position each fill belongs to (Binance USD-M futures’ LONG and SHORT). The engine in OmsMode::Hedging checks a forced fill, which matches none of its orders, against it: a forced fill must reduce the position the venue names. It only ever confirms the side a reducing fill already implies, the side opposite its own, and does not choose among several of the engine’s positions on that side.

It takes part in the derived Eq, Hash and Ord, as every field does: deduplicate fills by instrument and id, not by the whole Trade. None when the venue names none, as every client in this crate does as of writing: none trades a venue in hedge mode.

#[serde(default)] so trades serialised before this field existed still deserialise, as None.

client_order_id: Option<ClientOrderId>

The client order id of the order this fill belongs to, as the venue reported it with the fill.

The id is chosen before the order is sent, so a consumer can attribute a fill by it at once. That includes a fill of an order placed outside the engine on the same account, which no order the engine knows matches: order_id is the venue’s, and the fill can arrive before the venue’s response to the order names it, or long after, in a recovery read. A consumer that trades an account outside the engine can mark those orders’ client order ids, by a prefix say, and keep their fills from the engine.

None means the fill’s payload did not carry one. It is not a claim that the order has none. Known producers, as of writing:

Source	Reports it
Binance Spot / Margin WebSocket executionReport	yes (c)
Binance Spot / Margin fill recovery after a disconnect	yes, read from each recovered fill’s order; None where that lookup failed or ran out of time
Binance Spot / Margin fetch_trades (myTrades REST)	no
Alpaca WebSocket trade_updates	yes (order.client_order_id)
Alpaca account-activities REST (fill recovery, fetch_trades), fetch_option_events	no
Interactive Brokers executions	yes, the order reference, which this crate’s client sets to the client order id; None for an order without one
Hyperliquid userFills	yes, the client order id the order’s cloid maps to; None for an order placed without a cloid
SimulatedVenue	yes
The rustrade engine’s expiry settlement	no

#[serde(default)] so trades serialised before this field existed still deserialise, as None.

time_source: TimeSource

Whose clock time_exchange was read from. See TimeSource for when a producer fills in this host’s.

#[serde(default)] so trades serialised before this field existed still deserialise, as TimeSource::Venue.

Implementations

impl<AssetKey, InstrumentKey> Trade<AssetKey, InstrumentKey>

pub fn new( id: TradeId, order_id: OrderId, instrument: InstrumentKey, strategy: StrategyId, time_exchange: DateTime<Utc>, side: Side, price: Decimal, quantity: Decimal, order_filled_quantity: Option<Decimal>, fees: AssetFees<AssetKey>, ) -> Self

A trade of TradeOrigin::Order. Set another origin with with_origin.

pub fn with_origin(self, origin: TradeOrigin) -> Self

This trade with its origin set.

pub fn with_position_side(self, position_side: Side) -> Self

This trade with the position_side the venue named.

pub fn with_client_order_id(self, client_order_id: ClientOrderId) -> Self

This trade with the client_order_id the venue reported.

pub fn with_time_source(self, time_source: TimeSource) -> Self

This trade with its time_source set.

pub fn value_quote(&self) -> Decimal

pub fn holding_move<ExchangeKey>( &self, instrument: &Instrument<ExchangeKey, AssetKey>, held: Decimal, reduce_only: ReduceOnly, ) -> Option<HoldingMove>

where AssetKey: PartialEq,

How this fill moves the position it applies to, when that is not by its own side and quantity: a spot fill whose fee the venue charged in instrument’s base asset, or a reduce_only fill that would grow or flip the position. None otherwise: the fill then moves the position by its own side and quantity.

The rustrade engine applies every fill with this function. A component that mirrors positions outside the engine, such as a ledger of the fills an execution client forwarded, agrees with the engine by calling it too.

held is the position the fill applies to, as it stands before the fill, signed: positive for a long, negative for a short, zero for none. In an account holding a long and a short at once, it is the one position the fill is routed to. reduce_only is what the fill’s order was sent as, its RequestOpen::reduce_only. Both reduce-only values move the position alike: they differ only in how the engine books the excess (see ReduceOnly).

The rule

In this order:

• The fee is netted. It leaves the account in base on either side, so the holding moves by the fill’s signed quantity less the fee: a buy of q with a base fee f holds q − f, and a sell delivers q + f. A negative fee, a rebate, adds to it. Only on a spot instrument, spot margin included. A derivative’s position is counted in contracts, and an inverse contract pays its fees in the settlement coin, so a fee there never changes the quantity. A fee in quote or a third asset, such as BNB, and a fee of zero are not netted.
• A reduce-only move never grows or flips the position. When ReduceOnly::is_reduce_only, a netted move larger than the opposite position held is cut to land it flat, and one that does not reduce it at all, because held is zero or on the move’s side, moves nothing. What is cut off is HoldingMove::excess. A cut move is not rounded below: flat is on any step, and a position the fill left as it was is not the fill’s to round. This applies to any instrument kind.
• The position is rounded toward zero to the step. Only when the fee was netted and the move not cut. When Instrument::quantity_step gives a step, the position the fill leaves, held plus the netted move, is rounded toward zero to a whole multiple of it, and the move is what lands the position there. A venue sells only whole steps, so a position off the step could never be closed to flat. It is the position that is rounded, not the move: a sell of 1 with a fee of 0.001 from a long of 2, in steps of 0.01, leaves 0.999, so the position is 0.99 and the move a sell of 1.01. What is rounded off is HoldingMove::dust. A held already off the step is rounded too, so the dust can include a remainder this fill did not create. Without a step, the dust is zero.
• The move’s side is its sign. A fee larger than a buy’s quantity sells the difference. A move of zero keeps the netted move’s side, which is the fill’s own unless the fee reversed it, with a quantity of zero.

What it leaves to the caller

• The price and the fee. The netted quantity keeps the fill’s price, so PnL is charged the fee’s quote equivalent, its fees_quote: buying q − f at p and paying f × p costs q × p, what the fill paid. The engine charges nothing for the dust: it is held, a long’s as base the account holds and a short’s as base still owed on the loan, and the position books neither it nor the quote it cost. So the position agrees with the account at the fill’s price, and the dust’s value moves with the price outside it.
• Only the fee the venue reported is netted. A fee the caller computes itself, as the engine’s fee model does, is in quote, and reaches PnL alone.
• The excess and its share of the fee. No position takes the excess: the account holds it, or the venue spent it, as on a margin repayment sized to cover interest, or it was free base the order was sized to trade, under ReduceOnly::PositionAndFreeBase. The engine charges the position the share of the fill’s fees that the move is of the netted move, and the rest to its tear sheet as fees no position carries. It reports the excess without charging its value to PnL.
• A settlement fill larger than its position, in a hedged account. Where an account can hold a long and a short at once (the engine’s OmsMode::Hedging), the engine does not call this for a settlement fill, such as a liquidation, that matches none of its orders and is larger than the position it reduces: it cuts that fill to the position, unnetted, so the position lands flat, and reports the excess. A mirror that matches the engine does the same rather than calling this. Such a fill is of no order of the engine’s, so it is never reduce-only. With one position per instrument (OmsMode::Netting), the engine never cuts a settlement fill, so this applies to every fill.

Trait Implementations

impl<AssetKey: Clone, InstrumentKey: Clone> Clone for Trade<AssetKey, InstrumentKey>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<AssetKey: Debug, InstrumentKey: Debug> Debug for Trade<AssetKey, InstrumentKey>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de, AssetKey, InstrumentKey> Deserialize<'de> for Trade<AssetKey, InstrumentKey>

where AssetKey: Deserialize<'de>, InstrumentKey: Deserialize<'de>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<AssetKey, InstrumentKey> Display for Trade<AssetKey, InstrumentKey>

where AssetKey: Display, InstrumentKey: Display,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<AssetKey: Eq, InstrumentKey: Eq> Eq for Trade<AssetKey, InstrumentKey>

impl<ExchangeKey, AssetKey, InstrumentKey> From<Trade<AssetKey, InstrumentKey>> for AccountEventKind<ExchangeKey, AssetKey, InstrumentKey>

fn from(value: Trade<AssetKey, InstrumentKey>) -> Self

Converts to this type from the input type.

impl<AssetKey: Hash, InstrumentKey: Hash> Hash for Trade<AssetKey, InstrumentKey>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<AssetKey: Ord, InstrumentKey: Ord> Ord for Trade<AssetKey, InstrumentKey>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl<AssetKey: PartialEq, InstrumentKey: PartialEq> PartialEq for Trade<AssetKey, InstrumentKey>

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<AssetKey: PartialOrd, InstrumentKey: PartialOrd> PartialOrd for Trade<AssetKey, InstrumentKey>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<AssetKey, InstrumentKey> Serialize for Trade<AssetKey, InstrumentKey>

where AssetKey: Serialize, InstrumentKey: Serialize,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<AssetKey: PartialEq, InstrumentKey: PartialEq> StructuralPartialEq for Trade<AssetKey, InstrumentKey>