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.

48.0 KB
Raw Blame
// POST /api/x402-pay
//
// Server-side x402 payer for the /pay demo. Streams the payment lifecycle
// (challenge → build → verify → settle → result) as Server-Sent Events when
// the client requests `accept: text/event-stream`; otherwise returns a single
// JSON envelope on completion.
//
// In-process: this handler skips the HTTP round-trip to /api/mcp by
// replicating the same flow internally — paymentRequirements() + verifyPayment +
// dispatch() + settlePayment(). Saves ~50–200ms vs an external fetch and
// removes a self-egress hop.
//
// Env (required for prod): the x402 payer keypair, resolved via loadSeedKeypair
//   from X402_SEED_SOLANA_SECRET_BASE58 (primary) then X402_AGENT_SOLANA_SECRET_BASE58
//   (fallback name) — the same wallet the x402 ring pays from (see solana-signers.js
//   x402-ring-payer). Accepts base58 / base64 / JSON-array encodings.
// Local dev fallback (NODE_ENV !== 'production' only): reads keypair JSON at
//   /home/codespace/.config/x402-test-wallets/solana.json
//
// Also: GET /api/x402-pay?balance=1 → returns the agent wallet's USDC + SOL
// balance so the UI can show it ticking down during the demo.

import { solanaConnection } from './_lib/solana/connection.js';
import {
	PublicKey, TransactionMessage, VersionedTransaction, ComputeBudgetProgram,
} from '@solana/web3.js';
import {
	getAssociatedTokenAddressSync, createTransferCheckedInstruction,
	createAssociatedTokenAccountIdempotentInstruction,
	TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
} from '@solana/spl-token';
import { mintDecimals, ataExists, getRecentBlockhash, isRpcUnavailable, RPC_RETRY_AFTER_SECONDS } from './_lib/solana/read-guards.js';
import { cors, json, readJson, wrap, rateLimited, setRateLimitHeaders, respondError } from './_lib/http.js';
import { limits, clientIp } from './_lib/rate-limit.js';
import { requireCsrf } from './_lib/csrf.js';
import {
	paymentRequirements,
	verifyPayment,
	settlePayment,
	resolveResourceUrl,
	NETWORK_SOLANA_MAINNET,
} from './_lib/x402-spec.js';
import { loadSeedKeypair } from './_lib/x402/pay.js';
import { dispatch } from './_mcp/dispatch.js';
import { env } from './_lib/env.js';
import { getRedis as _getSharedRedis } from './_lib/redis.js';
import { sql } from './_lib/db.js';
import { thumbnailUrl } from './_lib/r2.js';
import { logger } from './_lib/usage.js';
import { getSessionUser, authenticateBearer, extractBearer } from './_lib/auth.js';
import { assertBearerMaySpend } from './_lib/spend-scope.js';
import { recoverSolanaAgentKeypair } from './_lib/agent-wallet.js';
import { requireRealFundsAgreement } from './_lib/real-funds-agreement.js';
import { SpendLimitError, reserveSpendUsd, updateCustodyEvent, releaseSpendReservation } from './_lib/agent-trade-guards.js';
import { validatePublicUrl, resolvePublicHost, pinnedAgent, disposeAgent, SsrfError } from './_lib/ssrf.js';
import { BUILDER_CODE } from './_lib/x402-builder-code.js';

const log = logger('x402-pay');

// ---- Persistent feed of recent paid calls -------------------------------
// Backed by Upstash Redis when available; falls back to an in-memory ring
// in dev so the feed still works locally.
const FEED_KEY = 'x402:pay:feed';
const FEED_MAX = 50;
const memFeed = [];

function redis() { return _getSharedRedis(); }

async function recordFeedEntry(entry) {
	const r = redis();
	if (r) {
		try {
			await r.lpush(FEED_KEY, JSON.stringify(entry));
			await r.ltrim(FEED_KEY, 0, FEED_MAX - 1);
		} catch (err) {
			log.warn('feed_write_failed', { message: err?.message });
		}
	}
	feedReadCache = null; // a new payment must show up on the next read
	memFeed.unshift(entry);
	if (memFeed.length > FEED_MAX) memFeed.length = FEED_MAX;
}

// The feed is polled by several always-on surfaces (the /pay page, the in-world
// jumbotron and exchange NPCs), and every poll used to spend a Redis LRANGE.
// That steady drip was a top contributor to exhausting the Upstash monthly
// request quota (June 2026). One instance-local snapshot per FEED_CACHE_TTL_MS,
// with in-flight coalescing, collapses all of it to ≤ one command per window —
// a few seconds of staleness on a public activity feed is invisible.
const FEED_CACHE_TTL_MS = 10_000;
let feedReadCache = null; // { at: epoch-ms, rows: entry[] }
let feedReadInflight = null;

async function readFeed(limit = 25) {
	const r = redis();
	if (r) {
		if (feedReadCache && Date.now() - feedReadCache.at < FEED_CACHE_TTL_MS) {
			return feedReadCache.rows.slice(0, limit);
		}
		// The inflight promise must never reject: both the originating call and any
		// coalesced waiters await it, and an unhandled rejection on a Redis outage
		// (e.g. WRONGPASS) would otherwise surface as a 500 instead of degrading to
		// the in-memory feed. Catch inside and fall back here.
		if (!feedReadInflight) {
			feedReadInflight = (async () => {
				try {
					const raw = await r.lrange(FEED_KEY, 0, FEED_MAX - 1);
					const rows = raw
						.map((row) => {
							if (typeof row === 'string') {
								try {
									return JSON.parse(row);
								} catch (parseErr) {
									log.warn('feed_row_parse_failed', { message: parseErr?.message });
									return null;
								}
							}
							return row;
						})
						.filter(Boolean);
					feedReadCache = { at: Date.now(), rows };
					return rows;
				} catch (err) {
					if (!err?.circuitOpen) log.warn('feed_read_failed', { message: err?.message });
					return memFeed.slice();
				} finally {
					feedReadInflight = null;
				}
			})();
		}
		const rows = await feedReadInflight;
		return rows.slice(0, limit);
	}
	return memFeed.slice(0, limit);
}

// Per-tx record so /pay/calls/<tx> can show the full receipt + tool result.
// A Solana signature is 64 bytes of base58 (86-88 chars); the bound is generous
// enough for any real signature and tight enough that the Redis key stays bounded.
export const TX_SIGNATURE_RE = /^[1-9A-HJ-NP-Za-km-z]{32,128}$/;
const memCalls = new Map();
const CALL_KEY = (tx) => `x402:pay:call:${tx}`;
const CALL_TTL_SECONDS = 60 * 60 * 24 * 30; // 30 days

