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.

234 KB
Raw Blame
// Consolidated pump.fun API dispatcher.
//
// Routes via Vercel's [action] file param. Single bundle replaces 22 separate
// serverless functions, each of which used to import @solana/web3.js and the
// @pump-fun/* SDKs from scratch.
//
// Action map:
//   balances                 -> handleBalances
//   buy-prep                 -> handleBuyPrep
//   buy-confirm              -> handleBuyConfirm
//   sell-prep                -> handleSellPrep
//   sell-confirm             -> handleSellConfirm
//   launch-prep              -> handleLaunchPrep
//   launch-confirm           -> handleLaunchConfirm
//   launch-agent             -> handleLaunchAgent (server-side signing via agent wallet)
//   agent-wallet             -> handleAgentWallet (resolve agent + Solana wallet info)
//   accept-payment-prep      -> handleAcceptPaymentPrep
//   accept-payment-confirm   -> handleAcceptPaymentConfirm
//   payments-list            -> handlePaymentsList
//   portfolio                -> handlePortfolio
//   by-agent                 -> handleByAgent
//   launches                 -> handleLaunches (public cross-agent launch feed)
//   quote                    -> handleQuote
//   governance-prep          -> handleGovernancePrep
//   withdraw-prep            -> handleWithdrawPrep
//   withdraw-confirm         -> handleWithdrawConfirm
//   strategy-backtest        -> handleStrategyBacktest
//   strategy-close-all       -> handleStrategyCloseAll
//   strategy-run             -> handleStrategyRun (SSE; bypasses wrap())
//   strategy-validate        -> handleStrategyValidate
//   live-stream              -> handleLiveStream  (SSE; bypasses wrap())
//   collect-creator-fee-prep      -> handleCollectCreatorFeePrep
//   distribute-creator-fees-prep  -> handleDistributeCreatorFeesPrep
//                                    (auto-prepends transfer_creator_fees_to_pump_v2
//                                     for graduated coins; ATA-init for non-native
//                                     quotes is handled internally by the SDK)
//   create-fee-sharing-prep       -> handleCreateFeeSharingPrep   (step 1)
//   update-fee-shares-prep        -> handleUpdateFeeSharesPrep    (step 2)
//   fee-info                      -> handleFeeInfo (read-only: claimable creator
//                                    fees, graduation, sharing-config shareholders)
//   resolve-github-shareholder    -> handleResolveGithubShareholder (read-only:
//                                    GitHub @login/id -> the recipient's linked
//                                    Solana payout wallet, or a pump.fun social-fee
//                                    escrow PDA when they haven't joined yet)
//   create-social-fee-pda-prep    -> handleCreateSocialFeePdaPrep (user-signed:
//                                    initialise the pump.fun social-fee escrow that
//                                    a fee-share update then routes a slice into)
//   collect-creator-fee-agent     -> handleCollectCreatorFeeAgent (server-signs
//                                    with the agent custodial wallet)
//   distribute-creator-fees-agent -> handleDistributeCreatorFeesAgent (server-signs)
//   fee-sharing-agent             -> handleFeeSharingAgent (server-signs create +
//                                    update sharing config; delegated fee rewards)

import { validateShareholders } from '../../src/shared/launch-fees.js';
import { z } from 'zod';
import { Keypair, PublicKey, LAMPORTS_PER_SOL } from '@solana/web3.js';
import { sql } from '../_lib/db.js';
import { resolveSocialReward } from '../_lib/github-reward.js';
import { submitProtected } from '../_lib/execution-engine.js';
import { getSessionUser, authenticateBearer, extractBearer, isSameSiteOrigin } from '../_lib/auth.js';
import { assertBearerMaySpend } from '../_lib/spend-scope.js';
import { cors, json, method, readJson, wrap, error, rateLimited, respondError } from '../_lib/http.js';
import { putObject, publicUrl as r2PublicUrl, thumbnailUrl } from '../_lib/r2.js';
import { env } from '../_lib/env.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { resolveOrCreateAgentForAvatar as resolveLaunchAgentId } from '../_lib/agent-identity.js';
import { parse, isUuid } from '../_lib/validate.js';
import { queryAgentLaunches } from '../_lib/pump-agent-launches.js';
import { markPlanLaunched } from '../_lib/agent-token-plan.js';
import { randomToken } from '../_lib/crypto.js';
import { publishFeedEvent } from '../_lib/feed.js';
import { recordDailyActivity } from '../_lib/streaks.js';
import { recordQuestTrade } from '../_lib/trading-quests.js';
import { recordCopyPathStep } from '../_lib/copy-path.js';
import { normalizeGatewayURL } from '../../src/ipfs.js';
import { buildTokenMetadata } from '../_lib/three-brand.js';
import {
	buildPlatformFeeInstructions,
	effectivePumpFeeBps,
	pumpFeeRecipient,
	pumpLaunchFeeBps,
	txPaidPlatformFee,
} from '../_lib/pump-platform-fee.js';
import {
	buildLaunchTransaction,
	countPrefixThatFits,
	getPumpLookupTables,
	pumpAgentBuybackAvailable,
	transactionV1Status,
} from '../_lib/pump-launch-tx.js';
import {
	creatorExtraQuoteMints,
	creatorFeeSweepInstructions,
	readCreatorFeeBuckets,
	sumByQuote,
	unsweptCreatorFees,
} from '../_lib/pump-creator-fees.js';
import { pinToIPFS, ipfsPinningConfigured } from '../_lib/ipfs-pin.js';
import { THREE_WS_VANITY, hasThreeWsMark } from '../../src/solana/vanity/brand.js';
import { grindVanityNode, GrindExhaustedError } from '../../src/solana/vanity/grinder-node.js';
import { logger } from '../_lib/usage.js';
import { cacheGet, cacheSet } from '../_lib/cache.js';
import { pumpFetchJson } from '../_lib/pump-feed-fetch.js';
import { getCurveView } from '../_lib/pump-curve-view.js';
import { collectFeeAgentSchema } from '../_lib/pump-fee-schemas.js';
import { isRpcOutageError, staleEnvelope } from '../_lib/rpc-degrade.js';
import { getLaunchEconomics, describeFeeSplit } from '../_lib/launch-economics.js';
import {
	GaslessError,
	gaslessEligibility,
	prepareGaslessCurveLaunch,
	recordSponsorshipPrepared,
	recordSponsorshipLaunched,
	verifyGaslessTransaction,
} from '../_lib/launch-sponsor.js';

const log = logger('pump.launch');
import {
	getConnection,
	getPumpSdk,
	getPumpSdkV2,
	getPumpAgent,
	getPumpAgentOffline,
	getAmmPoolState,
	buildUnsignedTxBase64,
	verifySignature,
	txInvokesPumpProgram,
	txInvokesAgentPaymentsProgram,
	solanaPubkey,
} from '../_lib/pump.js';

// Wrapped SOL mint: required as the quoteMint for SOL-paired V2 instructions
const WSOL_MINT = 'So11111111111111111111111111111111111111112';
import { solanaConnection, loadAgentForSigning } from '../_lib/agent-pumpfun.js';
import { connectPumpFunFeed } from '../_lib/pumpfun-ws-feed.js';
import { makeRuntime } from '../_lib/skill-runtime.js';
import { loadWallet } from '../_lib/solana-wallet.js';
import { enforceSpendLimit, SpendLimitError } from '../_lib/agent-trade-guards.js';
import { solUsdPrice } from '../_lib/avatar-wallet.js';
import { requireRealFundsAgreement, currentSignatureFor } from '../_lib/real-funds-agreement.js';
import {
	createStrategySpendGuard,
	reserveSpend,
	finalizeSpend,
	releaseSpend,
} from '../_lib/agent-spend-policy.js';
import { SOLANA_USDC_MINT, SOLANA_USDC_MINT_DEVNET, toUsdcAtomics } from '../payments/_config.js';
import { fetchUpstream } from '../_lib/upstream-fetch.js';
import {
	classifyLaunchQuote,
	usdcMintFor,
	tradeQuoteColumns,
	walletQuoteDeltaAtomics,
} from '../_lib/pump-quote.js';
import {
	slippagePercentFromBps,
	resolveTokenProgramForMintOwner,
} from '../_lib/pump-trade-args.js';

const TOKEN_PROGRAM_ID = new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA');

const RPC = {
	mainnet: process.env.SOLANA_RPC_URL || 'https://api.mainnet-beta.solana.com',
	devnet: process.env.SOLANA_RPC_URL_DEVNET || 'https://api.devnet.solana.com',
};

/**
 * Read and clamp a `?limit=` query param.
 *
 * `Number('abc')` is NaN, and NaN survives every Math.min/Math.max clamp, so the
 * naive `Math.min(Math.max(1, Number(param || 50)), max)` shape forwards a NaN
 * straight into SQL `limit`, into an upstream query string, and into the feed
 * slice. A single typo'd limit therefore answered 200 with an empty feed rather
 * than the default page. Anything non-numeric falls back to `fallback`; a real
 * number is floored and clamped into [1, max].
 */
function readLimit(url, fallback, max) {
	const param = url.searchParams.get('limit');
	const raw = param == null || param === '' ? NaN : Number(param);
	const n = Number.isFinite(raw) ? Math.floor(raw) : fallback;
	return Math.min(Math.max(1, n), max);
}

// `spend: true` marks a handler that signs with an agent's custodial key; a
// bearer must then hold the scope for that kind of movement (spend-scope.js):
// `kind: 'trade'` for a swap or a position, where value stays in the wallet.
async function resolveAuth(req, { spend = false, kind = 'spend' } = {}) {
	const session = await getSessionUser(req);
	if (session) {
		// CSRF defense-in-depth for the cookie path: these handlers sign real
		// spends with platform-held custodial keys, so a cross-site POST riding
		// the session cookie must never reach them. Reads stay open; bearer
		// callers (agent keys, workers) are exempt since the token itself is
		// the proof of intent.
		const isRead = ['GET', 'HEAD', 'OPTIONS'].includes(String(req.method || '').toUpperCase());
		if (!isRead && !isSameSiteOrigin(req)) {
			throw Object.assign(new Error('cross-site request blocked'), { status: 403, code: 'forbidden' });
		}
		return { userId: session.id };
	}
	const bearer = await authenticateBearer(extractBearer(req));
	if (!bearer) return null;
	if (spend) assertBearerMaySpend(bearer, req, { kind });
	return { userId: bearer.userId };
}

/**
 * The account behind a non-custodial trade prep or confirm. These four
 * handlers never touch a platform key: prep returns an unsigned transaction
 * for the caller's own wallet and confirm only records a trade it has verified
 * on chain. A bearer caller (an API key, or the trading tools over MCP and
 * /api/v1/trading) is therefore as safe as the cookie session they always
 * accepted, and the session path is unchanged.
 * @returns {Promise<{ id: string } | null>}
 */
async function walletTradeUser(req) {
	const session = await getSessionUser(req);
	if (session) return session;
	const bearer = await authenticateBearer(extractBearer(req));
	return bearer ? { id: bearer.userId } : null;
}

/**
 * Session lookup for the handlers that sign and BROADCAST with an agent's
 * custodial keypair server-side (launch-agent, the *-agent fee cranks). Those
 * need nothing from the caller but a cookie, so a cross-site POST alone was
 * enough to mint a coin or sweep fees: the exact threat resolveAuth() guards
 * against, which these paths were not routed through. Same rule as resolveAuth:
 * the cookie path must prove same-site intent, reads stay open.
 *
 * Returns the session user, or null after writing the 401/403 response.
 */
async function requireSessionUser(req, res) {
	const user = await getSessionUser(req);
	if (!user) {
		error(res, 401, 'unauthorized', 'sign in required');
		return null;
	}
	const isRead = ['GET', 'HEAD', 'OPTIONS'].includes(String(req.method || '').toUpperCase());
	if (!isRead && !isSameSiteOrigin(req)) {
		error(res, 403, 'forbidden', 'cross-site request blocked');
		return null;
	}
	return user;
}

const wrapped = wrap(async (req, res) => {
	const action = req.query?.action;
	switch (action) {
		case 'balances':
			return handleBalances(req, res);
		case 'buy-prep':
			return handleBuyPrep(req, res);
		case 'buy-confirm':
			return handleBuyConfirm(req, res);
		case 'sell-prep':
			return handleSellPrep(req, res);
		case 'sell-confirm':
			return handleSellConfirm(req, res);
		case 'build-metadata':
			return handleBuildMetadata(req, res);
		case 'launch-prep':
			return handleLaunchPrep(req, res);
		case 'launch-confirm':
			return handleLaunchConfirm(req, res);
		case 'launch-agent':
			return handleLaunchAgent(req, res);
		case 'agent-wallet':
			return handleAgentWallet(req, res);
		case 'accept-payment-prep':
			return handleAcceptPaymentPrep(req, res);
		case 'accept-payment-confirm':
			return handleAcceptPaymentConfirm(req, res);
		case 'payments-list':
			return handlePaymentsList(req, res);
		case 'portfolio':
			return handlePortfolio(req, res);
		case 'by-agent':
			return handleByAgent(req, res);
		case 'launches':
			return handleLaunches(req, res);
		case 'quote':
			return handleQuote(req, res);
		case 'governance-prep':
			return handleGovernancePrep(req, res);
		case 'withdraw-prep':
			return handleWithdrawPrep(req, res);
		case 'withdraw-confirm':
			return handleWithdrawConfirm(req, res);
		case 'strategy-backtest':
			return handleStrategyBacktest(req, res);
		case 'strategy-close-all':
			return handleStrategyCloseAll(req, res);
		case 'strategy-validate':
			return handleStrategyValidate(req, res);
		case 'channel-feed':
			return handleChannelFeed(req, res);
		case 'deliver-telegram':
			return handleDeliverTelegram(req, res);
		case 'first-claims':
			return handleFirstClaims(req, res);
		case 'recent-graduations':
			return handleRecentGraduations(req, res);
		case 'trending':
			return handleTrending(req, res);
		case 'coin':
			return handleCoin(req, res);
		case 'coin-trades':
			return handleCoinTrades(req, res);
		case 'search':
			return handleSearch(req, res);
		case 'collect-creator-fee-prep':
			return handleCollectCreatorFeePrep(req, res);
		case 'launch-config':
			return handleLaunchConfig(req, res);
		case 'my-coins':
			return handleMyCoins(req, res);
		case 'distribute-creator-fees-prep':
			return handleDistributeCreatorFeesPrep(req, res);
		case 'create-fee-sharing-prep':
			return handleCreateFeeSharingPrep(req, res);
		case 'update-fee-shares-prep':
			return handleUpdateFeeSharesPrep(req, res);
		case 'fee-info':
			return handleFeeInfo(req, res);
		case 'resolve-github-shareholder':
			return handleResolveGithubShareholder(req, res);
		case 'create-social-fee-pda-prep':
			return handleCreateSocialFeePdaPrep(req, res);
		case 'github-resolve':
			return handleGithubResolve(req, res);
		case 'social-fee-claim-status':
			return handleSocialFeeClaimStatus(req, res);
		case 'collect-creator-fee-agent':
			return handleCollectCreatorFeeAgent(req, res);
		case 'distribute-creator-fees-agent':
			return handleDistributeCreatorFeesAgent(req, res);
		case 'fee-sharing-agent':
			return handleFeeSharingAgent(req, res);
		default:
			return error(res, 404, 'not_found', 'unknown pump action');
	}
});

// SSE actions bypass wrap()'s JSON-error fallback: they manage their own response writes.
export default async function dispatcher(req, res) {
	if (req.query?.action === 'strategy-run') return handleStrategyRun(req, res);
	if (req.query?.action === 'vanity-keygen') return handleVanityKeygen(req, res);
	if (req.query?.action === 'live-stream') return handleLiveStream(req, res);
	// `trades-stream` is served by the dedicated api/pump/trades-stream.js file
	// (static routes win over [action]); no dispatch needed here.
	return wrapped(req, res);
}

// ── balances ───────────────────────────────────────────────────────────────

async function handleBalances(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;

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

	const url = new URL(req.url, `http://${req.headers.host}`);
	const mintStr = url.searchParams.get('mint');
	const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
	const currencyArg = url.searchParams.get('currency');

	const mint = solanaPubkey(mintStr);
	if (!mint) return error(res, 400, 'validation_error', 'invalid mint');

	const currencyStr =
		currencyArg || (network === 'devnet' ? SOLANA_USDC_MINT_DEVNET : SOLANA_USDC_MINT);
	const currency = solanaPubkey(currencyStr);
	if (!currency) return error(res, 400, 'validation_error', 'invalid currency');

	try {
		const { agent, agentPda } = await getPumpAgent({ network, mint });
		const balances = await agent.getBalances(currency);
		const fmt = (v) =>
			v && {
				address: v.address?.toString?.() ?? String(v.address),
				balance: v.balance?.toString?.() ?? String(v.balance ?? 0),
			};
		return json(res, 200, {
			mint: mintStr,
			network,
			currency: currencyStr,
			agent_pda: agentPda?.toString?.() ?? null,
			balances: {
				payment: fmt(balances.paymentVault),
				buyback: fmt(balances.buybackVault),
				withdraw: fmt(balances.withdrawVault),
			},
		});
	} catch (err) {
		// Most common: agent not yet bound to mint → PDA missing. Sanitize the 5xx :
		// web3.js network errors embed the keyed Helius RPC URL in err.message.
		return respondError(res, 502, 'pump_agent_error', err);
	}
}

// ── buy-prep ───────────────────────────────────────────────────────────────

const buyPrepSchema = z
	.object({
		mint: z.string().min(32).max(44),
		network: z.enum(['mainnet', 'devnet']).default('mainnet'),
		// For SOL-paired coins pass `sol`; for USDC-paired coins pass `usdc_amount`.
		// Exactly one must be provided: validation enforced below.
		sol: z.number().positive().max(50).optional(),
		usdc_amount: z.number().positive().max(1_000_000).optional(),
		// Optional explicit quote mint. When omitted the server auto-detects from
		// the on-chain bonding curve (quote_mint field added in pump.fun V2).
		quote_mint: z.string().min(32).max(44).optional(),
		slippage_bps: z.number().int().min(0).max(5000).default(100),
		wallet_address: z.string().min(32).max(44),
	})
	.refine((v) => v.sol != null || v.usdc_amount != null, {
		message: 'sol or usdc_amount required',
		path: ['sol'],
	});

async function handleBuyPrep(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await walletTradeUser(req);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

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

	const body = parse(buyPrepSchema, await readJson(req));
	const userPk = solanaPubkey(body.wallet_address);
	const mintPk = solanaPubkey(body.mint);
	if (!userPk || !mintPk) return error(res, 400, 'validation_error', 'invalid pubkeys');

	try {
		const { sdk, BN, web3, connection } = await getPumpSdk({ network: body.network });
		const { isLegacyQuoteMint, getBuyTokenAmountFromSolAmount } =
			await import('@pump-fun/pump-sdk');
		// @pump-fun SDK builders take slippage as a PERCENT (1 = 1%), not a
		// fraction: see api/_lib/pump-trade-args.js for the unit derivation.
		const slippagePct = slippagePercentFromBps(body.slippage_bps);

		// The base mint's owner decides base_token_program: create_v2 coins are
		// Token-2022, legacy coins are SPL Token (docs/instructions/BUY.md #4).
		const mintInfo = await connection.getAccountInfo(mintPk);
		if (!mintInfo)
			return error(
				res,
				404,
				'mint_not_found',
				`mint ${body.mint} not found on ${body.network}`,
			);
		const baseTokenProgram = resolveTokenProgramForMintOwner(mintInfo.owner);

		// Fetch bonding curve state: also gives us the on-chain quote_mint.
		// Pass the real token program so the user-ATA existence check resolves
		// the correct (possibly Token-2022) associated account.
		let buyState = null;
		try {
			if (sdk.fetchBuyState)
				buyState = await sdk.fetchBuyState(mintPk, userPk, baseTokenProgram);
		} catch {
			buyState = null;
		}

		// Resolve quoteMint: explicit override > on-chain curve > WSOL fallback.
		let quoteMintPk = body.quote_mint
			? solanaPubkey(body.quote_mint)
			: (buyState?.bondingCurve?.quoteMint ?? solanaPubkey(WSOL_MINT));
		if (!quoteMintPk) quoteMintPk = solanaPubkey(WSOL_MINT);

		const isUsdcQuote = !isLegacyQuoteMint(quoteMintPk);
		// On-chain SOL curves store quoteMint as PublicKey.default (all-zeros).
		// Surface wrapped SOL in the API response instead of the zero pubkey so
		// clients see a real, usable mint for every coin type.
		const quoteMintDisplay = isUsdcQuote ? quoteMintPk.toString() : WSOL_MINT;

		// quote_token_program must match the quote mint's owner (wSOL/USDC are
		// SPL Token today; read it from chain so a future quote can't break us).
		let quoteTokenProgram = TOKEN_PROGRAM_ID;
		if (isUsdcQuote) {
			const quoteInfo = await connection.getAccountInfo(quoteMintPk);
			if (!quoteInfo)
				return error(
					res,
					404,
					'quote_mint_not_found',
					`quote mint ${quoteMintPk.toBase58()} not found`,
				);
			quoteTokenProgram = resolveTokenProgramForMintOwner(quoteInfo.owner);
		}

		// Validate the quote-asset amount up front for both routes.
		if (isUsdcQuote && body.usdc_amount == null)
			return error(res, 400, 'validation_error', 'usdc_amount required for USDC-paired coin');
		if (!isUsdcQuote && body.sol == null)
			return error(res, 400, 'validation_error', 'sol required for SOL-paired coin');
		const quoteAtomics = isUsdcQuote
			? new BN(Math.round(body.usdc_amount * 1_000_000))
			: new BN(Math.floor(body.sol * web3.LAMPORTS_PER_SOL));

		if (buyState && buyState.bondingCurve && !buyState.bondingCurve.complete) {
			// Unified v2 interface for every coin type (SOL- and USDC-paired,
			// SPL and Token-2022 base mints) per the upstream migration guidance :
			// docs/pumpfun-program/UPSTREAM-buy-sell-v2-announcement.md.
			const [global, feeConfig] = await Promise.all([
				sdk.fetchGlobal(),
				sdk.fetchFeeConfig().catch(() => null),
			]);
			// buy_v2's `amount` arg is the base-token quantity to buy and must be
			// > 0 (docs/instructions/BUY.md): derive it from the quote input.
			const tokenAmount = getBuyTokenAmountFromSolAmount({
				global,
				feeConfig,
				mintSupply: buyState.bondingCurve.tokenTotalSupply,
				bondingCurve: buyState.bondingCurve,
				amount: quoteAtomics,
				quoteMint: quoteMintPk,
			});
			if (!tokenAmount.gt(new BN(0)))
				return error(
					res,
					400,
					'amount_too_small',
					'quote amount too small to buy any tokens',
				);
			const ixs = await sdk.buyV2Instructions({
				global,
				bondingCurveAccountInfo: buyState.bondingCurveAccountInfo,
				bondingCurve: buyState.bondingCurve,
				associatedUserAccountInfo: buyState.associatedUserAccountInfo,
				mint: mintPk,
				user: userPk,
				amount: tokenAmount,
				quoteAmount: quoteAtomics,
				slippage: slippagePct,
				tokenProgram: baseTokenProgram,
				quoteTokenProgram,
			});
			const __platformFee = await buildPlatformFeeInstructions({
				network: body.network, payer: userPk, isUsdc: isUsdcQuote,
				quoteMintPk, quoteTokenProgram, grossAtomics: BigInt(quoteAtomics.toString()), basis: 'buy',
			});
			if (__platformFee) ixs.push(...__platformFee.instructions);
			const tx_base64 = await buildUnsignedTxBase64({
				network: body.network,
				payer: userPk,
				instructions: ixs,
			});
			return json(res, 201, {
				route: 'bonding_curve',
				mint: body.mint,
				network: body.network,
				quote_mint: quoteMintDisplay,
				...(isUsdcQuote ? { usdc_in: body.usdc_amount } : { sol_in: body.sol }),
				expected_tokens_out: tokenAmount.toString(),
				slippage_bps: body.slippage_bps,
				platform_fee: __platformFee ? __platformFee.disclosure : null,
				tx_base64,
			});
		}

		// AMM (post-graduation)
		const amm = await getAmmPoolState({
			network: body.network,
			mint: mintPk,
			quoteMint: isUsdcQuote ? quoteMintPk : null,
		});
		const ammMod = await import('@pump-fun/pump-swap-sdk');
		const offline = new ammMod.PumpAmmSdk();
		const onlineAmm = new ammMod.OnlinePumpAmmSdk(getConnection({ network: body.network }));
		const swapState = await onlineAmm.swapSolanaState(amm.poolKey, userPk);

		const ixs = await offline.buyQuoteInput(swapState, quoteAtomics, slippagePct);
		const __platformFee = await buildPlatformFeeInstructions({
			network: body.network, payer: userPk, isUsdc: isUsdcQuote,
			quoteMintPk, quoteTokenProgram, grossAtomics: BigInt(quoteAtomics.toString()), basis: 'buy',
		});
		if (__platformFee) ixs.push(...__platformFee.instructions);
		const tx_base64 = await buildUnsignedTxBase64({
			network: body.network,
			payer: userPk,
			instructions: ixs,
		});
		return json(res, 201, {
			route: 'amm',
			pool: amm.poolKey.toString(),
			mint: body.mint,
			network: body.network,
			quote_mint: quoteMintDisplay,
			...(isUsdcQuote ? { usdc_in: body.usdc_amount } : { sol_in: body.sol }),
			slippage_bps: body.slippage_bps,
			platform_fee: __platformFee ? __platformFee.disclosure : null,
			tx_base64,
		});
	} catch (e) {
		return respondError(res, e.status || 502, e.code || 'pump_sdk_error', e);
	}
}

// ── buy-confirm ────────────────────────────────────────────────────────────

const buyConfirmSchema = z
	.object({
		mint: z.string().min(32).max(44),
		network: z.enum(['mainnet', 'devnet']).default('mainnet'),
		tx_signature: z.string().min(80).max(100),
		wallet_address: z.string().min(32).max(44),
		// SOL-paired coins record `sol`; USDC-paired (v2) coins record `usdc_amount`.
		// Both optional so either quote asset can confirm; the tx itself is the
		// source of truth (verified on-chain below), these only label the trade row.
		sol: z.number().nonnegative().max(50).optional(),
		usdc_amount: z.number().nonnegative().max(1_000_000).optional(),
		route: z.enum(['bonding_curve', 'amm']),
		slippage_bps: z.number().int().min(0).max(5000).optional(),
		// 'fork' when the trade panel was opened by a Fork (src/fork-trade.js). Only
		// labels the verified trade for the daily fork quest; it gates nothing.
		origin: z.enum(['fork']).optional(),
	})
	.refine((v) => (v.sol ?? 0) > 0 || (v.usdc_amount ?? 0) > 0, {
		message: 'sol or usdc_amount required',
		path: ['sol'],
	});

async function handleBuyConfirm(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await walletTradeUser(req);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

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

	const body = parse(buyConfirmSchema, await readJson(req));

	const [mintRow] = await sql`
		select id, quote_mint from pump_agent_mints where mint=${body.mint} and network=${body.network} limit 1
	`;
	const mintId = mintRow?.id ?? null;

	let tx;
	try {
		tx = await verifySignature({ network: body.network, signature: body.tx_signature });
	} catch (e) {
		return error(res, e.status || 422, e.code || 'tx_failed', e.message);
	}
	const accountKeys = tx.transaction.message.accountKeys.map((k) => (k.pubkey || k).toString());
	if (!accountKeys.includes(body.mint))
		return error(res, 422, 'mint_not_in_tx', 'mint not in tx');
	if (!accountKeys.includes(body.wallet_address))
		return error(res, 422, 'wallet_not_in_tx', 'wallet not in tx');

	if (mintId) {
		// Resolve the quote asset authoritatively from the coin's recorded pairing
		// mint (NULL = SOL-paired), so a USDC buy never lands in the lamports
		// column. `sol_amount` stays a SOL-only lamports field for legacy readers;
		// `quote_amount` carries the spend in whichever quote's atomic units.
		const { quote_mint, quote_symbol } = tradeQuoteColumns({
			quoteMint: mintRow?.quote_mint,
			network: body.network,
		});
		const lamports =
			quote_symbol === 'SOL' && body.sol > 0
				? BigInt(Math.floor(body.sol * 1_000_000_000)).toString()
				: null;
		const quoteAmount =
			quote_symbol === 'SOL'
				? lamports
				: body.usdc_amount > 0
					? String(Math.round(body.usdc_amount * 1_000_000))
					: walletQuoteDeltaAtomics({
							tx,
							wallet: body.wallet_address,
							quoteSymbol: quote_symbol,
							quoteMint: quote_mint,
						});
		await sql`
			insert into pump_agent_trades
				(mint_id, user_id, wallet, direction, route, sol_amount,
				 quote_mint, quote_symbol, quote_amount, slippage_bps, tx_signature, network)
			values
				(${mintId}, ${user.id}, ${body.wallet_address}, 'buy', ${body.route},
				 ${lamports}, ${quote_mint}, ${quote_symbol}, ${quoteAmount},
				 ${body.slippage_bps ?? null}, ${body.tx_signature}, ${body.network})
			on conflict (tx_signature, network) do nothing
		`;
		// A confirmed on-chain trade is the most real thing a user does here, and
		// the cross-surface streak counted logins, forges, worlds and walks but not
		// this. Fire-and-forget and idempotent per UTC day, exactly like every other
		// call site: it can never delay or fail the buy that earned it.
		recordDailyActivity(user.id).catch(() => {});
	} else {
		// A coin launched elsewhere has no pump_agent_trades row, so this verified
		// buy is the proof of step 3 of the first-copy path (api/_lib/copy-path.js).
		recordCopyPathStep(user.id, 'trade', { signature: body.tx_signature }).catch(() => {});
	}

	// Daily trading quests (api/_lib/trading-quests.js) count every verified trade,
	// on any coin. Fire-and-forget: a quest record can never delay or fail the buy.
	recordQuestTrade({
		userId: user.id,
		signature: body.tx_signature,
		network: body.network,
		wallet: body.wallet_address,
		origin: body.origin ?? null,
		direction: 'buy',
		mint: body.mint,
	}).catch(() => {});

	// Surface the buy on the site-wide live activity ticker. The tx is already
	// verified on-chain above, so this is a real, confirmed purchase. Fire-and-
	// forget: never let the delight layer delay or fail the buy response.
	publishFeedEvent({
		type: 'coin-buy',
		ts: Date.now(),
		actor: shortAddr(body.wallet_address),
		mint: body.mint,
		...(body.sol && body.sol > 0 ? { sol: body.sol } : {}),
		...(body.usdc_amount && body.usdc_amount > 0 ? { usdc: body.usdc_amount } : {}),
		network: body.network,
	}).catch(() => {});

	return json(res, 200, {
		ok: true,
		tracked: !!mintId,
		mint: body.mint,
		network: body.network,
		tx_signature: body.tx_signature,
	});
}

