pearpad-mcp 1.0.0

package/.env.example

@@ -0,0 +1,8 @@
+# Copy to .env (or set these in your MCP client config). Only PEARPAD_PRIVATE_KEY is required.
+
+# The wallet the agent trades with. Fund it with USDT0 on Stable (chain 988). NEVER commit this.
+PEARPAD_PRIVATE_KEY=0xyourprivatekey
+
+# Optional — defaults to the public endpoints.
+# PEARPAD_RPC_URL=https://rpc.stable.xyz
+# PEARPAD_API=https://pearpad.fun/api

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pearpad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+<p align="center">
+  <img src="https://pearpad.fun/assets/pearpad-mcp.png" alt="pearpad" width="140" height="140">
+</p>
+
+<h1 align="center">pearpad-mcp</h1>
+
+<p align="center"><strong>Give your agent a wallet and let it trade <a href="https://pearpad.fun">pearpad.fun</a>.</strong></p>
+
+<p align="center">
+  <img src="https://img.shields.io/npm/v/pearpad-mcp" alt="npm">
+  <img src="https://img.shields.io/node/v/pearpad-mcp" alt="node">
+  <img src="https://img.shields.io/npm/l/pearpad-mcp" alt="license">
+</p>
+
+An [MCP](https://modelcontextprotocol.io) server that hands any AI agent a set of tools for pearpad tokens on Stable Mainnet: find them, quote them, buy, sell, launch new ones, and claim your creator earnings. You point it at a wallet you control and talk to your agent in plain language. It figures out whether a token still trades on its bonding curve or has graduated to a pool, and routes the trade the right way. You never touch a contract address.
+
+## Tools
+
+| Tool | What your agent does |
+|---|---|
+| `list_tokens` | Browse tokens newest-first, or search by name or symbol |
+| `get_token` | Read one token's stats and phase; pull its trades, holders, or candles |
+| `quote` | See the result of a buy or sell before spending anything |
+| `buy` | Spend USDT0, receive tokens, with a slippage floor you set |
+| `sell` | Sell tokens for USDT0 by amount or by percent of what you hold |
+| `launch` | Deploy a new token with a name, symbol, image, and an optional first buy |
+| `collect_fees` | Claim the creator earnings owed to your wallet |
+| `wallet` | Check your address, USDT0 balance, and token holdings |
+
+Every buy and sell quotes first and rejects a fill worse than your slippage limit. The default limit is 5%. Override it per call.
+
+## Install
+
+You need Node.js 20 or newer and a wallet funded with **USDT0 on Stable** (chain 988). On Stable, USDT0 is both the gas token and the trading currency, so one balance covers both.
+
+**Claude Desktop.** Add this to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "pearpad": {
+      "command": "npx",
+      "args": ["-y", "pearpad-mcp"],
+      "env": { "PEARPAD_PRIVATE_KEY": "0xyourkey" }
+    }
+  }
+}
+```
+
+**Claude Code:**
+
+```bash
+claude mcp add pearpad -e PEARPAD_PRIVATE_KEY=0xyourkey -- npx -y pearpad-mcp
+```
+
+Any MCP client works. Run the server with `npx pearpad-mcp` and set `PEARPAD_PRIVATE_KEY` in its environment.
+
+## Talk to it
+
+Once it's connected, ask your agent:
+
+> "What are the newest pearpad tokens?"
+
+> "Quote buying 50 USDT0 of PEAR, then do it if I get at least 90% of the quote."
+
+> "Sell all my BOLT."
+
+> "Launch a token called Pear Bot, symbol PBOT, with this image, and buy 10 USDT0 of it myself."
+
+> "How much have I earned as a creator, and claim it."
+
+## What it looks like
+
+Tools return a formatted printout, so terminal clients show something readable instead of raw JSON:
+
+```
+🍐  PEAR  ·  Pear Coin
+0x1234abcd…5678   [CURVE]
+──────────────────────────────────────────────
+price     0.000003173 USDT0
+volume    24.24 USDT0
+trades    10
+holders   3
+reserves  19.15 USDT0  /  793,917,130 PEAR
+
+price
+ 0.000003180 │  ▄
+             │  █
+             │  ██▄
+             │ █████████
+ 0.000003171 │▄█████████
+             └──────────
+
+top holders
+  CURVE   99.39%   0x1111…1111
+  DEV      0.58%   0x2222…2222
+```
+
+## Config
+
+| Variable | Required | Default |
+|---|---|---|
+| `PEARPAD_PRIVATE_KEY` | Yes, for any transaction | none |
+| `PEARPAD_RPC_URL` | No | `https://rpc.stable.xyz` |
+| `PEARPAD_API` | No | `https://pearpad.fun/api` |
+
+The read-only tools (`list_tokens`, `get_token`, `quote`) run without a key.
+
+## Creator earnings
+
+Launch a token and you earn a fee on every trade against it. Your earnings accrue to your wallet on-chain. Ask your agent to run `collect_fees` and it claims whatever you're owed in one transaction.
+
+## Safety
+
+- **Your key stays on your machine.** The server reads it from the environment, signs locally, and never sends it anywhere or writes it to a log.
+- **Slippage is always enforced.** A buy or sell that would fill past your limit reverts instead of costing you.
+- **Fund the wallet with what you're willing to trade.** The agent spends real USDT0 from it.
+
+## How it works
+
+Token lists, stats, and charts come from the public pearpad data API. Trades and launches go straight to the pearpad contracts through your own RPC, so nothing sits between your agent and the chain. For each token the server reads its curve state and picks the venue: the bonding curve before graduation, the pearpad router after.
+
+## Develop
+
+```bash
+git clone https://github.com/pearpad/pearpad-mcp
+cd pearpad-mcp
+npm install
+npm test    # read-only self-check: quotes a live token, spends nothing, needs no key
+```
+
+## License
+
+MIT