async function persistCall(tx, record) {
	const r = redis();
	if (r) {
		try {
			await r.set(CALL_KEY(tx), JSON.stringify(record), { ex: CALL_TTL_SECONDS });
		} catch (err) {
			log.warn('call_persist_failed', { tx, message: err?.message });
		}
	}
	memCalls.set(tx, record);
}

async function readCall(tx) {
	const r = redis();
	if (r) {
		try {
			const row = await r.get(CALL_KEY(tx));
			if (typeof row === 'string') {
				try {
					return JSON.parse(row);
				} catch (parseErr) {
					log.warn('call_read_parse_failed', { tx, message: parseErr?.message });
				}
			} else if (row && typeof row === 'object') return row;
		} catch (err) {
			log.warn('call_read_failed', { tx, message: err?.message });
		}
	}
	return memCalls.get(tx) || null;
}

// ---- User auth + agent wallet loading ----------------------------------

async function requireAuth(req) {
	let bearer = null;
	try {
		const session = await getSessionUser(req);
		if (session) return { userId: session.id };
		bearer = await authenticateBearer(extractBearer(req));
	} catch (err) {
		log.warn('require_auth_failed', { message: err?.message });
	}
	if (!bearer) return null;
	assertBearerMaySpend(bearer, req);
	return { userId: bearer.userId };
}

// Decide which wallet signs an x402 payment. An agent context — an `agentId`
// on the request, which the wallet hub always sends and any authenticated owner
// call carries — ALWAYS pays from that agent's own custodial wallet. The shared
// platform wallet (X402_AGENT_SOLANA_SECRET_BASE58) is an explicit fallback for
// platform-level/demo calls that carry no agent context. The handler logs that
// fallback so a regression where an agent call drops its agentId is visible in
// the logs instead of silently spending the shared wallet on the agent's behalf.
export function resolvePayerRouting(input) {
	const agentId = input && input.agentId ? String(input.agentId) : '';
	if (agentId) return { mode: 'agent', agentId };
	return { mode: 'platform' };
}

async function loadAgentKeypairForUser(agentId, userId) {
	const [row] = await sql`
		SELECT id, meta FROM agent_identities
		WHERE id = ${agentId} AND user_id = ${userId} AND deleted_at IS NULL
	`;
	if (!row) return null;
	const enc = row.meta?.encrypted_solana_secret;
	if (!enc) return null;
	const keypair = await recoverSolanaAgentKeypair(enc, {
		agentId,
		userId,
		reason: 'x402_pay_tool_call',
	});
	// Carry the agent meta so the caller can enforce + record against the shared
	// per-agent spend policy without a second DB round-trip.
	return { keypair, meta: row.meta || {} };
}

async function getAgentsForUser(userId) {
	const rows = await sql`
		SELECT i.id, i.name, i.description, i.avatar_id, i.meta,
		       a.thumbnail_key AS avatar_thumbnail_key,
		       a.visibility    AS avatar_visibility
		FROM agent_identities i
		LEFT JOIN avatars a ON a.id = i.avatar_id AND a.deleted_at IS NULL
		WHERE i.user_id = ${userId} AND i.deleted_at IS NULL
		ORDER BY i.created_at ASC
	`;
	const conn = solanaConnection({ url: SOLANA_RPC, commitment: 'confirmed' });
	return Promise.all(rows.map(async (row) => {
		const address = row.meta?.solana_address || null;
		const source = row.meta?.solana_wallet_source || null;
		let usdc = null;
		let sol = null;
		if (address) {
			try {
				const lamports = await conn.getBalance(new PublicKey(address));
				sol = lamports / 1e9;
			} catch (err) {
				log.warn('agent_sol_balance_failed', { address, message: err?.message });
			}
			try {
				const ata = getAssociatedTokenAddressSync(
					new PublicKey(USDC_MAINNET_MINT),
					new PublicKey(address), false, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
				);
				const acct = await conn.getTokenAccountBalance(ata);
				usdc = Number(acct.value.uiAmount || 0);
			} catch (err) {
				// Missing ATA throws TokenAccountNotFoundError — that's an expected
				// state (agent never received USDC), so debug not warn.
				if (!/could not find account|TokenAccountNotFound/i.test(err?.message || '')) {
					log.warn('agent_usdc_balance_failed', { address, message: err?.message });
				}
				usdc = 0;
			}
		}
		// Thumbnails carry the same public/unlisted gate as everywhere else
		// (api/agents.js, characters.js): a private avatar's R2 object is not
		// publicly readable, so emitting its URL only paints a broken image.
		// Null lets the card fall back to the initial-letter avatar it already
		// renders as a sibling.
		const avatarPubliclyReadable =
			row.avatar_visibility === 'public' || row.avatar_visibility === 'unlisted';
		return {
			id: row.id,
			name: row.name,
			description: row.description,
			avatar_id: row.avatar_id,
			avatar_thumbnail_url:
				row.avatar_thumbnail_key && avatarPubliclyReadable
					? thumbnailUrl(row.avatar_thumbnail_key)
					: null,
			solana_address: address,
			solana_wallet_source: source,
			usdc,
			sol,
		};
	}));
}

function summarizeArgs(args) {
	if (!args || typeof args !== 'object') return '';
	if (args.url) {
		try { return new URL(args.url).pathname.split('/').pop() || args.url; }
		catch { return args.url.slice(0, 40); }
	}
	if (args.q) return `q=${String(args.q).slice(0, 24)}`;
	const keys = Object.keys(args);
	return keys.length ? keys.map((k) => `${k}=${String(args[k]).slice(0,16)}`).join(' ') : '';
}

const ALLOWED_TOOLS = new Set([
	'tools/list',
	'validate_model',
	'inspect_model',
	'optimize_model',
	'search_public_avatars',
]);

// In-house x402 routes the public showcase pages buy from the shared platform
// wallet (/agent-exchange drives the crypto-intel one). This branch is
// unauthenticated, exactly like the MCP `tool` path above, and it spends real
// USDC per call, so what it can buy is a fixed server-side allowlist and never
// a caller-supplied URL. Arbitrary endpoints go through handleExternalPay,
// which is owner-authenticated and pays from that owner's own agent wallet.
const SHOWCASE_ENDPOINTS = new Set(['/api/x402/crypto-intel']);