// Truncate a base58 address for public display: "AbCd…WxYz". The feed is world-
// readable, so we only ever surface the head/tail, never the full key.
function shortAddr(addr) {
	const s = String(addr || '');
	return s.length > 10 ? `${s.slice(0, 4)}…${s.slice(-4)}` : s;
}

// ── sell-prep ──────────────────────────────────────────────────────────────

const sellPrepSchema = z.object({
	mint: z.string().min(32).max(44),
	network: z.enum(['mainnet', 'devnet']).default('mainnet'),
	tokens: z.string().regex(/^\d+$/, 'tokens must be a base-units integer string'),
	slippage_bps: z.number().int().min(0).max(5000).default(100),
	wallet_address: z.string().min(32).max(44),
	// Optional: auto-detected from on-chain bonding curve when omitted.
	quote_mint: z.string().min(32).max(44).optional(),
});

async function handleSellPrep(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await walletTradeUser(req);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

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

	const body = parse(sellPrepSchema, await readJson(req));
	const userPk = solanaPubkey(body.wallet_address);
	const mintPk = solanaPubkey(body.mint);
	if (!userPk || !mintPk) return error(res, 400, 'validation_error', 'invalid pubkeys');

	try {
		const { sdk, BN, connection } = await getPumpSdk({ network: body.network });
		const { isLegacyQuoteMint, getSellSolAmountFromTokenAmount } =
			await import('@pump-fun/pump-sdk');
		const tokens = new BN(body.tokens);
		// SDK builders take slippage as a PERCENT: see api/_lib/pump-trade-args.js.
		const slippagePct = slippagePercentFromBps(body.slippage_bps);

		// base_token_program must match the mint owner (Token-2022 for create_v2
		// coins, SPL for legacy): docs/instructions/SELL.md #4.
		const mintInfo = await connection.getAccountInfo(mintPk);
		if (!mintInfo)
			return error(
				res,
				404,
				'mint_not_found',
				`mint ${body.mint} not found on ${body.network}`,
			);
		const baseTokenProgram = resolveTokenProgramForMintOwner(mintInfo.owner);

		let sellState = null;
		try {
			if (sdk.fetchSellState)
				sellState = await sdk.fetchSellState(mintPk, userPk, baseTokenProgram);
		} catch {
			sellState = null;
		}

		// Resolve quoteMint from explicit override > on-chain curve > WSOL fallback.
		let quoteMintPk = body.quote_mint
			? solanaPubkey(body.quote_mint)
			: (sellState?.bondingCurve?.quoteMint ?? solanaPubkey(WSOL_MINT));
		if (!quoteMintPk) quoteMintPk = solanaPubkey(WSOL_MINT);

		const isUsdcQuote = !isLegacyQuoteMint(quoteMintPk);
		// SOL curves store quoteMint as PublicKey.default: surface wrapped SOL.
		const quoteMintDisplay = isUsdcQuote ? quoteMintPk.toString() : WSOL_MINT;

		// quote_token_program must match the quote mint's owner.
		let quoteTokenProgram = TOKEN_PROGRAM_ID;
		if (isUsdcQuote) {
			const quoteInfo = await connection.getAccountInfo(quoteMintPk);
			if (!quoteInfo)
				return error(
					res,
					404,
					'quote_mint_not_found',
					`quote mint ${quoteMintPk.toBase58()} not found`,
				);
			quoteTokenProgram = resolveTokenProgramForMintOwner(quoteInfo.owner);
		}

		if (sellState && sellState.bondingCurve && !sellState.bondingCurve.complete) {
			// Unified v2 sell for every coin type. sell_v2 reads the fee-recipient
			// pool from the curve's mayhem flag inside the SDK builder, and the
			// expected quote output below gives the program a real min_sol_output
			// floor (expected minus slippage) instead of 0.
			const [global, feeConfig] = await Promise.all([
				sdk.fetchGlobal(),
				sdk.fetchFeeConfig().catch(() => null),
			]);
			const expectedQuoteOut = getSellSolAmountFromTokenAmount({
				global,
				feeConfig,
				mintSupply: sellState.bondingCurve.tokenTotalSupply,
				bondingCurve: sellState.bondingCurve,
				amount: tokens,
			});
			const ixs = [];
			if (isUsdcQuote) {
				// sell_v2 pays proceeds into the seller's quote ATA, which the
				// program does NOT init (SELL.md #16): create it idempotently.
				const spl = await import('@solana/spl-token');
				const userQuoteAta = spl.getAssociatedTokenAddressSync(
					quoteMintPk,
					userPk,
					true,
					quoteTokenProgram,
				);
				ixs.push(
					spl.createAssociatedTokenAccountIdempotentInstruction(
						userPk,
						userQuoteAta,
						userPk,
						quoteMintPk,
						quoteTokenProgram,
					),
				);
			}
			ixs.push(
				...(await sdk.sellV2Instructions({
					global,
					bondingCurveAccountInfo: sellState.bondingCurveAccountInfo,
					bondingCurve: sellState.bondingCurve,
					mint: mintPk,
					user: userPk,
					amount: tokens,
					quoteAmount: expectedQuoteOut,
					slippage: slippagePct,
					tokenProgram: baseTokenProgram,
					quoteTokenProgram,
				})),
			);
			const __platformFee = await buildPlatformFeeInstructions({
				network: body.network, payer: userPk, isUsdc: isUsdcQuote,
				quoteMintPk, quoteTokenProgram, grossAtomics: BigInt(expectedQuoteOut.toString()), basis: 'sell',
			});
			if (__platformFee) ixs.push(...__platformFee.instructions);
			const tx_base64 = await buildUnsignedTxBase64({
				network: body.network,
				payer: userPk,
				instructions: ixs,
			});
			return json(res, 201, {
				route: 'bonding_curve',
				mint: body.mint,
				network: body.network,
				quote_mint: quoteMintDisplay,
				tokens_in: body.tokens,
				...(isUsdcQuote
					? { expected_usdc_out: Number(expectedQuoteOut.toString()) / 1_000_000 }
					: { expected_sol_out: Number(expectedQuoteOut.toString()) / 1_000_000_000 }),
				slippage_bps: body.slippage_bps,
				platform_fee: __platformFee ? __platformFee.disclosure : null,
				tx_base64,
			});
		}

		const amm = await getAmmPoolState({
			network: body.network,
			mint: mintPk,
			quoteMint: isUsdcQuote ? quoteMintPk : null,
		});
		const ammMod = await import('@pump-fun/pump-swap-sdk');
		const offline = new ammMod.PumpAmmSdk();
		const onlineAmm = new ammMod.OnlinePumpAmmSdk(getConnection({ network: body.network }));
		const swapState = await onlineAmm.swapSolanaState(amm.poolKey, userPk);
		const ixs = await offline.sellBaseInput(swapState, tokens, slippagePct);
		// Expected proceeds (uiQuote) is the fee basis for an AMM sell. Best-effort:
		// if the low-level quote can't be derived we skip the fee, never the sell.
		let __ammSellGross = 0n;
		try {
			const { uiQuote } = ammMod.sellBaseInput({
				base: tokens, slippage: slippagePct,
				baseReserve: swapState.poolBaseAmount, quoteReserve: swapState.poolQuoteAmount,
				virtualQuoteReserves: swapState.pool.virtualQuoteReserves,
				baseMintAccount: swapState.baseMintAccount, baseMint: swapState.baseMint,
				quoteMint: swapState.pool.quoteMint, isMayhemMode: swapState.pool.isMayhemMode,
				creatorFeeBps: swapState.pool.creatorFeeBps,
				coinCreator: swapState.pool.coinCreator, creator: swapState.pool.creator,
				feeConfig: swapState.feeConfig, globalConfig: swapState.globalConfig,
			});
			__ammSellGross = BigInt(uiQuote.toString());
		} catch { /* fee basis unavailable */ }
		const __platformFee = await buildPlatformFeeInstructions({
			network: body.network, payer: userPk, isUsdc: isUsdcQuote,
			quoteMintPk, quoteTokenProgram, grossAtomics: __ammSellGross, basis: 'sell',
		});
		if (__platformFee) ixs.push(...__platformFee.instructions);
		const tx_base64 = await buildUnsignedTxBase64({
			network: body.network,
			payer: userPk,
			instructions: ixs,
		});
		return json(res, 201, {
			route: 'amm',
			pool: amm.poolKey.toString(),
			mint: body.mint,
			network: body.network,
			quote_mint: quoteMintDisplay,
			tokens_in: body.tokens,
			slippage_bps: body.slippage_bps,
			platform_fee: __platformFee ? __platformFee.disclosure : null,
			tx_base64,
		});
	} catch (e) {
		return respondError(res, e.status || 502, e.code || 'pump_sdk_error', e);
	}
}

// ── sell-confirm ───────────────────────────────────────────────────────────

const sellConfirmSchema = z.object({
	mint: z.string().min(32).max(44),
	network: z.enum(['mainnet', 'devnet']).default('mainnet'),
	tx_signature: z.string().min(80).max(100),
	wallet_address: z.string().min(32).max(44),
	tokens: z.string().regex(/^\d+$/),
	route: z.enum(['bonding_curve', 'amm']),
	slippage_bps: z.number().int().min(0).max(5000).optional(),
});

async function handleSellConfirm(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await walletTradeUser(req);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

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

	const body = parse(sellConfirmSchema, await readJson(req));

	const [mintRow] = await sql`
		select id, quote_mint from pump_agent_mints where mint=${body.mint} and network=${body.network} limit 1
	`;
	const mintId = mintRow?.id ?? null;

	let tx;
	try {
		tx = await verifySignature({ network: body.network, signature: body.tx_signature });
	} catch (e) {
		return error(res, e.status || 422, e.code || 'tx_failed', e.message);
	}
	const accountKeys = tx.transaction.message.accountKeys.map((k) => (k.pubkey || k).toString());
	if (!accountKeys.includes(body.mint))
		return error(res, 422, 'mint_not_in_tx', 'mint not in tx');
	if (!accountKeys.includes(body.wallet_address))
		return error(res, 422, 'wallet_not_in_tx', 'wallet not in tx');

	if (mintId) {
		// The sell-confirm payload only carries the token quantity, so derive the
		// proceeds (quote received) from the verified tx's on-chain balance delta
		// rather than trusting client input: real settled amount, not an estimate.
		const { quote_mint, quote_symbol } = tradeQuoteColumns({
			quoteMint: mintRow?.quote_mint,
			network: body.network,
		});
		const quoteAmount = walletQuoteDeltaAtomics({
			tx,
			wallet: body.wallet_address,
			quoteSymbol: quote_symbol,
			quoteMint: quote_mint,
		});
		// Keep sol_amount in sync for SOL sells so legacy readers see proceeds too.
		const lamports = quote_symbol === 'SOL' ? quoteAmount : null;
		await sql`
			insert into pump_agent_trades
				(mint_id, user_id, wallet, direction, route, sol_amount, token_amount,
				 quote_mint, quote_symbol, quote_amount, slippage_bps, tx_signature, network)
			values
				(${mintId}, ${user.id}, ${body.wallet_address}, 'sell', ${body.route},
				 ${lamports}, ${body.tokens}, ${quote_mint}, ${quote_symbol}, ${quoteAmount},
				 ${body.slippage_bps ?? null}, ${body.tx_signature}, ${body.network})
			on conflict (tx_signature, network) do nothing
		`;
		recordDailyActivity(user.id).catch(() => {});
	}

	recordQuestTrade({
		userId: user.id,
		signature: body.tx_signature,
		network: body.network,
		wallet: body.wallet_address,
		direction: 'sell',
		mint: body.mint,
	}).catch(() => {});

	return json(res, 200, {
		ok: true,
		tracked: !!mintId,
		mint: body.mint,
		network: body.network,
		tx_signature: body.tx_signature,
	});
}

// ── build-metadata ─────────────────────────────────────────────────────────
// Builds a pump.fun-compatible metadata JSON and uploads it (+ optional token
// image) to R2. Returns a stable public URL the wizard can use as the URI.

const buildMetadataSchema = z.object({
	name: z.string().trim().min(1).max(32),
	symbol: z.string().trim().min(1).max(10),
	description: z.string().trim().max(500).default(''),
	avatar_id: z.string().uuid().optional(),
	agent_id: z.string().uuid().optional(),
	// Social links surfaced on the coin page (pump.fun reads twitter/telegram/
	// website; explorers read external_url). Omit any to fall back to the agent
	// profile page (website) and the three.ws X/Telegram.
	twitter: z.string().trim().max(200).optional(),
	website: z.string().trim().max(200).optional(),
	telegram: z.string().trim().max(200).optional(),
	// Base64 data URL: "data:image/png;base64,...": max 4 MB raw.
	// Cap the string at 6 MB chars to safely cover 4 MB raw (base64 inflates ~4/3 → ~5.59 M)
	// plus the data URL header. Raw-byte ceiling is re-checked after decode.
	image_data_url: z.string().max(6_000_000).optional(),
});

async function handleBuildMetadata(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await getSessionUser(req);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

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

	let body;
	try {
		body = parse(buildMetadataSchema, await readJson(req));
	} catch (err) {
		if (err.code === 'validation_error') {
			console.warn('[pump/build-metadata] validation_error', {
				userId: user.id,
				issues: err.issues,
			});
		}
		throw err;
	}
	const uid = user.id;
	const ts = Date.now().toString(36);
	const prefix = `pump/meta/${uid}/${ts}`;

	// ── Resolve image bytes ─────────────────────────────────────────────────
	// We want raw bytes (not just an HTTPS URL) so the image can be pinned to
	// IPFS alongside the metadata: matching pump.fun's native upload flow.
	let imageBuf = null;
	let imageContentType = 'image/png';
	let imageExt = 'png';
	let imageUrl = null; // set directly only when we can't get bytes to pin

	if (body.image_data_url) {
		const commaIdx = body.image_data_url.indexOf(',');
		if (commaIdx === -1) return error(res, 400, 'validation_error', 'invalid image_data_url');
		const meta = body.image_data_url.slice(0, commaIdx);
		const payload = body.image_data_url.slice(commaIdx + 1);
		imageBuf = meta.includes('base64')
			? Buffer.from(payload, 'base64')
			: Buffer.from(decodeURIComponent(payload));
		if (imageBuf.byteLength > 4 * 1024 * 1024) {
			return error(res, 413, 'payload_too_large', 'image must be under 4 MB');
		}
		imageContentType = meta.match(/data:([^;,]+)/)?.[1] || 'image/png';
		imageExt =
			imageContentType.includes('jpeg') || imageContentType.includes('jpg') ? 'jpg' : 'png';
	} else if (body.avatar_id) {
		const [av] = await sql`
			select thumbnail_key from avatars
			where id=${body.avatar_id} and owner_id=${uid} and deleted_at is null limit 1
		`;
		// thumbnailUrl() returns null for a legacy origin-pointing `*_og.png` key,
		// whose object does not exist: fetching it would 404 and then the launch
		// would reference that dead URL from its permanent token metadata.
		const thumbUrl = thumbnailUrl(av?.thumbnail_key);
		if (thumbUrl) {
			// Fetch the stored thumbnail so it too lands on IPFS; if that fails,
			// fall back to referencing the R2 URL directly (still a valid image).
			try {
				// Bounded: a launch waits on this download, and an unbounded read of a
				// stalled object held the whole mint request open instead of falling
				// through to the R2 URL below, which is a perfectly good answer.
				const resp = await fetchUpstream(thumbUrl, {}, {
					name: 'r2:thumbnail',
					timeoutMs: 15_000,
					attempts: 2,
					okWhen: () => true,
				});
				if (resp.ok) {
					imageBuf = Buffer.from(await resp.arrayBuffer());
					imageContentType = resp.headers.get('content-type') || 'image/png';
					imageExt =
						imageContentType.includes('jpeg') || imageContentType.includes('jpg')
							? 'jpg'
							: 'png';
				}
			} catch {
				/* fall through to direct URL */
			}
			if (!imageBuf) imageUrl = thumbUrl;
		}
	}

	// Pin the image (IPFS preferred, R2 fallback) so the metadata references a
	// stable, gateway-resolvable URL.
	if (imageBuf && !imageUrl) {
		const pinnedImage = await pinToIPFS(imageBuf, `image.${imageExt}`).catch(() => null);
		if (pinnedImage) {
			imageUrl = pinnedImage.uri;
		} else {
			const imgKey = `${prefix}/image.${imageExt}`;
			await putObject({ key: imgKey, body: imageBuf, contentType: imageContentType });
			imageUrl = r2PublicUrl(imgKey);
		}
	}

	// ── Build metadata JSON via the canonical three.ws brand builder ─────────
	// This stamps createdOn=https://three.ws plus the Platform/Launchpad
	// attributes that explorers and launchpad aggregators read for attribution.
	// Link the coin to its 3D agent. An avatar that has no agent identity yet gets
	// one here (launch-prep would create it moments later anyway), so the page
	// the coin points at is the agent that launched it, not the three.ws homepage.
	let linkedAgentId = body.agent_id || null;
	let agentModelUrl;
	if (body.avatar_id) {
		if (!linkedAgentId) {
			const resolved = await resolveLaunchAgentId({ userId: uid, avatarId: body.avatar_id }).catch(() => null);
			linkedAgentId = resolved?.id || null;
		}
		const [avRow] = await sql`
			select storage_key, visibility from avatars
			where id=${body.avatar_id} and owner_id=${uid} and deleted_at is null limit 1
		`;
		// Token metadata is permanent and public: only a model its owner already
		// shares (public or unlisted) is written into it.
		if (avRow?.storage_key && (avRow.visibility === 'public' || avRow.visibility === 'unlisted')) {
			agentModelUrl = r2PublicUrl(avRow.storage_key);
		}
	}
	const agentHomeUrl = linkedAgentId ? `${env.APP_ORIGIN}/agents/${linkedAgentId}` : undefined;
	const metadata = buildTokenMetadata({
		name: body.name,
		symbol: body.symbol,
		description: body.description,
		image: imageUrl || '',
		...(agentHomeUrl ? { agentUrl: agentHomeUrl } : {}),
		...(agentModelUrl ? { agentModelUrl } : {}),
		...(body.twitter ? { twitter: body.twitter } : {}),
		...(body.website ? { website: body.website } : {}),
		...(body.telegram ? { telegram: body.telegram } : {}),
		createdAt: new Date().toISOString(),
	});

	// Pin the metadata JSON (IPFS preferred, R2 fallback).
	const jsonBuf = Buffer.from(JSON.stringify(metadata, null, 2));
	const pinnedJson = await pinToIPFS(jsonBuf, 'metadata.json').catch(() => null);
	let metadataUrl;
	if (pinnedJson) {
		metadataUrl = pinnedJson.uri;
	} else {
		const jsonKey = `${prefix}/metadata.json`;
		await putObject({ key: jsonKey, body: jsonBuf, contentType: 'application/json' });
		metadataUrl = r2PublicUrl(jsonKey);
	}

	return json(res, 200, {
		metadata_url: metadataUrl,
		image_url: imageUrl,
		agent_id: linkedAgentId,
		agent_url: agentHomeUrl || null,
		agent_model_url: agentModelUrl || null,
		on_ipfs: Boolean(pinnedJson),
		provider: pinnedJson?.provider ?? (ipfsPinningConfigured() ? 'r2-fallback' : 'r2'),
	});
}

// ── shared launch helpers ──────────────────────────────────────────────────

// Build the pump.fun launch instructions for the requested coin variant.
// All variants now go through createV2* (token-2022). Pump.fun no longer
// accepts V1 (SPL Token) launches: calling the deprecated createInstruction /
// createAndBuyInstructions paths returned tokens the pump.fun program rejected.
// mayhemMode toggles the high-volatility curve; agent binding is appended by
// the caller when applicable.
//
// creator is the on-chain "creator" (recipient of creator rewards / royalties).
// signer is the wallet that signs the tx, pays fees, and (if solBuyIn>0) funds
// the initial buy. When the caller omits signer it defaults to creator :
// preserving the legacy single-wallet semantics: but split mode is supported
// so a treasury / DAO wallet can be the creator while a contributor wallet
// signs and pays.
async function buildLaunchInstructions({
	sdk,
	BN,
	mint,
	creator,
	signer,
	name,
	symbol,
	uri,
	solBuyIn,
	usdcBuyIn,
	quoteMint,
	isMayhem,
	holderReward = false,
}) {
	const LAMPORTS = 1_000_000_000;
	const user = signer || creator;
	const { isLegacyQuoteMint } = await import('@pump-fun/pump-sdk');
	const isUsdcQuote = quoteMint && !isLegacyQuoteMint(quoteMint);

	if (isUsdcQuote) {
		// USDC-paired: use V2 buy path regardless of whether there's an initial buy.
		const hasBuy = usdcBuyIn > 0;
		const global = await sdk.fetchGlobal();
		const pumpSdk = await import('@pump-fun/pump-sdk');
		if (hasBuy) {
			const quoteAmount = new BN(Math.round(usdcBuyIn * 1_000_000));
			// Pass `quoteMint` so the SDK seeds a fresh curve from
			// `initial_virtual_quote_reserves` (USDC) rather than the SOL reserves :
			// otherwise the base-token estimate is priced against the wrong pool and
			// the create+buy can over/under-spend or revert on max_quote_cost.
			const tokenAmount = pumpSdk.getBuyTokenAmountFromSolAmount({
				global,
				feeConfig: null,
				mintSupply: null,
				bondingCurve: null,
				amount: quoteAmount,
				quoteMint,
			});
			const ixs = await sdk.createV2AndBuyV2Instructions({
				global,
				mint,
				name,
				symbol,
				uri,
				creator,
				user,
				quoteAmount,
				amount: tokenAmount,
				mayhemMode: !!isMayhem,
				quoteMint,
				holderReward,
			});
			return Array.isArray(ixs) ? [...ixs] : [ixs];
		}
		const ix = await sdk.createV2Instruction({
			mint,
			name,
			symbol,
			uri,
			creator,
			user,
			mayhemMode: !!isMayhem,
			quoteMint,
			holderReward,
		});
		return [ix];
	}

	// SOL-paired (original behaviour)
	const hasBuy = solBuyIn > 0;
	if (hasBuy) {
		const global = await sdk.fetchGlobal();
		const solAmount = new BN(Math.floor(solBuyIn * LAMPORTS));
		const pumpSdk = await import('@pump-fun/pump-sdk');
		const tokenAmount = pumpSdk.getBuyTokenAmountFromSolAmount({
			global,
			feeConfig: null,
			mintSupply: null,
			bondingCurve: null,
			amount: solAmount,
		});
		const ixs = await sdk.createV2AndBuyInstructions({
			global,
			mint,
			name,
			symbol,
			uri,
			creator,
			user,
			solAmount,
			amount: tokenAmount,
			mayhemMode: !!isMayhem,
			holderReward,
		});
		return Array.isArray(ixs) ? [...ixs] : [ixs];
	}

	const ix = await sdk.createV2Instruction({
		mint,
		name,
		symbol,
		uri,
		creator,
		user,
		mayhemMode: !!isMayhem,
		holderReward,
	});
	return [ix];
}

// ── launch-prep ────────────────────────────────────────────────────────────

const launchPrepSchema = z
	.object({
		agent_id: z.string().uuid().optional(),
		avatar_id: z.string().uuid().optional(),
		wallet_address: z.string().min(32).max(44), // the SIGNER — signs the tx, pays fees, funds initial buy
		// Optional on-chain creator address (the recipient of pump.fun creator
		// rewards / royalties). When omitted, defaults to wallet_address :
		// preserving the legacy single-wallet flow. When provided and different,
		// it must be another Solana wallet linked to the same user account
		// (validated at /api/pump/launch-prep). Enables team/DAO launches where
		// a treasury wallet is the creator and a contributor wallet pays gas.
		creator_address: z.string().min(32).max(44).optional(),
		name: z.string().trim().min(1).max(32),
		symbol: z.string().trim().min(1).max(10),
		// Bound the metadata URI so name(32)+symbol(10)+uri always fit inside
		// Solana's 1232-byte transaction packet: an unbounded URI is what pushed
		// the create message past the limit and threw "encoding overruns
		// Uint8Array" at sign time. 200 matches pump.fun's own URI ceiling; the
		// 413 guard at sign time remains as a defence-in-depth backstop.
		uri: z.string().url().max(200),
		network: z.enum(['mainnet', 'devnet']).default('mainnet'),
		buyback_bps: z.number().int().min(0).max(10_000).default(0),
		sol_buy_in: z.number().nonnegative().max(50).default(0), // SOL-paired initial buy, capped 50 SOL
		usdc_buy_in: z.number().nonnegative().max(1_000_000).default(0), // USDC-paired initial buy
		// Quote currency for the coin. `quote_currency: 'usdc'` is the friendly
		// form: the server resolves the network-correct USDC mint. `quote_mint`
		// is the explicit form (any non-WSOL mint → stable-paired v2 coin via
		// createV2AndBuyV2Instructions). When neither is set, the coin is
		// SOL-paired (existing behaviour). quote_currency wins when both appear.
		quote_currency: z.enum(['sol', 'usdc']).optional(),
		quote_mint: z.string().min(32).max(44).optional(),
		// Optional client-ground vanity mint address. When provided, the client
		// already holds the secret key locally and will co-sign in the wallet :
		// the server never sees the secret. When omitted, the server falls back
		// to a fresh Keypair.generate() and returns the secret key for co-sign.
		mint_address: z.string().min(32).max(44).optional(),
		// Coin variant:
		//   'agent'  : pump.fun coin + on-chain agent (buyback-bound)
		//   'regular': plain pump.fun coin, no agent binding
		//   'mayhem' : pump.fun mayhem-mode coin (V2 instruction set, token-2022)
		coin_type: z.enum(['regular', 'mayhem', 'agent']).default('agent'),
		// Platform-sponsored launch for a creator wallet with no SOL.
		gasless: z.boolean().default(false),
		// Pump SDK 2.0 holder-reward launch. Creator fees accrue to the
		// protocol-derived holder rewards PDA instead of a creator wallet.
		holder_reward: z.boolean().default(false),
		// Transaction format. 'auto' compiles v0 against pump.fun's lookup table and
		// only moves to the 4,096-byte v1 envelope when v0 overflows AND the wallet
		// advertised v1 signing (`v1_capable`). 0 or 1 pins the format.
		transaction_version: z.union([z.literal('auto'), z.literal(0), z.literal(1)]).default('auto'),
		v1_capable: z.boolean().default(false),
		// Optional Launch Copilot attach: a market-maker policy to arm on this coin
		// the moment it's confirmed (the success screen can also attach one after).
		// Validated + safety-gated by api/_lib/market-maker.js at confirm time.
		mm: z
			.object({
				preset: z.enum(['gentle', 'balanced', 'aggressive', 'custom']).optional(),
				mode: z.enum(['simulate', 'live']).optional(),
				enabled: z.boolean().optional(),
				floor_price_sol: z.number().nonnegative().optional(),
				floor_band_pct: z.number().optional(),
				take_profit_band_pct: z.number().optional(),
				recycle_pct: z.number().optional(),
				max_inventory_tokens: z.number().optional(),
				dip_buy_budget_sol: z.number().optional(),
				daily_budget_sol: z.number().optional(),
				seed_sol: z.number().optional(),
				graduation_action: z.enum(['provide_lp', 'hold', 'distribute']).optional(),
				slippage_bps: z.number().optional(),
				max_price_impact_pct: z.number().optional(),
				min_action_interval_seconds: z.number().optional(),
				max_volume_pct: z.number().optional(),
			})
			.optional(),
	})
	.refine((v) => v.agent_id || v.avatar_id, {
		message: 'agent_id or avatar_id required',
		path: ['agent_id'],
	})
	.refine((v) => !v.holder_reward || v.coin_type === 'regular', {
		message: 'holder_reward requires coin_type=regular',
		path: ['holder_reward'],
	})
	// Gasless: the launch sponsor pays rent + fees, and the coin's creator fees are
	// split on-chain with the platform (api/_lib/launch-sponsor.js). A dev buy
	// needs the creator's own funds, and the fee split needs a SOL-paired coin
	// whose creator fees reach a real wallet, so those options are excluded.
	.refine(
		(v) =>
			!v.gasless ||
			(!v.sol_buy_in && !v.usdc_buy_in && v.quote_currency !== 'usdc' && !v.quote_mint && v.coin_type !== 'mayhem' && !v.holder_reward),
		{
			message: 'a gasless launch has no dev buy, is SOL-paired, and is not a mayhem or holder-reward coin',
			path: ['gasless'],
		},
	);


