HKUDS/Vibe-Trading · error · UsdMObservationError

Binance USD-M isolated position requires positive isolated m

Error message

Binance USD-M isolated position requires positive isolated margin

What it means

A position flagged isolated=true must have isolatedMargin > 0 on the position-risk row. An isolated position with zero isolated margin is contradictory (margin would have been liquidated or the row is stale/wrong) so the library refuses it.

Source

Thrown at agent/src/trading/connectors/binance/usdm.py:206

            ("unrealizedProfit", "unRealizedProfit"),
        ):
            if not close_enough(
                _number(account_row.get(account_field), account_field),
                _number(risk_row.get(risk_field), risk_field),
            ):
                raise UsdMObservationError("Binance USD-M position reads are incoherent")
        if str(risk_row.get("marginAsset") or "").upper() != "USDT":
            raise UsdMObservationError("Binance USD-M Shadow Account supports USDT collateral only")
        isolated = account_row.get("isolated")
        if not isinstance(isolated, bool):
            raise UsdMObservationError("Binance USD-M margin mode is missing")
        isolated_margin = _number(
            risk_row.get("isolatedMargin"),
            "isolatedMargin",
            non_negative=True,
        )
        if isolated and isolated_margin == 0:
            raise UsdMObservationError("Binance USD-M isolated position requires positive isolated margin")
        if not isolated and isolated_margin != 0:
            raise UsdMObservationError("Binance USD-M cross position must report zero isolated margin")
        result.append(
            {
                "symbol": _canonical_symbol(raw_symbol),
                "quantity": quantity,
                "entry_price": entry_price,
                "leverage": _number(account_row.get("leverage"), "leverage", positive=True),
                "margin_mode": "isolated" if isolated else "cross",
                "isolated_margin": isolated_margin if isolated else None,
                "unrealized_pnl": _number(risk_row.get("unRealizedProfit"), "unRealizedProfit"),
                "initial_margin": _number(
                    risk_row.get("positionInitialMargin"),
                    "positionInitialMargin",
                    non_negative=True,
                ),
                "maintenance_margin": _number(risk_row.get("maintMargin"), "maintMargin", non_negative=True),
                "update_time": _integer(risk_row.get("updateTime"), "updateTime"),

View on GitHub (pinned to 80ffdda44c)

Solutions

Retry after a few seconds to let liquidation/settlement finish
Confirm on Binance UI whether the position still exists and has margin
If transitioning margin types, wait until Binance confirms the change completed before observing

Example fix

// before
obs = await connector.read_account_observation()

// after
await asyncio.sleep(3)  # let liquidation/settlement settle
obs = await connector.read_account_observation()

Defensive patterns

Strategy: retry

Validate before calling

risk = await client.futures_position_risk()
for p in risk:
    if p['marginType'].lower() == 'isolated' and float(p['isolatedMargin']) <= 0 and float(p['positionAmt']) != 0:
        raise RuntimeError(f"{p['symbol']}: isolated position with zero margin (liquidation in progress?)")

Try / catch

try:
    obs = await connector.read_account_observation()
except UsdMObservationError as e:
    if "positive isolated margin" in str(e):
        await asyncio.sleep(5)  # let liquidation settle
        obs = await connector.read_account_observation()
    else:
        raise

Prevention

Monitor margin levels so positions never reach full margin depletion
Do not observe during active liquidations
Top up isolated margin proactively

When it happens

Trigger: Observing an isolated position at the exact moment its margin was fully consumed (liquidation in progress), a margin-call/settlement mid-flight, or stale positionRisk data after manually transferring isolated margin out.

Common situations: Reading observations during a liquidation cascade, immediately after moving isolated margin back to the wallet, or during a margin-type transition cross/iso.

Related errors

AI-assisted analysis of HKUDS/Vibe-Trading@80ffdda44c (2026-08-28). Data as JSON: /api/errors/2c5e01820de9a2c9. Report an issue: GitHub.