Withdrawals

Per-asset and per-category withdrawals from Lighter deployments

Standard Lighter withdrawals are authorized by the provider plugin’s SDK signer through a WASM blob; the user’s wallet is not prompted. When the caller selects the fast path, the backend returns an internal TRANSFER step that also needs one EIP-191 signature from the user’s wallet, so userWallet must be configured. The same normalized flow applies to lighter and lighter-rh, while each instance owns its asset catalogue, collateral, endpoints, and signing configuration.

​

Discover valid selections

Call getWithdrawableBalances() and render exactly the rows it returns:

const rows = await perps.getWithdrawableBalances({
  provider: 'lighter',
  address: userAddress,
});

// One row per asset and category.
// { asset, categoryId: 'perps' | 'spot', available, max, withdrawalFee?, isFeeDeducted? }

The SDK joins the venue’s balances with /assets, filters zero and sub-minimum rows, and attaches each asset’s decimals, L1 address, and minWithdrawalAmount. Rows whose asset is missing from the registry are dropped, and the method returns undefined if the provider plugin has no withdrawable-balance read.

available depends on the category:

• spot: the balance minus locked_balance.
• perps, settlement asset: calculateTransferable(available_balance, margin_balance). Margin held by open positions does not count.
• perps, other assets: margin_balance.

max is the largest amount the row can fund. withdrawalFee is the flat venue fee in the asset’s units when the venue publishes one, and isFeeDeducted tells whether the venue takes it out of the amount. Do not sum the same asset across perps and spot; the selected category is part of the signed transaction.

​

Choose a withdrawal type

Call getWithdrawalTypes() to read the types each row offers:

const sources = await perps.getWithdrawalTypes({
  provider: 'lighter',
  address: userAddress,
});

Every row offers STANDARD up to its max. The deployment quote collateral on the perps category also offers FAST when the venue reports an operator account. The FAST max is the lower of the row max and the venue fast-withdraw limit. Each option carries the withdrawalOptions to pass unchanged in the withdrawal:

type	withdrawalOptions
STANDARD	{ mode: 'standard' }
FAST	{ mode: 'fast', toAccountIndex, fee }

fee is the transfer fee in L2 integer units with 6 decimals.

​

Submit the selected row

Signer	SDK (provider-owned Lighter key, WASM blob)
Params	{ destination, amount, source?, withdrawalOptions? }
Categories	perps or spot
Destination	Account-owner address only

Pass the selected row’s categoryId and asset as source. amount stays in human-readable asset units; the backend loads the authoritative asset precision and minimum, validates the amount, and the provider signer scales it exactly.

import { ActionType } from '@lifi/perps-sdk';

const rows = await perps.getWithdrawableBalances({
  provider: 'lighter',
  address: userAddress,
});
const selected = rows?.[0];
if (selected) {
  await perps.withdraw({
    provider: 'lighter',
    address: userAddress,
    withdrawal: {
      destination: userAddress,
      amount: selected.max,
      source: { categoryId: selected.categoryId, asset: { id: selected.asset.id } },
    },
  });
}

When source is omitted, the withdrawal draws on the perps category and the deployment quote collateral (USDC for lighter, USDG for lighter-rh). New UIs should use discovery. Do not rely on that default. The backend still accepts the legacy assetId and route pair, but a request that carries both source and the legacy pair fails validation.

​

Destination constraint

The backend rejects a destination that differs from the L1 account owner. The destination chain follows the deployment: mainnet Lighter exits through its Ethereum path, while lighter-rh uses the Robinhood deployment configuration.

​

Standard and fast paths

The caller selects the settlement with withdrawalOptions:

Path	Settlement	Eligibility
Fast (internally a TRANSFER)	Operator-relayed, typically minutes. Needs withdrawalOptions: { mode: 'fast', toAccountIndex, fee }, and the signed transfer needs one EIP-191 signature from the user’s wallet	Deployment quote collateral on the perps category only
Standard (WITHDRAWAL)	Normal rollup withdrawal. Needs withdrawalOptions: { mode: 'standard' }, or none	Every supported asset and category

The backend does not probe the venue and does not fall back. A fast request for another asset or category fails validation. A fast request without toAccountIndex and fee fails validation. TRANSFER remains internal and is not a directly callable public action.

The returned successful ActionResult can include txHash and explorerLink when that deployment has a configured explorer.