async function handleLaunchPrep(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await getSessionUser(req);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

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

	const body = parse(launchPrepSchema, await readJson(req));
	const signer = solanaPubkey(body.wallet_address);
	if (!signer) return error(res, 400, 'validation_error', 'invalid wallet_address');

	// Verify signer wallet linked to user.
	const [walletRow] = await sql`
		select id from user_wallets
		where user_id=${user.id} and address=${body.wallet_address} and chain_type='solana'
		limit 1
	`;
	if (!walletRow) return error(res, 403, 'forbidden', 'wallet not linked to your account');

	// Resolve the on-chain creator (creator-reward recipient). When omitted,
	// the signer IS the creator (legacy single-wallet flow). When provided,
	// validate it's a valid Solana pubkey AND linked to the same user
	// account so callers can't launch tokens "as" arbitrary wallets.
	let creator = signer;
	if (body.creator_address && body.creator_address !== body.wallet_address) {
		const creatorPk = solanaPubkey(body.creator_address);
		if (!creatorPk) return error(res, 400, 'validation_error', 'invalid creator_address');
		const [creatorWallet] = await sql`
			select id from user_wallets
			where user_id=${user.id} and address=${body.creator_address} and chain_type='solana'
			limit 1
		`;
		if (!creatorWallet) {
			return error(
				res,
				403,
				'forbidden',
				'creator_address must be a solana wallet linked to your account',
			);
		}
		creator = creatorPk;
	}

	// Resolve agent_identities.id from either agent_id or avatar_id.
	// /studio sends avatar_id; the dashboard/vanity flows send agent_id.
	const agent = await resolveLaunchAgentId({
		userId: user.id,
		agentId: body.agent_id,
		avatarId: body.avatar_id,
	});
	if (!agent) return error(res, 404, 'not_found', 'agent not found');
	const resolvedAgentId = agent.id;

	// Mint pubkey: client-supplied (vanity-ground) or server-ground with the three.ws mark.
	const enforceMark = env.THREE_WS_MARK_ENFORCE !== '0' && env.THREE_WS_MARK_ENFORCE !== 'false';
	let mintKeypair = null;
	let mint;

	if (body.mint_address) {
		const supplied = solanaPubkey(body.mint_address);
		if (!supplied) return error(res, 400, 'validation_error', 'invalid mint_address');
		if (enforceMark && !hasThreeWsMark(supplied.toBase58())) {
			return error(
				res,
				400,
				'unbranded_mint',
				'three.ws launches must use a mint address carrying the "3ws" mark — grind one client-side or omit mint_address to let the server stamp it',
			);
		}
		mint = supplied;
	} else if (enforceMark) {
		try {
			const ground = await grindVanityNode({ ...THREE_WS_VANITY }); // ~49k attempts, sub-second
			mintKeypair = Keypair.fromSecretKey(ground.secretKey);
			mint = mintKeypair.publicKey;
			log.info('mint_mark_stamped', {
				publicKey: ground.publicKey,
				attempts: ground.attempts,
				durationMs: Math.round(ground.durationMs),
			});
		} catch (err) {
			if (err instanceof GrindExhaustedError) {
				return error(
					res,
					503,
					'mark_grind_failed',
					'could not stamp the three.ws mark — retry',
				);
			}
			throw err;
		}
	} else {
		mintKeypair = Keypair.generate();
		mint = mintKeypair.publicKey;
	}

	if (body.gasless) {
		return prepGaslessLaunch(res, { user, body, creator, signer, mint, mintKeypair, agentId: resolvedAgentId });
	}

	const { sdk, BN } = await getPumpSdk({ network: body.network });
	const LAMPORTS_PER_SOL_LAUNCH = 1_000_000_000;

	// Coin-variant flags:
	//   mayhem → use createV2* (token-2022, mayhemMode=true), drop buyback binding
	//   agent  → V1 path + on-chain agent (PumpAgent.create with buyback_bps)
	//   regular→ V1 path, no agent binding
	const isMayhem = body.coin_type === 'mayhem';
	const isAgent = body.coin_type === 'agent';
	// The PumpAgent program currently refuses new agents (see
	// pumpAgentBuybackAvailable), so an 'agent' coin launches without the
	// on-chain buyback binding instead of reverting the whole launch.
	const buybackAvailable = pumpAgentBuybackAvailable();
	const effBuyback = isAgent && buybackAvailable ? body.buyback_bps : 0;

	// Resolve the quote pairing: null → SOL-paired; an explicit mint (e.g. USDC)
	// → stable-paired so the agent's USDC buyback can swap+burn natively. The
	// friendly `quote_currency` ('sol'|'usdc') wins and resolves the
	// network-correct USDC mint; otherwise an explicit `quote_mint` is used.
	const requestedQuoteMint =
		body.quote_currency === 'usdc'
			? usdcMintFor(body.network)
			: body.quote_currency === 'sol'
				? null
				: body.quote_mint;
	const quote = classifyLaunchQuote({ quoteMint: requestedQuoteMint, network: body.network });
	const launchQuoteMint = quote.quoteMint ? solanaPubkey(quote.quoteMint) : null;
	const instructions = await buildLaunchInstructions({
		sdk,
		BN,
		mint,
		creator,
		signer,
		name: body.name,
		symbol: body.symbol,
		uri: body.uri,
		solBuyIn: body.sol_buy_in,
		usdcBuyIn: body.usdc_buy_in,
		quoteMint: launchQuoteMint,
		isMayhem,
		holderReward: body.holder_reward,
	});
	const onchainCreator = body.holder_reward
		? (await import('@pump-fun/pump-sdk')).holderRewardsPda(mint)
		: creator;

	if (isAgent && effBuyback > 0) {
		const { offline } = await getPumpAgentOffline({ network: body.network, mint });
		const createIx = await offline.create({
			authority: creator,
			mint,
			agentAuthority: creator,
			buybackBps: effBuyback,
		});
		instructions.push(createIx);
	}

	// three.ws launch fee: a disclosed share of the dev buy, paid by the signer in
	// the same transaction as the create. No dev buy, no fee.
	const launchFee = await buildPlatformFeeInstructions({
		network: body.network,
		payer: signer,
		isUsdc: quote.isUsdc,
		quoteMintPk: launchQuoteMint,
		grossAtomics: quote.isUsdc
			? BigInt(Math.round((body.usdc_buy_in || 0) * 1_000_000))
			: BigInt(Math.floor((body.sol_buy_in || 0) * LAMPORTS_PER_SOL_LAUNCH)),
		basis: 'launch_dev_buy',
		bps: pumpLaunchFeeBps(),
	});
	if (launchFee) instructions.push(...launchFee.instructions);

	// Signer pays gas + funds the initial buy. Creator stays on-chain as the
	// reward recipient regardless of who paid. A server-ground mint co-signs
	// here so the browser only adds the wallet signature.
	const built = await buildLaunchTransaction({
		network: body.network,
		payer: signer,
		instructions,
		transactionVersion: body.transaction_version,
		v1Capable: body.v1_capable,
		signers: mintKeypair ? [mintKeypair] : [],
	});
	const txBase64 = built.tx_base64;

	const prepId = await randomToken(24);
	const expiresAt = new Date(Date.now() + 30 * 60 * 1000);

	await sql`
		insert into agent_registrations_pending (user_id, cid, metadata_uri, payload, expires_at)
		values (
			${user.id},
			${mint.toBase58()},
			${body.uri},
			${JSON.stringify({
				kind: 'pump_launch',
				agent_id: resolvedAgentId,
				wallet_address: body.wallet_address, // signer (pays gas, funds initial buy)
				creator_address: onchainCreator.toBase58(), // actual on-chain fee recipient
				mint: mint.toBase58(),
				name: body.name,
				symbol: body.symbol,
				network: body.network,
				buyback_bps: effBuyback,
				coin_type: body.coin_type,
				holder_reward: body.holder_reward,
				quote_mint: quote.quoteMint, // null = SOL-paired; else the stable quote mint
				platform_fee: launchFee ? launchFee.disclosure : null,
				transaction_version: built.transaction_version,
				prep_id: prepId,
				mm: body.mm || null, // optional Launch Copilot policy to arm on confirm
			})}::jsonb,
			${expiresAt}
		)
	`;

	return json(res, 201, {
		prep_id: prepId,
		agent_id: resolvedAgentId,
		mint: mint.toBase58(),
		// Mint keypair must co-sign the tx. When server-generated, we hand
		// the secret to the frontend; when client-supplied (vanity), the
		// client already holds it and the server never sees it.
		mint_secret_key_b64: mintKeypair
			? Buffer.from(mintKeypair.secretKey).toString('base64')
			: null,
		client_supplied_mint: !mintKeypair,
		mint_presigned: !!mintKeypair,
		tx_base64: txBase64,
		transaction_version: built.transaction_version,
		tx_bytes: built.bytes,
		tx_limit_bytes: built.limit_bytes,
		platform_fee: launchFee ? launchFee.disclosure : null,
		buyback_available: buybackAvailable,
		network: body.network,
		buyback_bps: effBuyback,
		coin_type: body.coin_type,
		holder_reward: body.holder_reward,
		quote_mint: quote.quoteMint,
		quote_currency: quote.label,
		expires_at: expiresAt.toISOString(),
		instructions: mintKeypair
			? 'The mint keypair has already co-signed tx_base64. Have the user wallet sign it (a Wallet Standard signTransaction for transaction_version 1), submit, then POST /api/pump/launch-confirm with the tx_signature.'
			: 'Decode tx_base64 as VersionedTransaction. Sign with your locally-held vanity mint keypair AND the user wallet, submit, then POST /api/pump/launch-confirm with the tx_signature.',
	});
}

// ── launch-prep (gasless) ──────────────────────────────────────────────────
//
// The launch sponsor pays rent + network fees; the creator (the signer) only
// signs. Eligibility is checked against the live caps and the sponsor's floor
// before anything is built, and the transaction is measured by simulation so
// the sponsored cost shown to the user is the cost the chain will charge.

async function prepGaslessLaunch(res, { user, body, creator, signer, mint, mintKeypair, agentId }) {
	if (!creator.equals(signer)) {
		return error(res, 400, 'validation_error', 'a gasless launch is signed by its creator: omit creator_address or set it to wallet_address');
	}
	const econ = await getLaunchEconomics();
	const eligibility = await gaslessEligibility({ userId: user.id, network: body.network, econ });
	if (!eligibility.eligible) {
		const first = eligibility.reasons[0];
		const status = /cap$/.test(first.code) ? 429 : first.code === 'gasless_disabled' ? 403 : 503;
		return error(res, status, first.code, first.message, { gasless: eligibility });
	}
	let built;
	try {
		built = await prepareGaslessCurveLaunch({
			network: body.network,
			mint,
			mintKeypair,
			creator,
			name: body.name,
			symbol: body.symbol,
			uri: body.uri,
			econ,
		});
	} catch (err) {
		if (err instanceof GaslessError) return error(res, err.status, err.code, err.message);
		if (isRpcOutageError(err)) return error(res, 503, 'rpc_unavailable', 'Solana RPC is temporarily unavailable. Try again in a moment.');
		throw err;
	}

	const prepId = await randomToken(24);
	const expiresAt = new Date(Date.now() + 30 * 60 * 1000);
	const gasless = {
		sponsor: built.sponsor,
		sponsored_lamports: built.sponsored_lamports,
		sponsored_sol: built.sponsored_lamports / LAMPORTS_PER_SOL,
		rent_forwarded_lamports: built.rent_forwarded_lamports,
		platform_recipient: built.platform_recipient,
		creator_share_bps: built.creator_share_bps,
		platform_share_bps: built.platform_share_bps,
		buyback_share_of_platform_bps: econ.buyback.share_of_platform_revenue_bps,
		explanation: describeFeeSplit(econ, { gasless: true }),
	};
	await sql`
		insert into agent_registrations_pending (user_id, cid, metadata_uri, payload, expires_at)
		values (
			${user.id},
			${mint.toBase58()},
			${body.uri},
			${JSON.stringify({
				kind: 'pump_launch',
				gasless: true,
				agent_id: agentId,
				wallet_address: body.wallet_address,
				creator_address: creator.toBase58(),
				mint: mint.toBase58(),
				name: body.name,
				symbol: body.symbol,
				network: body.network,
				buyback_bps: 0,
				coin_type: body.coin_type,
				holder_reward: false,
				quote_mint: null,
				platform_fee: null,
				transaction_version: 0,
				prep_id: prepId,
				sponsor: built.sponsor,
				sponsored_lamports: built.sponsored_lamports,
				platform_share_bps: built.platform_share_bps,
			})}::jsonb,
			${expiresAt}
		)
	`;
	await recordSponsorshipPrepared({
		userId: user.id,
		agentId,
		network: body.network,
		mint: mint.toBase58(),
		creator: creator.toBase58(),
		sponsor: built.sponsor,
		prepId,
		sponsoredLamports: built.sponsored_lamports,
		platformShareBps: built.platform_share_bps,
	});

	return json(res, 201, {
		prep_id: prepId,
		agent_id: agentId,
		mint: mint.toBase58(),
		mint_secret_key_b64: null,
		client_supplied_mint: !mintKeypair,
		mint_presigned: !!mintKeypair,
		tx_base64: built.tx_base64,
		transaction_version: 0,
		tx_bytes: built.bytes,
		fee_payer: built.sponsor,
		platform_fee: null,
		network: body.network,
		coin_type: body.coin_type,
		quote_currency: 'SOL',
		gasless,
		expires_at: expiresAt.toISOString(),
		instructions: mintKeypair
			? 'The launch sponsor and the mint have signed tx_base64 and the sponsor pays every fee. Have the creator wallet sign it (signTransaction, not signAndSend), then POST /api/pump/launch-confirm with prep_id and signed_tx_base64. The server submits it.'
			: 'The launch sponsor has signed tx_base64 and pays every fee. Sign with your vanity mint keypair and the creator wallet, then POST /api/pump/launch-confirm with prep_id and signed_tx_base64.',
	});
}

// ── launch-confirm ─────────────────────────────────────────────────────────

const launchConfirmSchema = z
	.object({
		prep_id: z.string().min(8),
		tx_signature: z.string().min(80).max(100).optional(),
		// Gasless launches: the fully signed transaction, submitted by the server so
		// the creator's wallet never has to broadcast a transaction it did not pay for.
		signed_tx_base64: z.string().min(100).max(8000).optional(),
	})
	.refine((v) => v.tx_signature || v.signed_tx_base64, {
		message: 'tx_signature or signed_tx_base64 required',
		path: ['tx_signature'],
	});

async function handleLaunchConfirm(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await getSessionUser(req);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

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

	const body = parse(launchConfirmSchema, await readJson(req));

	const [pending] = await sql`
		select id, payload, metadata_uri from agent_registrations_pending
		where user_id=${user.id} and payload->>'prep_id'=${body.prep_id}
		  and expires_at > now()
		order by created_at desc limit 1
	`;
	if (!pending) return error(res, 404, 'not_found', 'prep not found or expired');
	const p = pending.payload;
	if (p.kind !== 'pump_launch') return error(res, 400, 'wrong_kind', 'prep is not a pump launch');
	// metadata_uri lives as a top-level column on the pending row (= launch-prep
	// `uri`), not inside the payload JSON. Thread it through so client-signed
	// launches persist their metadata like the launch-agent path does.
	const metadataUri = pending.metadata_uri || p.metadata_uri || null;

	let txSignature = body.tx_signature;
	if (body.signed_tx_base64) {
		try {
			txSignature = await submitSignedLaunch({ network: p.network, signedTxBase64: body.signed_tx_base64, mint: p.mint, gasless: p.gasless ? p.sponsor : null });
		} catch (e) {
			return error(res, e.status || 422, e.code || 'submit_failed', e.message);
		}
	}

	let tx;
	try {
		tx = await verifySignature({ network: p.network, signature: txSignature });
	} catch (e) {
		return error(res, e.status || 422, e.code || 'tx_failed', e.message);
	}
	if (p.gasless) {
		try {
			verifyGaslessTransaction(tx, { sponsor: p.sponsor, mint: p.mint });
		} catch (e) {
			return error(res, e.status || 422, e.code || 'not_sponsored', e.message);
		}
	}
	const accountKeys = tx.transaction.message.accountKeys.map((k) => (k.pubkey || k).toString());
	if (!accountKeys.includes(p.mint)) {
		return error(res, 422, 'mint_not_in_tx', 'mint pubkey not present in tx');
	}
	// Prove the confirmed tx actually ran the pump.fun program: not just a tx
	// that happens to reference the mint pubkey. Without this, a confirmed memo
	// or transfer touching the new mint account could be recorded as a launch.
	if (!txInvokesPumpProgram(tx)) {
		return error(res, 422, 'not_a_pump_launch', 'transaction did not invoke the pump.fun program');
	}
	// The launch fee rode inside the transaction launch-prep built. A signature
	// for some other transaction (the same mint, minus the fee) is not a
	// three.ws launch and is not listed as one.
	if (!txPaidPlatformFee(tx, p.platform_fee, p.quote_mint || undefined)) {
		return error(res, 422, 'platform_fee_missing', 'transaction did not include the disclosed three.ws launch fee');
	}

	const [existing] = await sql`
		select id from pump_agent_mints where mint=${p.mint} and network=${p.network} limit 1
	`;
	if (existing) return error(res, 409, 'conflict', 'mint already registered');

	// agent_authority is the on-chain creator (royalty recipient + governance
	// authority), not the signer. p.creator_address is set by launch-prep;
	// fall back to wallet_address for prep rows written before the split landed.
	const agentAuthority = p.creator_address || p.wallet_address;
	const [row] = await sql`
		insert into pump_agent_mints
			(agent_id, user_id, network, mint, name, symbol, metadata_uri, agent_authority, buyback_bps, quote_mint)
		values
			(${p.agent_id}, ${user.id}, ${p.network}, ${p.mint},
			 ${p.name}, ${p.symbol}, ${metadataUri}, ${agentAuthority}, ${p.buyback_bps}, ${p.quote_mint ?? null})
		returning id, mint, network, buyback_bps, quote_mint, created_at
	`;

	await sql`delete from agent_registrations_pending where id=${pending.id}`;

	// Launch Copilot: if the launcher armed a market-maker policy at prep time,
	// attach it now from the launch's own agent wallet. Best-effort: a bad policy
	// (e.g. an anti-manipulation cap breach) must never fail the confirmed launch;
	// the owner can fix + arm it from the success screen. The MM trades only
	// through the shared firewall/spend-guard/custody path.
	if (p.mm && p.agent_id) {
		try {
			const { normalizePolicyPatch, upsertPolicy } = await import('../_lib/market-maker.js');
			const patch = normalizePolicyPatch(p.mm, { isCreate: true });
			// The launch itself is already on-chain, so an unsigned real-funds
			// agreement must not fail this confirm. Attach the maker disarmed instead;
			// arming it later goes through /api/launch/mm, which enforces the agreement.
			if (p.network !== 'devnet' && patch.enabled === true && patch.kill_switch !== true && patch.mode === 'live') {
				const signed = await currentSignatureFor(user.id).catch(() => null);
				if (!signed) patch.enabled = false;
			}
			await upsertPolicy({ mint: p.mint, network: p.network, agentId: p.agent_id, userId: user.id, patch });
		} catch (e) {
			console.warn('[pump/launch-confirm] market-maker attach skipped:', e?.code || e?.message);
		}
	}

	// Surface the confirmed launch on the site-wide live activity ticker.
	publishFeedEvent({
		type: 'coin-buy',
		ts: Date.now(),
		actor: shortAddr(p.wallet_address),
		mint: p.mint,
		sol: 0,
		network: p.network,
		branded: hasThreeWsMark(p.mint),
	}).catch(() => {});

	if (p.gasless) {
		await recordSponsorshipLaunched({ mint: p.mint, network: p.network, signature: txSignature });
	}

	return json(res, 201, {
		ok: true,
		mint: p.mint,
		pump_agent_mint: row,
		tx_signature: txSignature,
		signature: txSignature,
		gasless: !!p.gasless,
		launch_url: `${env.APP_ORIGIN}/launch/${p.mint}`,
		explorer: `https://solscan.io/tx/${txSignature}${p.network === 'devnet' ? '?cluster=devnet' : ''}`,
	});
}

/**
 * Broadcast a wallet-signed launch transaction and wait for confirmation.
 * For a gasless launch, the fee payer must be the sponsor that prepared it.
 */
async function submitSignedLaunch({ network, signedTxBase64, mint, gasless }) {
	const { VersionedTransaction } = await import('@solana/web3.js');
	let vtx;
	try {
		vtx = VersionedTransaction.deserialize(Buffer.from(signedTxBase64, 'base64'));
	} catch {
		throw Object.assign(new Error('signed_tx_base64 is not a serialized versioned transaction'), { status: 400, code: 'validation_error' });
	}
	const keys = vtx.message.staticAccountKeys.map((k) => k.toBase58());
	if (!keys.includes(mint)) throw Object.assign(new Error('the signed transaction does not create the prepared mint'), { status: 422, code: 'mint_not_in_tx' });
	if (gasless && keys[0] !== gasless) {
		throw Object.assign(new Error('the signed transaction is not fee-paid by the launch sponsor'), { status: 422, code: 'not_sponsored' });
	}
	const connection = getConnection({ network });
	const raw = vtx.serialize();
	const signature = await connection.sendRawTransaction(raw, { skipPreflight: false, preflightCommitment: 'confirmed', maxRetries: 3 });
	const { confirmOrThrow } = await import('../_lib/solana/confirm.js');
	await confirmOrThrow(connection, signature, 'confirmed');
	return signature;
}

// ── agent-wallet ───────────────────────────────────────────────────────────
//
// Resolves the agent_identity backing the avatar (creating it if needed) and
// the agent's custodial Solana wallet (provisioning if needed). Returns the
// wallet's address and live SOL balance so the /studio UI can display it,
// fund it, and check whether it can cover a launch.

const agentWalletSchema = z
	.object({
		agent_id: z.string().uuid().optional(),
		avatar_id: z.string().uuid().optional(),
		network: z.enum(['mainnet', 'devnet']).default('mainnet'),
	})
	.refine((v) => v.agent_id || v.avatar_id, {
		message: 'agent_id or avatar_id required',
		path: ['agent_id'],
	});

async function handleAgentWallet(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await getSessionUser(req);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

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

	const body = parse(agentWalletSchema, await readJson(req));

	const agent = await resolveLaunchAgentId({
		userId: user.id,
		agentId: body.agent_id,
		avatarId: body.avatar_id,
	});
	if (!agent) return error(res, 404, 'not_found', 'agent not found');

	const loaded = await loadAgentForSigning(agent.id, user.id, {
		reason: 'studio_launch_prepare',
	});
	if (loaded.error) return error(res, loaded.error.status, loaded.error.code, loaded.error.msg);

	const address = loaded.keypair.publicKey.toBase58();
	let lamports = null;
	try {
		const conn = solanaConnection(body.network);
		lamports = await conn.getBalance(loaded.keypair.publicKey);
	} catch (err) {
		console.error('[pump/agent-wallet] balance fetch failed', err?.message);
	}

	return json(res, 200, {
		agent_id: agent.id,
		address,
		network: body.network,
		lamports,
		sol: lamports == null ? null : lamports / 1e9,
	});
}

// ── launch-agent ───────────────────────────────────────────────────────────
//
// Server-side mirror of launch-prep + launch-confirm: builds, signs, and
// submits a pump.fun launch transaction using the agent's custodial Solana
// keypair. The user's connected wallet is not involved: the agent wallet
// pays for rent, fees, and any initial buy. PumpAgent.create is bound when
// buyback_bps > 0.

const launchAgentSchema = z
	.object({
		agent_id: z.string().uuid().optional(),
		avatar_id: z.string().uuid().optional(),
		name: z.string().trim().min(1).max(32),
		symbol: z.string().trim().min(1).max(10),
		// Bound the metadata URI so name(32)+symbol(10)+uri always fit inside
		// Solana's 1232-byte transaction packet: an unbounded URI is what pushed
		// the create message past the limit and threw "encoding overruns
		// Uint8Array" at sign time. 200 matches pump.fun's own URI ceiling; the
		// 413 guard at sign time remains as a defence-in-depth backstop.
		uri: z.string().url().max(200),
		network: z.enum(['mainnet', 'devnet']).default('mainnet'),
		buyback_bps: z.number().int().min(0).max(10_000).default(0),
		sol_buy_in: z.number().nonnegative().max(50).default(0),
		// USDC-paired agent coins: pass `quote_mint` (the USDC mint) to create a
		// stable-paired curve, and `usdc_buy_in` for an optional USDC dev buy. The
		// agent custodial wallet must hold that USDC (checked in the preflight).
		usdc_buy_in: z.number().nonnegative().max(1_000_000).default(0),
		quote_currency: z.enum(['sol', 'usdc']).optional(),
		quote_mint: z.string().min(32).max(44).optional(),
		mint_address: z.string().min(32).max(44).optional(),
		mint_secret_key_b64: z.string().min(20).optional(),
		coin_type: z.enum(['regular', 'mayhem', 'agent']).default('agent'),
		holder_reward: z.boolean().default(false),
	})
	.refine((v) => v.agent_id || v.avatar_id, {
		message: 'agent_id or avatar_id required',
		path: ['agent_id'],
	})
	.refine((v) => !v.mint_address || v.mint_secret_key_b64, {
		message: 'mint_secret_key_b64 required when mint_address is supplied',
		path: ['mint_secret_key_b64'],
	})
	.refine((v) => !v.holder_reward || v.coin_type === 'regular', {
		message: 'holder_reward requires coin_type=regular',
		path: ['holder_reward'],
	});

