Skip to main content
The withdraw action enables Vincent Apps to bridge USDC from a Vincent User’s HyperCore perp balance back to Arbitrum using the Hyperliquid bridge.

​
Prerequisites

Before executing the withdraw action, the following conditions must be met:
  • Perp Balance on HyperCore: The Vincent User Agent Wallet must have sufficient USDC in their HyperCore perp balance to cover the withdrawal amount.
  • Destination Address (optional): You can specify a destination address on Arbitrum. If not provided, the withdrawal will be sent to the Vincent User’s Agent Wallet address on Arbitrum.
To learn more about executing Vincent Abilities, see the Executing Abilities guide.

​
Executing the precheck Function

The precheck function validates some prerequisites for executing a withdrawal, without actually performing the operation. For the withdraw action, the precheck function will validate the following:
  • The Vincent User Agent Wallet has a HyperCore perp account.
  • The withdrawal amount is at least $1 USDC (due to the withdrawal fee required by Hyperliquid).
  • The Vincent User Agent Wallet has sufficient USDC in their HyperCore perp balance to cover the withdrawal amount.
  • Parameters
  • Implementation
  • Response
The precheck function requires the following parameters:
import { HyperliquidAction } from '@lit-protocol/vincent-ability-hyperliquid';

{
  /**
   * The action to perform (must be HyperliquidAction.WITHDRAW)
   */
  action: HyperliquidAction.WITHDRAW;
  /**
   * Whether to use Hyperliquid testnet (optional, defaults to false)
   */
  useTestnet?: boolean;
  /**
   * Withdraw parameters
   */
  withdraw: {
    /**
     * The amount of USDC to withdraw in 6-decimal format.
     * Example: "5000000" = 5 USDC
     */
    amount: string;
    /**
     * The destination address on Arbitrum (optional).
     * If not provided, defaults to the Vincent User's Agent Wallet address.
     */
    destination?: string;
  };
}

​
Executing the execute Function

The execute function performs the actual withdrawal by initiating a bridge transfer from the Vincent User’s HyperCore perp balance to Arbitrum. For the withdraw action, the execute function will:
  • Initiate a withdrawal of the specified amount of USDC from the Vincent User Agent Wallet’s HyperCore perp balance to the specified destination address on Arbitrum (or the Agent Wallet address if no destination is provided).
  • Return the withdrawal result from Hyperliquid.
  • Parameters
  • Implementation
  • Response
The execute function requires the following parameters:
import { HyperliquidAction } from '@lit-protocol/vincent-ability-hyperliquid';

{
  /**
   * The action to perform (must be HyperliquidAction.WITHDRAW)
   */
  action: HyperliquidAction.WITHDRAW;
  /**
   * Whether to use Hyperliquid testnet (optional, defaults to false)
   */
  useTestnet?: boolean;
  /**
   * Withdraw parameters
   */
  withdraw: {
    /**
     * The amount of USDC to withdraw in 6-decimal format.
     * Example: "5000000" = 5 USDC
     */
    amount: string;
    /**
     * The destination address on Arbitrum (optional).
     * If not provided, defaults to the Vincent User's Agent Wallet address.
     */
    destination?: string;
  };
}

​
Important Considerations

After successfully executing a withdrawal, it takes some time for the funds to appear on Arbitrum. The withdrawal must be processed by Hyperliquid’s bridge before the USDC becomes available on Arbitrum.
USDC uses 6 decimals. When specifying the withdrawal amount, use the 6-decimal format:
  • 5 USDC = "5000000"
  • 15 USDC = "15000000"
  • 100 USDC = "100000000"
Withdrawals are always taken from the Vincent User’s HyperCore perp balance. If you need to withdraw funds from the spot balance, you must first transfer them to the perp balance using the Transfer to Perp action.
If you don’t specify a destination address, the withdrawal will be sent to the Vincent User’s Agent Wallet address on Arbitrum. You can optionally specify a different destination address if needed.
After the withdrawal is initiated, you can verify the perp balance decreased by checking the clearinghouse state using a Hyperliquid SDK, or by using the Hyperliquid API.

​
Reference Implementation

For a complete working example showing the full withdrawal workflow including balance verification, see the withdraw.spec.ts end-to-end test in the ability-hyperliquid package.

​
Next Steps

Explore the rest of the supported Hyperliquid actions:

Deposit

Send Spot Asset

Send Perp USDC

Transfer to Spot

Transfer to Perp

Spot Buy

Spot Sell

Perp Long

Perp Short

Cancel Order

Cancel All Orders