const SOLANA_RPC = env.SOLANA_RPC_URL;
const USDC_MAINNET_MINT = env.X402_ASSET_MINT_SOLANA;

let _agent = null;
function loadAgentKeypair() {
	if (_agent) return _agent;
	// Single source of truth for the x402 payer keypair: loadSeedKeypair honors
	// the registry's declared chain (X402_SEED_SOLANA_SECRET_BASE58 first, then
	// the X402_AGENT_SOLANA_SECRET_BASE58 fallback name — see solana-signers.js
	// x402-ring-payer), auto-detects base58/base64/JSON encodings, and reads the
	// dev test keypair off disk when NODE_ENV !== 'production'. Reusing it keeps
	// this endpoint on the same wallet as the ring payer instead of a second,
	// separately-configured key.
	try {
		_agent = loadSeedKeypair();
		return _agent;
	} catch (err) {
		const e = new Error(err?.message || 'x402 agent wallet not configured');
		e.status = 503;
		e.code = /undecodable/i.test(err?.message || '') ? 'wallet_misconfigured' : 'wallet_unconfigured';
		e.cause = err;
		throw e;
	}
}

function buildJsonRpc(tool, args) {
	if (tool === 'tools/list') return { jsonrpc: '2.0', id: 1, method: 'tools/list' };
	return {
		jsonrpc: '2.0',
		id: 1,
		method: 'tools/call',
		params: { name: tool, arguments: args || {} },
	};
}

export async function buildSolanaPaymentPayload({ accept, buyer, conn, resourceUrl }) {
	const mint = new PublicKey(accept.asset);
	const payTo = new PublicKey(accept.payTo);
	// An accept with no feePayer is the x402 self-pay contract (x402-spec.js drops
	// it while the sponsor sits under its SOL floor): the buyer pays its own fee,
	// as in x402-checkout.js. Only the self-routed facilitator advertises it.
	const feePayer = accept.extra?.feePayer ? new PublicKey(accept.extra.feePayer) : buyer.publicKey;
	const amount = BigInt(accept.amount);

	const senderAta = getAssociatedTokenAddressSync(
		mint, buyer.publicKey, false, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
	);
	const receiverAta = getAssociatedTokenAddressSync(
		mint, payTo, false, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
	);
	// Guarded reads (api/_lib/solana/read-guards.js): USDC decimals never touch the
	// network, the ATA probe fails open to an idempotent create, and the blockhash
	// is served from cache inside its validity window when every RPC lane is down.
	// What still fails throws a typed 503 rpc_unavailable; no funds have moved yet.
	const decimals = await mintDecimals(conn, mint);

	const ixs = [
		ComputeBudgetProgram.setComputeUnitLimit({ units: 60_000 }),
		ComputeBudgetProgram.setComputeUnitPrice({ microLamports: 1 }),
	];
	if (!(await ataExists(conn, receiverAta))) {
		ixs.push(createAssociatedTokenAccountIdempotentInstruction(
			feePayer, receiverAta, payTo, mint,
			TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
		));
	}
	ixs.push(createTransferCheckedInstruction(
		senderAta, mint, receiverAta, buyer.publicKey,
		amount, decimals, [], TOKEN_PROGRAM_ID,
	));

	const blockhash = await getRecentBlockhash(conn, SOLANA_RPC);
	const message = new TransactionMessage({
		payerKey: feePayer,
		recentBlockhash: blockhash,
		instructions: ixs,
	}).compileToV0Message();
	const vtx = new VersionedTransaction(message);
	vtx.sign([buyer]);

	const txBase64 = Buffer.from(vtx.serialize()).toString('base64');
	return {
		x402Version: 2,
		scheme: 'exact',
		network: accept.network,
		// PayAI's v2 facilitator schema rejects a bare-string `resource` with
		// `invalid_payload` — it requires the same `{url, mimeType}` object
		// shape as the 402-challenge top-level resource. Keep them aligned.
		resource: { url: resourceUrl, mimeType: 'application/json' },
		accepted: accept,
		payload: { transaction: txBase64 },
	};
}

// ── External x402 endpoint pay (wallet hub "Pay" tab) ─────────────────────
// Pays an ARBITRARY x402 endpoint discovered via the bazaar from the agent's
// own Solana wallet. Distinct from runFlow (which pays the platform's own MCP):
// here the 402 challenge, payTo, asset and feePayer all come from the external
// resource server, and that server — not us — verifies + settles. We only build
// and sign the SPL transfer with the agent key and present it as X-PAYMENT.

// A paid flow makes TWO sequential calls to the external resource server (the 402
// probe, then the X-PAYMENT settle) plus on-chain blockhash + settlement work, all
// inside the function's 60s ceiling. At the old 30s-per-fetch budget two slow
// probes alone consumed the entire window, leaving nothing for settlement and
// surfacing a 504 instead of a clean, retryable timeout. 20s still tolerates a
// genuinely slow-but-alive server while leaving room for the second call + Solana.
const EXTERNAL_FETCH_TIMEOUT_MS = 20_000;

// SSRF-guarded one-shot fetch of an untrusted URL: https-only (http in dev),
// DNS resolved + checked against the private-range blocklist, the socket pinned
// to the validated addresses (closes the DNS-rebinding TOCTOU), redirects never
// followed into an internal target. Returns { status, ok, headers, text }.
// Throws SsrfError on a blocked target.
async function guardedFetch(rawUrl, { method = 'GET', headers = {}, body } = {}) {
	const url = validatePublicUrl(rawUrl);
	const addrs = await resolvePublicHost(url.hostname);
	const agent = pinnedAgent(url.hostname, addrs);
	const controller = new AbortController();
	const timer = setTimeout(() => controller.abort(), EXTERNAL_FETCH_TIMEOUT_MS);
	try {
		const res = await fetch(url, {
			method,
			redirect: 'manual',
			signal: controller.signal,
			dispatcher: agent,
			headers: {
				'user-agent': '3d-agent-x402/1.0 (+https://three.ws/)',
				accept: 'application/json, text/plain;q=0.8, */*;q=0.5',
				...(body != null ? { 'content-type': 'application/json' } : {}),
				...headers,
			},
			...(body != null
				? { body: typeof body === 'string' ? body : JSON.stringify(body) }
				: {}),
		});
		const text = await res.text();
		return { status: res.status, ok: res.ok, headers: res.headers, text };
	} finally {
		clearTimeout(timer);
		await disposeAgent(agent);
	}
}

