Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

74.0 KB
Raw Blame
// /api/pump-fun-mcp — pump.fun MCP server (Streamable HTTP transport, MCP 2025-06-18).
// POST — JSON-RPC (single + batch)   GET/HEAD — SSE handshake   DELETE — terminate.
//
// Real, in-house MCP server exposing read-only pump.fun tools to remote MCP
// connectors, the npm bridge (@three-ws/pumpfun-mcp), and the in-page
// <agent-3d> skill bundle (public/skills/pump-fun/). Registered with the MCP
// Registry as io.github.nirholas/pumpfun-solana-remote (see server-pumpfun.json).
//
// Back-compat: raw JSON-RPC consumers that POST plain application/json with no
// MCP headers (the npm bridge, the skill bundle) keep working unchanged —
// single requests return the same envelopes, statuses, and bodies as before.
//
// Tool names: canonical names are snake_case; the legacy camelCase names
// remain accepted forever via TOOL_NAME_ALIASES (src/pump/mcp-tools.js).
//
// Tools backed by on-chain reads (no external indexer required):
//   - get_bonding_curve   → @pump-fun/pump-sdk fetchBondingCurve
//   - get_token_details   → @solana/web3.js getAccountInfo + Metaplex metadata
//   - get_token_holders   → connection.getTokenLargestAccounts + concentration
//
// Tools that require indexed/aggregate data are routed through the existing
// pumpfunMcp client (api/_lib/pumpfun-mcp.js → upstream pumpfun-claims-bot).
// When PUMPFUN_BOT_URL is unset they return JSON-RPC error -32004 ("indexer
// not configured") — never a fabricated payload.
//
// CORS open (read-only data). Rate-limited by IP via limits.mcpIp.

import { cors, json, method, wrap, readJson, rateLimited } from './_lib/http.js';
import { limits, clientIp } from './_lib/rate-limit.js';
import { extractBearer, authenticateBearer } from './_lib/auth.js';
import { fetchSafePublicUrlPinned, SsrfBlockedError } from './_lib/ssrf-guard.js';
import {
	verifyPayment,
	settlePayment,
	encodePaymentResponseHeader,
	resolveResourceUrl,
	paymentRequirements,
	build402Body,
} from './_lib/x402-spec.js';
import { reservePaymentProof } from './_lib/x402/payment-identifier-server.js';
import { getPumpSdk, getConnection, solanaPubkey, getAmmPoolState } from './_lib/pump.js';
import { solPriceUsd } from './_lib/sol-price.js';
import { pumpfunMcp, pumpfunBotEnabled } from './_lib/pumpfun-mcp.js';
import { getTrendingSlim, getNewSlim } from './_lib/pump-trending.js';
import { TOOLS, resolveToolName, rpcError, rpcEnvelope } from '../src/pump/mcp-tools.js';
import { gateCall, listForRequest } from './_mcp/policy.js';

// The @three-ws/mcp-policy server id for this server. Every tool here is read
// or write tier, so the policy only ever narrows the list to what the caller
// asked for with X-Three-Tools; nothing on this server moves funds.
const POLICY_SERVER = 'threews-pumpfun';
import { generateVanityKey } from '../src/pump/vanity-keygen.js';
import bs58 from 'bs58';
import { resolveSnsName, reverseLookupAddress } from '../src/solana/sns.js';
import { scanFirstClaims } from './_lib/pump-claims.js';
import { eventField } from './_lib/pump-onchain-trades.js';
import { pumpTradesFromEvents } from '../src/pump/trade-events.js';
import { getSolPriceUsd } from '../src/shared/usd-price.js';

import { pinToIPFS, ipfsPinningConfigured } from './_lib/ipfs-pin.js';
import { issueSession, trackMcp } from './_lib/mcp-clients.js';
import { readXPost, summarizeXPost } from './_lib/x-syndication.js';
// ── On-chain handlers ──────────────────────────────────────────────────────

const TOTAL_PUMP_TOKEN_SUPPLY = 1_000_000_000; // 1B pump.fun standard
const GRADUATION_REAL_SOL_LAMPORTS = 85_000_000_000n; // ~85 SOL — heuristic

// Read a bonding curve's quote-side reserve as a string, or null if absent.
//
// Pump renamed these when USDC became a possible quote asset:
// `real_sol_reserves` → `real_quote_reserves`, `virtual_sol_reserves` →
// `virtual_quote_reserves` (same u64s at the same offsets, new names). Current
// SDKs expose only the `*Quote*` names. Reading just the legacy name yields
// `undefined`, which silently coerces to 0 and reports a healthy curve as empty
// rather than failing — so read the current name first and keep the legacy one
// as a fallback for an older decoder.
function curveQuoteReserve(curve, kind /* 'real' | 'virtual' */) {
	const quoteKey = kind === 'real' ? 'realQuoteReserves' : 'virtualQuoteReserves';
	const legacyKey = kind === 'real' ? 'realSolReserves' : 'virtualSolReserves';
	return curve?.[quoteKey]?.toString?.() ?? curve?.[legacyKey]?.toString?.() ?? null;
}

async function handleGetBondingCurve({ mint, network = 'mainnet' }) {
	const pk = solanaPubkey(mint);
	if (!pk) throw rpcError(-32602, 'invalid mint');
	const { sdk } = await getPumpSdk({ network });
	let curve;
	try {
		if (sdk.fetchBuyState) {
			const state = await sdk.fetchBuyState(pk, pk);
			curve = state.bondingCurve;
		} else if (sdk.fetchBondingCurve) {
			curve = await sdk.fetchBondingCurve(pk);
		}
	} catch (e) {
		throw rpcError(-32004, `bonding curve unavailable: ${e?.message || 'unknown'}`);
	}
	if (!curve) throw rpcError(-32004, 'no bonding curve found for this mint');

	const realSol = BigInt(curveQuoteReserve(curve, 'real') ?? '0');
	const realToken = BigInt(curve.realTokenReserves?.toString?.() ?? '0');
	const virtSol = BigInt(curveQuoteReserve(curve, 'virtual') ?? '0');
	const virtToken = BigInt(curve.virtualTokenReserves?.toString?.() ?? '0');
	const complete = !!curve.complete;
	// Graduation % heuristic: complete=100, else realSol/graduationTarget * 100.
	const graduationPercent = complete
		? 100
		: Number((realSol * 10000n) / GRADUATION_REAL_SOL_LAMPORTS) / 100;

	return {
		mint,
		network,
		complete,
		graduationPercent,
		solReserves: (Number(realSol) / 1e9).toFixed(4),
		tokenReserves: realToken.toString(),
		virtualSolReserves: virtSol.toString(),
		virtualTokenReserves: virtToken.toString(),
	};
}

async function handleGetTokenDetails({ mint, network = 'mainnet' }) {
	const pk = solanaPubkey(mint);
	if (!pk) throw rpcError(-32602, 'invalid mint');
	const connection = getConnection({ network });
	const [{ MintLayout, getTokenMetadata, TOKEN_2022_PROGRAM_ID }, { PublicKey }] =
		await Promise.all([import('@solana/spl-token'), import('@solana/web3.js')]);

	const info = await connection.getAccountInfo(pk);
	if (!info) throw rpcError(-32004, 'mint account not found');
	const mintAccount = MintLayout.decode(info.data);

	// Best-effort Metaplex Token Metadata read. PDA = [b"metadata", program, mint].
	const METADATA_PROGRAM = new PublicKey('metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s');
	const [metadataPda] = PublicKey.findProgramAddressSync(
		[Buffer.from('metadata'), METADATA_PROGRAM.toBuffer(), pk.toBuffer()],
		METADATA_PROGRAM,
	);
	// Token-2022 mints (what pump.fun launches today) keep name/symbol/uri in the
	// mint's own TokenMetadata extension and have no Metaplex PDA at all, so the
	// legacy read alone reported every current pump.fun token as unnamed.
	const extensionMetadata = info.owner?.equals?.(TOKEN_2022_PROGRAM_ID)
		? await getTokenMetadata(connection, pk, 'confirmed', TOKEN_2022_PROGRAM_ID).catch(() => null)
		: null;
	let name = extensionMetadata?.name?.trim() || null;
	let symbol = extensionMetadata?.symbol?.trim() || null;
	let uri = extensionMetadata?.uri?.trim() || null;
	try {
		const metaInfo = extensionMetadata ? null : await connection.getAccountInfo(metadataPda);
		if (metaInfo) {
			// Layout: 1 key + 32 updateAuthority + 32 mint + 4-byte string-length-prefixed name/symbol/uri.
			const buf = metaInfo.data;
			let cursor = 1 + 32 + 32;
			const readStr = (max) => {
				const len = Math.min(buf.readUInt32LE(cursor), max);
				cursor += 4;
				const slice = buf.slice(cursor, cursor + len);
				cursor += max; // always step the full fixed-width field
				return slice.toString('utf8').replace(/\0+$/g, '').trim();
			};
			name = readStr(32);
			symbol = readStr(10);
			uri = readStr(200);
		}
	} catch {
		// Metadata is optional — proceed without it.
	}

	const supply = mintAccount.supply.toString();
	const decimals = mintAccount.decimals;

	return {
		mint,
		name,
		symbol,
		uri,
		decimals,
		supply,
		mintAuthority: mintAccount.mintAuthorityOption
			? mintAccount.mintAuthority.toString()
			: null,
		freezeAuthority: mintAccount.freezeAuthorityOption
			? mintAccount.freezeAuthority.toString()
			: null,
	};
}

async function handleGetTokenHolders({ mint, limit = 10, network = 'mainnet' }) {
	const pk = solanaPubkey(mint);
	if (!pk) throw rpcError(-32602, 'invalid mint');
	const connection = getConnection({ network });
	let largest;
	try {
		largest = await connection.getTokenLargestAccounts(pk);
	} catch (e) {
		throw rpcError(-32004, `holders unavailable: ${e?.message || 'rpc error'}`);
	}
	const accounts = (largest?.value || []).slice(0, Math.min(20, Math.max(1, limit)));
	const total = accounts.reduce((sum, a) => sum + Number(a.uiAmount || 0), 0);
	const holders = accounts.map((a) => ({
		address: a.address.toString(),
		amount: a.amount,
		uiAmount: a.uiAmount,
		percent: total > 0 ? (Number(a.uiAmount || 0) / total) * 100 : 0,
	}));
	const topHolderPercent = holders[0]?.percent ?? 0;
	return {
		mint,
		count: holders.length,
		topHolderPercent,
		holders,
	};
}

