@three-ws/x402-payment-modal 1.1.0

package/examples/server-express/server.js

@@ -0,0 +1,89 @@
+// Runnable Express server for @three-ws/x402-payment-modal.
+//
+// What it does:
+//   1. Mounts the Solana checkout router at /api/x402-checkout. The browser
+//      modal posts here to build and settle Solana USDC transfers. (EVM
+//      payments sign in-browser and never hit this server.)
+//   2. Serves a trivial static page from ./public so you can click through the
+//      flow in a real browser.
+//   3. Exposes ONE demo paid endpoint, GET /api/paid/hello, that returns a
+//      correct x402 v2 challenge so you can see the 402 → pay loop end to end.
+//
+// Run:
+//   npm install
+//   SOLANA_RPC_URL="https://your-rpc" npm start
+//   open http://localhost:3000
+
+import express from 'express';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { x402CheckoutRouter } from '@three-ws/x402-payment-modal/server/express';
+import { solanaAccept } from '@three-ws/x402-payment-modal/server';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PORT = process.env.PORT || 3000;
+
+// A public Solana mainnet RPC works for a quick try, but it is rate-limited.
+// Use a dedicated RPC (Helius, Triton, QuickNode, …) for anything real.
+const SOLANA_RPC_URL =
+  process.env.SOLANA_RPC_URL || 'https://api.mainnet-beta.solana.com';
+
+const app = express();
+
+// Required by the checkout router — it reads JSON request bodies.
+app.use(express.json());
+
+// The checkout endpoint the browser modal talks to for Solana payments.
+app.use('/api/x402-checkout', x402CheckoutRouter({ rpcUrl: SOLANA_RPC_URL }));
+
+// ── Demo paid endpoint ─────────────────────────────────────────────────────
+//
+// A real x402 resource answers with HTTP 402 + a challenge until it receives a
+// valid X-PAYMENT header, then serves the content. Here we only implement the
+// challenge half so you can watch the modal react to a 402.
+//
+// IMPORTANT: verifying and settling the X-PAYMENT payload against an x402
+// facilitator is OUT OF SCOPE for this demo. In production you would verify the
+// payment proof (and idempotency) before returning 200. See the docs:
+// https://github.com/three-ws/x402-payment-modal/tree/main/docs
+//
+// Synthetic placeholders below — replace payTo / feePayer with YOUR addresses.
+const DEMO_PAY_TO = 'So11111111111111111111111111111111111111112'; // replace me
+const DEMO_FEE_PAYER = 'So11111111111111111111111111111111111111112'; // replace me
+
+app.get('/api/paid/hello', (req, res) => {
+  const hasPayment = Boolean(req.get('X-PAYMENT'));
+
+  if (!hasPayment) {
+    // No payment yet → answer with the x402 v2 challenge. We offer TWO Solana
+    // tokens — USDC and THREE — so the modal shows a token picker and the buyer
+    // chooses which to pay in. `solanaAccept` builds each spec-shaped entry.
+    const common = { payTo: DEMO_PAY_TO, feePayer: DEMO_FEE_PAYER, maxTimeoutSeconds: 60 };
+    return res.status(402).json({
+      x402Version: 2,
+      error: 'Payment required',
+      resource: {
+        url: `${req.protocol}://${req.get('host')}/api/paid/hello`,
+        description: 'A friendly hello — pay in USDC or THREE.',
+        mimeType: 'application/json',
+      },
+      accepts: [
+        solanaAccept({ token: 'usdc', uiAmount: 0.01, ...common }),  // $0.01 in USDC
+        solanaAccept({ token: 'three', uiAmount: 1000, ...common }), // or 1,000 THREE
+      ],
+    });
+  }
+
+  // A real implementation verifies the X-PAYMENT proof here before responding.
+  return res.json({ message: 'Hello — thanks for paying on Solana!' });
+});
+
+// Static demo page (examples/server-express/public/index.html).
+app.use(express.static(join(__dirname, 'public')));
+
+app.listen(PORT, () => {
+  console.log(`x402 checkout example running at http://localhost:${PORT}`);
+  console.log(`  checkout router  → /api/x402-checkout`);
+  console.log(`  demo paid route  → /api/paid/hello`);
+  console.log(`  Solana RPC       → ${SOLANA_RPC_URL}`);
+});

