Skip to main content
The transferToPerp action enables Vincent Apps to transfer USDC from a Vincent User’s HyperCore spot balance to their perp balance.

​
Prerequisites

Before executing the transferToPerp action, the following conditions must be met:
  • Spot Balance on HyperCore: The Vincent User Agent Wallet must have sufficient USDC in their HyperCore spot balance to cover the transfer amount.
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 transfer to perp, without actually performing the operation. For the transferToPerp action, the precheck function will validate the following:
  • The Vincent User Agent Wallet has sufficient USDC in their HyperCore spot balance to cover the transfer 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 'transferToPerp')
   */
  action: 'transferToPerp';
  /**
   * Whether to use Hyperliquid testnet (optional, defaults to false)
   */
  useTestnet?: boolean;
  /**
   * Transfer to perp parameters
   */
  transfer: {
    /**
     * The amount of USDC to transfer in 6-decimal format.
     * Example: "9000000" = 9.0 USDC
     */
    amount: string;
  };
}

​
Executing the execute Function

The execute function performs the actual transfer operation, moving USDC from the Vincent User’s HyperCore spot balance to their perp balance. For the transferToPerp action, the execute function will:
  • Transfer the specified amount of USDC from the Vincent User Agent Wallet’s HyperCore spot balance to their perp balance.
  • Return the transfer result from Hyperliquid.
  • Parameters
  • Implementation
  • Response
The execute function requires the following parameters:
{
  /**
   * The action to perform (must be 'transferToPerp')
   */
  action: 'transferToPerp';
  /**
   * Whether to use Hyperliquid testnet (optional, defaults to false)
   */
  useTestnet?: boolean;
  /**
   * Transfer to perp parameters
   */
  transfer: {
    /**
     * The amount of USDC to transfer in 6-decimal format.
     * Example: "9000000" = 9.0 USDC
     */
    amount: string;
  };
}

​
Important Considerations

USDC uses 6 decimals for the transfer amount parameter. When specifying the transfer amount:
  • 9.0 USDC = "9000000"
  • 5.0 USDC = "5000000"
  • 100 USDC = "100000000"
This action transfers USDC from the Vincent User’s HyperCore spot balance to their perp balance on HyperCore. If you need to transfer in the opposite direction (perp to spot), use the Transfer to Spot action.
After the transfer is executed, you can verify the balances changed by using a Hyperliquid SDK to check the clearinghouse state (perp balance) of the recipient and the spot clearinghouse state (spot balance) of the sender. You can also use the Hyperliquid API retrieve the perps balances and spot balances.

​
Reference Implementation

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

​
Next Steps

Explore the rest of the supported Hyperliquid actions:

Deposit

Withdraw

Send Spot Asset

Send Perp USDC

Transfer to Spot

Spot Buy

Spot Sell

Perp Long

Perp Short

Cancel Order

Cancel All Orders