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 create → authorize → execute pipeline documented in Actions, but consumers do not have to compose the steps manually.

The examples on this page use a PerpsClient with the provider plugin registered and, for Hyperliquid, the user’s wallet bound:

import {
  PerpsClient,
  UserActionStatus,
  isSubmittedOrAccepted,
} from '@lifi/perps-sdk';
import { hyperliquidProvider } from '@lifi/perps-sdk-provider-hyperliquid';

const perps = new PerpsClient({
  apiKey: 'your-api-key',
  providers: [hyperliquidProvider()],
});
perps.setUserWallet(walletClient);

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. Ondo withdrawals are HMAC-signed SDK-side with the client-held API key and relayed by the backend through executeAction. Always follow the ProviderAction.signer and signingMethod metadata instead of assuming one signer for every venue.

Ondo withdraws USDC to the connected wallet address only. The destination must be in the Ondo address book, so call getWithdrawFlow() first. See Ondo Withdrawals.

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

​

Checking the Withdrawal Flow

Call getWithdrawFlow() to see if a venue accepts a withdrawal now. It returns undefined when the provider declares no withdrawal flow.

const flow = await perps.getWithdrawFlow({
  provider: 'ondo',
  address: userAddress,
});

The result is a WithdrawFlow:

kind	Fields	Meaning
ready	destination	The venue accepts a withdrawal to destination now
setupRequired	setup: ActionType[]	The venue needs these setup actions first, in execution order

​

Running the setup actions

Each setup entry is an ActionType. Run each one in order with perps.execute, then read the flow again. executeProviderSetupAction() rejects them, because they are not in the provider’s setup list.

const flow = await perps.getWithdrawFlow({
  provider: 'ondo',
  address: userAddress,
});

if (flow?.kind === 'setupRequired') {
  for (const action of flow.setup) {
    await perps.execute({
      provider: 'ondo',
      address: userAddress,
      action,
      params: {},
    });
  }
}

On Ondo the list can hold siweLogin and addWithdrawalAddress. See Ondo Withdrawals.

​

Discovering Withdrawable Balances

Call getWithdrawableBalances() before rendering a withdrawal picker. Providers that support the capability return one row per withdrawable (asset, category) 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 categories: Hyperliquid, Lighter, and Ondo.

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

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

Each WithdrawableBalance contains:

Field	Type	Description
asset	Asset	Canonical asset metadata, including precision, L1 identity, and minWithdrawalAmount
categoryId	string	The provider category the row draws from. The same value as Balance.categoryId
available	string	Withdrawable amount in the asset’s own units
max	string	Largest amount the row can fund. It equals available when the venue deducts the fee from the amount or charges none. It equals available minus withdrawalFee, floored at zero, when the venue charges the fee on top
withdrawalFee	string?	Flat venue fee in the asset’s own units. Absent when the venue publishes no fee
isFeeDeducted	boolean?	Present only with withdrawalFee. true means the venue takes the fee out of the amount. false means the venue charges the fee in addition. Absent means unknown

The SDK joins provider rows with /assets, drops unknown assets, and filters amounts below each asset’s minWithdrawalAmount. Never merge balances across categories. The amount remains a human-readable decimal string — the provider signer applies the asset precision.

What a row lets you submit depends on the provider:

Provider	Categories	source on the withdrawal
Hyperliquid	perps, and spot per spot token under a unified or portfolio-margin account	Ignored. WITHDRAWAL always sends USDC, so show only the USDC row
Lighter	perps, spot	Accepted. Pass { categoryId, asset: { id } } from the selected row. Omitted uses the deployment’s quote collateral
Ondo	ondo (one row at most)	Accepted only as { categoryId: 'ondo', asset: { id: 'USDC' } }. Omit it

A WithdrawableBalance row is assignable to WithdrawalAssetRef, so you can pass the row’s categoryId and asset as source. The backend drops unknown withdrawal params without an error, so a misspelled field is never reported.

A provider plugin implements the optional getWithdrawableBalances read by returning ProviderWithdrawableBalance[] — the pre-join shape, keyed by the provider-native assetId, not the resolved Asset. It carries categoryId, available, max, and the optional withdrawalFee and isFeeDeducted. Only relevant when authoring a provider plugin; consumers use WithdrawableBalance as above.

​

Throws

getWithdrawableBalances() throws PerpsError with one code for the account’s access state. See Account access.

• SetupRequired — the venue needs a credential (a Lighter auth token or an Ondo session) and none is stored.
• Unauthorized — the venue rejects the credential.
• AccountNotFound — the wallet has no venue account.

Lighter reads withdrawable balances without an auth token, so on Lighter the only access code is AccountNotFound. An account with nothing to withdraw returns an empty list.

​

Choosing a Withdrawal Type

Call getWithdrawalTypes() to read how the venue can settle a withdrawal from each holding. It returns undefined when the provider plugin declares no such read. Only Lighter implements it.

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

for (const { source, options } of sources ?? []) {
  for (const option of options) {
    console.log(source.categoryId, source.asset.id, option.type, option.max);
  }
}

Each WithdrawalSourceTypes holds a source (WithdrawalAssetRef) and a list of WithdrawalTypeOption entries:

Field	Type	Description
type	WithdrawalType	FAST, STANDARD, NATIVE, or BRIDGE
max	string	Largest amount this type accepts from the holding, in the asset’s own units
withdrawalOptions	Record<string, unknown>	Provider options. Pass them unchanged as WithdrawalParams.withdrawalOptions

The method throws PerpsError when the provider plugin is not registered or when the plugin read fails.

---

​

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 (isSubmittedOrAccepted(result)) {
  console.log('Withdrawal acknowledged by the venue');
} else if (result.status === UserActionStatus.Indeterminate) {
  console.warn(result.error); // Read the account history before you retry
} 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.

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

declare const params: WithdrawParams;

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	Address	Yes	Destination address for the withdrawal. Ondo accepts only the connected wallet address, and Lighter only the account owner.
amount	string	Yes	Human-readable amount in the selected asset’s units
source	WithdrawalAssetRef	No	The holding to withdraw from: { categoryId, asset: { id } }. Omitted uses the venue’s default holding
withdrawalOptions	Record<string, unknown>	No	Provider options, taken unchanged from getWithdrawalTypes(). The backend validates them per provider. Omitted uses the venue’s default withdrawal
accountId	string	No	Venue-native account id. The provider plugin supplies it; callers omit it. Ondo requires it on the wire (1–20 digits).

For a Lighter spot or non-quote asset, pass source from a getWithdrawableBalances() row. For a Lighter fast withdrawal, pass withdrawalOptions from getWithdrawalTypes(). 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].status	UserActionStatus	Submitted, Accepted, Indeterminate or Failed
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. Set unless the status is Submitted or Accepted.
results[i].errorCode	PerpsErrorCode?	Structured failure classification, when provided

​

Using Service Functions (advanced)

For complete control over the create/authorize/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 → authorize → execute pattern.

A Hyperliquid withdrawal step is user-signed EIP-712. The wallet must be on the chain named in typedData.domain.chainId; PerpsClient.withdraw() switches it for you through the switchChain hook when one is set. Prefer withdraw() unless you need the payload before it is signed.

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

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

const signedActions: SignedActionStep[] = [];
for (const step of actions) {
  if (!('typedData' in step)) {
    throw new Error(`Expected an EIP-712 step, got ${step.action}`);
  }
  signedActions.push({
    action: step.action,
    typedData: step.typedData,
    signature: await walletClient.signTypedData(step.typedData),
  });
}

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

const [result] = results;
console.log(result.action, result.status, result.error);

API Reference: POST /createAction, POST /executeAction