package/package.json

@@ -0,0 +1,113 @@
+{
+  "name": "@three-ws/x402-payment-modal",
+  "version": "1.1.0",
+  "description": "Drop-in x402 payment modal for any paid HTTP endpoint. One ES module, zero runtime dependencies — handles wallet connect (Phantom/Solana + EVM via EIP-3009), the 402 → sign → settle flow, SIWX re-entry, client-side spending caps, and a receipt. Vanilla JS, no bundler required.",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./types/index.d.ts",
+  "browser": "./dist/x402.min.js",
+  "unpkg": "./dist/x402.min.js",
+  "jsdelivr": "./dist/x402.min.js",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./min": {
+      "types": "./types/index.d.ts",
+      "default": "./dist/x402.min.js"
+    },
+    "./server": {
+      "types": "./types/server.d.ts",
+      "import": "./server/checkout.js",
+      "default": "./server/checkout.js"
+    },
+    "./server/express": {
+      "import": "./server/express.js",
+      "default": "./server/express.js"
+    },
+    "./server/vercel": {
+      "import": "./server/vercel.js",
+      "default": "./server/vercel.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "dist",
+    "types",
+    "server",
+    "examples",
+    "docs",
+    "README.md",
+    "TUTORIAL.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "test": "node --test \"test/*.test.js\"",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "x402",
+    "payments",
+    "micropayments",
+    "paywall",
+    "pay-per-call",
+    "usdc",
+    "stablecoin",
+    "solana",
+    "phantom",
+    "evm",
+    "base",
+    "metamask",
+    "eip-3009",
+    "siwx",
+    "wallet",
+    "checkout",
+    "modal",
+    "agentic",
+    "web3",
+    "402",
+    "three-ws"
+  ],
+  "author": "three.ws <support@three.ws> (https://three.ws)",
+  "license": "Apache-2.0",
+  "homepage": "https://three.ws",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nirholas/three.ws.git",
+    "directory": "x402-payment-modal"
+  },
+  "bugs": {
+    "url": "https://github.com/nirholas/three.ws/issues"
+  },
+  "peerDependencies": {
+    "@solana/web3.js": "^1.95.0",
+    "@solana/spl-token": "^0.4.0"
+  },
+  "peerDependenciesMeta": {
+    "@solana/web3.js": {
+      "optional": true
+    },
+    "@solana/spl-token": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "esbuild": "^0.21.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": [
+    "./src/index.js",
+    "./dist/x402.min.js"
+  ]
+}

package/server/README.md

