Struct Balance 

pub struct Balance {
    pub total: Decimal,
    pub free: Decimal,
    pub margin: Option<MarginDetails>,
}

Per-asset balance: gross holdings, the freely-tradable portion, and optional margin debt.

Construct via Balance::new (cash) or Balance::new_margin (per-asset debt). total is gross holdings and free the freely-tradable portion; the remainder (total - free, exposed by Balance::used) is reserved against resting orders. Callers building the struct literally must keep free <= total.

margin: None denotes a cash / no-debt context, not “unknown debt” — see Balance::margin and Balance::net_asset.

Ord/PartialOrd are derived and compare lexicographically over (total, free, margin) (None sorts before Some); they exist for use as collection keys and generic bounds, not as a financial ranking. Use Balance::net_asset for value comparisons that account for debt.

Fields

total: Decimal

Gross holdings of the asset (free + locked). Unaffected by any borrowing — debt is carried separately in Balance::margin.

free: Decimal

Portion of total available to trade (not reserved against resting orders).

margin: Option<MarginDetails>

Per-asset margin debt, present only for venues that report it (see MarginDetails).

None means a cash / no-debt context — not “unknown debt”. The REST account snapshot always populates this for a margin account, and the WS partial update (BalanceUpdate) structurally cannot clear it, so None reliably denotes “no margin facility for this asset”. See Balance::net_asset.

Implementations

impl Balance

pub const fn new(total: Decimal, free: Decimal) -> Self

Construct a cash Balance with no margin debt (margin: None).

pub const fn new_margin( total: Decimal, free: Decimal, borrowed: Decimal, interest: Decimal, ) -> Self

Construct a margin Balance carrying per-asset borrowed/interest debt.

pub fn used(&self) -> Decimal

Portion of total reserved against resting orders (total - free).

pub fn net_asset(&self) -> Decimal

Net asset value after deducting borrowed principal.

Returns total when Balance::margin is None (a cash / no-debt context, where net asset is simply the gross holding) and total - borrowed when Some. The result can be negative — a short position is a negative net holding in the borrowed (base) asset.

Accrued MarginDetails::interest is intentionally excluded: it is tracked separately and does not reduce net holdings until the venue actually deducts it.

Freshness

The returned value reflects debt only as fresh as the last BalanceSnapshot for this asset. WS partial updates keep free/locked live but never carry debt, so a position borrowed since the last snapshot reads as zero-debt (net_asset == total) until the next snapshot. Consumers needing exact live debt should react to the venue’s borrow/repay event by refreshing the account snapshot.

pub fn apply_stream_update( prior: Option<Balance>, update: &BalanceUpdate, ) -> Balance

Merge a WS partial BalanceUpdate onto an optional prior Balance, preserving debt.

Applies the stream’s live free/locked (recomputing total = free + locked) while carrying forward any MarginDetails from prior — a partial update never carries debt, so this is the single-sourced “debt fresh as of last snapshot, free/locked live over the stream” merge. On a cold start (prior = None) the result has margin: None.

This is the same no-clobber merge the engine applies internally for asset-keyed balances. It is exposed so consumers applying per-instrument InstrumentBalanceUpdate frames — which the engine does not store — can reuse it rather than re-implement the contract.

Trait Implementations

impl Clone for Balance

fn clone(&self) -> Balance

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Balance

impl Debug for Balance

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

Formats the value using the given formatter.

impl Default for Balance

fn default() -> Balance

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Balance

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for Balance

impl Hash for Balance

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 Ord for Balance

fn cmp(&self, other: &Balance) -> 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.

impl PartialEq for Balance

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Balance

fn partial_cmp(&self, other: &Balance) -> 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 Serialize for Balance

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Balance