async function handleKolLeaderboard({ window = '7d', limit = 25 }) {
	const { getLeaderboard } = await import('../src/kol/leaderboard.js');
	return getLeaderboard({ window, limit });
}

// ── SNS handlers ──────────────────────────────────────────────────────────

async function handleSnsResolve({ name }) {
	if (!name) throw rpcError(-32602, 'name is required');
	const address = await resolveSnsName(name);
	if (!address) throw rpcError(-32004, `domain "${name}" not found`);
	return { name, address };
}

async function handleSnsReverseLookup({ address }) {
	if (!address) throw rpcError(-32602, 'address is required');
	const name = await reverseLookupAddress(address);
	if (!name) throw rpcError(-32004, `no .sol domain found for address`);
	return { address, name };
}

// ── Indexer-backed handlers (route through pumpfunMcp) ─────────────────────

// Tools whose data comes exclusively from the external pump.fun indexer
// (PUMPFUN_BOT_URL). When the bot is unconfigured these are filtered out of
// tools/list entirely so MCP clients only ever see tools they can call — they
// reappear automatically once the env var is set, with no code change. The
// -32004 guard in indexerOrUnavailable() stays as defence for any client that
// calls one anyway (e.g. from a cached tool list). get_token_trades is NOT
// here: it has a real on-chain fallback and works without the indexer. Neither
// are get_trending_tokens and get_new_tokens: both fall through to the live
// pump.fun feed (liveFeedOrIndexer below), so the strategy runtime's scans keep
// sourcing real mints on a deployment that never configured the indexer.
const INDEXER_TOOLS = new Set([
	'search_tokens',
	'get_graduated_tokens',
	'get_king_of_the_hill',
	'get_creator_profile',
]);

// Discovery tools with a rung below the indexer. The indexer is preferred when
// configured (richer rows); when it is absent or fails, the shared pump.fun
// feed (api/_lib/pump-trending.js: pump.fun frontend → recorder DB → stale
// cache) answers in the `{ tokens: [...] }` shape every consumer already
// unwraps (`r.tokens ?? r`, then `t.mint`). Only when every rung is down does
// the call surface -32004, the same code the indexer path uses.
function liveFeedOrIndexer(name, feed) {
	const viaIndexer = indexerOrUnavailable(name);
	return async (args = {}) => {
		const limit = Math.min(50, Math.max(1, Math.floor(Number(args.limit) || 10)));
		if (pumpfunBotEnabled()) {
			try {
				return await viaIndexer({ ...args, limit });
			} catch (err) {
				console.warn(`[pump-fun-mcp] ${name}: indexer failed, using live pump.fun feed`, err?.message);
			}
		}
		const { data, stale } = await feed(limit);
		if (!data) {
			throw rpcError(-32004, `tool "${name}": every live pump.fun source is unavailable right now`);
		}
		return { tokens: data, source: 'pump.fun', stale: !!stale };
	};
}

function indexerOrUnavailable(name) {
	return async (args) => {
		if (!pumpfunBotEnabled()) {
			throw rpcError(
				-32004,
				`tool "${name}" requires the pump.fun indexer (PUMPFUN_BOT_URL) to be configured`,
			);
		}
		// Map our canonical tool names to the upstream bot's (camelCase) surface.
		const upstreamMap = {
			search_tokens: { tool: 'searchTokens', args: { query: args.query, limit: args.limit } },
			get_token_trades: {
				tool: 'getTokenTrades',
				args: { mint: args.mint, limit: args.limit },
			},
			get_trending_tokens: { tool: 'getTrendingTokens', args: { limit: args.limit } },
			get_new_tokens: { tool: 'getNewTokens', args: { limit: args.limit } },
			get_graduated_tokens: { tool: 'getGraduatedTokens', args: { limit: args.limit } },
			get_king_of_the_hill: { tool: 'getKingOfTheHill', args: {} },
			get_creator_profile: { tool: 'getCreatorIntel', args: { wallet: args.creator } },
		};
		const upstream = upstreamMap[name];
		if (!upstream) throw rpcError(-32601, `tool "${name}" not implemented`);
		// Use the lower-level rpc-style call via callTool; pumpfunMcp's named
		// methods cover only a subset, so fall back to a generic invocation.
		const r = await pumpfunMcpCall(upstream.tool, upstream.args);
		if (!r.ok) throw rpcError(-32004, r.error || 'indexer error');
		return r.data;
	};
}

// Generic tools/call against the upstream bot using the same transport that
// pumpfunMcp uses internally. Encapsulated here so we don't leak transport
// details into the route.
async function pumpfunMcpCall(tool, args) {
	if (tool === 'getCreatorIntel') return pumpfunMcp.creatorIntel({ wallet: args?.wallet });
	if (tool === 'getRecentClaims') return pumpfunMcp.recentClaims({ limit: args?.limit });
	if (tool === 'getGraduations') return pumpfunMcp.graduations({ limit: args?.limit });
	// Fall through: not in the named surface — call raw rpc.
	return rawBotCall(tool, args);
}

async function rawBotCall(tool, args) {
	const url = process.env.PUMPFUN_BOT_URL;
	if (!url) return { ok: false, error: 'PUMPFUN_BOT_URL not set' };
	const headers = { 'content-type': 'application/json', accept: 'application/json' };
	if (process.env.PUMPFUN_BOT_TOKEN)
		headers.authorization = `Bearer ${process.env.PUMPFUN_BOT_TOKEN}`;
	const ctrl = new AbortController();
	const t = setTimeout(() => ctrl.abort(), 8000);
	try {
		const r = await fetch(url.replace(/\/$/, ''), {
			method: 'POST',
			headers,
			body: JSON.stringify({
				jsonrpc: '2.0',
				id: 1,
				method: 'tools/call',
				params: { name: tool, arguments: args || {} },
			}),
			signal: ctrl.signal,
		});
		if (!r.ok) return { ok: false, error: `bot ${r.status}` };
		const j = await r.json();
		if (j.error) return { ok: false, error: j.error.message || 'rpc error' };
		const payload = j.result?.structuredContent ?? j.result?.content ?? j.result;
		return { ok: true, data: payload };
	} catch (err) {
		return {
			ok: false,
			error: err?.name === 'AbortError' ? 'timeout' : err?.message || 'fetch failed',
		};
	} finally {
		clearTimeout(t);
	}
}

// Hard ceiling on the single-threaded vanity grind. Each iteration is a full
// ed25519 keygen; an unbounded budget lets one authenticated caller pin a CPU
// for the whole serverless window. 1.5M ≈ comfortably inside the 58s abort.
const VANITY_MAX_ATTEMPTS_CEILING = 1_500_000;
// Suffix/prefix length cap — the match space is base58^len, so >4 chars makes a
// hit astronomically unlikely within the budget and just burns CPU.
const VANITY_MAX_PATTERN_LEN = 4;

async function handleVanityMint({
	suffix = '',
	prefix = '',
	caseSensitive = false,
	maxAttempts = 1_500_000,
}) {
	if (!suffix && !prefix) throw rpcError(-32602, 'at least one of suffix or prefix is required');
	if (
		String(suffix).length > VANITY_MAX_PATTERN_LEN ||
		String(prefix).length > VANITY_MAX_PATTERN_LEN
	)
		throw rpcError(-32602, `suffix/prefix must each be ≤ ${VANITY_MAX_PATTERN_LEN} characters`);
	const budget = Math.min(
		VANITY_MAX_ATTEMPTS_CEILING,
		Math.max(1, Number(maxAttempts) || VANITY_MAX_ATTEMPTS_CEILING),
	);
	const ac = new AbortController();
	const timer = setTimeout(() => ac.abort(), 58_000);
	let result;
	try {
		result = await generateVanityKey({
			suffix,
			prefix,
			caseSensitive,
			maxAttempts: budget,
			signal: ac.signal,
		});
	} finally {
		clearTimeout(timer);
	}
	if (!result) throw rpcError(-32003, `no match found in ${budget} attempts`);
	// SECURITY: the secretKey is returned to the (authenticated) caller but must
	// never be logged or recorded server-side. Keep it out of any usage/event
	// metadata — the caller is the sole custodian of this key.
	return {
		publicKey: result.publicKey,
		secretKey: bs58.encode(result.secretKey),
		attempts: result.attempts,
		ms: result.ms,
	};
}

// ── Claims handlers (on-chain) ─────────────────────────────────────────────

const PUMP_CLAIM_PROGRAMS = new Set([
	'6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P',
	'pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA',
	'pfeeUxB6jkeY1Hxd7CsFCAjcbHA9rWtchMGdZ6VojVZ',
]);

async function _fetchClaimsFromChain({ creator, limit = 20, network = 'mainnet', sinceTs = 0 }) {
	const pk = solanaPubkey(creator);
	if (!pk) throw rpcError(-32602, 'invalid creator wallet');
	const conn = getConnection({ network });
	const sigInfos = await conn.getSignaturesForAddress(pk, { limit: Math.min(100, limit * 4) });
	const results = [];
	for (const { signature, blockTime } of sigInfos) {
		if (results.length >= limit) break;
		if (sinceTs && (blockTime ?? 0) <= sinceTs) break;
		let tx;
		try {
			tx = await conn.getParsedTransaction(signature, {
				maxSupportedTransactionVersion: 1,
				commitment: 'confirmed',
			});
		} catch {
			continue;
		}
		if (!tx) continue;
		const allIxs = [
			...(tx.transaction.message.instructions ?? []),
			...(tx.meta?.innerInstructions?.flatMap((i) => i.instructions) ?? []),
		];
		if (!allIxs.some((ix) => PUMP_CLAIM_PROGRAMS.has(ix.programId?.toString?.()))) continue;
		const accounts = tx.transaction.message.accountKeys;
		const idx = accounts.findIndex((a) => a.pubkey.toString() === creator);
		if (idx === -1) continue;
		const lamports = (tx.meta.postBalances[idx] ?? 0) - (tx.meta.preBalances[idx] ?? 0);
		if (lamports <= 0) continue;
		results.push({
			signature,
			mint: tx.meta.postTokenBalances?.[0]?.mint ?? null,
			lamports,
			ts: blockTime ?? Math.floor(Date.now() / 1000),
		});
	}
	return results;
}