// Hostname of a URL (or null) — used as the scoped-capability holder ref / target
// host for x402 payments, so an owner can leash an integration to specific services.
function hostOf(u) {
	try { return new URL(String(u)).hostname || null; } catch { return null; }
}

function safeJsonParse(text) {
	if (typeof text !== 'string' || !text) return null;
	try {
		return JSON.parse(text);
	} catch {
		return null;
	}
}

function b64decodeJson(s) {
	if (!s) return null;
	try {
		return JSON.parse(Buffer.from(String(s), 'base64').toString('utf8'));
	} catch {
		return null;
	}
}

// Probe an external x402 endpoint for its payment requirements WITHOUT paying.
// Returns the parsed 402 challenge + the Solana accept (the only network an
// agent wallet can pay), { free: true } when the endpoint served a result
// without a 402, or { unsupported: true, networks } when it has no Solana accept.
async function probeExternalRequirements({ url, method, body }) {
	let res;
	try {
		res = await guardedFetch(url, { method, body });
	} catch (err) {
		if (err instanceof SsrfError) {
			throw Object.assign(new Error('that endpoint is not a reachable public https URL'), {
				status: 400,
				code: 'blocked_url',
			});
		}
		throw Object.assign(
			new Error(`could not reach the service: ${err?.message || 'network error'}`),
			{ status: 502, code: 'endpoint_unreachable' },
		);
	}
	if (res.status !== 402) {
		// The endpoint returned without challenging for payment — nothing to pay.
		return { free: true, status: res.status, result: safeJsonParse(res.text) ?? res.text };
	}
	const challenge = safeJsonParse(res.text) || b64decodeJson(res.headers.get('payment-required'));
	if (!challenge || !Array.isArray(challenge.accepts)) {
		throw Object.assign(new Error('the service returned an unreadable payment challenge'), {
			status: 502,
			code: 'invalid_challenge',
		});
	}
	const solAccept = challenge.accepts.find(
		(a) => typeof a?.network === 'string' && a.network.startsWith('solana'),
	);
	if (!solAccept) {
		const networks = [...new Set(challenge.accepts.map((a) => a?.network).filter(Boolean))];
		return { unsupported: true, networks, challenge };
	}
	// Pin the asset to the configured Solana USDC mint. Without this an external
	// server could name ANY SPL token as `asset` (e.g. one the agent holds) and we
	// would sign a transferChecked of THAT token — draining the wallet — while the
	// USD spend cap (which divides amount by 1e6 assuming 6-decimal USDC) badly
	// mis-counts a non-USDC charge. Refuse anything that isn't the known USDC mint.
	if (!USDC_MAINNET_MINT || solAccept.asset !== USDC_MAINNET_MINT) {
		throw Object.assign(
			new Error('this service requested payment in a non-USDC asset; agent wallets only pay Solana USDC'),
			{
				status: 422,
				code: 'unsupported_asset',
				detail: { asset: solAccept.asset ?? null, expected: USDC_MAINNET_MINT ?? null },
			},
		);
	}
	const resource =
		challenge.resource && typeof challenge.resource === 'object'
			? challenge.resource
			: { url: typeof challenge.resource === 'string' ? challenge.resource : url };
	return { challenge, accept: solAccept, resource };
}

// Echo the builder-code app tag the challenge declared so the external server's
// on-chain attribution is honoured (mirrors x402-buyer-fetch.ensureBuilderCodeEcho).
function echoBuilderCode(challenge, paymentPayload) {
	const declaredA = challenge?.extensions?.[BUILDER_CODE]?.info?.a;
	if (!declaredA) return paymentPayload;
	const existing = paymentPayload.extensions || {};
	const block = { ...(existing[BUILDER_CODE] || {}), a: declaredA };
	if (env.X402_BUILDER_CODE_WALLET && !block.w) block.w = env.X402_BUILDER_CODE_WALLET;
	paymentPayload.extensions = { ...existing, [BUILDER_CODE]: block };
	return paymentPayload;
}

// Summarize the resource a probe surfaced for the SSE 'challenge'/'result' events
// and the spend ledger — never trust raw fields into innerHTML on the client.
function resourceSummary(probe, fallbackUrl) {
	const r = probe.resource || {};
	return {
		url: r.url || fallbackUrl,
		description: typeof r.description === 'string' ? r.description : null,
		serviceName: typeof r.serviceName === 'string' ? r.serviceName : null,
	};
}

