HKUDS/Vibe-Trading · error · UsdMObservationError

Binance USD-M Shadow Account supports USDT collateral only

Error message

Binance USD-M Shadow Account supports USDT collateral only

What it means

The Shadow Account only supports USDT-margined positions with USDT as the margin asset. If the position-risk row's marginAsset (uppercased) is anything but USDT (e.g. BUSD, USDC, or a multi-assets-mode row), this error is raised.

Source

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

                risk_row.get("openOrderInitialMargin"),
                "openOrderInitialMargin",
                non_negative=True,
            ),
        )
        if any(open_order_margins):
            raise UsdMObservationError("Binance USD-M Shadow Account requires zero open-order margin")
        for account_field, risk_field in (
            ("positionInitialMargin", "positionInitialMargin"),
            ("maintMargin", "maintMargin"),
            ("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),

View on GitHub (pinned to 80ffdda44c)

Solutions

  1. Switch the futures wallet to Single-Asset Mode with USDT (POST /fapi/v1/multiAssetsMargin with multiAssetsMargin=false)
  2. Close positions on non-USDT-margined contracts before importing the account
  3. Restrict trading to USDT-margined perpetual symbols (e.g. BTCUSDT not BTCUSDC)

Example fix

# before: account in Multi-Assets Mode
# after: switch to single-asset USDT margin
await client.futures_change_margin_type(coin='USDT')  # or:
await client.request('POST', '/fapi/v1/multiAssetsMargin', {'multiAssetsMargin': 'false'})
Defensive patterns

Strategy: validation

Validate before calling

risk = await client.futures_position_risk()
bad = [p for p in risk if float(p.get('positionAmt', 0)) != 0 and p['marginAsset'].upper() != 'USDT']
if bad:
    raise RuntimeError(f"non-USDT margined positions: {[p['symbol'] for p in bad]}")

Try / catch

try:
    obs = await connector.read_account_observation()
except UsdMObservationError as e:
    if "USDT collateral only" in str(e):
        # close/migrate non-USDT positions, then retry
        raise  # requires account action, not a runtime fallback
    raise

Prevention

When it happens

Trigger: Holding a position on a contract settled/margined in a non-USDT asset, or having Multi-Assets Mode enabled on the USD-M futures account, which reports marginAsset per position differently.

Common situations: Multi-Assets Mode enabled in Binance futures wallet settings; legacy BUSD-margined contracts; user copying a strategy from a coin-margined (COIN-M) account.

Related errors

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