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

​
Prerequisites

Before executing the transferToSpot 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 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 spot, without actually performing the operation. For the transferToSpot action, the precheck function will validate the following:
  • The Vincent User Agent Wallet has sufficient USDC in their HyperCore perp 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 HyperliquidAction.TRANSFER_TO_SPOT)
   */
  action: HyperliquidAction.TRANSFER_TO_SPOT;
  /**
   * Whether to use Hyperliquid testnet (optional, defaults to false)
   */
  useTestnet?: boolean;
  /**
   * Transfer to spot parameters
   */
  transferToSpot: {
    /**
     * The amount of USDC to transfer in 6-decimal format.
     * Example: "15000000" = 15.0 USDC
     */
    amount: string;
  };
}

​
Executing the execute Function

The execute function performs the actual transfer operation, moving USDC from the Vincent User’s HyperCore perp balance to their spot balance. For the transferToSpot action, the execute function will:
  • Transfer the specified amount of USDC from the Vincent User Agent Wallet’s HyperCore perp balance to their spot balance.
  • Return the transfer 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.TRANSFER_TO_SPOT)
   */
  action: HyperliquidAction.TRANSFER_TO_SPOT;
  /**
   * Whether to use Hyperliquid testnet (optional, defaults to false)
   */
  useTestnet?: boolean;
  /**
   * Transfer to spot parameters
   */
  transferToSpot: {
    /**
     * The amount of USDC to transfer in 6-decimal format.
     * Example: "15000000" = 15.0 USDC
     */
    amount: string;
  };
}

​
Important Considerations

USDC uses 6 decimals for the transfer amount parameter. When specifying the transfer amount:
  • 15.0 USDC = "15000000"
  • 5.0 USDC = "5000000"
  • 100 USDC = "100000000"
This action transfers USDC from the Vincent User’s HyperCore perp balance to their spot balance on HyperCore. If you need to transfer in the opposite direction (spot to perp), use the Transfer to Perp 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 sender and the spot clearinghouse state (spot balance) of the recipient. 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 spot workflow including balance verification, see the to-spot.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 Perp

Spot Buy

Spot Sell

Perp Long

Perp Short

Cancel Order

Cancel All Orders