# Hookr agent skill

Read any Hookr pool's rules, quote and swap on it, provide liquidity, open a market, and claim
what a pool owes you. No account, no API key. Every call is a direct chain read or a signed
transaction; nothing proxies through Hookr's servers. Paths are relative to https://hookr.fun.

## Chain

- Chain: Robinhood Chain, chain id 4663
- Public RPC: https://rpc.mainnet.chain.robinhood.com
- Explorer: https://robinhoodchain.blockscout.com

## Addresses

Deployed from source commit `3371e9bb (sources) / 8db7fc94 (release profile, script)`; a redeploy changes these, so re-read this
file for the current set.

- Root hook: `0xb3cA29cF721380CEe8b8e4755F3865Ebc68Fe8cC`
- Coordinator: `0x53A192A3fCeE94Da77916B461E0cCa2Dd6402442`
- Router: `0xf0E528c39f33F565876cbaa7e0DFaCa38Df966E9`
- Quoter: `0x5Ba8FBbB4aB20Ff6Daf0ecDEBe3784f869BcB1B5`
- Mechanics block: `0xD700492b504ba5A72D7de28dDe11Cd7985a7F1ae`
- Registry: `0x5b7f1A117A83aaac15B0698Aa4eB9D53fE5f5BA3`
- Forwarder: `0x9BB7c01571ef6e59a8834A6a89A6b024822BAf6f`
- PoolManager: `0x8366a39CC670B4001A1121B8F6A443A643e40951`
- PositionManager: `0x58daec3116aae6D93017bAAea7749052E8a04fA7`
- Permit2: `0x000000000022D473030F116dDEE9F6B43aC78BA3`

Ids: kernelId `0x1be0c118b1c6520d97de31ee9f0c33069f0e715ffcdcb16c87a343752bb5be14`, moduleId `0x961091565aaf4eaa4996296fda9772957e61d18d90b965111a59ded2bbb5e774`.

The Universal Router's address on chain 4663 is not pinned here: Hookr's own records
show two official sources disagreeing on it. Resolve it yourself, or use the pinned Hookr
router below.

## Pool key and pool id

```
PoolKey = {
  currency0: lower(subject, quote),  // numeric compare; 0x0 (ETH) sorts first
  currency1: higher(subject, quote),
  fee: 8388608,                       // dynamic-fee flag, not a real fee
  tickSpacing: <your choice, 60 is typical>,
  hooks: rootHook,
}
poolId = keccak256(abi.encode(PoolKey))  // bytes32; PoolKey is a static 160-byte tuple
```

Or read it back: `marketCoordinator.poolKeyFor(subject, market) view returns (PoolKey)`.

## Read a pool's rules

```
stackRegistry.stack(poolId) view returns (StackCore core)  // core.moduleCount, core.limits
stackRegistry.moduleAt(poolId, i) view returns (ModuleSnapshot, bytes config)
```

Loop `i` 0..moduleCount-1 and match `moduleId` to the id above (usually index 0). Decode its
`config` as `HookrNativeMechanicsBlockV2.Config` (640 bytes, 20 fields), in order:

- `poolId` bytes32: pool id
- `kernel` address: root hook
- `subject` address: token being priced
- `quote` address: quote currency; 0x0 = ETH
- `lockedLiquidityProvider` address: coordinator if guard is on, else 0x0
- `guardEndBlock` uint40: guard-close block, 0 = off
- `baseFeePips` uint24: base LP fee (pips)
- `maxFeePips` uint24: surge ceiling (pips)
- `snipeTaxPips` uint24: guard buy surcharge (pips)
- `surgeSens` uint16: surge speed, 0-10
- `burnBps` uint16: buy-output burn share (bps)
- `lpBps` uint16: buy-input LP share (bps)
- `potBps` uint16: buy-input pot share (bps)
- `royaltyBps` uint16: royalty share of cuts (bps)
- `potEveryNBuys` uint32: buys between pot payouts
- `maxBuyQuoteAmount` uint96: per-block guard cap, 0 = off
- `potMinBuyWei` uint96: min buy that advances the pot
- `royaltyTo` address: royalty recipient
- `protocolRecipient` address: must equal treasury forwarder
- `protocolShareBps` uint24: protocol cut per add-on (bps)

Full validation rules: /docs/reference/config-schema-and-limits.

## Quote and swap

Hookr quoter (includes the pot leg; not `view`, run it with `eth_call`):

```
kernelQuoter.quote(
  { key, payer, recipient, zeroForOne, amountSpecified, amountBound, sqrtPriceLimitX96 },
  hookData,
) returns (uint256 amountIn, uint256 amountOut)
```

`amountSpecified` is negative for exact input. Pass the real `recipient`: the pot leg is
recipient-specific.

