Core Concepts

Hooks

Hooks are smart contracts that intercept and modify AMM pool behavior. They fire at specific points in the pool lifecycle — before/after swaps, liquidity changes, and transfers — giving tokens programmable, composable behaviors.

Hook points

Each hook implements one or more lifecycle functions. The HookManager calls these functions at the appropriate time during pool interactions.

Hook Point	When it fires	Use cases
beforeSwap	Before a swap executes	MEV protection, sniper blocking, dynamic fees
afterSwap	After a swap completes	Burn-on-sell, fee redistribution, analytics
beforeAddLiquidity	Before LP deposits	Whitelist validation, minimum amounts
afterAddLiquidity	After LP deposits	LP rewards, position tracking
beforeRemoveLiquidity	Before LP withdrawals	Cooldown enforcement, lock periods
afterRemoveLiquidity	After LP withdrawals	Fee settlement, cleanup

Hook interface

All hooks must implement the IHook interface. You only need to implement the hook points you use — unimplemented functions are no-ops.

interfaces/IHook.sol

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.28;

interface IHook {
    function beforeSwap(
        address pool,
        address sender,
        bool zeroForOne,
        int256 amountSpecified,
        bytes calldata data
    ) external returns (bytes4);

    function afterSwap(
        address pool,
        address sender,
        bool zeroForOne,
        int256 amountSpecified,
        bytes calldata data
    ) external returns (bytes4);

    function beforeAddLiquidity(
        address pool,
        address sender,
        uint256 amount0,
        uint256 amount1,
        bytes calldata data
    ) external returns (bytes4);

    function afterAddLiquidity(
        address pool,
        address sender,
        uint256 amount0,
        uint256 amount1,
        bytes calldata data
    ) external returns (bytes4);
}

Gas limits

Each hook binding has a configurable gas limit (default: 500,000). If a hook exceeds its gas budget, the call reverts gracefully without affecting the underlying swap. The HookManager emits a HookExecuted event with a success flag so you can monitor failures.

Hooks run in the context of the HookManager, not the pool itself. They cannot directly modify pool state — only read it and emit side effects (burns, transfers, state updates).

Publishing a hook

To publish a hook to the marketplace, register it on the HookRegistry contract. Registration requires a fee of 0.01 ETH (configurable by admin) and includes metadata for the marketplace listing. Once registered, hooks can be verified by curators with the CURATOR_ROLE.

typescript

const hookId = await hookos.hooks.register({
  name: "Dynamic Fee Oracle",
  category: "Trading",
  implementation: deployedHookAddress,
  metadataURI: "ipfs://QmYour.../metadata.json",
});

Composability

Tokens can attach up to 8 hooks simultaneously. Hooks execute in order of attachment. This lets creators compose complex behaviors from simple building blocks:

MEV Shield + Burn-on-Sell — Protected trading with deflationary pressure
Sniper Cage + LP Bonded — Fair launch with locked liquidity
Dynamic Fee + Social Reflection — Adaptive fees with community rewards

Revenue model

Hook authors earn revenue from the FeeRouter. When protocol fees are collected, they are split according to the configured shares — typically 30% goes to hook authors, proportional to usage. High-install hooks earn more.

Quickstart

Tokens