// Run the full external-endpoint pay flow, emitting the same SSE event vocabulary
// the internal flow uses (challenge → built → settled → result) so the client can
// render one progress timeline. `buyer` is the agent's recovered keypair.
async function runExternalFlow({ url, method, body, emit, buyer, spendGuard, serviceLabel }) {
	const conn = solanaConnection({ url: SOLANA_RPC, commitment: 'confirmed' });

	const probe = await probeExternalRequirements({ url, method, body });
	if (probe.free) {
		emit('result', { ok: true, free: true, result: probe.result, payment: null });
		return;
	}
	if (probe.unsupported) {
		throw Object.assign(
			new Error('this service does not accept Solana USDC — agent wallets pay in Solana USDC'),
			{ status: 422, code: 'no_solana_accept', detail: { networks: probe.networks } },
		);
	}
	const accept = probe.accept;
	if (!accept.extra?.feePayer) {
		throw Object.assign(
			new Error('the service did not advertise a Solana fee payer, so it cannot be paid from here'),
			{ status: 422, code: 'missing_fee_payer' },
		);
	}
	const resource = resourceSummary(probe, url);
	const spendUsd = Number(accept.amount) / 1e6;
	const t0 = Date.now();
	emit('challenge', {
		network: accept.network,
		amount: accept.amount,
		asset: accept.asset,
		payTo: accept.payTo,
		price_usdc: spendUsd,
		resource,
	});

	// Per-agent spend policy — enforced BEFORE the payment is built/signed so a
	// breach moves no funds. reserveSpendUsd atomically checks the cap AND writes a
	// pending ledger row under a per-agent lock, so concurrent calls can't all pass
	// the same stale daily total and overspend the cap. Finalize/release below.
	let spendReservationId = null;
	if (spendGuard) {
		try {
			const reservation = await reserveSpendUsd({
				agentId: spendGuard.agentId,
				userId: spendGuard.userId,
				meta: spendGuard.meta,
				category: 'x402',
				usdValue: spendUsd,
				destination: accept.payTo,
				network: 'mainnet',
				asset: 'USDC',
				// Scoped session keys: the service URL is the capability target (a
				// service-scoped grant matches on its host), and the host is the holder
				// ref so a per-integration capability resolves preferentially.
				target: resource.url || url,
				capabilityHolderRef: hostOf(resource.url || url),
				rowMeta: { url, service: serviceLabel || resource.serviceName || null, resource: resource.url },
			});
			spendReservationId = reservation.reservationId;
		} catch (e) {
			if (e instanceof SpendLimitError) {
				throw Object.assign(new Error(e.message), { status: e.status, code: e.code, detail: e.detail });
			}
			throw e;
		}
	}

	const paymentPayload = await buildSolanaPaymentPayload({
		accept,
		buyer,
		conn,
		resourceUrl: resource.url,
	});
	echoBuilderCode(probe.challenge, paymentPayload);
	const tBuilt = Date.now();
	emit('built', { build_ms: tBuilt - t0 });

	const xPayment = Buffer.from(JSON.stringify(paymentPayload)).toString('base64');
	let paid;
	try {
		paid = await guardedFetch(url, { method, body, headers: { 'X-PAYMENT': xPayment } });
	} catch (err) {
		// The signed payment went out but we never saw the response — the chain
		// state is unknown, so do NOT promise the wallet was untouched.
		throw Object.assign(
			new Error('the payment was submitted but its status could not be confirmed — check the wallet activity before retrying'),
			{ status: 502, code: 'settle_uncertain', cause: err },
		);
	}
	const paidJson = safeJsonParse(paid.text) ?? paid.text;
	if (!paid.ok) {
		if (paid.status === 402) {
			// Explicit pre-settlement rejection: no funds moved, so release the
			// reservation — it must not count toward the daily cap. (The
			// settle_uncertain path below deliberately KEEPS the reservation:
			// chain state is unknown, so we conservatively count it as spent.)
			if (spendReservationId) await releaseSpendReservation(spendReservationId, 'payment_rejected_402');
			throw Object.assign(
				new Error('the service rejected the payment before settlement; no funds were transferred'),
				{ status: 402, code: 'payment_required', detail: typeof paidJson === 'object' ? paidJson : null },
			);
		}
		throw Object.assign(
			new Error(`the service returned an error after payment (HTTP ${paid.status}); check the wallet activity before retrying`),
			{ status: 502, code: 'settle_uncertain', detail: typeof paidJson === 'object' ? paidJson : null },
		);
	}
	const settled = b64decodeJson(paid.headers.get('x-payment-response'));
	const tx = settled?.transaction || null;
	const payer = settled?.payer || buyer.publicKey.toBase58();
	const tSettled = Date.now();
	emit('settled', {
		settle_ms: tSettled - tBuilt,
		tx,
		network: settled?.network || accept.network,
		payer,
		explorer: tx ? `https://solscan.io/tx/${tx}` : null,
	});

	// Finalize the pending reservation written before signing: flip it to
	// confirmed/ok and attach the tx signature. It already counts toward the daily
	// cap (written under the advisory lock), so this just records the outcome.
	if (spendReservationId) {
		void updateCustodyEvent(spendReservationId, {
			status: tx ? 'confirmed' : 'ok',
			signature: tx,
			meta: { settledAt: new Date(tSettled).toISOString() },
		}).catch((err) => log.warn('x402_external_spend_record_failed', { message: err?.message }));
	}

	emit('result', {
		ok: true,
		result: paidJson,
		payment: {
			network: settled?.network || accept.network,
			payer,
			payTo: accept.payTo,
			asset: accept.asset,
			amount: accept.amount,
			tx,
			explorer: tx ? `https://solscan.io/tx/${tx}` : null,
		},
		receipt: settled,
		resource,
		durations: { build_ms: tBuilt - t0, settle_ms: tSettled - tBuilt, total_ms: tSettled - t0 },
	});
}

async function getAgentBalance() {
	const buyer = loadAgentKeypair();
	const conn = solanaConnection({ url: SOLANA_RPC, commitment: 'confirmed' });
	const sol = await conn.getBalance(buyer.publicKey);
	let usdc = 0;
	try {
		const ata = getAssociatedTokenAddressSync(
			new PublicKey(USDC_MAINNET_MINT),
			buyer.publicKey, false, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
		);
		const acct = await conn.getTokenAccountBalance(ata);
		usdc = Number(acct.value.uiAmount || 0);
	} catch (err) {
		// Missing ATA is the expected case before the demo wallet has ever held USDC.
		if (!/could not find account|TokenAccountNotFound/i.test(err?.message || '')) {
			log.warn('demo_usdc_balance_failed', { address: buyer.publicKey.toBase58(), message: err?.message });
		}
	}
	return {
		address: buyer.publicKey.toBase58(),
		sol: sol / 1e9,
		usdc,
	};
}

function sseInit(res) {
	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');
	if (typeof res.flushHeaders === 'function') res.flushHeaders();
}

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

