Documentation

One API for Uniswap v4 hooks.

HookFi is developer infrastructure for programmable liquidity on Robinhood Chain (chain ID 4663). It reads the chain and returns data or unsigned calldata. It never holds keys, never signs, and never submits transactions.

Uniswap v4 lets any pool attach a hook: a contract that runs before or after swaps, liquidity changes and donations. Hooks make liquidity programmable (dynamic fees, custom curves, launchpads, limit orders, oracles), and they make every pool a little different. HookFi is one layer to discover every hook and pool, decode what a hook is allowed to do from its address, inspect its bytecode, mine CREATE2 salts, read live pool state, quote through the hook, build swaps, and give agents the same tools over MCP.

ContractAddress on Robinhood Chain
PoolManager0x8366a39cc670b4001a1121b8f6a443a643e40951
PositionManager0x58daec3116aae6d93017baaea7749052e8a04fa7
StateView0xf3334192d15450cdd385c8b70e03f9a6bd9e673b
V4Quoter0x8dc178efb8111bb0973dd9d722ebeff267c98f94
UniversalRouter0x204FAca1764B154221e35c0d20aBb3c525710498
Permit20x000000000022D473030F116dDEE9F6B43aC78BA3

Quickstart

The API is open: no key, open CORS, plain JSON over HTTPS. The base URL is .


From JavaScript, the SDK is one file with no dependencies:



Use with Cursor and Claude Code

Every endpoint is also an MCP tool. Any MCP client can use it with a one-line config: nothing to install, no key.



Hook API

Answers one question: what can this hook do to my swap or my liquidity? It covers every hook attached to a v4 pool on Robinhood Chain, indexed from the PoolManager's Initialize events.

GET/v1/hooksRegistry of every hook used by a pool. sort=pools|recent, limit 1 to 100, offset.
GET/v1/hooks/:addressFull profile: permissions, capability notes, bytecode size and hash, proxy detection, warnings, total pools and the 25 most recent.
GET/v1/hooks/:address/flagsPure decode of the permission bits in any address, deployed or not. No chain call.
GET/v1/hooks/flagsThe 14-flag table.
GET/v1/hooks/censusHow many indexed hooks carry each permission, and how many can set price, charge after a swap, or block withdrawals.

code.proxy is null, or { kind: "eip1967" | "eip1167", implementation, admin, upgradeable }. Minimal proxies (EIP-1167) point at a fixed implementation and are reported with upgradeable: false. codeHash lets you check whether two hooks run identical bytecode.

Hook Miner

A hook's permissions are the lowest 14 bits of its address. To ship a hook with beforeSwap and afterSwap you must deploy it to an address ending in exactly 0x00c0 (masked to 14 bits). The miner finds a CREATE2 salt that does it. On average it takes 2^14, about 16,000 hashes.

POST/v1/hooks/mineflags (names or a 14-bit mask), initCodeHash or initCode, optional deployer (default: the deterministic deployer 0x4e59b44847b379578588920cA78FbF26c0B4956C), startSalt, maxIterations up to 400000.

The mined address matches exactly: bits you did not ask for are zero, so the hook gets no permission you did not request. verify is the node recomputing the CREATE2 address from the deployer, salt and init code hash. If nothing is found within maxIterations, retry with startSalt = nextSalt. The salt is only valid for the exact init code: change a constructor argument and you need a new salt.

# creation code + abi-encoded constructor args (PoolManager on Robinhood Chain)
INIT_CODE=$(cast concat-hex \
  $(forge inspect src/MyHook.sol:MyHook bytecode) \
  $(cast abi-encode "constructor(address)" 0x8366a39cc670b4001a1121b8f6a443a643e40951))
cast keccak $INIT_CODE

Pool API

Lists every v4 pool initialized on Robinhood Chain and reads live state from the PoolManager through StateView. A pool is identified by its key: currency0, currency1 (sorted; native ETH is the zero address), fee in hundredths of a bip or 8388608 for a dynamic-fee pool, tickSpacing, and hooks. The PoolId is keccak256(abi.encode(key)).