async function handleListClaims({ creator, limit = 20, network = 'mainnet' }) {
	if (!creator) throw rpcError(-32602, 'creator required');
	return { creator, network, claims: await _fetchClaimsFromChain({ creator, limit, network }) };
}

async function handleWatchClaims({ creator, durationMs = 300_000, network = 'mainnet' }) {
	if (!creator) throw rpcError(-32602, 'creator required');
	const window = Math.min(1_800_000, Math.max(1, Number(durationMs) || 300_000));
	const sinceTs = Math.floor((Date.now() - window) / 1000);
	const claims = await _fetchClaimsFromChain({ creator, limit: 50, network, sinceTs });
	return { creator, network, windowMs: window, claims };
}

async function handleSocialCashtagSentiment({ posts }) {
	if (!Array.isArray(posts) || posts.length === 0)
		throw rpcError(-32602, 'posts must be a non-empty array');
	const { scoreSentiment } = await import('../src/social/sentiment.js');
	return scoreSentiment(posts);
}

async function handleGetFirstClaims({ sinceMinutes = 60, limit = 20 }) {
	const sinceTs = Math.floor(Date.now() / 1000) - Math.max(1, Math.min(1440, sinceMinutes)) * 60;
	const items = await scanFirstClaims({ sinceTs, limit: Math.max(1, Math.min(50, limit)) });
	return { items };
}

async function handleQuoteSwap({
	inputMint,
	outputMint,
	amountIn,
	slippageBps,
	network = 'mainnet',
}) {
	if (!solanaPubkey(inputMint)) throw rpcError(-32602, 'invalid inputMint');
	if (!solanaPubkey(outputMint)) throw rpcError(-32602, 'invalid outputMint');
	const WSOL = 'So11111111111111111111111111111111111111112';
	if (inputMint !== WSOL && outputMint !== WSOL) {
		throw rpcError(-32602, `one of inputMint or outputMint must be wSOL (${WSOL})`);
	}
	const baseMint = inputMint === WSOL ? outputMint : inputMint;
	let state;
	try {
		state = await getAmmPoolState({ network, mint: baseMint });
	} catch (err) {
		throw rpcError(err.status === 404 ? -32004 : -32603, err.message || 'pool unavailable');
	}
	const { buyQuoteInput, sellBaseInput } = await import('@pump-fun/pump-swap-sdk');
	const BNMod = await import('bn.js');
	const BN = BNMod.default || BNMod;
	const {
		poolKey,
		pool,
		baseReserve,
		quoteReserve,
		virtualQuoteReserves,
		effectiveQuoteReserve,
		baseMintAccount,
		globalConfig,
		feeConfig,
	} = state;
	const amountBn = new BN(String(amountIn));
	// `Pool.virtual_quote_reserves` is a SIGNED i128, so effective depth
	// (vault + virtual) can be zero or negative: a pool that cannot absorb a
	// trade. Refuse rather than quote it, because the impact math below clamps
	// with Math.max(0, …) and would report such a pool as 0 bps, the most
	// attractive quote we can return.
	if (BigInt(effectiveQuoteReserve.toString()) <= 0n) {
		throw rpcError(-32004, 'pool has no tradable quote depth');
	}
	// pump-swap-sdk takes slippage as a PERCENT (1 = 1%): `1 ± slippage / 100`.
	const slip = (slippageBps ?? 100) / 100;
	// `virtualQuoteReserves` is a separate arg the SDK adds to `quoteReserve`
	// itself — pass the RAW reserve here. Our own impact math below uses the
	// pre-summed `effectiveQuoteReserve`.
	const shared = {
		slippage: slip,
		baseReserve,
		quoteReserve,
		virtualQuoteReserves,
		globalConfig,
		baseMintAccount,
		baseMint: pool.baseMint,
		quoteMint: pool.quoteMint,
		isMayhemMode: pool.isMayhemMode,
		creatorFeeBps: pool.creatorFeeBps,
		coinCreator: pool.coinCreator,
		creator: pool.creator,
		feeConfig,
	};
	let amountOut, priceImpactBps;
	if (inputMint === WSOL) {
		const r = buyQuoteInput({ quote: amountBn, ...shared });
		amountOut = r.base;
		const num = amountBn.mul(baseReserve);
		const denom = amountOut.mul(effectiveQuoteReserve);
		priceImpactBps = denom.isZero()
			? 0
			: Math.max(0, num.muln(10_000).div(denom).subn(10_000).toNumber());
	} else {
		const r = sellBaseInput({ base: amountBn, ...shared });
		amountOut = r.uiQuote;
		const spot = effectiveQuoteReserve.mul(amountBn);
		const exec = amountOut.mul(baseReserve);
		priceImpactBps = spot.isZero()
			? 0
			: Math.max(0, spot.sub(exec).muln(10_000).div(spot).toNumber());
	}
	return {
		amountOut: amountOut.toString(),
		priceImpactBps,
		route: poolKey.toBase58(),
		expiresAtMs: Date.now() + 10_000,
		// Reserve provenance, so a caller can reproduce the number above rather
		// than trusting it. Mirrors the /api/pump quote response. The quote side
		// is priced on `effective_quote_reserve` (vault + virtual); the base side
		// is the raw vault balance and is unaffected by that change.
		base_reserve: baseReserve.toString(),
		quote_reserve: quoteReserve.toString(),
		virtual_quote_reserves: virtualQuoteReserves.toString(),
		effective_quote_reserve: effectiveQuoteReserve.toString(),
	};
}

async function handleSocialXPostImpact({ postUrl, mint, windowMin = 30, network = 'mainnet' }) {
	if (!postUrl) throw rpcError(-32602, 'postUrl is required');
	const pk = solanaPubkey(mint);
	if (!pk) throw rpcError(-32602, `invalid mint: ${mint}`);

	let post = null;
	try {
		post = summarizeXPost(await readXPost(postUrl));
	} catch {
		// X unreachable or post gone: curve analysis continues with post=null.
	}

	const { sdk } = await getPumpSdk({ network });
	let curve;
	try {
		if (sdk.fetchBuyState) {
			const state = await sdk.fetchBuyState(pk, pk);
			curve = state.bondingCurve;
		} else if (sdk.fetchBondingCurve) {
			curve = await sdk.fetchBondingCurve(pk);
		}
	} catch (e) {
		throw rpcError(-32004, `bonding curve unavailable: ${e?.message ?? 'unknown'}`);
	}
	if (!curve) throw rpcError(-32004, 'no bonding curve found for this mint');

	const virtSol = Number(curveQuoteReserve(curve, 'virtual') ?? '0');
	const virtToken = Number(curve.virtualTokenReserves?.toString?.() ?? '0');
	const realSolLamports = Number(curveQuoteReserve(curve, 'real') ?? '0');
	const priceRaw = virtToken > 0 ? virtSol / virtToken : null;
	const volSol = realSolLamports / 1e9;

	return {
		post,
		priceBefore: priceRaw,
		priceAfter: priceRaw,
		deltaPct: 0,
		volBefore: volSol,
		volAfter: volSol,
		deltaVolPct: 0,
		note: 'priceBefore/After reflect current bonding curve state; historical delta requires trade data.',
	};
}

// ── pumpfun_watch_whales ───────────────────────────────────────────────────

async function handleWatchWhales({ mint, minUsd = 5000, durationMs = 5000 }) {
	const pk = solanaPubkey(mint);
	if (!pk) throw rpcError(-32602, 'invalid mint');

	// Cap at 10 s — serverless max execution time.
	const windowMs = Math.min(10_000, Math.max(1_000, Number(durationMs) || 5_000));
	const minUsdNum = Math.max(0, Number(minUsd) || 5000);

	const [{ BorshCoder, EventParser }, { PUMP_PROGRAM_ID, pumpIdl }] = await Promise.all([
		import('@coral-xyz/anchor'),
		import('@pump-fun/pump-sdk'),
	]);

	// Shared multi-source SOL/USD price (api/_lib/sol-price.js). The old inline
	// fetch hit api.jup.ag/price/v2, which now 404s, so every call silently ran
	// on a hardcoded $150 and the minUsd whale filter was off by the real price
	// ratio. A hardcoded constant is kept only as the never-resolved fallback.
	let solPrice = 150;
	const livePrice = await solPriceUsd();
	if (livePrice > 0) solPrice = livePrice;

	const connection = getConnection({ network: 'mainnet' });
	const coder = new BorshCoder(pumpIdl);
	const parser = new EventParser(PUMP_PROGRAM_ID, coder);
	const mintStr = pk.toString();
	const trades = [];

	const subId = connection.onLogs(
		PUMP_PROGRAM_ID,
		(logInfo) => {
			if (logInfo.err) return;
			try {
				for (const trade of pumpTradesFromEvents(parser.parseLogs(logInfo.logs))) {
					const d = trade.data;
					if (trade.mint !== mintStr) continue;
					const sol = Number(trade.solAmount) / 1_000_000_000;
					const usd = sol * solPrice;
					if (usd < minUsdNum) continue;
					trades.push({
						signature: logInfo.signature,
						wallet: d.user?.toString() ?? null,
						sideBuy: trade.isBuy,
						usd,
						sol,
						ts:
							Number(eventField(d, 'timestamp')?.toString() ?? '0') * 1000 ||
							Date.now(),
					});
				}
			} catch {}
		},
		'confirmed',
	);

	await new Promise((resolve) => setTimeout(resolve, windowMs));
	await connection.removeOnLogsListener(subId).catch(() => {});

	return { mint, minUsd: minUsdNum, durationMs: windowMs, count: trades.length, trades };
}

// ── getTokenTrades (real on-chain history, indexer-optional) ────────────────