async function handleLaunchAgent(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await requireSessionUser(req, res);
	if (!user) return;

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

	const body = parse(launchAgentSchema, await readJson(req));

	const agent = await resolveLaunchAgentId({
		userId: user.id,
		agentId: body.agent_id,
		avatarId: body.avatar_id,
	});
	if (!agent) return error(res, 404, 'not_found', 'agent not found');
	const resolvedAgentId = agent.id;
	if (!(await requireRealFundsAgreement(req, res, { userId: user.id, network: body.network, context: 'pump-launch-agent' }))) return;

	const loaded = await loadAgentForSigning(resolvedAgentId, user.id, {
		reason: 'studio_pump_launch',
		meta: { network: body.network, buyback_bps: body.buyback_bps, coin_type: body.coin_type },
	});
	if (loaded.error) return error(res, loaded.error.status, loaded.error.code, loaded.error.msg);
	const agentKeypair = loaded.keypair;
	const creator = agentKeypair.publicKey;

	// Mint keypair: client-supplied (vanity) or server-ground with the three.ws mark.
	// This path signs server-side with the agent custodial wallet, so the server
	// always holds the mint secret: supplied or ground.
	const enforceMark = env.THREE_WS_MARK_ENFORCE !== '0' && env.THREE_WS_MARK_ENFORCE !== 'false';
	let mintKeypair;
	if (body.mint_address && body.mint_secret_key_b64) {
		try {
			mintKeypair = Keypair.fromSecretKey(
				Uint8Array.from(Buffer.from(body.mint_secret_key_b64, 'base64')),
			);
		} catch {
			return error(res, 400, 'validation_error', 'mint_secret_key_b64 did not parse');
		}
		if (mintKeypair.publicKey.toBase58() !== body.mint_address) {
			return error(res, 400, 'validation_error', 'mint_address does not match secret key');
		}
		if (enforceMark && !hasThreeWsMark(mintKeypair.publicKey.toBase58())) {
			return error(
				res,
				400,
				'unbranded_mint',
				'three.ws launches must use a mint carrying the "3ws" mark — omit mint_address to let the server stamp it',
			);
		}
	} else if (enforceMark) {
		try {
			const ground = await grindVanityNode({ ...THREE_WS_VANITY }); // ~49k attempts, sub-second
			mintKeypair = Keypair.fromSecretKey(ground.secretKey);
			log.info('mint_mark_stamped', {
				publicKey: ground.publicKey,
				attempts: ground.attempts,
				durationMs: Math.round(ground.durationMs),
			});
		} catch (err) {
			if (err instanceof GrindExhaustedError) {
				return error(
					res,
					503,
					'mark_grind_failed',
					'could not stamp the three.ws mark — retry',
				);
			}
			throw err;
		}
	} else {
		mintKeypair = Keypair.generate();
	}
	const mint = mintKeypair.publicKey;

	// Conflict check before doing on-chain work.
	const [existing] = await sql`
		select id from pump_agent_mints where mint=${mint.toBase58()} and network=${body.network} limit 1
	`;
	if (existing) return error(res, 409, 'conflict', 'mint already registered');

	// Resolve the quote pairing. Agent coins are SOL-paired by default; pass
	// `quote_currency: 'usdc'` (or an explicit `quote_mint`) to launch a
	// stable-paired coin whose USDC buyback swaps natively.
	const requestedQuoteMint =
		body.quote_currency === 'usdc'
			? usdcMintFor(body.network)
			: body.quote_currency === 'sol'
				? null
				: body.quote_mint;
	const quote = classifyLaunchQuote({ quoteMint: requestedQuoteMint, network: body.network });
	const launchQuoteMint = quote.quoteMint ? solanaPubkey(quote.quoteMint) : null;

	// three.ws launch fee on the dev buy, paid by the agent wallet in the launch
	// transaction itself. Built before the preflight so the balance check covers it.
	const launchFee = await buildPlatformFeeInstructions({
		network: body.network,
		payer: creator,
		isUsdc: quote.isUsdc,
		quoteMintPk: launchQuoteMint,
		grossAtomics: quote.isUsdc
			? BigInt(Math.round((body.usdc_buy_in || 0) * 1_000_000))
			: BigInt(Math.floor((body.sol_buy_in || 0) * LAMPORTS_PER_SOL)),
		basis: 'launch_dev_buy',
		bps: pumpLaunchFeeBps(),
	});
	const feeLamports = launchFee && launchFee.disclosure.asset === 'SOL' ? Number(launchFee.disclosure.amount) : 0;
	const feeUsdcAtomics = launchFee && launchFee.disclosure.asset === 'USDC' ? BigInt(launchFee.disclosure.amount) : 0n;

	// Pre-flight: make sure the agent wallet can afford the launch.
	const conn = solanaConnection(body.network);
	const PUMP_BASE_LAMPORTS = Math.floor(0.022 * LAMPORTS_PER_SOL);
	// SOL always covers rent + fees. A SOL dev buy adds to the requirement; a USDC
	// dev buy is funded from the wallet's USDC balance (checked separately), so it
	// does not add to the SOL requirement.
	const initialBuyLamports = quote.isUsdc
		? 0
		: Math.floor((body.sol_buy_in || 0) * LAMPORTS_PER_SOL);
	const requiredLamports = PUMP_BASE_LAMPORTS + initialBuyLamports + feeLamports;
	let balanceLamports = 0;
	try {
		balanceLamports = await conn.getBalance(creator);
	} catch (err) {
		console.error('[pump/launch-agent] balance check failed', err?.message);
	}
	if (balanceLamports < requiredLamports) {
		return error(
			res,
			402,
			'insufficient_funds',
			`agent wallet has ${(balanceLamports / LAMPORTS_PER_SOL).toFixed(4)} SOL, needs ~${(requiredLamports / LAMPORTS_PER_SOL).toFixed(4)} SOL — deposit to ${creator.toBase58()}`,
		);
	}

	// USDC dev buy: the custodial wallet must hold the USDC it will spend, or the
	// create+buy reverts on-chain. Verify up front so it fails cleanly here.
	if (quote.isUsdc && body.usdc_buy_in > 0) {
		const needAtomics = BigInt(Math.round(body.usdc_buy_in * 1_000_000)) + feeUsdcAtomics;
		let haveAtomics = 0n;
		try {
			const { getAssociatedTokenAddressSync } = await import('@solana/spl-token');
			const usdcAta = getAssociatedTokenAddressSync(launchQuoteMint, creator, true);
			const bal = await conn.getTokenAccountBalance(usdcAta);
			haveAtomics = BigInt(bal?.value?.amount ?? 0);
		} catch {
			haveAtomics = 0n; // missing/closed ATA → treat as zero balance
		}
		if (haveAtomics < needAtomics) {
			return error(
				res,
				402,
				'insufficient_usdc',
				`agent wallet holds ${(Number(haveAtomics) / 1e6).toFixed(2)} USDC, needs ${body.usdc_buy_in.toFixed(2)} USDC for the dev buy — deposit USDC to ${creator.toBase58()} or set usdc_buy_in to 0`,
			);
		}
	}

	const { sdk, BN } = await getPumpSdk({ network: body.network });

	const isMayhem = body.coin_type === 'mayhem';
	const isAgent = body.coin_type === 'agent';
	const buybackAvailable = pumpAgentBuybackAvailable();
	const effBuyback = isAgent && buybackAvailable ? body.buyback_bps : 0;

	const instructions = await buildLaunchInstructions({
		sdk,
		BN,
		mint,
		creator,
		name: body.name,
		symbol: body.symbol,
		uri: body.uri,
		solBuyIn: body.sol_buy_in,
		usdcBuyIn: body.usdc_buy_in,
		quoteMint: launchQuoteMint,
		isMayhem,
		holderReward: body.holder_reward,
	});

	if (isAgent && effBuyback > 0) {
		const { offline } = await getPumpAgentOffline({ network: body.network, mint });
		const createIx = await offline.create({
			authority: creator,
			mint,
			agentAuthority: creator,
			buybackBps: effBuyback,
		});
		instructions.push(createIx);
	}

	// Spend-policy gate: this path signs server-side with the agent's custodial
	// wallet, so a stolen session could otherwise drive an arbitrarily large SOL
	// dev-buy (up to the schema max) to drain the wallet. Reserve the SOL outflow
	// against the agent's per-tx + rolling-24h caps BEFORE broadcasting: atomic,
	// so concurrent launches can't both pass, and the launch is recorded toward
	// the daily cap. A USDC-paired dev buy moves no SOL (amount 0). Released on
	// send failure, finalized with the signature on success.
	const launchSolOutflow = (quote.isUsdc ? 0 : body.sol_buy_in || 0) + feeLamports / LAMPORTS_PER_SOL;
	// The owner's full spend policy (frozen switch, burner tier, USD caps, English
	// rules) applies before the SOL reservation, same as every other signing path.
	try {
		const price = await solUsdPrice().catch(() => null);
		await enforceSpendLimit({
			agentId: resolvedAgentId,
			meta: loaded.meta,
			category: 'trade',
			usdValue: Number.isFinite(price) && price > 0 ? launchSolOutflow * price : null,
			asset: 'SOL',
			userId: user.id,
			network: body.network,
		});
	} catch (err) {
		if (err instanceof SpendLimitError) return error(res, err.status, err.code, err.message, err.detail);
		throw err;
	}
	const reservation = await reserveSpend({
		agentId: resolvedAgentId,
		meta: loaded.meta,
		mint: mint.toBase58(),
		solAmount: launchSolOutflow,
		type: 'pumpfun.launch',
		payload: {
			name: body.name,
			symbol: body.symbol,
			network: body.network,
			source: 'studio_agent_wallet',
		},
	});
	if (!reservation.ok) return error(res, reservation.status, reservation.code, reservation.msg);

	let signature;
	// Set when the fee could not ride in the launch transaction and settles in its
	// own transaction after the launch lands: 'separate' on success, 'failed' if
	// that follow-up transfer did not land.
	let feeSettlement = launchFee ? 'bundled' : null;
	const lookupTables = await getPumpLookupTables({ network: body.network });
	const sendLaunch = (ixs) =>
		submitProtected({
			network: body.network,
			connection: conn,
			payer: agentKeypair,
			instructions: ixs,
			opts: { extraSigners: [mintKeypair], addressLookupTables: lookupTables },
		});
	try {
		// Protected send: the agent custodial wallet pays + signs, the new mint
		// co-signs. Priority fee + CU estimate, rebroadcast with blockhash refresh,
		// hard throw on an on-chain revert. The launch fee rides along when it
		// fits; a USDC-quoted launch plus the engine's compute-budget instructions
		// can exceed the v0 packet, and then the coin launches first and the fee
		// follows in its own transaction.
		try {
			({ signature } = await sendLaunch(launchFee ? [...instructions, ...launchFee.instructions] : instructions));
		} catch (err) {
			if (!launchFee || !/too large|overruns|RangeError/i.test(`${err?.name} ${err?.message}`)) throw err;
			({ signature } = await sendLaunch(instructions));
			feeSettlement = 'separate';
			try {
				await submitProtected({
					network: body.network,
					connection: conn,
					payer: agentKeypair,
					instructions: launchFee.instructions,
				});
			} catch (feeErr) {
				feeSettlement = 'failed';
				console.error('[pump/launch-agent] separate launch-fee transfer failed', mint.toBase58(), feeErr?.message);
			}
		}
	} catch (err) {
		await releaseSpend(reservation.reservationId);
		// A message too large for Solana's packet limit now surfaces here (compile
		// happens inside submitProtected): keep the actionable 413 rather than 502.
		if (/too large|overruns/i.test(err?.message || '')) {
			return error(res, 413, 'launch_payload_too_large', 'token launch transaction exceeds Solana size limits — shorten the token name or metadata URI');
		}
		console.error('[pump/launch-agent] send failed', err);
		return respondError(res, 502, 'rpc_error', err);
	}

	const mintAddr = mint.toBase58();
	const onchainCreator = body.holder_reward
		? (await import('@pump-fun/pump-sdk')).holderRewardsPda(mint)
		: creator;
	const [row] = await sql`
		insert into pump_agent_mints
			(agent_id, user_id, network, mint, name, symbol, metadata_uri, agent_authority, buyback_bps, quote_mint)
		values
			(${resolvedAgentId}, ${user.id}, ${body.network}, ${mintAddr},
			 ${body.name}, ${body.symbol}, ${body.uri}, ${onchainCreator.toBase58()}, ${effBuyback}, ${quote.quoteMint ?? null})
		on conflict (mint, network) do nothing
		returning id, mint, network, buyback_bps, quote_mint, created_at
	`;

	// Finalize the spend reservation in place: merge the launch metadata + tx
	// signature into the reserved row and mark it confirmed. This replaces the
	// previous standalone insert: the reserved row already carries `solAmount`
	// (so the launch counts toward the daily cap, which the old `sol_buy_in`-keyed
	// row never did), and reusing it avoids double-recording the launch.
	await finalizeSpend(reservation.reservationId, {
		mint: mintAddr,
		name: body.name,
		symbol: body.symbol,
		uri: body.uri,
		signature,
		network: body.network,
		sol_buy_in: body.sol_buy_in || 0,
		usdc_buy_in: body.usdc_buy_in || 0,
		quote_mint: quote.quoteMint,
		quote_currency: quote.label,
		buyback_bps: effBuyback,
		coin_type: body.coin_type,
		holder_reward: body.holder_reward,
		platform_fee: launchFee ? { ...launchFee.disclosure, settlement: feeSettlement } : null,
		source: 'studio_agent_wallet',
	});

	// Bind the launch back to the agent's saved token plan, if it launched from
	// one: the plan flips to 'launched' and records the mint, so the profile stops
	// advertising a coin that now exists and starts rendering its market instead.
	// A launch configured inline (no saved plan) writes nothing and is unaffected.
	await markPlanLaunched({ agentId: resolvedAgentId, network: body.network, mint: mintAddr });

	// Surface the confirmed agent-wallet launch on the site-wide live activity ticker.
	publishFeedEvent({
		type: 'coin-buy',
		ts: Date.now(),
		actor: shortAddr(creator.toBase58()),
		mint: mintAddr,
		sol: body.sol_buy_in || 0,
		network: body.network,
		branded: hasThreeWsMark(mintAddr),
	}).catch(() => {});

	return json(res, 201, {
		ok: true,
		agent_id: resolvedAgentId,
		mint: mintAddr,
		signature,
		network: body.network,
		buyback_bps: effBuyback,
		coin_type: body.coin_type,
		holder_reward: body.holder_reward,
		quote_mint: quote.quoteMint,
		quote_currency: quote.label,
		pump_agent_mint: row || null,
		platform_fee: launchFee ? { ...launchFee.disclosure, settlement: feeSettlement } : null,
		buyback_available: buybackAvailable,
		explorer: `https://solscan.io/tx/${signature}${body.network === 'devnet' ? '?cluster=devnet' : ''}`,
		pumpfun_url: `https://pump.fun/coin/${mintAddr}`,
	});
}

// ── accept-payment-prep ────────────────────────────────────────────────────

const acceptPaymentPrepSchema = z.object({
	mint: z.string().min(32).max(44), // pump.fun token mint = agent token
	payer_wallet: z.string().min(32).max(44),
	amount_usdc: z.number().positive().max(100_000),
	currency_mint: z.string().min(32).max(44).optional(), // defaults to USDC
	currency_token_program: z.string().min(32).max(44).optional(),
	user_token_account: z.string().min(32).max(44), // payer ATA
	skill_id: z.string().max(100).optional(),
	tool_name: z.string().max(100).optional(),
	duration_seconds: z
		.number()
		.int()
		.positive()
		.max(60 * 60 * 24 * 365)
		.default(60),
	network: z.enum(['mainnet', 'devnet']).default('mainnet'),
});

function bnFromBigint(BN, v) {
	return new BN(v.toString());
}

async function handleAcceptPaymentPrep(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	// Session users (browser) and bearer (MCP / agent) callers both allowed.
	// Routed through resolveAuth() rather than a bare getSessionUser() so the
	// cookie path has to prove same-site intent: this POST writes a pending
	// invoice row under the caller's identity, which is exactly the cookie-borne
	// write the same-site rule exists for. Bearer callers stay exempt.
	const auth = await resolveAuth(req);
	if (!auth) return error(res, 401, 'unauthorized', 'sign in or supply a bearer token');
	const userId = auth.userId;

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

	const body = parse(acceptPaymentPrepSchema, await readJson(req));
	const payer = solanaPubkey(body.payer_wallet);
	const userAta = solanaPubkey(body.user_token_account);
	if (!payer) return error(res, 400, 'validation_error', 'invalid payer_wallet');
	if (!userAta) return error(res, 400, 'validation_error', 'invalid user_token_account');

	const [agent] = await sql`
		select id, mint, network, buyback_bps from pump_agent_mints
		where mint=${body.mint} and network=${body.network} limit 1
	`;
	if (!agent) return error(res, 404, 'not_found', 'agent mint not registered');

	const currencyStr =
		body.currency_mint ||
		(body.network === 'devnet' ? SOLANA_USDC_MINT_DEVNET : SOLANA_USDC_MINT);
	const currency = solanaPubkey(currencyStr);
	if (!currency) return error(res, 400, 'validation_error', 'invalid currency_mint');

	const { offline, BN } = await getPumpAgentOffline({
		network: body.network,
		mint: body.mint,
	});

	// Invoice ID = random 64-bit unsigned (memo BN). Used as the PDA seed and
	// as the X402 receipt identifier downstream.
	const invoiceIdHex = (await randomToken(8)).slice(0, 16);
	const invoiceId = new BN(invoiceIdHex, 16);

	const startTime = Math.floor(Date.now() / 1000);
	const endTime = startTime + body.duration_seconds;

	const amountAtomics = toUsdcAtomics(body.amount_usdc); // bigint, USDC = 6 dp

	const tokenProgram = body.currency_token_program
		? solanaPubkey(body.currency_token_program)
		: undefined;

	const ix = await offline.acceptPayment({
		user: payer,
		userTokenAccount: userAta,
		currencyMint: currency,
		amount: bnFromBigint(BN, amountAtomics),
		memo: invoiceId,
		startTime: new BN(startTime),
		endTime: new BN(endTime),
		...(tokenProgram ? { tokenProgram } : {}),
	});

	const txBase64 = await buildUnsignedTxBase64({
		network: body.network,
		payer,
		instructions: [ix],
	});

	const [row] = await sql`
		insert into pump_agent_payments
			(mint_id, user_id, payer_wallet, currency_mint, amount_atomics,
			 invoice_id, start_time, end_time, status, skill_id, tool_name)
		values
			(${agent.id}, ${userId}, ${body.payer_wallet}, ${currencyStr},
			 ${amountAtomics.toString()}, ${invoiceId.toString()},
			 to_timestamp(${startTime}), to_timestamp(${endTime}),
			 'pending', ${body.skill_id || null}, ${body.tool_name || null})
		returning id, invoice_id, start_time, end_time, status
	`;

	return json(res, 201, {
		payment_id: row.id,
		mint: body.mint,
		invoice_id: invoiceId.toString(),
		amount_usdc: body.amount_usdc,
		amount_atomics: amountAtomics.toString(),
		currency_mint: currencyStr,
		start_time: row.start_time,
		end_time: row.end_time,
		network: body.network,
		tx_base64: txBase64,
		instructions:
			'Decode tx_base64, sign with payer wallet, submit, then call /api/pump/accept-payment-confirm with the tx_signature and payment_id.',
	});
}

// ── accept-payment-confirm ─────────────────────────────────────────────────

const acceptPaymentConfirmSchema = z.object({
	payment_id: z.string().uuid(),
	tx_signature: z.string().min(80).max(100),
});

async function handleAcceptPaymentConfirm(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	// Same same-site rule as accept-payment-prep: this POST settles an invoice
	// and can flip a payment row to 'failed', so the cookie path must prove
	// intent. Bearer callers stay exempt.
	const auth = await resolveAuth(req);
	if (!auth) return error(res, 401, 'unauthorized', 'auth required');

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

	const body = parse(acceptPaymentConfirmSchema, await readJson(req));
	const [payment] = await sql`
		select p.*, m.mint, m.network from pump_agent_payments p
		join pump_agent_mints m on m.id = p.mint_id
		where p.id=${body.payment_id} limit 1
	`;
	if (!payment) return error(res, 404, 'not_found', 'payment not found');
	if (payment.status === 'confirmed')
		return error(res, 409, 'already_confirmed', 'payment already confirmed');

	// One signature confirms one invoice. Reject a signature already consumed by
	// another payment before doing any on-chain work (the partial unique index
	// pump_agent_payments_tx_signature_unique is the hard backstop).
	const [sigDupe] = await sql`
		select id from pump_agent_payments
		where tx_signature=${body.tx_signature} and status='confirmed' and id != ${payment.id} limit 1
	`;
	if (sigDupe)
		return error(
			res,
			409,
			'tx_already_used',
			'this transaction already confirmed another payment',
		);

	let tx;
	try {
		tx = await verifySignature({ network: payment.network, signature: body.tx_signature });
	} catch (e) {
		await sql`update pump_agent_payments set status='failed' where id=${payment.id}`;
		return error(res, e.status || 422, e.code || 'tx_failed', e.message);
	}

	const accountKeys = tx.transaction.message.accountKeys.map((k) => (k.pubkey || k).toString());
	if (!accountKeys.includes(payment.mint)) {
		return error(res, 422, 'mint_not_in_tx', 'agent mint not in tx accounts');
	}

	// The declared payer must have signed the tx: a signature that didn't
	// involve this payer can't satisfy this invoice.
	const signed = tx.transaction.message.accountKeys.some(
		(k) => (k.pubkey || k).toString() === payment.payer_wallet && k.signer === true,
	);
	if (!signed)
		return error(res, 422, 'payer_not_signer', 'declared payer did not sign the transaction');

	// Verify the agent's payment vault was actually credited the invoiced amount
	// of the invoiced currency. Without this, "the mint pubkey appears in the tx"
	// is not proof of payment: any cheap unrelated tx referencing the mint would
	// pass. The vault is the ATA owned by the TokenAgentPayments PDA for this mint.
	const { agentPda } = await getPumpAgentOffline({
		network: payment.network,
		mint: payment.mint,
	});
	if (!agentPda) {
		return error(
			res,
			503,
			'verification_unavailable',
			'unable to derive agent payment vault for verification',
		);
	}
	const vaultOwner = agentPda.toString();
	const expectedAtomics = BigInt(payment.amount_atomics);
	const post = tx.meta?.postTokenBalances || [];
	const pre = tx.meta?.preTokenBalances || [];
	let credited = 0n;
	for (const p of post) {
		if (p.mint !== payment.currency_mint) continue;
		if (p.owner !== vaultOwner) continue;
		const before = pre.find((b) => b.accountIndex === p.accountIndex);
		const delta =
			BigInt(p.uiTokenAmount?.amount ?? '0') - BigInt(before?.uiTokenAmount?.amount ?? '0');
		if (delta > credited) credited = delta;
	}
	if (credited < expectedAtomics) {
		await sql`update pump_agent_payments set status='failed' where id=${payment.id}`;
		return error(
			res,
			422,
			'amount_not_credited',
			'transaction did not credit the invoiced amount to the agent payment vault',
		);
	}

	try {
		await sql`
			update pump_agent_payments
			set status='confirmed', tx_signature=${body.tx_signature}, confirmed_at=now()
			where id=${payment.id} and status != 'confirmed'
		`;
	} catch (e) {
		if (e?.code === '23505')
			return error(
				res,
				409,
				'tx_already_used',
				'this transaction already confirmed another payment',
			);
		throw e;
	}

	return json(res, 200, {
		ok: true,
		payment_id: payment.id,
		invoice_id: payment.invoice_id,
		tx_signature: body.tx_signature,
	});
}

// ── payments-list ──────────────────────────────────────────────────────────

async function handlePaymentsList(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['GET'])) return;

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

	const url = new URL(req.url, `http://${req.headers.host}`);
	const mint = url.searchParams.get('mint');
	const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
	const limit = readLimit(url, 50, 500);
	const wantsPending = url.searchParams.get('include_pending') === '1';

	// Pending payments expose unconfirmed invoices: require auth.
	if (wantsPending) {
		const auth = await resolveAuth(req);
		if (!auth) return error(res, 401, 'unauthorized', 'sign in required to view pending payments');
	}
	const includePending = wantsPending;

	if (!mint) return error(res, 400, 'validation_error', 'mint required');

	const [agent] = await sql`
		select id, mint, network, buyback_bps from pump_agent_mints
		where mint=${mint} and network=${network} limit 1
	`;
	if (!agent) return error(res, 404, 'not_found', 'agent mint not registered');

	const rows = includePending
		? await sql`
			select id, payer_wallet, currency_mint, amount_atomics, invoice_id,
			       start_time, end_time, status, skill_id, tool_name,
			       invoice_pda, tx_signature, created_at, confirmed_at
			from pump_agent_payments
			where mint_id=${agent.id}
			order by created_at desc limit ${limit}
		`
		: await sql`
			select id, payer_wallet, currency_mint, amount_atomics, invoice_id,
			       start_time, end_time, status, skill_id, tool_name,
			       invoice_pda, tx_signature, created_at, confirmed_at
			from pump_agent_payments
			where mint_id=${agent.id} and status='confirmed'
			order by confirmed_at desc nulls last limit ${limit}
		`;

	// Derive invoice PDAs for any rows that lack one (older rows pre-PDA backfill).
	// We do it lazily here so the widget can deep-link without a backfill cron.
	let pdaErrored = false;
	const needsPda = rows.filter((r) => !r.invoice_pda && r.invoice_id);
	if (needsPda.length > 0) {
		try {
			const [{ getInvoiceIdPDA }, { PublicKey }] = await Promise.all([
				import('@three-ws/agent-payments'),
				import('@solana/web3.js'),
			]);
			const BN = (await import('bn.js')).default || (await import('bn.js'));
			const mintPk = new PublicKey(mint);
			for (const r of needsPda) {
				try {
					const [pda] = getInvoiceIdPDA(mintPk, new BN(r.invoice_id));
					r.invoice_pda = pda.toBase58();
				} catch {
					/* skip individual failures */
				}
			}
		} catch {
			pdaErrored = true;
		}
	}

	const [agg] = await sql`
		select
			count(*)::int                                                      as total,
			count(*) filter (where status='confirmed')::int                    as confirmed,
			count(distinct payer_wallet) filter (where status='confirmed')::int as unique_payers,
			coalesce(sum(amount_atomics) filter (where status='confirmed'), 0)::text as total_atomics
		from pump_agent_payments where mint_id=${agent.id}
	`;

	return json(res, 200, {
		mint,
		network,
		buyback_bps: agent.buyback_bps,
		summary: agg,
		data: rows,
	});
}

// ── portfolio ──────────────────────────────────────────────────────────────

async function handlePortfolio(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['GET'])) return;

	const auth = await resolveAuth(req);
	if (!auth) return error(res, 401, 'unauthorized', 'sign in required');

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

	const url = new URL(req.url, `http://${req.headers.host}`);
	const agentId = url.searchParams.get('agentId');
	const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
	if (!agentId) return error(res, 400, 'validation_error', 'agentId required');
	if (!isUuid(agentId)) return error(res, 404, 'not_found', 'agent not found');

	const [agent] = await sql`
		SELECT user_id, meta FROM agent_identities
		WHERE id = ${agentId} AND deleted_at IS NULL
	`;
	if (!agent) return error(res, 404, 'not_found', 'agent not found');
	if (agent.user_id !== auth.userId) return error(res, 403, 'forbidden', 'not your agent');
	const address = agent.meta?.solana_address;
	if (!address) return error(res, 409, 'conflict', 'agent has no solana wallet');

	const conn = solanaConnection(network);
	const owner = new PublicKey(address);

	// Each chain leg settles on its own: a throttled getBalance must not throw
	// away a successful token-account read (or vice versa). A failed leg is
	// named in `degraded` and the response carries `partial: true`; only when
	// BOTH chain legs fail is there nothing honest to render.
	const [lamportsRead, tokenRead, tradeRows, recentBuys] = await Promise.allSettled([
		conn.getBalance(owner),
		conn.getParsedTokenAccountsByOwner(owner, { programId: TOKEN_PROGRAM_ID }),
		// Quote-aware cost basis from the trade ledger: net quote spent (buys −
		// sells) per mint, in the quote asset's own atomic units, grouped by quote
		// so SOL and USDC are never summed together.
		sql`
			SELECT pam.mint, t.quote_symbol,
			       COALESCE(SUM(CASE WHEN t.direction='buy'  THEN t.quote_amount ELSE 0 END), 0)::text AS buy_quote,
			       COALESCE(SUM(CASE WHEN t.direction='sell' THEN t.quote_amount ELSE 0 END), 0)::text AS sell_quote
			FROM pump_agent_trades t
			JOIN pump_agent_mints pam ON pam.id = t.mint_id
			WHERE t.wallet = ${address} AND t.network = ${network}
			GROUP BY pam.mint, t.quote_symbol
		`.catch(() => []),
		// Legacy fallback for SOL coins whose buys predate the trade ledger.
		sql`
			SELECT payload FROM agent_actions
			WHERE agent_id = ${agentId}
			  AND type IN ('pumpfun.buy', 'buy')
			ORDER BY created_at DESC
			LIMIT 500
		`.catch(() => []),
	]).then((settled) => settled.map((r) => (r.status === 'fulfilled' ? r.value : r)));

	const degraded = [];
	if (lamportsRead?.status === 'rejected') degraded.push('balance');
	if (tokenRead?.status === 'rejected') degraded.push('token_accounts');
	if (degraded.length === 2) {
		console.warn(`[pump/portfolio] both chain legs failed agentId=${agentId}: ${lamportsRead.reason?.message || lamportsRead.reason}`);
		res.setHeader('Retry-After', '15');
		return error(res, 503, 'rpc_unavailable', 'Solana RPC is temporarily unavailable, retry shortly', { retry_after: 15 });
	}
	const lamports = lamportsRead?.status === 'rejected' ? null : lamportsRead;
	const tokenResp = tokenRead?.status === 'rejected' ? { value: [] } : tokenRead;

	const holdings = tokenResp.value
		.map((acc) => {
			const info = acc.account.data.parsed.info;
			return {
				mint: info.mint,
				amount: info.tokenAmount.uiAmount ?? 0,
				decimals: info.tokenAmount.decimals,
			};
		})
		.filter((h) => h.amount > 0);

	// Atomic→UI divisor per quote asset (lamports for SOL, 6-dec for USDC).
	const QUOTE_ATOMS = { SOL: 1e9, USDC: 1e6 };

	// Cost basis + quote asset per mint from the quote-aware trade ledger.
	const basisByMint = new Map(); // mint -> { quoteSymbol, costBasis }
	for (const r of tradeRows) {
		const quoteSymbol = r.quote_symbol || 'SOL';
		const net = BigInt(r.buy_quote || '0') - BigInt(r.sell_quote || '0');
		const div = QUOTE_ATOMS[quoteSymbol] ?? null;
		basisByMint.set(r.mint, {
			quoteSymbol,
			costBasis: div != null ? Number(net) / div : null,
		});
	}
	// Supplement SOL basis from legacy agent_actions only for mints with no ledger
	// rows: keeps historical portfolios intact without double-counting.
	for (const row of recentBuys) {
		const p = row.payload || {};
		if (!p.mint || basisByMint.has(p.mint)) continue;
		const prev = basisByMint.get(p.mint) ?? { quoteSymbol: 'SOL', costBasis: 0 };
		prev.costBasis = (prev.costBasis ?? 0) + (Number(p.amountSol) || 0);
		basisByMint.set(p.mint, prev);
	}

	// Authoritative quote asset for held agent coins not seen in the ledger.
	const unknownMints = holdings.map((h) => h.mint).filter((m) => !basisByMint.has(m));
	const quoteByMint = new Map();
	if (unknownMints.length) {
		const mintRows = await sql`
			SELECT mint, quote_mint FROM pump_agent_mints
			WHERE network = ${network} AND mint = ANY(${unknownMints})
		`.catch(() => []);
		for (const r of mintRows) {
			quoteByMint.set(r.mint, tradeQuoteColumns({ quoteMint: r.quote_mint, network }).quote_symbol);
		}
	}

	// Live price per holding via the read-only pump-fun MCP (parallelized).
	const rt = makeRuntime();
	const priced = await Promise.all(
		holdings.map(async (h) => {
			const curve = await rt
				.invoke('pump-fun.getBondingCurve', { mint: h.mint })
				.catch(() => ({ ok: false }));
			const basis = basisByMint.get(h.mint);
			const quoteSymbol = basis?.quoteSymbol ?? quoteByMint.get(h.mint) ?? 'SOL';
			// A bonding-curve price is quote-per-token in the coin's OWN quote unit
			// (SOL/token for SOL-paired, USDC/token for USDC-paired), so value and
			// cost basis are always expressed in the same currency.
			const priceQuote = curve?.ok ? (curve.data?.priceSol ?? curve.data?.price ?? null) : null;
			const valueQuote = priceQuote != null ? priceQuote * h.amount : null;
			const costBasis = basis?.costBasis ?? null;
			const unrealized =
				valueQuote != null && costBasis != null ? valueQuote - costBasis : null;
			const isSol = quoteSymbol === 'SOL';
			return {
				...h,
				quoteSymbol,
				priceQuote,
				valueQuote,
				costBasis,
				unrealizedPnl: unrealized,
				unrealizedPnlPct:
					unrealized != null && costBasis > 0 ? (unrealized / costBasis) * 100 : null,
				// Backward-compat SOL-named fields, populated only for SOL-paired
				// coins so existing consumers never read a USDC figure as SOL.
				priceSol: isSol ? priceQuote : null,
				valueSol: isSol ? valueQuote : null,
				costBasisSol: isSol ? costBasis : null,
				unrealizedPnlSol: isSol ? unrealized : null,
			};
		}),
	);

	// Per-quote subtotals: the fix for summing mismatched units. Each quote
	// asset (SOL, USDC, …) gets its own value / cost-basis / PnL totals.
	const subtotals = {};
	for (const p of priced) {
		const s = (subtotals[p.quoteSymbol] ??= {
			quoteSymbol: p.quoteSymbol,
			positions: 0,
			value: 0,
			costBasis: 0,
			unrealizedPnl: 0,
			unrealizedPnlPct: null,
		});
		s.positions += 1;
		s.value += p.valueQuote ?? 0;
		s.costBasis += p.costBasis ?? 0;
	}
	for (const s of Object.values(subtotals)) {
		s.unrealizedPnl = s.value - s.costBasis;
		s.unrealizedPnlPct = s.costBasis > 0 ? (s.unrealizedPnl / s.costBasis) * 100 : null;
	}

	// Top-level SOL totals stay backward-compatible: now scoped to SOL-paired
	// holdings only (no cross-unit summing).
	const solSub = subtotals.SOL ?? { value: 0, costBasis: 0 };
	const totalValueSol = solSub.value;
	const totalCostBasisSol = solSub.costBasis;
	const unrealizedPnlSol = totalValueSol - totalCostBasisSol;

	return json(res, 200, {
		data: {
			address,
			network,
			lamports,
			sol: lamports == null ? null : lamports / LAMPORTS_PER_SOL,
			holdings: priced,
			subtotals,
			...(degraded.length ? { partial: true, degraded } : {}),
			totalValueSol,
			totalCostBasisSol,
			unrealizedPnlSol,
			unrealizedPnlPct:
				totalCostBasisSol > 0 ? (unrealizedPnlSol / totalCostBasisSol) * 100 : null,
		},
	});
}

