SDK, router and quoter

The npm package

hookr-sdk is the typed TypeScript package for building on the new Hookr from any app, launcher or agent. It runs on viem and ships the live addresses, the ABIs, the rule catalog with its bounds, and builders for the four calls an integration makes.

npm install hookr-sdk viem

The package names both live roots: the default root HookrModularHookV6 as ADDRESSES.root and the arbitrage-recapture root HookrModularHookV6WthV5 as ADDRESSES.recaptureRoot, with ROOTS pairing each with its kernel id. Pool keys, quotes, swaps and reads work on either root; pass the pool's own hooks to poolKeyFor. Its market builders open on the default root unless root: ROOTS.recapture is passed; on the recapture root they freeze the five correction fields from RECAPTURE_CORRECTION plus the creator, refuse any quote but native ETH, and need the creator wallet, so the pool corrects from its first swap (see Shipping a correction executor for what each field is). Its swap builders put the 1,100,000 gas floor on a call against the current recapture root, since an estimate underfunds the correction; a pool on a superseded recapture root gets no floor from 0.2.0 and needs one from the caller (see Routing a correcting pool), and 0.2.1 adds a correcting option on the swap builders with poolCorrects to read it from the pool's frozen rules. listRoots reads every kernel the registry has registered, current or not, and listMarkets scans in bounded windows. RPC_URL is the public node and is for light reads; anything that scans logs should use a provider endpoint of its own. Every value in it is checked against the app's own encoders by a parity test on each release, so the SDK and hookr.fun never disagree on an address, a bound or a calldata layout. The package README on npm carries a worked example for each builder, and the contracts behind it are public at github.com/Hookr-fun/hookr-contracts.

The rest of this page is what the SDK wraps: the two contracts that are the whole integration surface for trading a Hookr pool.

Two contracts are the whole integration surface for trading a Hookr pool: the trusted router and the trusted quoter. Everything else a pool needs is ordinary Uniswap v4 periphery.

Their ABIs are at /api/v2-abi/HookrKernelRouterV3 and /api/v2-abi/HookrKernelQuoterV1. See ABIs for the rest.

Why These Two Are Special

A pool's frozen stack names one router and one quoter, each pinned by runtime code hash. The accounting kernel decodes hookData only from those two addresses, at those code hashes. That is what lets the hook credit the Nth-buy pot to a wallet rather than to a router contract.

HookrStackRegistryV2 at 0x5b7f1A117A83aaac15B0698Aa4eB9D53fE5f5BA3 holds the registration. The registry identifiers are:

HookrKernelRouterV3.integrationVersion() returns 3 and HookrKernelQuoterV1.integrationVersion() returns 1. Read them rather than assuming.

Approvals

The two paths do not share an approval model, and mixing them up is the most common integration failure.

A plain ERC-20 approval to the Universal Router or to PositionManager is not read, and the swap or mint fails to settle. The Hookr router is the opposite: it does not use Permit2 at all.

For the creator's initial buy on a new-token launch, the approval goes to the router, not to the coordinator. The coordinator pulls no quote on either lane; the router pulls the creator's quote inside the launch transaction, so a missing allowance reverts the whole launch including the token deployment.

Quoting

Use HookrKernelQuoterV1 for anything routed through the Hookr router. It runs the real hook callbacks, the real module walk and the real fee override, then reverts with the result. It is not a view function, because it calls poolManager.unlock: call it with eth_call, or with a static call from another contract.

Pass the real recipient. The pot leg is recipient-specific, so a different recipient can produce a different result.

Use Uniswap's V4Quoter for anything routed through the Universal Router. It sees the same pool without the pot cut, which is exactly what a Universal Router swap pays. Quoting through the Hookr quoter and then routing through the Universal Router makes the two disagree by potBps on a pool with a pot.

On a pool whose root runs an arbitrage correction there is a second and larger source of divergence, because a correction can move the price in beforeSwap before the swap is priced, and such a swap also needs a gas limit an estimate will not give it. Routing a correcting pool has both.

The full call shapes are in Swapping and quoting.

Reading a Pool

A pool's rules are frozen, so one read at any block is correct for the life of the pool.

HookrModuleTypesV1.StackCore memory core = registry.stack(poolId);
(HookrModuleTypesV1.ModuleSnapshot memory m, bytes memory config) = registry.moduleAt(poolId, 0);
HookrNativeMechanicsBlockV2.Config memory cfg =
    abi.decode(config, (HookrNativeMechanicsBlockV2.Config));

Do not reconstruct a configuration from events. Events for indexers covers what the events are actually for.

Before You Ship

• Read marketCoordinator.marketOpeningPaused() on 0x53A192A3fCeE94Da77916B461E0cCa2Dd6402442 before showing a launch control. While it is true, only the owner can open a market.
• Read protocolShareBps(creator) in the same transaction you launch in. Admission reverts ProtocolShareTierMismatch on any other value.
• Use amountOutMinimum for slippage on a pool with input cuts, not a price limit. A non-canonical sqrtPriceLimitX96 reverts PartialFillUnsupportedWithInputCuts.
• Show a Universal Router price and a Hookr router price as two different numbers on a pool with a pot. They are.
• Check the pool's root before sending a swap. On a root that corrects, the estimate alone underfunds the correction and the route decides whether the trader is rebated at all.