Manage Trading Mode and Margin
Configure UTA and Multi-Asset Margin through the Lighter Core API. For the concepts, see Unified Trading Accounts and Multi-Asset Margin.
Change trading mode
On Lighter Core, switching the mode is a signed L2 transaction, UpdateAccountConfig, signed with the account's API key (no wallet signature). It works for master accounts and sub-accounts; each account index has its own mode.
0
Simple
1
Unified (UTA)
Python SDK:
await client.update_account_config(account_trading_mode=1). Examples: enable_uta.py, disable_uta.py.lighter-go WASM signer (TypeScript):
SignUpdateAccountConfig(accountTradingMode, skipNonce, nonce, apiKeyIndex, accountIndex). See WASM signer functions, then submit the signed transaction with sendTx.To read the current mode, use
account_trading_modeon account.
When UTA is enabled, the account's spot USDC balance moves into the perps margin balance.
To switch back to Simple, use account_trading_mode=0. The transaction is rejected when:
Open spot orders lock USDC in the account (
21143).A non-USDC asset is still enabled as margin; disable it first (
21158).The account is not healthy (
21723), or its cross USDC collateral is negative (21300).
Sending the mode the account is already in returns 21142.
Configure margin assets
Enable UTA (see Change trading mode).
Enable margin for the asset with
UpdateAccountAssetConfig. Python:await client.update_account_asset_config(asset_index=..., asset_margin_mode=client.ASSET_MARGIN_MODE_ENABLED). WASM:SignUpdateAccountAssetConfig(assetIndex, assetMarginMode, ...). The asset's full spot balance moves into its margin (perps) balance in the same transaction.To add more from the spot balance later, transfer it to perps within the same account. Python:
await client.transfer_same_master_account(..., route_from=client.ROUTE_SPOT, route_to=client.ROUTE_PERP), withto_account_index=client.account_index. WASM:SignTransferwithfromRouteType=1(spot),toRouteType=0(perps), andtoAccountIndexset to the same account index.
To stop using an asset as margin, call update_account_asset_config with asset_margin_mode=client.ASSET_MARGIN_MODE_DISABLED. The margin balance moves back to spot. Disabling is rejected with 21300 if the full margin balance is not available to move back to spot.
Python examples: enable_eth_as_margin.py, disable_eth_as_margin.py, add_eth_margin.py (full flow).
Was this helpful?