For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

account_trading_mode
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_mode on 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

  1. Enable UTA (see Change trading mode).

  2. 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.

  3. 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), with to_account_index=client.account_index. WASM: SignTransfer with fromRouteType=1 (spot), toRouteType=0 (perps), and toAccountIndex set 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.

Was this helpful?