package/abi.js

@@ -0,0 +1,27 @@
+// Minimal human-readable ABI fragments — only what the tools call. Full ABIs live in the pearpad
+// repo (pearpad-integration.md); we don't need events or admin fns here.
+
+export const FACTORY_ABI = [
+  'function launchFee() view returns (uint256)',
+  'function launch(string name, string symbol, string metadata, uint256 maxFee) payable returns (address)',
+  'function curves(address) view returns (uint256 ethReserve, uint256 tokenReserve, address creator, bool migrated)',
+  'function getTokensOut(address token, uint256 ethIn) view returns (uint256)',
+  'function getEthOut(address token, uint256 tokensIn) view returns (uint256)',
+  'function buy(address token, uint256 minTokensOut) payable returns (uint256)',
+  'function sell(address token, uint256 tokensIn, uint256 minEthOut) returns (uint256)',
+  'function feesOwed(address) view returns (uint256)',
+  'function claimFees()',
+  'event Launched(address indexed token, address indexed creator, string metadata)',
+]
+
+export const ROUTER_ABI = [
+  'function buy(address token, uint256 amountOutMin) payable returns (uint256)',
+  'function sell(address token, uint256 amountIn, uint256 amountOutMin) returns (uint256)',
+]
+
+export const ERC20_ABI = [
+  'function balanceOf(address) view returns (uint256)',
+  'function approve(address,uint256) returns (bool)',
+  'function allowance(address,address) view returns (uint256)',
+  'function symbol() view returns (string)',
+]

package/fmt.js