// Recent trade history for a mint, read directly from chain so it works without
// the optional pump.fun indexer. Pre-graduation tokens trade against the pump
// bonding-curve program (`TradeEvent`); graduated tokens trade on the pump AMM
// pool (`BuyEvent`/`SellEvent`). We pull recent signatures for whichever account
// is live, fetch those transactions, and decode the on-chain events.
async function readTradesFromChain({ mint, limit, network }) {
	const pk = solanaPubkey(mint);
	if (!pk) throw rpcError(-32602, 'invalid mint');
	const want = Math.min(50, Math.max(1, Number(limit) || 20));
	// Fetch a few extra signatures since some touching the account aren't trades
	// (fee claims, migrations) and get filtered out during decode.
	const sigLimit = Math.min(60, want * 2);
	const connection = getConnection({ network });

	// Resolve whether the token has graduated to the AMM. A live pool means we
	// read AMM Buy/Sell events; otherwise we read bonding-curve TradeEvents.
	let pool = null;
	try {
		const ammState = await getAmmPoolState({ network, mint });
		pool = ammState?.poolKey ?? null;
	} catch (e) {
		// No pool yet (pool_not_found) or a transient AMM read failure — fall
		// through to the bonding-curve path rather than failing the request.
		void e;
	}

	const [anchor, pumpSdk, ammSdk, solPrice] = await Promise.all([
		import('@coral-xyz/anchor'),
		import('@pump-fun/pump-sdk'),
		import('@pump-fun/pump-swap-sdk'),
		getSolPriceUsd().catch(() => 150),
	]);
	const { BorshCoder, EventParser } = anchor;

	const isAmm = !!pool;
	let address;
	let parser;
	if (isAmm) {
		address = pool;
		const coder = new BorshCoder(ammSdk.pumpAmmJson);
		parser = new EventParser(ammSdk.PUMP_AMM_PROGRAM_ID, coder);
	} else {
		const { getPumpSdkV2 } = await import('./_lib/pump.js');
		const v2 = await getPumpSdkV2({ network });
		address = v2.bondingCurvePda(pk);
		const coder = new BorshCoder(pumpSdk.pumpIdl);
		parser = new EventParser(pumpSdk.PUMP_PROGRAM_ID, coder);
	}

	const sigInfos = await connection.getSignaturesForAddress(address, { limit: sigLimit });
	if (!sigInfos.length) return { mint, network, graduated: isAmm, count: 0, trades: [] };

	const signatures = sigInfos.map((s) => s.signature);
	const mintStr = pk.toString();
	const poolStr = pool?.toString();
	const trades = [];

	function decodeTx(tx, signature) {
		const logs = tx?.meta?.logMessages;
		if (!logs || tx.meta.err) return null;
		const blockTime = tx.blockTime ? tx.blockTime * 1000 : Date.now();
		let parsed;
		try {
			parsed = [...parser.parseLogs(logs)];
		} catch {
			return null;
		}
		for (const event of parsed) {
			if (isAmm && (event.name === 'BuyEvent' || event.name === 'SellEvent')) {
				const d = event.data;
				if (poolStr && d.pool?.toString() !== poolStr) continue;
				const isBuy = event.name === 'BuyEvent';
				const lamports = isBuy
					? eventField(d, 'quoteAmountIn')
					: eventField(d, 'quoteAmountOut');
				const tokens = isBuy
					? eventField(d, 'baseAmountOut')
					: eventField(d, 'baseAmountIn');
				const sol = Number(lamports?.toString() ?? '0') / 1e9;
				const ts = eventField(d, 'timestamp');
				return {
					signature,
					isBuy,
					solAmount: sol,
					tokenAmount: tokens?.toString() ?? '0',
					usdValue: sol * solPrice,
					wallet: d.user?.toString() ?? null,
					timestamp: ts ? Number(ts.toString()) : Math.floor(blockTime / 1000),
				};
			}
		}
		if (isAmm) return null;
		// A buy that completed the curve also carries its synthetic-migration pool
		// part; pumpTradesFromEvents folds it in.
		const trade = pumpTradesFromEvents(parsed).find((t) => t.mint === mintStr);
		if (!trade) return null;
		const sol = Number(trade.solAmount) / 1e9;
		const ts = eventField(trade.data, 'timestamp');
		return {
			signature,
			isBuy: trade.isBuy,
			solAmount: sol,
			tokenAmount: trade.tokenAmount.toString(),
			usdValue: sol * solPrice,
			wallet: trade.user || null,
			timestamp: ts ? Number(ts.toString()) : Math.floor(blockTime / 1000),
		};
	}

	// Fetch in small chunks and stop as soon as we have enough trades. Most
	// signatures touching the curve/pool account ARE trades, so we rarely need
	// the full window — chunking also keeps batch sizes friendly to public RPCs.
	const CHUNK = 8;
	for (let off = 0; off < signatures.length && trades.length < want; off += CHUNK) {
		const slice = signatures.slice(off, off + CHUNK);
		const txs = await connection.getTransactions(slice, {
			maxSupportedTransactionVersion: 1,
			commitment: 'confirmed',
		});
		for (let i = 0; i < txs.length && trades.length < want; i++) {
			const trade = decodeTx(txs[i], slice[i]);
			if (trade) trades.push(trade);
		}
	}

	return { mint, network, graduated: isAmm, count: trades.length, trades };
}

async function handleGetTokenTrades({ mint, limit = 20, network = 'mainnet' }) {
	// Fast path: if the indexer is configured it serves richer historical data.
	if (pumpfunBotEnabled()) {
		const r = await pumpfunMcpCall('getTokenTrades', { mint, limit });
		if (r.ok) return r.data;
		// Indexer configured but errored — fall back to on-chain reads.
	}
	return readTradesFromChain({ mint, limit, network });
}

// ── get_coin_intel ─────────────────────────────────────────────────────────

// Reads the precomputed intel snapshot from pump_coin_intel + outcome label.
// This is the highest-signal single read for a trade decision — it combines
// classification, bundle/organic analysis, smart-money presence, bubblemaps
// connectivity, risk flags, and labeled outcome into one call.
async function handleGetCoinIntel({ mint, network = 'mainnet' } = {}) {
	if (!mint || typeof mint !== 'string') throw new Error('mint required');
	const cleanMint = mint.trim();

	// Lazy import so the MCP handler loads in edge envs without DATABASE_URL.
	let sql;
	try {
		sql = (await import('./_lib/db.js')).sql;
	} catch {
		return { found: false, reason: 'database_unavailable' };
	}

	const LAMPORTS_PER_SOL = 1_000_000_000;
	const num = (v) => {
		const n = Number(v);
		return Number.isFinite(n) ? n : null;
	};
	const sol = (v) => {
		const n = num(v);
		return n == null ? null : Math.round((n / LAMPORTS_PER_SOL) * 10000) / 10000;
	};

	try {
		// Main intel row
		const [row] = await sql`
			select mint, network, symbol, name, creator, image_uri, description,
				twitter, telegram, website, created_at, first_seen_at, observation_seconds,
				dev_buy_lamports, dev_sold, buy_count, sell_count,
				buy_volume_lamports, sell_volume_lamports, unique_buyers, unique_sellers,
				largest_buy_lamports, signals, bundle_score, organic_score, snipe_ratio,
				concentration_top10, fresh_wallet_ratio, bubblemap_connectivity,
				quality_score, risk_flags, category, tags, narrative, is_news_meme,
				classify_confidence, classify_source,
				smart_money_count, smart_money_score, smart_money_notable, cluster_count
			from pump_coin_intel
			where mint = ${cleanMint} and network = ${network}
			limit 1
		`;

		if (!row) return { found: false, mint: cleanMint, network };

		const signals = row.signals && typeof row.signals === 'object' ? row.signals : {};
		const riskFlags = Array.isArray(row.risk_flags) ? row.risk_flags : [];
		const q = num(row.quality_score) ?? 0;
		const hardFlags = ['bundle_launch', 'dev_dumped', 'single_whale'];
		const hard = riskFlags.some((f) => hardFlags.includes(f));
		const verdict =
			hard || q < 25
				? { key: 'avoid', label: 'Avoid', tone: 'danger' }
				: q < 50 || riskFlags.length
					? { key: 'caution', label: 'Caution', tone: 'warn' }
					: q < 72
						? { key: 'watch', label: 'Watch', tone: 'neutral' }
						: { key: 'strong', label: 'Strong', tone: 'success' };

		// Outcome label (may not exist yet for fresh coins)
		let outcome = null;
		try {
			const [o] = await sql`
				select outcome, graduated, rugged, ath_market_cap_usd, ath_multiple, labeled_at
				from pump_coin_outcomes where mint = ${cleanMint} limit 1
			`;
			if (o)
				outcome = {
					outcome: o.outcome,
					graduated: o.graduated,
					rugged: o.rugged,
					ath_market_cap_usd: num(o.ath_market_cap_usd),
					ath_multiple: num(o.ath_multiple),
					labeled_at: o.labeled_at,
				};
		} catch {
			/* outcome table absent — fine */
		}

		// Top wallets (compact — notable ones only for the MCP response)
		let topWallets = [];
		try {
			const wrows = await sql`
				select wallet, buy_lamports, sell_lamports, is_creator, funder, first_seen_at
				from pump_coin_wallets where mint = ${cleanMint}
				order by buy_lamports desc limit 20
			`;
			const totalBuy = wrows.reduce((s, w) => s + (num(w.buy_lamports) || 0), 0) || 1;
			topWallets = wrows.map((w) => ({
				wallet: w.wallet,
				is_creator: !!w.is_creator,
				buy_sol: sol(w.buy_lamports),
				sell_sol: sol(w.sell_lamports),
				share: Math.round(((num(w.buy_lamports) || 0) / totalBuy) * 1000) / 1000,
				funder: w.funder || null,
			}));
		} catch {
			/* wallets absent — fine */
		}

		// Latest model conditional win-rates (so agents see the evidence behind each signal)
		let model = null;
		try {
			const [wrow] = await sql`
				select weights, conditional_win_rates, sample_size, trained_at
				from pump_intel_weights
				where network = ${network}
				order by trained_at desc limit 1
			`;
			if (wrow)
				model = {
					sample_size: wrow.sample_size,
					trained_at: wrow.trained_at,
					conditional_win_rates: wrow.conditional_win_rates || null,
				};
		} catch {
			/* weights table absent — training hasn't run yet */
		}

		// Oracle conviction — fused 4-pillar score from the oracle engine (may not
		// exist for brand-new coins; the oracle-score cron sweeps ~every 5 min).
		let oracle = null;
		try {
			const [oc] = await sql`
				select score, tier, pedigree, structure, narrative, momentum,
				       structure_cap, badges, reasons, scored_at
				from oracle_conviction
				where mint = ${cleanMint} and network = ${network}
				limit 1
			`;
			if (oc)
				oracle = {
					score: num(oc.score),
					tier: oc.tier,
					pillars: {
						pedigree: num(oc.pedigree),
						structure: num(oc.structure),
						narrative: num(oc.narrative),
						momentum: num(oc.momentum),
					},
					structure_cap: !!oc.structure_cap,
					badges: Array.isArray(oc.badges) ? oc.badges : [],
					reasons: Array.isArray(oc.reasons) ? oc.reasons : [],
					scored_at: oc.scored_at,
				};
		} catch {
			/* oracle tables not yet migrated — fine */
		}

		const smartNotable = Array.isArray(row.smart_money_notable) ? row.smart_money_notable : [];

		// Build a plain-language summary the agent can read directly
		const parts = [];
		if (verdict.key === 'avoid') parts.push('⛔ AVOID.');
		else if (verdict.key === 'strong') parts.push('✅ Strong entry signal.');
		if (row.smart_money_count > 0)
			parts.push(
				`${row.smart_money_count} proven smart-money wallet${row.smart_money_count > 1 ? 's' : ''} entered (win-rate avg ${smartNotable[0]?.win_rate != null ? (smartNotable[0].win_rate * 100).toFixed(0) + '%' : 'unknown'}).`,
			);
		if (row.dev_sold) parts.push('Dev sold during observation window — high rug risk.');
		if (riskFlags.includes('bundle_launch')) parts.push('Coordinated bundle launch detected.');
		if (row.is_news_meme && signals.news_headline)
			parts.push(`News-meme: "${signals.news_headline}".`);
		if (row.category && row.category !== 'unknown') parts.push(`Category: ${row.category}.`);
		if (outcome?.graduated) parts.push('GRADUATED to Raydium.');
		else if (outcome?.rugged) parts.push('Rugged.');
		else if (outcome?.ath_multiple)
			parts.push(`ATH ${outcome.ath_multiple.toFixed(1)}× from entry.`);
		const summary =
			parts.join(' ') ||
			`Quality ${q}/100. ${riskFlags.length ? 'Risk flags: ' + riskFlags.join(', ') + '.' : 'No hard risk flags.'}`;

		return {
			found: true,
			mint: row.mint,
			network: row.network,
			symbol: row.symbol,
			name: row.name,
			creator: row.creator,
			image_uri: row.image_uri,
			has_socials: !!(row.twitter || row.telegram || row.website),
			twitter: row.twitter,
			telegram: row.telegram,
			website: row.website,
			first_seen_at: row.first_seen_at,
			observation_seconds: num(row.observation_seconds),

			// Verdict
			quality_score: q,
			verdict,
			risk_flags: riskFlags,
			summary,

			// Classification
			category: row.category || 'unknown',
			tags: Array.isArray(row.tags) ? row.tags : [],
			narrative: row.narrative,
			is_news_meme: !!row.is_news_meme,
			news_headline: signals.news_headline || null,
			news_url: signals.news_url || null,
			classify_confidence: num(row.classify_confidence),
			classify_source: row.classify_source,

			// Core signals
			organic_score: num(row.organic_score),
			bundle_score: num(row.bundle_score),
			snipe_ratio: num(row.snipe_ratio),
			concentration_top10: num(row.concentration_top10),
			fresh_wallet_ratio: num(row.fresh_wallet_ratio),
			bubblemap_connectivity: num(row.bubblemap_connectivity),
			cluster_count: num(row.cluster_count) ?? 0,
			timing_entropy: num(signals.timing_entropy),

			// Dev
			dev_buy_sol: sol(row.dev_buy_lamports),
			dev_sold: !!row.dev_sold,

			// Trade footprint
			unique_buyers: num(row.unique_buyers) ?? 0,
			unique_sellers: num(row.unique_sellers) ?? 0,
			buy_count: num(row.buy_count) ?? 0,
			sell_count: num(row.sell_count) ?? 0,
			buy_volume_sol: sol(row.buy_volume_lamports),
			sell_volume_sol: sol(row.sell_volume_lamports),
			largest_buy_sol: sol(row.largest_buy_lamports),
			buy_sell_ratio: num(signals.buy_sell_ratio),

			// Smart money
			smart_money_count: num(row.smart_money_count) ?? 0,
			smart_money_score: num(row.smart_money_score),
			smart_money_notable: smartNotable,

			// Wallet book
			top_wallets: topWallets,

			// Outcome (null if coin not yet labeled)
			outcome,

			// Learning model: conditional win-rates so agents can see the evidence behind the score
			model,

			// Oracle conviction — fused score from the 4-pillar engine (null until scored)
			oracle,
			oracle_url: `https://three.ws/oracle?mint=${encodeURIComponent(cleanMint)}`,
		};
	} catch (err) {
		const missing = /relation .* does not exist/i.test(String(err?.message));
		if (missing) return { found: false, reason: 'engine_tables_pending' };
		throw err;
	}
}

