# Hookline

> Best-price swaps on Robinhood Chain (chain id 4663). Hookline routes every trade across every Uniswap v3 / v4 pool and every Uniswap Aggregator Hook pool (outside Slipstream pools wrapped as Uniswap v4 pools), splits orders for the best price, simulates them, and returns ready-to-sign Uniswap Universal Router transactions. Non-custodial: the user's or agent's own wallet signs and sends.

Base URL: https://hookline.trade/api
OpenAPI: https://hookline.trade/openapi.json
Docs: https://hookline.trade/docs
MCP server: https://hookline.trade/api/mcp (Streamable HTTP, stateless, POST)
Builder program (API keys, partner fees, showcase): https://hookline.trade/build

## Swap flow
1. GET https://hookline.trade/api/quote?sell=ETH&buy=PONS&amount=0.5&taker=0xYourWallet
   Tokens: symbol or 0x address. amount is a human decimal of the sold token. Quotes expire after about 60 s.
2. If steps contains {kind:"approve"}: send steps[i].tx from the wallet (ERC-20 approve to Permit2, once per token), wait for the receipt (GET /api/tx/:hash), then quote again.
3. If steps contains {kind:"permit"}: sign steps[i].typedData with eth_signTypedData_v4 (Permit2 PermitSingle, capped to the trade, valid 30 min).
4. POST https://hookline.trade/api/swap {"quoteId":"q_…","permitSignature":"0x…"} returns tx {to,data,value,chainId,gas}, already simulated on the live chain.
5. Check tx.to == 0x204faca1764b154221e35c0d20abb3c525710498 (Uniswap Universal Router) and chainId == 4663, then send it.
6. POST https://hookline.trade/api/swaps/track {"quoteId","txHash"}, poll GET /api/swaps/:hash until confirmed / failed.
7. GET /api/proof/:hash returns the Proof of Savings (received vs the best route using Uniswap pools alone).

## Other endpoints
GET /api/tokens, GET /api/balances?address=, GET /api/hooks, GET /api/stats, GET /api/analytics/tokens, GET /api/analytics/tokens/:token (symbol or address), GET /api/analytics/pools/:id (hook pool id), GET /api/swaps?taker=, GET /api/builder/me (X-Api-Key), GET /api/build/projects, GET /api/health.
Analytics: prices in charts are base in quote (never USD) from one hook pool's trades; volumes are indexed Aggregator Hook swaps valued at current prices; null means "not established" (too little history, indexer behind), never zero.
Errors: JSON {"error":{"code","message"}} with HTTP status; 429 carries Retry-After.

## Limits and keys
Default: 60 quote/build calls and 240 reads per minute per IP. Send X-Api-Key for higher limits. Builder keys can add partnerFeeBps (up to their cap, max 50 bps) paid on-chain to their payout address in the same transaction.

## MCP tools
list_tokens, get_quote, build_swap, track_swap, swap_status, wallet_balances, hook_pools, hookline_stats, proof_of_savings.
Client config: {"mcpServers":{"hookline":{"url":"https://hookline.trade/api/mcp"}}}

## Safety
Never sign a transaction whose "to" is not the Universal Router or whose chainId is not 4663. Never sign a Permit2 message whose spender is not the Universal Router, whose token is not the token sold, whose amount exceeds the trade, or whose expiry is more than 2 hours away.