@@ -0,0 +1,117 @@
+// fmt.js — turns tool data into a cute monospace printout for terminal MCP clients. No deps; just
+// block-drawing chars. Everything an agent needs (full addresses, tx hashes) stays in the text.
+
+const BLOCKS = '▁▂▃▄▅▆▇█'
+
+const price = (n) => {
+  n = Number(n)
+  if (!Number.isFinite(n) || n === 0) return '0'
+  return n >= 1 ? n.toFixed(4) : n.toPrecision(4)
+}
+const num = (n) => {
+  n = Number(n)
+  return Number.isFinite(n) ? n.toLocaleString('en-US', { maximumFractionDigits: 0 }) : '?'
+}
+const money = (n) => {
+  n = Number(n)
+  return Number.isFinite(n) ? n.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 }) : '?'
+}
+const time = (t) => new Date(Number(t) * 1000).toISOString().slice(5, 16).replace('T', ' ')
+export const wei = (w) => Number(w) / 1e18
+
+// inline one-line sparkline
+function sparkline(series) {
+  const v = (series || []).map(Number).filter(Number.isFinite)
+  if (v.length < 2) return ''
+  const min = Math.min(...v), max = Math.max(...v), span = max - min || 1
+  return v.map((n) => BLOCKS[Math.min(7, Math.floor(((n - min) / span) * 8))]).join('')
+}
+
+// small area chart with a price axis
+function chart(series, { h = 7, w = 44 } = {}) {
+  let v = (series || []).map(Number).filter(Number.isFinite)
+  if (v.length < 2) return '  (not enough price data yet)'
+  if (v.length > w) { const s = v.length / w; v = Array.from({ length: w }, (_, i) => v[Math.floor(i * s)]) }
+  const min = Math.min(...v), max = Math.max(...v), span = max - min || Math.abs(max) || 1
+  const rows = []
+  for (let r = h - 1; r >= 0; r--) {
+    let line = ''
+    for (const n of v) {
+      const level = ((n - min) / span) * (h - 1)
+      line += level >= r + 0.5 ? '█' : level >= r ? '▄' : r === 0 ? '·' : ' '
+    }
+    const lbl = r === h - 1 ? price(max) : r === 0 ? price(min) : ''
+    rows.push(lbl.padStart(12) + ' │' + line)
+  }
+  rows.push(' '.repeat(12) + ' └' + '─'.repeat(v.length))
+  return rows.join('\n')
+}
+
+export function tokenList(tokens) {
+  if (!tokens.length) return 'No tokens found.'
+  const out = ['🍐  PEARPAD TOKENS', '']
+  tokens.forEach((t, i) => {
+    out.push(`${String(i + 1).padStart(2)}. ${t.symbol}  ·  ${t.name}   [${t.phase}]`)
+    out.push(`    ${t.address}`)
+    out.push(`    price ${price(t.price)}  ·  vol ${money(wei(t.volume))}  ·  ${num(t.holders)} holders   ${sparkline(t.spark)}`)
+    out.push('')
+  })
+  return out.join('\n')
+}
+
+export function tokenCard(t) {
+  const bar = '─'.repeat(46)
+  const out = [
+    `🍐  ${t.symbol}  ·  ${t.name}`,
+    `${t.address}   [${t.phase.toUpperCase()}]`,
+    bar,
+    `price     ${price(t.price)} USDT0`,
+    `volume    ${money(wei(t.volume))} USDT0`,
+    `trades    ${num(t.trades)}`,
+    `holders   ${num(t.holders)}`,
+    `reserves  ${money(t.reserves.usdt0)} USDT0  /  ${num(t.reserves.tokens)} ${t.symbol}`,
+    '',
+    'price',
+    chart(t.spark),
+  ]
+  if (t.topHolders?.length) {
+    out.push('', 'top holders')
+    for (const h of t.topHolders) out.push(`  ${(h.tag || '').padEnd(6)} ${h.pct.toFixed(2).padStart(6)}%   ${h.address}`)
+  }
+  if (t.recentTrades?.length) {
+    out.push('', 'recent trades')
+    for (const x of t.recentTrades) {
+      out.push(`  ${time(x.time)}  ${x.side.toUpperCase().padEnd(4)}  ${num(wei(x.amount_token)).padStart(14)} ${t.symbol}  ${wei(x.amount_eth).toFixed(2).padStart(9)} USDT0`)
+    }
+  }
+  return out.join('\n')
+}
+
+export function wallet(w) {
+  const out = [`🍐  WALLET  ${w.address}`, `balance   ${w.usdt0} USDT0`, '']
+  if (!w.holdings.length) { out.push('holdings  (none yet)'); return out.join('\n') }
+  out.push('holdings')
+  for (const h of w.holdings) out.push(`  ${h.symbol.padEnd(10)} ${num(h.balance).padStart(16)}   ${h.address}`)
+  return out.join('\n')
+}
+
+export function quote(q) {
+  if (q.side === 'buy') return `Quote · BUY  [${q.migrated ? 'pool' : 'curve'}]\n  spend ${q.spendUsdt0} USDT0  →  ~${num(q.tokensOut)} tokens`
+  if (q.usdt0Out == null) return `Quote · SELL  [pool]\n  ${q.note}`
+  return `Quote · SELL  [${q.migrated ? 'pool' : 'curve'}]\n  sell ${num(q.sellTokens)} tokens  →  ~${q.usdt0Out} USDT0`
+}
+
+export function bought(r) {
+  return `✓  BOUGHT ~${num(r.expectedTokens)} tokens  (min ${num(r.minTokens)}, ${r.migrated ? 'pool' : 'curve'})\n   tx ${r.txHash}`
+}
+export function sold(r) {
+  return `✓  SOLD ${num(r.soldTokens)} tokens  →  ~${r.expectedUsdt0} USDT0  (min ${r.minUsdt0}, ${r.migrated ? 'pool' : 'curve'})\n   tx ${r.txHash}`
+}
+export function launched(r) {
+  return `🍐  LAUNCHED\n   token   ${r.token}\n   dev buy ${r.devBuy} USDT0  (launch fee ${r.launchFee})\n   tx      ${r.txHash}`
+}
+export function fees(r) {
+  return r.claimed
+    ? `✓  CLAIMED ${r.owed} USDT0 creator earnings\n   tx ${r.txHash}`
+    : `No creator earnings owed yet.`
+}

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "pearpad-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for trading, deploying, and managing pearpad.fun tokens on Stable (chain 988) from any agent.",
+  "type": "module",
+  "bin": { "pearpad-mcp": "server.js" },
+  "files": ["server.js", "pearpad.js", "fmt.js", "abi.js", "README.md", ".env.example"],
+  "scripts": { "start": "node server.js", "test": "node test.js" },
+  "keywords": ["mcp", "pearpad", "stable", "defi", "bonding-curve", "agent"],
+  "license": "MIT",
+  "engines": { "node": ">=20" },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "ethers": "^6.13.0",
+    "zod": "^3.23.0"
+  }
+}

