Struct SpotMarginConfig 

pub struct SpotMarginConfig(/* private fields */);

Spot margin on the simulated venue: what it lends a spot order, how much, and what it repays.

Off by default: MockExecutionConfig::spot_margin is None, and the venue is a cash account whose spot orders must be paid for with what it holds. With a configuration, it is a cross margin account, with one pool of balances shared by every instrument, which lends a spot order what it lacks and reports each balance’s loan as Binance’s margin account does.

What it lends, and when

Each spot order has a MarginEffect: its request’s margin_effect, else this configuration’s margin_effect. An order with MarginEffect::Borrow that the account cannot pay for with its free balance borrows the shortfall of the asset it pays with (base for a sell, quote for a buy), or that asset’s min_borrow if it is more, as Binance does. It borrows when the venue accepts the order, as Binance does, so a resting limit order or a held market order is lent its shortfall at once, and the venue holds it against the order as it holds any other balance. What a minimum borrow lends beyond the shortfall is not held: it is free balance, owed. An asset the account has never held is opened with the loan.

An order that is cancelled, expires or is refused at its fill before it fills repays what it borrowed, interest first, and a held market order that fills for less than was held repays the part of its loan it no longer needs, if auto_repay_at_cancel is on (the default, as on Binance). One that fills in part and rests the remainder pays for the part that filled with the account’s own balance first, so the loan is held against the remainder and repaid if the remainder is cancelled. What a minimum borrow lent beyond the shortfall is repaid with the rest if the order ends before it fills in full, and stays owed once it does.

An order with MarginEffect::NoSideEffect or MarginEffect::Repay lends nothing: one it cannot pay for is rejected as on a cash account. A loan already in the venue’s initial state is left as it is, and balances still report their loans.

Only spot orders borrow. A CFD’s margin is posted from the quote asset’s free balance, as without this configuration, and a CFD order carrying MarginEffect::Borrow or MarginEffect::Repay is refused with OrderError::UnsupportedMarginEffect.

How much it lends

A borrow is allowed while the account’s debt, after it, is at most max_leverage − 1 times the account’s equity. Both are valued in valuation_asset:

• Each asset is valued at the mid of an instrument on the venue that pairs it with the valuation asset, else that market’s last price, in either direction (BTC/USDT, or the inverse of USDT/BTC). The valuation asset is worth one. A market priced at zero values nothing. A borrow price window values each asset over a recent window of that price instead: see # Borrow price window.
• Equity is the sum over assets of total − borrowed − interest, valued that way, where an asset whose net is positive counts at its borrow_collateral_ratio: see # Collateral ratios. An asset the venue cannot value counts as no equity, which understates what the account can borrow rather than overstating it.
• Debt is the sum over assets of borrowed + interest, valued the same way. The venue lends nothing while it cannot value a debt, and never lends an asset it cannot value.

An asset given a max_borrow is lent no more than that cap allows as well: what the account already owes of it, principal plus interest, plus the new loan, is at most the cap. Both limits apply, and the tighter one decides.

An order that needs more than the leverage limit allows is rejected as unaffordable, with a reason that says how much the venue would lend. So is one whose asset’s min_borrow is more than that, since the venue never lends less than the minimum, and its reason names the minimum too. One that needs more than an asset’s cap allows, where the cap is the tighter limit, is rejected with ApiError::BorrowRejected instead: see with_max_borrow. A max_leverage of one lends nothing, but still reports each balance’s loan.

It lends nothing while a liquidation is under way: see SpotMarginLiquidation.

Collateral ratios

An asset can count for less than its full value as collateral, as Binance’s cross margin weights each asset by a collateral ratio. Each asset has two, both one by default:

• a borrow_collateral_ratio, which the leverage limit above uses, and so what the venue lends;
• a liquidation_collateral_ratio, which the margin level a SpotMarginLiquidation checks uses.

A ratio applies only to the part of an asset the account holds beyond what it owes of it, its positive net: ratio × (total − borrowed − interest). What it holds up to what it owes counts in full, and so do the holdings of an asset it owes more of than it holds. So an account that holds 2 BTC and owes 1, at a ratio of 0.95, counts the first BTC in full and the second at 0.95. Debt is never weighted. A ratio of zero counts the asset for nothing beyond its debt.