// ── launches ─────────────────────────────────────────────────────────────────
// Public, paginated feed of every coin launched through three.ws, joined with
// the agent that launched it. Powers the /launches page and the agent-detail
// "launched coins" card. Anonymous-readable; avatar thumbnails respect the
// same public/unlisted visibility gate as api/agents.js.

const LAUNCHES_CACHE = new Map(); // cacheKey → { at, body }
const LAUNCHES_TTL_MS = 15_000;

async function handleLaunches(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;

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

	const url = new URL(req.url, `http://${req.headers.host}`);
	const limit = Math.min(Math.max(1, Number(url.searchParams.get('limit')) || 24), 100);
	const offset = Math.max(0, Number(url.searchParams.get('offset')) || 0);
	const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
	const agentId = url.searchParams.get('agent_id');
	if (agentId && !isUuid(agentId))
		return error(res, 400, 'validation_error', 'agent_id must be a uuid');

	const minTierParam = url.searchParams.get('min_tier') || '';

	const cacheKey = `${network}:${agentId || ''}:${minTierParam}:${offset}:${limit}`;
	const now = Date.now();
	const hit = LAUNCHES_CACHE.get(cacheKey);
	if (hit && now - hit.at < LAUNCHES_TTL_MS) {
		res.setHeader('cache-control', 'public, max-age=15');
		return json(res, 200, hit.body);
	}

	// Query + row-shaping lives in api/_lib/pump-agent-launches.js, shared with
	// the free GET /api/v1/pump/launches endpoint: one query, two doors.
	const { launches, has_more: hasMore } = await queryAgentLaunches({
		network,
		agentId,
		minTierParam,
		offset,
		limit,
	});

	const body = { data: { launches, has_more: hasMore, offset, limit, network, min_tier: minTierParam || null } };
	LAUNCHES_CACHE.set(cacheKey, { at: now, body });
	// Keep the per-instance cache bounded: feed pages only ever walk forward.
	if (LAUNCHES_CACHE.size > 200) {
		const oldest = LAUNCHES_CACHE.keys().next().value;
		LAUNCHES_CACHE.delete(oldest);
	}
	res.setHeader('cache-control', 'public, max-age=15');
	return json(res, 200, body);
}

// ── by-agent ───────────────────────────────────────────────────────────────

async function handleByAgent(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;

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

	const url = new URL(req.url, `http://${req.headers.host}`);
	const agentId = url.searchParams.get('agent_id');
	const avatarId = url.searchParams.get('avatar_id');
	if (!agentId && !avatarId)
		return error(res, 400, 'validation_error', 'agent_id or avatar_id required');
	if (agentId && !isUuid(agentId)) return error(res, 404, 'not_found', 'agent not found');
	if (avatarId && !isUuid(avatarId)) return error(res, 404, 'not_found', 'agent not found');

	// All coins this agent has launched, newest first. The newest one stays the
	// canonical `data` payload (stats, burns) for existing consumers; the full
	// list ships alongside as `coins` for the agent-page launch history.
	let rows;
	if (agentId) {
		rows = await sql`
			select pam.id, pam.mint, pam.network, pam.name, pam.symbol,
			       pam.buyback_bps, pam.agent_authority, pam.metadata_uri,
			       pam.sharing_config, pam.created_at
			from pump_agent_mints pam
			where pam.agent_id=${agentId}
			order by pam.created_at desc limit 50
		`;
	} else {
		rows = await sql`
			select pam.id, pam.mint, pam.network, pam.name, pam.symbol,
			       pam.buyback_bps, pam.agent_authority, pam.metadata_uri,
			       pam.sharing_config, pam.created_at
			from pump_agent_mints pam
			join agent_identities ai
			  on ai.id = pam.agent_id and ai.deleted_at is null
			where ai.avatar_id=${avatarId}
			order by pam.created_at desc limit 50
		`;
	}
	// Coins the agent launched on an EVM chain (Robinhood Chain through Pons)
	// live in fixed_supply_launches. They join the history list, never `data`,
	// whose payment and burn stats are pump.fun-mint specific.
	const evmRows = await sql`
		select f.mint, f.network, f.name, f.symbol, f.chain, f.venue, f.venue_url, f.image_url, f.created_at
		from fixed_supply_launches f
		${agentId ? sql`where f.agent_id = ${agentId}` : sql`join agent_identities ai on ai.id = f.agent_id and ai.deleted_at is null where ai.avatar_id = ${avatarId}`}
		  and f.chain <> 'solana'
		order by f.created_at desc limit 50
	`;
	const evmCoins = evmRows.map((r) => ({
		mint: r.mint,
		network: r.network,
		name: r.name,
		symbol: r.symbol,
		buyback_bps: 0,
		created_at: r.created_at,
		chain: r.chain,
		venue: r.venue,
		venue_url: r.venue_url || null,
		image_url: r.image_url || null,
	}));
	const [row] = rows;
	if (!row) return json(res, 200, { data: null, coins: evmCoins });
	const coins = rows
		.map((r) => ({
			mint: r.mint,
			network: r.network,
			name: r.name,
			symbol: r.symbol,
			buyback_bps: r.buyback_bps,
			created_at: r.created_at,
			chain: 'solana',
		}))
		.concat(evmCoins)
		.sort((a, b) => new Date(b.created_at) - new Date(a.created_at));

	const [stats] = await sql`
		select
			count(*) filter (where status='confirmed')::int                      as confirmed_payments,
			count(distinct payer_wallet) filter (where status='confirmed')::int  as unique_payers,
			coalesce(sum(amount_atomics) filter (where status='confirmed'),0)::text as total_atomics,
			max(confirmed_at) filter (where status='confirmed')                  as last_payment_at
		from pump_agent_payments where mint_id=${row.id}
	`;

	// Every column here counts CONFIRMED runs only. `last_burn_at` used to take a
	// bare max(created_at), so it reported the last time the buyback cron merely
	// looked: an agent with 12k `skipped` rows and zero burns answered
	// {runs: 0, total_burned: '0', last_burn_at: <minutes ago>}, and the dashboard
	// and passport rendered "last burn" for a burn that never happened.
	const [burnRow] = await sql`
		select
			count(*) filter (where status='confirmed')::int                       as runs,
			coalesce(sum(burn_amount) filter (where status='confirmed'),0)::text  as total_burned,
			max(created_at) filter (where status='confirmed')                     as last_burn_at
		from pump_buyback_runs where mint_id=${row.id}
	`;

	// Burns feed (separate from payments feed): recent confirmed buyback runs
	// for the dashboard / passport "🔥 burns" stream.
	const burnsFeed = await sql`
		select id, currency_mint, tx_signature, burn_amount, created_at
		from pump_buyback_runs
		where mint_id=${row.id} and status='confirmed'
		order by created_at desc
		limit 10
	`;

	return json(res, 200, {
		data: {
			...row,
			stats: stats || { confirmed_payments: 0, unique_payers: 0, total_atomics: '0' },
			burns: burnRow || { runs: 0, total_burned: '0' },
			burns_feed: burnsFeed,
		},
		coins,
	});
}

// ── quote ──────────────────────────────────────────────────────────────────

async function handleQuote(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;

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

	const url = new URL(req.url, `http://${req.headers.host}`);
	const mintStr = url.searchParams.get('mint');
	const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
	const direction = url.searchParams.get('direction') === 'sell' ? 'sell' : 'buy';
	const solRaw = url.searchParams.get('sol');
	const usdcRaw = url.searchParams.get('usdc');
	const tokenRaw = url.searchParams.get('token');
	const quoteMintRaw = url.searchParams.get('quote_mint');
	const slippageRaw = url.searchParams.get('slippage_bps');
	const slippageBps = Number.isFinite(Number(slippageRaw))
		? Math.max(0, Math.min(5000, Number(slippageRaw)))
		: 100;
	// AMM SDK pricing takes slippage as a PERCENT (1 = 1%): pump-trade-args.js.
	const slippagePct = slippagePercentFromBps(slippageBps);

	const mint = solanaPubkey(mintStr);
	if (!mint) return error(res, 400, 'validation_error', 'invalid mint');

	try {
		const { sdk, BN, web3 } = await getPumpSdk({ network });
		const {
			isLegacyQuoteMint,
			getBuyTokenAmountFromSolAmount,
			getSellSolAmountFromTokenAmount,
		} = await import('@pump-fun/pump-sdk');
		const LAMPORTS_PER_SOL_Q = web3.LAMPORTS_PER_SOL || 1_000_000_000;

		// Fetch bonding curve: exposes on-chain quote_mint for V2 coins.
		let curve = null;
		try {
			if (sdk.fetchBuyState) {
				const state = await sdk.fetchBuyState(mint, mint);
				curve = state.bondingCurve;
			} else if (sdk.fetchBondingCurve) {
				curve = await sdk.fetchBondingCurve(mint);
			}
		} catch {
			curve = null;
		}

		// Resolve quoteMint: explicit param > on-chain curve field > WSOL fallback.
		let quoteMintPk = quoteMintRaw
			? solanaPubkey(quoteMintRaw)
			: (curve?.quoteMint ?? solanaPubkey(WSOL_MINT));
		if (!quoteMintPk) quoteMintPk = solanaPubkey(WSOL_MINT);
		const isUsdcQuote = !isLegacyQuoteMint(quoteMintPk);
		const USDC_DECIMALS = 1_000_000;

		if (curve && !curve.complete) {
			const global = typeof sdk.fetchGlobal === 'function' ? await sdk.fetchGlobal() : null;
			const feeConfig =
				typeof sdk.fetchFeeConfig === 'function'
					? await sdk.fetchFeeConfig().catch(() => null)
					: null;
			let quote = null;

			if (direction === 'buy') {
				const quoteAmountRaw = isUsdcQuote ? usdcRaw : solRaw;
				if (quoteAmountRaw) {
					const quoteNum = Number(quoteAmountRaw);
					if (!(quoteNum > 0))
						return error(
							res,
							400,
							'validation_error',
							`${isUsdcQuote ? 'usdc' : 'sol'} must be > 0`,
						);
					const atomics = new BN(
						isUsdcQuote
							? Math.round(quoteNum * USDC_DECIMALS)
							: Math.floor(quoteNum * LAMPORTS_PER_SOL_Q),
					);
					const tokens = getBuyTokenAmountFromSolAmount({
						global,
						feeConfig,
						mintSupply: curve.tokenTotalSupply,
						bondingCurve: curve,
						amount: atomics,
					});
					quote = isUsdcQuote
						? {
								usdc_in: quoteNum,
								tokens_out: tokens.toString(),
								source: 'bonding_curve',
							}
						: {
								sol_in: quoteNum,
								tokens_out: tokens.toString(),
								source: 'bonding_curve',
							};
				}
			} else if (direction === 'sell' && tokenRaw) {
				const tokens = new BN(tokenRaw);
				const atomicsOut = getSellSolAmountFromTokenAmount({
					global,
					feeConfig,
					mintSupply: curve.tokenTotalSupply,
					bondingCurve: curve,
					amount: tokens,
				});
				quote = isUsdcQuote
					? {
							tokens_in: tokenRaw,
							usdc_out: Number(atomicsOut.toString()) / USDC_DECIMALS,
							source: 'bonding_curve',
						}
					: {
							tokens_in: tokenRaw,
							sol_out: Number(atomicsOut.toString()) / LAMPORTS_PER_SOL_Q,
							source: 'bonding_curve',
						};
			}

			return json(res, 200, {
				mint: mintStr,
				network,
				graduated: false,
				// SOL curves store quoteMint as PublicKey.default: surface wSOL.
				quote_mint: isUsdcQuote ? quoteMintPk.toString() : WSOL_MINT,
				bonding_curve: {
					real_quote_reserves:
						curve.realQuoteReserves?.toString?.() ??
						curve.realSolReserves?.toString?.() ??
						null,
					real_token_reserves: curve.realTokenReserves?.toString?.() ?? null,
					virtual_quote_reserves:
						curve.virtualQuoteReserves?.toString?.() ??
						curve.virtualSolReserves?.toString?.() ??
						null,
					virtual_token_reserves: curve.virtualTokenReserves?.toString?.() ?? null,
					complete: curve.complete ?? false,
				},
				platform_fee_bps: await effectivePumpFeeBps(),
				quote,
			});
		}

		// Post-graduation: canonical AMM pool. For USDC pairs use the quote-keyed PDA.
		let amm;
		try {
			amm = await getAmmPoolState({
				network,
				mint,
				quoteMint: isUsdcQuote ? quoteMintPk : null,
			});
		} catch (e) {
			if (e.code === 'pool_not_found') {
				return json(res, 200, {
					mint: mintStr,
					network,
					graduated: true,
					pool: null,
					quote: null,
					note: 'No bonding curve and no canonical AMM pool — token may not be a pump.fun mint or has not graduated yet',
				});
			}
			throw e;
		}

		const {
			pool,
			poolKey,
			baseReserve,
			quoteReserve,
			virtualQuoteReserves,
			effectiveQuoteReserve,
			baseMintAccount,
			globalConfig,
			feeConfig,
		} = amm;
		const ammSdk = await import('@pump-fun/pump-swap-sdk');
		// Resolved pool quoteMint tells us the definitive quote currency.
		const resolvedQuoteMintStr = pool.quoteMint?.toString?.() ?? quoteMintPk.toString();
		const resolvedIsUsdc = resolvedQuoteMintStr !== WSOL_MINT;
		const QUOTE_UNIT = resolvedIsUsdc ? USDC_DECIMALS : 1_000_000_000;
		let quote = null;

		if (direction === 'buy') {
			const quoteRaw = resolvedIsUsdc ? usdcRaw : solRaw;
			if (quoteRaw) {
				const quoteNum = Number(quoteRaw);
				if (!(quoteNum > 0))
					return error(
						res,
						400,
						'validation_error',
						`${resolvedIsUsdc ? 'usdc' : 'sol'} must be > 0`,
					);
				const atomics = new BN(Math.round(quoteNum * QUOTE_UNIT));
				const r = ammSdk.buyQuoteInput({
					quote: atomics,
					slippage: slippagePct,
					baseReserve,
					quoteReserve,
					virtualQuoteReserves,
					globalConfig,
					baseMintAccount,
					baseMint: pool.baseMint,
					quoteMint: pool.quoteMint,
					isMayhemMode: pool.isMayhemMode,
					creatorFeeBps: pool.creatorFeeBps,
					coinCreator: pool.coinCreator,
					creator: pool.creator,
					feeConfig,
				});
				// buyQuoteInput is a quote-input swap: slippage widens the max quote
				// spend (maxQuote), not a token floor: surface that real bound.
				const maxQuoteIn =
					r.maxQuote != null ? Number(r.maxQuote.toString()) / QUOTE_UNIT : null;
				quote = {
					...(resolvedIsUsdc ? { usdc_in: quoteNum } : { sol_in: quoteNum }),
					tokens_out: r.base?.toString?.() ?? null,
					...(resolvedIsUsdc ? { max_usdc_in: maxQuoteIn } : { max_sol_in: maxQuoteIn }),
					slippage_bps: slippageBps,
					source: 'amm',
				};
			}
		} else if (direction === 'sell' && tokenRaw) {
			const tokens = new BN(tokenRaw);
			const r = ammSdk.sellBaseInput({
				base: tokens,
				slippage: slippagePct,
				baseReserve,
				quoteReserve,
				virtualQuoteReserves,
				globalConfig,
				baseMintAccount,
				baseMint: pool.baseMint,
				quoteMint: pool.quoteMint,
				isMayhemMode: pool.isMayhemMode,
				creatorFeeBps: pool.creatorFeeBps,
				coinCreator: pool.coinCreator,
				creator: pool.creator,
				feeConfig,
			});
			const atomicsOut = r.uiQuote ?? r.minQuote;
			const minAtomicsOut = r.minQuote ?? r.uiQuote;
			const toUnit = (v) => (v != null ? Number(v.toString()) / QUOTE_UNIT : null);
			quote = {
				tokens_in: tokenRaw,
				...(resolvedIsUsdc
					? { usdc_out: toUnit(atomicsOut), min_usdc_out: toUnit(minAtomicsOut) }
					: { sol_out: toUnit(atomicsOut), min_sol_out: toUnit(minAtomicsOut) }),
				slippage_bps: slippageBps,
				source: 'amm',
			};
		}

		return json(res, 200, {
			mint: mintStr,
			network,
			graduated: true,
			quote_mint: resolvedQuoteMintStr,
			pool: {
				address: poolKey.toString(),
				base: pool.baseMint.toString(),
				quote: resolvedQuoteMintStr,
				base_reserve: baseReserve.toString(),
				quote_reserve: quoteReserve.toString(),
				// Price against `effective_quote_reserve`, not `quote_reserve`:
				// PumpSwap adds the pool's virtual quote reserves to the vault
				// balance when quoting (non-zero on launchpad coins since
				// 2026-07-20). The raw vault balance alone under-prices buys.
				virtual_quote_reserves: virtualQuoteReserves.toString(),
				effective_quote_reserve: effectiveQuoteReserve.toString(),
				lp_supply: pool.lpSupply?.toString?.() ?? null,
			},
			platform_fee_bps: await effectivePumpFeeBps(),
			quote,
		});
	} catch (err) {
		return respondError(res, err.status || 502, err.code || 'pump_sdk_error', err);
	}
}

// ── governance-prep ────────────────────────────────────────────────────────

const governancePrepSchema = z.object({
	mint: z.string().min(32).max(44),
	authority_wallet: z.string().min(32).max(44),
	new_buyback_bps: z.number().int().min(0).max(10_000),
	network: z.enum(['mainnet', 'devnet']).default('mainnet'),
});

async function handleGovernancePrep(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await getSessionUser(req);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

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

	const body = parse(governancePrepSchema, await readJson(req));
	const authority = solanaPubkey(body.authority_wallet);
	if (!authority) return error(res, 400, 'validation_error', 'invalid authority_wallet');

	const [row] = await sql`
		select id, user_id, agent_authority from pump_agent_mints
		where mint=${body.mint} and network=${body.network} limit 1
	`;
	if (!row) return error(res, 404, 'not_found', 'agent mint not registered');
	if (row.user_id !== user.id) return error(res, 403, 'forbidden', 'not your agent');
	if (row.agent_authority && row.agent_authority !== body.authority_wallet) {
		return error(res, 403, 'forbidden', 'authority does not match');
	}

	const { offline } = await getPumpAgentOffline({ network: body.network, mint: body.mint });
	const ix = await offline.updateBuybackBps(
		{ authority, buybackBps: body.new_buyback_bps },
		{}, // UpdateBuybackBpsOptions — empty default
	);

	const txBase64 = await buildUnsignedTxBase64({
		network: body.network,
		payer: authority,
		instructions: [ix],
	});

	return json(res, 201, {
		mint: body.mint,
		network: body.network,
		new_buyback_bps: body.new_buyback_bps,
		tx_base64: txBase64,
		instructions:
			'Sign with the agent authority wallet, submit, then optionally PATCH the local row via /api/agents/:id to refresh display.',
	});
}

// ── withdraw-prep ──────────────────────────────────────────────────────────

const withdrawPrepSchema = z.object({
	mint: z.string().min(32).max(44),
	authority_wallet: z.string().min(32).max(44),
	receiver_ata: z.string().min(32).max(44),
	currency_mint: z.string().min(32).max(44).optional(),
	currency_token_program: z.string().min(32).max(44).optional(),
	network: z.enum(['mainnet', 'devnet']).default('mainnet'),
});

async function handleWithdrawPrep(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const auth = await resolveAuth(req);
	if (!auth) return error(res, 401, 'unauthorized', 'sign in required');

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

	const body = parse(withdrawPrepSchema, await readJson(req));
	const authority = solanaPubkey(body.authority_wallet);
	const receiverAta = solanaPubkey(body.receiver_ata);
	if (!authority || !receiverAta) return error(res, 400, 'validation_error', 'invalid pubkeys');

	const [row] = await sql`
		select m.id, m.mint, m.user_id, m.agent_authority, m.network from pump_agent_mints m
		where m.mint=${body.mint} and m.network=${body.network} limit 1
	`;
	if (!row) return error(res, 404, 'not_found', 'agent mint not registered');
	if (row.user_id !== auth.userId) return error(res, 403, 'forbidden', 'not your agent');
	if (row.agent_authority && row.agent_authority !== body.authority_wallet) {
		return error(res, 403, 'forbidden', 'authority does not match');
	}

	const currencyStr =
		body.currency_mint ||
		(body.network === 'devnet' ? SOLANA_USDC_MINT_DEVNET : SOLANA_USDC_MINT);
	const currency = solanaPubkey(currencyStr);
	if (!currency) return error(res, 400, 'validation_error', 'invalid currency_mint');

	// An unparseable token program used to be dropped silently, which built a tx
	// against the default SPL program and only failed once the user had signed it.
	// Reject it here instead, where the caller can still fix the request.
	let tokenProgram;
	if (body.currency_token_program) {
		tokenProgram = solanaPubkey(body.currency_token_program);
		if (!tokenProgram) {
			return error(res, 400, 'validation_error', 'invalid currency_token_program');
		}
	}

	const { offline } = await getPumpAgentOffline({
		network: body.network,
		mint: body.mint,
	});

	const ix = await offline.withdraw({
		authority,
		currencyMint: currency,
		receiverAta,
		...(tokenProgram ? { tokenProgram } : {}),
	});

	const txBase64 = await buildUnsignedTxBase64({
		network: body.network,
		payer: authority,
		instructions: [ix],
	});

	return json(res, 201, {
		mint: body.mint,
		network: body.network,
		currency_mint: currencyStr,
		tx_base64: txBase64,
	});
}

// ── withdraw-confirm ───────────────────────────────────────────────────────

const withdrawConfirmSchema = z.object({
	mint: z.string().min(32).max(44),
	network: z.enum(['mainnet', 'devnet']).default('mainnet'),
	tx_signature: z.string().min(80).max(100),
});

async function handleWithdrawConfirm(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const auth = await resolveAuth(req);
	if (!auth) return error(res, 401, 'unauthorized', 'sign in required');

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

	const body = parse(withdrawConfirmSchema, await readJson(req));

	const [row] = await sql`
		select id, mint, user_id, agent_authority, network from pump_agent_mints
		where mint=${body.mint} and network=${body.network} limit 1
	`;
	if (!row) return error(res, 404, 'not_found', 'agent mint not registered');
	if (row.user_id !== auth.userId) return error(res, 403, 'forbidden', 'not your agent');

	let tx;
	try {
		tx = await verifySignature({ network: body.network, signature: body.tx_signature });
	} catch (e) {
		return error(res, e.status || 422, e.code || 'tx_failed', e.message);
	}

	// A versioned tx resolved through an address-lookup table can come back with
	// its account list under a different shape; treat a missing list as "no match"
	// rather than letting `.map` throw the whole confirm into a 500.
	const accountKeys = (tx.transaction?.message?.accountKeys || []).map((k) =>
		(k.pubkey || k).toString(),
	);
	if (!accountKeys.includes(body.mint)) {
		return error(res, 422, 'mint_not_in_tx', 'mint not present in tx accounts');
	}
	if (row.agent_authority && !accountKeys.includes(row.agent_authority)) {
		return error(res, 422, 'authority_not_in_tx', 'agent authority not present in tx');
	}
	// Account presence alone is not a payout: any succeeded transfer or memo that
	// touches the mint and the authority satisfies it. Require that the
	// agent-payments program actually ran before reporting a confirmed withdrawal.
	if (!txInvokesAgentPaymentsProgram(tx)) {
		return error(
			res,
			422,
			'not_a_withdrawal',
			'tx did not invoke the agent-payments program',
		);
	}

	return json(res, 200, {
		ok: true,
		mint: body.mint,
		network: body.network,
		tx_signature: body.tx_signature,
		slot: tx.slot ?? null,
		block_time: tx.blockTime ?? null,
	});
}

// ── strategy-backtest ──────────────────────────────────────────────────────

async function resolveStrategyMints(invoke, strategy, explicit, limit) {
	if (Array.isArray(explicit) && explicit.length) return explicit;
	const scan = strategy?.scan ?? {};
	if (scan.kind === 'mintList' && Array.isArray(scan.mints)) return scan.mints;
	const tool = scan.kind === 'trending' ? 'pump-fun.getTrendingTokens' : 'pump-fun.getNewTokens';
	const r = await invoke(tool, { limit: limit ?? scan.limit ?? 20 });
	if (!r.ok) throw new Error(`scan failed: ${r.error}`);
	const items = r.data?.tokens ?? r.data ?? [];
	return items.map((t) => t.mint ?? t.address).filter(Boolean);
}

async function handleStrategyBacktest(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const auth = await resolveAuth(req);
	if (!auth) return error(res, 401, 'unauthorized', 'sign in required');

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

	const body = await readJson(req);
	if (!body?.strategy) return error(res, 400, 'validation_error', 'strategy required');
	const network = body.network === 'devnet' ? 'devnet' : 'mainnet';

	const rt = makeRuntime();

	// Reject a semantically-broken spec up front with field-level issues, before
	// sourcing mints or replaying: same validator the validate endpoint uses.
	const vr = await rt.invoke('pump-fun-strategy.validateStrategy', {
		strategy: body.strategy,
		network,
		mintInfo: await resolveStrategyMintInfo(body.strategy?.scan?.mints, network),
	});
	if (vr.data && !vr.data.valid) {
		return error(res, 400, 'validation_error', vr.error || 'strategy is invalid', {
			issues: vr.data.issues,
			report: vr.data,
		});
	}

	let mints;
	try {
		mints = await resolveStrategyMints(rt.invoke, body.strategy, body.mints, body.limit);
	} catch (e) {
		return respondError(res, 502, 'upstream_error', e);
	}
	if (!mints.length) return error(res, 422, 'no_candidates', 'no mints to backtest');

	const { backtestStrategy } =
		await import('../../examples/skills/pump-fun-strategy/handlers.js');
	const result = await backtestStrategy(
		{ strategy: body.strategy, mints, sinceMs: body.sinceMs ?? 0 },
		{ skills: { invoke: rt.invoke }, memory: { note: () => {} } },
	);
	if (!result.ok) return error(res, 400, 'validation_error', result.error);
	return json(res, 200, { data: { ...result.data, mintsUsed: mints } });
}

// ── strategy-close-all ─────────────────────────────────────────────────────

