Skip to main content
The perpLong action enables Vincent Apps to open or increase long positions on Hyperliquid’s perpetuals market using a Vincent User’s HyperCore perp balance.

​
Prerequisites

Before executing the perpLong 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 margin requirements for the position.
  • Order Parameters: You must provide a valid perp symbol (e.g., “SOL”, “ETH”), price, size, leverage, and margin mode 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 perp long, without actually performing the operation. For the perpLong action, the precheck function will validate the following:
  • The Vincent User Agent Wallet has sufficient USDC in their HyperCore perp balance to cover the margin requirements.
  • 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.PERP_LONG)
   */
  action: HyperliquidAction.PERP_LONG;
  /**
   * Whether to use Hyperliquid testnet (optional, defaults to false)
   */
  useTestnet?: boolean;
  /**
   * Perp long parameters
   */
  perp: {
    /**
     * The perpetual symbol (base asset only, e.g., "SOL", "ETH", not "SOL-USD")
     */
    symbol: string;
    /**
     * The limit price for the long order.
     * Must follow Hyperliquid's price rules:
     * - Max 5 significant figures
     * - Max (6 - szDecimals) decimal places for perps
     * https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size#spot-price-examples
     */
    price: string;
    /**
     * The size (amount of contracts) to long.
     * Must be rounded to the asset's szDecimals.
     * Represents the notional size in the base asset.
     * https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size#spot-price-examples
     */
    size: string;
    /**
     * The leverage multiplier (e.g. 2 for 2x leverage, range 1-10x)
     */
    leverage: number;
    /**
     * Whether to use cross margin (true) or isolated margin (false)
     */
    isCross: boolean;
    /**
     * If true, this order will only reduce (not increase) your position size.
     * This is useful when you want to close part/all of an existing position but never accidentally open a larger position or flip from long to short.
     * If false or omitted, the order can both increase and decrease your position size.
     * Default: false.
     */
    reduceOnly?: boolean;
    /**
     * The order type for the long 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 };
  };
}

​
Executing the execute Function

The execute function performs the actual long operation, placing a long order on Hyperliquid’s perpetuals market. For the perpLong action, the execute function will:
  • Place a long order for the specified perpetual at the given price and size with the specified leverage.
  • Return the order 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.PERP_LONG)
   */
  action: HyperliquidAction.PERP_LONG;
  /**
   * Whether to use Hyperliquid testnet (optional, defaults to false)
   */
  useTestnet?: boolean;
  /**
   * Perp long parameters
   */
  perp: {
    /**
     * The perpetual symbol (base asset only, e.g., "SOL", "ETH", not "SOL-USD")
     */
    symbol: string;
    /**
     * The limit price for the long order.
     * Must follow Hyperliquid's price rules:
     * - Max 5 significant figures
     * - Max (6 - szDecimals) decimal places for perps
     * https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size#spot-price-examples
     */
    price: string;
    /**
     * The size (amount of contracts) to long.
     * Must be rounded to the asset's szDecimals.
     * Represents the notional size in the base asset.
     * https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size#spot-price-examples
     */
    size: string;
    /**
     * The leverage multiplier (e.g. 2 for 2x leverage, range 1-10x)
     */
    leverage: number;
    /**
     * Whether to use cross margin (true) or isolated margin (false)
     */
    isCross: boolean;
    /**
     * If true, this order will only reduce (not increase) your position size.
     * This is useful when you want to close part/all of an existing position but never accidentally open a larger position or flip from long to short.
     * If false or omitted, the order can both increase and decrease your position size.
     * Default: false.
     */
    reduceOnly?: boolean;
    /**
     * The order type for the long 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 perp orders. See the Hyperliquid API documentation for more details.
Perpetual symbols use the base asset only (e.g., “SOL”, “ETH”, “BTC”), not the full pair notation like “SOL-USD” or “SOL-PERP”. This is different from spot markets which use pairs like “PURR/USDC”.
  • Leverage controls how much position size you can open relative to the margin you put up.
    • Example: at 2x leverage, 50ofmarginallowsa50 of margin allows a 100 position.
    • Higher leverage increases both potential gains and liquidation risk.
  • Margin modes:
    • Cross margin (isCross: true): Your entire perp balance backs all positions. Profits and losses are shared across positions.
    • Isolated margin (isCross: false): Only the margin assigned to a specific position is at risk. Other balances remain protected.
  • Long positions profit when price goes up
  • Opening a long when you already have a long position will increase your position size
  • Position size is tracked as szi (signed size, positive for longs)
  • Uses USDC from your HyperCore perp balance for margin
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 perpetual, then adjust it based on your strategy (e.g., 1% above mid price for market longs).
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 positions 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 perp long workflow including balance verification and price calculation, see the long.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

Spot Sell

Perp Short

Cancel Order

Cancel All Orders