In margin-level terms, the account’s collateral is its debt plus its weighted equity, and the margin level is collateral over debt, as Binance defines it: a borrow is allowed while that level, with borrow ratios, stays at or above max_leverage / (max_leverage − 1).

An asset’s liquidation ratio may not be below its borrow ratio, so that the borrow ratios are the stricter ones, as on Binance. That keeps a borrow the leverage limit allows from leaving the account at its liquidation level.

Borrow price window

Off by default: the leverage limit values each asset at its current price, as the liquidation check does. Binance’s borrow check is stricter. It values each asset over a recent window of its price, at the highest for an asset the account owes and the lowest for every other, so a price that just jumped lends no more at once, and one that just fell lends less at once. Set with with_borrow_price_window, the leverage limit does the same over the window given:

• Each market observation the venue is fed adds its price to the window of that instrument: the mid, else the last price, at which the venue values the instrument, and the high and low of a bar the observation carries. The current price always counts.
• What counts is what was observed in the window up to the latest instant the venue’s clock has reached, from that instant less the window, inclusive.
• An asset the account owes is valued at its highest price in the window, for every unit it holds as well as for its debt. So is the asset being borrowed, since the loan makes it one the account owes: an order’s or a borrow_capacity query’s. Every other asset is valued at its lowest. The valuation asset is worth one.
• The venue lends the lesser of what the leverage limit allows at those prices and at the current ones. The window can only make the venue lend less. Valuing an asset the account owes at its highest raises the value of its holdings as well as its debt, so on its own it could lend more than the current prices would, and leave the account at its liquidation level the moment it borrowed.

The venue keeps, per spot instrument, every observed price that could still be the window’s lowest or highest: in a market that only rises or only falls, every observation inside the window, so a long window over a fast feed holds that many.

The window changes only how much the venue lends: the margin level a SpotMarginLiquidation checks, and any interest, are valued at current prices. A venue no driver feeds the market, one priced by each request’s own snapshot, has no window to look back on, and lends as if there were none.

What it repays

Under MarginEffect::Repay, whatever a fill delivers into an asset the account owes repays that asset’s loan, interest first, then principal, and only the rest becomes free balance. What a buy delivers is its quantity less any fee charged in base, so a buy of exactly what is owed, with a base fee, leaves a fee-sized loan. Gross the buy up by the fee to clear it. Under the other two effects a fill repays nothing: as on Binance, a repay is per order, and nothing repays a loan automatically.

Liquidation

Off by default: an account whose debt grows past its equity keeps trading, and nothing closes its positions. Configured with with_liquidation, the venue repays every debt once the account’s margin level falls to the configured level, selling what the account holds as needed. See SpotMarginLiquidation.

What it does not model

• Isolated margin. One pool of balances backs every instrument.
• Tiered collateral ratios. An asset has one ratio per check, whatever the size of its holding. Binance publishes each ratio in progressive tiers by the holding’s value in USD: each slice of the value is weighted at its own tier’s ratio. An asset with a single tier, as every asset had on 2026-11-04, is modelled exactly.
• Index prices. Every check values an asset at a market’s own mid or last price, where Binance values at an index over several venues. The borrow price window above stands in for the window Binance takes over that index.
• The venue’s lending pool. The venue has whatever it lends: no shared pool runs short, as one can on a real venue whatever the account’s own limits allow.
• Interest, by this configuration alone. A venue given a MarginInterestModel charges it; see that trait.

new refuses a max_leverage below one, with_min_borrow a negative minimum, with_max_borrow a negative cap, the collateral ratio builders a ratio outside [0, 1] or a liquidation ratio below the borrow ratio, with_borrow_price_window a window that is not a positive whole number of milliseconds, with_liquidation a liquidation the leverage limit could reach, and so does deserialising any of them, so a configuration that exists is one the venue can apply. Serialised, max_leverage, each minimum borrow, each cap and each ratio are decimal strings ("3"), as the crate writes decimals elsewhere, so no precision is lost to a float. min_borrow, max_borrow, borrow_collateral_ratio and liquidation_collateral_ratio are maps from asset to amount, each left out when empty. borrow_price_window_ms is the window in whole milliseconds, an integer, and liquidation is left out when off, as is the window.

Implementations

impl SpotMarginConfig

pub fn new( valuation_asset: AssetNameExchange, max_leverage: Decimal, margin_effect: MarginEffect, ) -> Result<Self, SpotMarginConfigError>