async function handleStrategyCloseAll(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const auth = await resolveAuth(req, { spend: true, kind: 'trade' });
	if (!auth) return error(res, 401, 'unauthorized', 'sign in required');

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

	const body = await readJson(req);
	if (!body?.agentId) return error(res, 400, 'validation_error', 'agentId required');
	const network = body.network === 'devnet' ? 'devnet' : 'mainnet';

	const [row] = await sql`
		SELECT user_id, meta FROM agent_identities
		WHERE id = ${body.agentId} AND deleted_at IS NULL
	`;
	if (!row) return error(res, 404, 'not_found', 'agent not found');
	if (row.user_id !== auth.userId) return error(res, 403, 'forbidden', 'not your agent');
	const enc = row.meta?.encrypted_solana_secret;
	if (!enc) return error(res, 409, 'conflict', 'agent has no solana wallet');

	const wallet = await loadWallet(enc, {
		agentId: body.agentId,
		userId: auth.userId,
		reason: 'pump_close_all',
	});
	const rt = makeRuntime({
		wallet,
		agentId: body.agentId,
		signerAddress: wallet.publicKey.toBase58(),
		configOverrides: {
			'pump-fun-trade': { rpc: RPC[network] },
			'solana-wallet': { rpc: RPC[network] },
		},
	});

	const { closeAllPositions } =
		await import('../../examples/skills/pump-fun-strategy/handlers.js');
	const result = await closeAllPositions(
		{ mints: body.mints, simulate: !!body.simulate },
		{ skills: { invoke: rt.invoke }, wallet, memory: { note: () => {} } },
	);
	if (!result.ok) return error(res, 400, 'sell_failed', result.error);
	return json(res, 200, { data: result.data });
}

// ── strategy-run ───────────────────────────────────────────────────────────
// SSE: manages its own response writes; routed before wrap() above.

async function loadAgentWalletForStrategy(agentId, userId) {
	const [row] = await sql`
		SELECT user_id, meta FROM agent_identities
		WHERE id = ${agentId} AND deleted_at IS NULL
	`;
	if (!row) throw Object.assign(new Error('agent not found'), { status: 404 });
	if (row.user_id !== userId) throw Object.assign(new Error('not your agent'), { status: 403 });
	const enc = row.meta?.encrypted_solana_secret;
	if (!enc)
		throw Object.assign(
			new Error('agent has no solana wallet — provision via /api/agents/:id/solana'),
			{ status: 409 },
		);
	const wallet = await loadWallet(enc, { agentId, userId, reason: 'pump_strategy' });
	return { wallet, address: wallet.publicKey.toBase58(), meta: row.meta };
}

async function handleStrategyRun(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

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

	let body;
	try {
		body = await readJson(req);
	} catch (e) {
		return error(res, 400, 'validation_error', e.message);
	}

	if (!body?.strategy) return error(res, 400, 'validation_error', 'strategy required');
	const durationSec = Math.max(5, Math.min(600, Number(body.durationSec) || 30));
	const mode = body.mode === 'live' ? 'live' : 'simulate';
	const network = body.network === 'devnet' ? 'devnet' : 'mainnet';

	// Pre-flight semantic validation BEFORE switching to SSE, so a broken spec
	// (or a quote-asset mismatch on a listed coin) is rejected with a clean JSON
	// error rather than streaming a doomed run. Same validator the validate
	// endpoint and the runner use: they cannot disagree.
	{
		const mintInfo = await resolveStrategyMintInfo(body.strategy?.scan?.mints, network);
		const vr = await makeRuntime().invoke('pump-fun-strategy.validateStrategy', {
			strategy: body.strategy,
			network,
			mintInfo,
		});
		if (vr.data && !vr.data.valid) {
			return error(res, 400, 'validation_error', vr.error || 'strategy is invalid', {
				issues: vr.data.issues,
				report: vr.data,
			});
		}
	}

	let wallet = null,
		walletAddress = null,
		agentMeta = null,
		agentOwnerId = null;
	if (mode === 'live') {
		// This handler is not behind wrap(), so a refusal thrown by resolveAuth
		// (cross-site cookie, bearer without wallet:write) is answered here.
		let auth;
		try {
			auth = await resolveAuth(req, { spend: true, kind: 'trade' });
		} catch (e) {
			return error(res, e.status || 403, e.code || 'forbidden', e.message);
		}
		if (!auth) return error(res, 401, 'unauthorized', 'sign in required for live mode');
		if (!body.agentId)
			return error(res, 400, 'validation_error', 'agentId required for live mode');
		if (!(await requireRealFundsAgreement(req, res, { userId: auth.userId, network, context: 'pump-strategy-run' }))) return;
		try {
			const r = await loadAgentWalletForStrategy(body.agentId, auth.userId);
			wallet = r.wallet;
			walletAddress = r.address;
			agentMeta = r.meta;
			agentOwnerId = auth.userId;
		} catch (e) {
			return error(
				res,
				e.status ?? 500,
				e.status === 409 ? 'conflict' : 'unauthorized',
				e.message,
			);
		}
	}

	res.statusCode = 200;
	res.setHeader('content-type', 'text/event-stream');
	res.setHeader('cache-control', 'no-cache, no-transform');
	res.setHeader('connection', 'keep-alive');
	res.setHeader('access-control-allow-origin', '*');
	const send = (event, data) => {
		res.write(`event: ${event}\n`);
		res.write(`data: ${JSON.stringify(data)}\n\n`);
	};

	let aborted = false;
	req.on('close', () => {
		aborted = true;
	});

	const spendGuard =
		mode === 'live' ? createStrategySpendGuard({ agentId: body.agentId, meta: agentMeta, userId: agentOwnerId }) : null;
	const rt = makeRuntime({
		wallet,
		agentId: mode === 'live' ? body.agentId : undefined,
		signerAddress: walletAddress,
		// Live buys are recorded by the spend reservation (finalizeSpend), so the
		// runtime must not persist a second pumpfun.buy row for the same trade.
		shouldPersist: (skillName, tag) => !(spendGuard && skillName === 'pump-fun-trade' && tag === 'pump-fun-trade:buy'),
		configOverrides: {
			'pump-fun-trade': { rpc: RPC[network] },
			'solana-wallet': { rpc: RPC[network] },
		},
		onEvent: (e) => send('memory', e),
	});

	send('start', { durationSec, mode, network, walletAddress });

	const { runStrategy } = await import('../../examples/skills/pump-fun-strategy/handlers.js');
	const ctx = {
		skills: { invoke: rt.invoke },
		skillConfig: { defaultPollMs: Math.max(1500, Number(body.pollMs) || 3000) },
		memory: { note: (tag, value) => send('memory', { tag, value }) },
		wallet,
	};

	const policyGuard = spendGuard ? spendGuard.guard : null;
	const policySettle = spendGuard ? spendGuard.settle : null;

	const abortController = new AbortController();
	req.on('close', () => abortController.abort());

	try {
		const result = await runStrategy(
			{
				strategy: body.strategy,
				durationSec,
				simulate: mode === 'simulate',
				onLog: (entry) => {
					if (!aborted) send('log', entry);
				},
				policyGuard,
				policySettle,
				abortSignal: abortController.signal,
			},
			ctx,
		);
		send('done', result.data);
	} catch (e) {
		send('error', { message: e.message });
	}
	res.end();
}

// ── live-stream ────────────────────────────────────────────────────────────
// SSE: fans out the PumpPortal WebSocket feed to browser clients.
// Routed before wrap() above. No auth; rate-limited by IP.

const liveStreamKindSchema = z.enum(['all', 'mint', 'graduation']).default('all');

async function handleLiveStream(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;

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

	const url = new URL(req.url, `http://${req.headers.host}`);
	let kind;
	try {
		kind = liveStreamKindSchema.parse(url.searchParams.get('kind') ?? undefined);
	} catch {
		return error(res, 400, 'validation_error', 'kind must be all, mint, or graduation');
	}

	res.statusCode = 200;
	res.setHeader('content-type', 'text/event-stream; charset=utf-8');
	res.setHeader('cache-control', 'no-cache, no-transform');
	res.setHeader('connection', 'keep-alive');
	res.setHeader('x-accel-buffering', 'no');

	// EventSource auto-reconnects when the stream ends; hint a 1s backoff so the
	// rotation below is near-seamless rather than the browser's ~3s default.
	res.write('retry: 1000\n\n');

	const ping = setInterval(() => {
		if (!res.writableEnded) res.write(': ping\n\n');
	}, 15_000);

	// Rotate the stream a few seconds BEFORE the Vercel function maxDuration
	// (60s: see vercel.json → functions["api/pump/[action].js"]). Ending the
	// response ourselves emits a clean `end` event and lets EventSource
	// reconnect; letting Vercel hit the hard limit instead kills the function
	// and logs a "Task timed out" error on every long-lived client connection.
	const STREAM_BUDGET_MS = 55_000;
	const maxDuration = setTimeout(() => {
		clearInterval(ping);
		stop?.();
		if (!res.writableEnded) {
			res.write(`event: end\ndata: ${JSON.stringify({ reason: 'rotate' })}\n\n`);
			res.end();
		}
	}, STREAM_BUDGET_MS);

	const stop = connectPumpFunFeed({
		kind,
		onEvent({ kind: evtKind, data }) {
			if (!res.writableEnded) {
				res.write(`event: ${evtKind}\ndata: ${JSON.stringify(data)}\n\n`);
			}
		},
	});

	req.on('close', () => {
		clearInterval(ping);
		clearTimeout(maxDuration);
		stop();
		if (!res.writableEnded) res.end();
	});
}

// ── strategy-validate ──────────────────────────────────────────────────────

// Resolve authoritative agent-coin facts (existence + quote pairing) for the
// mints a strategy explicitly lists. pump_agent_mints is the only place a
// three.ws coin's quote asset is reliably known (the on-chain bonding curve
// read does not surface it). Returns a map keyed by mint, or null on DB error
// (the handler then falls back to an on-chain existence probe).
async function resolveStrategyMintInfo(mints, network) {
	const listed = Array.isArray(mints)
		? [...new Set(mints.filter((m) => typeof m === 'string' && m.trim()).map((m) => m.trim()))]
		: [];
	if (!listed.length) return null;
	try {
		const rows = await sql`
			SELECT mint, quote_mint FROM pump_agent_mints
			WHERE mint = ANY(${listed}) AND network = ${network}
		`;
		const info = {};
		for (const row of rows) {
			const q = classifyLaunchQuote({ quoteMint: row.quote_mint, network });
			info[row.mint] = { isAgentCoin: true, quoteIsUsdc: q.isUsdc, quoteSymbol: q.label };
		}
		return info;
	} catch (e) {
		console.error('[strategy-validate] mint info lookup failed', e?.message);
		return null;
	}
}

async function handleStrategyValidate(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['POST'])) return;

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

	const body = await readJson(req);
	if (!body?.strategy || typeof body.strategy !== 'object') {
		return error(res, 400, 'validation_error', 'strategy required');
	}
	const network = body.network === 'devnet' ? 'devnet' : 'mainnet';

	const mintInfo = await resolveStrategyMintInfo(body.strategy?.scan?.mints, network);

	const rt = makeRuntime();
	const r = await rt.invoke('pump-fun-strategy.validateStrategy', {
		strategy: body.strategy,
		network,
		mintInfo,
	});
	const report = r.data ?? {
		valid: false,
		issues: [{ level: 'error', field: 'strategy', code: 'validate_failed', message: r.error || 'validation failed' }],
		errorCount: 1,
		warningCount: 0,
	};
	if (!report.valid) {
		return error(res, 400, 'validation_error', r.error || 'strategy is invalid', {
			issues: report.issues,
			report,
		});
	}
	return json(res, 200, { data: report });
}

// ── channel-feed ──────────────────────────────────────────────────────────────

async function handleChannelFeed(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;
	const rl = await limits.mcpIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);
	const url = new URL(req.url, `http://${req.headers.host}`);
	const limit = readLimit(url, 50, 200);
	const kinds = url.searchParams.get('kinds') || null;
	// `signal` is one of the four kinds buildFeed knows and the only one that
	// carries agent attribution (which agent earned the reputation event, and how
	// much it weighed). Leaving it out of the fan-out published a feed that could
	// never answer ?kinds=signal, so the whole agent-attributed lane was invisible.
	const { getMints, getWhales, getClaims, getSignals } = await import(
		'../_lib/channel-feed-sources.js'
	);
	const { buildFeed } = await import('../../src/pump/channel-feed.js');
	// buildFeed filters by kind after the fact; skipping the unrequested reads
	// here keeps ?kinds=mint to one query instead of four. It ignores a `kinds`
	// naming nothing valid and serves everything, so this must too, or the two
	// halves disagree and a typo'd filter returns an empty feed.
	const ALL_KINDS = ['mint', 'whale', 'claim', 'signal'];
	const named = kinds
		? kinds.split(',').map((k) => k.trim()).filter((k) => ALL_KINDS.includes(k))
		: [];
	const requested = named.length ? new Set(named) : null;
	const wants = (kind) => !requested || requested.has(kind);
	const [mints, whales, claims, signals] = await Promise.all([
		wants('mint') ? getMints(limit) : [],
		wants('whale') ? getWhales(limit) : [],
		wants('claim') ? getClaims(limit) : [],
		wants('signal') ? getSignals(limit) : [],
	]);
	const items = buildFeed(
		[
			{ kind: 'mint', items: mints },
			{ kind: 'whale', items: whales },
			{ kind: 'claim', items: claims },
			{ kind: 'signal', items: signals },
		],
		{ limit, kinds },
	);
	return json(res, 200, { items });
}

// ── trending / search (proxies for the CORS-protected pump.fun frontend API) ──

const PUMP_FRONTEND_BASE = 'https://frontend-api-v3.pump.fun';
const TRENDING_CACHE = { at: 0, body: null };
const TRENDING_TTL_MS = 15_000;

// pump.fun hands back image URLs on the retired cf-ipfs.com gateway, which no
// longer resolves in the browser. Repair the image fields onto a working
// gateway before the feed reaches any client (play lobby, home card, etc.).
function repairCoinImages(coins) {
	if (!Array.isArray(coins)) return coins;
	for (const c of coins) {
		if (!c || typeof c !== 'object') continue;
		if (c.image_uri) c.image_uri = normalizeGatewayURL(c.image_uri);
		if (c.image) c.image = normalizeGatewayURL(c.image);
		if (c.metadata_uri) c.metadata_uri = normalizeGatewayURL(c.metadata_uri);
	}
	return coins;
}

async function handleTrending(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;
	const rl = await limits.mcpIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);
	const now = Date.now();
	if (TRENDING_CACHE.body && now - TRENDING_CACHE.at < TRENDING_TTL_MS) {
		res.setHeader('cache-control', 'public, max-age=15');
		return json(res, 200, TRENDING_CACHE.body);
	}
	const url = new URL(req.url, `http://${req.headers.host}`);
	const limit = readLimit(url, 50, 100);
	const upstream = new URL('/coins', PUMP_FRONTEND_BASE);
	upstream.searchParams.set('offset', '0');
	upstream.searchParams.set('limit', String(limit));
	upstream.searchParams.set('sort', 'market_cap');
	upstream.searchParams.set('order', 'DESC');
	upstream.searchParams.set('includeNsfw', 'false');
	let resp;
	try {
		resp = await fetch(upstream, {
			headers: { accept: 'application/json' },
			signal: AbortSignal.timeout(8000),
		});
	} catch {
		// Upstream timeout/network blip: serve the last good list if we have one
		// rather than 500-ing the trending feed.
		if (TRENDING_CACHE.body) {
			res.setHeader('cache-control', 'public, max-age=15');
			return json(res, 200, TRENDING_CACHE.body);
		}
		return error(res, 504, 'upstream_timeout', 'pump.fun did not respond');
	}
	if (!resp.ok) return error(res, 502, 'upstream_failed', `pump.fun returned ${resp.status}`);
	// pump.fun can answer 200 with an empty/truncated body; resp.json() then throws
	// "Unexpected end of JSON input" → an unhandled 500. Fall back to the last good
	// list (or an empty feed) instead of crashing.
	let body;
	try {
		body = await resp.json();
	} catch {
		if (TRENDING_CACHE.body) {
			res.setHeader('cache-control', 'public, max-age=15');
			return json(res, 200, TRENDING_CACHE.body);
		}
		body = [];
	}
	const arr = repairCoinImages(
		Array.isArray(body) ? body : Array.isArray(body?.coins) ? body.coins : [],
	);
	TRENDING_CACHE.at = now;
	TRENDING_CACHE.body = arr;
	res.setHeader('cache-control', 'public, max-age=15');
	return json(res, 200, arr);
}

// ── coin ─────────────────────────────────────────────────────────────────────
// Live metadata for a single mint, proxied from pump.fun's frontend API
// (CORS-protected from the browser). Powers the /play lobby's pinned flagship
// town so its name/symbol/art/market-cap are always real and current, even when
// the coin isn't in the trending 30. Short-cached per mint to spare the upstream.

const COIN_CACHE = new Map(); // mint → { at, body }
const COIN_TTL_MS = 30_000;
// Shared last-good tier: a cold instance holds no COIN_CACHE, and pump.fun's
// frontend API rate-limits in windows longer than a request budget. The last
// body a healthy fetch produced is served marked stale until pump.fun answers.
const COIN_LKG_TTL_S = 24 * 3600;
const coinLkgKey = (mint) => `pump:coin:lkg:${mint}`;

// Third degrade tier for handleCoin, reached once both the in-memory cache and
// the 24h last-known-good copy are empty: pump.fun's own metadata is gone, but
// two real, first-party sources can still answer. Numeric/curve fields come
// from the on-chain bonding-curve reader already proven live behind
// /api/pump/curve (order 423); identity fields (name, symbol, creator) come
// from pump_agent_mints, the platform's own launch registry, for any mint
// three.ws itself launched. Neither source carries a stored image URL for a
// curve launch, so `image`/`image_uri` stay null rather than guessing.
// Returns null when neither source has anything, so the caller falls through
// to the honest 502.
async function fetchOnchainCoinDegrade(mint) {
	let curveBody = null;
	try {
		const view = await getCurveView({ mint, network: 'mainnet' });
		if (view?.httpStatus === 200 && view.body) curveBody = view.body;
	} catch (err) {
		console.warn('[pump/coin] on-chain curve fallback failed: %s', String(err?.message || err).slice(0, 160));
	}

	let dbRow = null;
	try {
		const rows = await sql`
			select name, symbol, agent_authority from pump_agent_mints
			where mint = ${mint} and network = 'mainnet'
			limit 1
		`;
		dbRow = rows[0] || null;
	} catch (err) {
		console.warn('[pump/coin] pump_agent_mints lookup failed: %s', String(err?.message || err).slice(0, 160));
	}

	if (!curveBody && !dbRow) return null;

	const curve = curveBody?.curve || null;
	return {
		mint,
		name: dbRow?.name ?? null,
		symbol: dbRow?.symbol ?? null,
		image: null,
		image_uri: null,
		description: null,
		creator: curve?.creator ?? dbRow?.agent_authority ?? null,
		complete: curve ? Boolean(curve.complete) : curveBody?.graduated === true ? true : null,
		usd_market_cap: curveBody?.graduatedPrice?.marketCapUsd ?? null,
		virtual_token_reserves: curve?.virtualTokenReserves ?? null,
		virtual_sol_reserves: curve?.virtualSolReserves ?? null,
		real_token_reserves: curve?.realTokenReserves ?? null,
		real_sol_reserves: curve?.realSolReserves ?? null,
		total_supply: curve?.tokenTotalSupply ?? null,
		metadataSource: dbRow ? 'platform' : 'onchain',
	};
}

async function serveStaleCoin(res, mint, status, code, message) {
	const hit = COIN_CACHE.get(mint) || (await cacheGet(coinLkgKey(mint)));
	if (hit && hit.body && typeof hit.at === 'number') {
		res.setHeader('cache-control', 'public, max-age=10');
		res.setHeader('x-pump-stale', '1');
		return json(res, 200, staleEnvelope(hit.body, hit.at));
	}
	const degraded = await fetchOnchainCoinDegrade(mint);
	if (degraded) {
		res.setHeader('cache-control', 'public, max-age=10');
		res.setHeader('x-pump-degraded', 'onchain');
		return json(res, 200, { ...degraded, stale: true, as_of: new Date().toISOString() });
	}
	res.setHeader('Retry-After', '15');
	return error(res, status, code, message, { retry_after: 15 });
}

export async function handleCoin(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;
	const rl = await limits.mcpIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);
	const url = new URL(req.url, `http://${req.headers.host}`);
	const mint = (url.searchParams.get('mint') || '').trim();
	if (!MINT_RE.test(mint))
		return error(res, 400, 'invalid_mint', 'mint must be a base58 address');
	// `?miss=empty` is for callers with their own fallback (the coin-status
	// widget reads the bonding curve next): an unindexed coin is an expected
	// answer there, not an error, so it gets a 204 instead of a 404 that every
	// browser prints to the console once per card on every refresh.
	const softMiss = url.searchParams.get('miss') === 'empty';
	const notFound = () => {
		if (!softMiss) return error(res, 404, 'coin_not_found', 'no pump.fun coin for that mint');
		res.setHeader('cache-control', 'public, max-age=60');
		res.statusCode = 204;
		return res.end();
	};

	const now = Date.now();
	const hit = COIN_CACHE.get(mint);
	if (hit && now - hit.at < COIN_TTL_MS) {
		res.setHeader('cache-control', 'public, max-age=15');
		return json(res, 200, hit.body);
	}

	// Bounded retry on 429/5xx with Retry-After honoured; never throws.
	const r = await pumpFetchJson(new URL(`/coins/${mint}`, PUMP_FRONTEND_BASE).toString(), { timeoutMs: 8000 });
	if (!r.ok) {
		// pump.fun returns 200 with an empty body for an unknown/unmigrated mint;
		// pumpFetchJson reports that as ok:false with the 200 status. That is a
		// real "coin not found", not an outage, so it never falls to last-good.
		if (r.status >= 200 && r.status < 300) return notFound();
		if (r.status === 0) return serveStaleCoin(res, mint, 504, 'upstream_timeout', 'pump.fun did not respond');
		if (r.status === 404) return notFound();
		return serveStaleCoin(res, mint, 502, 'upstream_failed', `pump.fun returned ${r.status}`);
	}
	const parsed = r.body;
	if (!parsed || typeof parsed !== 'object') return notFound();
	const [body] = repairCoinImages([parsed]);
	COIN_CACHE.set(mint, { at: now, body });
	cacheSet(coinLkgKey(mint), { at: now, body }, COIN_LKG_TTL_S).catch(() => {});
	res.setHeader('cache-control', 'public, max-age=15');
	return json(res, 200, body);
}

// ── coin-trades ────────────────────────────────────────────────────────────
// Recent buy/sell trades for a single mint, proxied from pump.fun's swap API
// (CORS-protected from the browser). Powers the homepage live token card's
// green/red flow. Covers both bonding-curve and migrated (AMM) trades.

const PUMP_SWAP_BASE = 'https://swap-api.pump.fun';
const MINT_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;

async function handleCoinTrades(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;
	const rl = await limits.mcpIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);
	const url = new URL(req.url, `http://${req.headers.host}`);
	const mint = (url.searchParams.get('mint') || '').trim();
	if (!MINT_RE.test(mint))
		return error(res, 400, 'invalid_mint', 'mint must be a base58 address');
	const limit = readLimit(url, 30, 100);
	const upstream = `${PUMP_SWAP_BASE}/v2/coins/${mint}/trades?limit=${limit}`;
	// "Recent trades" is a soft, continuously-polled feed (the homepage live card
	// re-fetches every ~4s). A transient pump.fun swap-API blip means "no new data
	// right now", not a hard error: so degrade to an empty 200 with `no-store`
	// rather than a 5xx the browser console logs on every poll. The next poll
	// retries immediately and the card recovers the moment upstream is back.
	const stale = (extra = {}) => {
		res.setHeader('cache-control', 'no-store');
		return json(res, 200, { mint, trades: [], stale: true, ...extra });
	};
	let resp;
	try {
		resp = await fetch(upstream, {
			headers: { accept: 'application/json' },
			signal: AbortSignal.timeout(8000),
		});
	} catch {
		return stale({ reason: 'upstream_timeout' });
	}
	if (!resp.ok) return stale({ reason: `upstream_${resp.status}` });
	let body;
	try {
		body = await resp.json();
	} catch {
		return stale({ reason: 'upstream_unparseable' });
	}
	const raw = Array.isArray(body) ? body : Array.isArray(body?.trades) ? body.trades : [];
	const trades = raw
		.map((t) => {
			const solAmount = Number(t.amountSol);
			const usdAmount = t.amountUsd != null ? Number(t.amountUsd) : null;
			// pump.fun v2 USDC-paired coins report the quote spend on amountQuote/
			// amountUsdc rather than amountSol. Surface whichever quote the upstream
			// used (with a stable symbol) so USDC trades are no longer silently
			// dropped by a SOL-only filter or shown as a misleading 0 SOL.
			const usdcRaw = t.amountQuote ?? t.amountUsdc ?? null;
			const isUsdcQuote = usdcRaw != null && (!isFinite(solAmount) || solAmount === 0);
			const quoteSymbol = isUsdcQuote ? 'USDC' : 'SOL';
			const quoteAmount = isUsdcQuote
				? Number(usdcRaw)
				: isFinite(solAmount)
					? solAmount
					: null;
			return {
				tx: t.tx,
				timestamp: t.timestamp,
				user: t.userAddress || t.user || null,
				is_buy: String(t.type).toLowerCase() === 'buy',
				sol_amount: isFinite(solAmount) ? solAmount : null,
				quote_symbol: quoteSymbol,
				quote_amount: quoteAmount,
				usd_amount: usdAmount,
				price_usd: t.priceUsd != null ? Number(t.priceUsd) : null,
			};
		})
		.filter(
			(t) =>
				t.tx &&
				((t.quote_amount != null && t.quote_amount > 0) ||
					(t.usd_amount != null && t.usd_amount > 0)),
		);
	res.setHeader('cache-control', 'public, max-age=3');
	return json(res, 200, { mint, trades });
}

async function handleSearch(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;
	const rl = await limits.mcpIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);
	const url = new URL(req.url, `http://${req.headers.host}`);
	const q = (url.searchParams.get('q') || '').trim();
	if (!q) return json(res, 200, []);
	const upstream = new URL('/coins', PUMP_FRONTEND_BASE);
	upstream.searchParams.set('searchTerm', q);
	upstream.searchParams.set('offset', '0');
	upstream.searchParams.set('limit', '30');
	upstream.searchParams.set('sort', 'market_cap');
	upstream.searchParams.set('order', 'DESC');
	upstream.searchParams.set('includeNsfw', 'false');
	const searchLkgKey = `pump:search:lkg:${q.toLowerCase()}`;
	// Bounded retry on 429/5xx with Retry-After honoured; never throws. A 200
	// with an empty/truncated body reports ok:false with a 2xx status, which is
	// "no results", not an outage.
	const r = await pumpFetchJson(upstream.toString(), { timeoutMs: 8000 });
	if (!r.ok) {
		if (r.status >= 200 && r.status < 300) return json(res, 200, []);
		// Outage or rate-limit window: the last result set this query produced
		// beats both a 502 and a misleading empty list.
		const lkg = await cacheGet(searchLkgKey);
		if (lkg && Array.isArray(lkg.rows) && typeof lkg.at === 'number') {
			res.setHeader('x-pump-stale', '1');
			return json(res, 200, lkg.rows, { 'x-pump-as-of': new Date(lkg.at).toISOString() });
		}
		if (r.status === 0) return json(res, 200, []);
		res.setHeader('Retry-After', '15');
		return error(res, 502, 'upstream_failed', `pump.fun returned ${r.status}`, { retry_after: 15 });
	}
	const body = r.body;
	const arr = repairCoinImages(
		Array.isArray(body) ? body : Array.isArray(body?.coins) ? body.coins : [],
	);
	if (arr.length) cacheSet(searchLkgKey, { rows: arr, at: Date.now() }, 3600).catch(() => {});
	return json(res, 200, arr);
}

// ── deliver-telegram ──────────────────────────────────────────────────────────

const _deliverSchema = z.object({
	chatId: z.union([z.string(), z.number()]),
	signal: z.object({
		kind: z.enum(['mint', 'whale', 'claim', 'graduation']),
		mint: z.string(),
		summary: z.string(),
		refs: z.array(z.string()).optional(),
		ts: z.number().optional(),
	}),
});

async function handleDeliverTelegram(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;
	const auth = await resolveAuth(req);
	if (!auth) return error(res, 401, 'unauthorized', 'sign in required');
	// This speaks under the platform's verified bot identity, so an authenticated
	// caller still gets a per-IP ceiling: without one, a single account turns the
	// bot into a spam/phishing relay one POST at a time.
	const rl = await limits.authIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl, 'too many delivery requests');
	const botToken = process.env.TELEGRAM_BOT_TOKEN;
	// An absent bot token is a deployment gap, not a server fault: 503 +
	// not_configured is what every sibling handler answers, and it tells a client
	// to stop retrying rather than to report a bug.
	if (!botToken)
		return error(res, 503, 'not_configured', 'Telegram delivery is not configured');
	const raw = await readJson(req);
	const { chatId, signal } = parse(_deliverSchema, raw);
	const { sendTelegramSignal } = await import('../../src/pump/telegram-delivery.js');
	const result = await sendTelegramSignal({ botToken, chatId, signal });
	return json(res, 200, result);
}

// ── first-claims ──────────────────────────────────────────────────────────────

import { scanFirstClaims } from '../_lib/pump-claims.js';

// ── recent-graduations ───────────────────────────────────────────────────────
//
// Returns the most-recent enriched graduation events as a single JSON payload.
// The page calls this once on load to backfill the feed before it opens an
// SSE connection. Reads from Postgres if available, falls back to the WS
// feed's in-process ring buffer (covers cold starts before the first migration
// arrives, plus dev environments without a DB).

async function handleRecentGraduations(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;
	const rl = await limits.mcpIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);
	const url = new URL(req.url, 'http://x');
	const limit = Math.max(1, Math.min(100, Number(url.searchParams.get('limit')) || 20));
	try {
		const { recentGraduations } = await import('../_lib/pumpfun-ws-feed.js');
		const items = await recentGraduations({ limit });
		return json(res, 200, { items }, { 'cache-control': 'public, max-age=5' });
	} catch (err) {
		console.warn('[recent-graduations] failed:', err?.message);
		return json(res, 200, { items: [] });
	}
}

