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. 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 order that needs more than that 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. 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.

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.
• Per-asset borrow limits and the venue’s lending pool. Only the leverage limit, and each asset’s minimum borrow, apply.
• 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_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 and each minimum borrow are decimal strings ("3"), as the crate writes decimals elsewhere, so no precision is lost to a float. min_borrow is a map from asset to minimum, 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_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