package/pearpad.js

@@ -0,0 +1,231 @@
+// pearpad.js — all chain + data-API logic for the MCP server. Pure of MCP wiring so test.js can
+// import and exercise the read paths without a wallet. Patterns (fee math, phase routing, legacy
+// gas) lifted from the live pearpad volume bots.
+import { ethers } from 'ethers'
+import fs from 'node:fs'
+import { FACTORY_ABI, ROUTER_ABI, ERC20_ABI } from './abi.js'
+
+export const FACTORY = '0xF2fe7D1eC701f69aEc294CA625d8520D4C2340c4'
+export const ROUTER = '0xf403be0A82d6400E5cb018A89FDeC6201AF02d98'
+export const API = process.env.PEARPAD_API || 'https://pearpad.fun/api'
+const IPFS_API = `${API}/ipfs`
+const RPC = process.env.PEARPAD_RPC_URL || 'https://rpc.stable.xyz'
+const ZERO = '0x0000000000000000000000000000000000000000'
+
+export const provider = new ethers.JsonRpcProvider(RPC, 988, { staticNetwork: true })
+const factory = new ethers.Contract(FACTORY, FACTORY_ABI, provider)
+
+// Wallet built lazily — read-only tools and the self-test never need a key.
+let _signer
+export function getSigner() {
+  if (_signer) return _signer
+  const key = process.env.PEARPAD_PRIVATE_KEY
+  if (!key) throw new Error('PEARPAD_PRIVATE_KEY not set — required for buy/sell/launch/collect_fees/wallet')
+  _signer = new ethers.Wallet(key.startsWith('0x') ? key : '0x' + key, provider)
+  return _signer
+}
+
+// Stable pays NO priority tip — a tip is lost funds. Every send is legacy (type-0) with explicit
+// gasPrice. gasPrice is re-read per call (cheap, keeps up with the chain).
+async function txOpts(extra = {}) {
+  const gasPrice = (await provider.getFeeData()).gasPrice
+  return { type: 0, gasPrice, ...extra }
+}
+
+export const parseUSDT0 = (s) => ethers.parseEther(String(s)) // 18-dec native
+export const fmtUSDT0 = (w) => ethers.formatEther(w)
+export const parseTokens = (s) => ethers.parseUnits(String(s), 18)
+export const fmtTokens = (w) => ethers.formatUnits(w, 18)
+
+// Sent on every pearpad API call so usage is greppable in nginx logs — free adoption visibility, no keys.
+const UA = 'pearpad-mcp/1.0'
+
+async function api(path) {
+  const res = await fetch(`${API}${path}`, { headers: { 'user-agent': UA } })
+  if (!res.ok) throw new Error(`GET ${path} -> ${res.status}`)
+  return res.json()
+}
+
+// ---- data (indexer) ----
+export async function listTokens({ search, sort = 'newest', limit = 20 } = {}) {
+  let { tokens } = await api('/tokens')
+  if (search) {
+    const q = search.toLowerCase()
+    tokens = tokens.filter((t) => `${t.name} ${t.symbol}`.toLowerCase().includes(q))
+  }
+  tokens.sort((a, b) => (sort === 'oldest' ? a.deploy_block - b.deploy_block : b.deploy_block - a.deploy_block))
+  return tokens.slice(0, limit).map((t) => ({
+    address: t.address, name: t.name, symbol: t.symbol,
+    migrated: t.migrated_block != null, phase: t.migrated_block != null ? 'migrated' : 'curve',
+    price: t.last_price_eth, volume: t.volume_eth, trades: t.trade_count,
+    holders: t.holders_count, creator: t.creator, spark: t.spark || [],
+  }))
+}
+
+const tagOf = (addr, t) => {
+  const a = String(addr).toLowerCase()
+  if (a === FACTORY.toLowerCase()) return 'CURVE'
+  if (t.pool && a === String(t.pool).toLowerCase()) return 'POOL'
+  if (t.creator && a === String(t.creator).toLowerCase()) return 'DEV'
+  return ''
+}
+
+export async function getToken(address, include = []) {
+  const { token: t } = await api(`/tokens/${address}`)
+  const ph = await phaseOf(address)
+  const out = {
+    address: t.address, symbol: t.symbol, name: t.name,
+    phase: ph.migrated ? 'migrated' : 'curve', reserves: ph.reserves,
+    price: t.last_price_eth, volume: t.volume_eth, trades: t.trade_count,
+    holders: t.holders_count, creator: t.creator, pool: t.pool, spark: t.spark || [],
+  }
+  if (include.includes('holders')) {
+    const hs = (await api(`/tokens/${address}/holders?limit=20`)).holders
+    out.topHolders = hs.map((h) => ({ address: h.address, pct: (Number(h.balance) / 1e18 / 1e9) * 100, tag: tagOf(h.address, t) }))
+  }
+  if (include.includes('trades')) out.recentTrades = (await api(`/tokens/${address}/trades?limit=10`)).trades
+  if (include.includes('candles')) out.candles = (await api(`/tokens/${address}/bars?res=3600`)).bars
+  return out
+}
+
+// ---- phase ----
+export async function phaseOf(token) {
+  const c = await factory.curves(token)
+  if (c.creator === ZERO) throw new Error(`${token} is not a pearpad token`)
+  return {
+    creator: c.creator, migrated: c.migrated,
+    reserves: { usdt0: fmtUSDT0(c.ethReserve), tokens: fmtTokens(c.tokenReserve) },
+  }
+}
+
+// ---- quotes ----
+// Buy: how many tokens `valueWei` USDT0 buys. Curve strips the 1.3% fee before quoting; router is
+// simulated (its 1% fee is applied internally, so simulate on the full value).
+export async function quoteBuy(token, valueWei) {
+  const { migrated } = await phaseOf(token)
+  if (!migrated) {
+    const ethIn = (valueWei * 10000n) / 10130n
+    return { migrated, tokensOut: await factory.getTokensOut(token, ethIn) }
+  }
+  const router = new ethers.Contract(ROUTER, ROUTER_ABI, provider)
+  const from = _signer?.address
+  const tokensOut = await router.buy.staticCall(token, 0n, { value: valueWei, from })
+  return { migrated, tokensOut }
+}
+
+// Sell: how much USDT0 `amountWei` tokens returns. Curve is a pure view. Router has no on-chain
+// quoter — it must be simulated, which needs an allowance (transferFrom runs inside). If the token
+// isn't approved yet we can't simulate; the sell tool approves first, so it always gets an exact
+// quote. Here we flag it instead of guessing.
+export async function quoteSell(token, amountWei) {
+  const { migrated } = await phaseOf(token)
+  if (!migrated) {
+    const gross = await factory.getEthOut(token, amountWei)
+    return { migrated, usdt0Out: gross - (gross * 130n) / 10000n }
+  }
+  const from = _signer?.address
+  if (from) {
+    const t = new ethers.Contract(token, ERC20_ABI, provider)
+    if ((await t.allowance(from, ROUTER)) >= amountWei) {
+      const router = new ethers.Contract(ROUTER, ROUTER_ABI, provider)
+      return { migrated, usdt0Out: await router.sell.staticCall(token, amountWei, 0n, { from }) }
+    }
+  }
+  return { migrated, usdt0Out: null, note: 'migrated sell — exact quote needs a one-time token approval; run `sell` (it approves, quotes, and slippage-guards in one step)' }
+}
+
+const minus = (x, pct) => (x * BigInt(Math.round((100 - pct) * 100))) / 10000n
+
+// ---- trades ----
+export async function buy(token, valueWei, slippagePct = 5) {
+  const w = getSigner()
+  const { migrated, tokensOut } = await quoteBuy(token, valueWei)
+  const minOut = minus(tokensOut, slippagePct)
+  const venue = migrated ? new ethers.Contract(ROUTER, ROUTER_ABI, w) : factory.connect(w)
+  // NO gasLimit on a curve buy: the buy that crosses TARGET triggers migration (~4M gas). Let ethers
+  // estimate so a near-graduation buy can't revert on a too-tight limit.
+  const rc = await (await venue.buy(token, minOut, await txOpts({ value: valueWei }))).wait()
+  return { txHash: rc.hash, expectedTokens: fmtTokens(tokensOut), minTokens: fmtTokens(minOut), migrated }
+}
+
+// amount = decimal token string, OR percent (0-100) of the wallet's balance.
+export async function sell(token, { amount, percent } = {}, slippagePct = 5) {
+  const w = getSigner()
+  const { migrated } = await phaseOf(token)
+  const t = new ethers.Contract(token, ERC20_ABI, w)
+  let amountWei
+  if (percent != null) {
+    const bal = await t.balanceOf(w.address)
+    amountWei = (bal * BigInt(Math.round(percent * 100))) / 10000n
+  } else if (amount != null) {
+    amountWei = parseTokens(amount)
+  } else throw new Error('sell needs `amount` (tokens) or `percent` (0-100)')
+  if (amountWei === 0n) throw new Error('nothing to sell')
+
+  const venue = migrated ? ROUTER : FACTORY
+  if ((await t.allowance(w.address, venue)) < amountWei) {
+    await (await t.approve(venue, ethers.MaxUint256, await txOpts({ gasLimit: 100000n }))).wait()
+  }
+  const q = await quoteSell(token, amountWei)
+  const minOut = minus(q.usdt0Out, slippagePct)
+  const seller = migrated ? new ethers.Contract(ROUTER, ROUTER_ABI, w) : factory.connect(w)
+  const rc = await (await seller.sell(token, amountWei, minOut, await txOpts({ gasLimit: 500000n }))).wait()
+  return { txHash: rc.hash, soldTokens: fmtTokens(amountWei), expectedUsdt0: fmtUSDT0(q.usdt0Out), minUsdt0: fmtUSDT0(minOut), migrated }
+}
+
+// ---- launch ----
+async function uploadImage(image) {
+  const form = new FormData()
+  const blob = /^https?:\/\//.test(image)
+    ? await (await fetch(image)).blob()
+    : new Blob([fs.readFileSync(image)])
+  form.append('file', blob, 'token.png')
+  const up = await fetch(`${IPFS_API}/launch/upload-image`, { method: 'POST', body: form, headers: { 'user-agent': UA } })
+  if (!up.ok) throw new Error(`image upload ${up.status}`)
+  return (await up.json()).cid
+}
+
+export async function launch({ name, symbol, description = '', image, devBuy = '0' }) {
+  const w = getSigner()
+  let imageCid = ''
+  if (image) imageCid = await uploadImage(image)
+  const prep = await fetch(`${IPFS_API}/launch/prepare`, {
+    method: 'POST', headers: { 'content-type': 'application/json', 'user-agent': UA },
+    body: JSON.stringify({ name, symbol, description: description.slice(0, 280), imageCid }),
+  })
+  if (!prep.ok) throw new Error(`prepare ${prep.status}: ${await prep.text()}`)
+  const { uri } = await prep.json()
+
+  const fee = await factory.launchFee()
+  const value = fee + parseUSDT0(devBuy)
+  const tx = await factory.connect(w).launch(name, symbol, uri, fee, await txOpts({ value, gasLimit: 4000000n }))
+  const rc = await tx.wait()
+  const token = rc.logs
+    .map((l) => { try { return factory.interface.parseLog(l) } catch { return null } })
+    .find((l) => l?.name === 'Launched')?.args?.token
+  if (!token) throw new Error(`no Launched event in tx ${tx.hash} — dev buy may be stranded`)
+  return { token, txHash: tx.hash, metadata: uri, devBuy, launchFee: fmtUSDT0(fee) }
+}
+
+// ---- creator fees ----
+export async function collectFees() {
+  const w = getSigner()
+  const owed = await factory.feesOwed(w.address)
+  if (owed === 0n) return { owed: '0', claimed: false, message: 'no creator earnings owed' }
+  const rc = await (await factory.connect(w).claimFees(await txOpts())).wait()
+  return { owed: fmtUSDT0(owed), claimed: true, txHash: rc.hash }
+}
+
+// ---- wallet ----
+// ponytail: balances via one balanceOf per launched token — fine at dozens of tokens; swap to
+// Multicall3 (0xcA11…CA11 is live on 988) if the token count grows into the hundreds.
+export async function walletInfo() {
+  const w = getSigner()
+  const usdt0 = fmtUSDT0(await provider.getBalance(w.address))
+  const { tokens } = await api('/tokens')
+  const bals = await Promise.all(tokens.map(async (t) => {
+    const bal = await new ethers.Contract(t.address, ERC20_ABI, provider).balanceOf(w.address).catch(() => 0n)
+    return bal > 0n ? { address: t.address, symbol: t.symbol, balance: fmtTokens(bal) } : null
+  }))
+  return { address: w.address, usdt0, holdings: bals.filter(Boolean) }
+}