Spot margin applying margin_effect to each order that does not carry its own, up to max_leverage over the account’s equity, valued in valuation_asset.

The effect has no default, so that a configuration says whether the venue may take on debt for an order. Unused loans are repaid when their order ends unfilled; see with_auto_repay_at_cancel.

Errors

Returns SpotMarginConfigError if max_leverage is below one.

pub fn with_auto_repay_at_cancel(self, auto_repay_at_cancel: bool) -> Self

This configuration, repaying a loan its order no longer needs (the order was cancelled, expired or refused at its fill, or a held market order filled for less than was held) when auto_repay_at_cancel is true, and leaving it owed when false.

On by default, as Binance’s autoRepayAtCancel is. With it off, an unused loan stays owed until a MarginEffect::Repay order repays it.

pub fn valuation_asset(&self) -> &AssetNameExchange

The asset equity and debt are valued in.

pub fn max_leverage(&self) -> Decimal

The most the account may hold, as a multiple of its equity: its debt may reach max_leverage − 1 times its equity.

pub fn margin_effect(&self) -> MarginEffect

The effect of an order whose request carries none.

pub fn auto_repay_at_cancel(&self) -> bool

Whether a loan its order no longer needs is repaid. See with_auto_repay_at_cancel.

pub fn with_min_borrow( self, asset: AssetNameExchange, min_borrow: Decimal, ) -> Result<Self, SpotMarginConfigError>

This configuration, never lending less than min_borrow of asset: a loan of asset below it is raised to it, as Binance raises a MARGIN_BUY loan to the asset’s userMinBorrow. A minimum of zero removes it. Replaces any minimum asset had.

No asset has one by default, so each loan is exactly its order’s shortfall. An order its free balance covers borrows nothing, whatever the minimum.

Errors

Returns SpotMarginConfigError::NegativeMinBorrow if min_borrow is negative.

pub fn min_borrow(&self, asset: &AssetNameExchange) -> Decimal

The least the venue lends of asset in one loan, zero if it has no minimum. See with_min_borrow.

pub fn with_max_borrow( self, asset: AssetNameExchange, max_borrow: Decimal, ) -> Result<Self, SpotMarginConfigError>

This configuration, lending asset only while what the account owes of it, principal plus interest, and the new loan come to at most max_borrow: a fixed cap on the account’s debt in asset, as Binance caps what a margin account may borrow of each asset (maxBorrowable’s borrowLimit). Replaces any cap asset had.

No asset has one by default, so only the leverage limit bounds a loan. A cap of zero lends none of asset. Nor is asset lent once what the cap leaves is below its min_borrow, since the venue never lends less than the minimum.

How the cap counts

A borrow is allowed while what the account already owes of asset, loan plus interest, plus the new loan is at most the cap. Interest the new loan is charged when it is made is not counted, as the leverage limit does not count it, so it can take the debt just past the cap. Counting interest is this venue’s rule: Binance does not document whether its limit counts it.

The cap is the account’s own limit, not the venue’s supply: Binance can also refuse a borrow its limit allows because it has too little of the asset to lend, which this venue does not model.

The mock client reports the cap as BorrowCapacity::account_limit, from BorrowCapacityClient::fetch_borrow_capacity.

Rejection

An order that would borrow past the cap is rejected, never lent less than it needs. Where the cap allows less than the leverage limit, the rejection is ApiError::BorrowRejected with reason BorrowLimitExceeded, as a live Binance margin client reports Binance’s -3006. Its message names the cap, and for a sell its available is how much more of the base asset the venue would lend: zero when that is below the minimum borrow. A buy borrows the quote asset, in units other than the order’s, so it leaves available unset. Where the leverage limit is the tighter, the order is rejected as unaffordable, as without a cap.

Errors

Returns SpotMarginConfigError::NegativeMaxBorrow if max_borrow is negative.

pub fn max_borrow(&self, asset: &AssetNameExchange) -> Option<Decimal>

The most the account may owe of asset, principal plus interest, or None if it has no cap. See with_max_borrow.

pub fn with_borrow_collateral_ratio( self, asset: AssetNameExchange, ratio: Decimal, ) -> Result<Self, SpotMarginConfigError>

This configuration, counting ratio of what the account holds of asset beyond what it owes of it as equity when the venue decides how much it lends: the asset’s borrow collateral ratio, as Binance’s Margin Data page lists one per asset. Replaces any borrow ratio asset had. See SpotMarginConfig’s # Collateral ratios.

