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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// @three-ws/x402-server — the SELLER half of x402.
//
// Framework-agnostic merchant middleware + primitives that issue a 402 Payment
// Required challenge, verify the buyer's X-PAYMENT header against a facilitator,
// run the work, settle on-chain, and emit the X-PAYMENT-RESPONSE receipt — the
// exact verify → dispatch → settle order the three.ws rails enforce in
// production. This is NOT the buyer side: it never signs or pays. Pair it with
// the buyer-side @three-ws/x402-fetch in a test.
//
// Every wire shape here is grounded in the real platform source:
// - challenge envelope + accept entries → api/_lib/x402-spec.js (build402Body /
// paymentRequirements)
// - facilitator /verify + /settle bodies → api/_lib/x402-spec.js
// (callFacilitator: { x402Version, paymentPayload, paymentRequirements })
// - fee split (clamp 10%, carved out of price, never marks up the buyer) →
// api/_lib/marketplace-platform-fee.js
//
// See README.md for the full reference.
import { createHttp, ThreeWsError } from './http.js';
export { ThreeWsError, PaymentRequiredError, DEFAULT_BASE_URL } from './http.js';
// v2 wire format (api/_lib/x402-spec.js X402_VERSION).
export const X402_VERSION = 2;
// CAIP-2 network IDs, mirrored from x402-spec.js. Solana mainnet uses the
// truncated genesis-block hash; EVM uses eip155:<chainId>.
export const NETWORK_SOLANA_MAINNET = 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp';
export const NETWORK_BASE_MAINNET = 'eip155:8453';
export const NETWORK_BASE_SEPOLIA = 'eip155:84532';
// The facilitator that settles Solana + Base by default. PayAI's public
// facilitator is the platform default in api/_lib/env.js
// (X402_FACILITATOR_URL_SOLANA / _BASE both fall back to it). Override per-route
// with the `facilitator` option.
export const DEFAULT_FACILITATOR_URL = 'https://facilitator.payai.network';
// Hard ceiling on the platform fee — a guard so a fat-fingered config can never
// charge an absurd fee (api/_lib/marketplace-platform-fee.js MAX_FEE_BPS).
export const MAX_FEE_BPS = 1000; // 10%
// Canonical USDC addresses per lane (api/_lib/env.js defaults). `asset: 'usdc'`
// resolves to these; pin explicit addresses with `asset: { solana, base }`.
const CANONICAL_USDC = {
solana: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
base: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
// Circle's Base Sepolia testnet USDC — a distinct mint from Base mainnet.
// Advertising the mainnet address on a testnet accept makes the facilitator
// verify against a token the buyer never signed for.
'base-sepolia': '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
};
// $THREE — the three.ws platform token, the second main x402 settlement asset
// alongside USDC. Solana-only (it's an SPL mint). `asset: 'three'` resolves to
// it; `acceptThree: true` advertises it next to USDC on the Solana lane, exactly
// as api/_lib/x402-spec.js does server-side. 6 decimals.
const CANONICAL_THREE = {
solana: 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump',
};
const THREE_DECIMALS = 6;
// Maps the ergonomic lane name → CAIP-2 network id. Solana leads when both are
// present, matching paymentRequirements()'s Solana-first ordering.
const LANE_NETWORK = {
solana: NETWORK_SOLANA_MAINNET,
base: NETWORK_BASE_MAINNET,
'base-sepolia': NETWORK_BASE_SEPOLIA,
};
const LANES = ['solana', 'base', 'base-sepolia'];
/**
* Create an x402-server client bound to a facilitator URL, fetch, and optional
* auth headers. Most callers can use the zero-config defaults
* (`buildChallenge`/`verifyPayment`/`settlePayment`/`paid`); use this to reuse a
* facilitator override or a custom fetch across many routes.
*
* @param {object} [options]
* @param {string} [options.facilitator] facilitator base URL for /verify + /settle.
* @param {string} [options.baseUrl] alias for `facilitator` (resolved the same way).
* @param {typeof fetch} [options.fetch] fetch implementation (default global fetch).
* @param {string} [options.apiKey] bearer token attached to facilitator calls.
* @param {Record<string,string>} [options.headers] default headers on every call.
*/
export function createX402Server(options = {}) {
const facilitatorUrl = options.facilitator || options.baseUrl || DEFAULT_FACILITATOR_URL;
const request = createHttp({ ...options, baseUrl: facilitatorUrl });
/**
* Build the v2 402 envelope: `{ x402Version, error, resource, accepts,
* extensions }` — the same object you base64 into the PAYMENT-REQUIRED header.
* Mirrors api/_lib/x402-spec.js build402Body + paymentRequirements.
*/
function buildChallenge(opts = {}) {
return buildChallengeEnvelope(opts);
}
/**
* Decode the base64 X-PAYMENT header and verify it against `requirements` (the
* accepts[] you advertised) via the facilitator's /verify. Returns
* `{ ok: true, payer, accept, raw }` on success, or `{ ok: false, code,
* reason, body }` (a fresh 402 body) on a rejected/under-paid payment.
* **Run the work only when `ok`.** Mirrors x402-spec.js verifyPayment.
*/
async function verifyPayment(args = {}, expected) {
// Two call shapes: verifyPayment({ paymentHeader, requirements }) and the
// README's positional verifyPayment(xPaymentHeader, expected).
let header;
let requirements;
let signal;
if (typeof args === 'string') {
header = args;
requirements = expectedToRequirements(expected);
} else {
header = args.paymentHeader ?? args.xPaymentHeader;
requirements = expectedToRequirements(args.requirements ?? expected);
signal = args.signal;
}
return runVerify({ request, paymentHeader: header, requirements, signal });
}
/**
* Settle a verified payment on-chain via the facilitator's /settle and return
* the receipt `{ network, payer, transaction, raw }` — the object you base64
* into the X-PAYMENT-RESPONSE header. Run this AFTER the work succeeds, never
* before. Mirrors x402-spec.js settlePayment.
*/
async function settlePayment(args = {}) {
const verified = args.verified || args;
return runSettle({ request, verified, signal: args?.signal });
}
/**
* Wrap a request handler so it requires payment. Returns a `(req, res, next?)`
* function usable as Express/Connect middleware, a Vercel/Node http handler,
* or — via the `adapter` option — a fetch-style `(request) => Response`
* handler. Unpaid requests get a 402 challenge; paid ones verify → run the
* handler → settle.
*/
function paid(opts, handler) {
return buildPaidHandler({ buildChallenge, verifyPayment, settlePayment }, opts, handler);
}
return { buildChallenge, verifyPayment, settlePayment, paid };
}
// A lazily-created shared client backs the zero-config default functions, so
// `import { paid }` works with no setup (mirrors forge's defaultClient()).
let shared = null;
function defaultClient() {
return (shared ||= createX402Server());
}
/** Build the v2 402 challenge envelope. */
export function buildChallenge(opts) {
return defaultClient().buildChallenge(opts);
}
/** Verify an X-PAYMENT header against the offered requirements. */
export function verifyPayment(args, expected) {
return defaultClient().verifyPayment(args, expected);
}
/** Settle a verified payment and return its receipt. */
export function settlePayment(args) {
return defaultClient().settlePayment(args);
}
/** Wrap a handler so it demands payment (Express / Vercel / fetch-style). */
export function paid(opts, handler) {
return defaultClient().paid(opts, handler);
}
// ── Challenge construction ───────────────────────────────────────────────
// Build one v2 accept entry per advertised lane, in the platform's Solana-first
// order. Each entry carries scheme/network/amount/asset/payTo/maxTimeoutSeconds
// + the per-lane `extra` block (Solana needs a feePayer; Base pins the EIP-712
// domain name "USD Coin"). Grounded in paymentRequirements().
function buildAccepts({ price, asset, payTo, network, feePayer, maxTimeoutSeconds, resourceUrl, acceptThree, threeAmount }) {
if (price === undefined || price === null || String(price) === '') {
throw new ThreeWsError('buildChallenge() needs a `price` in atomic units.', { code: 'invalid_input' });
}
const amount = String(price);
if (!/^\d+$/.test(amount)) {
throw new ThreeWsError(`price must be a whole atomic amount string, got "${amount}".`, { code: 'invalid_input' });
}
if (!payTo || typeof payTo !== 'object') {
throw new ThreeWsError('buildChallenge() needs `payTo` with at least one lane (solana / base).', { code: 'invalid_input' });
}
// Which lanes to advertise: explicit `network`, else every lane present in
// payTo (Solana leads).
const requested = network ? (Array.isArray(network) ? network : [network]) : LANES.filter((l) => payTo[l]);
const lanes = [...new Set(requested)];
// Validate the optional flat $THREE amount once, up front. Omit → reuse the
// USDC `price`.
let threeAmt = null;
if (acceptThree) {
threeAmt = threeAmount === undefined || threeAmount === null || String(threeAmount) === '' ? amount : String(threeAmount);
if (!/^\d+$/.test(threeAmt)) {
throw new ThreeWsError(`threeAmount must be a whole atomic amount string, got "${threeAmt}".`, { code: 'invalid_input' });
}
}
const out = [];
for (const lane of lanes) {
if (!LANES.includes(lane)) {
throw new ThreeWsError(`Unknown network lane "${lane}". Expected one of: ${LANES.join(', ')}.`, { code: 'invalid_input' });
}
const to = payTo[lane];
if (!to) {
throw new ThreeWsError(`network includes "${lane}" but payTo.${lane} is not set.`, { code: 'invalid_input' });
}
out.push(buildAccept({ lane, amount, asset, payTo: to, feePayer, maxTimeoutSeconds, resourceUrl }));
// $THREE rides immediately after the USDC Solana accept — the platform's
// two main assets, Solana-first — so a wallet's token chooser surfaces both
// while a first-accept client still settles USDC. Mirrors paymentRequirements().
if (lane === 'solana' && acceptThree) {
out.push(buildAccept({ lane: 'solana', amount: threeAmt, asset: 'three', payTo: to, feePayer, maxTimeoutSeconds, resourceUrl }));
}
}
if (!out.length) {
throw new ThreeWsError('No payable lanes — set payTo for solana and/or base.', { code: 'invalid_input' });
}
return out;
}
/**
* Resolve the Solana sponsor account: explicit `feePayer` option, else the
* X402_FEE_PAYER_SOLANA env var. Deployments keep the sponsor in the
* environment (the platform rails do), so a route that omits the option still
* advertises a payable Solana accept instead of throwing missing_fee_payer.
*/
export function resolveFeePayer(feePayer) {
if (typeof feePayer === 'string' && feePayer.trim()) return feePayer.trim();
const env = typeof process !== 'undefined' && process.env ? process.env.X402_FEE_PAYER_SOLANA : null;
return typeof env === 'string' && env.trim() ? env.trim() : null;
}
function buildAccept({ lane, amount, asset, payTo, feePayer: explicitFeePayer, maxTimeoutSeconds, resourceUrl }) {
const feePayer = resolveFeePayer(explicitFeePayer);
const network = LANE_NETWORK[lane];
const assetAddress = resolveAsset(asset, lane);
const accept = {
scheme: 'exact',
network,
amount,
asset: assetAddress,
payTo,
maxTimeoutSeconds: Number.isInteger(maxTimeoutSeconds) && maxTimeoutSeconds > 0 ? maxTimeoutSeconds : 60,
...(resourceUrl ? { resource: resourceUrl } : {}),
};
if (lane === 'solana') {
// PayAI's Solana facilitator rejects with `missing_fee_payer` unless the
// accept advertises the sponsor account that co-signs the SPL transfer.
if (!feePayer) {
throw new ThreeWsError('Solana accepts need a `feePayer` (the facilitator sponsor account) — set X402_FEE_PAYER_SOLANA.', { code: 'missing_fee_payer' });
}
// `extra` names the settlement token — $THREE when this is a THREE accept,
// USDC otherwise — so a wallet labels the choice correctly.
const isThree = asset === 'three' || assetAddress === CANONICAL_THREE.solana;
accept.extra = isThree
? { name: 'THREE', decimals: THREE_DECIMALS, feePayer }
: { name: 'USDC', decimals: 6, feePayer };
} else {
// `name` MUST match the on-chain EIP-712 domain. Base USDC's domain name
// is "USD Coin" (not "USDC") — using "USDC" recomputes the wrong domain
// hash and the facilitator rejects the signature.
accept.extra = { name: 'USD Coin', version: '2', decimals: 6 };
}
return accept;
}
function resolveAsset(asset, lane) {
if (asset === 'three') {
// $THREE is an SPL mint — Solana only. Advertising it on an EVM lane is a
// misconfiguration, not a silent USDC fallback.
if (lane !== 'solana') {
throw new ThreeWsError(`$THREE settlement is Solana-only — lane "${lane}" can't advertise THREE.`, { code: 'invalid_input' });
}
return CANONICAL_THREE.solana;
}
if (!asset || asset === 'usdc') return CANONICAL_USDC[lane];
if (typeof asset === 'string') return asset;
if (typeof asset === 'object') {
// A pin can target the exact lane, or `base` can stand in for `base-sepolia`.
const pinned = asset[lane] ?? (lane === 'base-sepolia' ? asset.base : undefined);
return pinned || CANONICAL_USDC[lane];
}
return CANONICAL_USDC[lane];
}
// Assemble the full v2 envelope. Accepts either a pre-built `accepts[]` (raw
// path from the README) or the ergonomic { price, asset, payTo, ... } shape.
function buildChallengeEnvelope({
price,
asset,
payTo,
network,
feeBps,
feeTo,
feePayer,
acceptThree,
threeAmount,
accepts,
maxTimeoutSeconds,
resourceUrl,
description,
mimeType = 'application/json',
serviceName,
tags,
iconUrl,
error = 'X-PAYMENT header is required',
extensions: extraExtensions,
} = {}) {
const list = Array.isArray(accepts) && accepts.length
? accepts
: buildAccepts({ price, asset, payTo, network, feePayer, maxTimeoutSeconds, resourceUrl, acceptThree, threeAmount });
const resource = { url: resourceUrl ?? null, mimeType };
if (typeof description === 'string' && description.length) resource.description = description;
if (typeof serviceName === 'string' && serviceName.length) resource.serviceName = serviceName.slice(0, 32);
if (Array.isArray(tags) && tags.length) resource.tags = tags.slice(0, 5);
if (typeof iconUrl === 'string' && iconUrl.length) resource.iconUrl = iconUrl;
const extensions = { ...(extraExtensions || {}) };
const envelope = {
x402Version: X402_VERSION,
error,
resource,
accepts: list,
extensions,
};
// Surface the fee plan when configured — split out of the price, never marked
// up onto the buyer. `null` means no fee applies (see feeSplit).
if (feeBps != null && feeTo) {
envelope.fee = feeSplit(list[0]?.amount ?? price, feeBps, feeTo);
}
return envelope;
}
// ── Fee split ────────────────────────────────────────────────────────────
/**
* Split a platform fee OUT of the listed price: `fee = floor(price × bps /
* 10_000)`, `net = price − fee`. The buyer's total is never marked up — they
* pay `price`, the creator nets `net`, the treasury receives `fee`. Returns
* `null` when no fee applies (rate 0, no recipient, or a sub-atomic fee) so the
* creator receives the whole price. `bps` is clamped to `[0, MAX_FEE_BPS]`.
* Mirrors api/_lib/marketplace-platform-fee.js (resolveMarketplaceFee).
*
* @param {bigint|number|string} priceAtomics
* @param {number} bps
* @param {string} recipient
* @returns {{ price: string, net: string, fee: string, bps: number, recipient: string } | null}
*/
export function feeSplit(priceAtomics, bps, recipient) {
const clamped = clampBps(bps);
if (clamped <= 0 || !recipient) return null;
let price;
try {
price = BigInt(String(priceAtomics ?? '0').split('.')[0]);
} catch {
return null;
}
if (price <= 0n) return null;
const fee = (price * BigInt(clamped)) / 10_000n;
if (fee <= 0n) return null; // sub-atomic fee — charge nothing, creator keeps all
return {
price: price.toString(),
net: (price - fee).toString(),
fee: fee.toString(),
bps: clamped,
recipient,
};
}
function clampBps(bps) {
const n = Number(bps);
if (!Number.isFinite(n) || n < 0) return 0;
return Math.min(Math.floor(n), MAX_FEE_BPS);
}
// ── Verify / settle ───────────────────────────────────────────────────────
function decodePaymentHeader(header) {
if (!header) {
throw new ThreeWsError('X-PAYMENT header is required.', { code: 'payment_required', status: 402 });
}
let json;
try {
json = base64Decode(String(header));
} catch (err) {
throw new ThreeWsError(`X-PAYMENT base64 decode failed: ${err?.message || err}`, { code: 'invalid_payment', status: 400 });
}
let payload;
try {
payload = JSON.parse(json);
} catch (err) {
throw new ThreeWsError(`X-PAYMENT JSON parse failed: ${err?.message || err}`, { code: 'invalid_payment', status: 400 });
}
if (!payload || typeof payload !== 'object') {
throw new ThreeWsError('X-PAYMENT must decode to a JSON object.', { code: 'invalid_payment', status: 400 });
}
return payload;
}
// Match the decoded payload to one of the offered requirements by network,
// falling back to the first entry. Mirrors x402-spec.js selectRequirement's
// non-EVM path (the facilitator does the deep EIP-712/Permit2 matching).
function selectRequirement(paymentPayload, requirements) {
const network = paymentPayload?.network || paymentPayload?.accepted?.network;
if (network) {
const found = requirements.find((r) => r.network === network);
if (!found) {
throw new ThreeWsError(`payment network "${network}" is not offered by this resource.`, { code: 'unsupported_network', status: 400 });
}
return found;
}
return requirements[0];
}
async function runVerify({ request, paymentHeader, requirements, signal }) {
const all = Array.isArray(requirements) ? requirements : [requirements];
const payable = all.filter(Boolean);
if (!payable.length) {
throw new ThreeWsError('verifyPayment() needs the `requirements` (your accepts[]) to match against.', { code: 'invalid_input' });
}
let paymentPayload;
let requirement;
try {
paymentPayload = decodePaymentHeader(paymentHeader);
requirement = selectRequirement(paymentPayload, payable);
} catch (err) {
// Surface a rejected payment as a structured result (not a throw) plus a
// fresh 402 body — `paid()` re-challenges the buyer.
return rejected(err, payable);
}
let result;
try {
result = await request('/verify', {
method: 'POST',
body: { x402Version: X402_VERSION, paymentPayload, paymentRequirements: requirement },
signal,
});
} catch (err) {
// A facilitator outage is NOT a rejected payment — no funds moved, safe to
// retry. Bubble it as a typed error so paid() maps it to 502.
throw mapFacilitatorError(err, '/verify');
}
if (!result || result.isValid !== true) {
const reason = result?.invalidReason || 'payment rejected by facilitator';
return rejected(new ThreeWsError(`payment rejected: ${reason}`, { code: 'invalid_payment', status: 402 }), payable);
}
return {
ok: true,
payer: result.payer || null,
network: requirement.network,
amount: requirement.amount,
accept: requirement,
paymentPayload,
requirement,
raw: result,
};
}
async function runSettle({ request, verified, signal }) {
const paymentPayload = verified?.paymentPayload;
const requirement = verified?.requirement || verified?.accept;
if (!requirement || !paymentPayload) {
throw new ThreeWsError('settlePayment() requires the object returned by verifyPayment().', { code: 'invalid_input' });
}
let result;
try {
result = await request('/settle', {
method: 'POST',
body: { x402Version: X402_VERSION, paymentPayload, paymentRequirements: requirement },
signal,
});
} catch (err) {
// Verified + work ran, but settlement status is unknown — the caller must
// check on-chain before retrying to avoid double-paying.
throw mapFacilitatorError(err, '/settle', 'settle_uncertain');
}
if (!result || result.success !== true) {
throw new ThreeWsError(`settle failed: ${result?.errorReason || 'unknown reason'}`, { code: 'settle_failed', status: 502, body: result });
}
// Cross-check the facilitator's claimed network/payer against what we verified
// (defense-in-depth, mirrors x402-spec.js settlePayment).
if (result.network && requirement.network && result.network !== requirement.network) {
throw new ThreeWsError(`facilitator /settle network mismatch: requested ${requirement.network}, got ${result.network}.`, { code: 'facilitator_bad_response', status: 502 });
}
if (verified.payer && result.payer && String(result.payer).toLowerCase() !== String(verified.payer).toLowerCase()) {
throw new ThreeWsError(`facilitator /settle payer mismatch: verified ${verified.payer}, settled ${result.payer}.`, { code: 'facilitator_bad_response', status: 502 });
}
return {
network: result.network || requirement.network,
payer: result.payer || verified.payer || null,
transaction: result.transaction || null,
raw: result,
};
}
// A rejected (under-paid / malformed / wrong-network) payment → a structured
// result carrying a fresh 402 body so paid() can re-challenge.
function rejected(err, requirements) {
const code = err?.code || 'payment_required';
const status = err?.status === 400 ? 402 : err?.status || 402;
return {
ok: false,
code,
status,
reason: err?.message || 'payment required',
body: {
x402Version: X402_VERSION,
error: err?.message || 'payment required',
accepts: requirements,
},
};
}
// A facilitator that is unreachable or 5xx is a transient infra fault, never a
// rejected payment. `/verify` failures mean no funds moved; `/settle` failures
// are uncertain (verified + work ran).
function mapFacilitatorError(err, path, fallbackCode = 'facilitator_unreachable') {
if (err instanceof ThreeWsError && err.code !== 'network_error' && err.status && err.status < 500) {
return err;
}
const code = err?.code === 'network_error' ? fallbackCode : (err?.code || fallbackCode);
return new ThreeWsError(`facilitator ${path} failed: ${err?.message || err}`, {
code: fallbackCode === 'settle_uncertain' ? 'settle_uncertain' : code,
status: 502,
body: err?.body ?? null,
});
}
// ── paid() middleware factory ──────────────────────────────────────────────
// A tiny adapter layer lets one factory serve Express/Connect/Vercel (`req,res`)
// AND fetch-style (`Request → Response`) runtimes. The default adapter reads
// node-style req/res; pass `{ adapter: fetchAdapter }` for the fetch lane.
function buildPaidHandler({ buildChallenge, verifyPayment, settlePayment }, opts = {}, handler) {
if (typeof handler !== 'function') {
throw new ThreeWsError('paid(options, handler) needs a handler function.', { code: 'invalid_input' });
}
const {
price,
asset = 'usdc',
payTo,
network,
feeBps = 0,
feeTo,
feePayer,
facilitator,
maxTimeoutSeconds,
description,
serviceName,
tags,
iconUrl,
onSettled,
// Response ordering. Default (false) is DELIVER-THEN-SETTLE: run the work,
// settle, then flush the response with the X-PAYMENT-RESPONSE receipt
// header attached — the buyer never receives the good before the payment
// settles. Set `streaming: true` for handlers that must write their own
// body (binary download, SSE, res.pipe): settlement runs FIRST and the
// receipt header is emitted up-front, so a self-flushing handler is paid
// by construction. Mirrors api/_lib/x402-paid-endpoint.js.
streaming = false,
adapter = nodeAdapter,
} = opts;
// Validate the fee config up front: a fee needs both a rate and a recipient,
// or it ships inert (rate 0 → no fee, no surprise billing).
if (feeBps > 0 && !feeTo) {
throw new ThreeWsError('feeBps > 0 requires feeTo (the fee recipient) — no recipient, no fee.', { code: 'invalid_input' });
}
// One route-scoped server when a custom facilitator is set (reused for both
// verify and settle); else the shared default client.
const scoped = facilitator ? createX402Server({ facilitator }) : null;
const verify = scoped ? scoped.verifyPayment : verifyPayment;
const settle = scoped ? scoped.settlePayment : settlePayment;
async function runSettle(verified) {
const receipt = await settle({ verified });
if (typeof onSettled === 'function') {
try { onSettled(receipt); } catch { /* a webhook/log error must not unsettle a paid call */ }
}
return receipt;
}
return async function paidHandler(...args) {
const ctx = adapter.read(...args);
const challengeBody = buildChallenge({
price, asset, payTo, network, feePayer, maxTimeoutSeconds,
resourceUrl: ctx.url, description, serviceName, tags, iconUrl, feeBps, feeTo,
});
const accepts = challengeBody.accepts;
const header = ctx.header('x-payment');
if (!header) {
return adapter.challenge(ctx, challengeBody, args);
}
// 1 — verify. No work runs unless the payment is valid.
const verified = await verify({ paymentHeader: header, requirements: accepts });
if (!verified.ok) {
return adapter.challenge(ctx, verified.body || challengeBody, args, verified.status || 402);
}
const payment = {
payer: verified.payer,
network: verified.network,
amount: verified.amount,
accept: verified.accept,
};
// Streaming (settle-then-stream): settle up-front, emit the receipt header,
// then let the handler own the response body. Requires an adapter that can
// stream (node); other adapters fall back to deliver-then-settle.
if (streaming && typeof adapter.stream === 'function') {
const receipt = await runSettle(verified);
return adapter.stream(ctx, handler, payment, receipt, args);
}
// 2 — dispatch the work. The adapter buffers any response the handler
// writes so nothing reaches the buyer before settlement. A throw here
// SKIPS settlement (no funds move on a failed call) and surfaces a 500.
let dispatched;
try {
dispatched = await adapter.dispatch(ctx, handler, payment, args);
} catch (err) {
return adapter.fail(ctx, err, args);
}
if (dispatched && dispatched.__handled) return dispatched.value;
// 3 — settle, AFTER the work succeeded. Settlement is the last step, and
// the buffered response is flushed with the receipt header in respond().
const receipt = await runSettle(verified);
return adapter.respond(ctx, dispatched, receipt, args);
};
}
// Node / Express / Vercel adapter: `(req, res)`.
//
// The buyer must never receive the good before settlement, and the 200 must
// carry the base64 X-PAYMENT-RESPONSE receipt. A handler that writes its own
// response (`res.json`/`res.send`/`res.end`) would flush both problems away, so
// dispatch() BUFFERS every write; respond() then settles, injects the receipt
// header, and flushes for real. Handlers may also just RETURN a value — the
// wrapper serialises it. Streaming handlers opt out via `streaming: true`.
const nodeAdapter = {
read(req, res) {
return {
req,
res,
url: absoluteUrl(req),
header: (name) => headerOf(req, name),
};
},
challenge(ctx, body, _args, status = 402) {
const { res } = ctx;
res.statusCode = status;
res.setHeader?.('content-type', 'application/json; charset=utf-8');
res.setHeader?.('cache-control', 'no-store');
// v2: the same envelope ships base64 in the PAYMENT-REQUIRED header so a
// Bazaar validator reads discovery off the header during its probe.
res.setHeader?.('PAYMENT-REQUIRED', base64Encode(JSON.stringify(body)));
res.end?.(JSON.stringify(body));
return undefined;
},
// Run the (req, res, payment) handler with a buffered response so no bytes
// reach the buyer until settlement. Captures the handler's return value too,
// for handlers that return a value instead of writing.
async dispatch(ctx, handler, payment) {
ctx._buffer = bufferNodeResponse(ctx.res);
const value = await handler(ctx.req, ctx.res, payment);
return { __handled: false, value };
},
respond(ctx, dispatched, receipt) {
const { res } = ctx;
const buffer = ctx._buffer;
const receiptHeader = base64Encode(JSON.stringify(receipt));
// Write-style handler (Express res.json/send/end): flush the buffered
// response with the receipt header injected ahead of the real end().
if (buffer && buffer.ended) {
buffer.flush({ 'X-PAYMENT-RESPONSE': receiptHeader });
return receipt;
}
// Return-value handler: the handler returned a value without writing.
// Serialise it as JSON with the receipt header. Restore the real methods
// first so our end() below actually flushes.
if (buffer) buffer.restore();
const value = dispatched?.value;
const body = value === undefined ? { ok: true } : value;
if (!res.statusCode || res.statusCode === 200) res.statusCode = 200;
try { res.setHeader?.('content-type', 'application/json; charset=utf-8'); } catch { /* headers sent */ }
try { res.setHeader?.('X-PAYMENT-RESPONSE', receiptHeader); } catch { /* headers sent */ }
res.end?.(typeof body === 'string' ? body : JSON.stringify(body));
return receipt;
},
// settle-then-stream: settlement already ran; attach the receipt header
// up-front, then hand the raw response to the (self-flushing) handler.
async stream(ctx, handler, payment, receipt) {
const { res } = ctx;
try { res.setHeader?.('X-PAYMENT-RESPONSE', base64Encode(JSON.stringify(receipt))); } catch { /* headers sent */ }
await handler(ctx.req, ctx.res, payment);
return receipt;
},
// The work threw AFTER a valid payment but BEFORE settlement — no funds
// moved. Discard any buffered partial output and return a clean 500 so the
// buyer can retry (their payment authorization is still spendable).
fail(ctx, err) {
const { res } = ctx;
const buffer = ctx._buffer;
if (buffer) buffer.restore();
if (res && !res.writableEnded) {
res.statusCode = err?.status && err.status >= 400 && err.status < 600 ? err.status : 500;
try { res.setHeader?.('content-type', 'application/json; charset=utf-8'); } catch { /* headers sent */ }
res.end?.(JSON.stringify({ error: err?.code || 'handler_error', message: err?.message || 'the paid work failed; payment was not settled' }));
}
return undefined;
},
};
// Wrap a Node ServerResponse so writes are captured instead of flushed. Returns
// a controller: `ended` reflects whether the handler called end(); `flush(extra)`
// restores the real methods, sets `extra` headers, and emits the buffered body;
// `restore()` puts the real methods back without flushing.
function bufferNodeResponse(res) {
const orig = { write: res.write, end: res.end, writeHead: res.writeHead };
const chunks = [];
const state = { ended: false, pendingCb: null };
res.write = function bufferedWrite(chunk, enc, cb) {
if (chunk) chunks.push(toBuffer(chunk, typeof enc === 'string' ? enc : undefined));
const done = typeof enc === 'function' ? enc : cb;
if (typeof done === 'function') done();
return true;
};
res.end = function bufferedEnd(chunk, enc, cb) {
if (chunk && typeof chunk !== 'function') chunks.push(toBuffer(chunk, typeof enc === 'string' ? enc : undefined));
state.ended = true;
state.pendingCb = typeof chunk === 'function' ? chunk : typeof enc === 'function' ? enc : typeof cb === 'function' ? cb : null;
return res;
};
// Capture an explicit status (and any header map) from writeHead without
// sending it; headers flush together at real end().
res.writeHead = function bufferedWriteHead(status, ...rest) {
if (typeof status === 'number') res.statusCode = status;
const headerMap = rest.find((r) => r && typeof r === 'object' && !Array.isArray(r));
if (headerMap && typeof res.setHeader === 'function') {
for (const [k, v] of Object.entries(headerMap)) { try { res.setHeader(k, v); } catch { /* ignore */ } }
}
return res;
};
function restore() {
res.write = orig.write;
res.end = orig.end;
res.writeHead = orig.writeHead;
}
return {
get ended() { return state.ended; },
restore,
flush(extraHeaders) {
restore();
if (extraHeaders && typeof res.setHeader === 'function') {
for (const [k, v] of Object.entries(extraHeaders)) { try { res.setHeader(k, v); } catch { /* headers sent */ } }
}
const body = chunks.length ? Buffer.concat(chunks) : undefined;
if (typeof orig.end === 'function') orig.end.call(res, body);
if (state.pendingCb) { try { state.pendingCb(); } catch { /* callback error is not ours to own */ } }
},
};
}
function toBuffer(chunk, enc) {
if (Buffer.isBuffer(chunk)) return chunk;
if (chunk instanceof Uint8Array) return Buffer.from(chunk);
return Buffer.from(String(chunk), enc || 'utf8');
}
// Fetch-style adapter: `(request) => Response`. The handler receives
// `(request, payment)` and returns a `Response` (or a plain object → JSON).
export const fetchAdapter = {
read(request) {
return {
request,
url: request?.url || null,
header: (name) => request?.headers?.get?.(name) ?? null,
};
},
challenge(_ctx, body, _args, status = 402) {
return jsonResponse(body, status, {
'cache-control': 'no-store',
'PAYMENT-REQUIRED': base64Encode(JSON.stringify(body)),
});
},
async dispatch(ctx, handler, payment) {
const value = await handler(ctx.request, payment);
// The fetch handler returns its result; we settle, then attach the receipt
// header to the Response in respond().
return { __handled: false, value };
},
respond(_ctx, dispatched, receipt) {
const value = dispatched?.value;
const headers = { 'X-PAYMENT-RESPONSE': base64Encode(JSON.stringify(receipt)) };
if (value && typeof value === 'object' && typeof value.headers?.set === 'function') {
// It's a Response — clone and add the receipt header.
const res = new Response(value.body, value);
res.headers.set('X-PAYMENT-RESPONSE', headers['X-PAYMENT-RESPONSE']);
return res;
}
return jsonResponse(value ?? { ok: true }, 200, headers);
},
// The work threw after a valid payment but before settlement — no funds
// moved. Return a clean 500 so the buyer can retry.
fail(_ctx, err) {
const status = err?.status && err.status >= 400 && err.status < 600 ? err.status : 500;
return jsonResponse({ error: err?.code || 'handler_error', message: err?.message || 'the paid work failed; payment was not settled' }, status);
},
};
// ── small helpers ──────────────────────────────────────────────────────────
function headerOf(req, name) {
if (!req) return null;
const h = req.headers;
if (!h) return null;
if (typeof h.get === 'function') return h.get(name) ?? null;
return h[name] ?? h[name.toLowerCase()] ?? null;
}
function absoluteUrl(req) {
if (!req) return null;
if (typeof req.url === 'string' && /^https?:\/\//.test(req.url)) return req.url;
const host = headerOf(req, 'host') || 'localhost';
const proto = headerOf(req, 'x-forwarded-proto') || 'https';
const path = req.url || '/';
return `${proto}://${host}${path}`;
}
function jsonResponse(body, status, headers) {
return new Response(JSON.stringify(body), {
status,
headers: { 'content-type': 'application/json; charset=utf-8', ...headers },
});
}
function base64Encode(str) {
if (typeof Buffer !== 'undefined') return Buffer.from(str, 'utf8').toString('base64');
// Browser/Workers fallback.
return btoa(unescape(encodeURIComponent(str)));
}
function base64Decode(str) {
if (typeof Buffer !== 'undefined') return Buffer.from(str, 'base64').toString('utf8');
return decodeURIComponent(escape(atob(str)));
}
// Normalize the `expected` argument (an accepts[] array, a challenge envelope,
// a { requirements } wrapper, or a single accept) into a flat requirements[].
function expectedToRequirements(expected) {
if (!expected) return [];
if (Array.isArray(expected)) return expected;
if (Array.isArray(expected.accepts)) return expected.accepts;
if (Array.isArray(expected.requirements)) return expected.requirements;
return [expected];
}