async function runFlow({ tool, args, emit, buyer: buyerOverride, resourceUrl, spendGuard = null }) {
	const buyer = buyerOverride ?? loadAgentKeypair();
	const conn = solanaConnection({ url: SOLANA_RPC, commitment: 'confirmed' });

	const requirements = paymentRequirements();
	const accept = requirements.find((r) => r.network === NETWORK_SOLANA_MAINNET);
	if (!accept) throw Object.assign(new Error('no_solana_accept_configured'), { status: 500 });

	// Per-agent spend policy — enforced BEFORE any payment is built/signed so a
	// breach moves no funds. USDC is dollar-denominated (6 decimals), so the
	// payment amount converts straight to the USD ceiling unit.
	const spendUsd = Number(accept.amount) / 1e6;
	let spendReservationId = null;
	if (spendGuard) {
		try {
			const reservation = await reserveSpendUsd({
				agentId: spendGuard.agentId,
				userId: spendGuard.userId,
				meta: spendGuard.meta,
				category: 'x402',
				usdValue: spendUsd,
				destination: accept.payTo,
				network: spendGuard.network || 'mainnet',
				asset: 'USDC',
				// Scoped session keys: the resolved MCP resource is the capability target.
				target: resourceUrl,
				capabilityHolderRef: hostOf(resourceUrl),
				rowMeta: { tool },
			});
			spendReservationId = reservation.reservationId;
		} catch (e) {
			if (e instanceof SpendLimitError) {
				throw Object.assign(new Error(e.message), { status: e.status, code: e.code, detail: e.detail });
			}
			throw e;
		}
	}

	const t0 = Date.now();
	emit('challenge', { network: accept.network, amount: accept.amount, payTo: accept.payTo });

	const paymentPayload = await buildSolanaPaymentPayload({
		accept, buyer, conn, resourceUrl,
	});
	const tBuilt = Date.now();
	emit('built', { build_ms: tBuilt - t0, network: accept.network });

	const paymentHeader = Buffer.from(JSON.stringify(paymentPayload)).toString('base64');
	const verified = await verifyPayment({ paymentHeader, requirements });
	const tVerified = Date.now();
	emit('verified', { verify_ms: tVerified - tBuilt, payer: verified.payer });

	const auth = {
		userId: null,
		rateKey: `x402:${verified.payer || 'anon'}`,
		scope: '',
		source: 'x402',
		payer: verified.payer,
	};
	const rpcResp = await dispatch(buildJsonRpc(tool, args), auth, null);
	const tDispatched = Date.now();
	emit('dispatched', { dispatch_ms: tDispatched - tVerified });

	if (rpcResp?.error) {
		// Dispatch failed before settlement — no funds moved, release the reservation.
		if (spendReservationId) await releaseSpendReservation(spendReservationId, 'mcp_dispatch_error');
		throw Object.assign(
			new Error(rpcResp.error.message || 'mcp_dispatch_error'),
			{ status: 502, mcpError: rpcResp.error },
		);
	}

	const settled = await settlePayment({ verified });
	const tSettled = Date.now();
	emit('settled', {
		settle_ms: tSettled - tDispatched,
		tx: settled.transaction,
		network: settled.network,
		payer: settled.payer,
		explorer: settled.transaction ? `https://solscan.io/tx/${settled.transaction}` : null,
	});

	// Persist a feed entry + per-tx record for the public feed and /pay/calls/<tx>.
	const feedEntry = {
		ts: Date.now(),
		tool,
		argsSummary: summarizeArgs(args),
		tx: settled.transaction || null,
		network: settled.network || accept.network,
		amount: accept.amount,
	};
	void recordFeedEntry(feedEntry).catch((err) => {
		log.warn('feed_record_failed', { tx: settled.transaction, message: err?.message });
	});
	// Finalize the pending reservation written before signing: it already counts
	// toward the daily cap (reserved under the advisory lock); attach the outcome.
	if (spendReservationId) {
		void updateCustodyEvent(spendReservationId, {
			status: settled.transaction ? 'confirmed' : 'ok',
			signature: settled.transaction || null,
		}).catch((err) => log.warn('x402_spend_record_failed', { message: err?.message }));
	}
	if (settled.transaction) {
		void persistCall(settled.transaction, {
			...feedEntry,
			args,
			result: rpcResp?.result ?? rpcResp,
			payer: verified.payer || buyer.publicKey.toBase58(),
			payTo: accept.payTo,
			asset: accept.asset,
			explorer: `https://solscan.io/tx/${settled.transaction}`,
		}).catch((err) => {
			log.warn('call_persist_failed_outer', { tx: settled.transaction, message: err?.message });
		});
	}

	const total_ms = tSettled - t0;
	emit('result', {
		ok: true,
		tool, args,
		result: rpcResp?.result ?? rpcResp,
		payment: {
			network: accept.network,
			payer: verified.payer || buyer.publicKey.toBase58(),
			payTo: accept.payTo,
			asset: accept.asset,
			amount: accept.amount,
			tx: settled.transaction || null,
			explorer: settled.transaction ? `https://solscan.io/tx/${settled.transaction}` : null,
		},
		durations: {
			build_ms: tBuilt - t0,
			verify_ms: tVerified - tBuilt,
			dispatch_ms: tDispatched - tVerified,
			settle_ms: tSettled - tDispatched,
			total_ms,
		},
	});
}

// Build the client-facing envelope for a failed payment flow. Carries the
// upstream status/code through (so a facilitator 5xx surfaces as 502, an
// invalid/under-paid payment as 402, an MCP tool error as 502) and adds an
// honest charging note: a flow that never reached on-chain settlement moved no
// funds, while a post-settlement mismatch is ambiguous and must not promise the
// wallet was untouched.
function payErrorEnvelope(err) {
	const code = err?.code || (err?.mcpError ? 'mcp_dispatch_error' : 'flow_failed');
	let error_description;
	if (code === 'facilitator_unreachable' || code === 'facilitator_error' || code === 'settle_failed') {
		error_description = 'Payment could not be completed and no funds were transferred from the agent wallet. Please try again.';
	} else if (code === 'facilitator_bad_response' || code === 'settle_uncertain') {
		error_description = 'Payment status could not be confirmed. Check the payment activity before retrying to avoid paying twice.';
	} else if (code === 'no_solana_accept' || code === 'missing_fee_payer' || code === 'endpoint_unreachable' || code === 'invalid_challenge' || code === 'blocked_url') {
		error_description = 'No payment was attempted, so no funds were transferred from the agent wallet.';
	} else if (code === 'invalid_payment' || code === 'payment_required' || code === 'builder_code_tampered') {
		error_description = 'The payment was rejected before settlement; no funds were transferred.';
	} else if (code === 'rpc_unavailable') {
		error_description = 'The Solana RPC is temporarily unavailable, so the payment could not be built. No funds were transferred; retry shortly.';
	}
	const envelope = {
		ok: false,
		error: err?.message || 'flow_failed',
		code,
		mcpError: err?.mcpError || null,
	};
	if (error_description) envelope.error_description = error_description;
	return envelope;
}

// Map a flow error to its HTTP status. X402Error carries an explicit `status`
// (402 rejected payment, 502 facilitator/upstream); MCP dispatch errors are
// 502; everything else is an unexpected 500.
function payErrorStatus(err) {
	if (Number.isInteger(err?.status)) return err.status;
	if (err?.mcpError) return 502;
	return 500;
}

// Response headers for a flow error: an RPC outage advertises Retry-After so
// callers and CDNs back off instead of hammering a dead chain.
function payErrorHeaders(err) {
	return isRpcUnavailable(err) ? { 'retry-after': String(RPC_RETRY_AFTER_SECONDS) } : {};
}