Every asset’s is one by default. A ratio of one removes it.

Errors

SpotMarginConfigError::CollateralRatioOutOfRange if ratio is outside [0, 1], and SpotMarginConfigError::LiquidationRatioBelowBorrowRatio if it is above asset’s liquidation_collateral_ratio.

pub fn borrow_collateral_ratio(&self, asset: &AssetNameExchange) -> Decimal

The fraction of what the account holds of asset beyond what it owes of it that counts as equity when the venue decides how much it lends, one if it has none. See with_borrow_collateral_ratio.

pub fn with_liquidation_collateral_ratio( self, asset: AssetNameExchange, ratio: Decimal, ) -> Result<Self, SpotMarginConfigError>

This configuration, counting ratio of what the account holds of asset beyond what it owes of it as equity in the margin level a SpotMarginLiquidation checks: the asset’s liquidation collateral ratio, as Binance’s Margin Data page lists one per asset. Replaces any liquidation ratio asset had. See SpotMarginConfig’s # Collateral ratios.

Every asset’s is one by default. A ratio of one removes it. It has no effect without a liquidation.

Errors

SpotMarginConfigError::CollateralRatioOutOfRange if ratio is outside [0, 1], and SpotMarginConfigError::LiquidationRatioBelowBorrowRatio if it is below asset’s borrow_collateral_ratio. To set a liquidation ratio below the asset’s current borrow ratio, lower the borrow ratio first, or set both at once with with_collateral_ratios.

pub fn liquidation_collateral_ratio(&self, asset: &AssetNameExchange) -> Decimal

The fraction of what the account holds of asset beyond what it owes of it that counts as equity in the margin level a liquidation checks, one if it has none. See with_liquidation_collateral_ratio.

pub fn with_collateral_ratios( self, asset: AssetNameExchange, borrow: Decimal, liquidation: Decimal, ) -> Result<Self, SpotMarginConfigError>

This configuration, with asset’s borrow_collateral_ratio and liquidation_collateral_ratio both replaced, checked together once both are set.

Setting the two one after the other checks the pair after each step, against the other ratio’s old value, so it can refuse a pair that is valid as a whole: raising a 0.5 borrow ratio and a 0.6 liquidation ratio to 0.8 and 0.9 fails if the borrow ratio goes first, and lowering them back fails the other way round. This setter does not depend on the order.

A ratio of one removes it, as either setter does.

Errors

SpotMarginConfigError::CollateralRatioOutOfRange if either ratio is outside [0, 1], and SpotMarginConfigError::LiquidationRatioBelowBorrowRatio if liquidation is below borrow.

pub fn with_borrow_price_window( self, window: TimeDelta, ) -> Result<Self, SpotMarginConfigError>

This configuration, valuing each asset over the trailing window of its price when the venue decides how much it lends. Replaces any window it had. See SpotMarginConfig’s # Borrow price window.

Off by default, when each asset is valued at its current price.

Errors

SpotMarginConfigError::BorrowPriceWindowInvalid if window is not a positive whole number of milliseconds, the unit it is serialised in.

pub fn borrow_price_window(&self) -> Option<TimeDelta>

How far back the venue looks at each asset’s price when it decides how much it lends, or None if it values each at its current price. See with_borrow_price_window.

pub fn with_liquidation( self, liquidation: SpotMarginLiquidation, ) -> Result<Self, SpotMarginConfigError>

This configuration, liquidating the account as liquidation says. Replaces any liquidation it had.

Errors

Returns SpotMarginConfigError::LiquidationWithinLeverage if a borrow the leverage limit allows could leave the account at the liquidation level: if max_leverage is above one and the level is at least max_leverage / (max_leverage − 1), the margin level of an account borrowed to the limit.

pub fn liquidation(&self) -> Option<SpotMarginLiquidation>

When the venue liquidates the account, or None if it never does. See with_liquidation.

Trait Implementations

impl Clone for SpotMarginConfig

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SpotMarginConfig

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for SpotMarginConfig

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for SpotMarginConfig

impl Hash for SpotMarginConfig

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 SpotMarginConfig

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 SpotMarginConfig

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

Equality operator ==.

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

Inequality operator !=.

impl PartialOrd for SpotMarginConfig

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 SpotMarginConfig

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 SpotMarginConfig