Hookr router (eligible for the pot; it authenticates hookData itself, pass `0x`):

```
kernelRouter.exactInput({ key, zeroForOne, amountIn, amountOutMinimum, sqrtPriceLimitX96,
  recipient, deadline }, 0x) returns (uint256 amountOut)
```

`exactOutput` mirrors it: `amountOut`/`amountInMaximum` in place of
`amountIn`/`amountOutMinimum`, returns `amountIn`.

Any input cut (LP reward, pot, surge, snipe tax or burn) requires the canonical full-fill
limit on an exact-input buy: `4295128740` if `zeroForOne`, else
`1461446703485210103287273052203988822378723970341`. Anything else reverts. Never send `amountOutMinimum` (or
`amountBound`) as zero.

Universal Router: a `V4_SWAP` command, same `PoolKey`, empty `hookData`. Every rule applies
except the pot leg. Quote it with Uniswap's `V4Quoter`, not the quoter above; the two disagree
by the pot's share.

## Provide liquidity

Uniswap v4 `PositionManager`, the ordinary way:

```
Actions.MINT_POSITION(poolKey, tickLower, tickUpper, liquidity, amount0Max, amount1Max, owner, hookData=0x)
Actions.SETTLE_PAIR(currency0, currency1)
```

Approve an ERC-20 leg to Permit2, then PositionManager as a Permit2 spender. A new-token pool
blocks outside liquidity while its guard is open (`guardEndBlock != 0 && block.number <
guardEndBlock`, read as above): anyone but the coordinator reverts until it closes.

## Open a market

Both lanes read your tier first: `marketCoordinator.protocolShareBps(you) view returns
(uint24)` (default 2000 bps, ceiling 5000 bps);
your config's `protocolShareBps` must equal it exactly or admission reverts.

New-token lane: a fixed-supply ERC-20 (1,000,000,000 tokens), whole supply in one sell
band, optional creator buy, one transaction.

```
marketCoordinator.openNewTokenMarket{value}(NewTokenArgs args, bytes32 intentId, address expectedToken)
  returns (address subject, PoolId poolId)
```

`NewTokenArgs = { name, symbol, tagline, logoURI, expectedCreator, totalSupply, deploymentSalt,
market: MarketParams, initialBuy: InitialBuyParams }`. Every new-token pool opens at a fixed
2.5 ETH whole-supply valuation: tick 198060 at tickSpacing 60 against
native ETH, no conversion needed; against another quote, convert it at a live reference price
first. The founding band is 207000 ticks wide and single-sided in the subject. A
guard window, when used, is `block.number + N` capped at 100000 blocks. A
creator buy may not exceed 50,000,000 tokens (5% of supply).

Existing-asset lane: a fresh pool for a token that already exists, no liquidity, no guard, no
creator buy.

```
marketCoordinator.openExistingTokenMarket(ExistingTokenArgs args) returns (PoolId poolId)
```

`ExistingTokenArgs = { subject, market: MarketParams }`. Pick your own `baseFeePips` here
(500, 3000, 10000 mirror Uniswap's 0.05%/0.30%/1.00% tiers); base fee, surge headroom and
snipe tax together must stay under 500000 pips (50%).

## Claim

```
nativeMechanicsBlock.claimable(quote, account) view returns (uint256)
nativeMechanicsBlock.claim(quote)        // pays msg.sender
nativeMechanicsBlock.claimTo(quote, to)  // pays to
marketCoordinator.collectLpFees(poolId) returns (uint256 amount0, uint256 amount1)
```

`claim`/`claimTo` pay pot winnings and royalties, pooled per quote currency across every
pool; read `claimable` first, a zero balance reverts. `collectLpFees` pays a new-token
market's founding fees, 100%, to `lpFeeRecipient`; anyone may call it; it reverts on an
existing-asset market, which has none.

## Public JSON routes

- `GET /api/protocol-stats`: block-pinned protocol metrics
- `GET /api/hooks/catalog`: the root hook and its rules
- npm: `hookr-sdk`
- `GET /api/hooks/integrations`: external hook catalog
- `GET /api/integrations/tracks`: partner integration tracks
- `GET /api/integrations/manifest`: integration intake links
- `GET /api/pool-apr?pools=<comma-separated PoolIds>`: estimated APR, up to 50 pools
- `GET /api/discover/pools`, `.../snapshot`, `.../volumes`: pool discovery data

## Safety rules

1. Quote before every swap, with a real minimum out.
2. Read the guard window and every rule before trading a new token.
3. Never sign what the simulation did not pass.
4. Every figure above is a chain read at one block. Re-read it before you rely on it.

Full docs: /docs. Source and review: https://github.com/Hookr-fun/hookr-contracts.