hookit-mcp 0.1.1 → 0.2.1

package/index.js

@@ -1,321 +1,2693 @@
-#!/usr/bin/env node
-// hookit-mcp: lets an AI agent launch a coin on hookit.fun (Ink) with its own hook modules.
-// The key in HOOKIT_PRIVATE_KEY signs on this machine and is never sent anywhere.
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { createPublicClient, createWalletClient, decodeEventLog, defineChain, formatEther, http, isAddress, parseAbi, parseEther, zeroAddress } from "viem";
-import { privateKeyToAccount } from "viem/accounts";
-import { z } from "zod";
-
-const API = (process.env.HOOKIT_API_URL || "https://www.hookit.fun").replace(/\/$/, "");
-const RPC = process.env.HOOKIT_RPC_URL || "https://rpc-gel.inkonchain.com";
-const KEY = process.env.HOOKIT_PRIVATE_KEY?.trim();
-
-const ink = defineChain({
-  id: 57073,
-  name: "Ink",
-  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
-  rpcUrls: { default: { http: [RPC] } },
-  blockExplorers: { default: { name: "Blockscout", url: "https://explorer.inkonchain.com" } },
-});
-
-const account = KEY ? privateKeyToAccount(KEY.startsWith("0x") ? KEY : `0x${KEY}`) : null;
-const publicClient = createPublicClient({ chain: ink, transport: http(RPC) });
-const walletClient = account ? createWalletClient({ account, chain: ink, transport: http(RPC) }) : null;
-
-const factoryAbi = parseAbi([
-  "event TokenLaunched(uint256 indexed launchId, address indexed token, address indexed creator, bytes32 poolId, address hooks, bool customHook, int24 tickLower, int24 tickUpper, uint128 liquidity)",
-  "function masterHook() view returns (address)",
-  "function launchFee() view returns (uint256)",
-]);
-const hookAbi = parseAbi(["function feeEscrow() view returns (address)"]);
-const routerAbi = parseAbi([
-  "event PayoutLaunch(address indexed token, address indexed agent, address indexed controller, uint8 provider, uint256 accountId, address wallet)",
-]);
-const escrowAbi = parseAbi([
-  "function balanceOf(address account, address currency) view returns (uint256)",
-  "function claimAll(address[] currencies)",
-]);
-const erc20Abi = parseAbi(["function symbol() view returns (string)", "function decimals() view returns (uint8)"]);
-
-let catalogCache = null;
-async function catalog() {
-  if (catalogCache) return catalogCache;
-  const res = await fetch(`${API}/api/agents/catalog`);
-  if (!res.ok) throw new Error(`hookit catalog unavailable (${res.status})`);
-  catalogCache = await res.json();
-  return catalogCache;
-}
-
-function reply(value) {
-  return { content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }] };
-}
-function fail(message) {
-  return { content: [{ type: "text", text: message }], isError: true };
-}
-function needKey() {
-  return fail("No wallet. Set HOOKIT_PRIVATE_KEY in this server's env to a wallet funded for launches and nothing else.");
-}
-
-const launchShape = {
-  name: z.string().describe("Coin name, up to 32 characters."),
-  symbol: z.string().describe("Ticker, 1 to 12 letters or digits."),
-  description: z.string().optional(),
-  image: z.string().optional().describe("Logo as an https:// or ipfs:// URL."),
-  twitter: z.string().optional(),
-  telegram: z.string().optional(),
-  website: z.string().optional(),
-  pair: z.string().optional().describe("What the coin is priced in. Default eth. See list_pairs."),
-  pairs: z.array(z.string()).optional().describe("Several pairs for a multi-pair launch (USDG and stocks only)."),
-  preset: z.string().optional().describe("A strategy from list_presets: clean, community, deflationary, floor, builder, dynamic."),
-  hookTaxPct: z.number().optional().describe("Extra swap fee feeding the hook modules, 0 to 9."),
-  modules: z.record(z.union([z.boolean(), z.number()])).optional().describe("Module settings from list_modules, e.g. {\"autoBurn\": true, \"autoBurnPct\": 100}. Without a preset they start from a clean slate."),
-  devBuyPct: z.number().optional().describe("Creator's own first buy in the launch tx, % of supply (up to 2.5, less with Max Tx). No sniper tax on it."),
-  payout: z
-    .object({
-      kind: z.enum(["wallet", "x", "github", "tiktok"]),
-      address: z.string().optional(),
-      handle: z.string().optional(),
-      accountId: z.string().optional(),
-    })
-    .optional()
-    .describe("Who receives the creator fees. Default: the launching wallet."),
-};
-
-async function prepare(args) {
-  const res = await fetch(`${API}/api/agents/prepare-launch`, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({ ...args, from: account?.address }),
-  });
-  const body = await res.json().catch(() => ({ ok: false, error: `hookit answered ${res.status}` }));
-  if (!res.ok && !body.error) body.error = `hookit answered ${res.status}`;
-  return body;
-}
-
-const server = new McpServer({ name: "hookit", version: "0.1.1" });
-
-server.registerTool(
-  "list_presets",
-  {
-    description: "Launch strategies by goal (clean, community, deflationary, floor, builder, dynamic) with the exact hook modules each one turns on. Needs no key.",
-    inputSchema: {},
-    annotations: { readOnlyHint: true },
-  },
-  async () => {
-    const c = await catalog();
-    return reply(c.presets.map(({ id, label, goal, settings, singlePairOnly }) => ({ id, label, goal, settings, singlePairOnly })));
-  },
-);
-
-server.registerTool(
-  "list_modules",
-  {
-    description: "Every hook module an agent can combine, what it does, its settings and the rules a combination must follow. Needs no key.",
-    inputSchema: {},
-    annotations: { readOnlyHint: true },
-  },
-  async () => {
-    const c = await catalog();
-    return reply({ modules: c.modules, rules: c.rules });
-  },
-);
-
-server.registerTool(
-  "list_pairs",
-  {
-    description: "What a coin can be priced in (ETH, USDG, kHYPE, kBTC, HKT, tokenized stocks), and which can be combined in a multi-pair launch. Needs no key.",
-    inputSchema: {},
-    annotations: { readOnlyHint: true },
-  },
-  async () => reply((await catalog()).pairs),
-);
-
-server.registerTool(
-  "wallet_status",
-  {
-    description: "Says in words whether the wallet can launch: its address, ETH balance and the launch fee.",
-    inputSchema: {},
-    annotations: { readOnlyHint: true },
-  },
-  async () => {
-    if (!account) return needKey();
-    const c = await catalog();
-    const [balance, fee] = await Promise.all([
-      publicClient.getBalance({ address: account.address }),
-      c.factory ? publicClient.readContract({ address: c.factory, abi: factoryAbi, functionName: "launchFee" }).catch(() => null) : null,
-    ]);
-    const gasPrice = await publicClient.getGasPrice();
-    const needed = (fee ?? 0n) + gasPrice * 4_000_000n;
-    return reply({
-      address: account.address,
-      chain: "Ink (57073)",
-      balanceEth: formatEther(balance),
-      launchFeeEth: fee === null ? "unknown" : formatEther(fee),
-      roughCostEth: formatEther(needed),
-      ready: balance >= needed,
-      verdict:
-        balance >= needed
-          ? "Ready to launch."
-          : `Not enough ETH on Ink. Send about ${formatEther(needed - balance)} ETH more to ${account.address}.`,
-      ...(balance >= needed
-        ? {}
-        : {
-            howToFund:
-              "Withdraw ETH from Kraken straight to Ink (choose the Ink network), or bridge from another chain. With the Kraken CLI MCP loaded, an agent can do the withdrawal itself; the user must first whitelist this address in Kraken.",
-          }),
-    });
-  },
-);
-
-server.registerTool(
-  "launch_token",
-  {
-    description:
-      "Launches a coin on hookit.fun with the chosen preset or hook modules, in one call. With dryRun it only checks the launch and returns the unsigned transaction: use it first and show the user the settings.",
-    inputSchema: { ...launchShape, dryRun: z.boolean().optional().describe("Check and simulate only. Signs nothing.") },
-  },
-  async ({ dryRun, ...args }) => {
-    if (!dryRun && !account) return needKey();
-    let prepared = await prepare(args);
-    if (prepared.error) return fail(prepared.error);
-    if (!dryRun && prepared.approve) {
-      // ERC-20 dev buy: approve the pair token, then prepare again so the launch is simulated.
-      const approveHash = await walletClient.sendTransaction({
-        to: prepared.approve.tx.to,
-        data: prepared.approve.tx.data,
-      });
-      await publicClient.waitForTransactionReceipt({ hash: approveHash });
-      prepared = await prepare(args);
-      if (prepared.error) return fail(prepared.error);
-    }
-    if (dryRun) {
-      return reply({
-        dryRun: true,
-        verdict: prepared.simulation?.needsApproval
-          ? "Valid. A real launch will first approve the dev buy token, then launch."
-          : prepared.simulation?.ok === false
-            ? `The launch would fail: ${prepared.simulation.error}`
-            : "The launch is valid.",
-        plan: prepared.plan,
-        approveFirst: prepared.approve ?? null,
-        tx: prepared.tx,
-        warnings: prepared.warnings,
-      });
-    }
-    if (prepared.simulation && !prepared.simulation.ok) {
-      return fail(`The launch would fail: ${prepared.simulation.error}\nSettings: ${prepared.plan.settings.join("; ")}`);
-    }
-
-    const hash = await walletClient.sendTransaction({
-      to: prepared.tx.to,
-      data: prepared.tx.data,
-      value: BigInt(prepared.tx.value),
-      gas: BigInt(prepared.tx.gas),
-    });
-    const receipt = await publicClient.waitForTransactionReceipt({ hash });
-    if (receipt.status !== "success") return fail(`Launch transaction reverted: ${hash}`);
-    let token = null;
-    let agent = null;
-    for (const log of receipt.logs) {
-      for (const abi of [factoryAbi, routerAbi]) {
-        try {
-          const ev = decodeEventLog({ abi, data: log.data, topics: log.topics });
-          if (ev.eventName === "TokenLaunched") token = ev.args.token;
-          if (ev.eventName === "PayoutLaunch") agent = ev.args.agent;
-        } catch {}
-      }
-    }
-    return reply({
-      launched: true,
-      token,
-      page: token ? `${API}/token/${token}` : null,
-      tx: `https://explorer.inkonchain.com/tx/${hash}`,
-      settings: prepared.plan.settings,
-      payout: prepared.plan.payout,
-      payoutAgent: agent,
-      note: agent
-        ? "Creator fees go to the payout target through this launch's CreatorPayoutAgent. This wallet is its controller."
-        : "Creator fees build up in FeeEscrow for this wallet. Call claim_fees to collect them.",
-    });
-  },
-);
-
-server.registerTool(
-  "claim_fees",
-  {
-    description: "Collects the creator fees this wallet has earned on coins it launched itself (paid in ETH and the pair tokens).",
-    inputSchema: {
-      currencies: z.array(z.string()).optional().describe("Token addresses to collect. Default: ETH plus every pair token."),
-    },
-  },
-  async ({ currencies }) => {
-    if (!account) return needKey();
-    const c = await catalog();
-    if (!c.factory) return fail("Launches are not configured on this hookit.");
-    const hook = await publicClient.readContract({ address: c.factory, abi: factoryAbi, functionName: "masterHook" });
-    const escrow = await publicClient.readContract({ address: hook, abi: hookAbi, functionName: "feeEscrow" });
-    const candidates = currencies?.length ? currencies : [zeroAddress, ...(c.pairAddresses ?? [])];
-    const owed = [];
-    for (const currency of candidates) {
-      const amount = await publicClient.readContract({ address: escrow, abi: escrowAbi, functionName: "balanceOf", args: [account.address, currency] });
-      if (amount > 0n) owed.push({ currency, amount });
-    }
-    if (owed.length === 0) return reply("Nothing to collect yet.");
-    const hash = await walletClient.writeContract({ address: escrow, abi: escrowAbi, functionName: "claimAll", args: [owed.map((o) => o.currency)] });
-    await publicClient.waitForTransactionReceipt({ hash });
-    const lines = [];
-    for (const { currency, amount } of owed) {
-      if (currency === zeroAddress) {
-        lines.push(`${formatEther(amount)} ETH`);
-        continue;
-      }
-      const [symbol, decimals] = await Promise.all([
-        publicClient.readContract({ address: currency, abi: erc20Abi, functionName: "symbol" }).catch(() => currency),
-        publicClient.readContract({ address: currency, abi: erc20Abi, functionName: "decimals" }).catch(() => 18),
-      ]);
-      lines.push(`${Number(amount) / 10 ** Number(decimals)} ${symbol}`);
-    }
-    return reply({ collected: lines, tx: `https://explorer.inkonchain.com/tx/${hash}` });
-  },
-);
-
-server.registerTool(
-  "send_eth",
-  {
-    description:
-      "Sends ETH from this wallet on Ink, for example to cash out to the user's Kraken ETH deposit address on the Ink network (get it with the Kraken MCP deposit addresses tool for the \"ETH - Ink\" method only). Kraken's minimum ETH deposit on Ink is 0.001 ETH; smaller deposits fail and the funds are lost, so never send less. Run it with dryRun first and repeat the address and amount to the user before sending.",
-    inputSchema: {
-      to: z.string().describe("Destination address on Ink."),
-      amountEth: z.string().describe('Amount in ETH, or "max" to send everything except gas.'),
-      dryRun: z.boolean().optional().describe("Check only. Signs nothing."),
-    },
-  },
-  async ({ to, amountEth, dryRun }) => {
-    if (!account) return needKey();
-    if (!isAddress(to)) return fail(`Not an address: ${to}`);
-    const [balance, gasPrice] = await Promise.all([publicClient.getBalance({ address: account.address }), publicClient.getGasPrice()]);
-    // A plain transfer is 21k gas; keep extra for the L1 data fee.
-    const gasReserve = gasPrice * 60_000n + 20_000_000_000_000n;
-    let value;
-    if (amountEth.trim().toLowerCase() === "max") {
-      value = balance > gasReserve ? balance - gasReserve : 0n;
-    } else {
-      try {
-        value = parseEther(amountEth.trim());
-      } catch {
-        return fail(`Not an amount: ${amountEth}`);
-      }
-    }
-    if (value <= 0n) return fail(`Nothing to send: the wallet holds ${formatEther(balance)} ETH.`);
-    if (value + gasReserve > balance) {
-      return fail(`Not enough ETH: the wallet holds ${formatEther(balance)} ETH and needs some left for gas.`);
-    }
-    if (dryRun) return reply({ dryRun: true, from: account.address, to, amountEth: formatEther(value), verdict: "Ready to send." });
-    const hash = await walletClient.sendTransaction({ to, value });
-    await publicClient.waitForTransactionReceipt({ hash });
-    return reply({ sentEth: formatEther(value), to, tx: `https://explorer.inkonchain.com/tx/${hash}` });
-  },
-);
-
-await server.connect(new StdioServerTransport());
+#!/usr/bin/env node
+// hookit-mcp: lets an AI agent launch a coin on hookit.fun (Ink) with its own hook modules, find coins, buy and sell
+// them with ETH, USDG, kBTC or tokenized stocks (swapped through Relay when the coin trades in something else;
+// AI-agents-only coins too, with a Hookit Agent Pass), redeem them at their Backed Floor or borrow against it, and
+// collect its creator fees.
+// The key in HOOKIT_PRIVATE_KEY signs on this machine and is never sent anywhere.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  createPublicClient,
+  createWalletClient,
+  decodeEventLog,
+  decodeFunctionData,
+  defineChain,
+  encodeAbiParameters,
+  encodeFunctionData,
+  formatEther,
+  formatUnits,
+  getAddress,
+  http,
+  isAddress,
+  keccak256,
+  maxUint256,
+  parseAbi,
+  parseEther,
+  parseUnits,
+  toHex,
+  zeroAddress,
+  zeroHash,
+} from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { z } from "zod";
+
+const API = (process.env.HOOKIT_API_URL || "https://www.hookit.fun").replace(/\/$/, "");
+const RPC = process.env.HOOKIT_RPC_URL || "https://rpc-gel.inkonchain.com";
+const KEY = process.env.HOOKIT_PRIVATE_KEY?.trim();
+const VERSION = "0.2.1";
+const EXPLORER = "https://explorer.inkonchain.com";
+/**
+ * The Ink deployments this server signs against. Pinned here, never taken from hookit.fun's catalog: a compromised
+ * site must not be able to point an approval, a value transfer or a quote at another contract. A Hookit redeploy
+ * needs a new hookit-mcp release.
+ */
+const PINNED = {
+  factory: "0x145c3F3560c23fDA93eA79f2EfeB7f33D8A9Ff3e", // LaunchFactoryC: new launches
+  factories: [
+    "0x145c3F3560c23fDA93eA79f2EfeB7f33D8A9Ff3e", // LaunchFactoryC
+    "0x99C6f8921858660881186296c39a07d1B30Dc039", // Master LaunchFactory gen 3
+    "0x2851Cb70a6784ae69B45E6b7065908A00176322F", // Master LaunchFactory gen 2
+    "0xAB6eaE3092AE574BEF0A16505FDf137072DCafdd", // Master LaunchFactory gen 1
+  ],
+  payoutRouter: "0x9d1C8384fdAf2597C41FA2af0c2f16049CaF550C", // CreatorPayoutRouterC
+  swapRouter: "0xb099176151Ecde2E194CCa23E491413f789D1Cb7", // HookitSwapRouter
+  usdg: "0xe343167631d89B6Ffc58B88d6b7fB0228795491D", // Paxos USDG, 6 decimals
+  v4Quoter: "0x3972C00f7ed4885e145823eb7C655375d275A1C5", // Uniswap V4Quoter
+  routeConfig: "0x34D6C456A31d50829Ca572D019E1E3410A5D05E3", // RouteConfigC: names the v2 aggregator
+  aggregator: "0x6518b4b2D77F8351F8cE7C9BA1ca7E6D8631D210", // BalancedAggregatorC (USDG in / out on v2 coins)
+  loanPlugin: "0xA9e9347175B1d128478D0DdA475dE5a11C33DBB4", // FloorLoanPlugin
+  gatedBuyPlugin: "0x4af18ddf7Ccbb0d30DE397B8ebdc873f98BFA9f3", // GatedBuyPlugin
+  agentPass: "0xe847CCD9EcD9889c39B381C83B33e0251759Cf67", // HookitAgentPass
+  agentValidator: "0x7A9365784b438D327D468b717dd644fd0fB09fa7", // HookitAgentValidator (ERC-8004)
+};
+/** Tickers payWith / receive accept, besides "eth" and "usdg" (the catalog's list is only a fallback). */
+const KNOWN_ASSETS = {
+  kbtc: "0x73E0C0d45E048D25Fc26Fa3159b0aA04BfA4Db98",
+  khype: "0xAd09Cd20e513E4d8cB78036F77Ab9AfdE8555929",
+  waaplx: "0x943BF64D566c32A2Bcd41AC92FB63C111cC9De8f",
+  wamznx: "0x910cabdE3EBa7Fc1Ce64fD14bD680b9f60fA0F90",
+  wgooglx: "0xf8c5308F80E459bb53d9EbE689854d9cBb2Caa6f",
+  wmcdx: "0xc6639026a3a862cd4fcbae3f67cB2D25A2959d37",
+  wmstrx: "0x30987adF0B11dc698438a99BA04ec3a1AB2c7EaB",
+  wnflxx: "0x7d87fD6A379714194a797c0bBB8B40c30D250856",
+  wnvdax: "0xa8ddb5Cd96b5222AFe198316E9A57CAA642850D5",
+  wspyx: "0xE7E553Cd128F0011777323A0b44a7b96EA1CB540",
+  wtslax: "0xc3FdBe3A68EE5dE461D30415a8165cf9Aefe1171",
+};
+/** Largest single buy paid in ETH (HOOKIT_MAX_BUY_ETH overrides it): a typo must not empty the wallet. */
+const MAX_BUY_WEI = (() => {
+  try {
+    const v = parseEther((process.env.HOOKIT_MAX_BUY_ETH || "0.5").trim());
+    return v > 0n ? v : parseEther("0.5");
+  } catch {
+    return parseEther("0.5");
+  }
+})();
+/** Largest single buy paid in a token (USDG, a stock, kBTC), in US dollars (HOOKIT_MAX_BUY_USD overrides it). */
+const MAX_BUY_USD = (() => {
+  const v = Number((process.env.HOOKIT_MAX_BUY_USD || "1000").trim());
+  return Number.isFinite(v) && v > 0 ? v : 1000;
+})();
+/** Ink's per-transaction gas cap (2^24). */
+const MAX_TX_GAS = 16_777_216n;
+/** Gas floor for a swap through a hooked pool (the hook's modules can do a lot of work). */
+const SWAP_MIN_GAS = 650_000n;
+/** FloorLoanPlugin durations (days) and their upfront fee (bps of the loan). */
+const LOAN_FEES_BPS = { 7: 100, 14: 175, 30: 300, 60: 500, 90: 700 };
+const ETH = { address: zeroAddress, symbol: "ETH", decimals: 18 };
+
+const ink = defineChain({
+  id: 57073,
+  name: "Ink",
+  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+  rpcUrls: { default: { http: [RPC] } },
+  blockExplorers: { default: { name: "Blockscout", url: "https://explorer.inkonchain.com" } },
+});
+
+const account = KEY ? privateKeyToAccount(KEY.startsWith("0x") ? KEY : `0x${KEY}`) : null;
+// Ink makes a block a second: poll receipts at that pace rather than viem's 4 s default.
+const publicClient = createPublicClient({ chain: ink, transport: http(RPC), pollingInterval: 1_000 });
+const walletClient = account ? createWalletClient({ account, chain: ink, transport: http(RPC) }) : null;
+
+const factoryAbi = parseAbi([
+  "event TokenLaunched(uint256 indexed launchId, address indexed token, address indexed creator, bytes32 poolId, address hooks, bool customHook, int24 tickLower, int24 tickUpper, uint128 liquidity)",
+  "function masterHook() view returns (address)",
+  "function launchFee() view returns (uint256)",
+]);
+const hookAbi = parseAbi(["function feeEscrow() view returns (address)"]);
+const routerAbi = parseAbi([
+  "event PayoutLaunch(address indexed token, address indexed agent, address indexed controller, uint8 provider, uint256 accountId, address wallet)",
+]);
+const escrowAbi = parseAbi([
+  "function balanceOf(address account, address currency) view returns (uint256)",
+  "function claimAll(address[] currencies)",
+]);
+const erc20Abi = parseAbi([
+  "function symbol() view returns (string)",
+  "function decimals() view returns (uint8)",
+  "function balanceOf(address) view returns (uint256)",
+  "function totalSupply() view returns (uint256)",
+  "function allowance(address owner, address spender) view returns (uint256)",
+  "function approve(address spender, uint256 amount) returns (bool)",
+]);
+const launchLookupAbi = parseAbi([
+  "function tokenLaunchId(address token) view returns (uint256)",
+  "function poolKeyOf(uint256 launchId) view returns ((address currency0, address currency1, uint24 fee, int24 tickSpacing, address hooks))",
+  "function launchMarketCount(uint256 launchId) view returns (uint8)",
+  "function poolKeyOfMarket(uint256 launchId, uint256 marketIndex) view returns ((address currency0, address currency1, uint24 fee, int24 tickSpacing, address hooks))",
+]);
+const swapRouterAbi = parseAbi([
+  "function swapExactIn((address currency0, address currency1, uint24 fee, int24 tickSpacing, address hooks) key, bool zeroForOne, uint256 amountIn, uint256 minAmountOut, uint160 sqrtPriceLimitX96) payable returns (uint256 amountOut)",
+]);
+/** Uniswap's V4Quoter: what a one-pool exact-input swap returns, hook included (eth_call only). */
+const quoterAbi = parseAbi([
+  "function quoteExactInputSingle(((address currency0, address currency1, uint24 fee, int24 tickSpacing, address hooks) poolKey, bool zeroForOne, uint128 exactAmount, bytes hookData) params) returns (uint256 amountOut, uint256 gasEstimate)",
+  "error UnexpectedRevertBytes(bytes revertData)",
+  "error NotEnoughLiquidity(bytes32 poolId)",
+]);
+/** NotEnoughLiquidity(bytes32): the pool could not fill the whole amount (V4Quoter wraps it in UnexpectedRevertBytes). */
+const NOT_ENOUGH_LIQUIDITY = "7a5ed734";
+/** BalancedAggregatorC: USDG in or out on a v2 coin, bridged to the market's quote when it is a stock or ETH. */
+const aggregatorAbi = parseAbi([
+  "struct RouteLeg { uint8 marketIndex; uint8 venue; uint256 amountIn; uint256 minAmountOut; }",
+  "function factory() view returns (address)",
+  "function buyExactInput(uint256 launchId, address token, uint256 amountIn, uint256 minTotalOut, RouteLeg[] legs, address recipient, uint256 deadline) returns (uint256 totalOut)",
+  "function sellExactInput(uint256 launchId, address token, uint256 amountIn, uint256 minTotalOut, RouteLeg[] legs, address recipient, uint256 deadline) returns (uint256 totalOut)",
+  "function quoteExactInput(bool isBuy, uint256 launchId, address token, uint256 amountIn, RouteLeg[] legs, address recipient) returns (uint256[] legOuts, uint256 totalOut)",
+  "error InsufficientOutput()",
+  "error UnsupportedQuote()",
+  "error UnsupportedVenue()",
+  "error Expired()",
+]);
+const routeConfigAbi = parseAbi([
+  "function aggregator() view returns (address)",
+  "function bridgeOf(address quote) view returns ((uint24 fee, int24 tickSpacing, address hooks, bool enabled))",
+  "function bridgeV3Of(address quote) view returns ((address pool, uint24 fee, bool enabled))",
+]);
+/** FloorVault (v1) and FloorVaultC (v2): the Backed Floor reserve of a coin; `floorState` is v2 only. */
+const floorVaultAbi = parseAbi([
+  "function floorVault() view returns (address)",
+  "function redeemFloor(address token, uint256 tokenAmount) returns (uint256 quoteOut)",
+  "function reserve(address token) view returns (uint256)",
+  "function quoteOf(address token) view returns (address)",
+  "function floorState(address token) view returns (uint256 V, uint256 S, uint256 E)",
+  "event Redeemed(address indexed token, address indexed account, uint256 tokenAmount, uint256 quoteOut)",
+  "error ZeroAmount()",
+  "error QuoteNotSet()",
+  "error InsufficientReserve()",
+  "error FloorWouldDecrease()",
+  "error FloorSupplyExhausted()",
+]);
+/** FloorLoanPlugin (v2 module 1): borrow the floor value of a coin, repay before expiry to get it back. */
+const loanAbi = parseAbi([
+  "struct Loan { address borrower; uint40 start; uint40 expiry; uint8 status; address token; uint128 e; uint128 gross; uint128 fee; uint128 net; }",
+  "function loansEnabled(address token) view returns (bool)",
+  "function previewBorrow(address token, uint256 e, uint256 duration) view returns (uint256 gross, uint256 fee, uint256 net)",
+  "function maxCollateral(address token) view returns (uint256)",
+  "function repayAmount(uint256 loanId) view returns (uint256)",
+  "function loansOf(address borrower) view returns (uint256[])",
+  "function getLoan(uint256 loanId) view returns (Loan)",
+  "function borrow(address token, uint256 e, uint256 duration, uint256 minNet) returns (uint256 loanId)",
+  "function repay(uint256 loanId, uint256 maxRepay) payable returns (uint256 repaid)",
+  "event Borrowed(uint256 indexed loanId, address indexed borrower, address indexed token, uint256 e, uint256 gross, uint256 fee, uint256 net, uint256 expiry)",
+  "error LoansNotEnabled(address token)",
+  "error InvalidDuration(uint256 duration)",
+  "error CollateralCapExceeded(uint256 maxCollateral)",
+  "error ZeroLoan()",
+  "error BelowMinimum(uint256 net, uint256 minNet)",
+  "error NotBorrower()",
+  "error LoanNotOpen()",
+  "error LoanExpired()",
+  "error RepayTooHigh(uint256 repay, uint256 maxRepay)",
+  "error FloorSupplyExhausted()",
+  "error ModuleHalted(uint32 moduleId)",
+]);
+const gatedBuyAbi = parseAbi([
+  "function gateState(address token) view returns (address hook, address creator, uint64 endsAt, bool open)",
+  "function canBuy(address token, address wallet) view returns (bool ok, uint256 left)",
+  "function spentOf(address token, address wallet) view returns (uint256)",
+  "function params(address token) view returns ((uint32 duration, uint64 listId, uint128 walletCap, (address token, uint128 minBalance)[] communities))",
+]);
+const passAbi = parseAbi([
+  "function claim(uint256 deadline, bytes signature)",
+  "function balanceOf(address wallet) view returns (uint256)",
+  "function agentOf(address wallet) view returns (bool isAgent, uint8 via)",
+  "error Expired()",
+  "error AlreadyHolder()",
+  "error Revoked()",
+  "error InvalidSignature()",
+]);
+/** HookitAgentValidator: the ERC-8004 adapter the pass reads (claim_agent_pass with agentId). */
+const validatorAbi = parseAbi([
+  "function validate(uint256 agentId, uint256 deadline, bytes signature, bytes32 requestHash)",
+  "function balanceOf(address wallet) view returns (uint256)",
+  "function agentIdOf(address wallet) view returns (bool linked, uint256 agentId)",
+  "function identityRegistry() view returns (address)",
+  "function validationRegistry() view returns (address)",
+  "error InvalidSignature()",
+  "error Expired()",
+  "error NotAgentWallet()",
+  "error Revoked()",
+  "error WrongRequest()",
+]);
+/** The ERC-8004 ValidationRegistry: the request the identity's owner addresses to Hookit's validator. */
+const validationRegistryAbi = parseAbi([
+  "function validationRequest(address validatorAddress, uint256 agentId, string requestURI, bytes32 requestHash)",
+  "function getValidationStatus(bytes32 requestHash) view returns (address validatorAddress, uint256 agentId, uint8 response, bytes32 responseHash, string tag, uint256 lastUpdate)",
+  "function getSummary(uint256 agentId, address[] validatorAddresses, string tag) view returns (uint64 count, uint8 avgResponse)",
+]);
+/** The ERC-8004 IdentityRegistry: who may send an identity's validation request (its owner or an approved operator). */
+const identityAbi = parseAbi([
+  "function ownerOf(uint256 agentId) view returns (address)",
+  "function getApproved(uint256 agentId) view returns (address)",
+  "function isApprovedForAll(address owner, address operator) view returns (bool)",
+]);
+/** What hookit.fun's validation requests carry (web/src/lib/agent-pass.ts), and Hookit's response tag. */
+const VALIDATION_REQUEST_URI = "https://hookit.fun/agents";
+const VALIDATION_TAG = "hookit-agent";
+/** Hook C reverts (wrapped by the PoolManager): a guard plugin refused the buy, or a plugin's size cap. */
+const PLUGIN_BLOCKED = keccak256(toHex("PluginBlocked(uint16,uint16)")).slice(2, 10);
+const PLUGIN_SIZE_CAP = keccak256(toHex("PluginSizeCap(uint16)")).slice(2, 10);
+/** Hook anti-MEV: one swap per wallet (tx.origin) per pool per block. */
+const SANDWICH_BLOCKED = keccak256(toHex("SandwichBlocked()")).slice(2, 10);
+/** GatedBuyPlugin.REASON_EXACT_INPUT_ONLY: with a wallet cap, exact-output buys are refused during the window. */
+const REASON_EXACT_INPUT_ONLY = 2;
+const PASS_STEPS =
+  "This coin is AI-agents-only for now. Get your Agent Pass first: call agent_pass_challenge, then claim_agent_pass, then retry buy_token.";
+
+let catalogCache = null;
+async function catalog() {
+  if (catalogCache) return catalogCache;
+  const res = await fetch(`${API}/api/agents/catalog`);
+  if (!res.ok) throw new Error(`hookit catalog unavailable (${res.status})`);
+  const body = await res.json();
+  // Presets, modules, pairs and rules come from hookit.fun; every contract address is this server's own.
+  const { factory, factories, payoutRouter, gatedBuyPlugin, agentPass, agentValidator } = PINNED;
+  catalogCache = { ...body, factory, factories, payoutRouter, gatedBuyPlugin, agentPass, agentValidator };
+  return catalogCache;
+}
+
+function reply(value) {
+  return { content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }] };
+}
+function fail(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+function needKey() {
+  return fail("No wallet. Set HOOKIT_PRIVATE_KEY in this server's env to a wallet funded for launches and nothing else.");
+}
+
+/**
+ * Whether `wallet` counts as an agent on the Hookit Agent Pass. `via` is "pass" for a pass holder; "erc8004" for the
+ * operating wallet of an ERC-8004 identity validated by Hookit (claim_agent_pass with agentId) or by a validator the
+ * owner trusts.
+ */
+async function agentStatus(pass, wallet) {
+  const [isAgent, via] = await publicClient.readContract({ address: pass, abi: passAbi, functionName: "agentOf", args: [wallet] });
+  return { holder: isAgent, via: isAgent ? (via === 1 ? "pass" : via === 2 ? "erc8004" : null) : null };
+}
+
+/** The exact text the wallet signs for /api/agents/pass (answers as sent, joined with " | "). */
+function passMessage(wallet, id, answers) {
+  return `Hookit Agent Pass\nWallet: ${getAddress(wallet)}\nChallenge: ${id}\nAnswers: ${answers.join(" | ")}`;
+}
+
+/** Every revert payload and message an error carries, lowercased, to look for a nested selector. */
+function errorText(err) {
+  const parts = [];
+  let e = err;
+  for (let i = 0; e && i < 12; i++) {
+    for (const v of [e.raw, e.data, e.data?.data, e.details, e.shortMessage, e.message]) {
+      if (typeof v === "string") parts.push(v);
+    }
+    e = e.cause;
+  }
+  return parts.join(" ").toLowerCase();
+}
+
+function errorName(err) {
+  let e = err;
+  for (let i = 0; e && i < 12; i++) {
+    if (e.data?.errorName) return e.data.errorName;
+    e = e.cause;
+  }
+  return null;
+}
+
+/** The `reason` of a PluginBlocked(slot, reason) found in the revert text, else null. */
+function pluginBlockedReason(text) {
+  const m = new RegExp(`${PLUGIN_BLOCKED}([0-9a-f]{64})([0-9a-f]{64})`).exec(text);
+  return m ? Number.parseInt(m[2].slice(-4), 16) : null;
+}
+
+function swapFailure(err, what = "buy") {
+  const text = errorText(err);
+  if (pluginBlockedReason(text) === REASON_EXACT_INPUT_ONLY) {
+    return "During the gated window this coin only accepts exact-input buys. buy_token always buys exact-input, so retry it rather than another route.";
+  }
+  if (text.includes(PLUGIN_BLOCKED)) return `The coin's launch gate refused this wallet (PluginBlocked). ${PASS_STEPS} If the coin is gated to an allowlist or holders instead, wait for the gate to open.`;
+  if (text.includes(PLUGIN_SIZE_CAP)) return "This buy is above what the wallet may still buy during the coin's gate window (wallet cap). Buy less, or wait for the gate to open.";
+  if (text.includes(SANDWICH_BLOCKED)) return "This coin allows one trade per wallet per block (anti-MEV) and this wallet already traded it in the latest block. Retry in a few seconds.";
+  if (/insufficient funds/.test(text)) return `The wallet does not hold enough ETH for this ${what} and its gas.`;
+  const name = errorName(err);
+  if (name === "InsufficientOutput") return `The ${what} would return less than the slippage floor. Retry, or allow more slippage.`;
+  if (name === "UnsupportedQuote" || name === "UnsupportedVenue") return `No USDG route reaches this coin's market for this ${what}.`;
+  return `The ${what} would fail: ${shortError(err)}`;
+}
+
+/**
+ * Runs an eth_call or a send; when the coin's anti-MEV rule refuses it because this wallet traded the same pool in
+ * the latest block (calls run against that block), waits for the next block (Ink makes one a second) and runs it once
+ * more.
+ */
+async function nextBlockRetry(fn) {
+  try {
+    return await fn();
+  } catch (err) {
+    if (!errorText(err).includes(SANDWICH_BLOCKED)) throw err;
+    const start = await publicClient.getBlockNumber();
+    for (let i = 0; i < 20 && (await publicClient.getBlockNumber()) <= start; i++) {
+      await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+    return fn();
+  }
+}
+
+function shortError(err) {
+  const name = errorName(err);
+  const text = String(err?.shortMessage || err?.message || err).slice(0, 300);
+  return name && !text.includes(name) ? `${name}: ${text}` : text;
+}
+
+/** Why a validator or ValidationRegistry call would fail, in words (claim_agent_pass with agentId). */
+function validationFailure(err, agentId) {
+  const name = errorName(err);
+  const text = errorText(err);
+  if (name === "Expired") return "the voucher expired. Call agent_pass_challenge again.";
+  if (name === "Revoked") {
+    return "this wallet was revoked by Hookit's ERC-8004 validator; it cannot be validated again unless the owner lifts the revocation.";
+  }
+  if (name === "NotAgentWallet") return `this wallet is not the operating wallet (agentWallet) of ERC-8004 identity ${agentId}.`;
+  if (name === "InvalidSignature") return "the voucher's signature was refused. Call agent_pass_challenge again later.";
+  if (name === "WrongRequest") return `no validation request from the identity's owner was found for identity ${agentId}.`;
+  if (/exists/.test(text)) return "this validation request was already sent. Call agent_pass_challenge again for a new voucher.";
+  if (/not authorized/.test(text)) return `this wallet is not the owner (or an approved operator) of ERC-8004 identity ${agentId}.`;
+  if (/insufficient funds/.test(text)) return "the wallet has no ETH on Ink for the gas.";
+  return String(err?.shortMessage || err?.message || err).slice(0, 300);
+}
+
+/**
+ * Simulates then sends one call from this wallet and waits for it: { hash }, or { error } plus the hash when it was sent
+ * (nothing is sent when the simulation fails). `validate` ends in a nested ValidationRegistry write that the node's
+ * estimate can leave short of gas (seen on an Ink fork), so the call gets 30% on top; unused gas is not paid.
+ */
+async function sendChecked(call, agentId) {
+  let request;
+  let gas;
+  try {
+    ({ request } = await publicClient.simulateContract({ account, ...call }));
+    gas = await publicClient.estimateContractGas({ account, ...call });
+  } catch (err) {
+    return { error: validationFailure(err, agentId) };
+  }
+  let hash;
+  try {
+    hash = await walletClient.writeContract({ ...request, gas: (gas * 13n) / 10n });
+    const receipt = await publicClient.waitForTransactionReceipt({ hash });
+    if (receipt.status !== "success") return { error: "the transaction reverted", hash };
+  } catch (err) {
+    return { error: String(err?.shortMessage || err?.message || err).slice(0, 300), ...(hash ? { hash } : {}) };
+  }
+  return { hash };
+}
+
+/**
+ * claim_agent_pass with agentId, once hookit answered with the validator's voucher. Nothing in the answer is trusted:
+ * the validator is the pinned one, the voucher must be for this wallet and identity with a sane deadline, `request` must
+ * be `validationRequest(validator, agentId, VALIDATION_REQUEST_URI, this voucher's hash)` to the validator's own registry,
+ * and who owns the identity is read on chain. A link-only simulation proves the voucher works before anything is sent.
+ * Then: with `requestHash` (a request the identity's owner already addressed to Hookit's validator) `validate` answers
+ * it; when this wallet owns the identity or is its approved operator and Hookit has not published yet, it sends the
+ * request then `validate`; else it only links the wallet (nothing when already linked). The verdict is read on chain.
+ */
+async function claimValidation(body, agentId, requestHash) {
+  const id = BigInt(agentId);
+  const me = account.address;
+  const validator = at(null, "agentValidator");
+  if (!same(body.validator, validator)) return fail("hookit answered with an unexpected validator address. Nothing was sent.");
+  let registry;
+  let identity;
+  let now;
+  try {
+    [registry, identity, now] = await Promise.all([
+      publicClient.readContract({ address: validator, abi: validatorAbi, functionName: "validationRegistry" }),
+      publicClient.readContract({ address: validator, abi: validatorAbi, functionName: "identityRegistry" }),
+      publicClient.getBlock().then((b) => b.timestamp),
+    ]);
+  } catch {
+    return fail("Could not read Hookit's ERC-8004 validator on Ink. Nothing was sent; try again later.");
+  }
+  let deadline;
+  let signature;
+  let ownHash;
+  try {
+    if (!same(body.validate?.to, validator) || !same(body.validateLinkOnly?.to, validator) || !same(body.request?.to, registry)) {
+      throw new Error("to");
+    }
+    const validate = decodeFunctionData({ abi: validatorAbi, data: body.validate.data });
+    const linkOnly = decodeFunctionData({ abi: validatorAbi, data: body.validateLinkOnly.data });
+    const request = decodeFunctionData({ abi: validationRegistryAbi, data: body.request.data });
+    if (validate.functionName !== "validate" || linkOnly.functionName !== "validate") throw new Error("fn");
+    if (request.functionName !== "validationRequest") throw new Error("fn");
+    [, deadline, signature, ownHash] = validate.args;
+    if (validate.args[0] !== id || linkOnly.args[0] !== id || request.args[1] !== id) throw new Error("agentId");
+    if (linkOnly.args[1] !== deadline || linkOnly.args[2] !== signature || linkOnly.args[3] !== zeroHash) throw new Error("voucher");
+    if (!same(request.args[0], validator) || request.args[2] !== VALIDATION_REQUEST_URI || request.args[3] !== ownHash) throw new Error("request");
+    const expected = keccak256(
+      encodeAbiParameters(
+        [{ type: "string" }, { type: "address" }, { type: "uint256" }, { type: "address" }, { type: "uint256" }],
+        [VALIDATION_TAG, validator, id, me, deadline],
+      ),
+    );
+    if (ownHash !== expected) throw new Error("requestHash");
+    if (deadline <= now || deadline > now + 86_400n) throw new Error("deadline");
+  } catch {
+    return fail("hookit answered with unexpected validation transactions. Nothing was sent.");
+  }
+  const call = (hash) => ({ address: validator, abi: validatorAbi, functionName: "validate", args: [id, deadline, signature, hash] });
+  // The voucher itself (deadline, this wallet as the identity's agentWallet, signature, revocation), before any send.
+  try {
+    await publicClient.simulateContract({ account, ...call(zeroHash) });
+  } catch (err) {
+    return fail(`Nothing was sent: the validation would fail: ${validationFailure(err, agentId)}`);
+  }
+
+  const publishedCount = () =>
+    publicClient
+      .readContract({ address: registry, abi: validationRegistryAbi, functionName: "getSummary", args: [id, [validator], VALIDATION_TAG] })
+      .then(([count]) => count)
+      .catch(() => null);
+  const [[linked, linkedId], owner, approved, published] = await Promise.all([
+    publicClient.readContract({ address: validator, abi: validatorAbi, functionName: "agentIdOf", args: [me] }),
+    publicClient.readContract({ address: identity, abi: identityAbi, functionName: "ownerOf", args: [id] }).catch(() => null),
+    publicClient.readContract({ address: identity, abi: identityAbi, functionName: "getApproved", args: [id] }).catch(() => null),
+    publishedCount(),
+  ]);
+  const canRequest =
+    !!owner &&
+    (same(owner, me) ||
+      same(approved, me) ||
+      (await publicClient.readContract({ address: identity, abi: identityAbi, functionName: "isApprovedForAll", args: [owner, me] }).catch(() => false)));
+  const alreadyLinked = linked && linkedId === id;
+
+  const txs = [];
+  const notes = [];
+  const send = async (c) => {
+    const r = await sendChecked(c, agentId);
+    if (r.hash) txs.push(`${EXPLORER}/tx/${r.hash}`);
+    return r;
+  };
+  const sentSoFar = () => (txs.length ? ` Sent so far: ${txs.join(", ")}.` : " Nothing was sent.");
+  if (requestHash) {
+    let status;
+    try {
+      status = await publicClient.readContract({ address: registry, abi: validationRegistryAbi, functionName: "getValidationStatus", args: [requestHash] });
+    } catch {
+      return fail(`No validation request ${requestHash} was found on Ink's ValidationRegistry. Nothing was sent.`);
+    }
+    if (!same(status[0], validator) || status[1] !== id) {
+      return fail(`Request ${requestHash} is not addressed to Hookit's validator for identity ${agentId}. Nothing was sent.`);
+    }
+    const r = await send(call(requestHash));
+    if (r.error) return fail(`validate failed: ${r.error}.${sentSoFar()}`);
+  } else if (canRequest && published === 0n) {
+    // Owner or operator: request Hookit's validation, then validate (Hookit publishes its response).
+    const r1 = await send({ address: registry, abi: validationRegistryAbi, functionName: "validationRequest", args: [validator, id, VALIDATION_REQUEST_URI, ownHash] });
+    let linkedNow = false;
+    if (r1.error) {
+      if (r1.hash) return fail(`The validation request failed: ${r1.error}.${sentSoFar()}`);
+      notes.push(`Hookit's validation was not published: the request would fail (${r1.error}).`);
+    } else {
+      let r2 = await send(call(ownHash));
+      if (r2.error && !r2.hash) {
+        // The registry may not show the request yet on this RPC: one more try a moment later.
+        await sleep(2_000);
+        r2 = await send(call(ownHash));
+      }
+      if (r2.hash && r2.error) return fail(`validate failed: ${r2.error}.${sentSoFar()}`);
+      if (r2.error) notes.push(`Hookit's validation was not published: validate would fail (${r2.error}).`);
+      else linkedNow = true;
+    }
+    if (!linkedNow && !alreadyLinked) {
+      const r3 = await send(call(zeroHash));
+      if (r3.error) return fail(`The validation failed: ${r3.error}.${sentSoFar()}`);
+    }
+  } else if (!alreadyLinked) {
+    const r = await send(call(zeroHash));
+    if (r.error) return fail(`The validation failed: ${r.error}.${sentSoFar()}`);
+  }
+
+  const [status, publishedAfter] = await Promise.all([agentStatus(at(null, "agentPass"), me).catch(() => null), publishedCount()]);
+  if (!status?.holder) {
+    return fail(
+      `This wallet does not count as an agent on the Hookit Agent Pass after the validation (ERC-8004 agents may be switched off on Hookit right now): use claim_agent_pass without agentId for a plain pass.${sentSoFar()}`,
+    );
+  }
+  const isPublished = (publishedAfter ?? 0n) > 0n;
+  const howToPublish = `To publish Hookit's validation on ERC-8004 too: the identity's owner${owner ? ` (${getAddress(owner)})` : ""} sends validationRequest(${validator}, ${agentId}, "${VALIDATION_REQUEST_URI}", any new 32-byte hash) to the ValidationRegistry ${registry}, then this wallet runs agent_pass_challenge({ agentId: "${agentId}" }) and claim_agent_pass with the same agentId and requestHash set to that hash. Or the owner approves this wallet on the IdentityRegistry ${identity} and this wallet runs the two tools again with agentId.`;
+  return reply({
+    validated: true,
+    wallet: me,
+    agentId,
+    validator,
+    agentPass: status,
+    publishedOnErc8004: isPublished,
+    tx: txs,
+    ...(notes.length ? { note: notes.join(" ") } : {}),
+    next: `${txs.length ? "" : "Nothing was sent. "}This wallet is linked to ERC-8004 identity ${agentId} and counts as an agent: buy AI-agents-only coins with buy_token (step 3), from this same wallet.${isPublished ? ` Hookit's 100/100 "${VALIDATION_TAG}" validation of identity ${agentId} is public on ERC-8004.` : ` ${howToPublish}`}`,
+  });
+}
+
+function opensAt(endsAt) {
+  const sec = Number(endsAt);
+  const minutes = Math.max(0, Math.ceil((sec * 1000 - Date.now()) / 60_000));
+  return `${new Date(sec * 1000).toISOString()} (in about ${minutes} min)`;
+}
+
+/** A catalog address, or its Ink default when this hookit.fun does not list it yet. */
+/** A pinned Ink address (see PINNED). `c` is unused: kept so call sites read the same. */
+function at(c, name) {
+  return getAddress(PINNED[name]);
+}
+
+const read = (address, abi, functionName, args = []) => publicClient.readContract({ address, abi, functionName, args });
+
+/** An amount for people: every digit before the point, at most 6 significant ones after leading zeros. */
+function short(amount, decimals) {
+  const s = formatUnits(amount, decimals);
+  const [whole, frac = ""] = s.split(".");
+  if (!frac) return whole;
+  const lead = /^-?0$/.test(whole) ? Math.max(0, frac.search(/[1-9]/)) : 0;
+  const kept = frac.slice(0, lead + 6).replace(/0+$/, "");
+  return kept ? `${whole}.${kept}` : whole;
+}
+function amountText(amount, meta) {
+  return `${short(amount, meta.decimals)} ${meta.symbol}`;
+}
+
+const assetCache = new Map();
+/** { address, symbol, decimals } of ETH (zeroAddress) or an ERC-20. */
+async function assetMeta(address) {
+  if (address === zeroAddress) return ETH;
+  const key = address.toLowerCase();
+  if (!assetCache.has(key)) {
+    const meta = Promise.all([
+      read(address, erc20Abi, "symbol").catch(() => "tokens"),
+      read(address, erc20Abi, "decimals").catch(() => 18),
+    ]).then(([symbol, decimals]) => ({ address: getAddress(address), symbol, decimals: Number(decimals) }));
+    assetCache.set(key, meta);
+  }
+  return assetCache.get(key);
+}
+
+async function balanceOf(asset, wallet) {
+  return asset === zeroAddress ? publicClient.getBalance({ address: wallet }) : read(asset, erc20Abi, "balanceOf", [wallet]);
+}
+
+const same = (a, b) => typeof a === "string" && typeof b === "string" && a.toLowerCase() === b.toLowerCase();
+
+/** The Master pool of `token` on the first factory that knows it, or null. */
+async function resolvePool(c, token) {
+  const factories = (c.factories?.length ? c.factories : [c.factory]).filter(Boolean);
+  for (const factory of factories) {
+    const launchId = await publicClient
+      .readContract({ address: factory, abi: launchLookupAbi, functionName: "tokenLaunchId", args: [token] })
+      .catch(() => 0n);
+    if (launchId > 0n) {
+      const key = await publicClient.readContract({ address: factory, abi: launchLookupAbi, functionName: "poolKeyOf", args: [launchId] });
+      return { factory, launchId, key };
+    }
+  }
+  return null;
+}
+
+/**
+ * A Master coin and every market it trades in: { token, meta, factory, launchId, key, markets[{ index, key, tokenIs0,
+ * quote }] }, or null when no Master factory knows it. A multi-pair launch has one market per quote (USDG, stocks).
+ */
+async function loadCoin(c, token) {
+  const pool = await resolvePool(c, token);
+  if (!pool) return null;
+  const count = Number(await read(pool.factory, launchLookupAbi, "launchMarketCount", [pool.launchId]).catch(() => 0));
+  const keys =
+    count > 0
+      ? await Promise.all(Array.from({ length: count }, (_, i) => read(pool.factory, launchLookupAbi, "poolKeyOfMarket", [pool.launchId, BigInt(i)])))
+      : [pool.key];
+  if (!keys.every((key) => same(key.currency0, token) || same(key.currency1, token))) return null;
+  const markets = keys.map((key, index) => {
+    const tokenIs0 = same(key.currency0, token);
+    return { index, key, tokenIs0, quote: getAddress(tokenIs0 ? key.currency1 : key.currency0) };
+  });
+  return { ...pool, token, meta: await assetMeta(token), markets };
+}
+
+const NOT_A_COIN =
+  "hookit.fun does not know this coin on its Master factories (Classic bonding-curve coins are not supported here). Find coins with list_coins.";
+
+/** What `input` names: "eth", "usdg", a pair id or ticker from list_pairs, a market's quote symbol, or an address. */
+async function resolveAsset(c, input, coin) {
+  const s = String(input).trim();
+  const low = s.toLowerCase();
+  if (low === "eth" || low === "ether" || low === "native") return zeroAddress;
+  if (isAddress(s)) return getAddress(s);
+  if (low === "usdg") return at(c, "usdg");
+  if (KNOWN_ASSETS[low]) return getAddress(KNOWN_ASSETS[low]);
+  const pair = (c.pairs ?? []).find((p) => same(p.id, low) || same(p.ticker, low));
+  if (pair?.address && isAddress(pair.address)) return getAddress(pair.address);
+  for (const m of coin?.markets ?? []) {
+    if (same((await assetMeta(m.quote)).symbol, low)) return m.quote;
+  }
+  return null;
+}
+
+/**
+ * What the coin trades against on chain, as [{ address, symbol, decimals }]: each market's quote, plus USDG on a v2
+ * coin when the aggregator can bridge USDG to one of its markets (RouteConfigC enables a v4 or v3 USDG pool per quote).
+ */
+async function directAssets(c, coin) {
+  const assets = [];
+  for (const m of coin.markets) {
+    if (!assets.some((a) => same(a.address, m.quote))) assets.push(await assetMeta(m.quote));
+  }
+  const usdg = at(c, "usdg");
+  if (!assets.some((a) => same(a.address, usdg)) && (await aggregatorFor(c, coin))) {
+    const rc = at(c, "routeConfig");
+    for (const m of coin.markets) {
+      const [v4, v3] = await Promise.all([
+        read(rc, routeConfigAbi, "bridgeOf", [m.quote]).catch(() => null),
+        read(rc, routeConfigAbi, "bridgeV3Of", [m.quote]).catch(() => null),
+      ]);
+      if (v4?.enabled || v3?.enabled) {
+        assets.push(await assetMeta(usdg));
+        break;
+      }
+    }
+  }
+  return assets;
+}
+
+/** The symbols of directAssets. */
+async function tradeAssets(c, coin) {
+  return (await directAssets(c, coin)).map((a) => a.symbol);
+}
+
+/**
+ * An amount of `meta` given by the user: a decimal, "max" (the whole balance) or "N%" of it, in base units; null when
+ * it is not an amount. `keepDust` keeps 1 base unit when spending everything: emptying a holder-airdrop coin in one
+ * transaction can hit a bug of the older airdrop vaults, and 1 wei of a coin is worth nothing.
+ */
+function parseAmount(input, meta, balance, keepDust = false) {
+  const s = String(input).trim().toLowerCase();
+  if (s === "max" || s === "all") return keepDust && balance > 1n ? balance - 1n : balance;
+  const pct = /^([0-9]*\.?[0-9]+)\s*%$/.exec(s);
+  if (pct) {
+    const bp = Math.round(Number(pct[1]) * 100);
+    if (!(bp > 0 && bp <= 10_000)) return null;
+    const v = (balance * BigInt(bp)) / 10_000n;
+    return keepDust && bp === 10_000 && v > 1n ? v - 1n : v;
+  }
+  try {
+    return parseUnits(s, meta.decimals);
+  } catch {
+    return null;
+  }
+}
+
+/** hookit.fun's coin list (/api/launches), cached for 30 s. */
+let launchesCache = null;
+async function launches() {
+  if (launchesCache && Date.now() - launchesCache.at < 30_000) return launchesCache.body;
+  const res = await fetch(`${API}/api/launches`);
+  const body = await res.json().catch(() => null);
+  if (!res.ok || !Array.isArray(body?.pools)) throw new Error(body?.error ?? `hookit answered ${res.status}`);
+  launchesCache = { at: Date.now(), body };
+  return body;
+}
+
+/**
+ * The USD price of one unit of `asset` (ETH, a stock, kBTC): hookit.fun's price for a coin priced in it, else its
+ * USDG pool on Ink (a stock that only backs secondary markets); null if unknown.
+ */
+async function usdPrice(c, asset) {
+  if (same(asset, at(c, "usdg"))) return 1;
+  const body = await launches().catch(() => null);
+  if (asset === zeroAddress) return body?.ethUsd > 0 ? body.ethUsd : null;
+  const pool = body?.pools.find((p) => same(p.quoteAddress, asset) && p.quoteUsd > 0);
+  if (pool) return pool.quoteUsd;
+  const key = asset.toLowerCase();
+  const hit = poolPriceCache.get(key);
+  if (hit && Date.now() - hit.at < 30_000) return hit.price;
+  const price = await usdgPoolPrice(c, asset).catch(() => null);
+  poolPriceCache.set(key, { at: Date.now(), price });
+  return price;
+}
+const poolPriceCache = new Map();
+
+/**
+ * One unit of `asset` in USDG from its Uniswap v4 USDG pool (the bridge RouteConfigC names for it), or null: a
+ * thousandth of a unit sold for USDG, else one USDG spent on it when the USDG side is too thin.
+ */
+async function usdgPoolPrice(c, asset) {
+  const bridge = await read(at(c, "routeConfig"), routeConfigAbi, "bridgeOf", [asset]);
+  if (!bridge.enabled) return null;
+  const usdg = at(c, "usdg");
+  const usdgIs0 = BigInt(usdg) < BigInt(asset);
+  const poolKey = { currency0: usdgIs0 ? usdg : asset, currency1: usdgIs0 ? asset : usdg, fee: bridge.fee, tickSpacing: bridge.tickSpacing, hooks: bridge.hooks };
+  const quote = (zeroForOne, exactAmount) =>
+    publicClient
+      .simulateContract({ address: at(c, "v4Quoter"), abi: quoterAbi, functionName: "quoteExactInputSingle", args: [{ poolKey, zeroForOne, exactAmount, hookData: "0x" }] })
+      .then(({ result }) => result[0])
+      .catch(() => 0n);
+  const unit = 10n ** BigInt((await assetMeta(asset)).decimals);
+  const sold = await quote(!usdgIs0, unit / 1000n);
+  if (sold > 0n) return Number(formatUnits(sold * 1000n, 6));
+  const bought = await quote(usdgIs0, 1_000_000n);
+  return bought > 0n ? Number(unit) / Number(bought) : null;
+}
+
+/** `amount` of `from` in units of `to`, through their US dollar prices; null when either has no price. */
+async function convertAtUsd(c, from, to, amount) {
+  if (same(from.address, to.address)) return amount;
+  const [pf, pt] = await Promise.all([usdPrice(c, from.address), usdPrice(c, to.address)]);
+  if (!pf || !pt) return null;
+  const v = (Number(formatUnits(amount, from.decimals)) * pf) / pt;
+  return Number.isFinite(v) && v > 0 ? parseUnits(v.toFixed(to.decimals), to.decimals) : null;
+}
+
+/** Whether hookit.fun's Relay proxy swaps `from` into `to` on Ink: one side must be ETH or USDG. */
+function relayable(c, from, to) {
+  if (same(from, to)) return false;
+  const funding = (a) => same(a, zeroAddress) || same(a, at(c, "usdg"));
+  return funding(from) || funding(to);
+}
+
+/** The v2 aggregator that trades `coin` against USDG, or null (v1 coins, or a hookit.fun without one). */
+async function aggregatorFor(c, coin) {
+  const configured = await read(at(c, "routeConfig"), routeConfigAbi, "aggregator").catch(() => null);
+  const aggregator = configured && configured !== zeroAddress ? getAddress(configured) : at(c, "aggregator");
+  const factory = await read(aggregator, aggregatorAbi, "factory").catch(() => null);
+  return same(factory, coin.factory) ? aggregator : null;
+}
+
+/** abi.encode(wallet): the hookData HookitSwapRouter and the aggregator pass, so hook plugins credit this wallet. */
+const hookDataFor = (wallet) => encodeAbiParameters([{ type: "address" }], [wallet]);
+
+/**
+ * The route and quote of an exact-input trade of `coin` against `asset` (`isBuy`: pay `asset`, get the coin; else the
+ * reverse): HookitSwapRouter on the market quoted in `asset`, else the aggregator for USDG on a v2 coin (the best
+ * single market and bridge). { route } or { error }. Quotes are eth_calls from this wallet, so gates see it.
+ */
+async function planTrade(c, coin, isBuy, asset, amountIn) {
+  const what = isBuy ? "buy" : "sale";
+  const usdg = at(c, "usdg");
+  const aggregator = same(asset, usdg) ? await aggregatorFor(c, coin) : null;
+  if (aggregator) {
+    const options = [];
+    for (const m of coin.markets) {
+      for (const venue of same(m.quote, usdg) ? [0] : [0, 1]) options.push({ marketIndex: m.index, venue });
+    }
+    let firstError = null;
+    const quotes = await Promise.all(
+      options.map(async (o) => {
+        try {
+          const leg = { ...o, amountIn, minAmountOut: 0n };
+          const { result } = await nextBlockRetry(() =>
+            publicClient.simulateContract({
+              account,
+              address: aggregator,
+              abi: aggregatorAbi,
+              functionName: "quoteExactInput",
+              args: [isBuy, coin.launchId, coin.token, amountIn, [leg], account.address],
+            }),
+          );
+          return { ...o, out: result[1] };
+        } catch (err) {
+          firstError ??= err;
+          return { ...o, out: 0n };
+        }
+      }),
+    );
+    const best = quotes.reduce((a, b) => (b.out > a.out ? b : a));
+    if (best.out > 0n) return { route: { kind: "aggregator", spender: aggregator, leg: best, out: best.out } };
+    if (!coin.markets.some((m) => same(m.quote, asset))) {
+      if (["UnsupportedQuote", "UnsupportedVenue"].includes(errorName(firstError))) {
+        const assets = (await tradeAssets(c, coin)).filter((a) => a !== "USDG");
+        return { error: `No on-chain USDG route reaches this coin's market. Trade it in ${assets.join(", ")} instead.` };
+      }
+      return { error: firstError ? swapFailure(firstError, what) : `The pools would return nothing for this ${what}.` };
+    }
+  }
+  const market = coin.markets.find((m) => same(m.quote, asset));
+  if (!market) {
+    const assets = await tradeAssets(c, coin);
+    return { error: `This coin trades in ${assets.join(", ")} here, not in that token. Use one of those.` };
+  }
+  const zeroForOne = isBuy ? !market.tokenIs0 : market.tokenIs0;
+  try {
+    const { result } = await nextBlockRetry(() =>
+      publicClient.simulateContract({
+        account,
+        address: at(c, "v4Quoter"),
+        abi: quoterAbi,
+        functionName: "quoteExactInputSingle",
+        args: [{ poolKey: market.key, zeroForOne, exactAmount: amountIn, hookData: hookDataFor(account.address) }],
+      }),
+    );
+    if (result[0] <= 0n) return { error: `The pool would return nothing for this ${what}.` };
+    return { route: { kind: "router", spender: at(c, "swapRouter"), market, zeroForOne, out: result[0] } };
+  } catch (err) {
+    if (errorName(err) === "NotEnoughLiquidity" || errorText(err).includes(NOT_ENOUGH_LIQUIDITY)) {
+      const q = await assetMeta(market.quote);
+      return {
+        thin: true,
+        error: isBuy
+          ? `The coin's ${q.symbol} market cannot fill a buy this big. Buy less.`
+          : `The coin's ${q.symbol} market does not hold enough ${q.symbol} to pay for this sale (a market only pays out what its buyers paid in).`,
+      };
+    }
+    return { error: swapFailure(err, what) };
+  }
+}
+
+/**
+ * The sale of `value` coins through each of `assets` (assets the coin trades in), best first by US dollar value,
+ * unpriced ones last: { ranked: [{ asset, route, usd }], firstError, thinOnly }. Markets that cannot pay are left out;
+ * `thinOnly` says every one that failed lacked liquidity.
+ */
+async function rankSales(c, coin, value, assets) {
+  let firstError = null;
+  const scored = await Promise.all(
+    assets.map(async (asset, i) => {
+      const planned = await planTrade(c, coin, false, asset.address, value);
+      if (planned.error) return { i, error: planned.error, thin: planned.thin };
+      const price = await usdPrice(c, asset.address);
+      return { i, asset, route: planned.route, usd: price ? Number(formatUnits(planned.route.out, asset.decimals)) * price : null };
+    }),
+  );
+  for (const s of scored) if (s.error) firstError ??= s.error;
+  const ranked = scored
+    .filter((s) => s.route)
+    .sort((a, b) => (a.usd !== null && b.usd !== null ? b.usd - a.usd : a.usd !== null ? -1 : b.usd !== null ? 1 : a.i - b.i));
+  return { ranked, firstError, thinOnly: scored.every((s) => s.route || s.thin) };
+}
+
+/**
+ * The most coins one market of `assets` can pay for now, up to `value` (a binary search on quotes): { asset, amount }
+ * for the market that takes the most, or null when none takes any.
+ */
+async function largestSale(c, coin, assets, value) {
+  const fits = await Promise.all(
+    assets.map(async (asset) => {
+      let lo = 0n;
+      let hi = value;
+      for (let i = 0; i < 14 && hi - lo > value / 1000n; i++) {
+        const mid = (lo + hi) / 2n;
+        if ((await planTrade(c, coin, false, asset.address, mid)).route) lo = mid;
+        else hi = mid;
+      }
+      return { asset, amount: (lo * 98n) / 100n };
+    }),
+  );
+  const best = fits.reduce((a, b) => (b.amount > a.amount ? b : a), { amount: 0n });
+  return best.amount > 0n ? best : null;
+}
+
+/** Why no single market takes a sale of `value` coins, and what to sell instead (`most` from largestSale). */
+function saleTooBig(coin, value, most) {
+  if (!most) return "None of this coin's markets that could pay for this sale has anything to pay with yet: a market only pays out what its buyers paid in. Receive another asset.";
+  return `No single market of this coin can pay for ${amountText(value, coin.meta)} now: a market only pays out what its buyers paid in. The most one takes is about ${amountText(most.amount, coin.meta)} (its ${most.asset.symbol} market): sell that much, then the rest in another call.`;
+}
+
+/** `assets` (where a Relay swap of `amount` of `pay` could land) sorted by how many coins each would buy, best first. */
+async function rankBuyLandings(c, coin, pay, amount, assets) {
+  const scored = await Promise.all(
+    assets.map(async (asset, i) => {
+      const legAmount = await convertAtUsd(c, pay, asset, amount).catch(() => null);
+      const planned = legAmount ? await planTrade(c, coin, true, asset.address, legAmount) : null;
+      return { i, asset, out: planned?.route ? planned.route.out : -1n };
+    }),
+  );
+  return scored.sort((a, b) => (b.out > a.out ? 1 : b.out < a.out ? -1 : a.i - b.i)).map((s) => s.asset);
+}
+
+/**
+ * Another market of `coin` where the same dollars buy at least a quarter more coins than `out` (what `amount` of
+ * `pay` buys in its own market), or null: { asset, out, ratio }. The markets of one coin can drift far apart.
+ */
+async function cheaperMarket(c, coin, pay, amount, out) {
+  let best = null;
+  for (const m of coin.markets) {
+    if (same(m.quote, pay.address)) continue;
+    const asset = await assetMeta(m.quote);
+    const legAmount = await convertAtUsd(c, pay, asset, amount).catch(() => null);
+    if (!legAmount) continue;
+    const planned = await planTrade(c, coin, true, asset.address, legAmount);
+    if (planned.route && planned.route.out * 4n >= out * 5n && (!best || planned.route.out > best.out)) best = { asset, out: planned.route.out };
+  }
+  return best ? { ...best, ratio: Number((best.out * 100n) / out) / 100 } : null;
+}
+
+/** The call that executes `route` for `amountIn` with at least `minOut` back, to this wallet. */
+async function tradeCall(coin, route, isBuy, asset, amountIn, minOut) {
+  if (route.kind === "router") {
+    return {
+      address: route.spender,
+      abi: swapRouterAbi,
+      functionName: "swapExactIn",
+      args: [route.market.key, route.zeroForOne, amountIn, minOut, 0n],
+      ...(isBuy && asset === zeroAddress ? { value: amountIn } : {}),
+    };
+  }
+  const { timestamp } = await publicClient.getBlock();
+  const leg = { marketIndex: route.leg.marketIndex, venue: route.leg.venue, amountIn, minAmountOut: 0n };
+  return {
+    address: route.spender,
+    abi: aggregatorAbi,
+    functionName: isBuy ? "buyExactInput" : "sellExactInput",
+    args: [coin.launchId, coin.token, amountIn, minOut, [leg], account.address, timestamp + 900n],
+  };
+}
+
+/**
+ * Simulates `call` from this wallet, sends it with a third more gas than estimated (at least `minGas`) and waits:
+ * { hash, result, receipt }, or { error } when the simulation fails (nothing sent) or the transaction reverts.
+ */
+async function send(call, { minGas = 0n, explain = shortError } = {}) {
+  let result;
+  let gas;
+  try {
+    ({ result, gas } = await nextBlockRetry(async () => {
+      const { result } = await publicClient.simulateContract({ account, ...call });
+      const estimated = await publicClient.estimateContractGas({ account, ...call });
+      return { result, gas: estimated + estimated / 3n };
+    }));
+  } catch (err) {
+    return { error: explain(err) };
+  }
+  if (gas < minGas) gas = minGas;
+  if (gas > MAX_TX_GAS) gas = MAX_TX_GAS;
+  const hash = await walletClient.writeContract({ ...call, gas });
+  const receipt = await publicClient.waitForTransactionReceipt({ hash });
+  if (receipt.status !== "success") return { error: `the transaction reverted: ${EXPLORER}/tx/${hash}`, hash };
+  return { hash, result, receipt };
+}
+
+/** Approves `spender` for exactly `amount` of `asset` unless it already may spend that much. { hash } or { error }. */
+async function approveIfNeeded(asset, spender, amount) {
+  if (asset === zeroAddress) return {};
+  const allowance = await read(asset, erc20Abi, "allowance", [account.address, spender]).catch(() => 0n);
+  if (allowance >= amount) return {};
+  const sent = await send({ address: asset, abi: erc20Abi, functionName: "approve", args: [spender, amount] });
+  return sent.error ? { error: `The approval would fail: ${sent.error}` } : { hash: sent.hash };
+}
+
+/** ETH the wallet keeps for gas (with Ink's L1 data fee) on a trade of `gasUnits`. */
+async function gasReserve(gasUnits) {
+  const gasPrice = await publicClient.getGasPrice();
+  return gasPrice * gasUnits + 20_000_000_000_000n;
+}
+
+/** What a mined transaction cost in ETH: execution gas plus Ink's L1 data fee. */
+function feeOf(receipt) {
+  const l1 = receipt.l1Fee != null ? BigInt(receipt.l1Fee) : 0n;
+  return receipt.gasUsed * receipt.effectiveGasPrice + l1;
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Relay's contracts on Ink (api.relay.link/chains): a conversion only ever calls one of these, or approves one of them
+ * on the token it spends. A quote that asks for anything else is refused before signing.
+ */
+const RELAY_INK = new Set(
+  [
+    "0xb92fe925dc43a0ecde6c8b1a2709c170ec4fff4f", // erc20Router
+    "0xccc88a9d1b4ed6b0eaba998850414b24f1c315be", // approvalProxy
+    "0x7f4babd2c7d35221e72ab67ea72cba99573a0089", // relayReceiver
+    "0xe2035a0d568dec7f37b3267823cd9c919e744594", // multicaller
+    "0x4cd00e387622c35bddb9b4c962c136462338bc31", // depository
+  ],
+);
+const RELAY_APPROVAL_PROXY = getAddress("0xccc88a9d1b4ed6b0eaba998850414b24f1c315be");
+/** Slippage allowed on a Relay leg (ETH, USDG, stocks: liquid pairs), whatever the coin's own slippage is. */
+const RELAY_MAX_SLIPPAGE_BPS = 300;
+
+/**
+ * A Relay quote to swap `amount` of `from` into `to` on Ink for this wallet, through hookit.fun's /api/relay/quote
+ * (Relay's key stays on that server): { quote: { requestId, out, min, impact, calls } } or { error }.
+ */
+async function relayQuote(from, to, amount, slippageBps) {
+  const [inMeta, outMeta] = await Promise.all([assetMeta(from), assetMeta(to)]);
+  let res;
+  try {
+    res = await fetch(`${API}/api/relay/quote`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        user: account.address,
+        originChainId: ink.id,
+        destinationChainId: ink.id,
+        originCurrency: from,
+        destinationCurrency: to,
+        amount: amount.toString(),
+        slippageBps,
+      }),
+    });
+  } catch {
+    return { error: "hookit.fun's Relay quote did not answer. Retry later." };
+  }
+  const body = await res.json().catch(() => null);
+  if (!res.ok) {
+    const why = body?.error ?? `hookit.fun answered ${res.status}`;
+    if (why === "Unsupported Relay pair") return { error: `Relay does not swap ${inMeta.symbol} into ${outMeta.symbol} through hookit.fun.`, unsupported: true };
+    return { error: `Relay has no ${inMeta.symbol} to ${outMeta.symbol} route right now (${why}).` };
+  }
+  if (!/^\d+$/.test(body?.amountOut ?? "") || !/^\d+$/.test(body?.minimumAmount ?? "") || !Array.isArray(body?.calls)) {
+    return { error: "hookit.fun's Relay quote came back malformed. Nothing was sent." };
+  }
+  const out = BigInt(body.amountOut);
+  if (out <= 0n) return { error: `Relay would return no ${outMeta.symbol}.` };
+  const checked = relayPlan(body.calls, from, amount, inMeta.symbol);
+  if (checked.error) return { error: checked.error };
+  return {
+    quote: {
+      requestId: body.requestId,
+      out,
+      min: BigInt(body.minimumAmount),
+      impact: body.impactPercent ?? null,
+      calls: body.calls,
+      inMeta,
+      outMeta,
+    },
+  };
+}
+
+/**
+ * Checks a Relay quote's calls before anything is signed: Ink only, at most one approval (of Relay's approval proxy,
+ * on the token spent; replaced by an exact approval of `amount`: an allowance given to Relay's router could be spent
+ * by anyone), every other call to a Relay contract, and no more ETH sent than `amount` (none when an ERC-20 is spent).
+ * The calls' effect is checked separately, by relaySimulate. { spender, txs } or { error }.
+ */
+function relayPlan(calls, from, amount, symbol) {
+  const refused = (why) => ({ error: `Refused Relay's transactions (${why}). Nothing was sent.` });
+  if (calls.length === 0 || calls.length > 4) return refused(`${calls.length} calls`);
+  let spender = null;
+  let total = 0n;
+  const txs = [];
+  for (const call of calls) {
+    if (Number(call?.chainId) !== ink.id) return refused("a call outside Ink");
+    if (!isAddress(call.to ?? "") || !/^0x([0-9a-fA-F]{2})*$/.test(call.data ?? "") || !/^\d+$/.test(String(call.value ?? "0"))) {
+      return refused("a malformed call");
+    }
+    const to = getAddress(call.to);
+    const value = BigInt(call.value ?? 0);
+    if (from !== zeroAddress && same(to, from)) {
+      let decoded;
+      try {
+        decoded = decodeFunctionData({ abi: erc20Abi, data: call.data });
+      } catch {
+        decoded = null;
+      }
+      if (decoded?.functionName !== "approve" || value !== 0n || !same(decoded.args[0], RELAY_APPROVAL_PROXY) || spender) {
+        return refused(`a call on ${symbol} other than approving Relay's approval proxy`);
+      }
+      spender = getAddress(decoded.args[0]);
+      continue;
+    }
+    if (!RELAY_INK.has(to.toLowerCase())) return refused(`a call to ${to}, which is not a Relay contract this version knows; update hookit-mcp`);
+    if (from !== zeroAddress && value > 0n) return refused("ETH sent with a token swap");
+    total += value;
+    txs.push({ to, data: call.data, value });
+  }
+  if (txs.length === 0) return refused("no swap call");
+  if (from === zeroAddress && total > amount) return refused("more ETH than the amount");
+  if (from !== zeroAddress && !spender && txs.some((tx) => same(tx.to, RELAY_APPROVAL_PROXY))) spender = RELAY_APPROVAL_PROXY;
+  return { spender, txs };
+}
+
+const TRANSFER_TOPIC = keccak256(toHex("Transfer(address,address,uint256)"));
+/** eth_simulateV1 reports ETH moves as Transfer logs of this address (traceTransfers). */
+const ETH_TRACE = "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee";
+
+/**
+ * Runs the approval and Relay's transactions together in one eth_simulateV1 from this wallet (nothing is sent) and
+ * checks what the wallet would send and get: at most `amount` of `from` out, at least `min` of `to` in, nothing else
+ * out. Relay contracts run arbitrary calls, so this is what stops a forged quote from paying someone else. null when
+ * sound, else why not.
+ */
+async function relaySimulate(from, to, amount, min, plan) {
+  const wallet = account.address;
+  const calls = [];
+  if (from !== zeroAddress && plan.spender) {
+    calls.push({ from: wallet, to: from, data: encodeFunctionData({ abi: erc20Abi, functionName: "approve", args: [plan.spender, amount] }) });
+  }
+  for (const tx of plan.txs) calls.push({ from: wallet, to: tx.to, data: tx.data, value: toHex(tx.value) });
+  let result;
+  try {
+    result = await publicClient.request({
+      method: "eth_simulateV1",
+      params: [{ blockStateCalls: [{ calls }], traceTransfers: true, validation: false }, "latest"],
+    });
+  } catch (err) {
+    return `this RPC cannot simulate Relay's transactions (eth_simulateV1: ${shortError(err)}). Set HOOKIT_RPC_URL to an Ink RPC that supports it, such as https://rpc-gel.inkonchain.com.`;
+  }
+  const net = new Map();
+  const add = (asset, v) => net.set(asset, (net.get(asset) ?? 0n) + v);
+  for (const call of result?.[0]?.calls ?? []) {
+    if (call.status !== "0x1") return "Relay's swap fails when simulated";
+    for (const log of call.logs ?? []) {
+      if (log.topics?.[0] !== TRANSFER_TOPIC || log.topics.length !== 3) continue;
+      const asset = same(log.address, ETH_TRACE) ? zeroAddress : getAddress(log.address);
+      const v = /^0x[0-9a-fA-F]{1,64}$/.test(log.data ?? "") ? BigInt(log.data) : 0n;
+      if (same(`0x${log.topics[1].slice(26)}`, wallet)) add(asset, -v);
+      if (same(`0x${log.topics[2].slice(26)}`, wallet)) add(asset, v);
+    }
+  }
+  for (const [asset, v] of net) {
+    if (v < 0n && !same(asset, from)) return `Relay's transactions would also take ${asset === zeroAddress ? "ETH" : asset} from the wallet`;
+  }
+  const spent = -(net.get(getAddress(from)) ?? 0n);
+  if (spent > amount) return `Relay's transactions would take more than ${amountText(amount, await assetMeta(from))}`;
+  const got = net.get(getAddress(to)) ?? 0n;
+  if (got < min) return `Relay's transactions would return ${amountText(got, await assetMeta(to))}, below Relay's own minimum of ${amountText(min, await assetMeta(to))}`;
+  return null;
+}
+
+/** The structural and the simulated check of a Relay quote: { plan } or { error } (refused, nothing sent). */
+async function relayCheck(from, to, amount, quote) {
+  const plan = relayPlan(quote.calls, from, amount, quote.inMeta.symbol);
+  if (plan.error) return plan;
+  const why = await relaySimulate(from, to, amount, quote.min, plan);
+  return why ? { error: `Refused Relay's transactions: ${why}. Nothing was sent.` } : { plan };
+}
+
+/** Sets this wallet's allowance of `asset` to `spender` to exactly `amount` (0 revokes). { hash } or { error }. */
+async function setAllowance(asset, spender, amount) {
+  const allowance = await read(asset, erc20Abi, "allowance", [account.address, spender]).catch(() => null);
+  if (allowance === amount) return {};
+  const sent = await send({ address: asset, abi: erc20Abi, functionName: "approve", args: [spender, amount] });
+  return sent.error ? { error: `The approval would fail: ${sent.error}` } : { hash: sent.hash, receipt: sent.receipt };
+}
+
+/** `asset`'s balance of `wallet` at `blockNumber`, retried while a lagging RPC does not have that block yet; null if never. */
+async function balanceAt(asset, wallet, blockNumber) {
+  for (let i = 0; i < 10; i++) {
+    try {
+      return asset === zeroAddress
+        ? await publicClient.getBalance({ address: wallet, blockNumber })
+        : await publicClient.readContract({ address: asset, abi: erc20Abi, functionName: "balanceOf", args: [wallet], blockNumber });
+    } catch {
+      await sleep(500);
+    }
+  }
+  return null;
+}
+
+/** Relay's status of a request ("success", "pending", "failure", "refund"…), through hookit.fun; null if unknown. */
+async function relayStatus(requestId) {
+  if (!/^0x[0-9a-fA-F]{64}$/.test(requestId ?? "")) return null;
+  try {
+    const res = await fetch(`${API}/api/relay/status?requestId=${requestId}`);
+    const body = await res.json().catch(() => null);
+    return res.ok && typeof body?.status === "string" ? body.status : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Swaps `amount` of `from` into `to` on Ink with a Relay quote, from this wallet: checks the quote again (simulated
+ * from the current state), approves exactly `amount` to Relay's approval proxy when `from` is a token, sends Relay's
+ * transactions, then waits until the wallet holds at least Relay's minimum. Whatever happens, no allowance to Relay is
+ * left behind. { received, txs } or { error, txs }; `received` is measured at the swap's block, with the gas paid
+ * counted back when `to` is ETH.
+ */
+async function relayConvert(from, to, amount, quote) {
+  const checked = await relayCheck(from, to, amount, quote);
+  if (checked.error) return { error: checked.error, txs: [] };
+  const { plan } = checked;
+  const txs = [];
+  const receipts = [];
+  const approves = from !== zeroAddress && plan.spender;
+  try {
+    if (approves) {
+      const approval = await setAllowance(from, plan.spender, amount);
+      if (approval.error) return { error: approval.error, txs };
+      if (approval.hash) {
+        txs.push(approval.hash);
+        receipts.push(approval.receipt);
+      }
+    }
+    for (const tx of plan.txs) {
+      let gas;
+      try {
+        await publicClient.call({ account, ...tx });
+        const estimated = await publicClient.estimateGas({ account, ...tx });
+        gas = estimated + estimated / 3n;
+      } catch (err) {
+        return { error: `Relay's swap would fail: ${shortError(err)}`, txs };
+      }
+      const hash = await walletClient.sendTransaction({ ...tx, gas: gas > MAX_TX_GAS ? MAX_TX_GAS : gas });
+      const receipt = await publicClient.waitForTransactionReceipt({ hash });
+      txs.push(hash);
+      receipts.push(receipt);
+      if (receipt.status !== "success") return { error: `Relay's swap reverted: ${EXPLORER}/tx/${hash}`, txs };
+    }
+  } finally {
+    if (approves) {
+      const left = await read(from, erc20Abi, "allowance", [account.address, plan.spender]).catch(() => 1n);
+      if (left > 0n) {
+        const revoked = await setAllowance(from, plan.spender, 0n);
+        if (revoked.hash) txs.push(revoked.hash);
+      }
+    }
+  }
+  // A swap inside Ink settles in Relay's own transaction; otherwise Relay's solver fills it shortly after.
+  const fees = to === zeroAddress ? receipts.reduce((sum, r) => sum + feeOf(r), 0n) : 0n;
+  const before = await balanceAt(to, account.address, receipts[0].blockNumber - 1n);
+  const last = receipts.at(-1).blockNumber;
+  if (before === null) return { error: `Could not read the wallet's ${quote.outMeta.symbol} balance after Relay's swap.`, txs, swapped: true };
+  let got = ((await balanceAt(to, account.address, last)) ?? before) - before + fees;
+  for (let i = 0; got < quote.min && i < 40; i++) {
+    await sleep(1_500);
+    const status = await relayStatus(quote.requestId);
+    if (status === "failure" || status === "refund") {
+      return { error: `Relay reported "${status}" for this swap: ${quote.inMeta.symbol} comes back to the wallet if it was taken.`, txs, swapped: true };
+    }
+    got = (await balanceOf(to, account.address)) - before + fees;
+  }
+  if (got < quote.min) {
+    return { error: `Relay delivered ${amountText(got > 0n ? got : 0n, quote.outMeta)}, below its minimum of ${amountText(quote.min, quote.outMeta)}. Check the wallet (wallet_status).`, txs, swapped: true };
+  }
+  // Positive slippage stays in the wallet: the next leg spends at most what was quoted.
+  return { received: got < quote.out ? got : quote.out, txs };
+}
+
+/**
+ * Where a Relay conversion should land for `coin`, best first: its markets' quotes (USDG, then ETH, then the rest),
+ * then USDG when the aggregator bridges it to a market. `except` (the asset swapped from) is left out.
+ */
+async function landingAssets(c, coin, except) {
+  const usdg = at(c, "usdg");
+  const rank = (a) => (same(a.address, usdg) ? 0 : a.address === zeroAddress ? 1 : 2);
+  const markets = [];
+  for (const m of coin.markets) {
+    if (!markets.some((a) => same(a.address, m.quote))) markets.push(await assetMeta(m.quote));
+  }
+  markets.sort((a, b) => rank(a) - rank(b));
+  const direct = await directAssets(c, coin);
+  const bridged = direct.filter((a) => !markets.some((m) => same(m.address, a.address)));
+  return [...markets, ...bridged].filter((a) => !same(a.address, except));
+}
+
+/** Why one Relay swap must not convert `amount` of `meta` (above the per-buy cap, in ETH or US dollars), or null. */
+async function relayCapRefusal(c, meta, amount) {
+  if (meta.address === zeroAddress) return amount > MAX_BUY_WEI ? `${amountText(amount, meta)} (HOOKIT_MAX_BUY_ETH is ${formatEther(MAX_BUY_WEI)})` : null;
+  const price = await usdPrice(c, meta.address);
+  if (price === null) return `${amountText(amount, meta)}, which could not be priced in US dollars`;
+  const usd = Number(formatUnits(amount, meta.decimals)) * price;
+  return usd > MAX_BUY_USD ? `about $${usd.toFixed(2)} (HOOKIT_MAX_BUY_USD is $${MAX_BUY_USD})` : null;
+}
+
+/** Relay's swap, in words. */
+function relayText(quote) {
+  const impact = quote.impact !== null && Number.isFinite(Number(quote.impact)) ? `, price impact ${Number(quote.impact).toFixed(2)}%` : "";
+  return `${quote.inMeta.symbol} to ${quote.outMeta.symbol} through Relay${impact}`;
+}
+
+/**
+ * The Backed Floor of a coin: { vault, quote, quoteMeta, V, F, perToken(amount) } where `perToken` is what
+ * `redeemFloor` pays for `amount`, or null when the coin has no floor. v2 vaults count the floor over the free supply
+ * F = S − E (coins locked as loan collateral are out of it); v1 vaults over the total supply.
+ */
+async function floorOf(coin) {
+  const vault = await read(coin.key.hooks, floorVaultAbi, "floorVault").catch(() => null);
+  if (!vault || vault === zeroAddress) return null;
+  const quote = await read(vault, floorVaultAbi, "quoteOf", [coin.token]).catch(() => null);
+  let V;
+  let F;
+  let v2 = true;
+  try {
+    const [v, s, e] = await read(vault, floorVaultAbi, "floorState", [coin.token]);
+    V = v;
+    F = s - e;
+  } catch {
+    v2 = false;
+    V = await read(vault, floorVaultAbi, "reserve", [coin.token]).catch(() => 0n);
+    F = await read(coin.token, erc20Abi, "totalSupply");
+  }
+  if (V === 0n || F === 0n || quote === null) return null;
+  const quoteMeta = await assetMeta(getAddress(quote));
+  const perToken = (amount) => (amount * V) / F;
+  // Human price: quote per whole coin.
+  const price = short((V * 10n ** BigInt(coin.meta.decimals)) / F, quoteMeta.decimals);
+  return { vault: getAddress(vault), v2, quote: quoteMeta.address, quoteMeta, V, F, perToken, price: `${price} ${quoteMeta.symbol}` };
+}
+
+/**
+ * Gated Buy before a buy: null when the coin has no closed gate (or the plugin is unknown), { refuse } when this wallet
+ * cannot buy `value` now, else what the gate allows. `value` is in the market's quote (`unit`); null skips the cap
+ * check (a bridged buy, where the hook then refuses an over-cap buy itself).
+ */
+async function gateCheck(c, token, wallet, value, unit = ETH) {
+  const plugin = c.gatedBuyPlugin;
+  if (!plugin) return null;
+  let state;
+  try {
+    state = await publicClient.readContract({ address: plugin, abi: gatedBuyAbi, functionName: "gateState", args: [token] });
+  } catch {
+    return null;
+  }
+  const [hook, , endsAt, open] = state;
+  if (hook === zeroAddress || open) return null;
+  const [[ok, left], params] = await Promise.all([
+    publicClient.readContract({ address: plugin, abi: gatedBuyAbi, functionName: "canBuy", args: [token, wallet] }),
+    publicClient.readContract({ address: plugin, abi: gatedBuyAbi, functionName: "params", args: [token] }),
+  ]);
+  const agentsOnly =
+    !!c.agentPass &&
+    params.listId === 0n &&
+    params.communities.length === 1 &&
+    params.communities[0].token.toLowerCase() === c.agentPass.toLowerCase();
+  if (!ok) {
+    if (agentsOnly) {
+      const status = await agentStatus(c.agentPass, wallet).catch(() => null);
+      if (!status?.holder) return { refuse: `${PASS_STEPS} After ${opensAt(endsAt)} anyone can buy.` };
+    }
+    if (params.walletCap > 0n) {
+      const spent = await publicClient
+        .readContract({ address: plugin, abi: gatedBuyAbi, functionName: "spentOf", args: [token, wallet] })
+        .catch(() => 0n);
+      if (spent >= params.walletCap) {
+        return { refuse: `This wallet used its ${amountText(params.walletCap, unit)} cap for the gate window. It can buy more after ${opensAt(endsAt)}.` };
+      }
+    }
+    return {
+      refuse: `This coin is gated until ${opensAt(endsAt)}: until then only its allowlist and holders of its communities can buy, from their own wallet. Retry after that.`,
+    };
+  }
+  if (value !== null && left !== maxUint256 && value > left) {
+    return {
+      refuse: `During the gate window this wallet can buy at most ${amountText(left, unit)} more of this coin (wallet cap). Retry with an amount at or below that, or after ${opensAt(endsAt)}.`,
+    };
+  }
+  return { agentsOnly, opensAt: opensAt(endsAt), capLeft: left === maxUint256 ? null : amountText(left, unit) };
+}
+
+/** The wallet's loans on the loan plugin that are still open, with what repaying each costs now. */
+async function openLoans(c, wallet) {
+  const plugin = at(c, "loanPlugin");
+  const ids = await read(plugin, loanAbi, "loansOf", [wallet]).catch(() => []);
+  const now = BigInt(Math.floor(Date.now() / 1000));
+  const loans = [];
+  for (const id of ids) {
+    const loan = await read(plugin, loanAbi, "getLoan", [id]);
+    if (loan.status !== 1) continue;
+    const meta = await assetMeta(loan.token);
+    const expired = loan.expiry <= now;
+    const owed = expired ? null : await read(plugin, loanAbi, "repayAmount", [id]).catch(() => null);
+    loans.push({ id, loan, meta, expired, owed });
+  }
+  return loans;
+}
+
+/** One open loan for people, with its quote for amounts (the coin's floor quote). */
+async function loanView(c, { id, loan, meta, expired, owed }) {
+  const coin = await loadCoin(c, loan.token).catch(() => null);
+  const floor = coin ? await floorOf(coin).catch(() => null) : null;
+  const q = floor?.quoteMeta ?? ETH;
+  return {
+    loanId: id.toString(),
+    token: loan.token,
+    collateral: amountText(loan.e, meta),
+    received: amountText(loan.net, q),
+    expires: new Date(Number(loan.expiry) * 1000).toISOString(),
+    ...(expired
+      ? { status: "expired: the collateral is burned at settlement and the wallet keeps what it received; nothing is owed" }
+      : { repayNow: owed === null ? "unknown" : amountText(owed, q) }),
+  };
+}
+
+const launchShape = {
+  name: z.string().describe("Coin name, up to 32 characters."),
+  symbol: z.string().describe("Ticker, 1 to 12 letters or digits."),
+  description: z.string().optional(),
+  image: z.string().optional().describe("Logo as an https:// or ipfs:// URL."),
+  twitter: z.string().optional(),
+  telegram: z.string().optional(),
+  website: z.string().optional(),
+  pair: z.string().optional().describe("What the coin is priced in. Default eth. See list_pairs."),
+  pairs: z.array(z.string()).optional().describe("Several pairs for a multi-pair launch (USDG and stocks only)."),
+  preset: z.string().optional().describe("A strategy from list_presets: clean, community, deflationary, floor, builder, dynamic."),
+  hookTaxPct: z.number().optional().describe("Extra swap fee feeding the hook modules, 0 to 9."),
+  modules: z.record(z.union([z.boolean(), z.number()])).optional().describe("Module settings from list_modules, e.g. {\"autoBurn\": true, \"autoBurnPct\": 100}. Without a preset they start from a clean slate."),
+  devBuyPct: z.number().optional().describe("Creator's own first buy in the launch tx, % of supply (up to 2.5, less with Max Tx). No sniper tax on it."),
+  payout: z
+    .object({
+      kind: z.enum(["wallet", "x", "github", "tiktok"]),
+      address: z.string().optional(),
+      handle: z.string().optional(),
+      accountId: z.string().optional(),
+    })
+    .optional()
+    .describe("Who receives the creator fees. Default: the launching wallet."),
+};
+
+async function prepare(args) {
+  const res = await fetch(`${API}/api/agents/prepare-launch`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ ...args, from: account?.address }),
+  });
+  const body = await res.json().catch(() => ({ ok: false, error: `hookit answered ${res.status}` }));
+  if (!res.ok && !body.error) body.error = `hookit answered ${res.status}`;
+  return body;
+}
+
+/** Most ETH a launch may send: the launch fee plus an ETH dev buy within the per-buy cap. */
+const MAX_LAUNCH_VALUE = MAX_BUY_WEI + parseEther("0.01");
+
+/**
+ * Why the transactions hookit.fun prepared for a launch must not be signed, or null: the launch goes to the pinned
+ * Factory C or CreatorPayoutRouterC with at most MAX_LAUNCH_VALUE, and a dev-buy approval only approves one of those.
+ */
+function launchRefusal(prepared) {
+  const targets = [PINNED.factory, PINNED.payoutRouter];
+  const tx = prepared.tx;
+  if (!tx || !isAddress(tx.to ?? "") || !targets.some((t) => same(t, tx.to))) {
+    return "hookit answered with a launch to a contract this version does not know (not Factory C or its payout router). Nothing was sent; update hookit-mcp.";
+  }
+  if (!/^\d+$/.test(String(tx.value ?? "0")) || BigInt(tx.value ?? 0) > MAX_LAUNCH_VALUE) {
+    return `hookit answered with a launch that sends more than ${formatEther(MAX_LAUNCH_VALUE)} ETH (launch fee plus a dev buy within HOOKIT_MAX_BUY_ETH). Nothing was sent.`;
+  }
+  if (prepared.approve) {
+    let call = null;
+    try {
+      call = decodeFunctionData({ abi: erc20Abi, data: prepared.approve.tx?.data });
+    } catch {}
+    if (call?.functionName !== "approve" || !targets.some((t) => same(t, call.args[0])) || BigInt(prepared.approve.tx?.value ?? 0) !== 0n) {
+      return "hookit answered with a dev-buy approval this version does not expect. Nothing was sent.";
+    }
+  }
+  return null;
+}
+
+/**
+ * Runs the tools that sign one at a time: an agent may call several at once, and two of them sharing the wallet's
+ * nonce or its balance deltas could spend what the other one just received.
+ */
+let signing = Promise.resolve();
+function serialized(handler) {
+  return (...args) => {
+    const run = signing.then(() => handler(...args));
+    signing = run.catch(() => {});
+    return run;
+  };
+}
+
+const server = new McpServer({ name: "hookit", version: VERSION });
+
+server.registerTool(
+  "list_presets",
+  {
+    description: "Launch strategies by goal (clean, community, deflationary, floor, builder, dynamic) with the exact hook modules each one turns on. Needs no key.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+  },
+  async () => {
+    const c = await catalog();
+    return reply(c.presets.map(({ id, label, goal, settings, singlePairOnly }) => ({ id, label, goal, settings, singlePairOnly })));
+  },
+);
+
+server.registerTool(
+  "list_modules",
+  {
+    description: "Every hook module an agent can combine, what it does, its settings and the rules a combination must follow. Needs no key.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+  },
+  async () => {
+    const c = await catalog();
+    return reply({ modules: c.modules, rules: c.rules });
+  },
+);
+
+server.registerTool(
+  "list_pairs",
+  {
+    description: "What a coin can be priced in (ETH, USDG, kBTC, tokenized stocks), and which can be combined in a multi-pair launch. Needs no key.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+  },
+  async () => reply((await catalog()).pairs),
+);
+
+server.registerTool(
+  "wallet_status",
+  {
+    description:
+      "This wallet on Ink: its address, ETH and USDG balances, the hookit.fun coins it holds (with their USD value), its open Backed Floor loans, whether it holds a Hookit Agent Pass, and in words whether it can launch (launch fee and gas).",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+  },
+  async () => {
+    if (!account) return needKey();
+    const c = await catalog();
+    const usdg = await assetMeta(at(c, "usdg"));
+    const [balance, fee, usdgBalance, positions, loans] = await Promise.all([
+      publicClient.getBalance({ address: account.address }),
+      c.factory ? publicClient.readContract({ address: c.factory, abi: factoryAbi, functionName: "launchFee" }).catch(() => null) : null,
+      balanceOf(usdg.address, account.address).catch(() => null),
+      fetch(`${API}/api/wallets/${account.address}`)
+        .then((res) => (res.ok ? res.json() : null))
+        .then((body) => (Array.isArray(body?.positions) ? body.positions : null))
+        .catch(() => null),
+      openLoans(c, account.address).catch(() => []),
+    ]);
+    const gasPrice = await publicClient.getGasPrice();
+    const needed = (fee ?? 0n) + gasPrice * 4_000_000n;
+    // AI-agents-only coins: whether this wallet holds a Hookit Agent Pass.
+    const agentPass = c.agentPass ? await agentStatus(c.agentPass, account.address).catch(() => null) : null;
+    const usd = (n) => Math.round((n ?? 0) * 100) / 100;
+    const holdings =
+      positions === null
+        ? "unavailable (hookit.fun's wallet API did not answer)"
+        : positions
+            .filter((p) => p.balance > 0)
+            .sort((a, b) => (b.valueUsd ?? 0) - (a.valueUsd ?? 0))
+            .slice(0, 25)
+            .map((p) => ({
+              token: p.token,
+              symbol: p.symbol,
+              balance: p.balance,
+              valueUsd: usd(p.valueUsd),
+              ...(p.unrealizedPct !== null && p.unrealizedPct !== undefined ? { unrealizedPct: usd(p.unrealizedPct) } : {}),
+            }));
+    return reply({
+      address: account.address,
+      chain: "Ink (57073)",
+      balanceEth: formatEther(balance),
+      ...(usdgBalance !== null ? { balanceUsdg: short(usdgBalance, usdg.decimals) } : {}),
+      holdings,
+      ...(loans.length ? { loans: await Promise.all(loans.map((l) => loanView(c, l))) } : {}),
+      launchFeeEth: fee === null ? "unknown" : formatEther(fee),
+      roughCostEth: formatEther(needed),
+      ...(agentPass ? { agentPass } : {}),
+      ready: balance >= needed,
+      verdict:
+        balance >= needed
+          ? "Ready to launch."
+          : `Not enough ETH on Ink. Send about ${formatEther(needed - balance)} ETH more to ${account.address}.`,
+      ...(balance >= needed
+        ? {}
+        : {
+            howToFund:
+              "Withdraw ETH from Kraken straight to Ink (choose the Ink network), or bridge from another chain. With the Kraken CLI MCP loaded, an agent can do the withdrawal itself; the user must first whitelist this address in Kraken.",
+          }),
+    });
+  },
+);
+
+server.registerTool(
+  "launch_token",
+  {
+    description:
+      "Launches a coin on hookit.fun with the chosen preset or hook modules, in one call. With dryRun it only checks the launch and returns the unsigned transaction: use it first and show the user the settings.",
+    inputSchema: { ...launchShape, dryRun: z.boolean().optional().describe("Check and simulate only. Signs nothing.") },
+  },
+  serialized(async ({ dryRun, ...args }) => {
+    if (!dryRun && !account) return needKey();
+    let prepared = await prepare(args);
+    if (prepared.error) return fail(prepared.error);
+    let refused = launchRefusal(prepared);
+    if (refused) return fail(refused);
+    if (!dryRun && prepared.approve) {
+      // ERC-20 dev buy: approve the pair token, then prepare again so the launch is simulated.
+      const approveHash = await walletClient.sendTransaction({
+        to: prepared.approve.tx.to,
+        data: prepared.approve.tx.data,
+      });
+      await publicClient.waitForTransactionReceipt({ hash: approveHash });
+      prepared = await prepare(args);
+      if (prepared.error) return fail(prepared.error);
+      refused = launchRefusal(prepared);
+      if (refused) return fail(refused);
+    }
+    if (dryRun) {
+      return reply({
+        dryRun: true,
+        verdict: prepared.simulation?.needsApproval
+          ? "Valid. A real launch will first approve the dev buy token, then launch."
+          : prepared.simulation?.ok === false
+            ? `The launch would fail: ${prepared.simulation.error}`
+            : "The launch is valid.",
+        plan: prepared.plan,
+        approveFirst: prepared.approve ?? null,
+        tx: prepared.tx,
+        warnings: prepared.warnings,
+      });
+    }
+    if (prepared.simulation && !prepared.simulation.ok) {
+      return fail(`The launch would fail: ${prepared.simulation.error}\nSettings: ${prepared.plan.settings.join("; ")}`);
+    }
+
+    const hash = await walletClient.sendTransaction({
+      to: prepared.tx.to,
+      data: prepared.tx.data,
+      value: BigInt(prepared.tx.value),
+      gas: BigInt(prepared.tx.gas),
+    });
+    const receipt = await publicClient.waitForTransactionReceipt({ hash });
+    if (receipt.status !== "success") return fail(`Launch transaction reverted: ${hash}`);
+    let token = null;
+    let agent = null;
+    for (const log of receipt.logs) {
+      for (const abi of [factoryAbi, routerAbi]) {
+        try {
+          const ev = decodeEventLog({ abi, data: log.data, topics: log.topics });
+          if (ev.eventName === "TokenLaunched") token = ev.args.token;
+          if (ev.eventName === "PayoutLaunch") agent = ev.args.agent;
+        } catch {}
+      }
+    }
+    return reply({
+      launched: true,
+      token,
+      page: token ? `${API}/token/${token}` : null,
+      tx: `https://explorer.inkonchain.com/tx/${hash}`,
+      settings: prepared.plan.settings,
+      payout: prepared.plan.payout,
+      payoutAgent: agent,
+      note: agent
+        ? "Creator fees go to the payout target through this launch's CreatorPayoutAgent. This wallet is its controller."
+        : "Creator fees build up in FeeEscrow for this wallet. Call claim_fees to collect them.",
+    });
+  }),
+);
+
+server.registerTool(
+  "claim_fees",
+  {
+    description: "Collects the creator fees this wallet has earned on coins it launched itself (paid in ETH and the pair tokens).",
+    inputSchema: {
+      currencies: z.array(z.string()).optional().describe("Token addresses to collect. Default: ETH plus every pair token."),
+    },
+  },
+  serialized(async ({ currencies }) => {
+    if (!account) return needKey();
+    const c = await catalog();
+    if (!c.factory) return fail("Launches are not configured on this hookit.");
+    const hook = await publicClient.readContract({ address: c.factory, abi: factoryAbi, functionName: "masterHook" });
+    const escrow = await publicClient.readContract({ address: hook, abi: hookAbi, functionName: "feeEscrow" });
+    const candidates = currencies?.length ? currencies : [zeroAddress, ...(c.pairAddresses ?? [])];
+    const owed = [];
+    for (const currency of candidates) {
+      const amount = await publicClient.readContract({ address: escrow, abi: escrowAbi, functionName: "balanceOf", args: [account.address, currency] });
+      if (amount > 0n) owed.push({ currency, amount });
+    }
+    if (owed.length === 0) return reply("Nothing to collect yet.");
+    const hash = await walletClient.writeContract({ address: escrow, abi: escrowAbi, functionName: "claimAll", args: [owed.map((o) => o.currency)] });
+    await publicClient.waitForTransactionReceipt({ hash });
+    const lines = [];
+    for (const { currency, amount } of owed) {
+      if (currency === zeroAddress) {
+        lines.push(`${formatEther(amount)} ETH`);
+        continue;
+      }
+      const [symbol, decimals] = await Promise.all([
+        publicClient.readContract({ address: currency, abi: erc20Abi, functionName: "symbol" }).catch(() => currency),
+        publicClient.readContract({ address: currency, abi: erc20Abi, functionName: "decimals" }).catch(() => 18),
+      ]);
+      lines.push(`${Number(amount) / 10 ** Number(decimals)} ${symbol}`);
+    }
+    return reply({ collected: lines, tx: `https://explorer.inkonchain.com/tx/${hash}` });
+  }),
+);
+
+server.registerTool(
+  "send_eth",
+  {
+    description:
+      "Sends ETH from this wallet on Ink, for example to cash out to the user's Kraken ETH deposit address on the Ink network (get it with the Kraken MCP deposit addresses tool for the \"ETH - Ink\" method only). Kraken's minimum ETH deposit on Ink is 0.001 ETH; smaller deposits fail and the funds are lost, so never send less. Run it with dryRun first and repeat the address and amount to the user before sending.",
+    inputSchema: {
+      to: z.string().describe("Destination address on Ink."),
+      amountEth: z.string().describe('Amount in ETH, or "max" to send everything except gas.'),
+      dryRun: z.boolean().optional().describe("Check only. Signs nothing."),
+    },
+  },
+  serialized(async ({ to, amountEth, dryRun }) => {
+    if (!account) return needKey();
+    if (!isAddress(to)) return fail(`Not an address: ${to}`);
+    const [balance, gasPrice] = await Promise.all([publicClient.getBalance({ address: account.address }), publicClient.getGasPrice()]);
+    // A plain transfer is 21k gas; keep extra for the L1 data fee.
+    const gasReserve = gasPrice * 60_000n + 20_000_000_000_000n;
+    let value;
+    if (amountEth.trim().toLowerCase() === "max") {
+      value = balance > gasReserve ? balance - gasReserve : 0n;
+    } else {
+      try {
+        value = parseEther(amountEth.trim());
+      } catch {
+        return fail(`Not an amount: ${amountEth}`);
+      }
+    }
+    if (value <= 0n) return fail(`Nothing to send: the wallet holds ${formatEther(balance)} ETH.`);
+    if (value + gasReserve > balance) {
+      return fail(`Not enough ETH: the wallet holds ${formatEther(balance)} ETH and needs some left for gas.`);
+    }
+    if (dryRun) return reply({ dryRun: true, from: account.address, to, amountEth: formatEther(value), verdict: "Ready to send." });
+    const hash = await walletClient.sendTransaction({ to, value });
+    await publicClient.waitForTransactionReceipt({ hash });
+    return reply({ sentEth: formatEther(value), to, tx: `https://explorer.inkonchain.com/tx/${hash}` });
+  }),
+);
+
+server.registerTool(
+  "agent_pass_challenge",
+  {
+    description:
+      "Step 1 of 3 to buy an AI-agents-only coin (Gated Buy, AI agents only): starts the Hookit Agent Pass check for this wallet. Returns an id and five short tasks. Answer all of them yourself, in order, and call claim_agent_pass({ id, answers }) within 30 seconds (step 2), then buy_token (step 3). An ERC-8004 agent whose operating wallet is this wallet can pass its agentId here and to claim_agent_pass to get Hookit's ERC-8004 validation instead of a pass. Without agentId, if the wallet already holds a pass or counts as an agent it says so: go straight to buy_token.",
+    inputSchema: {
+      agentId: z
+        .string()
+        .regex(/^[0-9]{1,78}$/, "agentId is a string of digits")
+        .optional()
+        .describe("Optional: your ERC-8004 agent id on Ink, for an ERC-8004 validation (also when this wallet already counts, to publish it). Pass the same agentId to claim_agent_pass."),
+    },
+  },
+  async ({ agentId }) => {
+    if (!account) return needKey();
+    const holder = async (pass) => {
+      const status = await agentStatus(pass, account.address).catch(() => null);
+      if (!status?.holder) return null;
+      return reply({
+        wallet: account.address,
+        agentPass: status,
+        verdict:
+          status.via === "pass"
+            ? "This wallet already holds a Hookit Agent Pass. Go straight to buy_token."
+            : "This wallet already counts as an agent on the Hookit Agent Pass: no pass needed. Go straight to buy_token.",
+      });
+    };
+    if (!agentId) {
+      const already = await holder(at(null, "agentPass"));
+      if (already) return already;
+    }
+    const res = await fetch(`${API}/api/agents/pass?wallet=${account.address}`);
+    const body = await res.json().catch(() => null);
+    if (!res.ok || !body?.ok) return fail(body?.error ?? `hookit answered ${res.status}`);
+    const within = body.solveWithinSec ?? 30;
+    return reply({
+      id: body.id,
+      wallet: body.wallet,
+      tasks: body.tasks,
+      answerWithinSec: within,
+      next: `Answer all ${body.tasks.length} tasks yourself, in order, with short answers only (a number, a word or one character), and call claim_agent_pass with { "id": "${body.id}", "answers": [...]${agentId ? `, "agentId": "${agentId}"` : ""} } within ${within} seconds of this call. One try per challenge: if it fails, call agent_pass_challenge again.`,
+    });
+  },
+);
+
+server.registerTool(
+  "claim_agent_pass",
+  {
+    description:
+      "Step 2 of 3 to buy an AI-agents-only coin: sends your answers to the agent_pass_challenge tasks, signed by this wallet's key, and claims the Hookit Agent Pass on Ink from this wallet (one small transaction). Call it within 30 seconds of agent_pass_challenge. Then buy with buy_token (step 3). With agentId (an ERC-8004 identity on Ink whose operating wallet, agentWallet, is this wallet), it gets Hookit's ERC-8004 validation instead of a pass: if this wallet owns the identity or is its approved operator, it sends the validation request then validate (two transactions, and Hookit publishes a 100/100 \"hookit-agent\" validation anyone can read); otherwise it only links the wallet (one transaction). Either way the wallet then counts as an agent. With requestHash too (a validation request the identity's owner already sent to Hookit's validator), validate answers that request.",
+    inputSchema: {
+      id: z.string().describe("The challenge id returned by agent_pass_challenge."),
+      answers: z
+        .array(z.union([z.string(), z.number()]))
+        .describe("Your answers to the tasks, in the same order: one short answer per task."),
+      agentId: z
+        .string()
+        .regex(/^[0-9]+$/, "agentId is a string of digits")
+        .optional()
+        .describe("Optional: your ERC-8004 agent id on Ink, as a string of digits, to get Hookit's ERC-8004 validation instead of a pass. This wallet must be the identity's agentWallet."),
+      requestHash: z
+        .string()
+        .regex(/^0x[0-9a-fA-F]{64}$/, "requestHash is a 0x-prefixed 32-byte hex string")
+        .optional()
+        .describe("Optional, with agentId: the hash of a validationRequest the identity's owner already sent to Hookit's validator on Ink's ValidationRegistry; Hookit then publishes its response to it."),
+    },
+  },
+  serialized(async ({ id, answers, agentId, requestHash }) => {
+    if (!account) return needKey();
+    if (requestHash && !agentId) return fail("requestHash goes with agentId. Nothing was sent.");
+    if (agentId && BigInt(agentId) > maxUint256) return fail("agentId is too large for an ERC-8004 identity. Nothing was sent.");
+    const sent = answers.map((a) => String(a).trim());
+    const signature = await account.signMessage({ message: passMessage(account.address, id, sent) });
+    const res = await fetch(`${API}/api/agents/pass`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ id, wallet: account.address, answers: sent, signature, ...(agentId ? { agentId } : {}) }),
+    });
+    const body = await res.json().catch(() => null);
+    if (!res.ok || !body?.ok) {
+      const error = body?.error ?? `hookit answered ${res.status}`;
+      const used = [400, 401, 408, 410].includes(res.status) || (res.status === 403 && /operating wallet/.test(error));
+      const retry = used ? " Call agent_pass_challenge for a new challenge and answer within 30 seconds." : "";
+      return fail(`${error}${retry}`);
+    }
+    if (agentId) return claimValidation(body, agentId, requestHash?.toLowerCase());
+    if (body.alreadyHolder) {
+      return reply({ wallet: account.address, agentPass: { holder: true, via: "pass" }, verdict: "This wallet already holds a Hookit Agent Pass. Go straight to buy_token." });
+    }
+    // Only ever send claim(deadline, signature) to the pinned pass, with no value, whatever the answer says.
+    const pass = at(null, "agentPass");
+    if (!same(body.pass, pass)) return fail("hookit answered with an unexpected pass address. Nothing was sent.");
+    let call;
+    try {
+      if (body.claim?.to?.toLowerCase() !== pass.toLowerCase()) throw new Error("to");
+      call = decodeFunctionData({ abi: passAbi, data: body.claim.data });
+      if (call.functionName !== "claim") throw new Error("fn");
+    } catch {
+      return fail("hookit answered with an unexpected claim transaction. Nothing was sent.");
+    }
+    let request;
+    try {
+      ({ request } = await publicClient.simulateContract({ account, address: pass, abi: passAbi, functionName: "claim", args: call.args }));
+    } catch (err) {
+      const name = errorName(err);
+      const why =
+        name === "Expired"
+          ? "the voucher expired. Call agent_pass_challenge again."
+          : name === "Revoked"
+            ? "this wallet's pass was revoked; it cannot claim again unless the owner lifts the revocation."
+            : name === "AlreadyHolder"
+              ? "this wallet already holds a pass. Go straight to buy_token."
+              : name === "InvalidSignature"
+                ? "the voucher's signature was refused. Call agent_pass_challenge again later."
+                : /insufficient funds/.test(errorText(err))
+                  ? "the wallet has no ETH on Ink for the gas."
+                  : String(err?.shortMessage || err?.message || err).slice(0, 300);
+      return fail(`The claim would fail: ${why}`);
+    }
+    const hash = await walletClient.writeContract(request);
+    const receipt = await publicClient.waitForTransactionReceipt({ hash });
+    if (receipt.status !== "success") return fail(`Claim transaction reverted: ${EXPLORER}/tx/${hash}`);
+    const balance = await publicClient.readContract({ address: pass, abi: passAbi, functionName: "balanceOf", args: [account.address] });
+    return reply({
+      claimed: true,
+      wallet: account.address,
+      pass,
+      balanceOf: balance.toString(),
+      tx: `${EXPLORER}/tx/${hash}`,
+      next: "This wallet now holds a Hookit Agent Pass. Buy AI-agents-only coins with buy_token (step 3), from this same wallet.",
+    });
+  }),
+);
+
+/**
+ * The asset a coin trades against by default: its only market's quote, USDG for a multi-pair coin (a sale of a
+ * multi-pair coin without the v2 aggregator goes to the market that pays the most instead: see sell_token).
+ */
+function defaultAsset(c, coin) {
+  return coin.markets.length === 1 ? coin.markets[0].quote : at(c, "usdg");
+}
+
+/** How a trade is routed, in words. */
+async function routeText(c, coin, route, isBuy) {
+  if (route.kind === "router") return `direct, in the coin's ${(await assetMeta(route.market.quote)).symbol} market (HookitSwapRouter)`;
+  const market = coin.markets[route.leg.marketIndex];
+  const q = await assetMeta(market.quote);
+  if (same(market.quote, at(c, "usdg"))) return "direct, in the coin's USDG market (Hookit aggregator)";
+  const bridge = `the USDG/${q.symbol} Uniswap ${route.leg.venue === 1 ? "v3" : "v4"} pool`;
+  return isBuy
+    ? `USDG to ${q.symbol} through ${bridge}, then the coin's ${q.symbol} market (Hookit aggregator, one transaction)`
+    : `the coin's ${q.symbol} market, then ${q.symbol} to USDG through ${bridge} (Hookit aggregator, one transaction)`;
+}
+
+const tokenArg = z.string().describe("The coin's address on Ink.");
+const slippageArg = z.number().int().min(1).max(5000).optional().describe("Max slippage in basis points. Default 500 (5%).");
+const dryRunArg = z.boolean().optional().describe("Quote and check only. Signs nothing.");
+
+server.registerTool(
+  "buy_token",
+  {
+    description:
+      "Buys a hookit.fun coin from this wallet, exact-input: you set what you spend. Pay with ETH, USDG, kBTC or a tokenized stock such as wNVDAx; by default it pays with the coin's own pair (USDG for a multi-pair coin). USDG buys v2 coins priced in a tokenized stock in one transaction (bridged on chain, best route picked). When the coin does not trade in what you pay with (ETH for a coin priced in a stock, USDG for a coin priced in ETH…), it first swaps it through Relay into an asset the coin trades in, then buys: two transactions, both shown in a dryRun. On a coin with several markets, the Relay swap lands in the market where the coin is cheapest, and a buy is refused when the market of the asset you pay with prices the coin far above its other markets. The wallet signs, so it is what a launch gate checks. Step 3 for AI-agents-only coins: if the coin needs an Agent Pass this wallet does not hold, it sends nothing and says to run agent_pass_challenge then claim_agent_pass first. Paying with a token approves exactly the amount first. Use dryRun to quote without sending.",
+    inputSchema: {
+      token: tokenArg,
+      amount: z
+        .union([z.string(), z.number()])
+        .optional()
+        .describe(`What to spend, in payWith units: "0.01" (ETH), "25" (USDG), or "50%" of the balance. At most ${formatEther(MAX_BUY_WEI)} ETH or $${MAX_BUY_USD} per buy.`),
+      payWith: z.string().optional().describe('"eth", "usdg", a pair ticker from list_pairs such as "wNVDAx" or "kBTC", or a token address. Default: the coin\'s own pair.'),
+      amountEth: z.union([z.string(), z.number()]).optional().describe("Older form of amount with payWith \"eth\"."),
+      slippageBps: slippageArg,
+      dryRun: dryRunArg,
+    },
+  },
+  serialized(async ({ token, amount, payWith, amountEth, slippageBps, dryRun }) => {
+    if (!account) return needKey();
+    if (!isAddress(token)) return fail(`Not an address: ${token}`);
+    if (amount === undefined && amountEth !== undefined) {
+      amount = amountEth;
+      payWith ??= "eth";
+    }
+    if (amount === undefined) return fail('amount is required, e.g. { "amount": "0.01", "payWith": "eth" }.');
+    token = getAddress(token);
+    const c = await catalog();
+    const coin = await loadCoin(c, token);
+    if (!coin) return fail(NOT_A_COIN);
+    const asset = payWith ? await resolveAsset(c, payWith, coin) : defaultAsset(c, coin);
+    if (!asset || same(asset, token)) {
+      return fail(`Cannot pay with "${payWith}". Pay with ETH, USDG, a pair ticker from list_pairs or a token address; this coin trades in ${(await tradeAssets(c, coin)).join(", ")}.`);
+    }
+    const pay = await assetMeta(asset);
+    const [ethBalance, reserve] = await Promise.all([publicClient.getBalance({ address: account.address }), gasReserve(2_000_000n)]);
+    const balance = asset === zeroAddress ? (ethBalance > reserve ? ethBalance - reserve : 0n) : await balanceOf(asset, account.address);
+    const value = parseAmount(amount, pay, balance);
+    if (value === null) return fail(`Not an amount: ${amount}`);
+    if (value <= 0n) return fail(`Nothing to spend: the wallet holds ${amountText(balance, pay)}${asset === zeroAddress ? " beyond gas" : ""}.`);
+    if (asset === zeroAddress && value > MAX_BUY_WEI) {
+      return fail(`buy_token spends at most ${formatEther(MAX_BUY_WEI)} ETH per buy (HOOKIT_MAX_BUY_ETH). Buy less, or in several buys.`);
+    }
+    if (value > balance) {
+      return fail(`Not enough ${pay.symbol}: the wallet holds ${amountText(balance, pay)}${asset === zeroAddress ? " beyond gas" : ""}, and the buy spends ${amountText(value, pay)}.`);
+    }
+    if (ethBalance < reserve) return fail(`Not enough ETH for gas: the wallet holds ${formatEther(ethBalance)} ETH and needs about ${formatEther(reserve)}.`);
+
+    // The coin's trade runs in `leg` (an asset it trades in). When `asset` is not one, Relay swaps it into one first.
+    const bps = BigInt(slippageBps ?? 500);
+    const relayBps = Math.min(slippageBps ?? 100, RELAY_MAX_SLIPPAGE_BPS);
+    let leg = pay;
+    let legAmount = value;
+    let relay = null;
+    if (!(await directAssets(c, coin)).some((a) => same(a.address, asset))) {
+      let firstError = null;
+      // Land where the coin is cheapest: the markets of one coin can be priced far apart.
+      const landings = (await landingAssets(c, coin, asset)).filter((a) => relayable(c, asset, a.address));
+      if (!landings.length) firstError = `Relay does not swap ${pay.symbol} into what this coin trades in through hookit.fun (one side must be ETH or USDG).`;
+      for (const landing of (await rankBuyLandings(c, coin, pay, value, landings)).slice(0, 3)) {
+        const q = await relayQuote(asset, landing.address, value, relayBps);
+        const checked = q.quote ? await relayCheck(asset, landing.address, value, q.quote) : q;
+        if (q.quote && !checked.error) {
+          relay = q.quote;
+          leg = landing;
+          legAmount = q.quote.out;
+          break;
+        }
+        if (!checked.unsupported || !firstError) firstError = checked.error;
+      }
+      if (!relay) {
+        const assets = await tradeAssets(c, coin);
+        return fail(`${firstError ?? "Relay cannot swap into what this coin trades in."} This coin trades in ${assets.join(", ")}: pay with ${assets.length > 1 ? "one of those" : "that"} instead.`);
+      }
+    }
+    if (asset !== zeroAddress) {
+      let price = await usdPrice(c, asset);
+      let usd = price === null ? null : Number(formatUnits(value, pay.decimals)) * price;
+      if (usd === null && relay) {
+        price = await usdPrice(c, leg.address);
+        usd = price === null ? null : Number(formatUnits(legAmount, leg.decimals)) * price;
+      }
+      if (usd === null) {
+        return fail(`Could not price ${pay.symbol} in US dollars for the $${MAX_BUY_USD} per-buy cap: hookit.fun's coin list has no price for it and no USDG pool on Ink quoted it. Nothing was sent; pay with ETH or USDG instead.`);
+      }
+      if (usd > MAX_BUY_USD) {
+        return fail(`buy_token spends at most $${MAX_BUY_USD} per buy (HOOKIT_MAX_BUY_USD); ${amountText(value, pay)} is about $${usd.toFixed(2)}. Buy less, or in several buys.`);
+      }
+    }
+
+    const inMarket = coin.markets.some((m) => same(m.quote, leg.address));
+    const gate = await gateCheck(c, token, account.address, inMarket ? legAmount : null, leg);
+    if (gate?.refuse) return fail(gate.refuse);
+    const planned = await planTrade(c, coin, true, leg.address, legAmount);
+    if (planned.error) return fail(planned.error);
+    let { route } = planned;
+    if (!relay && route.kind === "router" && coin.markets.length > 1) {
+      const cheaper = await cheaperMarket(c, coin, pay, value, route.out);
+      if (cheaper) {
+        const via = relayable(c, zeroAddress, cheaper.asset.address) ? `, or with ETH or USDG (swapped through Relay into that market)` : "";
+        return fail(
+          `This coin costs about ${cheaper.ratio}x more in its ${pay.symbol} market than in its ${cheaper.asset.symbol} market: ${amountText(value, pay)} buys ${amountText(route.out, coin.meta)} here, and the same dollars buy about ${amountText(cheaper.out, coin.meta)} there. Pay with ${cheaper.asset.symbol}${via}. Nothing was sent.`,
+        );
+      }
+    }
+    let minOut = (route.out * (10_000n - bps)) / 10_000n || 1n;
+    const routeWords = await routeText(c, coin, route, true);
+    const quote = {
+      token,
+      spend: amountText(value, pay),
+      ...(relay ? { relay: `${amountText(relay.out, leg)} expected, at least ${amountText(relay.min, leg)}` } : {}),
+      expected: amountText(route.out, coin.meta),
+      minimum: amountText(minOut, coin.meta),
+      route: relay ? `${relayText(relay)}, then ${routeWords} (two transactions)` : routeWords,
+      slippageBps: Number(bps),
+      ...(gate ? { gate: gate.agentsOnly ? `AI agents only until ${gate.opensAt}` : `gated until ${gate.opensAt}`, capLeft: gate.capLeft } : {}),
+    };
+    if (dryRun) {
+      const approvals = [
+        ...(relay && asset !== zeroAddress ? [`exactly ${amountText(value, pay)} to Relay's approval proxy`] : []),
+        ...(leg.address !== zeroAddress ? [`exactly ${relay ? `the ${leg.symbol} Relay returns` : amountText(value, pay)} to ${route.spender}`] : []),
+      ];
+      return reply({
+        dryRun: true,
+        ...quote,
+        ...(relay ? { relayCheck: "Relay's transactions were simulated from this wallet: they only spend what you pay and return at least Relay's minimum." } : {}),
+        ...(approvals.length ? { approval: `A real buy first approves ${approvals.join(", then ")}.` } : {}),
+        verdict: "The buy would go through at this price.",
+      });
+    }
+
+    const txs = [];
+    const links = () => txs.map((h) => `${EXPLORER}/tx/${h}`);
+    let partial = null;
+    if (relay) {
+      const converted = await relayConvert(asset, leg.address, value, relay);
+      txs.push(...converted.txs);
+      if (converted.error) {
+        if (!converted.swapped) return fail(`${converted.error}${txs.length ? ` Sent: ${links().join(", ")}.` : ""}`);
+        return reply({ partial: true, spent: quote.spend, problem: converted.error, tx: links(), doNotRetry: "Relay's swap went through. Check the wallet before buying again." });
+      }
+      // What Relay returned buys the coin, at no worse a price than quoted: the minimum scales with what arrived.
+      const quotedMin = (((route.out * converted.received) / relay.out) * (10_000n - bps)) / 10_000n;
+      legAmount = converted.received;
+      partial = (problem) =>
+        reply({
+          partial: true,
+          spent: quote.spend,
+          relaySwap: `${amountText(value, pay)} into ${amountText(legAmount, leg)}`,
+          problem,
+          tx: links(),
+          doNotRetry: `Relay's swap went through and the wallet keeps the ${amountText(legAmount, leg)}. Buy the coin with ${leg.symbol} (payWith "${leg.symbol}") instead of retrying this call.`,
+        });
+      const again = await planTrade(c, coin, true, leg.address, legAmount);
+      if (again.error) return partial(`The buy would fail now: ${again.error}`);
+      route = again.route;
+      minOut = (route.out * (10_000n - bps)) / 10_000n || 1n;
+      if (minOut < quotedMin) minOut = quotedMin;
+      if (route.out < minOut) return partial(`The coin's price moved past the slippage floor since the quote (now ${amountText(route.out, coin.meta)}, floor ${amountText(minOut, coin.meta)}).`);
+    }
+    const approval = await approveIfNeeded(leg.address, route.spender, legAmount);
+    if (approval.error) return partial ? partial(approval.error) : fail(approval.error);
+    if (approval.hash) txs.push(approval.hash);
+    const sent = await send(await tradeCall(coin, route, true, leg.address, legAmount, minOut), {
+      minGas: SWAP_MIN_GAS,
+      explain: (err) => swapFailure(err),
+    });
+    if (sent.hash) txs.push(sent.hash);
+    if (sent.error) {
+      const why = sent.hash ? `The buy reverted (price moved past the slippage floor?): ${EXPLORER}/tx/${sent.hash}` : sent.error;
+      if (partial) return partial(why);
+      const approved = approval.hash ? ` The approval went through (${EXPLORER}/tx/${approval.hash}).` : "";
+      return fail(`${why}${approved}`);
+    }
+    const block = sent.receipt.blockNumber;
+    const [before, after] = await Promise.all([balanceAt(token, account.address, block - 1n), balanceAt(token, account.address, block)]);
+    return reply({
+      bought: before !== null && after !== null ? amountText(after - before, coin.meta) : `about ${amountText(route.out, coin.meta)}`,
+      spent: quote.spend,
+      ...(relay ? { relaySwap: `${amountText(value, pay)} into ${amountText(legAmount, leg)}` } : {}),
+      minimum: amountText(minOut, coin.meta),
+      route: quote.route,
+      page: `${API}/token/${token}`,
+      tx: links(),
+    });
+  }),
+);
+
+server.registerTool(
+  "sell_token",
+  {
+    description:
+      "Sells a hookit.fun coin from this wallet, exact-input: you set how many coins to sell, \"max\" or a percentage. By default it sells for the coin's own pair (ETH, a stock, kBTC); a multi-pair coin sells in the market that pays the most, for that market's asset (USDG through the aggregator on v2 coins). receive \"usdg\" sells v2 coins priced in a tokenized stock for USDG in one transaction. To receive anything else the coin does not trade in (USDG from a coin priced in ETH, ETH from a coin priced in a stock…), or when the market of the asset asked for cannot pay for the sale, it sells in the market that pays the most, then swaps the proceeds through Relay: two transactions. It approves exactly the coins sold first. If the coin's Backed Floor pays more than the market, it says so: redeem_floor then pays more. Use dryRun to quote without sending.",
+    inputSchema: {
+      token: tokenArg,
+      amount: z.union([z.string(), z.number()]).describe('Coins to sell: "1000000", "max" or "50%". "max" keeps 1 wei of the coin.'),
+      receive: z.string().optional().describe('"eth", "usdg", a pair ticker such as "wNVDAx" or "kBTC", or a token address. Default: the coin\'s own pair, or on a multi-pair coin the market that pays the most.'),
+      slippageBps: slippageArg,
+      dryRun: dryRunArg,
+    },
+  },
+  serialized(async ({ token, amount, receive, slippageBps, dryRun }) => {
+    if (!account) return needKey();
+    if (!isAddress(token)) return fail(`Not an address: ${token}`);
+    token = getAddress(token);
+    const c = await catalog();
+    const coin = await loadCoin(c, token);
+    if (!coin) return fail(NOT_A_COIN);
+    const asset = receive ? await resolveAsset(c, receive, coin) : defaultAsset(c, coin);
+    if (!asset || same(asset, token)) {
+      return fail(`Cannot sell for "${receive}". Receive ETH, USDG, a pair ticker from list_pairs or a token address; this coin trades in ${(await tradeAssets(c, coin)).join(", ")}.`);
+    }
+    let out = await assetMeta(asset);
+    const [balance, ethBalance, reserve] = await Promise.all([
+      balanceOf(token, account.address),
+      publicClient.getBalance({ address: account.address }),
+      gasReserve(2_000_000n),
+    ]);
+    const value = parseAmount(amount, coin.meta, balance, true);
+    if (value === null) return fail(`Not an amount: ${amount}`);
+    if (value <= 0n) return fail(`Nothing to sell: the wallet holds ${amountText(balance, coin.meta)}.`);
+    if (value > balance) return fail(`The wallet holds only ${amountText(balance, coin.meta)}.`);
+    if (ethBalance < reserve) return fail(`Not enough ETH for gas: the wallet holds ${formatEther(ethBalance)} ETH and needs about ${formatEther(reserve)}.`);
+
+    // The coin sells for `leg` (an asset it trades in). When `asset` is not one, Relay swaps the proceeds into it.
+    const bps = BigInt(slippageBps ?? 500);
+    const relayBps = Math.min(slippageBps ?? 100, RELAY_MAX_SLIPPAGE_BPS);
+    let leg = out;
+    let route = null;
+    let relay = null;
+    let thin = null;
+    let picked = null;
+    const direct = await directAssets(c, coin);
+    if (!receive && coin.markets.length > 1 && !(await aggregatorFor(c, coin))) {
+      // A multi-pair coin without the v2 aggregator: sell in the market that pays the most, for its own quote, in one
+      // transaction (USDG when it pays within 2% of the best). Most of its markets only pay what their buyers paid in.
+      const { ranked, firstError, thinOnly } = await rankSales(c, coin, value, direct);
+      if (!ranked.length) return fail(thinOnly ? saleTooBig(coin, value, await largestSale(c, coin, direct, value)) : firstError);
+      const usdg = ranked.find((r) => same(r.asset.address, at(c, "usdg")));
+      const pick = usdg && ranked[0].usd !== null && usdg.usd >= ranked[0].usd * 0.98 ? usdg : ranked[0];
+      out = leg = pick.asset;
+      route = pick.route;
+      if (direct.length > 1) picked = `Sold in the coin's ${pick.asset.symbol} market, the one that pays the most for it now. Pass receive to pick another asset.`;
+    } else if (direct.some((a) => same(a.address, asset))) {
+      const planned = await planTrade(c, coin, false, asset, value);
+      if (!planned.error) route = planned.route;
+      else if (planned.thin) thin = planned.error;
+      else return fail(planned.error);
+    }
+    if (!route) {
+      // Sell where it pays the most among the markets Relay can swap from into `asset`, then swap the proceeds.
+      const landings = (await landingAssets(c, coin, asset)).filter((a) => relayable(c, a.address, asset));
+      const { ranked, firstError, thinOnly } = await rankSales(c, coin, value, landings);
+      if (!ranked.length && thinOnly && (thin || landings.length)) {
+        return fail(saleTooBig(coin, value, await largestSale(c, coin, thin ? [out, ...landings] : landings, value)));
+      }
+      let relayError = null;
+      for (const r of ranked.slice(0, 3)) {
+        const q = await relayQuote(r.asset.address, asset, r.route.out, relayBps);
+        if (q.quote) {
+          leg = r.asset;
+          route = r.route;
+          relay = q.quote;
+          break;
+        }
+        if (!q.unsupported || !relayError) relayError = q.error;
+      }
+      if (!relay) {
+        if (thin) {
+          return fail(
+            `${thin} ${ranked.length ? `Selling in its ${ranked[0].asset.symbol} market and swapping to ${out.symbol} through Relay did not work either: ${relayError}` : `No other market of this coin can pay for it either: ${firstError}`} Sell less, or receive another asset.`,
+          );
+        }
+        const assets = await tradeAssets(c, coin);
+        const none = landings.length ? "Relay cannot swap what this coin trades in." : `Relay does not swap what this coin trades in into ${out.symbol} through hookit.fun (one side must be ETH or USDG).`;
+        return fail(`${relayError ?? firstError ?? none} This coin trades in ${assets.join(", ")}: receive ${assets.length > 1 ? "one of those" : "that"} instead.`);
+      }
+      const capped = await relayCapRefusal(c, leg, route.out);
+      if (capped) return fail(`The sale would pay ${capped}, more than one Relay swap converts. Receive ${leg.symbol} (receive "${leg.symbol}"), or sell less at a time.`);
+    }
+    const minOut = (route.out * (10_000n - bps)) / 10_000n || 1n;
+    const floor = await floorOf(coin).catch(() => null);
+    const atFloor = floor && same(floor.quote, leg.address) ? floor.perToken(value) : null;
+    const routeWords = await routeText(c, coin, route, false);
+    // Relay's minimum, scaled to the sale's own minimum.
+    const finalMin = relay ? (relay.min * minOut) / route.out : minOut;
+    const quote = {
+      token,
+      sell: amountText(value, coin.meta),
+      ...(relay ? { sale: `${amountText(route.out, leg)} expected, at least ${amountText(minOut, leg)}` } : {}),
+      expected: amountText(relay ? relay.out : route.out, out),
+      minimum: `${amountText(finalMin, out)}${relay ? " (estimated: Relay quotes again for what the sale returns)" : ""}`,
+      route: relay ? `${routeWords}, then ${relayText(relay)} (two transactions)` : routeWords,
+      ...(picked ? { market: picked } : {}),
+      slippageBps: Number(bps),
+      ...(atFloor !== null && atFloor > route.out
+        ? { betterAtFloor: `The Backed Floor pays more right now: redeem_floor would pay ${amountText(atFloor, leg)} for these coins.` }
+        : {}),
+    };
+    if (dryRun) {
+      const approvals = [
+        `exactly ${amountText(value, coin.meta)} to ${route.spender}`,
+        ...(relay && leg.address !== zeroAddress ? [`exactly the ${leg.symbol} it swaps to Relay's approval proxy`] : []),
+      ];
+      return reply({
+        dryRun: true,
+        ...quote,
+        ...(relay ? { relayCheck: "Relay's transactions are simulated from this wallet once the sale has paid, and refused unless they only spend the proceeds and return at least Relay's minimum." } : {}),
+        approval: `A real sale first approves ${approvals.join(", then ")}.`,
+        verdict: "The sale would go through at this price.",
+      });
+    }
+
+    const txs = [];
+    const links = () => txs.map((h) => `${EXPLORER}/tx/${h}`);
+    const approval = await approveIfNeeded(token, route.spender, value);
+    if (approval.error) return fail(approval.error);
+    if (approval.hash) txs.push(approval.hash);
+    const sent = await send(await tradeCall(coin, route, false, leg.address, value, minOut), {
+      minGas: SWAP_MIN_GAS,
+      explain: (err) => swapFailure(err, "sale"),
+    });
+    if (sent.error) {
+      const approved = approval.hash ? ` The approval went through (${EXPLORER}/tx/${approval.hash}).` : "";
+      return fail(`${sent.hash ? `The sale reverted (price moved past the slippage floor?): ${EXPLORER}/tx/${sent.hash}` : sent.error}${approved}`);
+    }
+    txs.push(sent.hash);
+    const block = sent.receipt.blockNumber;
+    const [before, after] = await Promise.all([balanceAt(leg.address, account.address, block - 1n), balanceAt(leg.address, account.address, block)]);
+    const proceeds = before !== null && after !== null ? after - before + (leg.address === zeroAddress ? feeOf(sent.receipt) : 0n) : null;
+    if (!relay) {
+      return reply({
+        sold: quote.sell,
+        received: proceeds !== null ? amountText(proceeds, out) : `about ${amountText(sent.result ?? route.out, out)}`,
+        minimum: quote.minimum,
+        route: quote.route,
+        ...(picked ? { market: picked } : {}),
+        tx: links(),
+      });
+    }
+
+    const partial = (problem) =>
+      reply({
+        partial: true,
+        sold: quote.sell,
+        ...(proceeds !== null ? { sale: amountText(proceeds, leg) } : {}),
+        problem,
+        tx: links(),
+        doNotRetry: `The sale went through: the wallet keeps the ${leg.symbol}. Do not sell again; swap the ${leg.symbol} later, or keep it.`,
+      });
+    if (proceeds === null || proceeds <= 0n) return partial(`Could not read what the sale paid, so the ${leg.symbol} was not swapped to ${out.symbol}.`);
+    const again = await relayQuote(leg.address, asset, proceeds, relayBps);
+    if (again.error) return partial(again.error);
+    const floorOut = (relay.out * proceeds * (10_000n - bps)) / (route.out * 10_000n);
+    if (again.quote.out < floorOut) {
+      return partial(`Relay now offers only ${amountText(again.quote.out, out)} for it, past the slippage floor (${amountText(floorOut, out)}), so it was not swapped.`);
+    }
+    const converted = await relayConvert(leg.address, asset, proceeds, again.quote);
+    txs.push(...converted.txs);
+    if (converted.error) return partial(`Relay's swap to ${out.symbol} did not complete: ${converted.error}`);
+    return reply({
+      sold: quote.sell,
+      received: amountText(converted.received, out),
+      sale: amountText(proceeds, leg),
+      route: quote.route,
+      tx: links(),
+    });
+  }),
+);
+
+/** Why a FloorVault or FloorLoanPlugin call would fail, in words. */
+function floorFailure(err) {
+  const name = errorName(err);
+  if (name === "LoansNotEnabled") return "loans are not enabled on this coin.";
+  if (name === "CollateralCapExceeded") return "that is more collateral than the loan cap allows now (loans may lock at most half of the free supply).";
+  if (name === "ZeroLoan" || name === "ZeroAmount") return "the amount is too small: it is worth 0 at the floor.";
+  if (name === "BelowMinimum") return "the floor moved and the loan would pay less than quoted. Retry.";
+  if (name === "LoanExpired") return "the loan has expired: it can no longer be repaid. The collateral is burned at settlement and the wallet keeps what it borrowed.";
+  if (name === "LoanNotOpen") return "this loan is not open (already repaid or settled).";
+  if (name === "NotBorrower") return "this wallet is not the borrower of this loan.";
+  if (name === "RepayTooHigh") return "the floor rose past the repay bound. Retry.";
+  if (name === "ModuleHalted") return "Hookit halted the loan module: new loans are paused (repaying still works).";
+  if (name === "InsufficientReserve" || name === "FloorSupplyExhausted") return "the floor reserve cannot pay this amount.";
+  if (/insufficient funds/.test(errorText(err))) return "the wallet does not hold enough ETH for this and its gas.";
+  return shortError(err);
+}
+
+server.registerTool(
+  "redeem_floor",
+  {
+    description:
+      "Redeems coins at their Backed Floor: the coins are burned and the floor reserve pays their floor value (floor price = reserve / circulating supply, a price that never goes down) in the coin's floor quote (ETH, USDG...). No slippage: the payout is exact. It compares with selling on the market and says which pays more. Only coins launched with Backed Floor. Use dryRun to see the payout first.",
+    inputSchema: {
+      token: tokenArg,
+      amount: z.union([z.string(), z.number()]).describe('Coins to redeem: "1000000", "max" or "50%". "max" keeps 1 wei of the coin.'),
+      dryRun: z.boolean().optional().describe("Check only. Signs nothing."),
+    },
+  },
+  serialized(async ({ token, amount, dryRun }) => {
+    if (!account) return needKey();
+    if (!isAddress(token)) return fail(`Not an address: ${token}`);
+    token = getAddress(token);
+    const c = await catalog();
+    const coin = await loadCoin(c, token);
+    if (!coin) return fail(NOT_A_COIN);
+    const floor = await floorOf(coin);
+    if (!floor) return fail("This coin has no Backed Floor reserve to redeem from.");
+    const balance = await balanceOf(token, account.address);
+    const value = parseAmount(amount, coin.meta, balance, true);
+    if (value === null) return fail(`Not an amount: ${amount}`);
+    if (value <= 0n) return fail(`Nothing to redeem: the wallet holds ${amountText(balance, coin.meta)}.`);
+    if (value > balance) return fail(`The wallet holds only ${amountText(balance, coin.meta)}.`);
+    const payout = floor.perToken(value);
+    if (payout === 0n) return fail("Too few coins: they are worth 0 at the floor.");
+    const sale = await planTrade(c, coin, false, floor.quote, value);
+    const saleOut = sale.route?.out ?? null;
+    const view = {
+      token,
+      redeem: amountText(value, coin.meta),
+      receive: amountText(payout, floor.quoteMeta),
+      floorPrice: `${floor.price} per ${coin.meta.symbol}`,
+      ...(saleOut !== null ? { marketWouldPay: amountText(saleOut, floor.quoteMeta) } : {}),
+      verdict:
+        saleOut !== null && saleOut > payout
+          ? `Selling pays more right now (${amountText(saleOut, floor.quoteMeta)}): consider sell_token instead.`
+          : "Redeeming pays at least as much as selling right now.",
+    };
+    if (dryRun) return reply({ dryRun: true, ...view, approval: `A real redeem first approves exactly ${view.redeem} to the floor vault ${floor.vault}.` });
+
+    const approval = await approveIfNeeded(token, floor.vault, value);
+    if (approval.error) return fail(approval.error);
+    const sent = await send(
+      { address: floor.vault, abi: floorVaultAbi, functionName: "redeemFloor", args: [token, value] },
+      { explain: (err) => `The redeem would fail: ${floorFailure(err)}` },
+    );
+    if (sent.error) return fail(sent.error);
+    let received = sent.result;
+    for (const log of sent.receipt.logs) {
+      if (!same(log.address, floor.vault)) continue;
+      try {
+        const ev = decodeEventLog({ abi: floorVaultAbi, data: log.data, topics: log.topics });
+        if (ev.eventName === "Redeemed") received = ev.args.quoteOut;
+      } catch {}
+    }
+    return reply({
+      redeemed: view.redeem,
+      received: amountText(received, floor.quoteMeta),
+      tx: [...(approval.hash ? [`${EXPLORER}/tx/${approval.hash}`] : []), `${EXPLORER}/tx/${sent.hash}`],
+    });
+  }),
+);
+
+server.registerTool(
+  "borrow_against_floor",
+  {
+    description:
+      "Borrows the Backed Floor value of a coin without selling it (v2 coins launched with Backed Floor and loans): the coins are locked as collateral, the wallet receives their floor value minus an upfront fee (1% for 7 days, 1.75% for 14, 3% for 30, 5% for 60, 7% for 90), and repay_loan gets them back before expiry for their floor value then (it only rises with the floor). Without repayment the collateral is burned at expiry and the wallet keeps what it borrowed: nothing more is ever owed, no liquidation before expiry. Use dryRun to see the terms first.",
+    inputSchema: {
+      token: tokenArg,
+      amount: z.union([z.string(), z.number()]).describe('Coins to lock: "1000000", "50%", or "max" (the most the wallet and the loan cap allow).'),
+      days: z.union([z.literal(7), z.literal(14), z.literal(30), z.literal(60), z.literal(90)]).optional().describe("Loan length: 7, 14, 30, 60 or 90 days. Default 30."),
+      dryRun: z.boolean().optional().describe("Check only. Signs nothing."),
+    },
+  },
+  serialized(async ({ token, amount, days, dryRun }) => {
+    if (!account) return needKey();
+    if (!isAddress(token)) return fail(`Not an address: ${token}`);
+    token = getAddress(token);
+    const c = await catalog();
+    const plugin = at(c, "loanPlugin");
+    const coin = await loadCoin(c, token);
+    if (!coin) return fail(NOT_A_COIN);
+    const enabled = await read(plugin, loanAbi, "loansEnabled", [token]).catch(() => false);
+    if (!enabled) return fail("Loans are not enabled on this coin. Only v2 coins launched with Backed Floor and loans (the \"Allow loans\" option) can be borrowed against.");
+    const floor = await floorOf(coin);
+    if (!floor) return fail("This coin's Backed Floor reserve is empty: there is nothing to borrow yet.");
+    const length = days ?? 30;
+    const duration = BigInt(length * 86_400);
+    const [balance, cap] = await Promise.all([balanceOf(token, account.address), read(plugin, loanAbi, "maxCollateral", [token])]);
+    const isMax = ["max", "all"].includes(String(amount).trim().toLowerCase());
+    let value = parseAmount(amount, coin.meta, balance, true);
+    if (value === null) return fail(`Not an amount: ${amount}`);
+    if (isMax && value > cap) value = cap;
+    if (value <= 0n) {
+      return fail(cap === 0n ? "The loan cap is reached on this coin: no new collateral can be locked now." : `Nothing to lock: the wallet holds ${amountText(balance, coin.meta)}.`);
+    }
+    if (value > balance) return fail(`The wallet holds only ${amountText(balance, coin.meta)}.`);
+    if (value > cap) return fail(`At most ${amountText(cap, coin.meta)} can be locked now (loans may lock at most half of the free supply). Use "max".`);
+    let preview;
+    try {
+      preview = await read(plugin, loanAbi, "previewBorrow", [token, value, duration]);
+    } catch (err) {
+      return fail(`The loan would fail: ${floorFailure(err)}`);
+    }
+    const [gross, fee, net] = preview;
+    const minNet = (net * 995n) / 1000n;
+    const q = floor.quoteMeta;
+    const terms = {
+      token,
+      collateral: amountText(value, coin.meta),
+      receive: amountText(net, q),
+      fee: `${amountText(fee, q)} (${LOAN_FEES_BPS[length] / 100}% upfront, kept by the floor reserve)`,
+      days: length,
+      expiresAround: new Date(Date.now() + length * 86_400_000).toISOString(),
+      repayToday: amountText(gross, q),
+      howItEnds: `Repay with repay_loan before expiry to get the coins back, for their floor value at that time (${amountText(gross, q)} today; more if the floor rose). Without repayment the coins are burned at expiry and the wallet keeps the ${q.symbol}: nothing more is owed.`,
+    };
+    if (dryRun) return reply({ dryRun: true, ...terms, approval: `A real loan first approves exactly ${terms.collateral} to the loan plugin ${plugin}.` });
+
+    const approval = await approveIfNeeded(token, plugin, value);
+    if (approval.error) return fail(approval.error);
+    const sent = await send(
+      { address: plugin, abi: loanAbi, functionName: "borrow", args: [token, value, duration, minNet] },
+      { explain: (err) => `The loan would fail: ${floorFailure(err)}` },
+    );
+    if (sent.error) return fail(sent.error);
+    let loanId = sent.result;
+    let got = net;
+    let expiry = null;
+    for (const log of sent.receipt.logs) {
+      if (!same(log.address, plugin)) continue;
+      try {
+        const ev = decodeEventLog({ abi: loanAbi, data: log.data, topics: log.topics });
+        if (ev.eventName === "Borrowed") ({ loanId, net: got, expiry } = ev.args);
+      } catch {}
+    }
+    return reply({
+      borrowed: true,
+      loanId: loanId.toString(),
+      collateral: terms.collateral,
+      received: amountText(got, q),
+      expires: expiry ? new Date(Number(expiry) * 1000).toISOString() : terms.expiresAround,
+      next: `Repay with repay_loan({ "loanId": "${loanId}" }) before expiry to get the coins back.`,
+      tx: [...(approval.hash ? [`${EXPLORER}/tx/${approval.hash}`] : []), `${EXPLORER}/tx/${sent.hash}`],
+    });
+  }),
+);
+
+server.registerTool(
+  "repay_loan",
+  {
+    description:
+      "Repays a Backed Floor loan of this wallet before it expires and gets the collateral coins back. It pays the collateral's floor value now (at least what was borrowed: the floor never goes down), in the loan's quote (ETH, USDG...). Without loanId it repays the wallet's only open loan. Use dryRun to see the amount first.",
+    inputSchema: {
+      loanId: z.string().regex(/^[0-9]+$/, "loanId is a string of digits").optional().describe("The loan id from borrow_against_floor or wallet_status. Default: the only open loan."),
+      dryRun: z.boolean().optional().describe("Check only. Signs nothing."),
+    },
+  },
+  serialized(async ({ loanId, dryRun }) => {
+    if (!account) return needKey();
+    const c = await catalog();
+    const plugin = at(c, "loanPlugin");
+    let id;
+    if (loanId) {
+      id = BigInt(loanId);
+    } else {
+      const open = (await openLoans(c, account.address)).filter((l) => !l.expired);
+      if (open.length === 0) return fail("This wallet has no open loan to repay.");
+      if (open.length > 1) {
+        return fail(`This wallet has ${open.length} open loans: ${open.map((l) => `${l.id} (${amountText(l.loan.e, l.meta)})`).join(", ")}. Pass the loanId to repay.`);
+      }
+      id = open[0].id;
+    }
+    const loan = await read(plugin, loanAbi, "getLoan", [id]).catch(() => null);
+    if (!loan || loan.borrower === zeroAddress) return fail(`There is no loan ${id}.`);
+    if (!same(loan.borrower, account.address)) return fail(`Loan ${id} belongs to another wallet.`);
+    if (loan.status !== 1) return fail(`Loan ${id} is not open: it was already ${loan.status === 2 ? "repaid" : "settled at expiry"}.`);
+    if (BigInt(Math.floor(Date.now() / 1000)) >= loan.expiry) {
+      return fail(`Loan ${id} has expired: it can no longer be repaid. The collateral is burned at settlement and the wallet keeps what it borrowed; nothing is owed.`);
+    }
+    const coin = await loadCoin(c, loan.token);
+    const floor = coin ? await floorOf(coin) : null;
+    if (!coin || !floor) return fail("Could not read this loan's coin and floor on Ink. Nothing was sent; retry later.");
+    const q = floor.quoteMeta;
+    let owed;
+    try {
+      owed = await read(plugin, loanAbi, "repayAmount", [id]);
+    } catch (err) {
+      return fail(`The repay would fail: ${floorFailure(err)}`);
+    }
+    // The floor can rise before the transaction lands: allow 0.5% more; ETH above the actual amount is refunded.
+    const maxRepay = owed + (owed * 5n) / 1000n + 1n;
+    const native = floor.quote === zeroAddress;
+    const [ethBalance, reserve] = await Promise.all([publicClient.getBalance({ address: account.address }), gasReserve(800_000n)]);
+    const holds = native ? ethBalance : await balanceOf(floor.quote, account.address);
+    if (holds < (native ? maxRepay + reserve : owed)) {
+      return fail(`Not enough ${q.symbol}: repaying costs ${amountText(owed, q)}${native ? " plus gas" : ""}, and the wallet holds ${amountText(holds, q)}.`);
+    }
+    if (!native && ethBalance < reserve) return fail(`Not enough ETH for gas: the wallet holds ${formatEther(ethBalance)} ETH.`);
+    const view = {
+      loanId: id.toString(),
+      repay: amountText(owed, q),
+      getBack: amountText(loan.e, coin.meta),
+      expires: new Date(Number(loan.expiry) * 1000).toISOString(),
+    };
+    if (dryRun) {
+      return reply({
+        dryRun: true,
+        ...view,
+        bound: `It sends at most ${amountText(maxRepay, q)}${native ? " (the rest is refunded)" : ` and first approves that much ${q.symbol} to ${plugin}`}.`,
+      });
+    }
+    const approval = native ? {} : await approveIfNeeded(floor.quote, plugin, maxRepay);
+    if (approval.error) return fail(approval.error);
+    const sent = await send(
+      { address: plugin, abi: loanAbi, functionName: "repay", args: [id, maxRepay], ...(native ? { value: maxRepay } : {}) },
+      { explain: (err) => `The repay would fail: ${floorFailure(err)}` },
+    );
+    if (sent.error) return fail(sent.error);
+    return reply({
+      repaid: amountText(sent.result, q),
+      gotBack: view.getBack,
+      tx: [...(approval.hash ? [`${EXPLORER}/tx/${approval.hash}`] : []), `${EXPLORER}/tx/${sent.hash}`],
+    });
+  }),
+);
+
+/** The hooks a coin runs, by name, from a /api/launches pool. */
+function hookNames(p) {
+  const on = Object.entries(p.hooks ?? {})
+    .filter(([name, v]) => v === true && name !== "customHook")
+    .map(([name]) => name);
+  if (p.bossRaid) on.push("bossRaid");
+  if (p.gatedBuy) on.push("gatedBuy");
+  return on;
+}
+
+/** One coin of /api/launches for an agent. */
+function coinRow(p, now) {
+  const priceUsd = p.priceEth > 0 && p.quoteUsd > 0 ? p.priceEth * p.quoteUsd : null;
+  const gated = p.gatedBuy && p.gatedBuyEndsAt > now;
+  const pair = p.markets?.length > 1 ? p.markets.map((m) => m.quoteAsset ?? "?").join(" + ") : (p.quoteAsset ?? "ETH");
+  const round = (n) => (Number.isFinite(n) ? Math.round(n * 100) / 100 : null);
+  return {
+    token: p.contractAddress ?? p.id,
+    name: p.name,
+    ticker: p.ticker,
+    pair,
+    marketCapUsd: round(p.marketCap),
+    ...(priceUsd !== null ? { priceUsd: Number(priceUsd.toPrecision(6)) } : {}),
+    volume24hUsd: round(p.volume24h ?? 0),
+    change24hPct: round(p.change24h ?? 0),
+    launched: p.launchedAt ? new Date(p.launchedAt * 1000).toISOString() : null,
+    hooks: hookNames(p),
+    ...(p.launchedByAgent ? { launchedByAgent: true } : {}),
+    ...(gated ? { gate: `${p.gatedBuyAgentsOnly ? "AI agents only" : "gated"} until ${new Date(p.gatedBuyEndsAt * 1000).toISOString()}` } : {}),
+  };
+}
+
+server.registerTool(
+  "list_coins",
+  {
+    description:
+      "Lists hookit.fun coins the trading tools can trade (Master rail), with market cap, price, 24h volume and change, pair, hooks and launch gate. Sort by newest, market cap, volume or 24h gainers; filter AI-agents-only coins, coins launched by agents, Backed Floor coins (redeem_floor), Boss Raid coins; or search a name or ticker. Needs no key.",
+    inputSchema: {
+      sort: z.enum(["new", "marketcap", "volume", "gainers"]).optional().describe("Default new."),
+      filter: z
+        .enum(["all", "ai_agents_only", "gated", "launched_by_agents", "backed_floor", "boss_raid"])
+        .optional()
+        .describe("ai_agents_only and gated: coins whose launch gate is still closed. Default all."),
+      pair: z.string().optional().describe('Only coins priced in this pair: "eth", "usdg", "wNVDAx"...'),
+      search: z.string().optional().describe("Part of a name or ticker."),
+      limit: z.number().int().min(1).max(50).optional().describe("Default 20."),
+    },
+    annotations: { readOnlyHint: true },
+  },
+  async ({ sort, filter, pair, search, limit }) => {
+    let body;
+    try {
+      body = await launches();
+    } catch (err) {
+      return fail(`hookit.fun's coin list did not answer: ${err.message}`);
+    }
+    const now = Math.floor(Date.now() / 1000);
+    const want = pair?.trim().toLowerCase();
+    const needle = search?.trim().toLowerCase();
+    const pools = body.pools.filter((p) => {
+      if (p.rail === "classic" || p.hookType === "Classic") return false;
+      if (needle && !`${p.name} ${p.ticker}`.toLowerCase().includes(needle)) return false;
+      if (want) {
+        const quotes = [p.quoteAsset, ...(p.markets ?? []).map((m) => m.quoteAsset)].filter(Boolean).map((q) => q.toLowerCase());
+        if (!quotes.includes(want) && !(want === "eth" && quotes.length === 0)) return false;
+      }
+      switch (filter ?? "all") {
+        case "ai_agents_only":
+          return p.gatedBuyAgentsOnly && p.gatedBuyEndsAt > now;
+        case "gated":
+          return p.gatedBuy && p.gatedBuyEndsAt > now;
+        case "launched_by_agents":
+          return !!p.launchedByAgent;
+        case "backed_floor":
+          return !!p.hooks?.backedFloor;
+        case "boss_raid":
+          return !!p.bossRaid;
+        default:
+          return true;
+      }
+    });
+    const by = {
+      new: (p) => p.launchedAt ?? 0,
+      marketcap: (p) => p.marketCap ?? 0,
+      volume: (p) => p.volume24h ?? 0,
+      gainers: (p) => p.change24h ?? 0,
+    }[sort ?? "new"];
+    pools.sort((a, b) => by(b) - by(a));
+    const rows = pools.slice(0, limit ?? 20).map((p) => coinRow(p, now));
+    return reply({ count: pools.length, shown: rows.length, coins: rows, next: "coin_info({ token }) for one coin; buy_token to buy." });
+  },
+);
+
+server.registerTool(
+  "coin_info",
+  {
+    description:
+      "Everything about one hookit.fun coin: market data, what it trades in, its hooks, its Backed Floor (price, reserve) and loans, its launch gate, and this wallet's balance and loans on it. Needs no key (the wallet part needs one).",
+    inputSchema: { token: tokenArg },
+    annotations: { readOnlyHint: true },
+  },
+  async ({ token }) => {
+    if (!isAddress(token)) return fail(`Not an address: ${token}`);
+    token = getAddress(token);
+    const c = await catalog();
+    const [coin, pool] = await Promise.all([
+      loadCoin(c, token),
+      fetch(`${API}/api/launches/${token}`)
+        .then((res) => (res.ok ? res.json() : null))
+        .then((body) => body?.pool ?? null)
+        .catch(() => null),
+    ]);
+    if (!coin && !pool) return fail(NOT_A_COIN);
+    const now = Math.floor(Date.now() / 1000);
+    const info = { token, page: `${API}/token/${token}` };
+    if (pool) {
+      Object.assign(info, coinRow(pool, now), {
+        token,
+        ...(pool.description ? { description: pool.description.slice(0, 500) } : {}),
+        ...(pool.hookTaxBps ? { hookTaxPct: pool.hookTaxBps / 100 } : {}),
+        ...(pool.creator ? { creator: pool.creator } : {}),
+      });
+    }
+    if (!coin) return reply({ ...info, tradable: false, note: "Classic bonding-curve coin: trade it on the site." });
+    info.tradeIn = await tradeAssets(c, coin);
+    info.alsoTradeVia = "buy_token and sell_token also take ETH, USDG, kBTC or a tokenized stock: Relay swaps it into one of tradeIn first (two transactions).";
+    const floor = await floorOf(coin).catch(() => null);
+    info.backedFloor = floor
+      ? { floorPrice: `${floor.price} per ${coin.meta.symbol}`, reserve: amountText(floor.V, floor.quoteMeta), vault: floor.vault, redeem: "redeem_floor" }
+      : null;
+    const plugin = at(c, "loanPlugin");
+    const loans = floor ? await read(plugin, loanAbi, "loansEnabled", [token]).catch(() => false) : false;
+    if (loans) {
+      const cap = await read(plugin, loanAbi, "maxCollateral", [token]).catch(() => null);
+      info.loans = {
+        enabled: true,
+        ...(cap !== null ? { maxCollateralNow: amountText(cap, coin.meta) } : {}),
+        feesPct: Object.fromEntries(Object.entries(LOAN_FEES_BPS).map(([d, bps]) => [`${d}d`, bps / 100])),
+        borrow: "borrow_against_floor",
+      };
+    }
+    if (c.gatedBuyPlugin) {
+      const state = await read(c.gatedBuyPlugin, gatedBuyAbi, "gateState", [token]).catch(() => null);
+      if (state && state[0] !== zeroAddress && !state[3]) {
+        const gate = account ? await gateCheck(c, token, account.address, null, coin.meta).catch(() => null) : null;
+        info.gate = {
+          opensAt: opensAt(state[2]),
+          ...(account ? { thisWalletCanBuy: !gate?.refuse, ...(gate?.refuse ? { why: gate.refuse } : {}) } : {}),
+        };
+      }
+    }
+    if (account) {
+      const balance = await balanceOf(token, account.address).catch(() => 0n);
+      const mine = loans ? (await openLoans(c, account.address)).filter((l) => same(l.loan.token, token)) : [];
+      info.wallet = {
+        balance: amountText(balance, coin.meta),
+        ...(mine.length ? { loans: await Promise.all(mine.map((l) => loanView(c, l))) } : {}),
+      };
+    }
+    return reply(info);
+  },
+);
+
+await server.connect(new StdioServerTransport());