Swapping and quoting

Introduction

A Hookr pool on Hookr's shared hook is an ordinary Uniswap v4 pool whose PoolKey.hooks is HookrRoot. Any v4 caller can trade it. There are two ways in, the Universal Router and Hookr's own HookrRouter, and HookrQuoter quotes either one. Their addresses, and every other address, render below from the release book the app ships; none is typed into this page.

Through the Universal Router

Nothing special is required. Build a V4_SWAP command against the pool's PoolKey and send empty hookData.

Commands.V4_SWAP
  Actions.SWAP_EXACT_IN_SINGLE   (key, zeroForOne, amountIn, amountOutMinimum, hookData = "")
  Actions.SETTLE_ALL             (inputCurrency, amountIn)
  Actions.TAKE_ALL               (outputCurrency, amountOutMinimum)

An ERC-20 input is pulled through Permit2, so the payer approves the token to Permit2 and then approves the Universal Router as a Permit2 spender with an amount and an expiry. A plain ERC-20 approval to the Universal Router is not read, and the swap fails to settle.

Every Hook Block the pool froze at launch applies, whichever way the swap arrives.

Through HookrRouter

HookrRouter carries the payer to the root, settles exact amounts and returns unused ETH. It takes one Swap:

struct Swap {
    PoolKey key;
    bool zeroForOne;
    int128 amountSpecified;     // negative for exact input
    uint128 amountBound;        // minimum out for exact input, maximum in for exact output
    uint160 sqrtPriceLimitX96;
    address recipient;
    uint256 deadline;
}

For a native input, send msg.value equal to the input. For an ERC-20 input, approve the router directly: it pulls with transferFrom and does not read Permit2. swapAllowance in hookr-sdk returns the approval, and buildSwap builds the call. The builders refuse a swap without an amount bound, a price bound and a deadline within the next hour, and refuse a pool whose hooks is not HookrRoot.

Quoting

HookrQuoter answers in the shape of Uniswap's V4Quoter, so an aggregator that already quotes v4 pools quotes a Hookr pool the same way:

QuoteExactSingleParams is V4Quoter's own struct: the pool key, the direction, the exact amount and hookData, which must be empty. Use these for a swap routed through the Universal Router.

For a swap routed through HookrRouter, quote the router's own call: quote(Swap, payer) returns the receipt the swap will settle, and quoteDetailed(Swap, payer) adds the payer's arb recapture claim and the simulation's gas. buildQuote builds that call from the same Swap that buildSwap sends.

Each quote runs the real hook callbacks and then reverts with its result, so none of them is a view function: call it with eth_call, or with a static call from another contract. A revert that is not the quote's result bubbles up unchanged, so a swap the pool would refuse reaches you as the same error the swap would throw. A quote simulates the pool's accounting; it does not prove approvals, balances or gas.

The Lane Gas Floor

On a pool with arb recapture on, a swap must carry the lane's gas floor plus its own gas: laneGasFloor in the SDK, or gasFloor from laneOf(id) on the root. The floor is 6,802,619 at the lane's 3,000,000 gas cap. eth_estimateGas includes the floor, about 7.5 million for a buy now. Send the estimate plus a sixth, never less than the estimate. A fixed limit should be at least 8.8 million. Unused gas is refunded.

What a Trader Pays

A pool's fee is its base LP fee, plus Hookr dynamic fees up to the ceiling it froze at launch, plus any Hook Block charge it carries (Anti-Snipe's tax during its window, Auto Burn, LP Rewards, a royalty), each frozen at launch. Quote before every swap during a new token's Anti-Snipe window: its limits are per block and shared by every trader.

Next Steps

Read Providing liquidity for the LP side of the same pool, and SDK, router and quoter for the builders.