hookit-mcp 0.2.0 → 0.2.2

package/README.md

@@ -30,13 +30,13 @@ Optional env: `HOOKIT_API_URL` (default `https://www.hookit.fun`), `HOOKIT_RPC_U
 | `wallet_status` | The wallet's ETH and USDG, the hookit.fun coins it holds with their value, its open floor loans, and whether it can launch. |
 | `launch_token` | Launches in one call, with an optional `devBuyPct`. `dryRun: true` checks and simulates without signing. |
 | `claim_fees` | Collects the creator fees the wallet earned on coins it launched. |
-| `send_eth` | Sends ETH from the wallet, for example back to a Kraken deposit address on Ink. `dryRun: true` checks only. |
+| `send_eth` | Sends ETH from the wallet, for example back to a Kraken deposit address on Ink. Refuses less than 0.001 ETH, Kraken's minimum deposit (`belowKrakenMinimum: true` for an address that is not Kraken). `dryRun: true` checks only. |
 | `agent_pass_challenge` | Step 1 for AI-agents-only coins: five short tasks for the Hookit Agent Pass check (or "already a holder"). `{ agentId? }` for an ERC-8004 validation (below). |
 | `claim_agent_pass` | Step 2: `{ id, answers, agentId?, requestHash? }` within 30 seconds; signs the answers with the wallet and claims the pass on chain. With `agentId`, gets Hookit's ERC-8004 validation instead (below). |
 | `list_coins` | Coins to trade: newest, top market cap, volume or 24h gainers; filters for AI-agents-only, launched by agents, Backed Floor and Boss Raid coins, a pair, or a name. |
 | `coin_info` | One coin: market data, what it trades in, hooks, Backed Floor price and reserve, loans, launch gate, and the wallet's balance and loans on it. |
-| `buy_token` | Step 3 (or any time): buys a coin, `{ token, amount, payWith?, slippageBps?, dryRun? }`. Pays with ETH, USDG, kBTC, kHYPE or a tokenized stock such as wNVDAx. USDG reaches v2 coins priced in a stock in one transaction (bridged on chain); anything else the coin does not trade in is swapped through Relay first (USDG for a coin priced in ETH, ETH for a coin priced in a stock), then the coin is bought: two transactions. Checks the coin's launch gate first and sends nothing when the wallet is not allowed yet. Always an exact-input buy, the only kind a capped gate window accepts. |
-| `sell_token` | Sells a coin, `{ token, amount, receive?, slippageBps?, dryRun? }`, `amount` in coins, `"max"` or `"50%"`. Receives the coin's pair, USDG through the same on-chain bridges, or anything else through Relay after the sale (two transactions). Says when the Backed Floor pays more. |
+| `buy_token` | Step 3 (or any time): buys a coin, `{ token, amount, payWith?, slippageBps?, dryRun? }`. Pays with ETH, USDG, kBTC or a tokenized stock such as wNVDAx. USDG reaches v2 coins priced in a stock in one transaction (bridged on chain); anything else the coin does not trade in is swapped through Relay first (USDG for a coin priced in ETH, ETH for a coin priced in a stock), then the coin is bought: two transactions. On a coin with several markets the Relay swap lands where the coin is cheapest, and a buy is refused when the market of the asset paid with prices the coin far above its other markets. Checks the coin's launch gate first and sends nothing when the wallet is not allowed yet. Always an exact-input buy, the only kind a capped gate window accepts. |
+| `sell_token` | Sells a coin, `{ token, amount, receive?, slippageBps?, dryRun? }`, `amount` in coins, `"max"` or `"50%"`. Receives the coin's pair, USDG through the same on-chain bridges, or anything else through Relay after the sale (two transactions). A multi-pair coin sells by default in the market that pays the most (most of its markets only pay out what their buyers paid in); when the market of the asset asked for cannot pay, it sells in the best one and swaps through Relay. Says when the Backed Floor pays more. |
 | `redeem_floor` | Burns coins for their Backed Floor value from the floor reserve, `{ token, amount, dryRun? }`: exact payout, no slippage. Compares with selling. |
 | `borrow_against_floor` | Locks coins and borrows their floor value, `{ token, amount, days?, dryRun? }` (7, 14, 30, 60 or 90 days, fee 1% to 7% upfront). v2 coins launched with loans. |
 | `repay_loan` | Repays a floor loan before expiry and gets the coins back, `{ loanId?, dryRun? }`. |
@@ -47,7 +47,7 @@ Paying or receiving a token approves exactly that amount to the contract that tr
 
 `coin_info` lists what a coin trades in (`tradeIn`). When `payWith` or `receive` is not one of them, the server swaps through [Relay](https://relay.link) on Ink, the same route hookit.fun's own swap box uses: it asks `https://www.hookit.fun/api/relay/quote` for the swap (Relay's API key stays on that server), then signs Relay's transactions itself. A buy swaps first and buys with what Relay returned; a sale sells for the coin's pair first, then swaps the proceeds. `dryRun` shows both legs.
 