// Buy one of the in-house SHOWCASE_ENDPOINTS from the shared platform wallet and
// stream the payment lifecycle. This is what /agent-exchange runs: the two 3D
// avatars are a view over a real x402 purchase of /api/x402/crypto-intel, so the
// flow here is the same probe → sign → settle path an external agent would take
// against the same public route. Unauthenticated by design (a viewer has no
// wallet), bounded by the per-IP and global rate limits already applied on the
// POST path plus the platform wallet's own balance.
async function handleShowcasePay(req, res, input, ip) {
	const endpoint = String(input.endpoint || '');
	if (!SHOWCASE_ENDPOINTS.has(endpoint)) {
		log.warn('showcase_endpoint_rejected', { endpoint: endpoint.slice(0, 120), ip });
		return json(res, 400, {
			error: 'invalid_endpoint',
			error_description: 'that endpoint is not payable from the showcase wallet',
			allowed: [...SHOWCASE_ENDPOINTS],
		});
	}

	let buyer;
	try {
		buyer = loadAgentKeypair();
	} catch {
		return json(res, 503, {
			error: 'config_missing',
			error_description: 'payment processing not available',
		});
	}

	const url = resolveResourceUrl(req, endpoint);
	const body = input.body && typeof input.body === 'object' ? input.body : {};
	const wantsStream =
		(req.headers.accept || '').includes('text/event-stream') || input.stream === true;

	// No spendGuard: the platform wallet has no per-agent daily policy to charge
	// against. The rate limiters upstream are the ceiling for this path.
	const flowArgs = {
		url,
		method: 'POST',
		body,
		buyer,
		spendGuard: null,
		serviceLabel: typeof input.service_label === 'string' ? input.service_label : null,
	};

	if (wantsStream) {
		sseInit(res);
		const emit = (ev, data) => sseSend(res, ev, data);
		try {
			await runExternalFlow({ ...flowArgs, emit });
		} catch (err) {
			emit('error', payErrorEnvelope(err));
		} finally {
			res.end();
		}
		return;
	}

	let final = null;
	const emit = (ev, data) => {
		if (ev === 'result') final = data;
	};
	try {
		await runExternalFlow({ ...flowArgs, emit });
	} catch (err) {
		return json(res, payErrorStatus(err), payErrorEnvelope(err), payErrorHeaders(err));
	}
	return json(res, 200, final);
}