package/server.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// pearpad-mcp — MCP server exposing pearpad.fun trading to any agent. Wallet key from
+// PEARPAD_PRIVATE_KEY (env). Reads use the public pearpad API; trades go straight on-chain.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { z } from 'zod'
+import * as pp from './pearpad.js'
+import * as fmt from './fmt.js'
+
+const server = new McpServer({ name: 'pearpad-mcp', version: '1.0.0' })
+
+// Wrap a handler so any throw comes back as a clean tool error instead of crashing the process.
+// fn returns a pre-formatted string (the cute printout the client shows).
+const tool = (name, desc, shape, fn) =>
+  server.tool(name, desc, shape, async (args) => {
+    try {
+      return { content: [{ type: 'text', text: await fn(args) }] }
+    } catch (e) {
+      return { content: [{ type: 'text', text: `Error: ${e.shortMessage || e.message}` }], isError: true }
+    }
+  })
+
+const usdt0 = z.string().describe('USDT0 amount as a decimal string, e.g. "50" for 50 USDT0')
+
+tool('list_tokens', 'List pearpad tokens (newest first by default). Optionally search by name/symbol.',
+  { search: z.string().optional(), sort: z.enum(['newest', 'oldest']).optional(), limit: z.number().int().optional() },
+  async (a) => fmt.tokenList(await pp.listTokens(a)))
+
+tool('get_token', 'Get one token: stats, phase (curve vs migrated), reserves, price chart. Add include for trades/holders/candles.',
+  { address: z.string(), include: z.array(z.enum(['trades', 'holders', 'candles'])).optional() },
+  async (a) => fmt.tokenCard(await pp.getToken(a.address, a.include || [])))
+
+tool('quote', 'Preview a trade before doing it. Buy: how many tokens `usdt0` buys. Sell: how much USDT0 `amount` tokens returns. Auto-routes curve vs migrated pool.',
+  { token: z.string(), side: z.enum(['buy', 'sell']), usdt0: usdt0.optional(), amount: z.string().optional().describe('token amount, for sell') },
+  async (a) => {
+    if (a.side === 'buy') {
+      if (!a.usdt0) throw new Error('buy quote needs `usdt0`')
+      const q = await pp.quoteBuy(a.token, pp.parseUSDT0(a.usdt0))
+      return fmt.quote({ side: 'buy', migrated: q.migrated, spendUsdt0: a.usdt0, tokensOut: pp.fmtTokens(q.tokensOut) })
+    }
+    if (!a.amount) throw new Error('sell quote needs `amount`')
+    const q = await pp.quoteSell(a.token, pp.parseTokens(a.amount))
+    return fmt.quote({ side: 'sell', migrated: q.migrated, sellTokens: a.amount, usdt0Out: q.usdt0Out == null ? null : pp.fmtUSDT0(q.usdt0Out), note: q.note })
+  })
+
+tool('buy', 'Buy a token with USDT0 from the configured wallet. Quotes first and enforces slippage. Auto-routes curve vs pool.',
+  { token: z.string(), usdt0, slippage_pct: z.number().optional().describe('default 5') },
+  async (a) => fmt.bought(await pp.buy(a.token, pp.parseUSDT0(a.usdt0), a.slippage_pct ?? 5)))
+
+tool('sell', 'Sell a token back to USDT0. Give `amount` (tokens) OR `percent` (0-100) of holdings. Auto-approves, quotes, slippage-guards, auto-routes.',
+  { token: z.string(), amount: z.string().optional(), percent: z.number().optional(), slippage_pct: z.number().optional() },
+  async (a) => fmt.sold(await pp.sell(a.token, { amount: a.amount, percent: a.percent }, a.slippage_pct ?? 5)))
+
+tool('launch', 'Deploy a new pearpad token. image = URL or local file path (optional). dev_buy = USDT0 to buy of your own token in the same tx (optional).',
+  { name: z.string(), symbol: z.string(), description: z.string().optional(), image: z.string().optional(), dev_buy: usdt0.optional() },
+  async (a) => fmt.launched(await pp.launch({ name: a.name, symbol: a.symbol, description: a.description, image: a.image, devBuy: a.dev_buy || '0' })))
+
+tool('collect_fees', 'Claim creator earnings owed to the configured wallet from tokens it launched.',
+  {}, async () => fmt.fees(await pp.collectFees()))
+
+tool('wallet', 'Show the configured wallet: address, USDT0 balance, and pearpad token holdings.',
+  {}, async () => fmt.wallet(await pp.walletInfo()))
+
+await server.connect(new StdioServerTransport())