// ── pumpfun_upload_metadata ────────────────────────────────────────────────
//
// Build + pin a pump.fun-ready metadata JSON to IPFS. Returns an ipfs:// URI
// the caller passes to /api/pump/launch-agent as the `uri` field to launch
// their coin. Requires bearer auth (API key) so Pinata credits aren't open.
//
// Two-step: (1) pin the image, (2) build the metadata JSON with the image CID
// and pin that too. Both steps go through the shared provider chain in
// api/_lib/ipfs-pin.js (Pinata, then web3.storage, each with a deadline and a
// breaker) so one provider's outage never fails the launch prep.

const IMG_MAX_BYTES = 5 * 1024 * 1024; // 5 MB
const META_IMG_TIMEOUT_MS = 8_000;

async function _pinBuffer(buf, filename) {
	if (!ipfsPinningConfigured()) {
		throw rpcError(
			-32004,
			'no IPFS pinning provider configured (PINATA_JWT or WEB3_STORAGE_TOKEN)',
		);
	}
	try {
		const { cid, provider } = await pinToIPFS(buf, filename);
		return { cid, provider };
	} catch (err) {
		throw Object.assign(new Error(`IPFS pin failed: ${err?.message || err}`), { rpcCode: -32004 });
	}
}

async function _fetchImgBuf(imageUrl) {
	if (imageUrl.startsWith('data:')) {
		const comma = imageUrl.indexOf(',');
		if (comma === -1) throw rpcError(-32602, 'invalid data: URI');
		const meta = imageUrl.slice(0, comma);
		const payload = imageUrl.slice(comma + 1);
		const buf = meta.includes('base64')
			? Buffer.from(payload, 'base64')
			: Buffer.from(decodeURIComponent(payload));
		if (buf.byteLength > IMG_MAX_BYTES) throw rpcError(-32602, 'image exceeds 5 MB');
		const mime = meta.split(':')[1]?.split(';')[0] || 'image/png';
		return { buf, filename: `image.${mime.split('/')[1] || 'png'}` };
	}
	const ctrl = new AbortController();
	const tid = setTimeout(() => ctrl.abort(), META_IMG_TIMEOUT_MS);
	try {
		// image_url is fully caller-supplied; guard against SSRF (internal hosts /
		// cloud metadata) before fetching. Pinned variant closes the DNS-rebind window.
		let r;
		try {
			r = await fetchSafePublicUrlPinned(
				imageUrl,
				{ signal: ctrl.signal },
				{ allowHttp: true },
			);
		} catch (err) {
			if (err instanceof SsrfBlockedError)
				throw rpcError(-32602, 'image_url is not an allowed public URL');
			throw err;
		}
		if (!r.ok) throw rpcError(-32004, `image fetch failed: HTTP ${r.status}`);
		const buf = Buffer.from(await r.arrayBuffer());
		if (buf.byteLength > IMG_MAX_BYTES) throw rpcError(-32602, 'image exceeds 5 MB');
		const ct = r.headers.get('content-type') || 'image/png';
		const ext = ct.split('/')[1]?.split(';')[0] || 'png';
		const fname = new URL(imageUrl, 'https://x').pathname.split('/').pop() || `image.${ext}`;
		return { buf, filename: fname };
	} finally {
		clearTimeout(tid);
	}
}

async function handleUploadMetadata({
	name,
	symbol,
	description,
	image_url,
	twitter,
	telegram,
	website,
} = {}) {
	if (!name || !symbol || !description || !image_url)
		throw rpcError(-32602, 'name, symbol, description, and image_url are required');
	if (String(name).length > 32) throw rpcError(-32602, 'name exceeds 32 chars');
	if (String(symbol).length > 10) throw rpcError(-32602, 'symbol exceeds 10 chars');
	if (String(description).length > 500) throw rpcError(-32602, 'description exceeds 500 chars');

	const { buf: imgBuf, filename: imgFilename } = await _fetchImgBuf(image_url);
	const { cid: imageCid, provider } = await _pinBuffer(imgBuf, imgFilename);
	const imageUri = `https://ipfs.io/ipfs/${imageCid}`;

	const meta = {
		name: String(name).slice(0, 32),
		symbol: String(symbol).replace(/^\$/, '').slice(0, 10),
		description: String(description).slice(0, 500),
		image: imageUri,
		showName: true,
		createdOn: 'https://three.ws',
	};
	if (twitter) meta.twitter = String(twitter);
	if (telegram) meta.telegram = String(telegram);
	if (website) meta.website = String(website);

	const metaBuf = Buffer.from(JSON.stringify(meta), 'utf8');
	const { cid } = await _pinBuffer(metaBuf, 'metadata.json');
	const uri = `https://ipfs.io/ipfs/${cid}`;
	return { uri, cid, image_cid: imageCid, provider };
}

// ── pumpfun_bot_status (metadata, always available) ────────────────────────