GET/v1/poolsIndexed pools, newest first. Filter with hook, token, tokenA + tokenB, hooked.
GET/v1/pools/:poolIdLive state by PoolId: price, tick, liquidity, current LP fee, hook permissions.
POST/v1/pools/stateLive state by pool key, for any pool, indexed or not.
POST/v1/pools/idPoolId for a key. Pure. Currencies may be passed in either order.
GET/v1/pools/:poolId/checkRisk level with plain-English reasons. Add tokenIn and amount to compare a live quote with the pool's own spot price.
GET/v1/statsIndex totals and the v4 contract addresses.
LevelRaised by
highAn invalid hook address, no code at the hook, an upgradeable proxy, or a hook that can block LP withdrawals.
mediumA hook that can set the swap price or move tokens, a dynamic-fee pool whose hook runs before swaps, or a quote more than 1% from the pool's own price.
lowNone of the above.

Quote API

Hooks can change swap output: charge a fee, rebate tokens, or replace the curve. A quote computed from liquidity alone can be wrong for a hooked pool. HookFi quotes with the on-chain V4Quoter, which simulates the real swap through the PoolManager, so the hook runs exactly as it would on chain.

GETPOST/v1/quotepoolId or the key, tokenIn or zeroForOne, amount (decimal string), exactOut, hookData.
GET/v1/quote/besttokenIn, tokenOut, amount, limit 1 to 15. Reads every indexed pool for the pair, quotes the deepest (plus pools whose hook prices swaps itself) and ranks them.

If the simulated swap reverts the API returns 422 no_route with the revert selector, so you can match it against the hook's custom errors.

Swap API

POST /v1/swap/build turns a pool, an input token and an amount into the exact transactions a wallet needs: approvals when needed, then one Universal Router call. Fields: poolId or the key, tokenIn, amount, sender, slippageBps (1 to 5000, default 50), hookData.

  • ERC-20 approve(Permit2, max): only when the token's allowance to Permit2 is too low.
  • Permit2.approve(token, UniversalRouter, …): only when the router's Permit2 allowance is too low or expired. Valid for 30 days.
  • UniversalRouter.execute with one V4_SWAP command running SWAP_EXACT_IN_SINGLE, SETTLE_ALL and TAKE_ALL. Output goes to sender; the swap reverts below minAmountOut or after deadline (20 minutes).

When tokenIn is native ETH there is nothing to approve: you get only the swap, with value set to the input amount. Send the transactions in order from sender.

Agent API (MCP)

The endpoint speaks MCP over streamable HTTP: JSON-RPC on POST, JSON responses, no sessions. Methods: initialize, ping, tools/list, tools/call. Batches are accepted. Every tool is read-only.

ToolWhat it does
decode_hookPermissions in a hook address, with capability notes. Pure.
inspect_hookFull profile of a deployed hook: bytecode, proxy, warnings, pools.
list_hooksEvery hook used by a pool, by pool count or recency.
mine_hook_saltCREATE2 salt for a hook address with the requested permissions.
list_poolsIndexed pools, filterable by hook, token, pair, hooked.
get_poolLive pool state and hook permissions.
compute_pool_idPoolId for a key. Pure.
quoteQuote through the pool's hook via the V4Quoter.
build_swapUnsigned approval and Universal Router transactions.
best_quoteBest pool for a pair, ranked.
check_poolRisk level and reasons before trading or providing liquidity.
get_statsContract addresses and index totals.
list_launch_chainsChains the launchpad runs on and the fee presets.
list_launchesTokens launched on a chain, with price and current fee.
build_launchUnsigned transaction that launches a token with the hook.


Launchpad