// Pay an arbitrary external x402 endpoint from the owner's agent wallet. This is
// the money core behind the wallet hub Pay tab. Owner-authenticated + ownership-
// gated; the agent key is decrypted server-side via recoverSolanaAgentKeypair
// (audit-logged) and never leaves the server. Two modes:
//   { preview: true } — probe requirements only (no funds moved, no key signs).
//   default           — full pay; SSE-streams progress when the client asks.
async function handleExternalPay(req, res, input, ip) {
	const auth = await requireAuth(req);
	if (!auth) return json(res, 401, { error: 'authentication_required' });
	const agentId = input.agentId ? String(input.agentId) : '';
	if (!agentId) {
		// An external pay with no agent context would have no wallet to pay from —
		// never silently reach for the shared platform wallet here.
		log.warn('external_pay_missing_agent', { ip });
		return json(res, 400, {
			error: 'agent_required',
			error_description: 'paying a service requires an agent context',
		});
	}

	const loaded = await loadAgentKeypairForUser(agentId, auth.userId);
	if (!loaded) return json(res, 403, { error: 'agent_not_found_or_no_solana_wallet' });

	const method =
		typeof input.method === 'string' && /^(GET|POST|PUT|PATCH|DELETE)$/i.test(input.method)
			? input.method.toUpperCase()
			: 'GET';
	const body = input.body != null ? input.body : undefined;

	// Preview: surface the live price + what's being bought before the owner
	// confirms. Moves no funds.
	if (input.preview === true) {
		try {
			const probe = await probeExternalRequirements({ url: input.url, method, body });
			if (probe.free) {
				return json(res, 200, { ok: true, requires_payment: false, status: probe.status });
			}
			if (probe.unsupported) {
				return json(res, 200, {
					ok: true,
					requires_payment: true,
					payable: false,
					code: 'no_solana_accept',
					networks: probe.networks,
				});
			}
			const accept = probe.accept;
			const resource = resourceSummary(probe, input.url);
			return json(res, 200, {
				ok: true,
				requires_payment: true,
				payable: !!accept.extra?.feePayer,
				...(accept.extra?.feePayer ? {} : { code: 'missing_fee_payer' }),
				network: accept.network,
				amount: accept.amount,
				asset: accept.asset,
				payTo: accept.payTo,
				price_usdc: Number(accept.amount) / 1e6,
				resource,
				method,
			});
		} catch (err) {
			return json(res, payErrorStatus(err), payErrorEnvelope(err), payErrorHeaders(err));
		}
	}

	// CSRF on the settle path (funds move + the agent key signs). The preview branch
	// above returns before this point, so a live price probe never burns a token.
	// Bearer/API-key callers are exempt inside requireCsrf.
	if (!(await requireRealFundsAgreement(req, res, { userId: auth.userId, context: 'x402-pay' }))) return;
	if (!(await requireCsrf(req, res, auth.userId))) return;

	const spendGuard = { agentId, userId: auth.userId, meta: loaded.meta, network: 'mainnet' };
	const wantsStream =
		(req.headers.accept || '').includes('text/event-stream') || input.stream === true;

	if (wantsStream) {
		sseInit(res);
		const emit = (ev, data) => sseSend(res, ev, data);
		try {
			await runExternalFlow({
				url: input.url,
				method,
				body,
				emit,
				buyer: loaded.keypair,
				spendGuard,
				serviceLabel: typeof input.service_label === 'string' ? input.service_label : null,
			});
		} catch (err) {
			emit('error', payErrorEnvelope(err));
		} finally {
			res.end();
		}
		return;
	}

	let final = null;
	const emit = (ev, data) => {
		if (ev === 'result') final = data;
	};
	try {
		await runExternalFlow({
			url: input.url,
			method,
			body,
			emit,
			buyer: loaded.keypair,
			spendGuard,
			serviceLabel: typeof input.service_label === 'string' ? input.service_label : null,
		});
	} catch (err) {
		return json(res, payErrorStatus(err), payErrorEnvelope(err), payErrorHeaders(err));
	}
	return json(res, 200, final);
}

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

	if (req.method === 'GET') {
		const u = new URL(req.url, 'http://x');
		if (u.searchParams.get('balance') === '1') {
			try {
				const b = await getAgentBalance();
				return json(res, 200, { configured: true, ...b });
			} catch (err) {
				// Wallet config problems are surfaced as a 200 with a flag so
				// the demo UI can render "wallet not configured" instead of a
				// red console error. Other failures still bubble as 500.
				if (err.code === 'wallet_misconfigured' || err.code === 'wallet_unconfigured') {
					return json(res, 200, { configured: false, code: err.code, error: err.message, address: null, sol: 0, usdc: 0 });
				}
				// A balance read failure here is a Solana RPC fault, and web3.js
				// embeds the keyed RPC URL in its error text, so the raw message
				// must never reach the client. respondError sanitizes the 5xx to a
				// support ref (and still passes a 4xx client-fault message through).
				return respondError(res, err.status || 500, err.code || 'balance_unavailable', err);
			}
		}
		if (u.searchParams.get('feed') === '1') {
			const limit = Math.max(1, Math.min(50, Number(u.searchParams.get('limit') || 25)));
			const items = await readFeed(limit);
			return json(res, 200, { items });
		}
		const txParam = u.searchParams.get('call');
		if (txParam) {
			// The lookup key is a Solana transaction signature. Shape-check it before
			// it becomes a Redis key: an unbounded caller-controlled suffix turns a
			// public GET into arbitrary key reads against the Upstash request budget
			// this feed already had to be rewritten to protect (see readFeed above).
			if (!TX_SIGNATURE_RE.test(txParam)) {
				return json(res, 400, { error: 'invalid_call', error_description: 'call must be a base58 transaction signature' });
			}
			const record = await readCall(txParam);
			if (!record) return json(res, 404, { error: 'call_not_found' });
			return json(res, 200, record);
		}
		if (u.searchParams.get('agents') === '1') {
			const auth = await requireAuth(req);
			if (!auth) return json(res, 401, { error: 'authentication_required' });
			const agents = await getAgentsForUser(auth.userId);
			return json(res, 200, { agents });
		}
		return json(res, 404, { error: 'not_found' });
	}
	if (req.method !== 'POST') return json(res, 405, { error: 'method_not_allowed' });

	const ip = clientIp(req);
	const ipRl = await limits.x402PayIp(ip);
	if (!ipRl.success) {
		return rateLimited(res, ipRl);
	}
	const globalRl = await limits.x402PayGlobal();
	if (!globalRl.success) {
		// Distinct code from the per-IP limit so the demo UI can tell a global
		// budget exhaustion apart from a single caller's burst. Headers are the
		// same standard shape as rateLimited().
		const retryAfter = Math.max(1, setRateLimitHeaders(res, globalRl));
		res.setHeader('retry-after', String(retryAfter));
		return json(res, 429, { error: 'rate_limited_global', retry_after: retryAfter });
	}

	const input = await readJson(req, 50_000);

	// External x402 endpoint pay (wallet hub Pay tab): a target `url` means an
	// arbitrary bazaar service paid from the agent's OWN wallet — never the shared
	// platform wallet. Owner-authenticated, per-agent spend policy enforced.
	if (typeof input.url === 'string' && input.url) {
		return handleExternalPay(req, res, input, ip);
	}

	// Showcase pay: an in-house /api/x402/* route bought from the platform wallet
	// for a public demo page. Allowlisted server-side (SHOWCASE_ENDPOINTS).
	if (typeof input.endpoint === 'string' && input.endpoint) {
		return handleShowcasePay(req, res, input, ip);
	}

	const tool = String(input.tool || '');
	const args = input.args && typeof input.args === 'object' ? input.args : {};
	if (!ALLOWED_TOOLS.has(tool)) {
		return json(res, 400, { error: 'invalid_tool', allowed: [...ALLOWED_TOOLS] });
	}

	// Resolve payer. An agent context (agentId) ALWAYS pays from that agent's own
	// wallet; the shared showcase wallet is the explicit, logged fallback for
	// platform/demo calls with no agent context (see resolvePayerRouting).
	const routing = resolvePayerRouting(input);
	let buyer;
	let spendGuard = null;
	if (routing.mode === 'agent') {
		const auth = await requireAuth(req);
		if (!auth) return json(res, 401, { error: 'authentication_required' });
		if (!(await requireRealFundsAgreement(req, res, { userId: auth.userId, context: 'x402-pay' }))) return;
		const loaded = await loadAgentKeypairForUser(routing.agentId, auth.userId);
		if (!loaded) return json(res, 403, { error: 'agent_not_found_or_no_solana_wallet' });
		// CSRF: this tool call pays from the agent's own wallet. Bearer callers exempt.
		if (!(await requireCsrf(req, res, auth.userId))) return;
		buyer = loaded.keypair;
		// Per-agent spend policy applies to x402 just like trade/snipe/withdraw.
		spendGuard = { agentId: routing.agentId, userId: auth.userId, meta: loaded.meta, network: 'mainnet' };
	} else {
		// No agent context — fall back to the shared platform wallet, but log it so
		// a regression that drops agentId off an agent call is visible, not silent.
		log.warn('platform_wallet_fallback', { tool, reason: 'no_agent_context', ip });
		try {
			buyer = loadAgentKeypair();
		} catch (err) {
			return json(res, 503, { error: 'config_missing', error_description: 'payment processing not available' });
		}
	}

	const wantsStream =
		(req.headers.accept || '').includes('text/event-stream') ||
		input.stream === true;
	const resourceUrl = resolveResourceUrl(req, '/api/mcp');

	if (wantsStream) {
		sseInit(res);
		const emit = (ev, data) => sseSend(res, ev, data);
		try {
			await runFlow({ tool, args, emit, buyer, resourceUrl, spendGuard });
		} catch (err) {
			emit('error', payErrorEnvelope(err));
		} finally {
			res.end();
		}
		return;
	}

	// Non-streaming JSON path: collect the result event, surface any throw with
	// its real status + honest charging guidance.
	let final = null;
	const emit = (ev, data) => {
		if (ev === 'result') final = data;
	};
	try {
		await runFlow({ tool, args, emit, buyer, resourceUrl, spendGuard });
	} catch (err) {
		return json(res, payErrorStatus(err), payErrorEnvelope(err), payErrorHeaders(err));
	}
	return json(res, 200, final);
});