// Reports whether the indexer is configured and, when it is, whether it's
// answering. Always available (never gated, never filtered) so MCP clients can
// discover backend capability without parsing tools/list. The health ping uses
// the same transport as the indexer tools (MCP tools/call against the bot) with
// a tight 3 s budget so a slow/dead bot can't stall the metadata call.
async function handlePumpfunBotStatus() {
	if (!pumpfunBotEnabled()) {
		return {
			configured: false,
			healthy: false,
			message:
				'PUMPFUN_BOT_URL is not configured. On-chain tools are available; indexer-backed discovery tools are disabled.',
		};
	}
	const url = process.env.PUMPFUN_BOT_URL.replace(/\/$/, '');
	const headers = { 'content-type': 'application/json', accept: 'application/json' };
	if (process.env.PUMPFUN_BOT_TOKEN)
		headers.authorization = `Bearer ${process.env.PUMPFUN_BOT_TOKEN}`;
	const ctrl = new AbortController();
	const timer = setTimeout(() => ctrl.abort(), 3000);
	const startedAt = Date.now();
	try {
		const r = await fetch(url, {
			method: 'POST',
			headers,
			body: JSON.stringify({
				jsonrpc: '2.0',
				id: 1,
				method: 'tools/call',
				params: { name: 'getNewTokens', arguments: { limit: 1 } },
			}),
			signal: ctrl.signal,
		});
		const latencyMs = Date.now() - startedAt;
		if (!r.ok) return { configured: true, healthy: false, latencyMs, error: `bot ${r.status}` };
		const j = await r.json().catch(() => null);
		if (j?.error)
			return {
				configured: true,
				healthy: false,
				latencyMs,
				error: j.error.message || 'rpc error',
			};
		return { configured: true, healthy: true, latencyMs };
	} catch (err) {
		return {
			configured: true,
			healthy: false,
			error:
				err?.name === 'AbortError'
					? 'timeout after 3000ms'
					: err?.message || 'fetch failed',
		};
	} finally {
		clearTimeout(timer);
	}
}

// ── get_oracle_conviction ──────────────────────────────────────────────────

// Returns the fused Oracle conviction score for a mint: 4-pillar breakdown,
// tier, badges, reasons, full who's-in trader roster, narrative classification,
// and labeled outcome when available.
async function handleGetOracleConviction({ mint, network = 'mainnet' } = {}) {
	if (!mint || typeof mint !== 'string') throw new Error('mint required');
	const cleanMint = mint.trim();

	let sql;
	try {
		sql = (await import('./_lib/db.js')).sql;
	} catch {
		return { found: false, reason: 'database_unavailable' };
	}

	const num = (v) => {
		const n = Number(v);
		return Number.isFinite(n) ? n : null;
	};

	try {
		// 1. Conviction verdict from oracle_conviction cache
		const [conv] = await sql`
			select mint, network, symbol, name, image_uri,
			       score, tier, pedigree, structure, narrative, momentum,
			       structure_cap, badges, reasons, components, category,
			       smart_wallet_count, scored_at
			from oracle_conviction
			where mint = ${cleanMint} and network = ${network}
			limit 1
		`.catch(() => []);

		if (conv == null) {
			// Not yet scored — return basic identity if we at least know the coin
			const [basic] = await sql`
				select mint, symbol, name from pump_coin_intel
				where mint = ${cleanMint} and network = ${network} limit 1
			`.catch(() => []);
			return {
				found: !!basic,
				mint: cleanMint,
				symbol: basic?.symbol || null,
				name: basic?.name || null,
				conviction: null,
				narrative: null,
				whos_in: [],
				outcome: null,
				url: `https://three.ws/oracle?mint=${encodeURIComponent(cleanMint)}`,
				reason: basic ? 'not_yet_scored' : 'unknown_mint',
			};
		}

		// 2. Narrative classification
		const [narr] = await sql`
			select category, narrative, virality, confidence, tags, source
			from oracle_narrative
			where mint = ${cleanMint} and network = ${network} limit 1
		`.catch(() => []);

		// 3. Trader roster — wallets annotated with reputation labels
		const walletRows = await sql`
			select w.wallet, w.buy_lamports, w.sell_lamports, w.is_creator, w.funder,
			       r.label, r.smart_money_score, r.win_rate, r.early_win_rate, r.tag
			from pump_coin_wallets w
			left join wallet_reputation r on r.wallet = w.wallet and r.network = ${network}
			where w.mint = ${cleanMint}
			order by w.buy_lamports desc
			limit 50
		`.catch(() => []);

		// 4. Outcome label
		let outcome = null;
		try {
			const [o] = await sql`
				select outcome, graduated, rugged, ath_market_cap_usd, ath_multiple, labeled_at
				from pump_coin_outcomes where mint = ${cleanMint} limit 1
			`;
			if (o)
				outcome = {
					outcome: o.outcome,
					graduated: o.graduated,
					rugged: o.rugged,
					ath_market_cap_usd: num(o.ath_market_cap_usd),
					ath_multiple: num(o.ath_multiple),
					labeled_at: o.labeled_at,
				};
		} catch {
			/* fine — table may not exist yet */
		}

		// Resolve wallet labels: brain reputation wins; knownWallet() seed fills the gap.
		let knownWallet;
		try {
			const kw = await import('./_lib/oracle/known-wallets.js');
			await kw.loadKnownWallets();
			knownWallet = kw.knownWallet;
		} catch {
			knownWallet = () => null;
		}

		const whosIn = walletRows.map((w) => {
			const brainLabel = w.label && w.label !== 'unproven' ? w.label : null;
			const known = brainLabel ? null : knownWallet(w.wallet);
			return {
				wallet: w.wallet,
				label: brainLabel || known?.label || 'unproven',
				score:
					w.smart_money_score != null ? num(w.smart_money_score) : (known?.score ?? null),
				win_rate: w.win_rate != null ? num(w.win_rate) : null,
				early_win_rate: w.early_win_rate != null ? num(w.early_win_rate) : null,
				source: brainLabel ? 'brain' : known ? 'gmgn' : null,
				tag: w.tag || known?.tag || null,
				buy_sol: Number(w.buy_lamports || 0) / 1e9,
				sell_sol: Number(w.sell_lamports || 0) / 1e9,
				is_creator: !!w.is_creator,
				funder: w.funder || null,
			};
		});

		// Tier summary for agent quick-read
		const tierLabel =
			{
				prime: 'PRIME — highest conviction. Top-grade entry signal.',
				strong: 'STRONG — solid conviction. Enter with normal position size.',
				lean: 'LEAN — mild positive lean. Size small or wait for confirmation.',
				watch: 'WATCH — insufficient signal. Observe only.',
				avoid: 'AVOID — negative signal. Do not enter.',
			}[conv.tier] || conv.tier;

		return {
			found: true,
			mint: conv.mint,
			network: conv.network,
			symbol: conv.symbol,
			name: conv.name,
			image_uri: conv.image_uri,
			category: conv.category || narr?.category || 'unknown',

			conviction: {
				score: num(conv.score),
				tier: conv.tier,
				tier_label: tierLabel,
				pillars: {
					pedigree: num(conv.pedigree),
					structure: num(conv.structure),
					narrative: num(conv.narrative),
					momentum: num(conv.momentum),
				},
				structure_cap: !!conv.structure_cap,
				badges: Array.isArray(conv.badges) ? conv.badges : [],
				reasons: Array.isArray(conv.reasons) ? conv.reasons : [],
				scored_at: conv.scored_at,
			},

			narrative: narr
				? {
						category: narr.category,
						narrative: narr.narrative,
						virality: num(narr.virality),
						confidence: num(narr.confidence),
						tags: Array.isArray(narr.tags) ? narr.tags : [],
						source: narr.source,
					}
				: null,

			whos_in: whosIn,
			outcome,
			url: `https://three.ws/oracle?mint=${encodeURIComponent(cleanMint)}`,
		};
	} catch (err) {
		const missing = /relation .* does not exist/i.test(String(err?.message));
		if (missing) return { found: false, reason: 'oracle_tables_pending' };
		throw err;
	}
}

// ── Dispatch ───────────────────────────────────────────────────────────────

// Keyed by CANONICAL (snake_case) names. tools/call resolves legacy camelCase
// aliases through resolveToolName before this lookup.
const HANDLERS = {
	get_bonding_curve: handleGetBondingCurve,
	get_token_details: handleGetTokenDetails,
	get_token_holders: handleGetTokenHolders,
	get_coin_intel: handleGetCoinIntel,
	get_oracle_conviction: handleGetOracleConviction,
	kol_leaderboard: handleKolLeaderboard,
	search_tokens: indexerOrUnavailable('search_tokens'),
	get_token_trades: handleGetTokenTrades,
	get_trending_tokens: liveFeedOrIndexer('get_trending_tokens', getTrendingSlim),
	get_new_tokens: liveFeedOrIndexer('get_new_tokens', getNewSlim),
	get_graduated_tokens: indexerOrUnavailable('get_graduated_tokens'),
	get_king_of_the_hill: indexerOrUnavailable('get_king_of_the_hill'),
	social_cashtag_sentiment: handleSocialCashtagSentiment,
	social_x_post_impact: handleSocialXPostImpact,
	get_creator_profile: indexerOrUnavailable('get_creator_profile'),
	pumpfun_list_claims: handleListClaims,
	pumpfun_watch_claims: handleWatchClaims,
	pumpfun_first_claims: handleGetFirstClaims,
	pumpfun_vanity_mint: handleVanityMint,
	pumpfun_watch_whales: handleWatchWhales,
	pumpfun_quote_swap: handleQuoteSwap,
	sns_resolve: handleSnsResolve,
	sns_reverseLookup: handleSnsReverseLookup,
	pumpfun_upload_metadata: handleUploadMetadata,
	pumpfun_bot_status: handlePumpfunBotStatus,
};

/**
 * In-process tool call for server-side callers (the skill runtime behind
 * /api/pump/strategy-*). Same alias resolution and handler table as the HTTP
 * route, without the loopback hop: a strategy loop polling four tools per mint
 * every three seconds would otherwise spend the server's own per-IP MCP rate
 * limit on itself. Gated tools (vanity grind, whale watch, metadata pin) stay
 * HTTP-only because their bearer / x402 proof lives on the request.
 *
 * Resolves with the tool's data; rejects with an Error carrying `rpcCode` so a
 * caller can wrap it in the JSON-RPC envelope the skills unwrap.
 */
export async function callPumpFunTool(requestedName, args = {}) {
	const name = resolveToolName(requestedName);
	const handler =
		typeof name === 'string' && Object.hasOwn(HANDLERS, name) ? HANDLERS[name] : null;
	if (!handler) throw rpcError(-32601, `unknown tool: ${requestedName}`);
	if (AUTH_REQUIRED_TOOLS.has(name)) {
		throw rpcError(-32001, `tool "${name}" needs a bearer or x402 payment: call it over HTTP`);
	}
	return handler(args && typeof args === 'object' ? args : {});
}