-Before signing, Relay's transactions are checked twice. First their shape: Ink only, calls only to Relay's Ink contracts (router, approval proxy, receiver, multicaller, depository), an approval only of Relay's approval proxy (replaced by an exact approval of the amount), and no more ETH than the amount. Then their effect: the approval and every call run together in one `eth_simulateV1` from the wallet, and the swap is refused unless the wallet would give at most the amount, get at least Relay's own minimum, and lose nothing else. Anything else is refused and nothing is sent. No allowance to Relay is left behind, even when a swap fails. One Relay swap converts at most the per-buy cap (`HOOKIT_MAX_BUY_ETH` / `HOOKIT_MAX_BUY_USD`), with at most 3% slippage. Relay swaps ETH or USDG with each other, kBTC, kHYPE and the tokenized stocks. The RPC in `HOOKIT_RPC_URL` must support `eth_simulateV1` (Ink's public RPC does).
+Before signing, Relay's transactions are checked twice. First their shape: Ink only, calls only to Relay's Ink contracts (router, approval proxy, receiver, multicaller, depository), an approval only of Relay's approval proxy (replaced by an exact approval of the amount), and no more ETH than the amount. Then their effect: the approval and every call run together in one `eth_simulateV1` from the wallet, and the swap is refused unless the wallet would give at most the amount, get at least Relay's own minimum, and lose nothing else. Anything else is refused and nothing is sent. No allowance to Relay is left behind, even when a swap fails. One Relay swap converts at most the per-buy cap (`HOOKIT_MAX_BUY_ETH` / `HOOKIT_MAX_BUY_USD`), with at most 3% slippage. Relay swaps ETH or USDG with each other, kBTC and the tokenized stocks. The RPC in `HOOKIT_RPC_URL` must support `eth_simulateV1` (Ink's public RPC does).
 
 When the first leg went through and the second did not, the reply is `partial: true` with what the wallet now holds: do not retry the call, or the first leg runs twice.
 

package/index.js

@@ -1,6 +1,6 @@
 #!/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, kHYPE or tokenized stocks (swapped through Relay when the coin trades in something else;
+// 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.
@@ -34,7 +34,7 @@ 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.0";
+const VERSION = "0.2.2";
 const EXPLORER = "https://explorer.inkonchain.com";
 /**
  * The Ink deployments this server signs against. Pinned here, never taken from hookit.fun's catalog: a compromised
@@ -65,8 +65,11 @@ 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",
@@ -92,6 +95,8 @@ 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 };
+/** Kraken's minimum ETH deposit on Ink: smaller deposits are marked failed and lost. */
+const KRAKEN_MIN_DEPOSIT_WEI = parseEther("0.001");
 
 const ink = defineChain({
   id: 57073,
@@ -139,7 +144,11 @@ const swapRouterAbi = parseAbi([
 /** 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; }",
@@ -707,13 +716,61 @@ async function launches() {
   return body;
 }
 
-/** The USD price of one unit of `asset` (a stock or kBTC), from a hookit.fun coin priced in it; null if unknown. */
+/**
+ * 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);
-  return pool ? pool.quoteUsd : null;
+  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). */
@@ -791,10 +848,97 @@ async function planTrade(c, coin, isBuy, asset, amountIn) {
     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") {
@@ -1384,7 +1528,7 @@ server.registerTool(
 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.",
+    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 },
   },
@@ -1577,14 +1721,18 @@ 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.",
+      "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 it refuses to send less unless belowKrakenMinimum is set for an address that is not Kraken. 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.'),
+      amountEth: z.string().describe('Amount in ETH, or "max" to send everything except gas. At least 0.001 ETH.'),
+      belowKrakenMinimum: z
+        .boolean()
+        .optional()
+        .describe("Allows less than 0.001 ETH. Only for an address that is not a Kraken deposit address: Kraken loses smaller deposits."),
       dryRun: z.boolean().optional().describe("Check only. Signs nothing."),
     },
   },
-  serialized(async ({ to, amountEth, dryRun }) => {
+  serialized(async ({ to, amountEth, belowKrakenMinimum, 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()]);
@@ -1601,6 +1749,11 @@ server.registerTool(
       }
     }
     if (value <= 0n) return fail(`Nothing to send: the wallet holds ${formatEther(balance)} ETH.`);
+    if (value < KRAKEN_MIN_DEPOSIT_WEI && !belowKrakenMinimum) {
+      return fail(
+        `${formatEther(value)} ETH is under Kraken's 0.001 ETH minimum deposit on Ink: Kraken marks smaller deposits as failed and the ETH is lost. Nothing was sent. Wait until the wallet holds more, or, only if ${to} is not a Kraken deposit address, pass belowKrakenMinimum: true.`,
+      );
+    }
     if (value + gasReserve > balance) {
       return fail(`Not enough ETH: the wallet holds ${formatEther(balance)} ETH and needs some left for gas.`);
     }
@@ -1745,7 +1898,10 @@ server.registerTool(
   }),
 );
 
-/** The asset a coin trades against by default: its only market's quote, USDG for a multi-pair coin. */
+/**
+ * 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");
 }
@@ -1770,7 +1926,7 @@ 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, kHYPE 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. 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.",
+      "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
@@ -1821,7 +1977,10 @@ server.registerTool(
     let relay = null;
     if (!(await directAssets(c, coin)).some((a) => same(a.address, asset))) {
       let firstError = null;
-      for (const landing of (await landingAssets(c, coin, asset)).slice(0, 3)) {
+      // 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) {
@@ -1845,7 +2004,7 @@ server.registerTool(
         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 did not answer). Nothing was sent; retry later.`);
+        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.`);
@@ -1858,6 +2017,15 @@ server.registerTool(
     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 = {
@@ -1945,11 +2113,11 @@ 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; USDG for a multi-pair coin); 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…), it sells for the coin's pair, 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.",
+      "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.'),
+      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,
     },
@@ -1965,7 +2133,7 @@ server.registerTool(
     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(", ")}.`);
     }
-    const out = await assetMeta(asset);
+    let out = await assetMeta(asset);
     const [balance, ethBalance, reserve] = await Promise.all([
       balanceOf(token, account.address),
       publicClient.getBalance({ address: account.address }),
@@ -1983,30 +2151,52 @@ server.registerTool(
     let leg = out;
     let route = null;
     let relay = null;
-    if ((await directAssets(c, coin)).some((a) => same(a.address, asset))) {
+    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) return fail(planned.error);
-      route = planned.route;
-    } else {
-      let firstError = null;
-      for (const landing of (await landingAssets(c, coin, asset)).slice(0, 3)) {
-        const planned = await planTrade(c, coin, false, landing.address, value);
-        if (planned.error) {
-          firstError ??= planned.error;
-          continue;
-        }
-        const q = await relayQuote(landing.address, asset, planned.route.out, relayBps);
+      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 = landing;
-          route = planned.route;
+          leg = r.asset;
+          route = r.route;
           relay = q.quote;
           break;
         }
-        if (!q.unsupported || !firstError) firstError = q.error;
+        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);
-        return fail(`${firstError ?? "Relay cannot swap what this coin trades in."} This coin trades in ${assets.join(", ")}: receive ${assets.length > 1 ? "one of those" : "that"} instead.`);
+        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.`);
@@ -2024,6 +2214,7 @@ server.registerTool(
       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.` }
@@ -2066,6 +2257,7 @@ server.registerTool(
         received: proceeds !== null ? amountText(proceeds, out) : `about ${amountText(sent.result ?? route.out, out)}`,
         minimum: quote.minimum,
         route: quote.route,
+        ...(picked ? { market: picked } : {}),
         tx: links(),
       });
     }
@@ -2471,7 +2663,7 @@ server.registerTool(
     }
     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, kHYPE or a tokenized stock: Relay swaps it into one of tradeIn first (two transactions).";
+    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" }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hookit-mcp",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Let an AI agent launch a coin on hookit.fun (Ink) with its own hook modules, find, buy and sell coins with ETH, USDG or tokenized stocks (AI-agents-only ones too, with a Hookit Agent Pass), redeem or borrow at their Backed Floor, and collect its creator fees.",
   "type": "module",
   "bin": { "hookit-mcp": "index.js" },