@@ -0,0 +1,68 @@
+# Server — Solana checkout helpers
+
+The modal's **EVM** path signs EIP-3009 typed-data in the browser and never calls
+your server. The **Solana** path needs a small endpoint because Phantom signs
+serialized transactions but doesn't build instructions: this module builds the
+SPL `transferChecked` the buyer signs, then wraps the signed transaction into the
+base64 `X-PAYMENT` envelope the x402 facilitator expects.
+
+> If you only accept Base/EVM USDC, you don't need any of this.
+
+## Install peer deps
+
+```bash
+npm install @solana/web3.js @solana/spl-token
+```
+
+## Mount it
+
+**Express**
+
+```js
+import express from 'express';
+import { x402CheckoutRouter } from '@three-ws/x402-payment-modal/server/express';
+
+const app = express();
+app.use(express.json());
+app.use('/api/x402-checkout', x402CheckoutRouter({ rpcUrl: process.env.SOLANA_RPC_URL }));
+```
+
+**Vercel / Next.js** — `api/x402-checkout.js`
+
+```js
+export { default } from '@three-ws/x402-payment-modal/server/vercel';
+// or, with options:
+// import { createVercelCheckoutHandler } from '@three-ws/x402-payment-modal/server/vercel';
+// export default createVercelCheckoutHandler({ rpcUrl: process.env.SOLANA_RPC_URL });
+```
+
+**Anything else** — use the core router:
+
+```js
+import { handleCheckout } from '@three-ws/x402-payment-modal/server';
+
+const { status, body } = await handleCheckout({
+  action: url.searchParams.get('action'), // 'prepare' | 'encode'
+  body: await readJson(req),
+  options: { rpcUrl: process.env.SOLANA_RPC_URL },
+});
+```
+
+## Exports
+
+| Export | Description |
+| --- | --- |
+| `prepareSolanaCheckout({ accept, buyer, rpcUrl?, devnetRpcUrl? })` | Build the partially-signed v0 transaction the buyer signs. |
+| `encodeX402Payment({ accept, signedTxBase64, resourceUrl, builderCode? })` | Wrap the signed tx into the base64 `X-PAYMENT` envelope. |
+| `handleCheckout({ action, body, options? })` | Route `prepare`/`encode`; returns `{ status, body }`. |
+| `CheckoutError` | `Error` subclass with `.status` and `.code`. |
+| `isSolanaNetwork(network)` | CAIP-2 / `solana` alias check. |
+| `X402_VERSION`, `NETWORK_SOLANA_MAINNET`, `NETWORK_SOLANA_DEVNET` | Constants. |
+
+Adapters: `./express` → `x402CheckoutRouter(options)`, `./vercel` →
+`createVercelCheckoutHandler(options)` (default export is a ready handler). Both
+set permissive CORS (`origin: '*'`) by default and handle the `OPTIONS`
+preflight; pass `{ origin }` to restrict it.
+
+See [../docs/server-setup.md](../docs/server-setup.md) for the request/response
+shapes and environment variables.

package/server/checkout.js