/**
 * The tools this server advertises right now: indexer-backed tools only when
 * the indexer is configured, exactly what tools/list returns over HTTP. The
 * unified server at /mcp mounts this same list.
 */
export function listPumpFunTools() {
	return pumpfunBotEnabled() ? TOOLS : TOOLS.filter((t) => !INDEXER_TOOLS.has(t.name));
}

/**
 * Every tool this server can serve, each flagged with whether it needs the
 * pump.fun indexer. listPumpFunTools() is the subset live right now; the MCP
 * census (api/_lib/mcp-census.js) publishes both numbers.
 * @returns {Array<{ tool: object, indexer: boolean }>}
 */
export function listAllPumpFunTools() {
	return TOOLS.map((tool) => ({ tool, indexer: INDEXER_TOOLS.has(tool.name) }));
}

/**
 * The raw handler for one tool, for a caller that authenticates the request
 * itself (the unified server at /mcp). Unlike callPumpFunTool this includes
 * the gated tools, so that caller owns their bearer-or-payment check and the
 * per-principal gated rate limit.
 * @returns {{ handler: Function, gated: boolean } | null}
 */
export function pumpFunToolEntry(requestedName) {
	const name = resolveToolName(requestedName);
	if (typeof name !== 'string' || !Object.hasOwn(HANDLERS, name)) return null;
	return { handler: HANDLERS[name], gated: AUTH_REQUIRED_TOOLS.has(name) };
}

// ── HTTP entrypoint ────────────────────────────────────────────────────────

// Keep in sync with api/_lib/mcp-dispatch.js PROTOCOL_VERSION. Declared locally
// (not imported) so this read-only lambda — and the Worker mirror — don't pull
// the usage/db graph that mcp-dispatch carries.
const PROTOCOL_VERSION = '2025-06-18';
const RESOURCE_PATH = '/api/pump-fun-mcp';
const SERVER_INFO = { name: 'three.ws-pumpfun-mcp', version: '1.0.0' };
const INSTRUCTIONS =
	'Free, read-only pump.fun + Solana intelligence tools from three.ws. ' +
	'ORACLE CONVICTION (highest-signal trade read): get_oracle_conviction returns the ' +
	'fused 0–100 Oracle score for a mint — a 4-pillar synthesis of pedigree (smart-money ' +
	'presence), structure (organic vs bundle, holder concentration, bubblemaps connectivity), ' +
	'narrative (category, meme virality, news hook), and momentum (velocity, timing). ' +
	'Includes the tier (prime ≥86 / strong ≥72 / lean ≥54 / watch ≥36 / avoid), ' +
	'natural-language reasons, badge labels, and the full classified trader roster with ' +
	'win-rates. COIN INTELLIGENCE (raw signals): get_coin_intel returns every signal recorded ' +
	'during the observation window — bundle/organic verdict, bubblemaps cluster connectivity, ' +
	'smart-money wallet details, dev behaviour, category, news-meme detection, risk flags, ' +
	'quality score, and now also includes the Oracle score inline. ' +
	'Token discovery (search_tokens, get_trending_tokens, get_new_tokens, ' +
	'get_graduated_tokens, get_king_of_the_hill), on-chain analysis (get_bonding_curve, ' +
	'get_token_holders, get_token_details, get_token_trades), creator intelligence ' +
	'(get_creator_profile, pumpfun_list_claims, pumpfun_watch_claims, ' +
	'pumpfun_first_claims), Solana Name Service (sns_resolve, sns_reverseLookup), ' +
	'market signals (kol_leaderboard, pumpfun_quote_swap, ' +
	'pumpfun_watch_whales), and social sentiment (social_cashtag_sentiment, ' +
	'social_x_post_impact). Discovery tools require the indexer backend — call ' +
	'pumpfun_bot_status (always available) to check. ' +
	'LAUNCH A COIN: to deploy a new pump.fun coin as an agent, call pumpfun_upload_metadata ' +
	'(bearer required) to pin name/symbol/description/image to IPFS and get a uri, then POST ' +
	'to /api/pump/launch-agent with agent_id + uri to build, sign, and submit the launch ' +
	"transaction using the agent's custodial wallet. All data is live; most tools need no key.";
const MAX_BATCH = 16;

// Tools that are expensive (CPU grind or long-lived RPC subscriptions) or that
// return sensitive material (a secret key). These require authentication — a
// valid bearer (OAuth access token or sk_live_/sk_test_ API key) OR a verified
// x402 micropayment. The free read-only snapshot/quote tools stay open.
const AUTH_REQUIRED_TOOLS = new Set([
	'pumpfun_vanity_mint',
	'pumpfun_watch_whales',
	'pumpfun_watch_claims',
	'pumpfun_upload_metadata',
]);

// Resolve the caller's credentials for a gated tool, once per request. Returns
//   { ok: true, x402Ctx, principal }  x402Ctx null for bearer auth, or the
//                                    verified payment envelope to settle later;
//                                    principal is a stable per-caller key used for
//                                    the per-principal rate limit on gated tools
//   { ok: false, failure }           failure.kind ∈ bad_bearer | bad_payment |
//                                    no_credentials (+ message, envelope)
// The result is memoized so a batch carrying several gated calls verifies the
// bearer / X-PAYMENT exactly once and one payment covers the whole request.
async function resolveGatedAuth(req) {
	const bearer = extractBearer(req);
	if (bearer) {
		const auth = await authenticateBearer(bearer).catch(() => null);
		if (auth) {
			// A valid bearer authorizes the gated tools for free, so bind a stable
			// principal (api key id / oauth subject) for the per-principal rate limit
			// — otherwise one account could drive unlimited expensive/credit-burning
			// calls.
			const principal = auth.apiKeyId
				? `apikey:${auth.apiKeyId}`
				: `user:${auth.userId || 'unknown'}`;
			return { ok: true, x402Ctx: null, principal };
		}
		return {
			ok: false,
			failure: {
				kind: 'bad_bearer',
				code: -32001,
				message: 'authentication required: invalid or expired bearer token',
			},
		};
	}
	const paymentHeader = req.headers['x-payment'];
	if (paymentHeader) {
		const resourceUrl = resolveResourceUrl(req, RESOURCE_PATH);
		const requirements = paymentRequirements(resourceUrl);
		try {
			const verified = await verifyPayment({ paymentHeader, requirements });
			const payer = verified?.payer || verified?.payload?.payer || null;
			return {
				ok: true,
				x402Ctx: { resourceUrl, requirements, verified },
				principal: payer ? `payer:${payer}` : `ip:${clientIp(req)}`,
			};
		} catch (err) {
			return {
				ok: false,
				failure: {
					kind: 'bad_payment',
					code: -32402,
					message: `payment verification failed: ${err?.message || 'invalid payment'}`,
				},
			};
		}
	}
	// No bearer, no payment: surface the full x402 envelope so paying agents
	// (and registry crawlers like zauth) can discover price/accepts. The body
	// keeps the JSON-RPC error shape MCP clients expect, with the envelope
	// mirrored in error.data and the PAYMENT-REQUIRED header (same
	// dual-protocol pattern as _mcp/auth.js).
	const resourceUrl = resolveResourceUrl(req, RESOURCE_PATH);
	const envelope = build402Body({
		resourceUrl,
		accepts: paymentRequirements(resourceUrl),
		error: 'X-PAYMENT header is required',
	});
	return {
		ok: false,
		failure: {
			kind: 'no_credentials',
			code: -32402,
			message:
				'payment or authentication required for this tool (provide a Bearer token or X-PAYMENT)',
			envelope,
		},
	};
}

// Single-request gate denial: same statuses, bodies, and headers raw JSON-RPC
// consumers have always received (401 bad bearer / 402 otherwise).
function writeGatedAuthFailure(res, id, failure) {
	if (failure.kind === 'no_credentials') {
		res.setHeader(
			'PAYMENT-REQUIRED',
			Buffer.from(JSON.stringify(failure.envelope), 'utf8').toString('base64'),
		);
	}
	const status = failure.kind === 'bad_bearer' ? 401 : 402;
	return json(
		res,
		status,
		rpcEnvelope(id, null, {
			code: failure.code,
			message: failure.message,
			...(failure.envelope ? { data: failure.envelope } : {}),
		}),
		{ 'mcp-protocol-version': PROTOCOL_VERSION },
	);
}

// Batch-mode gate denial: HTTP stays 200, the denial becomes a per-message
// JSON-RPC error (the PAYMENT-REQUIRED header is still set for discovery).
function gatedAuthFailureEnvelope(res, id, failure) {
	if (failure.kind === 'no_credentials' && !res.headersSent) {
		res.setHeader(
			'PAYMENT-REQUIRED',
			Buffer.from(JSON.stringify(failure.envelope), 'utf8').toString('base64'),
		);
	}
	return rpcEnvelope(id, null, {
		code: failure.code,
		message: failure.message,
		...(failure.envelope ? { data: failure.envelope } : {}),
	});
}

// GET/HEAD — the Streamable HTTP SSE handshake. This server never initiates
// server→client messages (stateless, request-scoped lambda), so the stream
// opens with the correct content-type and closes immediately; the spec allows
// the server to close the SSE stream at any time. All tools that don't carry
// an auth gate are free, so unlike /api/mcp-3d the handshake itself requires
// no credentials.
function handleSseHandshake(req, res) {
	res.statusCode = 200;
	res.setHeader('content-type', 'text/event-stream');
	res.setHeader('cache-control', 'no-store');
	res.setHeader('mcp-protocol-version', PROTOCOL_VERSION);
	if (req.method === 'HEAD') return res.end();
	res.write(`: ${SERVER_INFO.name} streamable-http — POST JSON-RPC 2.0 to this URL\n\n`);
	return res.end();
}

