Skip to main content
The spotSell action enables Vincent Apps to execute sell orders on Hyperliquid’s spot market using a Vincent User’s HyperCore spot balance.

​
Prerequisites

Before executing the spotSell action, the following conditions must be met:
  • Spot Balance on HyperCore: The Vincent User Agent Wallet must have sufficient balance for the base asset in their HyperCore spot balance to cover the sell amount. The base asset is the first asset in the trading pair (e.g., PURR in “PURR/USDC”).
  • Order Parameters: You must provide a valid trading pair symbol (e.g., “PURR/USDC”), price, and size according to Hyperliquid’s trading rules.
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 spot sell, without actually performing the operation. For the spotSell action, the precheck function will validate the following:
  • The trading pair symbol is a valid Hyperliquid trading pair (e.g., “PURR/USDC”).
  • The Vincent User Agent Wallet has sufficient balance for the base asset in their HyperCore spot balance to cover the sell amount. The base asset is the first asset in the trading pair (e.g. PURR in “PURR/USDC”).
  • 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.SPOT_SELL)
   */
  action: HyperliquidAction.SPOT_SELL;
  /**
   * Whether to use Hyperliquid testnet (optional, defaults to false)
   */
  useTestnet?: boolean;
  /**
   * Spot sell parameters
   */
  spot: {
    /**
     * The trading pair symbol (e.g., "PURR/USDC", "ETH/USDC")
     */
    symbol: string;
    /**
     * The limit price for the sell order.
     * Must follow Hyperliquid's spot price rules:
     * - Max 5 significant figures
     * - Max (8 - szDecimals) decimal places
     * https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size#spot-price-examples
     */
    price: string;
    /**
     * The size (amount of tokens) to sell.
     * Must be rounded to the token's szDecimals.
     * https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size#spot-price-examples
     */
    size: string;
  };
}

​
Executing the execute Function

The execute function performs the actual sell operation, placing a sell order on Hyperliquid’s spot market. For the spotSell action, the execute function will:
  • Place a sell order for the specified token pair at the given price and size.
  • Return the order result from Hyperliquid.
  • Parameters
  • Implementation
  • Response
The execute function requires the following parameters:
import { HyperliquidAction, OrderType } from '@lit-protocol/vincent-ability-hyperliquid';

{
  /**
   * The action to perform (must be HyperliquidAction.SPOT_SELL)
   */
  action: HyperliquidAction.SPOT_SELL;
  /**
   * Whether to use Hyperliquid testnet (optional, defaults to false)
   */
  useTestnet?: boolean;
  /**
   * Spot sell parameters
   */
  spot: {
    /**
     * The trading pair symbol (e.g., "PURR/USDC", "ETH/USDC")
     */
    symbol: string;
    /**
     * The limit price for the buy order.
     * Must follow Hyperliquid's spot price rules:
     * - Max 5 significant figures
     * - Max (8 - szDecimals) decimal places
     * https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size#spot-price-examples
     */
    price: string;
    /**
     * The size (amount of tokens) to buy.
     * Must be rounded to the token's szDecimals.
     * https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size#spot-price-examples
     */
    size: string;
    /**
     * The order type for the buy order (optional).
     * You may specify either a limit or market order using the form:
     *   { type: "limit", tif: "Gtc" | "Ioc" | "Alo" }
     *   or
     *   { type: "market" }
     * Defaults to: { type: "limit", tif: "Gtc" }
     */
    orderType?:
      | { type: OrderType.LIMIT; tif: 'Gtc' | 'Ioc' | 'Alo' }
      | { type: OrderType.MARKET };
  };
}

​
Important Considerations

Hyperliquid has strict formatting requirements for spot orders. See the Hyperliquid API documentation for more details.
When selling tokens, you may encounter “dust” - small amounts below the minimum tradeable size. For example:
  • If a token has szDecimals=0 (only whole tokens), fractional amounts like 0.9986 cannot be sold
  • The sell size is floored to the token’s precision, so 1.9986 PURR becomes 1.0 PURR for a sell order
You’ll need to fetch the current market price before placing an order. Use the Hyperliquid API or SDK to get the mid price for your trading pair, then adjust it based on your strategy (e.g. 1% below mid price for market sells).
You can specify either a limit or market order using the orderType parameter. See the Parameters section for more details.
After the order is executed, you can verify the balances changed by checking the spot balances using a Hyperliquid SDK, or by using the Hyperliquid API.

​
Reference Implementation

For a complete working example showing the full spot sell workflow including balance verification and price calculation, see the sell.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

Transfer to Perp

Spot Buy

Perp Long

Perp Short

Cancel Order

Cancel All Orders