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

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 tiers by the holding’s value in USD.
• Conservative borrow prices. The leverage limit values each asset at the same price as the liquidation check. Binance’s borrow check values an asset the account owes at the highest index price over a recent window, and every other asset at the lowest.
• 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_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, and liquidation is left out when off.

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.

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