Struct BinanceMargin 

pub struct BinanceMargin { /* private fields */ }

Binance Margin (cross and isolated) execution client using the official binance-sdk.

Places orders and queries account state over the margin REST API (margin_trading::rest_api), and streams live account events over Binance’s margin user-data stream, read with a listen key from POST /sapi/v2/margin/listen-key.

See BinanceMarginConfig::testnet for the no-testnet caveat. The behaviour a caller most needs to know is summarised below, with links to the authoritative detail.

Borrow/repay (sideEffectType)

A client has a default MarginEffect (BinanceMarginConfig::margin_effect, by default NoSideEffect, so no order takes on debt unless asked), and each request may carry its own (RequestOpen::margin_effect). Open a short or a margin long with Borrow (MARGIN_BUY), which borrows what the order lacks when it is placed, and close it with Repay (AUTO_REPAY), which repays from the proceeds. Binance retired AUTO_BORROW_REPAY on 2026-10-14, so there is no longer one value that does both. A mis-sized Borrow order borrows the shortfall, or the asset’s minimum borrow if that is more, without further opt-in: see MarginEffect::Borrow for the rule, and open_order. open_margin_order also reports what the order borrowed.

Cross vs. isolated margin

The mode is fixed per client via BinanceMarginConfig::is_isolated:

• Cross (is_isolated = false, isIsolated = "FALSE", account-wide collateral): per-asset balances (incl. debt) are surfaced account-wide in the top-level balances.
• Isolated (is_isolated = true): per-pair sub-accounts. Balances + risk are attached per-instrument via InstrumentAccountSnapshot::isolated (the asset-keyed top-level balances is left empty, since (pair, asset) slots would collide), and per-symbol queries are scoped to the configured BinanceMarginConfig::isolated_symbols. See account_snapshot for the full per-method semantics.

Trailing stops

As on spot, a TrailingStop is placed as a STOP_LOSS with a trailingDelta, and a TrailingStopFixedLimit as a STOP_LOSS_LIMIT with a trailingDelta and its fixed limit as price, for BasisPoints and Percentage offsets that come to a whole number of basis points. An activation price is sent as stopPrice. Absolute offsets and TrailingStopLimit return OrderError::UnsupportedOrderType. See open_order.

The account mode matters for TrailingStop. A cross account refuses a trailing STOP_LOSS with -3111 (“Trailing stop order only supports limit type”), which this client returns as OrderError::UnsupportedOrderType; an isolated account has accepted it. TrailingStopFixedLimit is accepted on both, so it is the form to place on a cross account. The client does not refuse a TrailingStop unsent: Binance’s answer decides, so the client carries no per-mode rule that could fall out of date.

Stop and take-profit orders without a limit

Since 2026-10-14 Binance has refused STOP_LOSS and TAKE_PROFIT orders on margin with -3116 (“not supported for this account”), and has not said when it will take them again. That covers a Stop, a TakeProfit and a TrailingStop, which this client places as those types. The refusal comes back as OrderError::UnsupportedOrderType, after the round trip: place the limit form instead, StopLimit, TakeProfitLimit or TrailingStopFixedLimit, which is not affected. The client does not refuse these orders unsent, so they go through again once Binance takes them.

Conditional orders Binance does not describe

Binance margin accepts a trailingDelta on its conditional types (STOP_LOSS, STOP_LOSS_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT), on cross and isolated accounts, though a cross account refuses a trailing STOP_LOSS (see “Trailing stops” above). Two of its reports never say whether such an order trails:

• the REST order queries this client reads (openOrders, order, allOrders) return neither trailingDelta nor trailingTime (#541), on either account;
• an isolated account’s stream sends an empty trailing delta ("d": "") for every order, trailing or not. A cross account’s stream sends the delta of a trailing order, and an empty one only for an order that does not trail.

A trailing order placed without an activation price reads stopPrice "0" in both.

Such an order is reported with the kind this client knows it by: the kind it was placed with, known from the moment the order is sent, since the stream may report it before the answer to placing it arrives, or the one a report that did describe it gave, for every order the client placed, listed or saw while live, or else a kind the caller supplied with recall_order_kinds. An order it knows no kind for, such as one placed elsewhere or before a restart, is reported as OrderKind::ConditionalUnresolved, with its type’s family and its stopPrice as trigger_price, logged at warn, rather than described as a fixed or a trailing order it may not be. So fetch_open_orders, account_snapshot, the account_stream and fetch_ended_orders list every live conditional order, and report every ended one as ended, so that a stop that fired is not held as live.

User-data stream

account_stream reads Binance’s margin user-data stream with a listen key from POST /sapi/v2/margin/listen-key, kept alive as each connection opens and every 30 minutes after. Since 2026-10-14 Binance refuses the earlier margin streams’ credentials (POST /sapi/v1/userListenToken and POST /sapi/v1/margin/listen-key) with -3086 for new accounts and for accounts it has migrated, and the v2 key is open to every account. One stream carries fills, orders, balances, margin debt and margin notices, for the cross account and every isolated pair alike.

Margin balances & debt-freshness

Balances carry per-asset margin debt: Balance::net_asset returns total - borrowed - interest, as Binance’s netAsset does, with borrowed/interest exposed via MarginDetails. Authoritative debt totals come from the REST account_snapshot (BalanceSnapshot). The WS stream keeps free/locked live via BalanceStreamUpdate, which never clobbers debt, and keeps debt live via AccountEventKind::MarginDebt, one per asset a liabilityChange lists, on a cross account: Binance has not been seen to send that event for an isolated pair. A debt change sent while the stream is down is not recovered, so call account_snapshot at startup and after a reconnect (see account_stream’s cold-start note).

As Binance documents it, margin interest is charged hourly on what is borrowed and accrues as the asset’s unpaid interest, which comes out of total only when it is repaid. net_asset deducts it as it accrues, as fresh as the rest of the debt. Fills carry no interest, so PnL computed from them excludes it.

Rate limits

Once a /sapi response reports at least 90% of the documented per-IP weight limit (12000 per minute) used, queries wait for the next minute, so the rest is left for orders and cancels, which never wait for it. A query, including a fetch_open_orders after a reconnect, can therefore take up to about a minute longer. A reconnect’s fill recovery and its listen-key request do not wait for it either, since a pause could outlast the recovery’s 30 s and delay its fills to a retry. The per-UID /sapi limit is not tracked. After Binance answers with a rate-limit error, every REST call waits out a cooldown as long as its Retry-After asked, or 10 s without one. A call facing more than 10 s of it is not sent: it fails at once with ApiError::RateLimit carrying the time left, rather than hanging through a ban that can last days. A 418 (an IP ban) is never retried in place.

The account stream follows the same rule. It does not open, or reconnect, during a cooldown: it waits out one of 10 s or less, without spending a reconnect attempt, and a longer one fails the open with ApiError::RateLimit, unsent, or ends a running stream with StreamTerminationReason::RateLimited, carrying the time left. A connect or subscribe Binance refuses for a rate limit starts a cooldown, as a REST refusal does. A refused handshake names no wait, so a 429 starts the 10 s default, and handshakes refused that way spend the reconnect budget as any failure does; a 418, an IP ban, starts Binance’s shortest ban, 2 minutes, and so ends the stream.

One client per engine (ExchangeId)

All emitted events — cross and isolated alike — are stamped ExchangeId::BinanceMargin, and the engine routes AssetStates / ConnectivityStates by ExchangeId. Running two BinanceMargin clients in a single engine (e.g. one cross, one isolated) therefore collides their exchange identity. A single engine should run at most one BinanceMargin client; a consumer needing cross and isolated concurrently runs them in separate engines.

Fills of other clients’ orders

The account stream, fill recovery and fetch_trades report every fill on the account, whoever placed the order, and Binance does not say who did. A consumer that also trades the account outside the engine filters those fills itself, for example by Trade::client_order_id. See the module docs.

Implementations

impl BinanceMargin

pub async fn fetch_collateral_ratios( &self, ) -> Result<HashMap<AssetNameExchange, Vec<CollateralRatioTier>>, UnindexedClientError>

The collateral ratio tiers of every asset on Binance cross margin: GET /sapi/v1/margin/crossMarginCollateralRatio.

Each asset maps to its tiers in ascending min_usd_value. Binance groups assets that share a tier list; each asset of a group gets the group’s tiers. An asset Binance does not list is absent.

The ratios are Binance’s for cross margin, read whichever margin this client is configured for. They are market data, not this account’s: the request carries the API key and is not signed.

What the answer holds

Binance publishes three collateral ratios per asset on its Margin Data page (borrow, transfer-out and liquidation), and the endpoint returns one. Binance does not document which, nor how an asset with several tiers is weighted across them. What was observed on 2026-11-02:

• every asset had one tier with a ratio of 1, matching the page’s liquidation ratios (100% for every asset) and not its borrow ratios (as low as 10%);
• that tier had no maxUsdValue, so it is reported with max_usd_value None.

Read the answer as observed, not guaranteed. Binance’s API documents no endpoint for the borrow ratios, which govern how much the account may borrow.

To model these ratios on the simulated venue, a single-tier ratio as observed above maps to SpotMarginConfig::with_liquidation_collateral_ratio. Take the borrow ratios (SpotMarginConfig::with_borrow_collateral_ratio) from Binance’s Margin Data page, not from this answer: they can be far lower, and using this answer for them would let a backtest borrow more than Binance lends.

Cost

One request, costing 100 of Binance’s per-IP request weight.

Errors

• Whatever error the request returns.
• UnindexedClientError::Internal for an answer that cannot be read whole, rather than return a map that silently lacks its assets or tiers: a group missing its assets or its tiers, a group with no tiers, a tier missing its minUsdValue or discountRate, a value that does not read as a decimal, or an asset listed twice.

impl BinanceMargin

pub async fn fetch_margin_interest( &self, start: DateTime<Utc>, end: DateTime<Utc>, ) -> Result<CashFlowsRead<AssetNameExchange, InstrumentNameExchange>, UnindexedClientError>

Read the interest Binance charged the account from start to end, each charge as a CashFlow of MarginInterest, oldest first, in CashFlowsRead::flows.

A cross-margin client reads the cross account. An isolated one reads each pair in its isolated_symbols, and attributes each charge to its pair through CashFlow::instrument; a cross charge is attributed to none.

What a charge is

Binance charges interest hourly, and once when a loan is taken, by adding it to the loan rather than taking it from the account’s free balance. A charge is cash only once the loan is repaid. The flow’s negative amount is the cost charged at time_exchange, not a balance that moved then: the account’s balance shows it as interest owed on the asset.

• asset is the asset field of Binance’s record. Binance charges interest in the asset borrowed, or converts it into BNB for an account that pays interest in BNB: a _CONVERTED record’s asset is BNB, so its flow does not name the asset borrowed. Binance names that asset in a separate rawAsset field, which this method does not read, and which Binance does not return on an isolated record.
• principal is the loan the charge was on. On a _CONVERTED record it can read 0, and Binance’s documentation does not say when. Binance’s support points to its borrow and repay history (GET /sapi/v1/margin/borrow-repay) for the loan. A converted record’s flow does not carry the asset borrowed, so that history cannot be narrowed to it by asset from the flow alone.
• rate is Binance’s interestRate, a daily rate even on an hourly charge: an hourly charge is about the rate divided by 24 of the principal. Binance’s API documentation does not state the unit; it is read off the rates Binance publishes on its margin fee page, whose hourly figure is the daily one divided by 24 (BTC’s daily rate matches the field, its hourly rate is about 24 times smaller).
• timing is read from Binance’s type: PERIODIC (and PERIODIC_CONVERTED, and portfolio margin’s daily PORTFOLIO) is Periodic, ON_BORROW (and ON_BORROW_CONVERTED) is OnBorrow, and any other value is Other with Binance’s own name. None when the record has no type.
• time_exchange is Binance’s interestAccuredTime, the period the charge is for, not when Binance posted it (see Delivery): for an hourly charge, the start of its hour. An ON_BORROW charge is stamped at the start of the hour the loan was taken in, so it can precede the opening of the position it belongs to.
• period is that hour, from interestAccuredTime to an hour after it, for an hourly charge: PERIODIC, ON_BORROW and their _CONVERTED forms. The engine reads it to give an ON_BORROW charge to a position opened later in its hour (see InstrumentState::update_from_cash_flow in rustrade). None for any other type, whose period Binance does not document, PORTFOLIO included, and, logged at WARN, for an hourly charge not stamped on the hour.
• id is Binance’s transaction id for the charge.

The engine adds a flow attributed to an instrument to the carry of its open position, in the slot for the flow’s asset: the quote asset’s carry, the base asset’s, or any other asset’s. Interest on a short’s borrowed base asset is valued at the price the position closes at, which is what buying the asset back costs. Interest in BNB, or any asset that is neither the instrument’s base nor quote, is kept as charged and is in no PnL figure.

Delivery

Nothing is pushed: the caller decides when to read, and must drop the charges it has already counted, by id, before applying a read’s flows. Within one read each charge appears once: a charge read twice, as one stamped on a window’s boundary is, is kept the first time its id is seen in its asset and pair, or, without an id, once per identical record.

A charge is posted some time after the period it is for, by a delay Binance does not document and that may vary, and is then served stamped at that period. A read whose span ends near the present can therefore miss a charge that a later read returns at a time inside the earlier span. A caller that polls by time should start each read before the previous read’s end, by at least the longest posting delay it is prepared to allow for, and drop the charges it has already counted by id within their asset and pair. A charge with no id can be matched only by its whole record, which cannot tell it from an identical charge.

The records need not add up to the interest owed. On a live account, a loan was charged interest when it was taken, yet a read served only the hourly charge that followed, with no ON_BORROW record. Whether such a record is posted later, or never, is not known. The account’s balance, which reports the interest owed (see MarginDetails::interest), is the figure to rely on for what is owed.

Span

• Binance serves interest charged in the last 90 days only. A start before that is moved up to a minute inside that limit, clear of any skew between the clocks, and held_since is where the read then starts: charges before it may exist but were not read. A caller adding up the interest on a position opened before it has only part of it. held_since is None when start is at or after that point, a minute inside the 90 days; a request for the last 90 days reports it.
• Charges are read up to end, or up to the local clock at the call if that is earlier.
• The whole span is read in one call, so resume is always None.
• Binance serves at most 30 days per request, so a span is read in windows of 29 days, each paged by 100 charges. A read costs a request weight of 1 per page, at least 1 per window, and, on an isolated client, as much again for each pair.

Records left out

A record without an asset, an amount or a time that parses is left out, and logged at WARN. A rate or principal that does not parse is left None, and logged at WARN.

Errors

Fails if any request fails, or if one window of one account holds more than 50,000 charges. Nothing is returned from a read that failed part way.

pub async fn fetch_forced_liquidations( &self, start: DateTime<Utc>, end: DateTime<Utc>, ) -> Result<Vec<MarginForcedLiquidation>, UnindexedClientError>

Read the orders Binance placed from start to end to liquidate the account, oldest first.

A cross-margin client reads the cross account. An isolated one reads each pair in its isolated_symbols.

Binance marks no liquidation on the account stream, so this client reports a liquidation order’s fills as TradeOrigin::Order. A caller that learns the account is being liquidated, as from a margin-level notice, can read these records and match their order_ids against the fills it has, with the caveat on that field.

Span

Records are read up to end, or up to the local clock at the call if that is earlier, in pages of 100. Binance documents no limit on the span or on how far back it serves; a two-year span was accepted when tried in October 2026, which is no guarantee. A read costs a request weight of 1 per page and, on an isolated client, as much again for each pair.

Records left out

• A record without an order id, a pair, a side, a filled quantity or a time that parses is left out, and logged at WARN. A price or quantity that does not parse is left None, and logged at WARN.
• On a cross client, a record Binance marks as isolated is left out, and logged at WARN: the cross query should not return one. An isolated client asks for one pair at a time, and keeps what Binance returns for it.

Errors

Fails if any request fails, or if one account holds more than 50,000 records in the span. Nothing is returned from a read that failed part way.

impl BinanceMargin

pub fn recall_order_kinds( &self, kinds: impl IntoIterator<Item = (ClientOrderId, OrderKind)>, )

Tell the client the kinds of orders it may not know, by client order id, such as after a restart, so that it reports them with these kinds where Binance’s reports cannot describe them.

Binance’s margin REST order queries never say whether a conditional order (STOP_LOSS, STOP_LOSS_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT) trails, and neither does an isolated account’s stream. The client reports such an order with the kind it knows it by, from placing it or from a report that described it, and otherwise as OrderKind::ConditionalUnresolved. A kind recalled here fills that gap: it is reported for its order when Binance’s report leaves the kind unresolved and the client has learned no resolved kind itself. Call it before account_snapshot, fetch_open_orders or account_stream to have their first reports use it. It can be called again at any time, and adds to what earlier calls supplied.

Each kind must be the one its order was placed with: it is reported as given, unchecked against the order’s Binance type.

A kind is kept until the client sees its order end: on its account stream, on cancelling it, or in the check the stream runs after a reconnect. fetch_ended_orders does not drop it. One for an order this client has recently seen end is ignored. So is an unresolved kind, and anything past 4096 held kinds, with a warning. The client keeps nothing across restarts: persisting the kinds of the orders it places is the caller’s.

kinds is collected before the client’s order set is locked, so it may call this client.

pub async fn load_rules( &self, instruments: &[InstrumentNameExchange], ) -> Result<HashMap<InstrumentNameExchange, OrderRules>, UnindexedClientError>

Load the order rules of instruments from Binance now, and hold them for open_order to check against.

Rules otherwise load on each pair’s first order, which adds a request to that order. Calling this ahead takes it off the first order, and shows a bad symbol or a failed load here. Binance refuses the whole request if one symbol is not listed. The rules are the pair’s spot rules, which Binance margin has no endpoint for.

pub async fn fetch_next_hourly_interest_rates( &self, assets: &[AssetNameExchange], ) -> Result<HashMap<AssetNameExchange, Decimal>, UnindexedClientError>

The next hourly interest rate of each of assets on this client’s cross or isolated margin: GET /sapi/v1/margin/next-hourly-interest-rate.

Each rate is a fraction of the amount borrowed, per hour, at this account’s VIP level, for the next hourly charge; Binance can change it before then. It is not annualised: fetch_shortability reports the base asset’s rate × 24 × 365.

An asset Binance does not answer for is absent from the map. An asset named twice is asked for once, and an empty assets sends nothing.

Cost

Binance takes at most 20 assets a request, so the assets are read 20 at a time, one request after another, each costing 100 of Binance’s per-IP request weight.

Errors

Whatever error any of the requests returns: a failed request fails the whole read, rather than return a map that silently lacks its assets. UnindexedClientError::Internal for a rate that does not read as a decimal.

pub async fn fetch_commission_rates( &self, instrument: &InstrumentNameExchange, ) -> Result<CommissionRates, UnindexedClientError>

The account’s commission rates on instrument, read from the spot GET /api/v3/account/commission at 20 of Binance’s per-IP spot request weight.

Binance margin has no commission endpoint of its own. A margin trade has been seen to pay the account’s spot rates, which is what this reads; Binance does not document that, so treat it as observed, not guaranteed. CommissionRates says how Binance combines them.

Errors

• ApiError::InstrumentInvalid for a symbol Binance does not list.
• UnindexedClientError::Internal for an answer missing a rate, with a rate that does not read as a decimal, or for another symbol.

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

The most this host’s clock leads Binance’s, from the client’s reads of Binance’s server time; negative when it trails. None when server_time_sync is off, or before a read has succeeded.

An upper bound: the true lead, plus the time the kept read’s answer took to arrive and the drift allowed for since. A read logs at warn when it finds the clocks 1 s or more apart.

pub async fn open_margin_order( &self, request: OrderRequestOpen<ExchangeId, &InstrumentNameExchange>, ) -> MarginPlacement

Submit a margin order over the SAPI POST /sapi/v1/margin/order endpoint, and report what it borrowed.

ExecutionClient::open_order returns this method’s MarginPlacement::order. Call this one to learn what an order placed with MarginEffect::Borrow borrowed, which Binance reports only in its answer to the order (marginBuyBorrowAmount, marginBuyBorrowAsset): see MarginPlacement::borrowed. Binance leaves them out when the free balance covered the order. The amount is what Binance reports lending, which need not equal the order’s shortfall: it is at least the asset’s minimum borrow (see MarginEffect::Borrow), so read it rather than compute it from the balance.

Mirrors BinanceSpot::open_order’s contract: every failure is folded into the returned order’s state as OrderState::inactive, so the engine always sees an outcome.

Margin specifics:

• sideEffectType is the request’s MarginEffect, else the client’s BinanceMarginConfig::margin_effect: NO_SIDE_EFFECT, MARGIN_BUY for Borrow and AUTO_REPAY for Repay.
• A Borrow borrows when the order is placed, not when it fills, and nothing repays it from the order’s proceeds: close the position with a Repay order.
• autoRepayAtCancel is sent with Borrow only, from BinanceMarginConfig::auto_repay_at_cancel: Binance applies it to MARGIN_BUY alone.
• An order with Borrow has a request weight of 1500 against the account’s UID limit, against 6 for the other effects. Place them accordingly.
• isIsolated is config-driven ("TRUE" for isolated, "FALSE" for cross).
• A TrailingStop is sent as a STOP_LOSS with trailingDelta in basis points, and a TrailingStopFixedLimit as a STOP_LOSS_LIMIT with trailingDelta and its fixed limit as price; an activation price goes as stopPrice. An Absolute offset, and TrailingStopLimit, return OrderError::UnsupportedOrderType; an offset that is not a positive whole number of basis points returns OrderError::InvalidPrecision (see the type-level docs). A non-positive activation price, or a TrailingStopFixedLimit without a positive price, is refused unsent as OrderError::Rejected.
• A cross account refuses the STOP_LOSS form of a TrailingStop with -3111, which comes back as OrderError::UnsupportedOrderType after the round trip. Place a TrailingStopFixedLimit there instead: it is accepted on both account modes.
• A successful answer that cannot be read (one that does not decode, has no orderId, or reports a borrowed amount without its asset or the other way round) returns OrderError::Connectivity: the venue acted on the request, so the order may be live, and its outcome is unknown rather than refused.
• The order’s time is the answer’s transactTime. An answer without a readable one is still read, at the local time, and logged with a warn!.
• The order’s kind is known to the client from the moment its request is sent, so a stream report that arrives before the answer is described by it. If the future is dropped after the request was sent, the order may be live: its kind is kept until the client sees the order end, as one from recall_order_kinds is, and counts toward the same limit. That includes a drop while waiting to retry a rate-limited request, which Binance refused, since the client cannot tell the two apart.

Trait Implementations

impl BorrowCapacityClient for BinanceMargin

async fn fetch_borrow_capacity( &self, instrument: &InstrumentNameExchange, side: Side, ) -> Result<BorrowCapacity, UnindexedClientError>

Reads the pair, then /sapi/v1/margin/maxBorrowable for the asset an order on side borrows, on this client’s cross margin or on the pair’s isolated account. They cost 51 of Binance’s per-IP request weight on cross margin and 60 on isolated.

borrowable_now is Binance’s amount, which it describes as the account’s “max borrowable amount with sufficient system availability”, so it is also capped by what Binance has to lend. account_limit is its borrowLimit, the most the account’s VIP level allows.

Errors

• ApiError::InstrumentInvalid for a pair Binance does not trade on this client’s cross or isolated margin.
• ApiError::RequestRejected with Binance’s -11001 on isolated margin, for a pair this account has no isolated margin account for. Open one on Binance, or ask a cross-margin client.

impl Clone for BinanceMargin

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 BinanceMargin

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

Formats the value using the given formatter.

impl ExecutionClient for BinanceMargin

fn new(config: Self::Config) -> Self

Construct a BinanceMargin client from its configuration.

Panics

Panics if:

• the binance-sdk configuration builder fails (e.g. empty or malformed API key/secret), matching BinanceSpot’s startup contract; or
• is_isolated = true but isolated_symbols is empty — an isolated client with no configured pairs has nothing to snapshot or stream. This gate lives here (not only in BinanceMarginConfig::isolated) because the config is Deserialize-only and a deserialized config bypasses the named constructor. The ExecutionClient::new signature returns Self, not Result, so an unusable config is a fail-fast panic (consistent with the credential expects above), not a recoverable error.

async fn open_order( &self, request: OrderRequestOpen<ExchangeId, &InstrumentNameExchange>, ) -> Order<ExchangeId, InstrumentNameExchange, UnindexedOrderState>

Submit a margin order over the SAPI POST /sapi/v1/margin/order endpoint.

BinanceMargin::open_margin_order’s order, without what it borrowed: see there for the margin specifics.

async fn cancel_order( &self, request: OrderRequestCancel<ExchangeId, &InstrumentNameExchange>, ) -> UnindexedOrderResponseCancel

Cancel a resting margin order via DELETE /sapi/v1/margin/order.

Cancels by exchange orderId when present and parseable, otherwise by the originating client order id. isIsolated is config-driven. Mirrors BinanceSpot::cancel_order: every failure is folded into the returned response’s state as an Err.

The cancellation’s time is the answer’s transactTime. An answer without a readable one is read at the local time, with a warn!.

A successful answer that cannot be read (one that does not decode, or has no readable orderId) returns OrderError::Connectivity: the venue acted on the cancel, so whether the order is still working is unknown.

async fn account_snapshot( &self, assets: &[AssetNameExchange], instruments: &[InstrumentNameExchange], ) -> Result<UnindexedAccountSnapshot, UnindexedClientError>

Fetch a full margin account snapshot: balances plus open orders per instrument.

Cross (is_isolated = false): account-wide per-asset balances from query_cross_margin_account_details (carrying borrowed/interest → Balance::new_margin) in the top-level balances, plus open orders per requested instrument — mirroring BinanceSpot::account_snapshot.

Isolated (is_isolated = true): per-pair balances + risk from query_isolated_margin_account_info (chunked ≤5 symbols/request), attached per-instrument via InstrumentAccountSnapshot::isolated rather than folded into the asset-keyed top-level balances (which is left empty) — isolated sub-accounts are per-(pair, asset) and would collide in the asset-keyed model. The instrument set is the effective isolated set (isolated_symbols, or instruments ∩ isolated_symbols with out-of-set instruments skipped); each instrument’s open orders and isolated balances are fetched over that same set.

Known limitation: balances can lag a fill

Binance’s REST account view can trail its matching engine. A cross account read straight after a fill has returned the pre-trade balances, and was current about 2 s later. A caller that needs post-fill balances should apply the account_stream’s balance events, or read again after a short delay. The client adds no retry or delay of its own: when and how to reconcile is the caller’s policy.

So each balance is stamped 5 s before its request was sent: a stream balance or debt event the read may not yet show is then still more recent than the read, and applies over it. The send is timed on Binance’s clock when this host’s is ahead of it (see the module docs).

async fn fetch_balances( &self, assets: &[AssetNameExchange], ) -> Result<Vec<AssetBalance<AssetNameExchange>>, UnindexedClientError>

Fetch current margin balances (incl. borrowed/interest debt) for the requested assets.

Cross: account-wide per-asset balances; an empty assets slice is the “return all” sentinel.

Isolated: returns an empty Vec. Isolated balances are per-(pair, asset) and the asset-keyed return type cannot carry them without collision — they are surfaced per-instrument via account_snapshot’s InstrumentAccountSnapshot::isolated instead.

Reads the same REST account view as account_snapshot, so its known limitation applies: balances read straight after a fill can still be the pre-trade ones.

async fn fetch_open_orders( &self, instruments: &[InstrumentNameExchange], ) -> Result<Vec<Order<ExchangeId, InstrumentNameExchange, Open>>, UnindexedClientError>

Fetch currently open margin orders, optionally filtered by instrument.

Cross: honours the ExecutionClient::fetch_open_orders “return all” sentinel — an empty instruments slice is served by a single no-symbol query_margin_accounts_open_orders call (each order’s instrument taken from its own symbol); a non-empty slice fetches the listed instruments concurrently, per-symbol.

Isolated: per-symbol on the venue — always iterates the effective isolated set (empty instruments → configured isolated_symbols; out-of-set instruments skipped with a warning); never issues a no-symbol isolated call.

A conditional order is listed with the kind this client knows it by, or else as OrderKind::ConditionalUnresolved: the REST row cannot tell a fixed from a trailing one (#541). See the type-level docs and recall_order_kinds.

async fn fetch_trades( &self, start: DateTime<Utc>, end: DateTime<Utc>, instruments: &[InstrumentNameExchange], ) -> Result<TradesRead<AssetNameExchange, InstrumentNameExchange>, UnindexedClientError>

Read margin trades (fills) from start to end, optionally filtered by instrument.

Documented deviation from the ExecutionClient::fetch_trades “return all” contract: Binance’s margin trade-list endpoint (myTrades) requires a symbol — there is no no-symbol “all trades” query (unlike open orders).

Cross: an empty instruments slice has nothing to query and reads nothing; callers wanting all trades must enumerate instruments explicitly.

Isolated: the empty sentinel resolves to the configured isolated_symbols (the effective isolated set; out-of-set instruments skipped with a warning), iterated per-symbol (Design decision #4).

Complete: each instrument is read to the span’s end within the call, with no page cap, so the read is always complete (resume: None).

Lookback cost: Binance serves margin trades by time only in spans under 24 hours, so each instrument is read in 23-hour windows from start until its first trade, one request (weight 10) per window, then by trade id. The cost grows with the lookback and has no cap: a start 30 days back with no trades costs about 32 requests per instrument, and one at the Unix epoch about 21,000. Pass the most recent start that covers what you need.

Upper bound: trades are read up to end, or up to the local clock at the call if that is earlier. A trade stamped after the local clock, as one inside any skew between it and Binance’s can be, is left to the next read, unless a window before the last one held a trade (or the last one read a full page) and the walk went on to page by id, which reads on to end.

async fn account_stream( &self, assets: &[AssetNameExchange], instruments: &[InstrumentNameExchange], ) -> Result<Self::AccountStream, UnindexedClientError>

Live stream of account events (fills, order updates, balances, margin debt and notices) over Binance’s margin user-data stream.

Gets a listen key (POST /sapi/v2/margin/listen-key, weight 1), connects to wss://fstream.binance.com/private/ws and subscribes the key, then keeps the stream live with auto-reconnect, exponential backoff, heartbeat monitoring and fill recovery (mirroring BinanceSpot). The key is kept alive as each connection opens and every 30 minutes after (PUT, weight 1), since Binance hands back a key that is still live without saying how long it has left; a failed keepalive is logged at warn, and if the key lapses anyway Binance says so on the stream, and the stream reconnects with a new one. The key is not closed when the stream ends: it lapses 60 minutes after its last keepalive. The stream ends once 10 reconnects in a row have failed or a rate-limit cooldown outlasts what it waits through: see the module docs. After each reconnect it restates the account’s balances, debt included: see there.

Binance sends on this stream only when the account changes, so the client pings it at each heartbeat check, and the pong is what proves a quiet connection alive.

As on spot, each instrument’s gap after a reconnect is kept until its fills are forwarded: a gap whose read failed or timed out is retried after 1, 2, 4, 8 and 16 minutes, connected or not in between, reading only the gap. After five failed retries it is given up, logged at error and reported as an AccountEventKind::FillRecoveryGaveUp; ExecutionClient::fetch_trades can still read its fills.

One key for the whole margin account

Binance’s listen key covers the cross account and every isolated pair alike, and each frame says which it is about. A cross client keeps the cross account’s frames, and an isolated client those of its isolated_symbols; the rest are dropped at debug. So a cross and an isolated client on one account each see only their own, though each opens a stream of its own.

An executionReport that does not say which it is about is kept by its symbol, on cross whatever the symbol and on isolated when it is a configured pair, and the ambiguity is logged at warn once: an order on the same symbol in the other kind of account could then reach both clients. A balance or debt frame that does not say is dropped with a warn.

Debt cold-start

This method does not seed balances. Margin debt (borrowed/interest) is correct only if the caller invokes ExecutionClient::account_snapshot at startup (the BalanceSnapshot that populates margin). The stream thereafter keeps free/locked live via BalanceStreamUpdate, and debt via AccountEventKind::MarginDebt (see “Margin debt” below), but only for the assets whose debt changes; a change sent while the stream was down is not recovered.

Margin notices

Binance’s marginLevelChange is delivered as an AccountEventKind::Notice. Its status maps to a NoticeKind: MARGIN_CALL → MarginCall, PRE_LIQUIDATION → LiquidationWarning, FORCE_LIQUIDATION → Liquidation, NORMAL and EXCESSIVE → MarginRestored, anything else → Other, with Binance’s status verbatim in AccountNotice::status and its margin level (l) in margin_level.

The event’s s is its status, so it names no pair. A cross account’s notice names no instrument. An isolated pair’s is delivered to an isolated client naming no instrument, with a warn, whichever pair it is about, since losing a margin call costs more than losing its attribution; a cross client does not receive it. So an isolated client’s notice can be about any isolated pair of the account, one it is not configured for included, and two isolated clients on one account each receive it.

A notice with no time is stamped on arrival. Each arrival is logged at info, before dedup. A notice sent while the stream is disconnected is not recovered.

Margin debt

Binance’s liabilityChange is delivered as one AccountEventKind::MarginDebt per asset it lists. Each asset’s principal (p) and interest (i) are its totals after the change, as observed live (Binance’s docs do not say), so each update states the whole debt. Its type (t) maps to a MarginDebtKind: BORROW → Borrow, REPAY → Repay, INTEREST (the periodic charge) → Interest, anything else, such as DEBT_CHANGE, → Other, with Binance’s type verbatim in venue_kind.

• Cross updates name no instrument: they are the account’s debt in that asset.
• Isolated debt is not known to be streamed. Binance has not been seen to send liabilityChange for an isolated pair: a borrow and a repay there came with balance updates alone. One that did arrive would name its pair, from the frame. An isolated client reads its pairs’ debt from ExecutionClient::account_snapshot.

Binance posts an interest charge some time after the period it is for; when is not documented. An asset with no name, or whose p or i cannot be read, is dropped with a warn, as is a change with no readable time, which could not be ordered against the debt held. Each arrival is logged at info.

Fills around the start

Frames the venue sends before it confirms the subscription are kept and delivered first. A fill before the subscription is not on the stream: callers requiring startup fill completeness call ExecutionClient::fetch_trades with a ~1s lookback after this returns.

A recovered fill advances the order too. A live fill carries the order’s cumulative filled quantity in Trade::order_filled_quantity (executionReport’s z); REST myTrades carries none, so recovery rebuilds the same figure by reading each recovered order’s executions from its first: one extra request per order (another per further 1,000 executions), up to four orders at a time per instrument. Those lookups have their own time budget inside the recovery timeout, so they can never cost a fill: a fill whose order was not looked up in time, or whose lookup failed, goes out with order_filled_quantity: None, logged at warn, and advances the position but not the order.

Orders that ended while disconnected

A reconnect also reports how each order the client holds as live on one of the stream’s instruments ended, where it did, as an AccountEventKind::OrderSnapshot of its inactive state: filled, cancelled with what filled before, expired, or rejected. The stream’s instruments are instruments on cross and isolated_symbols on isolated, as for fill recovery. Binance’s order history filters on when an order was created, so such an order is found by asking about it, not by time.

• Which orders. The client holds an order as live from the response to placing it, from a listing of open orders (account_snapshot, fetch_open_orders), and from its live reports on any of its account streams, until it sees the order end. It holds up to 4,096 orders and forgets the oldest past that, logged at warn. An order placed outside this client and never listed or reported to it is not covered.
• Cost. One GET /sapi/v1/margin/openOrders per instrument with an order held (weight 10), then one GET /sapi/v1/margin/order (weight 10) for each held order the listing no longer shows, all in the configured cross or isolated account.
• Fills first. An instrument is checked only once its fill gap is recovered or given up, so an order’s recovered fills arrive before how it ended. A fill that brings an order to its full quantity ends it, and that order is not reported again.
• Keys. Each snapshot carries StrategyId::unknown, since Binance records no strategy. The engine matches it to the order it tracks by client order id.
• Failures. Each order’s lookup is settled as it ends, and each instrument as soon as its check ends. One whose listing or any lookup fails, or whose check is still running when a pass reaches 30 s, is retried on the fill gaps’ schedule (1, 2, 4, 8 and 16 minutes), asking only about the orders still held, then given up, logged at error. Its orders are asked about again at the next reconnect. An order Binance does not know (-2013) stops being held, logged at warn; one it still reports live, or in a state this version cannot read, stays held.

The same lookup is public as OrderStatusClient::fetch_ended_orders.

Isolated mode

Under is_isolated = true the stream covers exactly isolated_symbols; the instruments argument does not choose them. Each pair’s base and quote asset are read from the isolated account info before the stream opens, and a failed read fails the call.

Live per-pair balances — InstrumentBalanceUpdate

The isolated stream delivers live fills and order updates and live per-pair free/locked balances, emitted as AccountEventKind::InstrumentBalanceUpdate, one per asset whose balance changed: base, quote or both. A side that did not change is not reported. A pair whose base and quote could not be read at the start has its balance frames dropped with a warn; its fills and orders are unaffected.

Debt totals (borrowed/interest) are not known to be streamed for an isolated pair (see “Margin debt” above), so they come from account_snapshot, and from the InstrumentBalanceSnapshots the stream restates after each reconnect (see the module docs).

Consumption contract (important): the engine deliberately does not store InstrumentBalanceUpdate — it falls through update_from_account’s _ => None wildcard, mirroring the snapshot’s InstrumentAccountSnapshot::isolated. It is therefore never in EngineState, and a StateReplicaManager replica replays the same wildcard so it is not in replica state either. A consumer obtains live per-pair balances only by inspecting the raw account event off the stream (AccountStreamEvent::Item(..) / audit_tick.event) and matching the variant itself — a consumer reading solely replica EngineState will see nothing and wrongly conclude the feature is broken. A wrapper wanting engine-queryable per-instrument balances uses the InstrumentData extension point instead.

const EXCHANGE: ExchangeId = ExchangeId::BinanceMargin

const SUPPORTED_KINDS: &'static [InstrumentKindDiscriminant]

The InstrumentKindDiscriminants this client can trade.

type Config = BinanceMarginConfig

type AccountStream = Pin<Box<dyn Stream<Item = AccountEvent<ExchangeId, AssetNameExchange, InstrumentNameExchange>> + Send>>

fn validate_config( config: &Self::Config, instruments: &[ClientInstrument<'_>], ) -> Result<(), String>

Checks config against the instruments this client is about to be built to trade, before Self::new is called. Err names what is wrong.

fn cancel_orders<'a>( &self, requests: impl IntoIterator<Item = OrderRequestCancel<ExchangeId, &'a InstrumentNameExchange>>, ) -> impl Stream<Item = UnindexedOrderResponseCancel> + Send

fn open_orders<'a>( &self, requests: impl IntoIterator<Item = OrderRequestOpen<ExchangeId, &'a InstrumentNameExchange>>, ) -> impl Stream<Item = Order<ExchangeId, InstrumentNameExchange, UnindexedOrderState>> + Send

impl OrderStatusClient for BinanceMargin

Looks each order up with GET /sapi/v1/margin/order by symbol and client order id, in the cross or isolated account as BinanceMarginConfig::is_isolated says, weight 10 each, up to eight at a time. Binance’s FILLED is reported with its average price, CANCELED with what filled before it, EXPIRED and EXPIRED_IN_MATCH (self-trade prevention) as expired, and REJECTED as OpenFailed. An order Binance does not know under the key’s symbol (-2013, or -1121 for a symbol that does not exist) is omitted. A row whose status this version does not know is omitted too, with a warning, as is a PENDING_CANCEL one.

In isolated mode a key’s symbol is asked about whether or not it is one of isolated_symbols, since an order can be placed on any pair. Any error other than those two codes fails the call, including one Binance gives for a pair with no isolated account.

The account stream runs the same lookup itself after a reconnect; see account_stream.

async fn fetch_ended_orders( &self, orders: &[UnindexedOrderKey], ) -> Result<Vec<UnindexedInactiveOrder>, UnindexedClientError>

How each of orders ended, for those that have.

fn fetch_order_status( &self, key: &UnindexedOrderKey, ) -> impl Future<Output = Result<VenueOrderStatus, UnindexedClientError>> + Send

where Self: Sync,

What the venue knows of the order under key: live, ended, or nothing.

impl ShortabilityClient for BinanceMargin

async fn fetch_shortability( &self, instrument: &InstrumentNameExchange, ) -> Result<Shortability, UnindexedClientError>

Reads the pair, its base asset, the base asset’s next hourly interest rate and Binance’s margin delisting schedule, which cost 202 of Binance’s per-IP request weight on cross margin and 211 on isolated, almost all of it the interest rate and the schedule.

• shortable is whether the pair is traded on margin and may be sold (/sapi/v1/margin/allPairs, or isolated/allPairs on isolated margin), its base asset may be borrowed (/sapi/v1/margin/allAssets), and its delisting time, if any, is still ahead. Any of them false makes it false.
• delisting_at is when Binance will delist the pair from this client’s margin, from /sapi/v1/margin/delist-schedule, which lists only what is due to be delisted. On cross margin Binance schedules assets, so the pair goes with the first of its base and quote assets to be delisted. On isolated margin it schedules the pair itself.
• fee_rate is the base asset’s next hourly interest rate (/sapi/v1/margin/next-hourly-interest-rate, for this client’s cross or isolated margin) times 24 × 365. It is this account’s rate, at its VIP level, for the coming hour only.
• easy_to_borrow is unknown: Binance has no such distinction.
• available is unknown: Binance does not say how much it has to lend in total, only how much this account can borrow, which fetch_borrow_capacity reports.

Errors

• ApiError::InstrumentInvalid for a pair Binance does not trade on this client’s cross or isolated margin.
• Whatever error any of the requests returns, the delisting schedule’s included: an unread schedule is not reported as no delisting scheduled.