Withdrawal

Withdraw funds from a provider perps account

Withdraw funds from a provider perps account.

The examples on this page use Hyperliquid (provider: 'hyperliquid'). Withdrawal mechanics (supported assets, destination chains, and processing times) vary by provider.

Overview

PerpsClient.withdraw() is a single-call helper that builds the withdrawal payload, authorizes it through the registered provider plugin, and submits the signed action. It dispatches through the same createAction → authorize → executeAction pipeline documented in Actions, but consumers do not have to compose the steps manually.

Withdrawal authorization is provider-specific. Hyperliquid withdrawals require the user’s wallet. Lighter withdrawals are signed by the provider plugin’s SDK-managed Lighter key. Always follow the ProviderAction.signers and signingMethod metadata instead of assuming one signer for every venue.

Ondo has no withdraw method — the provider exposes no withdrawal action. Ondo still implements getWithdrawableBalances() as a read — see Ondo / Account figures.

Hyperliquid: Withdrawal processing typically takes 3–4 minutes. The bridge transfer from Hyperliquid L1 to Arbitrum is asynchronous.

Discovering Withdrawable Balances

Call getWithdrawableBalances() before rendering a withdrawal picker. Providers that support the capability return one row per withdrawable (asset, route) pair; providers without the optional read return undefined, which means the form remains amount-only.

Hyperliquid, Lighter, and Ondo all implement this read. Each provider’s own page describes its routes: Hyperliquid, Lighter, and Ondo.

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

for (const row of rows ?? []) {
  console.log(row.asset.displaySymbol, row.route, row.available);
}

Each WithdrawableBalance contains:

Field	Type	Description
asset	Asset	Canonical asset metadata, including precision, L1 identity, and minWithdrawalAmount
route	WithdrawalRoute ('perps' | 'spot')	Venue balance route used by the signed withdrawal
available	string	Withdrawable amount in the asset’s own units

The SDK joins provider rows with /assets, drops unknown assets, and filters amounts below each asset’s minWithdrawalAmount. For a row-based provider, pass the selected asset.id and route through the withdrawal action params together; never merge balances across routes. The amount remains a human-readable decimal string — the provider signer applies the asset precision.

A provider plugin implements the optional getWithdrawableBalances read by returning ProviderWithdrawableBalance[] — the pre-join shape, keyed by the provider-native assetId rather than the resolved Asset. Only relevant when authoring a provider plugin; consumers use WithdrawableBalance as above.

---

Using PerpsClient (recommended)

const { results } = await perps.withdraw({
  provider: 'hyperliquid',
  address: userAddress,
  withdrawal: {
    destination: userAddress, // Address to receive withdrawn funds
    amount: '100.0',
  },
});

const [result] = results;
if (result.success) {
  console.log('Withdrawal submitted successfully');
} else {
  console.error(`Withdrawal failed: ${result.error}`);
}

Withdrawal submission returns 202 Accepted. Processing is asynchronous — for Hyperliquid, this typically takes 3–4 minutes via the Arbitrum bridge. Poll getAccount() to verify the balance change.

PerpsClient.withdraw

Build, sign with the provider-declared signer, and submit a withdrawal in a single call.

const response = await perps.withdraw(params);

Parameters: WithdrawParams

Field	Type	Required	Description
provider	string	Yes	Provider identifier
address	string	Yes	User’s wallet address (account owner)
withdrawal	WithdrawalParams	Yes	Withdrawal details

WithdrawalParams:

Field	Type	Required	Description
destination	string	Yes	Destination address for the withdrawal
amount	string	Yes	Human-readable amount in the selected asset’s units

The exported WithdrawalParams type carries only destination and amount. A row-based provider (currently Lighter) also accepts assetId and route on the withdrawal payload, but these are backend-validated wire fields, not part of the SDK’s named TypeScript type — see Lighter Withdrawals.

Returns: ExecuteActionResponse — { results: ActionResult[] }. The array contains a single result for the WITHDRAWAL action:

Field	Type	Description
results[i].action	ActionType	ActionType.WITHDRAWAL
results[i].success	boolean	Whether the withdrawal was accepted
results[i].txHash	string?	Venue transaction hash when known at submission time
results[i].explorerLink	string?	Fully resolved explorer link for txHash, when configured
results[i].error	string?	Error message (failed result only)
results[i].errorCode	PerpsErrorCode?	Structured failure classification, when provided

Using Service Functions (advanced)

For complete control over the create/sign/execute steps — for example, to surface the typed-data payload in a confirmation dialog before requesting the signature — call the lower-level createAction / executeAction service functions directly. See Actions for the full create → sign → execute pattern.

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

const { actions } = await createAction(client, {
  provider: 'hyperliquid',
  address: userAddress,
  action: ActionType.WITHDRAWAL,
  params: {
    destination: userAddress,
    amount: '100.0',
  },
});

const signedActions = await Promise.all(
  actions.map(async (a) => ({
    action: a.action,
    typedData: a.typedData,
    signature: await walletClient.signTypedData({ ...a.typedData }),
  })),
);

const { results } = await executeAction(client, {
  provider: 'hyperliquid',
  address: userAddress,
  action: ActionType.WITHDRAWAL,
  actions: signedActions,
});

const [result] = results;
console.log(result.action, result.success ? 'OK' : result.error);

API Reference: POST /createAction, POST /executeAction