async function handleFirstClaims(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;
	const rl = await limits.mcpIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);
	const url = new URL(req.url, 'http://x');
	const limit = Math.max(1, Math.min(50, Number(url.searchParams.get('limit')) || 50));
	let sinceTs;
	if (url.searchParams.has('sinceTs')) {
		sinceTs = Number(url.searchParams.get('sinceTs'));
	} else {
		const sinceMinutes = Math.max(
			1,
			Math.min(1440, Number(url.searchParams.get('sinceMinutes')) || 60),
		);
		sinceTs = Math.floor(Date.now() / 1000) - sinceMinutes * 60;
	}
	if (!Number.isFinite(sinceTs) || sinceTs <= 0)
		return error(res, 400, 'validation_error', 'invalid sinceTs');
	const items = await scanFirstClaims({ sinceTs, limit });
	return json(res, 200, { items });
}


// ── vanity-keygen (SSE) ───────────────────────────────────────────────────────

async function handleVanityKeygen(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (req.method !== 'POST') {
		res.setHeader('allow', 'POST');
		return error(res, 405, 'method_not_allowed', 'method POST required');
	}
	const auth = await resolveAuth(req);
	if (!auth) return error(res, 401, 'unauthorized', 'sign in required');
	const rl = await limits.mcpIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);
	let body;
	try {
		body = await readJson(req);
	} catch (e) {
		return error(res, e.status || 400, 'bad_request', e.message);
	}
	const { suffix = '', prefix = '', caseSensitive = false, maxAttempts = 5_000_000 } = body || {};
	if (!suffix && !prefix)
		return error(res, 400, 'validation_error', 'at least one of suffix or prefix is required');
	res.statusCode = 200;
	res.setHeader('content-type', 'text/event-stream; charset=utf-8');
	res.setHeader('cache-control', 'no-store');
	res.setHeader('connection', 'keep-alive');
	res.setHeader('x-accel-buffering', 'no');
	const ac = new AbortController();
	const timeout = setTimeout(() => {
		ac.abort();
		_sse(res, 'error', {
			error: 'request_timeout',
			error_description: 'vanity search exceeded 60 s limit',
		});
		res.statusCode = 408;
		res.end();
	}, 60_000);
	req.on('close', () => ac.abort());
	const progressInterval = setInterval(() => {
		if (ac.signal.aborted) return clearInterval(progressInterval);
		_sse(res, 'progress', { elapsed: Date.now() });
	}, 2_000);
	try {
		const { generateVanityKey } = await import('../../src/pump/vanity-keygen.js');
		const _bs58 = (await import('bs58')).default;
		const result = await generateVanityKey({
			suffix,
			prefix,
			caseSensitive,
			maxAttempts,
			signal: ac.signal,
		});
		clearTimeout(timeout);
		clearInterval(progressInterval);
		if (!result)
			_sse(res, 'error', {
				error: 'max_attempts_reached',
				error_description: `no match found in ${maxAttempts} attempts`,
			});
		else
			_sse(res, 'result', {
				publicKey: result.publicKey,
				secretKey: _bs58.encode(result.secretKey),
				attempts: result.attempts,
				ms: result.ms,
			});
	} catch (err) {
		clearTimeout(timeout);
		clearInterval(progressInterval);
		if (!res.writableEnded)
			_sse(res, 'error', {
				error: 'internal_error',
				error_description: err.message || 'unexpected error',
			});
	} finally {
		if (!res.writableEnded) res.end();
	}
}

// ── launch-config ──────────────────────────────────────────────────────────
// What a launch will cost and which transaction formats it can use, read live
// so the /launch preview never quotes a fee the transaction will not take.

async function handleLaunchConfig(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;

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

	const url = new URL(req.url, `http://${req.headers.host}`);
	const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
	const [recipient, txV1, tradeFeeBps, econ] = await Promise.all([
		pumpFeeRecipient(),
		transactionV1Status({ network }),
		effectivePumpFeeBps(),
		getLaunchEconomics(),
	]);
	// Gasless availability for the caller when signed in; the platform-level
	// blockers (paused, sponsor floor, platform cap) for everyone else.
	const session = await getSessionUser(req).catch(() => null);
	const gasless = await gaslessEligibility({ userId: session?.id || null, network, econ }).catch((err) => ({
		eligible: false,
		reasons: [{ code: 'unavailable', message: err?.message || 'gasless eligibility could not be read' }],
	}));

	res.setHeader('cache-control', session ? 'private, no-store' : 'public, max-age=60');
	return json(res, 200, {
		data: {
			network,
			launch_fee_bps: recipient ? pumpLaunchFeeBps() : 0,
			launch_fee_basis: 'dev_buy',
			fee_recipient: recipient ? recipient.toBase58() : null,
			trade_fee_bps: tradeFeeBps,
			create_cost_sol_estimate: 0.022,
			max_sol_buy_in: 50,
			buyback_available: pumpAgentBuybackAvailable(),
			tx_v1: txV1,
			economics: {
				...econ,
				standard_explanation: describeFeeSplit(econ, { gasless: false }),
				gasless_explanation: describeFeeSplit(econ, { gasless: true }),
			},
			gasless,
		},
	});
}

// ── my-coins ───────────────────────────────────────────────────────────────
// Every coin the signed-in user launched through three.ws, grouped by the
// on-chain creator that earns its rewards, with the live unclaimed balance per
// creator. pump.fun pools creator fees per creator wallet (not per coin), so a
// claim is per wallet and sweeps every coin that wallet created.

const PUMP_QUOTE_LABELS = {
	So11111111111111111111111111111111111111112: { symbol: 'SOL', decimals: 9 },
	EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v: { symbol: 'USDC', decimals: 6 },
	'4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU': { symbol: 'USDC', decimals: 6 },
};

// ── unswept creator fees ───────────────────────────────────────────────────
// v3 bonding-curve and v2 PumpSwap trades (pump-sdk 4.0) leave the creator fee
// on the curve or in the pool until a permissionless sweep moves it into the
// creator vault. Every claim below sweeps first, so it collects those fees in
// the same transaction, and every balance counts what is still waiting there.

const SOL_QUOTE_MINT = 'So11111111111111111111111111111111111111112';
// Room for the compute-budget instructions submitProtected adds to a send.
const PROTECTED_SEND_RESERVE_BYTES = 120;

// Coins a creator wallet launched through three.ws, plus any the caller named.
async function creatorCoinMints(creator, network, extra = []) {
	const rows = await sql`
		select mint from pump_agent_mints
		where agent_authority = ${creator} and network = ${network}
		order by created_at desc
		limit 500
	`;
	return [...new Set([...rows.map((r) => r.mint), ...extra])];
}

// Sweeps (largest first) and the extra quote mints for one creator's collect.
// A failed chain read degrades to a vault-only claim instead of no claim.
async function prepareCreatorSweeps(connection, { creator, mints, payer, solOnly }) {
	const empty = { sweeps: [], swept: [], legs: [], extraQuoteMints: [] };
	if (!mints.length) return empty;
	try {
		const buckets = await readCreatorFeeBuckets(connection, mints);
		const legs = unsweptCreatorFees(buckets.values(), creator).filter(
			(l) => !solOnly || l.quoteMint === SOL_QUOTE_MINT,
		);
		const { instructions, swept } = await creatorFeeSweepInstructions(connection, { legs, payer });
		return { sweeps: instructions, swept, legs, extraQuoteMints: creatorExtraQuoteMints(buckets.values(), creator) };
	} catch (e) {
		console.warn('[pump] creator-fee bucket read failed, collecting the vault only', creator, e?.message);
		return empty;
	}
}

// The first `count` swept legs, as the claim responses report them.
function sweptReport(swept, count) {
	return swept.slice(0, count).map((l) => ({
		mint: l.mint,
		source: l.source,
		quote_mint: l.quoteMint,
		amount: l.amount.toString(),
	}));
}

// Every nonzero creator-fee bucket on one coin, swept to whoever it belongs to:
// the programs refuse a distribution, CTO or fee-sharing change while one is
// nonzero (CreatorFeesNotSwept), so these go first in the same transaction.
async function coinSweepInstructions(connection, mintPk, payer) {
	const buckets = await readCreatorFeeBuckets(connection, [mintPk.toBase58()]);
	const { instructions } = await creatorFeeSweepInstructions(connection, {
		legs: unsweptCreatorFees(buckets.values()),
		payer,
	});
	return instructions;
}

// The quote mint and payer buildDistributeCreatorFeesInstructions needs: with
// the payer it also sweeps the pool bucket, with the quote mint it finds a
// token-quoted coin's pool and vaults instead of treating it as SOL.
async function distributeOptions(onlineSdk, mintPk, payer) {
	const { normalizeQuoteMint } = await import('@pump-fun/pump-sdk');
	const curve = await onlineSdk.fetchBondingCurve(mintPk).catch(() => null);
	return curve ? { payer, quoteMint: normalizeQuoteMint(curve.quoteMint) } : { payer };
}

// One creator's waiting rewards per quote mint: the vaults plus the fees still
// on that creator's curves and pools, which the claim sweeps in first.
async function creatorRewardBalances(connection, creator, buckets) {
	const { OnlinePumpSdk } = await import('@pump-fun/pump-sdk');
	const list = [...buckets.values()];
	const pending = sumByQuote(unsweptCreatorFees(list, creator));
	const rows = await new OnlinePumpSdk(connection).getCreatorVaultQuoteBalances(
		new PublicKey(creator),
		creatorExtraQuoteMints(list, creator),
	);
	const byMint = new Map(rows.map((r) => [r.mint.toBase58(), BigInt(r.total.toString())]));
	for (const mint of pending.keys()) if (!byMint.has(mint)) byMint.set(mint, 0n);
	return [...byMint.entries()]
		.map(([mint, vault]) => {
			const label = PUMP_QUOTE_LABELS[mint] || { symbol: `${mint.slice(0, 4)}…`, decimals: null };
			const unswept = pending.get(mint) || 0n;
			const total = vault + unswept;
			return {
				mint,
				symbol: label.symbol,
				amount: total.toString(),
				amount_ui: label.decimals == null ? null : Number(total) / 10 ** label.decimals,
				unswept: unswept.toString(),
			};
		})
		.filter((r) => r.amount !== '0');
}

async function handleMyCoins(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['GET'])) return;

	const user = await getSessionUser(req);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

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

	const url = new URL(req.url, `http://${req.headers.host}`);
	const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';

	const [rows, linked] = await Promise.all([
		sql`
			select pam.mint, pam.name, pam.symbol, pam.created_at, pam.agent_authority,
			       pam.sharing_config, pam.quote_mint,
			       ai.id as agent_id, ai.name as agent_name, ai.avatar_id,
			       ai.meta->>'solana_address' as agent_wallet,
			       a.thumbnail_key
			from pump_agent_mints pam
			left join agent_identities ai on ai.id = pam.agent_id and ai.deleted_at is null
			left join avatars a on a.id = ai.avatar_id and a.deleted_at is null
			where pam.user_id = ${user.id} and pam.network = ${network}
			order by pam.created_at desc
			limit 200
		`,
		sql`select address from user_wallets where user_id = ${user.id} and chain_type = 'solana'`,
	]);
	const linkedSet = new Set(linked.map((w) => w.address));
	const { holderRewardsPda } = await import('@pump-fun/pump-sdk');

	const coins = [];
	const creators = new Map(); // address -> wallet group
	for (const r of rows) {
		const creator = r.agent_authority;
		let route;
		const shared = r.sharing_config && Array.isArray(r.sharing_config.shareholders) && r.sharing_config.shareholders.length > 0;
		if (shared) route = 'shared';
		else if (!creator) route = 'unknown';
		else if (holderRewardsPda(new PublicKey(r.mint)).toBase58() === creator) route = 'holders';
		else if (r.agent_wallet && r.agent_wallet === creator) route = 'agent';
		else if (linkedSet.has(creator)) route = 'wallet';
		else route = 'external';

		coins.push({
			mint: r.mint,
			name: r.name,
			symbol: r.symbol,
			created_at: r.created_at,
			quote_mint: r.quote_mint,
			creator,
			reward_route: route,
			agent: r.agent_id
				? {
						id: r.agent_id,
						name: r.agent_name,
						avatar_id: r.avatar_id,
						thumbnail_url: thumbnailUrl(r.thumbnail_key),
					}
				: null,
		});

		if (route !== 'agent' && route !== 'wallet') continue;
		if (!creators.has(creator)) {
			creators.set(creator, {
				address: creator,
				kind: route,
				agent: route === 'agent' ? { id: r.agent_id, name: r.agent_name } : null,
				// The agent claim endpoint authorizes through one of the agent's coins.
				claim_mint: r.mint,
				coins: [],
				rewards: [],
				balance_error: null,
			});
		}
		creators.get(creator).coins.push(r.mint);
	}

	const connection = getConnection({ network });
	const claimMints = [...creators.values()].flatMap((g) => g.coins);
	const buckets = claimMints.length
		? await readCreatorFeeBuckets(connection, claimMints).catch((e) => {
				console.warn('[pump/my-coins] fee bucket read failed', e?.message);
				return new Map();
			})
		: new Map();
	await Promise.all(
		[...creators.values()].map(async (group) => {
			try {
				group.rewards = await creatorRewardBalances(connection, group.address, buckets);
			} catch (e) {
				group.balance_error = isRpcOutageError(e) ? 'rpc_unavailable' : 'balance_read_failed';
				console.warn('[pump/my-coins] vault read failed', group.address, e?.message);
			}
		}),
	);

	return json(res, 200, {
		data: { network, coins, wallets: [...creators.values()] },
	});
}

// ── collect-creator-fee-prep ───────────────────────────────────────────────
// Builds the tx for the coin creator to collect accrued creator fees from the
// pump.fun fee vault into their own wallet.
// Docs: https://github.com/pump-fun/pump-public-docs/blob/main/docs/instructions/COLLECT_CREATOR_FEE.md

const collectCreatorFeePrepSchema = z.object({
	// The on-chain creator address registered for the coin.
	creator_address: z.string().min(32).max(44),
	// The wallet that will sign (and receive fees). Must match creator_address.
	wallet_address: z.string().min(32).max(44),
	network: z.enum(['mainnet', 'devnet']).default('mainnet'),
	// Sweep every quote mint (SOL plus USDC and any other listed quote) instead
	// of SOL alone, so a USDC-paired coin's rewards are claimable too.
	all_quotes: z.boolean().default(false),
	// Coins this creator made outside three.ws whose curve or pool fees should be
	// swept in too. Coins launched here are found from the launch records.
	mints: z.array(z.string().min(32).max(44)).max(50).default([]),
	transaction_version: z.union([z.literal('auto'), z.literal(0), z.literal(1)]).default('auto'),
	v1_capable: z.boolean().default(false),
});

async function handleCollectCreatorFeePrep(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await getSessionUser(req);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

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

	const body = parse(collectCreatorFeePrepSchema, await readJson(req));
	const creatorPk = solanaPubkey(body.creator_address);
	const feePayer = solanaPubkey(body.wallet_address);
	if (!creatorPk || !feePayer) return error(res, 400, 'validation_error', 'invalid pubkeys');

	try {
		const { connection } = await getPumpSdk({ network: body.network });
		const { OnlinePumpSdk } = await import('@pump-fun/pump-sdk');
		const onlineSdk = new OnlinePumpSdk(connection);
		const extraMints = body.mints.filter((m) => solanaPubkey(m));
		const prep = await prepareCreatorSweeps(connection, {
			creator: creatorPk.toBase58(),
			mints: await creatorCoinMints(creatorPk.toBase58(), body.network, extraMints),
			payer: feePayer,
			solOnly: !body.all_quotes,
		});
		const ixs = body.all_quotes
			? await onlineSdk.collectCoinCreatorFeeAllQuotesInstructions(creatorPk, feePayer, prep.extraQuoteMints)
			: await onlineSdk.collectCoinCreatorFeeInstructions(creatorPk, feePayer);
		const collectIxs = Array.isArray(ixs) ? ixs : [ixs];
		const sweepCount = countPrefixThatFits({
			payer: feePayer,
			prefix: prep.sweeps,
			rest: collectIxs,
			tables: await getPumpLookupTables({ network: body.network }),
		});
		const built = await buildLaunchTransaction({
			network: body.network,
			payer: feePayer,
			instructions: [...prep.sweeps.slice(0, sweepCount), ...collectIxs],
			transactionVersion: body.transaction_version,
			v1Capable: body.v1_capable,
		});
		return json(res, 201, {
			creator: body.creator_address,
			network: body.network,
			tx_base64: built.tx_base64,
			transaction_version: built.transaction_version,
			swept: sweptReport(prep.swept, sweepCount),
			// Fee legs left on curves or pools after this claim (too many for one
			// transaction); claiming again sweeps the next largest.
			sweeps_remaining: prep.legs.length - sweepCount,
		});
	} catch (e) {
		return error(
			res,
			e.status || 502,
			e.code || 'pump_sdk_error',
			e.message || 'failed to build collect-creator-fee tx',
		);
	}
}

// ── distribute-creator-fees-prep ──────────────────────────────────────────
// Builds the tx that distributes accumulated creator fees to shareholders
// defined in the coin's fee-sharing config. For graduated coins the SDK
// automatically prepends a `transfer_creator_fees_to_pump_v2` instruction so
// AMM-side fees are consolidated into the bonding-curve vault first: no
// separate transfer call is needed at this layer.
//
// ATA initialization for non-native quotes (e.g. USDC) is handled internally
// by `buildDistributeCreatorFeesInstructions`: the SDK reads the coin's
// quote_mint and emits `initialize_ata: true` for the underlying
// `distribute_creator_fees_v2` instruction so each shareholder's USDC ATA is
// idempotently created before the program transfers their share.
//
// Docs: https://github.com/pump-fun/pump-public-docs/blob/main/docs/instructions/CREATOR_FEE_SHARING.md

const distributeCreatorFeesPrepSchema = z.object({
	mint: z.string().min(32).max(44),
	wallet_address: z.string().min(32).max(44), // fee payer / signer (permissionless)
	network: z.enum(['mainnet', 'devnet']).default('mainnet'),
});

async function handleDistributeCreatorFeesPrep(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await getSessionUser(req);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

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

	const body = parse(distributeCreatorFeesPrepSchema, await readJson(req));
	const mintPk = solanaPubkey(body.mint);
	const payerPk = solanaPubkey(body.wallet_address);
	if (!mintPk || !payerPk) return error(res, 400, 'validation_error', 'invalid pubkeys');

	try {
		const { connection } = await getPumpSdk({ network: body.network });
		const { OnlinePumpSdk } = await import('@pump-fun/pump-sdk');
		const onlineSdk = new OnlinePumpSdk(connection);
		const { instructions, isGraduated } = await onlineSdk.buildDistributeCreatorFeesInstructions(
			mintPk,
			await distributeOptions(onlineSdk, mintPk, payerPk),
		);
		const tx_base64 = await buildUnsignedTxBase64({
			network: body.network,
			payer: payerPk,
			instructions,
		});
		return json(res, 201, {
			mint: body.mint,
			network: body.network,
			is_graduated: !!isGraduated,
			tx_base64,
		});
	} catch (e) {
		return error(
			res,
			e.status || 502,
			e.code || 'pump_sdk_error',
			e.message || 'failed to build distribute-creator-fees tx',
		);
	}
}

// ── update-fee-shares-prep ────────────────────────────────────────────────
// Step 2 of the fee-sharing lifecycle. The current sharing_config admin
// finalises the shareholder list (1-10 entries, share_bps must sum to 10_000).
// This sweeps any pending AMM + bonding-curve fees, applies the new
// distribution, and (in version-1 configs) permanently revokes further
// updates: so for v1 callers should call it exactly once after
// create-fee-sharing-prep.
// Docs: https://github.com/pump-fun/pump-public-docs/blob/main/docs/instructions/CREATOR_FEE_SHARING.md

const updateFeeSharesSchema = z.object({
	mint: z.string().min(32).max(44),
	wallet_address: z.string().min(32).max(44), // sharing_config admin (signer + fee payer)
	network: z.enum(['mainnet', 'devnet']).default('mainnet'),
	// The set of shareholder addresses currently encoded in the on-chain
	// sharing_config. Right after create-fee-sharing-prep this is `[creator]`
	// at 10_000 bps; after a prior update it's whatever was last set. The SDK
	// uses these to derive the existing PDA accounts that must be passed in.
	// Optional: when omitted the handler decodes the current set from the
	// on-chain sharing_config so the client never has to track it.
	current_shareholders: z.array(z.string().min(32).max(44)).min(1).max(10).optional(),
	new_shareholders: z
		.array(
			z.object({
				address: z.string().min(32).max(44),
				share_bps: z.number().int().min(1).max(10_000),
			}),
		)
		.min(1)
		.max(10)
		.superRefine((arr, ctx) => {
			// One rule set for the server and the launch UI: src/shared/launch-fees.js.
			for (const message of validateShareholders(arr).errors) ctx.addIssue({ code: 'custom', message });
		}),
});

async function handleUpdateFeeSharesPrep(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await getSessionUser(req);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

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

	const body = parse(updateFeeSharesSchema, await readJson(req));
	const mintPk = solanaPubkey(body.mint);
	const payerPk = solanaPubkey(body.wallet_address);
	if (!mintPk || !payerPk) return error(res, 400, 'validation_error', 'invalid pubkeys');

	const guard = await assertCoinNotOwnedByOther({
		userId: user.id,
		mint: body.mint,
		network: body.network,
		res,
	});
	if (guard.blocked) return;

	const newShareholders = body.new_shareholders.map((s) => {
		const addr = solanaPubkey(s.address);
		if (!addr)
			throw Object.assign(new Error(`invalid shareholder ${s.address}`), {
				status: 400,
				code: 'validation_error',
			});
		return { address: addr, shareBps: s.share_bps };
	});

	try {
		const { sdk, connection } = await getPumpSdk({ network: body.network });

		// Current shareholders: trust the client list when supplied, otherwise
		// decode them from the on-chain sharing_config so callers don't have to
		// track on-chain state themselves.
		let currentShareholders;
		if (body.current_shareholders?.length) {
			currentShareholders = body.current_shareholders.map((s) => {
				const pk = solanaPubkey(s);
				if (!pk)
					throw Object.assign(new Error(`invalid current shareholder ${s}`), {
						status: 400,
						code: 'validation_error',
					});
				return pk;
			});
		} else {
			const { feeSharingConfigPda } = await import('@pump-fun/pump-sdk');
			const cfgInfo = await connection.getAccountInfo(feeSharingConfigPda(mintPk));
			if (!cfgInfo) {
				return error(
					res,
					409,
					'no_sharing_config',
					'no fee-sharing config for this coin — create one first via create-fee-sharing-prep',
				);
			}
			const cfg = sdk.decodeSharingConfig(cfgInfo);
			currentShareholders = cfg.shareholders.map((s) => new PublicKey(s.address));
		}

		const ix = await sdk.updateFeeShares({
			authority: payerPk,
			mint: mintPk,
			currentShareholders,
			newShareholders,
		});
		const tx_base64 = await buildUnsignedTxBase64({
			network: body.network,
			payer: payerPk,
			instructions: [...(await coinSweepInstructions(connection, mintPk, payerPk)), ix],
		});
		return json(res, 201, {
			mint: body.mint,
			network: body.network,
			shareholder_count: newShareholders.length,
			tx_base64,
		});
	} catch (e) {
		return error(
			res,
			e.status || 502,
			e.code || 'pump_sdk_error',
			e.message || 'failed to build update-fee-shares tx',
		);
	}
}

// ── create-fee-sharing-prep ────────────────────────────────────────────────
// Builds the tx to create a fee-sharing config for a graduated coin, enabling
// the coin creator to split AMM creator fees among multiple shareholders.
// Docs: https://github.com/pump-fun/pump-public-docs/blob/main/docs/instructions/CREATOR_FEE_SHARING.md

const createFeeSharingPrepSchema = z.object({
	mint: z.string().min(32).max(44),
	creator_address: z.string().min(32).max(44),
	wallet_address: z.string().min(32).max(44), // signer / fee payer
	network: z.enum(['mainnet', 'devnet']).default('mainnet'),
});

async function handleCreateFeeSharingPrep(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await getSessionUser(req);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

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

	const body = parse(createFeeSharingPrepSchema, await readJson(req));
	const mintPk = solanaPubkey(body.mint);
	const creatorPk = solanaPubkey(body.creator_address);
	const payerPk = solanaPubkey(body.wallet_address);
	if (!mintPk || !creatorPk || !payerPk)
		return error(res, 400, 'validation_error', 'invalid pubkeys');

	const guard = await assertCoinNotOwnedByOther({
		userId: user.id,
		mint: body.mint,
		network: body.network,
		res,
	});
	if (guard.blocked) return;

	try {
		const { canonicalPumpPoolPda } = await import('@pump-fun/pump-swap-sdk');
		const { bondingCurvePda } = await import('@pump-fun/pump-sdk');
		const { isLegacyQuoteMint } = await getPumpSdkV2({ network: body.network });
		const { sdk, connection } = await getPumpSdk({ network: body.network });

		const bcPda = bondingCurvePda(mintPk);
		const bcInfo = await connection.getAccountInfo(bcPda);
		const bc = bcInfo ? sdk.decodeBondingCurve(bcInfo) : null;

		let poolPk;
		if (bc && bc.quoteMint && !isLegacyQuoteMint(bc.quoteMint)) {
			poolPk = canonicalPumpPoolPda(mintPk, bc.quoteMint);
		} else {
			poolPk = canonicalPumpPoolPda(mintPk);
		}

		const ix = await sdk.createFeeSharingConfig({
			creator: creatorPk,
			mint: mintPk,
			pool: poolPk,
		});
		const tx_base64 = await buildUnsignedTxBase64({
			network: body.network,
			payer: payerPk,
			instructions: [...(await coinSweepInstructions(connection, mintPk, payerPk)), ix],
		});
		return json(res, 201, {
			mint: body.mint,
			creator: body.creator_address,
			pool: poolPk.toString(),
			network: body.network,
			tx_base64,
		});
	} catch (e) {
		return error(
			res,
			e.status || 502,
			e.code || 'pump_sdk_error',
			e.message || 'failed to build create-fee-sharing tx',
		);
	}
}

// Soft ownership guard for connected-wallet fee/delegation actions. If this mint
// was launched through three.ws (a pump_agent_mints row exists), it must belong
// to the session user: this stops one account building fee txs against another
// account's coin. Coins launched outside three.ws have no row and are allowed
// (the on-chain sharing-config admin signature is the real gate either way).
async function assertCoinNotOwnedByOther({ userId, mint, network, res }) {
	const [row] = await sql`
		select id, user_id from pump_agent_mints
		where mint=${mint} and network=${network}
		limit 1
	`;
	if (row && row.user_id !== userId) {
		error(res, 403, 'forbidden', 'this coin belongs to another account');
		return { blocked: true };
	}
	return { blocked: false, row: row || null };
}

// pump.fun social platform ids (matches the SDK's Platform enum):
//   Pump = 0, X = 1, GitHub = 2
const SOCIAL_PLATFORM_ID = { pump: 0, x: 1, github: 2 };

// ── resolve-github-shareholder ─────────────────────────────────────────────
// Turns a GitHub identity into a concrete fee-share recipient address so the
// delegation UI never has to know the mapping. If the GitHub user is on
// three.ws (linked via the existing GitHub OAuth) and has a linked Solana
// wallet, we return that wallet: a fully-claimable shareholder paid by the
// permissionless distribute crank. Otherwise we return the pump.fun social-fee
// escrow PDA for their numeric id; fees can be routed into it, but the final
// claim is brokered by pump.fun's own app (we don't hold the social-claim
// authority), so we flag claimable_now:false and explain.

const resolveGithubShareholderSchema = z
	.object({
		// Platform is now general: 'github' (default) or 'x' (Twitter). The
		// github_* fields are kept for back-compat; `username`/`user_id` are the
		// platform-agnostic inputs the fees panel and Launch Studio use.
		platform: z.enum(['github', 'x']).default('github'),
		username: z.string().trim().min(1).max(40).optional(),
		user_id: z.string().trim().regex(/^\d{1,20}$/).optional(),
		github_username: z.string().trim().min(1).max(40).optional(),
		github_user_id: z.string().trim().regex(/^\d{1,20}$/).optional(),
		network: z.enum(['mainnet', 'devnet']).default('mainnet'),
	})
	.refine((b) => b.username || b.user_id || b.github_username || b.github_user_id, {
		message: 'a username or numeric user id is required',
	});

async function handleResolveGithubShareholder(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await getSessionUser(req);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

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

	const body = parse(resolveGithubShareholderSchema, await readJson(req));

	// One source of truth for social → reward resolution (github + x), shared with
	// the launch use-case engine and the fees panel.
	const r = await resolveSocialReward({
		platform: body.platform,
		username: body.username || body.github_username,
		userId: body.user_id || body.github_user_id,
		network: body.network,
	});
	return json(res, 200, {
		platform: r.platform,
		mode: r.mode,
		address: r.address,
		username: r.username,
		user_id: r.user_id,
		// Back-compat aliases for existing github callers.
		github_username: r.platform === 'github' ? r.username : undefined,
		github_user_id: r.platform === 'github' ? r.user_id : undefined,
		claimable_now: r.claimable_now,
		note: r.note,
	});
}