The launchpad launches a token with a hook built in, on every chain that has Uniswap v4. One hook contract and one launchpad contract sit at the same address on each chain. launch() deploys a fixed-supply ERC-20 (1,000,000,000, no owner, no mint), opens a native/token pool with the HookFi hook, places the whole supply in the pool as one position the launchpad can never withdraw, and makes the creator's opening buy in the same transaction.

The hook's permission bits are 0x2044: beforeInitialize (only the launchpad can open pools on it), afterSwap and afterSwapReturnDelta (it takes a fee after each swap). The fee is set per pool, up to 5%. 80% is credited to the creator and 20% to the protocol. Each pool can open at a higher launch fee, up to 90%, that falls in a straight line to the normal fee within at most an hour, so first-block bots pay the creator.

GET/v1/launch/chainsThe chains, whether the launchpad is live on each, the opening market cap, and the fee presets.
POST/v1/launch/buildchainId, name, symbol, creator, preset (standard, antisnipe, creator) or feeBps / snipeBps / snipeSecs, and buy. Returns the unsigned launch transaction and the token address it will create.
GET/v1/launch/listLaunches on a chain, newest first, with price, market cap and the fee right now.
GET/v1/launch/tokenOne launch: its fee settings and the creator's unclaimed fees.
GET/v1/launch/quotechainId, token, side (buy or sell), amount. Quoted through the hook.
POST/v1/launch/swapUnsigned Universal Router transactions for a buy or sell on that chain.
POST/v1/launch/claimUnsigned transaction that pays the caller the hook fees credited to them.
ChainIDNative coin
Robinhood Chain4663ETH
Base8453ETH
Unichain130ETH
Ethereum1ETH
Arbitrum One42161ETH
Optimism10ETH
BNB Smart Chain56BNB
Polygon137POL

Hook permissions

The PoolManager decides which hook functions to call by looking at the hook's address: the lowest 14 bits are permission flags. So you can read a hook's permissions from its address alone, offline, and they cannot change after deployment because the address cannot.

BitValueFlagCalled

The four *ReturnDelta flags let a hook change token balances, and each is only valid with the function that returns the delta. The PoolManager rejects an address that sets one without its base flag; HookFi reports it in errors and the miner refuses it (422 invalid_flags). A pool without a hook cannot use a dynamic fee, and a hook with no bits set is only valid on a dynamic-fee pool.

Reading a hook's risk profile

HookFi does not label hooks safe or unsafe. It reports what a hook is able to do, from its permission bits and its deployed bytecode. warning: the hook can move tokens in or out of your swap or position beyond the curve and the LP fee, so the quote is the only reliable number. caution: the hook can block or delay LP withdrawals. info: the hook runs at that point and can revert, but cannot change amounts on its own.

Before swapping through a hooked pool: read the pool, read the hook profile, quote through the hook, then build the swap with a slippage bound you are comfortable with.

Errors

Every error has the same shape: { "error": { "code", "message" } }.

400 bad_requestMissing or malformed input.
404 not_foundUnknown route, pool not indexed, or pool not initialized.
422 invalid_flagsMining with a *ReturnDelta flag but not its base flag.
422 no_routeThe quote reverted: no liquidity, hook rejected, amount too large.
502 upstream_errorThe Robinhood Chain RPC did not answer.

$HOOK

$HOOK is the native token of HookFi on Robinhood Chain. It has one utility: buyback and burn, funded by trading fees. A share of $HOOK trading fees buys it on the open market and sends it to 0x000000000000000000000000000000000000dEaD, and every roadmap phase that ships raises that share. GET /v1/token returns the supply, the amount burned and every burn, read from the chain on each request. The API, SDK and MCP server do not require $HOOK.

PhaseTech
1 · liveHook API, Hook Miner, Pool API, Quote and Swap API, MCP server with 15 tools, SDK, hook explorer, permission census, multi-chain launchpad with the hook built in.
2Agent plugin for Cursor and Claude Code, routing across multiple pools.
3Hook monitoring: alerts when a hook is upgraded, a pool's risk changes, or new pools appear.
4More chains with Uniswap v4.