Struct Balance 

#[non_exhaustive]
pub struct Balance {
    pub total: Decimal,
    pub free: Decimal,
    pub margin: Option<MarginDetails>,
    pub accrued: Option<Decimal>,
}

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

Construct via Balance::new (cash) or Balance::new_margin (per-asset debt), then Balance::with_accrued where the venue reports an accrual. The struct is #[non_exhaustive], so code outside this crate builds it only through those, and later fields are additive. total is gross holdings and free the freely-tradable portion; the remainder (total - free, exposed by Balance::used) is reserved against resting orders. Producers 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, accrued) (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 (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.

total: Decimal

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

Exception: a venue whose margin is account-level (Alpaca, IBKR) reports only the account’s cash here, which is negative while the account borrows, with margin left None. See the client’s account_snapshot.

A carrying cost (funding, margin interest, a borrow fee) reaches total only once the venue posts it to the account, hourly at some venues and monthly at others. Until then total leaves it out. A venue that reports the pending amount puts it in Balance::accrued, or, for interest on a loan, in MarginDetails::interest. Each client’s rustdoc says what its venue posts and when.

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.

accrued: Option<Decimal>

Carry accrued to date and not yet posted to total: interest earned or charged, and whatever else the venue accrues the same way. Signed: positive is an amount the account will receive, negative one it will pay.

The cash the account holds once the accrual posts is total + accrued. The venue resets the accrual as it posts it, so the two never count the same amount twice. None means the venue does not report one, not that nothing has accrued.

This differs from MarginDetails::interest, which is interest owed on a loan of the asset and is paid out of a later repayment, not added to cash.

It is only as fresh as the last BalanceSnapshot for the asset: a BalanceUpdate carries none, and Balance::apply_stream_update keeps the prior value.

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 const fn with_accrued(self, accrued: Decimal) -> Self

Set Balance::accrued, the carry accrued and not yet posted to total.

pub fn used(&self) -> Decimal

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

pub fn net_asset(&self) -> Decimal

Net asset value: gross holdings less everything owed on the asset’s loan.

Returns total when Balance::margin is None and total - borrowed - interest when Some, as Binance defines its margin accounts’ netAsset. The result can be negative: a short position is a negative net holding in the borrowed (base) asset.

None is a cash / no-debt context, where net asset is simply the gross holding, except on a venue whose margin is account-level (Alpaca, IBKR): there total is already the account’s cash, negative while it borrows (see Balance::total), and the result is that figure, with no loan or interest itemised.

Accrued MarginDetails::interest is owed as the principal is, so it is deducted once the venue reports it accrued, not when it is repaid. Repaying the loan out of the asset’s holdings leaves the result unchanged, since total falls by what the debt does. For the principal alone, read MarginDetails::borrowed.

Balance::accrued is not counted: it is carry the venue posts to total later, not a debt of the loan.

Freshness

The returned value reflects debt only as fresh as the last BalanceSnapshot or MarginDebt for this asset. WS partial updates keep free/locked live but never carry debt, so on a venue that streams no debt changes a position borrowed since the last snapshot reads as zero-debt (net_asset == total) until the next snapshot. Interest is likewise held at its last reported total: it falls in steps as snapshots or debt events report it, not continuously as the venue accrues it. Each venue client says whether it streams debt changes.

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 and Balance::accrued from prior — a partial update carries neither, so this is the single-sourced “debt and accruals fresh as of last snapshot, free/locked live over the stream” merge. On a cold start (prior = None) the result has margin: None and accrued: 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) -> Self

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() -> Self

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: &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 PartialEq for Balance

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

Equality operator ==.

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

Inequality operator !=.

impl PartialOrd for Balance

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 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