// ── create-social-fee-pda-prep ─────────────────────────────────────────────
// Initialises the pump.fun social-fee escrow PDA for a (social_user_id,
// platform) pair so a subsequent update-fee-shares-prep can name it as a
// shareholder address. Idempotent on-chain (no-op if it already exists). The
// returned tx is signed by the connected wallet (the coin admin/payer).

const createSocialFeePdaPrepSchema = z.object({
	wallet_address: z.string().min(32).max(44), // payer / signer
	social_user_id: z.string().trim().min(1).max(20), // numeric social id (SDK caps at 20 chars)
	platform: z.enum(['github', 'x', 'pump']).default('github'),
	mint: z.string().min(32).max(44).optional(), // when set, enforces coin ownership
	network: z.enum(['mainnet', 'devnet']).default('mainnet'),
});

async function handleCreateSocialFeePdaPrep(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await getSessionUser(req);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

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

	const body = parse(createSocialFeePdaPrepSchema, await readJson(req));
	const payerPk = solanaPubkey(body.wallet_address);
	if (!payerPk) return error(res, 400, 'validation_error', 'invalid wallet_address');

	if (body.mint) {
		const guard = await assertCoinNotOwnedByOther({
			userId: user.id,
			mint: body.mint,
			network: body.network,
			res,
		});
		if (guard.blocked) return;
	}

	const platform = SOCIAL_PLATFORM_ID[body.platform];

	try {
		const { sdk } = await getPumpSdk({ network: body.network });
		const { socialFeePda } = await import('@pump-fun/pump-sdk');
		const ix = await sdk.createSocialFeePda({
			payer: payerPk,
			userId: body.social_user_id,
			platform,
		});
		const tx_base64 = await buildUnsignedTxBase64({
			network: body.network,
			payer: payerPk,
			instructions: Array.isArray(ix) ? ix : [ix],
		});
		return json(res, 201, {
			social_fee_pda: socialFeePda(body.social_user_id, platform).toBase58(),
			platform: body.platform,
			social_user_id: body.social_user_id,
			network: body.network,
			tx_base64,
		});
	} catch (e) {
		return error(
			res,
			e.status || 502,
			e.code || 'pump_sdk_error',
			e.message || 'failed to build create-social-fee-pda tx',
		);
	}
}
// ── fee-info ───────────────────────────────────────────────────────────────
// Read-only resolver: given a mint, report where creator fees go (cashback,
// sharing-config shareholders, or direct creator), the claimable vault balance
// (pump native vault + AMM WSOL vault), graduation status, and the on-chain
// sharing-config shareholders if one exists. Mirrors the coin-fees skill's
// fetch-fee-info.mjs so the studio shows real, on-chain numbers: no estimates.
// Public read (rate-limited) so anyone can inspect a coin's fee posture before
// claiming a delegated share.

const MIN_RENT_EXEMPTION_LAMPORTS = 890_880n;

/**
 * Pure fee-routing read for `mintPk`: returns the same object handleFeeInfo
 * serves, or null when the mint has no bonding curve. Exported so other
 * composed read surfaces (the launch receipt) can reuse this without an
 * internal HTTP round trip. Throws on an on-chain read failure; the caller
 * decides how to surface that.
 */
export async function computeFeeInfo(mintPk, network) {
	const connection = getConnection({ network });
	const [
		{ PumpSdk, OnlinePumpSdk, canonicalPumpPoolPdaWithQuote, normalizeQuoteMint, creatorVaultPda, feeSharingConfigPda },
		{ OnlinePumpAmmSdk, coinCreatorVaultAuthorityPda, coinCreatorVaultAtaPda },
		{ AccountLayout, NATIVE_MINT, TOKEN_PROGRAM_ID },
	] = await Promise.all([
		import('@pump-fun/pump-sdk'),
		import('@pump-fun/pump-swap-sdk'),
		import('@solana/spl-token'),
	]);

	const onlineSdk = new OnlinePumpSdk(connection);
	const offlineSdk = new PumpSdk();
	const bondingCurve = await onlineSdk.fetchBondingCurve(mintPk).catch(() => null);
	if (!bondingCurve) return null;
	const isHolderReward = bondingCurve.isHolderReward === true;

	const poolPda = canonicalPumpPoolPdaWithQuote(mintPk, normalizeQuoteMint(bondingCurve.quoteMint));
	const poolInfo = await connection.getAccountInfo(poolPda);
	let isGraduated = false;
	let poolCoinCreator = null;
	let isCashbackCoin = false;

	if (poolInfo) {
		isGraduated = true;
		try {
			const pool = await new OnlinePumpAmmSdk(connection).fetchPool(poolPda);
			poolCoinCreator = pool.coinCreator;
			isCashbackCoin =
				pool.isCashbackCoin === true ||
				(Array.isArray(pool.is_cashback_coin) && pool.is_cashback_coin[0] === true);
		} catch {
			/* pool not fully initialized */
		}
	} else {
		isCashbackCoin =
			bondingCurve.isCashbackCoin === true ||
			(Array.isArray(bondingCurve.is_cashback_coin) &&
				bondingCurve.is_cashback_coin[0] === true);
	}

	const effectiveCreator = poolCoinCreator ?? new PublicKey(bondingCurve.creator);

	let hasSharingConfig = false;
	let sharingConfig = null;
	if (!isCashbackCoin && !isHolderReward) {
		// When a creator migrates to a fee-sharing config, the on-chain creator
		// field (pool.coinCreator / bondingCurve.creator) becomes the config PDA.
		const cfgPda = feeSharingConfigPda(mintPk);
		hasSharingConfig = effectiveCreator.equals(cfgPda);
		if (hasSharingConfig) {
			const cfgInfo = await connection.getAccountInfo(cfgPda);
			if (cfgInfo) {
				const cfg = offlineSdk.decodeSharingConfig(cfgInfo);
				sharingConfig = {
					address: cfgPda.toBase58(),
					admin: cfg.admin.toBase58(),
					admin_revoked: cfg.adminRevoked ?? false,
					shareholders: cfg.shareholders.map((s) => ({
						address: s.address.toBase58(),
						bps: Number(s.shareBps),
					})),
				};
			} else {
				hasSharingConfig = false;
			}
		}
	}

	// Vault balance = pump native creator vault (minus rent) + AMM WSOL vault,
	// plus the SOL creator fees v3 / PumpSwap v2 trades left on this coin's
	// curve and pool, which a claim sweeps into the vault first.
	// When a sharing config exists, fees accrue under the config PDA.
	let claimableLamports = 0n;
	let unsweptLamports = 0n;
	if (!isCashbackCoin) {
		const vaultCreator = hasSharingConfig ? feeSharingConfigPda(mintPk) : effectiveCreator;
		const buckets = await readCreatorFeeBuckets(connection, [mintPk.toBase58()]);
		for (const leg of unsweptCreatorFees(buckets.values(), vaultCreator.toBase58())) {
			if (leg.quoteMint === SOL_QUOTE_MINT) unsweptLamports += leg.amount;
		}
		claimableLamports += unsweptLamports;
		const nativeVault = creatorVaultPda(vaultCreator);
		const nativeInfo = await connection.getAccountInfo(nativeVault);
		if (nativeInfo) {
			const adjusted = BigInt(nativeInfo.lamports) - MIN_RENT_EXEMPTION_LAMPORTS;
			if (adjusted > 0n) claimableLamports += adjusted;
		}
		try {
			const ammAuthority = coinCreatorVaultAuthorityPda(vaultCreator);
			const ammAta = coinCreatorVaultAtaPda(ammAuthority, NATIVE_MINT, TOKEN_PROGRAM_ID);
			const ammInfo = await connection.getAccountInfo(ammAta);
			if (ammInfo) {
				const parsed = AccountLayout.decode(
					new Uint8Array(
						ammInfo.data.buffer,
						ammInfo.data.byteOffset,
						ammInfo.data.byteLength,
					),
				);
				claimableLamports += BigInt(parsed.amount.toString());
			}
		} catch {
			/* no AMM vault yet */
		}
	}

	const feeDestination = isHolderReward
		? 'holder_rewards'
		: isCashbackCoin
		? 'cashback'
		: hasSharingConfig
			? 'sharing_config'
			: 'creator';

	return {
		mint: mintPk.toBase58(),
		network,
		is_graduated: isGraduated,
		is_cashback_coin: isCashbackCoin,
		is_holder_reward: isHolderReward,
		has_sharing_config: hasSharingConfig,
		creator: effectiveCreator.toBase58(),
		claimable_lamports: claimableLamports.toString(),
		claimable_sol: Number(claimableLamports) / LAMPORTS_PER_SOL,
		// The part of claimable still on the curve or pool (swept by the claim).
		unswept_lamports: unsweptLamports.toString(),
		fee_destination: feeDestination,
		sharing_config: sharingConfig,
	};
}

async function handleFeeInfo(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;

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

	const url = new URL(req.url, `http://${req.headers.host}`);
	const mintStr = url.searchParams.get('mint');
	const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
	const mintPk = solanaPubkey(mintStr);
	if (!mintPk) return error(res, 400, 'validation_error', 'valid mint required');

	try {
		const info = await computeFeeInfo(mintPk, network);
		if (!info) return error(res, 404, 'not_found', 'no bonding curve for this mint');
		return json(res, 200, info);
	} catch (e) {
		return error(
			res,
			e.status || 502,
			e.code || 'pump_sdk_error',
			e.message || 'failed to read fee info',
		);
	}
}

// Build a v0 transaction from `instructions`, sign with the agent keypair (and
// any extra signers), send, and confirm. Mirrors the launch-agent send path so
// every server-signed pump action uses the same RPC handling.
async function signSendWithAgent({ network, agentKeypair, instructions, extraSigners = [], lookupTables = [] }) {
	const conn = solanaConnection(network);
	// Protected send: priority fee + CU estimate, rebroadcast with blockhash
	// refresh, hard throw on an on-chain revert.
	const { signature } = await submitProtected({
		network,
		connection: conn,
		payer: agentKeypair,
		instructions,
		opts: { extraSigners, addressLookupTables: lookupTables },
	});
	return signature;
}

// Resolve the agent + mint the caller controls, and assert the agent's custodial
// wallet is the on-chain creator (agent_authority) of the coin. Returns
// { agent, mintRow, loaded, creator } or sends an error and returns null.
async function resolveAgentFeeContext(req, res, body, { agreementContext = null } = {}) {
	const user = await requireSessionUser(req, res);
	if (!user) return null;

	const agent = await resolveLaunchAgentId({
		userId: user.id,
		agentId: body.agent_id,
		avatarId: body.avatar_id,
	});
	if (!agent) {
		error(res, 404, 'not_found', 'agent not found');
		return null;
	}

	const [mintRow] = await sql`
		select id, mint, network, agent_authority, sharing_config
		from pump_agent_mints
		where agent_id=${agent.id} and mint=${body.mint} and network=${body.network}
		limit 1
	`;
	if (!mintRow) {
		error(res, 404, 'not_found', 'coin not found for this agent');
		return null;
	}
	if (agreementContext && !(await requireRealFundsAgreement(req, res, { userId: user.id, network: body.network, context: agreementContext }))) {
		return null;
	}

	const loaded = await loadAgentForSigning(agent.id, user.id, {
		reason: 'studio_fee_action',
		meta: { mint: body.mint, network: body.network },
	});
	if (loaded.error) {
		error(res, loaded.error.status, loaded.error.code, loaded.error.msg);
		return null;
	}

	const creator = loaded.keypair.publicKey.toBase58();
	if (mintRow.agent_authority && mintRow.agent_authority !== creator) {
		error(
			res,
			409,
			'creator_mismatch',
			'this coin was launched from a connected wallet — claim with that wallet instead of the agent wallet',
		);
		return null;
	}
	return { user, agent, mintRow, loaded, creator };
}

// ── collect-creator-fee-agent ──────────────────────────────────────────────
// Server-signs the creator-fee collection with the agent custodial wallet. Use
// for coins launched from the agent wallet (agent_authority == agent wallet).
// The body contract (collectFeeAgentSchema) lives in api/_lib/pump-fee-schemas.js.

async function handleCollectCreatorFeeAgent(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

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

	const body = parse(collectFeeAgentSchema, await readJson(req));
	const ctx = await resolveAgentFeeContext(req, res, body);
	if (!ctx) return;

	try {
		const { connection } = await getPumpSdk({ network: body.network });
		const { OnlinePumpSdk } = await import('@pump-fun/pump-sdk');
		const onlineSdk = new OnlinePumpSdk(connection);
		const creatorPk = ctx.loaded.keypair.publicKey;
		// Snapshot the creator's SOL before the sweep so we can report the exact
		// lamports the claim delivered (net of tx fee): callers (the launcher
		// claimer, the studio) need the real figure, not a boolean.
		const balanceBefore = await connection.getBalance(creatorPk).catch(() => null);
		// Fees v3 / PumpSwap v2 trades left on the creator's curves and pools are
		// swept into the vault first, so this one claim collects them too.
		const prep = await prepareCreatorSweeps(connection, {
			creator: ctx.creator,
			mints: await creatorCoinMints(ctx.creator, body.network, [body.mint]),
			payer: creatorPk,
			solOnly: !body.all_quotes,
		});
		const ixs = body.all_quotes
			? await onlineSdk.collectCoinCreatorFeeAllQuotesInstructions(creatorPk, creatorPk, prep.extraQuoteMints)
			: await onlineSdk.collectCoinCreatorFeeInstructions(creatorPk, creatorPk);
		const collectIxs = Array.isArray(ixs) ? ixs : [ixs];
		const lookupTables = await getPumpLookupTables({ network: body.network });
		const sweepCount = countPrefixThatFits({
			payer: creatorPk,
			prefix: prep.sweeps,
			rest: collectIxs,
			tables: lookupTables,
			reserveBytes: PROTECTED_SEND_RESERVE_BYTES,
		});
		const signature = await signSendWithAgent({
			network: body.network,
			agentKeypair: ctx.loaded.keypair,
			instructions: [...prep.sweeps.slice(0, sweepCount), ...collectIxs],
			lookupTables,
		});
		const swept = sweptReport(prep.swept, sweepCount);
		const balanceAfter = balanceBefore == null ? null : await connection.getBalance(creatorPk).catch(() => null);
		const lamports = balanceBefore != null && balanceAfter != null ? Math.max(0, balanceAfter - balanceBefore) : null;
		await sql`
			insert into agent_actions (agent_id, type, payload, source_skill)
			values (${ctx.agent.id}, ${'pumpfun.collect_creator_fee'},
				${JSON.stringify({ mint: body.mint, network: body.network, signature, lamports, swept, source: 'studio_agent_wallet' })}::jsonb,
				${'pumpfun'})
		`.catch((e) => console.error('[pump/collect-creator-fee-agent] log failed', e?.message));
		return json(res, 201, {
			ok: true,
			mint: body.mint,
			network: body.network,
			signature,
			lamports,
			sol: lamports == null ? null : lamports / LAMPORTS_PER_SOL,
			swept,
			sweeps_remaining: prep.legs.length - sweepCount,
			explorer: `https://solscan.io/tx/${signature}${body.network === 'devnet' ? '?cluster=devnet' : ''}`,
		});
	} catch (e) {
		return respondError(res, e.status || 502, e.code || 'rpc_error', e);
	}
}

// ── distribute-creator-fees-agent ──────────────────────────────────────────
// Server-signs distribution of shared fees to the sharing-config shareholders,
// paid by the agent custodial wallet. Distribution is permissionless on-chain;
// this lets the agent wallet crank it without a connected wallet.

async function handleDistributeCreatorFeesAgent(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

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

	const body = parse(collectFeeAgentSchema, await readJson(req));
	const ctx = await resolveAgentFeeContext(req, res, body);
	if (!ctx) return;

	try {
		const { connection } = await getPumpSdk({ network: body.network });
		const { OnlinePumpSdk } = await import('@pump-fun/pump-sdk');
		const onlineSdk = new OnlinePumpSdk(connection);
		const mintPk = new PublicKey(body.mint);
		const { instructions } = await onlineSdk.buildDistributeCreatorFeesInstructions(
			mintPk,
			await distributeOptions(onlineSdk, mintPk, ctx.loaded.keypair.publicKey),
		);
		const signature = await signSendWithAgent({
			network: body.network,
			agentKeypair: ctx.loaded.keypair,
			instructions,
		});
		await sql`
			insert into agent_actions (agent_id, type, payload, source_skill)
			values (${ctx.agent.id}, ${'pumpfun.distribute_creator_fees'},
				${JSON.stringify({ mint: body.mint, network: body.network, signature, source: 'studio_agent_wallet' })}::jsonb,
				${'pumpfun'})
		`.catch((e) => console.error('[pump/distribute-creator-fees-agent] log failed', e?.message));
		return json(res, 201, {
			ok: true,
			mint: body.mint,
			network: body.network,
			signature,
			explorer: `https://solscan.io/tx/${signature}${body.network === 'devnet' ? '?cluster=devnet' : ''}`,
		});
	} catch (e) {
		return respondError(res, e.status || 502, e.code || 'rpc_error', e);
	}
}

// ── fee-sharing-agent ──────────────────────────────────────────────────────
// Server-signs the full delegation lifecycle with the agent custodial wallet:
// creates the sharing config if absent, then sets the shareholder split. This
// is the on-chain mechanism behind "reward" coins: creator fees are split to a
// list of delegated wallets (e.g. GitHub contributors) who can each claim their
// share via distribute. Shares are basis points and must sum to 10000.

const feeSharingAgentSchema = z
	.object({
		agent_id: z.string().uuid().optional(),
		avatar_id: z.string().uuid().optional(),
		mint: z.string().min(32).max(44),
		network: z.enum(['mainnet', 'devnet']).default('mainnet'),
		shareholders: z
			.array(
				z.object({
					address: z.string().min(32).max(44),
					share_bps: z.number().int().min(1).max(10_000),
				}),
			)
			.min(1)
			.max(10)
			.refine((arr) => arr.reduce((s, x) => s + x.share_bps, 0) === 10_000, {
				message: 'share_bps must sum to 10000',
			})
			.refine((arr) => new Set(arr.map((x) => x.address)).size === arr.length, {
				message: 'duplicate shareholder addresses',
			}),
	})
	.refine((b) => b.agent_id || b.avatar_id, { message: 'agent_id or avatar_id required' });

async function handleFeeSharingAgent(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

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

	const body = parse(feeSharingAgentSchema, await readJson(req));
	// Redirects the coin's creator-fee revenue and pays config rent from the agent wallet.
	const ctx = await resolveAgentFeeContext(req, res, body, { agreementContext: 'pump-fee-sharing' });
	if (!ctx) return;

	const newShareholders = body.shareholders.map((s) => {
		const pk = solanaPubkey(s.address);
		if (!pk)
			throw Object.assign(new Error(`invalid shareholder ${s.address}`), {
				status: 400,
				code: 'validation_error',
			});
		return { address: pk, shareBps: s.share_bps };
	});

	try {
		const { sdk, connection } = await getPumpSdk({ network: body.network });
		const [
			{ feeSharingConfigPda, bondingCurvePda },
			{ canonicalPumpPoolPda },
			{ isLegacyQuoteMint },
		] = await Promise.all([
			import('@pump-fun/pump-sdk'),
			import('@pump-fun/pump-swap-sdk'),
			getPumpSdkV2({ network: body.network }),
		]);

		const mintPk = new PublicKey(body.mint);
		const creator = ctx.loaded.keypair.publicKey;

		// The sharing-config account existing on-chain means the split has already
		// been initialized: skip creation and go straight to updating shares.
		const cfgPda = feeSharingConfigPda(mintPk);
		const cfgInfo = await connection.getAccountInfo(cfgPda);
		const configExists = !!cfgInfo;

		const signatures = [];

		// Step 1: create the config if it doesn't exist yet. A fresh config seeds
		// the creator as the sole shareholder at 10000 bps.
		if (!configExists) {
			const bcInfo = await connection.getAccountInfo(bondingCurvePda(mintPk));
			const bc = bcInfo ? sdk.decodeBondingCurve(bcInfo) : null;
			const poolPk =
				bc && bc.quoteMint && !isLegacyQuoteMint(bc.quoteMint)
					? canonicalPumpPoolPda(mintPk, bc.quoteMint)
					: canonicalPumpPoolPda(mintPk);
			const createIx = await sdk.createFeeSharingConfig({
				creator,
				mint: mintPk,
				pool: poolPk,
			});
			signatures.push(
				await signSendWithAgent({
					network: body.network,
					agentKeypair: ctx.loaded.keypair,
					instructions: [...(await coinSweepInstructions(connection, mintPk, creator)), createIx],
				}),
			);
		}

		// Step 2: set the shareholder split. Right after creation the current set
		// is [creator] at 10000 bps; otherwise it's whatever the cached config holds.
		const cached = Array.isArray(ctx.mintRow.sharing_config?.shareholders)
			? ctx.mintRow.sharing_config.shareholders
			: null;
		const currentShareholders =
			configExists && cached?.length
				? cached.map((s) => new PublicKey(s.address))
				: [creator];
		const updateIx = await sdk.updateFeeShares({
			authority: creator,
			mint: mintPk,
			currentShareholders,
			newShareholders,
		});
		signatures.push(
			await signSendWithAgent({
				network: body.network,
				agentKeypair: ctx.loaded.keypair,
				instructions: [...(await coinSweepInstructions(connection, mintPk, creator)), updateIx],
			}),
		);

		// Cache the split so the next update knows the current shareholder set and
		// the UI reflects delegation immediately. On-chain fee-info remains the
		// source of truth.
		const sharingConfig = {
			address: cfgPda.toBase58(),
			admin: creator,
			shareholders: body.shareholders.map((s) => ({ address: s.address, bps: s.share_bps })),
			updated_at: new Date().toISOString(),
		};
		await sql`
			update pump_agent_mints set sharing_config=${JSON.stringify(sharingConfig)}::jsonb
			where id=${ctx.mintRow.id}
		`;
		await sql`
			insert into agent_actions (agent_id, type, payload, source_skill)
			values (${ctx.agent.id}, ${'pumpfun.set_fee_sharing'},
				${JSON.stringify({ mint: body.mint, network: body.network, shareholders: sharingConfig.shareholders, signatures, source: 'studio_agent_wallet' })}::jsonb,
				${'pumpfun'})
		`.catch((e) => console.error('[pump/fee-sharing-agent] log failed', e?.message));

		return json(res, 201, {
			ok: true,
			mint: body.mint,
			network: body.network,
			created: !configExists,
			signatures,
			sharing_config: sharingConfig,
			explorer: `https://solscan.io/tx/${signatures[signatures.length - 1]}${body.network === 'devnet' ? '?cluster=devnet' : ''}`,
		});
	} catch (e) {
		return error(
			res,
			e.status || 502,
			e.code || 'rpc_error',
			e.message || 'fee sharing failed',
		);
	}
}

// ── github-resolve ─────────────────────────────────────────────────────────
// Validate a GitHub handle and return its public profile + numeric id. The
// numeric id is what pump.fun's social-fee program keys on (platform=2), and
// the avatar/profile let the launch UI confirm "rewards → @handle" before the
// user delegates fees. Read-only; best-effort (GitHub rate-limits unauthed IPs
// at 60/hr: set GITHUB_TOKEN to raise that).

async function handleGithubResolve(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;

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

	const url = new URL(req.url, `http://${req.headers.host}`);
	const handle = (url.searchParams.get('handle') || '').replace(/^@/, '').trim();
	if (!/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/.test(handle)) {
		return error(res, 400, 'validation_error', 'invalid github handle');
	}

	// A GitHub login maps to one numeric id for the account's whole life, so a
	// resolved profile is safe to hold for days: a 60/hr unauthenticated rate
	// limit window must not turn "rewards to @handle" into a 502.
	const lkgKey = `github:user:lkg:${handle.toLowerCase()}`;
	const GITHUB_LKG_TTL_S = 7 * 24 * 3600;
	const serveLastGood = async (status, code, message) => {
		const lkg = await cacheGet(lkgKey);
		if (lkg && lkg.body && typeof lkg.at === 'number') {
			res.setHeader('x-github-stale', '1');
			return json(res, 200, staleEnvelope(lkg.body, lkg.at));
		}
		if (status === 429 || status === 502) res.setHeader('Retry-After', '15');
		return error(res, status, code, message, ...(status === 429 || status === 502 ? [{ retry_after: 15 }] : []));
	};

	try {
		const headers = { 'user-agent': 'three.ws', accept: 'application/vnd.github+json' };
		if (process.env.GITHUB_TOKEN) headers.authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
		const gh = await fetch(`https://api.github.com/users/${encodeURIComponent(handle)}`, {
			headers,
			signal: AbortSignal.timeout(8000),
		});
		if (gh.status === 404)
			return error(res, 404, 'github_user_not_found', `@${handle} not found on GitHub`);
		if (gh.status === 403 || gh.status === 429)
			return serveLastGood(429, 'github_rate_limited', 'GitHub rate limit, try again shortly');
		if (!gh.ok) return serveLastGood(502, 'github_error', `github responded ${gh.status}`);
		const j = await gh.json();
		if (!j?.id) return serveLastGood(502, 'github_error', 'github id missing');
		const body = {
			ok: true,
			login: j.login,
			id: String(j.id), // social-fee user_id (≤20 chars, fits u64)
			name: j.name || null,
			avatar_url: j.avatar_url || null,
			html_url: j.html_url || `https://github.com/${j.login}`,
			type: j.type || 'User',
		};
		cacheSet(lkgKey, { body, at: Date.now() }, GITHUB_LKG_TTL_S).catch(() => {});
		return json(res, 200, body);
	} catch (e) {
		const lkg = await cacheGet(lkgKey);
		if (lkg && lkg.body && typeof lkg.at === 'number') {
			res.setHeader('x-github-stale', '1');
			return json(res, 200, staleEnvelope(lkg.body, lkg.at));
		}
		res.setHeader('Retry-After', '15');
		return respondError(res, 502, 'github_error', e, { retry_after: 15 });
	}
}

// Read pump.fun's global FeeProgramGlobal account and decode the single field we
// need: `social_claim_authority`: the only signer allowed to release social
// (GitHub/X) fee claims. We surface it so the UI can be honest that claiming
// native social rewards is gated by pump.fun, not self-custodial. No exported
// decoder exists for FeeProgramGlobal, so we slice the known layout:
//   [8 disc][1 bump][32 authority][1 disable_flags][32 social_claim_authority]…
async function readSocialClaimAuthority(connection) {
	try {
		const { FEE_PROGRAM_GLOBAL_PDA } = await import('@pump-fun/pump-sdk');
		const info = await connection.getAccountInfo(FEE_PROGRAM_GLOBAL_PDA);
		if (!info?.data || info.data.length < 8 + 1 + 32 + 1 + 32) return null;
		const off = 8 + 1 + 32 + 1;
		return new PublicKey(info.data.subarray(off, off + 32)).toBase58();
	} catch {
		return null;
	}
}

// ── social-fee-claim-status ────────────────────────────────────────────────
// Read-only view of a GitHub/X identity's pump.fun social-fee PDA: how much has
// accrued and been claimed, and the gated deep-link to claim it. We CANNOT build
// a claim tx ourselves: claim_social_fee_pda requires pump.fun's global
// `social_claim_authority` to co-sign: so this endpoint is read + deep-link.
// Self-custodial "reward" delegation is the fee-sharing split (see
// fee-sharing-agent / update-fee-shares-prep), which IS claimable directly.

async function handleSocialFeeClaimStatus(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;

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

	const url = new URL(req.url, `http://${req.headers.host}`);
	const userId = (url.searchParams.get('user_id') || '').trim();
	const platform = Number(url.searchParams.get('platform') ?? '2'); // 0=pump 1=X 2=GitHub
	const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
	if (!/^\d{1,20}$/.test(userId))
		return error(res, 400, 'validation_error', 'numeric user_id required');
	if (![0, 1, 2].includes(platform))
		return error(res, 400, 'validation_error', 'platform must be 0,1,2');

	try {
		const connection = getConnection({ network });
		const { socialFeePda, PUMP_SDK } = await import('@pump-fun/pump-sdk');
		const pda = socialFeePda(userId, platform);
		const info = await connection.getAccountInfo(pda);

		let decoded = null;
		let claimableLamports = 0n;
		if (info) {
			claimableLamports = BigInt(info.lamports) - MIN_RENT_EXEMPTION_LAMPORTS;
			if (claimableLamports < 0n) claimableLamports = 0n;
			try {
				const d = PUMP_SDK.decodeSocialFeePda(info);
				decoded = {
					user_id: d.userId,
					platform: Number(d.platform),
					total_claimed_lamports: d.totalClaimed?.toString?.() ?? '0',
					last_claimed: d.lastClaimed?.toString?.() ?? '0',
				};
			} catch {
				/* layout drift: still return the balance */
			}
		}

		const social_claim_authority = await readSocialClaimAuthority(connection);
		return json(res, 200, {
			user_id: userId,
			platform,
			network,
			social_fee_pda: pda.toBase58(),
			exists: !!info,
			claimable_lamports: claimableLamports.toString(),
			claimable_sol: Number(claimableLamports) / LAMPORTS_PER_SOL,
			decoded,
			// Claiming is gated: only pump.fun's social_claim_authority can sign.
			gated: true,
			social_claim_authority,
			claim_url: 'https://pump.fun/profile',
		});
	} catch (e) {
		return error(
			res,
			e.status || 502,
			e.code || 'pump_sdk_error',
			e.message || 'failed to read social fee status',
		);
	}
}

function _sse(res, event, data) {
	res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
}