@@ -0,0 +1,392 @@
+// @three-ws/x402-payment-modal/server — Solana checkout helpers.
+//
+// The modal's EVM path signs EIP-3009 typed-data entirely in the browser and
+// never calls your server. The Solana path is different: Phantom only *signs*
+// serialized transactions — it does not build instructions. So the modal needs a
+// tiny server endpoint that (a) builds the SPL transfer the buyer should sign,
+// and (b) wraps the signed transaction into the base64 `X-PAYMENT` envelope the
+// x402 facilitator expects.
+//
+// This module is framework-agnostic. `prepareSolanaCheckout` and
+// `encodeX402Payment` are pure functions; `handleCheckout` routes the two
+// actions and returns `{ status, body }`. Thin adapters for Express and Vercel
+// live in ./express.js and ./vercel.js.
+//
+// Runtime deps: @solana/web3.js and @solana/spl-token (declared as optional peer
+// dependencies — install them in the app that mounts this handler). Nothing here
+// imports anything three.ws-specific.
+
+import {
+	Connection,
+	PublicKey,
+	TransactionMessage,
+	VersionedTransaction,
+	ComputeBudgetProgram,
+} from '@solana/web3.js';
+import {
+	TOKEN_PROGRAM_ID,
+	ASSOCIATED_TOKEN_PROGRAM_ID,
+	getAssociatedTokenAddressSync,
+	createAssociatedTokenAccountIdempotentInstruction,
+	createTransferCheckedInstruction,
+	getMint,
+} from '@solana/spl-token';
+
+export const X402_VERSION = 2;
+
+// CAIP-2 network identifiers for Solana (genesis-hash prefixes).
+export const NETWORK_SOLANA_MAINNET = 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp';
+export const NETWORK_SOLANA_DEVNET = 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1';
+
+const DEFAULT_MAINNET_RPC = 'https://api.mainnet-beta.solana.com';
+const DEFAULT_DEVNET_RPC = 'https://api.devnet.solana.com';
+
+// ─────────────────────────────────────────────── Well-known Solana tokens ────
+// The two settlement assets the modal treats as first-class on Solana. USDC is
+// the universal dollar-stable rail; THREE is the three.ws utility token, so any
+// endpoint can let holders pay in THREE alongside USDC. `solanaAccept()` builds
+// the x402 `accept` entry for either (or any other SPL mint) — the prepare path
+// already transfers any mint, so offering THREE needs no further wiring.
+export const USDC_MINT_SOLANA = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
+export const THREE_MINT = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
+
+export const WELL_KNOWN_SOLANA_TOKENS = Object.freeze({
+	usdc: { mint: USDC_MINT_SOLANA, symbol: 'USDC', name: 'USD Coin', decimals: 6 },
+	three: { mint: THREE_MINT, symbol: 'THREE', name: 'THREE', decimals: 6 },
+});
+
+/**
+ * Build one x402 Solana `accept` entry for a merchant's 402 challenge.
+ *
+ * Pass `token: 'usdc' | 'three'` for a well-known asset, or an explicit `mint`
+ * (+ optional `decimals`/`name`) for any other SPL token. Supply the price as
+ * either `amount` (atomic integer string) or `uiAmount` (human units, converted
+ * with the token's decimals). `feePayer` is the facilitator sponsor that pays
+ * the SOL network fee so buyers need only the token itself.
+ *
+ * @param {object} args
+ * @param {'usdc'|'three'} [args.token]   well-known token shortcut
+ * @param {string} [args.mint]            explicit SPL mint (base58); overrides token
+ * @param {string} args.payTo             recipient address (base58)
+ * @param {string} args.feePayer          facilitator sponsor address (base58)
+ * @param {string|number|bigint} [args.amount]    atomic integer amount
+ * @param {string|number} [args.uiAmount] human amount (e.g. 0.25) — converted via decimals
+ * @param {number} [args.decimals]        token decimals (default: well-known or 6)
+ * @param {string} [args.name]            display name for the modal (default: well-known symbol)
+ * @param {string} [args.network]         CAIP-2 network (default: Solana mainnet)
+ * @param {number} [args.maxTimeoutSeconds]
+ * @returns {SolanaAccept}
+ */
+export function solanaAccept({
+	token,
+	mint,
+	payTo,
+	feePayer,
+	amount,
+	uiAmount,
+	decimals,
+	name,
+	network = NETWORK_SOLANA_MAINNET,
+	maxTimeoutSeconds,
+} = {}) {
+	const known = token ? WELL_KNOWN_SOLANA_TOKENS[String(token).toLowerCase()] : null;
+	if (token && !known) {
+		throw new CheckoutError(400, 'invalid_request', `unknown token '${token}'. Use 'usdc', 'three', or pass an explicit mint.`);
+	}
+	const asset = mint || known?.mint;
+	if (!asset) {
+		throw new CheckoutError(400, 'invalid_request', "solanaAccept needs a token ('usdc'|'three') or an explicit mint");
+	}
+	assertPubkey(asset, 'mint');
+	assertPubkey(payTo, 'payTo');
+	assertPubkey(feePayer, 'feePayer');
+
+	const dec = Number.isFinite(decimals) ? decimals : (known?.decimals ?? 6);
+	let atomic;
+	if (amount != null) {
+		atomic = BigInt(amount).toString();
+	} else if (uiAmount != null) {
+		atomic = uiToAtomic(uiAmount, dec);
+	} else {
+		throw new CheckoutError(400, 'invalid_request', 'solanaAccept needs amount (atomic) or uiAmount (human)');
+	}
+
+	const accept = {
+		scheme: 'exact',
+		network,
+		amount: atomic,
+		asset,
+		payTo,
+		extra: {
+			name: name || known?.name || 'USDC',
+			decimals: dec,
+			feePayer,
+		},
+	};
+	if (maxTimeoutSeconds != null) accept.maxTimeoutSeconds = maxTimeoutSeconds;
+	return accept;
+}
+
+// Convert a human token amount (e.g. "0.25", 1.5) to an atomic integer string
+// without floating-point drift: split on the decimal point and pad/truncate.
+function uiToAtomic(uiAmount, decimals) {
+	const s = String(uiAmount).trim();
+	if (!/^\d+(\.\d+)?$/.test(s)) {
+		throw new CheckoutError(400, 'invalid_request', `uiAmount must be a non-negative number, got '${uiAmount}'`);
+	}
+	const [whole, frac = ''] = s.split('.');
+	const fracPadded = (frac + '0'.repeat(decimals)).slice(0, decimals);
+	const atomic = BigInt(whole) * 10n ** BigInt(decimals) + BigInt(fracPadded || '0');
+	return atomic.toString();
+}
+
+// Short-lived caches so repeated prepare calls don't re-issue identical RPC
+// round-trips. Mint decimals are effectively immutable; a Solana blockhash stays
+// valid for ~60-90s, so a few seconds of reuse cuts redundant traffic without
+// handing out a blockhash too stale for the buyer's signed tx to land.
+const MINT_DECIMALS_TTL_MS = 5 * 60 * 1000;
+const BLOCKHASH_TTL_MS = 8 * 1000;
+const mintDecimalsCache = new Map(); // `${rpc}:${mint}` -> { decimals, at }
+const blockhashCache = new Map(); // rpc -> { blockhash, at }
+
+/** Thrown for any client-correctable problem; carries an HTTP `status` + `code`. */
+export class CheckoutError extends Error {
+	constructor(status, code, message) {
+		super(message);
+		this.name = 'CheckoutError';
+		this.status = status;
+		this.code = code;
+	}
+}
+
+export function isSolanaNetwork(network) {
+	return (
+		network === NETWORK_SOLANA_MAINNET ||
+		network === NETWORK_SOLANA_DEVNET ||
+		network === 'solana'
+	);
+}
+
+function rpcFor(network, { rpcUrl, devnetRpcUrl } = {}) {
+	if (network === NETWORK_SOLANA_DEVNET) return devnetRpcUrl || DEFAULT_DEVNET_RPC;
+	return rpcUrl || DEFAULT_MAINNET_RPC;
+}
+
+const BASE58 = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+function assertPubkey(value, field) {
+	if (typeof value !== 'string' || !BASE58.test(value)) {
+		throw new CheckoutError(400, 'invalid_request', `${field} must be a base58 Solana address`);
+	}
+	return value;
+}
+
+// Validate the subset of the x402 `accept` entry the Solana path relies on.
+// `extra.feePayer` is required — it is the facilitator's sponsor account that
+// pays the SOL network fee so the buyer needs no SOL, only USDC.
+function validateAccept(accept) {
+	if (!accept || typeof accept !== 'object') {
+		throw new CheckoutError(400, 'invalid_request', 'accept object is required');
+	}
+	if (accept.scheme !== 'exact') {
+		throw new CheckoutError(400, 'invalid_request', `unsupported scheme: ${accept.scheme}`);
+	}
+	if (!isSolanaNetwork(accept.network)) {
+		throw new CheckoutError(
+			400,
+			'unsupported_network',
+			`prepare only builds Solana transactions; got network=${accept.network}. EVM clients sign EIP-712 typed data locally and don't need this endpoint.`,
+		);
+	}
+	if (typeof accept.amount !== 'string' || !/^\d+$/.test(accept.amount)) {
+		throw new CheckoutError(400, 'invalid_request', 'accept.amount must be an atomic integer string');
+	}
+	assertPubkey(accept.asset, 'accept.asset');
+	assertPubkey(accept.payTo, 'accept.payTo');
+	const feePayer = accept.extra?.feePayer;
+	assertPubkey(feePayer, 'accept.extra.feePayer');
+	return accept;
+}
+
+async function getMintDecimals(conn, rpc, mint) {
+	const key = `${rpc}:${mint.toBase58()}`;
+	const hit = mintDecimalsCache.get(key);
+	if (hit && Date.now() - hit.at < MINT_DECIMALS_TTL_MS) return hit.decimals;
+	const info = await getMint(conn, mint);
+	mintDecimalsCache.set(key, { decimals: info.decimals, at: Date.now() });
+	return info.decimals;
+}
+
+async function getRecentBlockhash(conn, rpc) {
+	const hit = blockhashCache.get(rpc);
+	if (hit && Date.now() - hit.at < BLOCKHASH_TTL_MS) return hit.blockhash;
+	const { blockhash } = await conn.getLatestBlockhash('confirmed');
+	blockhashCache.set(rpc, { blockhash, at: Date.now() });
+	return blockhash;
+}
+
+/**
+ * Build the partially-signed v0 SPL `transferChecked` the buyer's Phantom wallet
+ * should add its signature to. The fee payer is `accept.extra.feePayer` (the
+ * facilitator's sponsor), so the buyer pays only USDC.
+ *
+ * @param {object} args
+ * @param {object} args.accept   one x402 `accept` entry (scheme=exact, Solana)
+ * @param {string} args.buyer    buyer's base58 Solana address
+ * @param {string} [args.rpcUrl] mainnet RPC URL override
+ * @param {string} [args.devnetRpcUrl] devnet RPC URL override
+ * @returns {Promise<{ network: string, tx_base64: string, recent_blockhash: string }>}
+ */
+export async function prepareSolanaCheckout({ accept, buyer, rpcUrl, devnetRpcUrl }) {
+	validateAccept(accept);
+	assertPubkey(buyer, 'buyer');
+
+	const rpc = rpcFor(accept.network, { rpcUrl, devnetRpcUrl });
+	const conn = new Connection(rpc, 'confirmed');
+
+	const mint = new PublicKey(accept.asset);
+	const payTo = new PublicKey(accept.payTo);
+	const feePayer = new PublicKey(accept.extra.feePayer);
+	const buyerPubkey = new PublicKey(buyer);
+	const amount = BigInt(accept.amount);
+
+	const senderAta = getAssociatedTokenAddressSync(
+		mint, buyerPubkey, false, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
+	);
+	const receiverAta = getAssociatedTokenAddressSync(
+		mint, payTo, false, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
+	);
+	const mintDecimals = await getMintDecimals(conn, rpc, mint);
+
+	const ixs = [
+		ComputeBudgetProgram.setComputeUnitLimit({ units: 60_000 }),
+		ComputeBudgetProgram.setComputeUnitPrice({ microLamports: 1 }),
+	];
+	// Create the recipient's token account if it doesn't exist yet — idempotent,
+	// paid for by the fee payer so the buyer is never charged extra SOL.
+	const receiverInfo = await conn.getAccountInfo(receiverAta);
+	if (!receiverInfo) {
+		ixs.push(
+			createAssociatedTokenAccountIdempotentInstruction(
+				feePayer, receiverAta, payTo, mint, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
+			),
+		);
+	}
+	ixs.push(
+		createTransferCheckedInstruction(
+			senderAta, mint, receiverAta, buyerPubkey, amount, mintDecimals, [], TOKEN_PROGRAM_ID,
+		),
+	);
+
+	const blockhash = await getRecentBlockhash(conn, rpc);
+	const message = new TransactionMessage({
+		payerKey: feePayer,
+		recentBlockhash: blockhash,
+		instructions: ixs,
+	}).compileToV0Message();
+	const vtx = new VersionedTransaction(message);
+
+	return {
+		network: accept.network,
+		tx_base64: Buffer.from(vtx.serialize()).toString('base64'),
+		recent_blockhash: blockhash,
+	};
+}
+
+const BUILDER_CODE_PATTERN = /^[a-z0-9_]{1,32}$/;
+function sanitizeBuilderCode(builderCode) {
+	if (!builderCode || typeof builderCode !== 'object') return null;
+	const a = builderCode.a;
+	if (typeof a !== 'string' || !BUILDER_CODE_PATTERN.test(a)) return null;
+	const out = { a };
+	if (typeof builderCode.w === 'string' && BUILDER_CODE_PATTERN.test(builderCode.w)) out.w = builderCode.w;
+	if (Array.isArray(builderCode.s)) {
+		const s = builderCode.s.filter((x) => typeof x === 'string' && BUILDER_CODE_PATTERN.test(x)).slice(0, 32);
+		if (s.length) out.s = s;
+	}
+	return out;
+}
+
+/**
+ * Wrap a buyer-signed Solana transaction into the base64 `X-PAYMENT` envelope.
+ *
+ * @param {object} args
+ * @param {object} args.accept            the same accept entry used in prepare
+ * @param {string} args.signedTxBase64    base64 of the fully buyer-signed v0 tx
+ * @param {string} args.resourceUrl       absolute URL of the paid resource
+ * @param {object} [args.builderCode]     optional ERC-8021 builder-code echo
+ * @returns {{ x_payment: string }}
+ */
+export function encodeX402Payment({ accept, signedTxBase64, resourceUrl, builderCode }) {
+	validateAccept(accept);
+	if (typeof signedTxBase64 !== 'string' || signedTxBase64.length < 40) {
+		throw new CheckoutError(400, 'invalid_request', 'signedTxBase64 is required');
+	}
+	let url;
+	try {
+		url = new URL(resourceUrl).href;
+	} catch {
+		throw new CheckoutError(400, 'invalid_request', 'resourceUrl must be an absolute URL');
+	}
+
+	const payload = {
+		x402Version: X402_VERSION,
+		scheme: 'exact',
+		network: accept.network,
+		resource: { url, mimeType: 'application/json' },
+		accepted: accept,
+		payload: { transaction: signedTxBase64 },
+	};
+	const echo = sanitizeBuilderCode(builderCode);
+	if (echo) payload.extensions = { 'builder-code': echo };
+
+	return { x_payment: Buffer.from(JSON.stringify(payload), 'utf8').toString('base64') };
+}
+
+/**
+ * Route an action ('prepare' | 'encode') to its handler and return a plain
+ * `{ status, body }` pair the framework adapters serialize as JSON. Accepts the
+ * camelCase fields the helpers use *and* the snake_case fields the browser modal
+ * POSTs (`signed_tx_base64`, `resource_url`, `builder_code`).
+ *
+ * @param {object} args
+ * @param {'prepare'|'encode'} args.action
+ * @param {object} args.body   parsed JSON request body
+ * @param {object} [args.options] { rpcUrl, devnetRpcUrl }
+ * @returns {Promise<{ status: number, body: object }>}
+ */
+export async function handleCheckout({ action, body = {}, options = {} }) {
+	try {
+		if (action === 'prepare') {
+			const data = await prepareSolanaCheckout({
+				accept: body.accept,
+				buyer: body.buyer,
+				rpcUrl: options.rpcUrl,
+				devnetRpcUrl: options.devnetRpcUrl,
+			});
+			return { status: 200, body: data };
+		}
+		if (action === 'encode') {
+			const data = encodeX402Payment({
+				accept: body.accept,
+				signedTxBase64: body.signedTxBase64 ?? body.signed_tx_base64,
+				resourceUrl: body.resourceUrl ?? body.resource_url,
+				builderCode: body.builderCode ?? body.builder_code,
+			});
+			return { status: 200, body: data };
+		}
+		return {
+			status: 404,
+			body: { error: 'not_found', error_description: `unknown action: ${action ?? '(none)'}` },
+		};
+	} catch (err) {
+		if (err instanceof CheckoutError) {
+			return { status: err.status, body: { error: err.code, error_description: err.message } };
+		}
+		// Unexpected (RPC down, malformed tx). Surface a generic 502 — the caller
+		// shows "try again"; the real cause is in your server logs.
+		return {
+			status: 502,
+			body: { error: 'checkout_failed', error_description: 'Could not build the Solana payment. Try again.' },
+		};
+	}
+}