Swap integration

This guide explains how to execute token swaps on HyperAMM. There are two approaches depending on your use case.

Approach	When to use
SwapRouter	Multi-hop routing, native HYPE wrapping/unwrapping, simpler interface
SovereignPool (direct)	Single-pool swap from a smart contract that already holds tokens, custom routing logic

Getting a Quote with HyperAMMLens

Before executing a swap, use HyperAMMLens.previewLiquidityQuote to get the expected output amount. Use the result to set amountOutMin with your desired slippage tolerance.

function previewLiquidityQuote(
    address hyperAMM,
    bool isZeroToOne,
    uint256 amountIn,
    uint256 amountOutMin
) external view returns (ALMLiquidityQuote memory quote);

Parameter	Description
`hyperAMM`	The HyperAMM pool address
`isZeroToOne`	`true` = sell token0 for token1, `false` = the reverse
`amountIn`	Gross input amount (fees are deducted internally)
`amountOutMin`	Set to `0` for a pure quote

Returns:

struct ALMLiquidityQuote {
    uint256 amountOut;        // Expected output amount
    uint256 amountInFilled;   // Input consumed after fees
    bool    isCallbackOnSwap; // Always false for HyperAMM
}

The quote includes fee deduction and hedge capacity validation. If the call succeeds, the swap is feasible at the current state.

Revert Conditions

The call reverts in the following cases:

Error	Cause
`HyperAMMLens__InsufficientOutputAmount`	Quoted output is below `amountOutMin`
`HyperAMMLens__InsufficientHedgeCapacity`	Swap size exceeds the pool’s available hedging budget
`HyperAMM__InsufficientLiquidity`	Pool does not hold enough output tokens to fill the swap

In practice, the two most common reverts integrators will encounter are:

InsufficientLiquidity – the pool lacks enough output token balance. Try a smaller amountIn.
InsufficientHedgeCapacity – the swap is too large relative to the pool’s hedge budget. Try a smaller amountIn or wait for capacity to free up.

Example

// Get quote
ALMLiquidityQuote memory quote = lens.previewLiquidityQuote(
    hyperAMM,
    true,       // token0 -> token1
    1000e6,     // 1000 USDT
    0           // pure quote
);

// Apply 0.5% slippage tolerance
uint256 amountOutMin = quote.amountOut * 995 / 1000;

Case 1: Swap via SwapRouter

HyperAMMSwapRouter handles token transfers, multi-hop routing, and native HYPE wrapping/unwrapping.

function swap(
    DirectSwapParams calldata params
) external payable returns (uint256 amountOut);