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

​
Prerequisites

Before executing the spotBuy action, the following conditions must be met:
  • Spot Balance on HyperCore: The Vincent User Agent Wallet must have sufficient balance for the quote asset in their HyperCore spot balance to cover the purchase amount. The quote asset is the second asset in the trading pair (e.g., USDC 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 buy, without actually performing the operation. For the spotBuy 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 quote asset in their HyperCore spot balance to cover the purchase amount. The quote asset is the second asset in the trading pair (e.g. USDC 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_BUY)
   */
  action: HyperliquidAction.SPOT_BUY;
  /**
   * Whether to use Hyperliquid testnet (optional, defaults to false)
   */
  useTestnet?: boolean;
  /**
   * Spot buy 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;
  };
}

​
Executing the execute Function

The execute function performs the actual buy operation, placing a buy order on Hyperliquid’s spot market. For the spotBuy action, the execute function will:
  • Place a buy 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_BUY)
   */
  action: HyperliquidAction.SPOT_BUY;
  /**
   * Whether to use Hyperliquid testnet (optional, defaults to false)
   */
  useTestnet?: boolean;
  /**
   * Spot buy 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.
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% above mid price for market buys).
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 buy workflow including balance verification and price calculation, see the buy.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 Sell

Perp Long

Perp Short

Cancel Order

Cancel All Orders