// Dispatch ONE JSON-RPC message. Returns null for notifications (no response
// is owed) or the response envelope. `ctx` carries per-request state:
//   ensureGateAuth()  memoized resolveGatedAuth for this request
//   batch             true → gate denials become per-message error envelopes
//                     (single requests keep their legacy HTTP 401/402 — the
//                     caller handles the `gateDenied` flag)
async function dispatchRpc(msg, ctx) {
	const { id = null, method: rpcMethod, params } = msg || {};
	const isNotification = msg?.id === undefined && typeof rpcMethod === 'string';

	if (rpcMethod === 'initialize') {
		return rpcEnvelope(id, {
			protocolVersion: PROTOCOL_VERSION,
			capabilities: { tools: { listChanged: false } },
			// indexerEnabled lets client authors check indexer capability without a
			// tools/list round-trip — it tracks the same env presence as the filter.
			serverInfo: { ...SERVER_INFO, indexerEnabled: pumpfunBotEnabled() },
			instructions: INSTRUCTIONS,
		});
	}
	if (rpcMethod === 'ping') return rpcEnvelope(id, {});
	if (rpcMethod === 'notifications/initialized') return null;
	if (rpcMethod === 'tools/list') {
		// Advertise indexer-backed tools only when the bot is configured, so MCP
		// clients never see a tool that would just return -32004 on call. The
		// always-on pumpfun_bot_status (not in INDEXER_TOOLS) reports capability.
		return rpcEnvelope(id, { tools: await listForRequest(POLICY_SERVER, listPumpFunTools(), null, ctx.req) });
	}
	if (rpcMethod === 'resources/list') return rpcEnvelope(id, { resources: [] });
	if (rpcMethod === 'resources/templates/list') return rpcEnvelope(id, { resourceTemplates: [] });
	if (rpcMethod === 'prompts/list') return rpcEnvelope(id, { prompts: [] });

	if (rpcMethod === 'tools/call') {
		const requestedName = params?.name;
		// Legacy camelCase aliases resolve to the canonical snake_case names —
		// both forms are accepted forever (TOOL_NAME_ALIASES is the contract).
		const name = resolveToolName(requestedName);
		// Own-property lookup only so "__proto__"/"constructor" can't resolve an
		// inherited member and pass the !handler guard.
		const handler =
			typeof name === 'string' && Object.hasOwn(HANDLERS, name) ? HANDLERS[name] : null;
		if (!handler) {
			return rpcEnvelope(id, null, {
				code: -32601,
				message: `unknown tool: ${requestedName}`,
			});
		}
		const policyGate = await gateCall(POLICY_SERVER, name, params?.arguments || {}, null, ctx.req);
		if (!policyGate.ok) return rpcEnvelope(id, policyGate.result);
		// Auth gate: expensive (vanity grind, long-lived RPC watch) and sensitive
		// (returns a secret key) tools require a bearer or verified x402 payment.
		if (AUTH_REQUIRED_TOOLS.has(name)) {
			const authz = await ctx.ensureGateAuth();
			if (!authz.ok) {
				if (!ctx.batch) {
					ctx.gateDenied = { id, failure: authz.failure };
					return null;
				}
				return gatedAuthFailureEnvelope(ctx.res, id, authz.failure);
			}
			ctx.x402Ctx = authz.x402Ctx;
			// Per-principal ceiling on expensive/gated tools so a single bearer (which
			// pays nothing) or payer can't drive unlimited grind/credit-burning work.
			const gatedRl = await limits.mcpPumpGated(authz.principal || `ip:${clientIp(ctx.req)}`);
			if (!gatedRl.success) {
				if (!ctx.batch) {
					ctx.gateDenied = {
						id,
						failure: {
							kind: 'rate_limited',
							code: -32029,
							message: 'rate limit exceeded for gated tools',
						},
					};
					return null;
				}
				return rpcEnvelope(id, null, {
					code: -32029,
					message: 'rate limit exceeded for gated tools',
				});
			}
			try {
				const data = await handler(params?.arguments || {});
				ctx.gatedSuccess = true;
				ctx.gatedId = id;
				return rpcEnvelope(id, {
					content: [{ type: 'text', text: JSON.stringify(data) }],
					structuredContent: data,
				});
			} catch (err) {
				return rpcEnvelope(id, null, {
					code: err.rpcCode || -32603,
					message: err.message || 'tool error',
				});
			}
		}
		try {
			const data = await handler(params?.arguments || {});
			// Mirror MCP content shape so existing skill clients can unwrap text.
			return rpcEnvelope(id, {
				content: [{ type: 'text', text: JSON.stringify(data) }],
				structuredContent: data,
			});
		} catch (err) {
			return rpcEnvelope(id, null, {
				code: err.rpcCode || -32603,
				message: err.message || 'tool error',
			});
		}
	}

	if (isNotification) return null;
	return rpcEnvelope(id, null, { code: -32601, message: `unknown method: ${rpcMethod}` });
}

export default wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,HEAD,POST,DELETE,OPTIONS', origins: '*' })) return;

	if (req.method === 'GET' || req.method === 'HEAD') return handleSseHandshake(req, res);
	if (req.method === 'DELETE') {
		// Stateless per-request server — nothing to tear down (same contract as
		// api/_mcp/auth.js handleTerminate).
		res.statusCode = 204;
		return res.end();
	}
	if (!method(req, res, ['POST'])) return;

	const rl = await limits.mcpIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	let body;
	try {
		body = await readJson(req);
	} catch {
		return json(res, 400, rpcEnvelope(null, null, { code: -32700, message: 'parse error' }));
	}

	const isBatch = Array.isArray(body);
	const messages = isBatch ? body : [body];
	if (isBatch && messages.length === 0) {
		return json(res, 200, rpcEnvelope(null, null, { code: -32600, message: 'empty batch' }), {
			'mcp-protocol-version': PROTOCOL_VERSION,
		});
	}
	if (messages.length > MAX_BATCH) {
		return json(
			res,
			200,
			rpcEnvelope(null, null, {
				code: -32600,
				message: `batch too large (max ${MAX_BATCH})`,
			}),
			{ 'mcp-protocol-version': PROTOCOL_VERSION },
		);
	}

	// A single X-PAYMENT settles exactly once for the whole request, so a batch
	// carrying more than one gated (paid) tool would run them all for one payment
	// (pay-once-run-many). Reject that up front. Bearer-authed batches are exempt —
	// they don't settle a payment and are bounded by the per-principal limiter.
	if (req.headers['x-payment'] && !extractBearer(req)) {
		const gatedCount = messages.reduce((n, m) => {
			if (m?.method !== 'tools/call') return n;
			const nm = resolveToolName(m?.params?.name);
			return n + (typeof nm === 'string' && AUTH_REQUIRED_TOOLS.has(nm) ? 1 : 0);
		}, 0);
		if (gatedCount > 1) {
			return json(
				res,
				400,
				rpcEnvelope(null, null, {
					code: -32600,
					message:
						'one X-PAYMENT settles a single gated call — send at most one paid tool per request',
				}),
				{ 'mcp-protocol-version': PROTOCOL_VERSION },
			);
		}
	}

	// Replay guard (parity with paidEndpoint): a paid request holds a single-use
	// lock on its signed payment proof across dispatch+settle so a captured/retried
	// X-PAYMENT can't re-run the gated (often on-chain or LLM-backed) tool before
	// the first settle lands. Scoped to genuine paid requests (X-PAYMENT, no
	// bearer) — the same condition as the pay-once-run-many guard above. Released
	// in the finally; the consumed on-chain nonce blocks any replay thereafter.
	let releaseProof = async () => {};
	if (req.headers['x-payment'] && !extractBearer(req)) {
		const guard = await reservePaymentProof('/api/pump-fun-mcp', req.headers['x-payment']);
		if (!guard.ok) {
			return json(
				res,
				409,
				rpcEnvelope(null, null, {
					code: -32402,
					message:
						'a request with this payment is already being processed; retry shortly',
				}),
				{ 'mcp-protocol-version': PROTOCOL_VERSION },
			);
		}
		releaseProof = guard.release;
	}

	try {
		// Per-request dispatch context. Gate credentials resolve at most once.
		let gateAuthPromise = null;
		const ctx = {
			req,
			res,
			batch: isBatch,
			x402Ctx: null,
			gatedSuccess: false,
			gatedId: null,
			gateDenied: null,
			ensureGateAuth() {
				if (!gateAuthPromise) gateAuthPromise = resolveGatedAuth(req);
				return gateAuthPromise;
			},
		};

		const responses = [];
		for (const msg of messages) {
			const envelope = await dispatchRpc(msg, ctx);
			// Single-request gate denial keeps the legacy 401/402 HTTP semantics.
			if (ctx.gateDenied)
				return writeGatedAuthFailure(res, ctx.gateDenied.id, ctx.gateDenied.failure);
			if (envelope !== null) responses.push(envelope);
		}

		// Settle the verified x402 payment AFTER gated work succeeded — atomic from
		// the payer's perspective (verify → work → settle, mirroring /api/mcp): a
		// failed tool never broadcasts the payment, and a successful one is always
		// captured so the gated work can't be delivered free or the same signed
		// payload replayed. One settlement covers the whole request.
		if (ctx.x402Ctx && ctx.gatedSuccess) {
			try {
				const settled = await settlePayment({ verified: ctx.x402Ctx.verified });
				res.setHeader('x-payment-response', encodePaymentResponseHeader(settled));
			} catch (settleErr) {
				return json(
					res,
					402,
					rpcEnvelope(ctx.gatedId, null, {
						code: -32402,
						message: `payment settlement failed: ${settleErr?.message || 'settle error'}`,
						data: build402Body({
							resourceUrl: ctx.x402Ctx.resourceUrl,
							accepts: ctx.x402Ctx.requirements,
							error: settleErr?.message || 'settle error',
						}),
					}),
					{ 'mcp-protocol-version': PROTOCOL_VERSION },
				);
			}
		}

		// All-notification requests owe no body — 202 Accepted per Streamable HTTP.
		if (responses.length === 0) {
			res.statusCode = 202;
			res.setHeader('mcp-protocol-version', PROTOCOL_VERSION);
			return res.end();
		}

		const issuedSessionId = issueSession(res, body);
		const gate = gateAuthPromise ? await gateAuthPromise : null;
		const authSource = gate?.x402Ctx
			? 'x402'
			: gate?.principal?.startsWith('apikey:')
				? 'apikey'
				: gate?.principal
					? 'oauth'
					: null;
		const sent = json(res, 200, isBatch ? responses : responses[0], {
			'mcp-protocol-version': PROTOCOL_VERSION,
		});
		trackMcp({ surface: 'pump-fun-mcp', req, body, responses, auth: { source: authSource }, issuedSessionId });
		return sent;
	} finally {
		await releaseProof();
	}
});