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
// Helper for building paid x402 endpoints with minimal boilerplate.
//
// A paid endpoint runs an 8-step dance: CORS → method-check → access-control
// hook (optional bypass) → SIWX short-circuit (when opted in) → 402 challenge
// (when no payment header) → verify → run the handler → settle → respond
// with the X-PAYMENT-RESPONSE header. We factor that into `paidEndpoint(spec)`
// so each new /api/x402/* file only has to declare its route metadata + a
// handler that returns JSON.
//
// Pricing: each endpoint gets its own `priceAtomics` (USDC has 6 decimals,
// so "1000" = $0.001). Networks default to Solana first then Base, which is
// the order the 402 challenge lists them in; pass `networks` only to narrow
// that set (e.g. `['solana']`) or to force a different order. The bazaar discovery
// extension is required — agentic.market's catalog rejects entries without
// it. See api/_lib/x402-spec.js for the v2 wire-format details.
//
// SIWX opt-in (Sign-In-With-X, CAIP-122). Add `siwx: { statement, ttlSeconds?,
// expirationSeconds? }` to opt the endpoint into wallet-signature re-access:
// - statement: human-readable purpose shown to the wallet on signing.
// - ttlSeconds: how long the payment grant lasts (null = permanent).
// - expirationSeconds: SIWX message validity window (default 300s).
// When set, the 402 body declares the `sign-in-with-x` extension, and an
// incoming `SIGN-IN-WITH-X` header skips the X-PAYMENT path for any wallet
// already in siwx_payments. Fresh settlements record a grant automatically.
//
// Per-asset payouts. Pass `payTo: { base?, solana?, bsc? }` to override the
// shared env.X402_PAY_TO_* receivers — used by /api/x402/asset-download so
// each creator can collect USDC to their own wallet without forking the
// helper. Missing keys fall back to env (so a single override doesn't
// disable the other networks).
import { cors, error, readBody, respondError, rateLimited, wrap } from './http.js';
import { env } from './env.js';
import { clientIp, limits } from './rate-limit.js';
import { logPaymentEvent } from './x402/audit-log.js';
import { recordPaymentMetric } from './axiom.js';
import { PAYMENT_EVENT_TOPIC as BSC_PAYMENT_EVENT_TOPIC } from './x402-bsc-direct.js';
import {
BUILDER_CODE,
NETWORK_BASE_MAINNET,
NETWORK_BSC_MAINNET,
NETWORK_SOLANA_MAINNET,
X402Error,
baseSettleable,
solanaSettleable,
encodePaymentResponseHeader,
permit2VariantOf,
resolveResourceUrl,
send402,
settlePayment,
verifyPayment,
} from './x402-spec.js';
import { declareBuilderCodeExtension } from './x402-builder-code.js';
import { sponsorKnownBelowFloor, refreshSponsorFloorState } from './x402/self-facilitator.js';
import { resolveSolanaFacilitator } from './x402/ring-config.js';
import {
buildUptoRequirement,
normaliseCharge,
settleUptoClaim,
settleUptoDeposit,
uptoEnabled,
} from './x402/upto.js';
import {
PAYMENT_IDENTIFIER,
checkCache,
enforceRequired,
extractIdFromHeader,
hashPaymentProof,
legacyPaymentProofHash,
hashRequestPayload,
paymentIdentifierExtension,
reserveSlot,
releaseSlot,
storeResponse,
writeCachedResponse,
writeConflict,
writeInflight,
} from './x402/payment-identifier-server.js';
import {
buildSolanaChargeChallenge,
chargeMatchesRequirement,
chargeToX402Payment,
installMppResponse,
parseSolanaChargeCredential,
pickSolanaExact,
} from './mpp-solana.js';
import { authenticateSiwx, declareSiwxExtensionFor, recordSiwxPayment } from './siwx-server.js';
import { verifyAuthHintsSiwx } from './x402/auth-hints.js';
import { declarePrepaidExtension, prepaidRequirement, servePrepaid } from './x402/prepaid-route.js';
import { normalizeAddress } from './siwx-storage.js';
import { normalizeBazaarEntry } from './x402/bazaar-helpers.js';
import { buildOffersExtension, buildReceiptExtension } from './x402/offer-receipt-server.js';
import { signReceipt } from './x402-offer-receipt.js';
import { recordReceipt } from './x402/receipt-storage.js';
import {
claimPaidRetry,
claimSpentPayment,
isPaymentSpent,
markDelivered,
markFailedAfterSettle,
paidFailureFields,
writeReplayed,
} from './x402/spent-payments.js';
import {
authenticateAuthHintsRequest,
declareAuthHintsExtension,
freeEvmAcceptForAuth,
} from './x402/auth-hints.js';
const NETWORK_ALIASES = {
base: NETWORK_BASE_MAINNET,
'base-mainnet': NETWORK_BASE_MAINNET,
bsc: NETWORK_BSC_MAINNET,
'bsc-mainnet': NETWORK_BSC_MAINNET,
solana: NETWORK_SOLANA_MAINNET,
'solana-mainnet': NETWORK_SOLANA_MAINNET,
};
function resolveNetwork(name) {
return NETWORK_ALIASES[name] || name;
}
// USDC is 6-decimal; the x402 requirement carries the price as an atomic string.
// Returns undefined for an absent/unparseable amount so the metric simply omits
// the field rather than reporting a misleading 0.
function atomicsToUsd(atomics) {
if (atomics == null) return undefined;
const n = Number(atomics);
return Number.isFinite(n) ? n / 1e6 : undefined;
}
// Largest request body the wrapper buffers to key the idempotency hash. Above
// the Cloud Run body-parser limit (8 MB) so every parsed body fits, with room
// for the raw-audio routes that read their own stream.
const PAID_BODY_HASH_LIMIT = 32 * 1024 * 1024;
// The request bytes a paid call is FOR, so the payment-identifier hash keys a
// cached response to the exact input. GET/HEAD carry no body. On Cloud Run the
// server's body parsers have already buffered the bytes (req.rawBody / req.body)
// and readBody returns them without touching the stream; anywhere the stream is
// still unread, the bytes are kept on req.rawBody so the handler's own
// readBody/readJson reads the same buffer instead of a drained stream.
async function paidRequestBody(req) {
const m = String(req.method || 'GET').toUpperCase();
if (m === 'GET' || m === 'HEAD') return null;
const buffered = Buffer.isBuffer(req.rawBody) || req.body !== undefined;
const buf = await readBody(req, PAID_BODY_HASH_LIMIT);
if (!buffered) req.rawBody = buf;
return buf;
}
// What the durable spent-payment row stores about a settlement: enough for a
// paid retry to answer with the original x-payment-response and rebuild the
// handler's `settled` / `requirement` context without a second settle, plus
// the request payload hash, so a retry can only re-run the request that was
// paid for.
function settlementRecord(settled, verified, paymentResponseHeader, payloadHash) {
return {
payload: payloadHash ?? null,
transaction: settled?.transaction ?? null,
network: settled?.network || verified?.requirement?.network || null,
payer: settled?.payer || verified?.payer || null,
asset: verified?.requirement?.asset ?? null,
amount: verified?.requirement?.amount ?? null,
status: settled?.status ?? null,
header: paymentResponseHeader ?? null,
};
}
function settledFromRecord(record) {
return {
success: true,
transaction: record?.transaction ?? null,
network: record?.network ?? null,
payer: record?.payer ?? null,
...(record?.status ? { status: record.status } : {}),
};
}
// A paid retry skips verify, so the requirement the buyer originally paid
// against is recovered from this request's accepts by network and asset.
function verifiedFromRecord(record, requirements) {
const requirement = requirements.find(
(r) => r.network === record?.network && (!record?.asset || r.asset === record.asset),
) || { network: record?.network ?? null, asset: record?.asset ?? null, amount: record?.amount ?? null };
return { requirement, payer: record?.payer ?? null, paymentPayload: null };
}
// Any failure once the buyer was charged answers with `paid: true`, whether a
// retry with the same payment is safe, and the settlement transaction, so a
// client never reads it as "pay again".
function writePaidFailure(res, { status, code, err, record, state }) {
if (record?.header) res.setHeader('x-payment-response', record.header);
return respondError(res, status, code, err, paidFailureFields({ settlement: record, ...state }));
}
function buildAccept(network, priceAtomics, resourceUrl, payToOverride, selfPayOnly = false) {
const common = {
scheme: 'exact',
amount: String(priceAtomics),
maxTimeoutSeconds: 60,
resource: resourceUrl,
};
if (network === NETWORK_BASE_MAINNET) {
return {
...common,
network: NETWORK_BASE_MAINNET,
payTo: payToOverride?.base || env.X402_PAY_TO_BASE,
asset: env.X402_ASSET_ADDRESS_BASE,
// EIP-712 domain name must match the on-chain USDC contract — Base
// USDC's domain is "USD Coin" (not "USDC"), or signatures fail.
extra: { name: 'USD Coin', version: '2', decimals: 6 },
};
}
if (network === NETWORK_SOLANA_MAINNET) {
return {
...common,
network: NETWORK_SOLANA_MAINNET,
payTo: payToOverride?.solana || env.X402_PAY_TO_SOLANA,
asset: env.X402_ASSET_MINT_SOLANA,
// PayAI requires this account as fee payer; without it /verify rejects.
// Omitted deliberately in self-pay mode: absence of feePayer is the
// wire signal that the buyer covers their own gas, which is what keeps
// the endpoint payable while the sponsor wallet is empty.
extra: {
name: 'USDC',
decimals: 6,
...(selfPayOnly ? {} : { feePayer: env.X402_FEE_PAYER_SOLANA }),
},
};
}
if (network === NETWORK_BSC_MAINNET) {
const contract = payToOverride?.bsc || env.X402_PAY_TO_BSC;
// Contract-mediated "direct" scheme — the client calls
// ThreeWSPayments.pay(bytes32) from their own wallet (see x402-bsc-direct.js).
return {
...common,
scheme: 'direct',
network: NETWORK_BSC_MAINNET,
payTo: contract,
asset: env.X402_ASSET_ADDRESS_BSC,
extra: {
name: 'Binance-Peg USD Coin',
decimals: 6,
contract,
method: 'pay(bytes32)',
eventTopic: BSC_PAYMENT_EVENT_TOPIC,
},
};
}
throw new X402Error('unsupported_network', `paidEndpoint: unsupported network ${network}`, 500);
}
// Exported for tests: the self-pay fallback below decides whether a paid
// endpoint stays payable while the sponsor wallet is empty, which is the
// difference between taking money and answering 503.
export function buildRequirements({ priceAtomics, networks, resourceUrl, payToOverride, acceptThree = true }) {
const out = [];
for (const name of networks) {
const net = resolveNetwork(name);
const baseTo = payToOverride?.base || env.X402_PAY_TO_BASE;
const solTo = payToOverride?.solana || env.X402_PAY_TO_SOLANA;
const bscTo = payToOverride?.bsc || env.X402_PAY_TO_BSC;
// Advertise a network only when EVERY field its accept needs is present.
// One half-configured chain must never take down the others: the endpoint
// offers whatever networks are fully wired and silently drops the rest,
// 402-failing only when NONE are payable. The asset is checked here too —
// without it the accept would be advertised and then rejected by the
// facilitator at settle, which is the same broken experience as a 500.
// Base also needs a WORKING facilitator to settle against — CDP creds or the
// X402_ADVERTISE_BASE opt-in. A bare facilitator URL is not enough: the prod
// host was decommissioned and 404s every /verify, so advertising Base would
// hand buyers an accept that always fails at settle (a 502, not a clean 402).
// Drop Base instead; the Solana accept still settles in-house.
if (
net === NETWORK_BASE_MAINNET &&
(!baseTo || !env.X402_ASSET_ADDRESS_BASE || !baseSettleable())
)
continue;
// Solana needs somewhere to send the money and a mint to send. Those are
// the only hard requirements: without them there is nothing to advertise.
if (
net === NETWORK_SOLANA_MAINNET &&
(!solTo || !env.X402_ASSET_MINT_SOLANA)
)
continue;
// Who pays the Solana fee is a SEPARATE question from whether we can be
// paid. Sponsoring the buyer's gas is a convenience we offer so a buyer
// holding only USDC needs no SOL; it is not a precondition for receiving.
// This used to drop Solana whenever the sponsor could not co-sign (no
// X402_FEE_PAYER_SECRET_BASE58 loaded, or the wallet under its SOL floor),
// which 503'd a paid endpoint whose entire job is RECEIVING crypto while
// the payTo wallet sat there perfectly able to receive. Advertise the
// accept without a feePayer instead: that is the self-pay contract, where
// the buyer signs as their own fee payer and the facilitator only
// broadcasts, spending none of our SOL. Sponsored mode resumes by itself
// the moment the wallet is topped up.
//
// Only when WE settle. An external facilitator (PayAI) pins the sponsor as
// fee payer and rejects a challenge without one at /verify, so dropping
// feePayer there would trade a retryable 503 for a hard verify failure.
const solanaSelfPayOnly =
net === NETWORK_SOLANA_MAINNET &&
resolveSolanaFacilitator().self &&
(!env.X402_FEE_PAYER_SOLANA || !solanaSettleable() || sponsorKnownBelowFloor());
if (net === NETWORK_BSC_MAINNET && (!bscTo || !env.X402_ASSET_ADDRESS_BSC)) continue;
const accept = buildAccept(net, priceAtomics, resourceUrl, payToOverride, solanaSelfPayOnly);
out.push(accept);
// $THREE alongside USDC on Solana (opt-in via X402_ACCEPT_THREE_SOLANA).
// Pushed right after the USDC Solana accept — and after the network guard
// above already confirmed solTo + fee payer + USDC mint — so holders can
// pay this endpoint in the platform token; the modal shows a token chooser.
// USDC stays first, so first-accept clients keep settling USDC.
// `acceptThree: false` opts a route out. The $THREE amount is a FIXED
// env value, so on a route whose USDC price varies per request (a print
// order priced from its own quote token, a knock priced by the
// recipient's door) it would let a $40 good settle for a flat token
// amount. A fixed-price route is unaffected, which is why the default
// stays on.
if (acceptThree && net === NETWORK_SOLANA_MAINNET && env.X402_ACCEPT_THREE_SOLANA) {
out.push({
scheme: 'exact',
network: NETWORK_SOLANA_MAINNET,
amount: String(env.X402_THREE_AMOUNT_SOLANA || priceAtomics),
maxTimeoutSeconds: 60,
resource: resourceUrl,
payTo: solTo,
asset: env.THREE_TOKEN_MINT,
extra: {
name: 'THREE',
decimals: env.THREE_TOKEN_DECIMALS,
...(solanaSelfPayOnly ? {} : { feePayer: env.X402_FEE_PAYER_SOLANA }),
},
});
}
// For EVM `exact` networks, advertise a Permit2 sibling so @x402/* SDK
// clients can pick the gasless Permit2-via-EIP-2612 path. The EIP-3009
// entry stays first so the browser modal (which only signs
// transferWithAuthorization) keeps selecting it. send402/build402Body
// auto-declares the eip2612GasSponsoring extension when this sibling
// is present — no per-endpoint opt-in needed.
const sibling = permit2VariantOf(accept);
if (sibling) out.push(sibling);
}
if (!out.length) {
// Distinguish a TEMPORARY settlement gap from a genuine misconfiguration.
// If Solana was requested and is otherwise fully configured (pay-to + mint +
// sponsor pubkey) but dropped ONLY because solanaSettleable() is false — the
// self-facilitator's co-signing secret isn't loaded yet — this is a transient,
// operator-fixable state, not "nothing is wired". Surface a retryable 503 with
// an actionable message instead of a 500 that reads as a permanent config
// error, and never after taking a payment. Self-heals when the secret is set.
const solanaConfigured =
networks.some((n) => resolveNetwork(n) === NETWORK_SOLANA_MAINNET) &&
(payToOverride?.solana || env.X402_PAY_TO_SOLANA) &&
env.X402_FEE_PAYER_SOLANA &&
env.X402_ASSET_MINT_SOLANA;
if (solanaConfigured && !solanaSettleable()) {
throw new X402Error(
'settlement_unavailable',
'paidEndpoint: Solana settlement is temporarily unavailable — the self-facilitator co-signing key (X402_FEE_PAYER_SECRET_BASE58) is not configured. Retry once it is set.',
503,
);
}
// Same transient class, different cause: fully wired but the sponsor
// wallet is under its SOL settle floor. Self-heals when treasury-topup
// (or the operator) refunds the wallet.
if (solanaConfigured && sponsorKnownBelowFloor()) {
throw new X402Error(
'settlement_unavailable',
'paidEndpoint: settlement is temporarily unavailable, the sponsor wallet is below its SOL settle floor. Retry after it is refunded.',
503,
);
}
throw new X402Error(
'no_payto_configured',
'paidEndpoint: no X402_PAY_TO_* configured for any requested network',
500,
);
}
return out;
}
// `spec.bazaar` is the v2 discoverable extension shape: { discoverable: true,
// info: { input, output }, schema }. See model-check.js for a worked example.
// `spec.handler({ req, res, requirement, payer })` is called only AFTER the
// payment verifies. It should return a JSON-serializable result; throwing an
// Error with .status + .code maps to a clean error response. Throwing an
// X402Error with status=402 re-emits the 402 challenge (e.g. wrong network).
//
// `spec.accessControl` (optional) — async (req, routeConfig) => result hook
// matching the v2 SDK onProtectedRequest contract. Built via
// installAccessControl() from api/_lib/x402/access-control.js. Returns:
// • { grantAccess: true, reason, callerId, headers? } → bypass payment,
// invoke the handler with `bypass = { reason, callerId, subscription?,
// oauth? }` instead of `requirement`/`payer`, and skip settlement.
// • { abort: true, status, reason, headers? } → reject the request with the
// given status (default 403) and message.
// • null / undefined → continue to the normal 402 flow.
//
// `spec.requiredScope` (optional) — OAuth scope the route declares for
// bypass-via-Bearer. Passed to the hook in routeConfig.requiredScope.
// The `upto` accept for a route: Solana USDC to the route's payee, amount = cap.
async function buildUptoOffer({ upto, resourceUrl, payTo }) {
const solTo = payTo?.solana || env.X402_PAY_TO_SOLANA;
if (!solTo || !env.X402_ASSET_MINT_SOLANA) return null;
const cap = BigInt(upto.capAtomics);
if (cap <= 0n) throw new Error('paidEndpoint: upto.capAtomics must be a positive integer');
const offer = await buildUptoRequirement({
capAtomics: cap,
network: NETWORK_SOLANA_MAINNET,
asset: env.X402_ASSET_MINT_SOLANA,
payTo: solTo,
resourceUrl,
});
return { ...offer, resource: resourceUrl };
}
export function paidEndpoint(spec) {
const {
route,
method = 'GET',
priceAtomics = env.X402_MAX_AMOUNT_REQUIRED,
// Solana-first platform default: the live 402 challenge lists Solana
// before Base so first-accept clients/modals settle on Solana unless a
// route explicitly overrides the network order.
networks = ['solana', 'base'],
description,
mimeType = 'application/json',
// Response shape. Default (false) is deliver-then-settle: the handler
// RETURNS a value and the wrapper settles, then serialises + flushes it.
// A handler on a default route that ends its own response is a bug — the
// good would ship before settlement — and is rejected loudly below.
// Set `streaming: true` for routes that must write their own body
// (binary download, res.pipe, SSE): the wrapper then settles BEFORE
// invoking the handler (settle-then-stream) and emits the
// x-payment-response header up-front, so a self-flushing handler is paid
// by construction. Streamed responses are never idempotency-cached.
streaming = false,
bazaar,
handler,
// ERC-8021 builder-code attribution. Optional per-route service codes
// — e.g. a multi-service route declares ["pose-studio", "openai-proxy"]
// so the on-chain CBOR suffix records every internal service that
// participated. The app code (`a`) is pulled from env so every route
// attributes to the same X402_BUILDER_CODE_APP. When env is unset, no
// builder-code extension is declared and echo verification is skipped.
services,
accessControl,
requiredScope = null,
// USE-15: payment-identifier idempotency. Defaults to optional so any
// caller can opt in. Set `{ required: true }` for routes where a
// duplicate call is materially expensive or observable (oracle
// submissions, fact-check writes, on-chain mints). `ttlSeconds`
// overrides the env default (X402_IDEMPOTENCY_TTL_SECONDS).
paymentIdentifier = {},
// Optional per-route payout overrides — { base?, solana?, bsc? }. When
// set, replaces env.X402_PAY_TO_* on a network-by-network basis.
// Missing keys fall back to env so a single override doesn't disable
// the other networks.
payTo,
// Advertise the $THREE accept alongside USDC on Solana (default true,
// still gated on env.X402_ACCEPT_THREE_SOLANA). Set false on a route
// whose USDC price varies per request: the $THREE amount comes from a
// FIXED env value, so a variable-price good would be purchasable at a
// flat token price no matter what its USDC quote said.
acceptThree = true,
// Optional SIWX (Sign-In-With-X, CAIP-122) opt-in. See file header.
siwx,
// 'exact' (default): every call is paid with its own x402 payment.
// 'prepaid': ALSO accept a debit from the caller's prepaid balance, proven
// by a SIGN-IN-WITH-X header with no X-PAYMENT. The balance is funded by one
// on-chain deposit and the sellers are paid in batches
// (api/_lib/x402/prepaid-ledger.js); a call that fails is never debited.
// A caller without a balance gets the normal 402 and can still pay per call.
mode = 'exact',
// MPP (Machine Payments Protocol) on Solana, additive to x402: when true
// the 402 also carries `WWW-Authenticate: Payment ... method="solana"
// intent="charge"`, an `Authorization: Payment` credential is redeemed
// through the same verify/settle path as an x402 `exact` payment, and a
// settled response gains `Payment-Receipt`. One price, one payee, one
// receipt. See api/_lib/mpp-solana.js and docs/mpp.md.
mpp = false,
// Optional post-settlement hook for per-job metering (Roadmap phase 4:
// inference settlement). Called with the settled payment context BEFORE
// the response is flushed; the value it returns is JSON-merged into the
// response body (object results only), so a paid route can attach a
// signed metered-job core + receipt that provably covers the exact bytes
// about to ship. Async; a throw is logged and the response ships
// un-metered rather than failing a settled payment.
metered,
// x402 v2 `upto` on Solana: ALSO advertise an escrow-backed offer whose
// `amount` is a CAP. The buyer deposits the cap, the handler runs, and only
// the measured charge is claimed (the rest of the deposit returns to the
// buyer). `{ capAtomics, charge? }`: `charge({ req, result, requirement,
// payer })` returns the atomic units to settle (<= cap; default = the
// cap). A handler that throws settles nothing and the deposit is refunded.
// Offered in addition to `exact`, never instead of it, and only when the
// deployment runs the upto facilitator (X402_UPTO_ENABLED). Not valid with
// `streaming`, whose body ships before the measurement exists.
upto,
// Optional post-settlement accrual hook (Roadmap phase 3: per-call
// royalties). Called fire-and-forget AFTER settlement succeeds, with
// { payer, network, txHash, amountAtomics, asset, resourceUrl }. Use it
// for ledger writes that must not delay or fail the settled response,
// e.g. /api/x402/skill-call recording the author's royalty accrual. Any
// throw is logged and swallowed; the payment already settled.
onSettled,
// Optional per-request resource URL. Default = route path. For routes
// that serve multiple distinct goods through query params (e.g.
// /api/x402/asset-download?slug=…), pass (req) => string to make each
// good its own SIWX grant key. The 402 challenge AND the SIWX message
// both use this URL, so the client signs against the same string we
// look up in siwx_payments.
resourceUrlBuilder,
// USE-21: `auth-hints` extension. Declares OAuth2 and/or SIWX as
// alternatives to paying for this endpoint. When set, the 402 body
// surfaces an `auth-hints` extension AND one zero-amount accepts[]
// entry per declared method, mapping authRequirements → acceptIndexes.
// A valid `Authorization: Bearer …` or `SIGN-IN-WITH-X: …` header
// short-circuits the payment dance with no facilitator settle and no
// X-PAYMENT-RESPONSE — the handler runs with `auth = { method, ... }`
// in place of `requirement`/`payer`.
//
// Shape:
// authHints: {
// oauth2: { requiredScope, tokenType?, authorizationServer?,
// tokenEndpoint?, registrationEndpoint? } | true,
// siwx: true,
// }
// Passing `true` for either method opts in with sensible defaults.
authHints,
// USE-17: Offer & Receipt extension. Defaults to `{}` which enables the
// extension when OFFER_RECEIPT_SIGNING_PRIVATE_KEY (eip712) or
// OFFER_RECEIPT_JWK (jws) is configured. Set `offerReceipt: false` to
// opt out, or `offerReceipt: { includeTxHash: true }` on routes that
// feed reputation systems where on-chain verifiability is more
// important than payer privacy. `offerValiditySeconds` overrides the
// 300-second default for how long signed offers stay valid.
offerReceipt = {},
// USE-13: Bazaar resource-level service metadata. Set per route so the
// facilitator can group / search / icon-ify the catalog entry. Pass
// `service: { serviceName, tags, iconUrl }` or use withService() from
// api/_lib/x402/bazaar-helpers.js to merge with three.ws defaults.
// Fields fall through to build402Body which gates each on the spec
// validation rules (printable ASCII, length caps, https URL).
service,
} = spec;
if (!route) throw new Error('paidEndpoint: route is required');
if (!description) throw new Error('paidEndpoint: description is required');
if (!bazaar) throw new Error('paidEndpoint: bazaar discovery extension is required');
// Legacy flat blocks become the v2 `{ info, schema }` entry here, once, so the
// live 402 matches what the discovery document already advertises.
const bazaarEntry = normalizeBazaarEntry(bazaar, { method });
if (typeof handler !== 'function') throw new Error('paidEndpoint: handler must be a function');
if (upto && streaming) {
throw new Error('paidEndpoint: `upto` cannot be combined with `streaming` (the body ships before the charge is measured)');
}
if (upto && !(BigInt(upto.capAtomics ?? 0) > 0n)) {
throw new Error('paidEndpoint: upto.capAtomics must be a positive integer of atomic units');
}
if (accessControl != null && typeof accessControl !== 'function') {
throw new Error('paidEndpoint: accessControl must be a function when provided');
}
if (siwx && typeof siwx.statement !== 'string') {
throw new Error('paidEndpoint: siwx.statement is required when siwx is set');
}
if (mode !== 'exact' && mode !== 'prepaid') {
throw new Error(`paidEndpoint: mode must be 'exact' or 'prepaid', got ${mode}`);
}
if (mode === 'prepaid' && (streaming || siwx)) {
throw new Error('paidEndpoint: mode prepaid cannot be combined with streaming or siwx');
}
const prepaidMode = mode === 'prepaid';
const routeConfig = { path: route, method: method.toUpperCase(), requiredScope };
const httpMethod = method.toUpperCase();
const allowMethods = httpMethod === 'GET' ? 'GET,HEAD,OPTIONS' : `${httpMethod},OPTIONS`;
const pidRequired = Boolean(paymentIdentifier.required);
const pidTtlSeconds = paymentIdentifier.ttlSeconds;
const pidExtension = paymentIdentifierExtension(pidRequired);
// wrap() instruments the request for zauth Provider Hub telemetry (every
// paidEndpoint route is a monitored x402 surface) and converts any uncaught
// handler throw into the standard JSON error envelope. instrument() is
// idempotent, so dispatchers that are already wrap()-ed (wk.js,
// x402/service.js) don't double-report.
return wrap(async function paidHandler(req, res) {
const requestStartTime = Date.now();
if (cors(req, res, { methods: allowMethods, origins: '*' })) return;
const isHead = req.method === 'HEAD' && httpMethod === 'GET';
// Discovery probes (x402scan, 402index, agent crawlers) hit paid routes
// with whatever method they like and expect the 402 challenge — the
// x402 discovery spec treats runtime 402 behavior as the source of
// truth, and a 405 reads as "not an x402 endpoint". A request on the
// wrong method that carries NO payment or auth credentials can only
// ever want the challenge, so serve it; anything carrying credentials
// intended to redeem the resource still gets the strict 405.
// An MPP credential is a payment, not a bearer token: lift it out of
// `authorization` so access control and the authenticated-caller bypass
// never mistake it for a login.
let mppAuthorization = null;
if (mpp && /^payment\s/i.test(req.headers?.authorization || '')) {
mppAuthorization = req.headers.authorization;
delete req.headers.authorization;
}
const hasCredentials =
!!mppAuthorization ||
!!req.headers?.['x-payment'] ||
!!req.headers?.['payment-signature'] ||
!!req.headers?.['sign-in-with-x'] ||
!!req.headers?.authorization ||
!!req.headers?.['x-api-key'];
const challengeOnly = req.method !== httpMethod && !isHead && !hasCredentials;
if (req.method !== httpMethod && !isHead && hasCredentials) {
res.setHeader('allow', allowMethods);
return error(res, 405, 'method_not_allowed', `use ${httpMethod}`);
}
const ip = clientIp(req);
// Abuse guard, tier 1 — anonymous-flood protection on the discovery/probe
// path. Authenticated and subscription callers (Bearer / SIWX / API key)
// have their own access-control gating downstream, so they bypass this
// per-IP cap; only unauthenticated traffic is bounded here. Non-critical:
// a Redis outage must never block price discovery or a legitimate paid
// retry — the fail-closed facilitator guard (tier 2) runs further down.
const isAuthenticatedCaller =
!!req.headers?.authorization ||
!!req.headers?.['sign-in-with-x'] ||
!!req.headers?.['x-api-key'];
if (!isAuthenticatedCaller) {
const probe = await limits.x402ProbeIp(ip);
if (!probe.success) {
return rateLimited(res, probe, 'too many requests — slow down and retry shortly');
}
}
const resourceUrl =
typeof resourceUrlBuilder === 'function'
? resourceUrlBuilder(req)
: resolveResourceUrl(req, route);
// Keep this instance's sponsor floor state warm so the challenge below
// reflects reality. Deliberately not awaited: at most one balance read per
// 20s per instance, and a slow or failed RPC must never delay a 402.
refreshSponsorFloorState();
let requirements;
try {
requirements = buildRequirements({
priceAtomics,
networks,
resourceUrl,
payToOverride: payTo,
acceptThree,
});
} catch (err) {
return error(
res,
err.status || 500,
err.code || 'misconfigured',
err.message || 'paid endpoint misconfigured',
);
}
if (mpp) {
const charge = pickSolanaExact(requirements);
if (charge) {
const challenge = buildSolanaChargeChallenge({ requirement: charge, description });
installMppResponse(res, { challengeHeader: challenge.header });
if (mppAuthorization && !req.headers['x-payment'] && !req.headers['payment-signature']) {
const parsed = parseSolanaChargeCredential(mppAuthorization);
if (!parsed.ok && parsed.code !== 'challenge_expired') {
return error(res, 401, parsed.code, parsed.message);
}
if (parsed.ok) {
if (!chargeMatchesRequirement(parsed.request, charge)) {
return error(res, 402, 'challenge_mismatch', 'the price or payee changed since this challenge, retry with a fresh one');
}
req.headers['x-payment'] = Buffer.from(
JSON.stringify(chargeToX402Payment({ requirement: charge, transaction: parsed.transaction })),
).toString('base64');
}
}
}
}
if (upto && uptoEnabled() && networks.includes('solana')) {
try {
const uptoAccept = await buildUptoOffer({ upto, resourceUrl, payTo });
if (uptoAccept) requirements = [...requirements, uptoAccept];
} catch (err) {
// The upto offer is additive. If it cannot be built (RPC down, key
// missing) the endpoint keeps selling `exact` rather than 503ing.
console.error(`paidEndpoint(${route}): upto offer unavailable`, err?.message || err);
}
}
// USE-21 auth-hints: append zero-amount accept entries for each declared
// auth method and build the auth-hints extension. The free entries
// reuse the Base USDC asset block so schema-checking clients accept
// them; amount="0" entries can only be redeemed by presenting the
// matching auth header, never via X-PAYMENT — verifyPayment enforces
// this structurally (it excludes amount-0 / extra.authRequired entries
// from requirement matching), so the guarantee does not depend on
// these entries being appended after the payable ones. The auth-hints
// extension maps each method to the index of its free entry so the
// buyer client knows which entry corresponds to which auth method.
let authHintsExtension = null;
// X402_AUTH_HINT_ACCEPTS=false suppresses the whole advertisement (the
// extension schema requires each declared method to map to a free
// accepts[] entry, so the two can only ship together). External x402
// directory validators reject challenges carrying amount="0" entries;
// the auth bypass itself keeps working either way because the
// access-control hook runs before the payment dance.
if (authHints && env.X402_AUTH_HINT_ACCEPTS) {
const baseTo = payTo?.base || env.X402_PAY_TO_BASE;
if (baseTo) {
const declarations = {};
if (authHints.oauth2) {
const oauthCfg = authHints.oauth2 === true ? {} : authHints.oauth2;
const idx = requirements.length;
requirements.push(
freeEvmAcceptForAuth({
network: NETWORK_BASE_MAINNET,
asset: env.X402_ASSET_ADDRESS_BASE,
payTo: baseTo,
authType: 'oauth2',
}),
);
declarations.oauth2 = { ...oauthCfg, acceptIndexes: [idx] };
}
if (authHints.siwx) {
const idx = requirements.length;
requirements.push(
freeEvmAcceptForAuth({
network: NETWORK_BASE_MAINNET,
asset: env.X402_ASSET_ADDRESS_BASE,
payTo: baseTo,
authType: 'sign-in-with-x',
}),
);
declarations.siwx = { acceptIndexes: [idx] };
}
if (declarations.oauth2 || declarations.siwx) {
authHintsExtension = declareAuthHintsExtension(declarations);
}
}
}
// Build the builder-code extension once per challenge so the same block
// is advertised in the 402 body AND passed to verifyPayment for echo
// validation. If a route declares services, override the auto-declared
// block from build402Body.
const appCode = env.X402_BUILDER_CODE_APP;
const builderCode =
appCode && Array.isArray(services) && services.length
? declareBuilderCodeExtension({ a: appCode, s: services })
: appCode
? declareBuilderCodeExtension({ a: appCode })
: null;
// SIWX extension advertised on every 402 when the endpoint opts in.
// `requirements[].network` lists every CAIP-2 chain we'll accept a
// signature for — the upstream helper turns it into supportedChains
// and enriches the info block (domain/uri/nonce/issuedAt) per request.
// Wrapped in try-catch: a failure here must never surface as 500 — the
// 402 challenge is still valid without the SIWX extension.
let siwxExtensions = null;
const prepaidReq = prepaidMode ? prepaidRequirement(requirements) : null;
if (siwx || prepaidReq) {
try {
siwxExtensions = await declareSiwxExtensionFor({
networks: requirements.map((r) => r.network),
resourceUrl,
statement:
siwx?.statement ||
'Spend your prepaid x402 balance on this request. Signing does not move funds.',
expirationSeconds: siwx?.expirationSeconds,
});
} catch (err) {
console.error('[paidEndpoint] declareSiwxExtensionFor failed', err?.message || err);
}
}
const extraExtensions = {
[PAYMENT_IDENTIFIER]: pidExtension,
...(builderCode ? { [BUILDER_CODE]: builderCode } : {}),
...(siwxExtensions || {}),
...(authHintsExtension || {}),
...(prepaidReq
? declarePrepaidExtension({ requirement: prepaidReq, origin: new URL(resourceUrl).origin })
: {}),
};
// USE-17: sign one offer per accepts[] entry (when issuer is
// configured AND the route hasn't opted out). Failing here returns
// null — we never want a missing signing key to break the 402 dance,
// since the protocol stays valid without the extension.
if (offerReceipt !== false) {
try {
const offersFragment = await buildOffersExtension(
resourceUrl,
requirements,
offerReceipt || {},
);
if (offersFragment) Object.assign(extraExtensions, offersFragment);
} catch (err) {
console.error('[paidEndpoint] buildOffersExtension failed', err?.message || err);
}
}
const challenge = {
resourceUrl,
accepts: requirements,
description,
mimeType,
bazaar: bazaarEntry,
extensions: extraExtensions,
...(service?.serviceName ? { serviceName: service.serviceName } : {}),
...(Array.isArray(service?.tags) && service.tags.length ? { tags: service.tags } : {}),
...(service?.iconUrl ? { iconUrl: service.iconUrl } : {}),
};
// Credential-less request on the wrong method (see the 405 gate above):
// answer with the challenge and stop — there is nothing to redeem, so
// none of the bypass/SIWX/settlement paths below apply.
if (challengeOnly) {
res.setHeader('allow', allowMethods);
return await send402(res, challenge);
}
// USE-21: auth-hints fast path. If the endpoint declared OAuth/SIWX as
// payment alternatives and the request carries a valid Authorization
// Bearer or SIGN-IN-WITH-X header, bypass the payment dance entirely.
// Runs BEFORE the generic access-control hook so the auth-hints
// principal is what reaches the handler. The SIWX path here does NOT
// require a prior on-chain payment (unlike the USE-16 returning-buyer
// SIWX flow further down).
if (authHintsExtension) {
const result = await authenticateAuthHintsRequest(req, {
audience: env.MCP_RESOURCE,
requiredScope: authHints?.oauth2?.requiredScope || requiredScope || null,
resourceUrl,
}).catch((err) => ({ ok: false, reason: 'auth_hints_failure', detail: err.message }));
if (result && !result.ok) {
return error(
res,
result.reason === 'insufficient_scope' ? 403 : 401,
result.reason || 'auth_failed',
result.detail || 'auth-hints verification failed',
);
}
if (result?.ok) {
let bypassResult;
try {
bypassResult = await handler({
req,
res,
bypass: {
reason: `auth-hints:${result.principal.method}`,
callerId: result.principal.userId
? `oauth:${result.principal.userId}`
: `siwx:${result.principal.address}`,
subscription: null,
oauth:
result.principal.method === 'oauth2'
? {
userId: result.principal.userId,
scope: result.principal.scope,
clientId: result.principal.clientId,
}
: null,
siwx:
result.principal.method === 'sign-in-with-x'
? {
address: result.principal.address,
network: result.principal.network,
}
: null,
},
auth: result.principal,
requirement: null,
payer: null,
});
} catch (err) {
if (err instanceof X402Error && err.status === 402) {
return await send402(res, { ...challenge, error: err.message });
}
return respondError(res, err.status || 500, err.code || 'internal_error', err);
}
if (res.writableEnded) return;
res.setHeader('x-payment-bypass', `auth-hints:${result.principal.method}`);
res.setHeader('cache-control', 'no-store');
res.setHeader('content-type', `${mimeType}; charset=utf-8`);
res.end(
typeof bypassResult === 'string' ? bypassResult : JSON.stringify(bypassResult),
);
logPaymentEvent({
eventType: 'bypass_granted',
route,
resourceUrl,
payer: result.principal.userId || result.principal.address || null,
durationMs: Date.now() - requestStartTime,
ipAddress: clientIp(req),
userAgent: req.headers?.['user-agent']?.slice(0, 512) || null,
metadata: { reason: `auth-hints:${result.principal.method}` },
});
return;
}
}
// Access-control hook (USE-23). Runs before the 402 so internal /
// subscription / OAuth callers can bypass payment entirely. Headers
// from `acResult.headers` are applied in both grant + abort paths.
if (accessControl) {
let acResult;
try {
acResult = await accessControl(req, routeConfig);
} catch (err) {
return error(
res,
err.status || 500,
err.code || 'access_control_failed',
err.message || 'access control failed',
);
}
if (acResult?.abort) {
if (acResult.headers) {
for (const [k, v] of Object.entries(acResult.headers)) res.setHeader(k, v);
}
return error(
res,
acResult.status || 403,
acResult.code || 'access_denied',
acResult.reason || 'access denied',
);
}
if (acResult?.grantAccess) {
let bypassResult;
try {
bypassResult = await handler({
req,
res,
bypass: {
reason: acResult.reason,
callerId: acResult.callerId,
subscription: acResult.subscription || null,
oauth: acResult.oauth || null,
},
requirement: null,
payer: null,
});
} catch (err) {
if (err instanceof X402Error && err.status === 402) {
return await send402(res, { ...challenge, error: err.message });
}
return respondError(res, err.status || 500, err.code || 'internal_error', err);
}
if (res.writableEnded) return;
if (acResult.headers) {
for (const [k, v] of Object.entries(acResult.headers)) res.setHeader(k, v);
}
res.setHeader('x-payment-bypass', acResult.reason || 'granted');
res.setHeader('cache-control', 'no-store');
res.setHeader('content-type', `${mimeType}; charset=utf-8`);
res.end(
typeof bypassResult === 'string' ? bypassResult : JSON.stringify(bypassResult),
);
logPaymentEvent({
eventType: 'bypass_granted',
route,
resourceUrl,
payer: acResult.callerId || null,
durationMs: Date.now() - requestStartTime,
ipAddress: clientIp(req),
userAgent: req.headers?.['user-agent']?.slice(0, 512) || null,
metadata: { reason: acResult.reason || 'access_control' },
});
return;
}
}
const paymentHeader = req.headers['x-payment'] || req.headers['payment-signature'];
// Prepaid balance. A SIGN-IN-WITH-X header with no X-PAYMENT proves the
// wallet; the price is debited from its prepaid balance and settled to us
// later in a batch. No balance, or an unreachable ledger, falls through to
// the ordinary 402 so the route is always payable per call.
let prepaidError = null;
if (prepaidReq && !paymentHeader && (req.headers['sign-in-with-x'] || req.headers['Sign-In-With-X'])) {
const auth = await verifyAuthHintsSiwx({ req, resourceUrl });
if (auth && !auth.ok) {
return error(res, 401, auth.reason || 'siwx_invalid', auth.detail || 'sign-in proof rejected');
}
if (auth?.ok) {
const outcome = await servePrepaid({
req,
res,
payer: auth.principal.address,
requirement: prepaidReq,
route,
resourceUrl,
handler,
challenge,
mimeType,
startedAt: requestStartTime,
});
if (outcome === 'served') return;
prepaidError =
outcome === 'insufficient'
? 'prepaid balance too low for this call; deposit more or pay per call'
: 'prepaid balances are temporarily unavailable; pay per call';
}
}
// SIWX short-circuit. A returning wallet sends `SIGN-IN-WITH-X: <base64>`
// instead of paying; we verify the CAIP-122 signature and skip the
// facilitator round-trip entirely. Only runs when the endpoint opted
// in and no X-PAYMENT was sent — paid requests still take precedence.
if (siwx && !paymentHeader) {
const auth = await authenticateSiwx({ req, resourceUrl });
if (auth?.ok) {
let result;
try {
result = await handler({
req,
res,
requirement: null,
payer: auth.address,
siwx: { address: auth.address, network: auth.network },
});
} catch (err) {
if (err instanceof X402Error && err.status === 402) {
return await send402(res, { ...challenge, error: err.message });
}
return respondError(res, err.status || 500, err.code || 'internal_error', err);
}
if (res.writableEnded) return;
res.setHeader('x-siwx-address', auth.address);
res.setHeader('cache-control', 'no-store');
res.setHeader('content-type', `${mimeType}; charset=utf-8`);
res.end(typeof result === 'string' ? result : JSON.stringify(result));
logPaymentEvent({
eventType: 'siwx_access',
route,
resourceUrl,
payer: auth.address,
network: auth.network || null,
durationMs: Date.now() - requestStartTime,
ipAddress: clientIp(req),
userAgent: req.headers?.['user-agent']?.slice(0, 512) || null,
});
return;
}
if (auth && !auth.ok) {
// 402 from siwx means "valid signature, no grant" → re-issue the
// challenge so the client can fall back to paying. Anything else
// (parse / signature failure) is a hard client error.
if (auth.status === 402) {
return await send402(res, { ...challenge, error: auth.error });
}
return error(res, auth.status, auth.code, auth.error);
}
// auth === null → no SIGN-IN-WITH-X header → fall through to 402.
}
if (!paymentHeader) {
return await send402(res, prepaidError ? { ...challenge, error: prepaidError } : challenge);
}
// Abuse guard, tier 2 — only requests carrying an X-PAYMENT header reach the
// facilitator /verify round-trip below, so this is where a junk-payment flood
// would amplify one cheap inbound request into one outbound facilitator call
// at our expense. Cap per-IP and globally; both CRITICAL (fail closed in
// prod) — during a Redis outage, rejecting a payment retry (the buyer keeps
// their funds and retries) beats letting the amplification run unbounded. The
// global ceiling is a runaway/DDoS circuit breaker, tunable via
// X402_VERIFY_GLOBAL_PER_HOUR as legitimate volume grows.
const verifyIpLimit = await limits.x402VerifyIp(ip);
if (!verifyIpLimit.success) {
return rateLimited(res, verifyIpLimit, 'too many payment attempts — retry shortly');
}
const verifyGlobalLimit = await limits.x402VerifyGlobal();
if (!verifyGlobalLimit.success) {
return rateLimited(res, verifyGlobalLimit, 'payment system at capacity — retry shortly');
}
// USE-15: required-mode rejects the call before we burn an RPC round-trip.
try {
enforceRequired({ paymentHeader, required: pidRequired });
} catch (err) {
if (err instanceof X402Error && err.status >= 400 && err.status < 500) {
return error(res, err.status, err.code, err.message);
}
throw err;
}
// USE-15: deduplicate before /verify. The hash covers method, URL and,
// for every non-GET route, the request body: many paid routes are POST
// (service proxies, pipelines, launches), and hashing the URL alone let
// two different bodies under one payment identifier share a cached
// response.
const clientPaymentId = extractIdFromHeader(paymentHeader);
let requestBody;
try {
requestBody = await paidRequestBody(req);
} catch (err) {
return respondError(res, err.status || 400, err.status === 413 ? 'payload_too_large' : 'bad_request', err);
}
const payloadHash = hashRequestPayload({
method: req.method,
url: req.url,
body: requestBody,
});
// Bind the idempotency cache to the signed payment proof so a stolen or
// guessed payment-identifier can't redeem a prior paid response for free.
const paymentHash = hashPaymentProof(paymentHeader);
// Always-on replay guard. The payment-identifier extension is client-
// opt-in, so a payer who omits it would otherwise get NO server-side
// replay protection: a captured X-PAYMENT header could be replayed to
// re-run the handler (re-delivering the paid good, with side effects) and
// re-hit /settle. The flow delivers BEFORE settling, so we can't lean on
// on-chain nonce reuse to stop the re-delivery, and we don't trust the
// external facilitator to reject the replay -- same defense-in-depth
// stance as the amount/recipient/network checks in x402-spec.js. When the
// client sends no id we fall back to the proof hash itself as the dedup
// key (reproducible only by the original payer), making replay protection
// unconditional. Entries are written only AFTER a successful settle, so a
// transient verify/settle failure never locks a legitimate payer out of
// retrying the same payment.
const paymentId = clientPaymentId || (paymentHash ? `proof:${paymentHash}` : null);
// Track whether THIS request owns the in-flight reservation, so we only
// release it on a failure path (never delete another request's slot or a
// stored response).
let ownsReservation = false;
if (paymentId) {
const lookup = await checkCache({ route, paymentId, payloadHash, paymentHash });
if (lookup.kind === 'hit') {
return writeCachedResponse(res, lookup.entry);
}
if (lookup.kind === 'conflict') {
return writeConflict(res, {
route,
attemptedHash: lookup.attemptedHash,
existingHash: lookup.existingHash,
reason: lookup.reason,
});
}
if (lookup.kind === 'inflight') {
return writeInflight(res);
}
// Atomically claim the slot. The check above + the deferred storeResponse
// (written only AFTER settle) left a window where N concurrent requests
// carrying the same X-PAYMENT all missed the cache, all ran the paid
// handler (side effects) and all settled before the first response was
// stored. The NX reservation closes it: only the winner proceeds; the rest
// observe the in-flight marker (or, once it finishes, the cached response).
ownsReservation = await reserveSlot({ route, paymentId, ttlSeconds: pidTtlSeconds });
if (!ownsReservation) {
const recheck = await checkCache({ route, paymentId, payloadHash, paymentHash });
if (recheck.kind === 'hit') return writeCachedResponse(res, recheck.entry);
if (recheck.kind === 'conflict') {
return writeConflict(res, {
route,
attemptedHash: recheck.attemptedHash,
existingHash: recheck.existingHash,
reason: recheck.reason,
});
}
return writeInflight(res);
}
}
// Durable replay guard — the leg the cache above cannot cover. Cache
// entries expire with pidTtlSeconds; a captured X-PAYMENT header replayed
// after that expiry misses the cache entirely and re-enters the handler,
// re-running its side effects and re-delivering the paid good. (The MONEY
// leg is already safe: settle-credit.js refuses a second credit per
// signature. Delivery is not, because the default path delivers before it
// settles.) One indexed lookup here, BEFORE verify and before the handler,
// keeps a replay away from the side effects; the atomic claim that closes
// the concurrent-race window runs at the end of settlement below. Fails
// OPEN on a DB outage — see api/_lib/x402/spent-payments.js for why this
// control's failure policy is the inverse of settle-credit's.
//
// A proof that settled but whose work then failed is NOT a replay: the
// buyer was charged and got nothing. Such a proof takes the paid-retry
// lane instead: no second verify, no second settle, the stored
// settlement is re-emitted, and the work runs again.
// `spentKey` is the hash the durable row lives under (the canonical hash,
// or the legacy one for a row written before canonicalization).
let spentKey = paymentHash;
let paidRetry = null;
if (paymentHash) {
let spent = await isPaymentSpent(paymentHash);
const legacyHash = legacyPaymentProofHash(paymentHeader);
if (!spent.spent && legacyHash && legacyHash !== paymentHash) {
const legacy = await isPaymentSpent(legacyHash);
if (legacy.spent) {
spent = legacy;
spentKey = legacyHash;
}
}
if (
spent.spent &&
spent.retryable &&
spent.endpoint === route &&
spent.settlement?.payload &&
spent.settlement.payload !== payloadHash
) {
// A paid retry re-runs the request that was paid for, never a
// different one: same method, URL and body.
if (ownsReservation) await releaseSlot({ route, paymentId });
return error(res, 409, 'payment_retry_mismatch', 'a paid retry must repeat the original request exactly',
paidFailureFields({ settlement: spent.settlement, retriesLeft: spent.retriesLeft }));
}
if (spent.spent && spent.retryable && spent.endpoint === route) {
const retry = await claimPaidRetry({ paymentHash: spentKey, endpoint: route });
// Lost the claim to a concurrent retry of the same header: re-read,
// so the answer below is "in flight", not "exhausted".
if (!retry.granted) spent = await isPaymentSpent(spentKey);
if (retry.granted) {
paidRetry = { record: retry.settlement || spent.settlement || {}, attempt: retry.attempt };
logPaymentEvent({
eventType: 'payment_paid_retry',
route,
resourceUrl,
payer: paidRetry.record.payer || null,
network: paidRetry.record.network || null,
txHash: paidRetry.record.transaction || null,
ipAddress: clientIp(req),
userAgent: req.headers?.['user-agent']?.slice(0, 512) || null,
metadata: { attempt: retry.attempt },
});
}
}
if (spent.spent && !paidRetry && spent.running) {
// The paid work for this proof is running right now on another
// request. Same answer as an in-flight idempotency slot.
if (ownsReservation) await releaseSlot({ route, paymentId });
return writeInflight(res);
}
if (spent.spent && !paidRetry && spent.outcome !== 'delivered' && spent.endpoint === route) {
// Charged, failed, and out of retries (or the window closed). Still
// a 409, but one that says the buyer paid, so a client escalates
// with the settlement instead of paying again.
if (ownsReservation) await releaseSlot({ route, paymentId });
res.setHeader('x-x402-idempotent', 'replayed');
return error(res, 409, 'payment_retries_exhausted', 'this payment settled but its retries are used up',
paidFailureFields({ settlement: spent.settlement, retriesLeft: 0 }));
}
if (spent.spent && !paidRetry) {
logPaymentEvent({
eventType: 'payment_replay_rejected',
route,
resourceUrl,
durationMs: Date.now() - requestStartTime,
ipAddress: clientIp(req),
userAgent: req.headers?.['user-agent']?.slice(0, 512) || null,
metadata: { stage: 'pre_handler' },
});
recordPaymentMetric({
kind: 'x402',
status: 'failed',
latencyMs: Date.now() - requestStartTime,
reason: 'payment_replayed',
});
if (ownsReservation) await releaseSlot({ route, paymentId });
return writeReplayed(res, { route });
}
}
let verified;
try {
verified = paidRetry
? verifiedFromRecord(paidRetry.record, requirements)
: await verifyPayment({ paymentHeader, requirements, builderCode });
} catch (err) {
// A failed verify is the amplification vector this family guards against: a
// junk X-PAYMENT header turns one cheap inbound request into one outbound
// facilitator call at our expense. So failure, not mere attempt, is what the
// per-IP verify bucket meters. Burn the extra penalty tokens here. A client
// that keeps paying successfully is never throttled for it, while a flood of
// invalid proofs drains its bucket and gets cut off at the pre-verify gate
// above, before the next facilitator round-trip. Rejected proofs (402) and
// upstream verify faults (502) both count, because an attacker chooses the
// shape of the garbage they send; exempting either would reopen the vector.
await limits.x402VerifyPenalty(ip);
// Verify is a payment outcome too — record it so the invalid/rejected-
// payment rate is visible alongside settlements. A 402 here is a rejected
// proof (insufficient/invalid), distinct from an upstream verify fault.
// The Axiom metric is fire-and-forget and unconfigured in most deploys,
// so ALSO write the durable audit event: the verify-reject rate is one
// of the three panels /api/ops/payment-outcomes exists to show, and a
// griefing wave (junk X-PAYMENT floods) is invisible without it.
logPaymentEvent({
eventType: 'payment_verify_rejected',
route,
resourceUrl,
durationMs: Date.now() - requestStartTime,
ipAddress: clientIp(req),
userAgent: req.headers?.['user-agent']?.slice(0, 512) || null,
metadata: {
reason: err.code || (err.status === 402 ? 'verify_rejected' : 'verify_failed'),
kind: err.status === 402 ? 'rejected_proof' : 'upstream_fault',
// The facilitator's own words (ata_create_wrong_account,
// transfer_wrong_mint, ...). The code above is the same
// invalid_payment for every rejected proof, which names the
// class and hides the cause.
detail: String(err.message || '').slice(0, 300) || null,
},
});
recordPaymentMetric({
kind: 'x402',
status: 'failed',
latencyMs: Date.now() - requestStartTime,
reason: err.code || (err.status === 402 ? 'verify_rejected' : 'verify_failed'),
});
if (ownsReservation) await releaseSlot({ route, paymentId });
if (err.status === 402) return await send402(res, { ...challenge, error: err.message });
return respondError(res, err.status || 502, err.code || 'verify_failed', err);
}
// `upto`: escrow the cap BEFORE the handler runs, so the seller never does
// work it cannot collect. A failed deposit delivers nothing and charges
// nothing; the buyer can sign a fresh channel and retry.
if (verified.upto && !paidRetry) {
let deposit;
let depositErr = null;
try {
deposit = await settleUptoDeposit({
paymentPayload: verified.paymentPayload,
requirement: verified.requirement,
});
} catch (err) {
depositErr = err;
}
if (depositErr || !deposit?.success) {
await limits.x402VerifyPenalty(ip);
if (ownsReservation) await releaseSlot({ route, paymentId });
const reason = depositErr?.message || deposit?.errorReason || 'deposit_failed';
recordPaymentMetric({
kind: 'x402',
status: 'failed',
latencyMs: Date.now() - requestStartTime,
reason: 'upto_deposit_failed',
});
if (depositErr) {
return respondError(res, 502, 'upto_deposit_failed', depositErr, { paid: false, retry_safe: true });
}
return await send402(res, { ...challenge, error: `upto deposit rejected: ${reason}` });
}
verified.upto.depositSettled = true;
verified.upto.depositTransaction = deposit.transaction || null;
}
// Cancel an escrowed `upto` channel: a zero claim returns the whole deposit
// to the buyer. Used when the handler failed, so a failed call costs nothing.
async function cancelUptoDeposit(reason) {
if (!verified.upto?.depositSettled || paidRetry) return;
try {
await settleUptoClaim({
paymentPayload: verified.paymentPayload,
requirement: verified.upto.capRequirement,
amountAtomics: '0',
});
} catch (err) {
console.error(`paidEndpoint(${route}): upto cancel failed (${reason})`, err?.message || err);
logPaymentEvent({
eventType: 'payment_upto_cancel_failed',
route,
resourceUrl,
payer: verified.payer || null,
network: verified.requirement?.network || null,
settlementStatus: 'failed',
durationMs: Date.now() - requestStartTime,
ipAddress: clientIp(req),
userAgent: req.headers?.['user-agent']?.slice(0, 512) || null,
metadata: { reason, error: String(err?.message || err).slice(0, 300) },
});
}
}
// Settle the verified payment and build the x-payment-response header
// (signed receipts + SIWX grant). Invoked with the response NOT yet
// flushed in BOTH paths: settle-then-stream calls it before the handler
// runs; deliver-then-settle calls it after the handler returned a value.
// On any settle/SIWX fault it writes the error response and returns null,
// and the caller returns immediately.
//
// On a paid retry the settlement already happened on the first attempt:
// nothing is settled again and no second receipt is issued; the stored
// settlement and its original x-payment-response are reused, and only the
// idempotent SIWX grant is re-run.
//
// `claimOutcome` is what the durable spent-payment claim records:
// 'delivered' when the good ships right after this returns (default
// path), 'running' when the handler still has to run (streaming path).
async function settleAndBuildResponse({ claimOutcome = 'delivered' } = {}) {
let settled;
let paymentResponseHeader;
if (paidRetry) {
settled = settledFromRecord(paidRetry.record);
paymentResponseHeader = paidRetry.record.header || encodePaymentResponseHeader(settled);
} else {
try {
settled = await settlePayment({ verified });
} catch (err) {
logPaymentEvent({
eventType: 'payment_failed',
route,
resourceUrl,
payer: verified.payer || null,
network: verified.requirement?.network || null,
amountAtomics: verified.requirement?.amount || null,
asset: verified.requirement?.asset || null,
settlementStatus: 'failed',
durationMs: Date.now() - requestStartTime,
ipAddress: clientIp(req),
userAgent: req.headers?.['user-agent']?.slice(0, 512) || null,
metadata: { error: err.message, code: err.code },
});
recordPaymentMetric({
kind: 'x402',
status: 'failed',
network: verified.requirement?.network,
amountUsd: atomicsToUsd(verified.requirement?.amount),
latencyMs: Date.now() - requestStartTime,
reason: err.code || 'settle_failed',
});
if (ownsReservation) await releaseSlot({ route, paymentId });
respondError(res, err.status || 502, err.code || 'settle_failed', err);
return null;
}
paymentResponseHeader = encodePaymentResponseHeader(settled, await buildResponseExtensions(settled));
}
const record = settlementRecord(settled, verified, paymentResponseHeader, payloadHash);
// Record the SIWX grant so the wallet can re-access via signature next
// time. siwx-storage.recordPayment is idempotent (upsert on PK), so a
// retried grant is safe. The on-chain payment is final; if Neon hiccups
// the buyer gets a paid failure that says to retry with the same
// payment, which re-runs this write without a second charge.
// An `upto` call that measured zero charged nothing, so it earns no session.
const uptoFree = verified.upto && String(verified.requirement.amount) === '0';
if (siwx && verified.payer && !uptoFree) {
try {
await recordSiwxPayment({
resourceUrl,
payer: normalizeAddress(verified.requirement.network, verified.payer),
network: verified.requirement.network,
ttlSeconds: siwx.ttlSeconds ?? null,
});
logPaymentEvent({
eventType: 'siwx_grant',
route,
resourceUrl,
payer: verified.payer,
network: verified.requirement.network,
ipAddress: clientIp(req),
userAgent: req.headers?.['user-agent']?.slice(0, 512) || null,
metadata: { ttlSeconds: siwx.ttlSeconds ?? null },
});
} catch (err) {
if (ownsReservation) await releaseSlot({ route, paymentId });
await failAfterSettle({ status: 502, code: 'siwx_record_failed', err, record, claimed: Boolean(paidRetry) });
return null;
}
}
// Durable spent-payment claim. Runs LAST, once settlement and every
// downstream step above succeeded. Atomic on the primary key: of any
// set of concurrent requests carrying one X-PAYMENT header exactly one
// claim wins, which closes the race the pre-handler lookup alone
// cannot. A losing claim is a replay that got past the lookup: refuse
// the response rather than deliver the good twice. Fails OPEN on a DB
// outage (the cache guard and settle-credit still apply). A paid retry
// already holds the row through claimPaidRetry.
if (!paidRetry) {
const claim = await claimSpentPayment({
paymentHash,
endpoint: route,
amountAtomics: verified.requirement?.amount ?? null,
outcome: claimOutcome,
settlement: record,
});
if (claim.replay) {
logPaymentEvent({
eventType: 'payment_replay_rejected',
route,
resourceUrl,
payer: settled.payer || verified.payer || null,
network: settled.network || verified.requirement?.network || null,
amountAtomics: verified.requirement?.amount || null,
asset: verified.requirement?.asset || null,
txHash: settled.transaction || null,
settlementStatus: 'failed',
durationMs: Date.now() - requestStartTime,
ipAddress: clientIp(req),
userAgent: req.headers?.['user-agent']?.slice(0, 512) || null,
metadata: { stage: 'post_settle' },
});
recordPaymentMetric({
kind: 'x402',
status: 'failed',
network: verified.requirement?.network,
amountUsd: atomicsToUsd(verified.requirement?.amount),
latencyMs: Date.now() - requestStartTime,
reason: 'payment_replayed',
});
if (ownsReservation) await releaseSlot({ route, paymentId });
writeReplayed(res, { route });
return null;
}
}
return { settled, paymentResponseHeader, record };
}
// USE-17: issue a signed receipt for the settled payment and stash it in
// the response extensions envelope. Persist asynchronously so the
// /api/x402/my-receipts buyer-lookup path can serve it later: the
// recordReceipt write is fire-and-forget so a Neon hiccup never surfaces
// as a 5xx on a payment that already settled on-chain.
async function buildResponseExtensions(settled) {
let responseExtensions;
if (offerReceipt !== false) {
try {
// Facilitators may omit payer/network from the settle response (backward-
// compat). Fall back to verified context so the receipt is still issued.
// BSC `direct` flows have verified.payer = null (contract event, no signed
// payload) — buildReceiptExtension returns null in that case gracefully.
const receiptSettled = {
...settled,
payer: settled.payer || verified.payer || null,
network: settled.network || verified.requirement?.network || null,
};
const receiptBuilt = await buildReceiptExtension(
resourceUrl,
receiptSettled,
offerReceipt || {},
);
if (receiptBuilt) {
responseExtensions = receiptBuilt.extensionFragment;
// Store the SAME settlement context the receipt was issued
// against: `settled` alone can be missing the payer (some
// facilitators omit it), and a payer-less row is dropped by
// the storage layer, silently losing a receipt the buyer
// already holds. Amount/asset come from the verified
// requirement so the buyer can see what each call cost.
recordReceipt({
resourceUrl,
signedReceipt: receiptBuilt.signedReceipt,
settled: receiptSettled,
payment: {
amountAtomics: verified.requirement?.amount || null,
asset: verified.requirement?.asset || null,
},
});
}
} catch (err) {
// A receipt sign failure must not break the 200 — the payment settled
// and the work ran. Log and continue with an unsigned response.
console.error('x402_receipt_sign_failed', err);
}
}
// New-stack receipt: keyed by X402_RECEIPT_SIGNING_KEY. Returns null when
// unset (byte-identical to current behaviour) or when payer/network absent
// (e.g. BSC direct with no decoded event payer). Merged as `signedReceipt`
// alongside any `info.receipt` produced by the old-stack above.
try {
const sr = await signReceipt({
resourceUrl,
payer: settled.payer || verified.payer || null,
network: settled.network || verified.requirement?.network || null,
txHash: settled.transaction,
includeTxHash: offerReceipt?.includeTxHash === true,
});
if (sr) {
responseExtensions = responseExtensions ?? {};
const existing = responseExtensions['offer-receipt'];
responseExtensions['offer-receipt'] = existing
? { ...existing, signedReceipt: sr }
: { signedReceipt: sr };
}
} catch (err) {
console.error('x402_receipt_sign_failed', err);
}
return responseExtensions;
}
// The buyer was charged and the work did not complete. Record the failure
// against the spent payment (opening its retry window), log it, and answer
// with the paid-failure fields. `claimed` is false only on a first attempt
// that failed before its claim was taken (the SIWX grant write), which
// writes the row here.
async function failAfterSettle({ status, code, err, record, claimed }) {
if (!claimed) {
const claim = await claimSpentPayment({
paymentHash,
endpoint: route,
amountAtomics: verified.requirement?.amount ?? null,
outcome: 'failed_after_settle',
settlement: record,
lastError: err?.message || code,
});
// Another request already holds this proof's row; never overwrite
// its outcome from here.
if (claim.replay) {
writeReplayed(res, { route });
return;
}
}
const state = await markFailedAfterSettle({
paymentHash: spentKey,
settlement: record,
lastError: err?.message || code,
});
logPaymentEvent({
eventType: 'payment_failed_after_settle',
route,
resourceUrl,
payer: record.payer,
network: record.network,
amountAtomics: record.amount,
asset: record.asset,
txHash: record.transaction,
settlementStatus: 'success',
durationMs: Date.now() - requestStartTime,
ipAddress: clientIp(req),
userAgent: req.headers?.['user-agent']?.slice(0, 512) || null,
metadata: { code, error: String(err?.message || '').slice(0, 300), retries_left: state.retriesLeft, retry: paidRetry?.attempt ?? 0 },
});
recordPaymentMetric({
kind: 'x402',
status: 'failed',
network: record.network,
amountUsd: atomicsToUsd(record.amount),
latencyMs: Date.now() - requestStartTime,
reason: 'failed_after_settle',
});
if (res.headersSent) {
// A stream that already began cannot carry a JSON error; end it. The
// row says failed, so the same payment can still be retried.
if (!res.writableEnded) res.end();
return;
}
writePaidFailure(res, { status, code, err, record, state });
}
// Success telemetry for a settled payment — logged once the good has been
// delivered (after res.end in the buffered path, after the handler streamed
// in the streaming path).
//
// A `status:'pending'` settlement is recorded as PENDING, not success. The
// good ships either way (the transaction is broadcast and the buyer holds
// its hash), but the books are not closed until
// /api/cron/x402-settlement-reconcile confirms the signature, and telemetry
// that called it settled would overstate revenue by exactly the payments
// still in flight.
function recordSettledSuccess(settled) {
const pending = settled.status === 'pending';
logPaymentEvent({
eventType: 'payment_settled',
route,
resourceUrl,
payer: settled.payer || verified.payer || null,
network: settled.network || verified.requirement?.network || null,
amountAtomics: verified.requirement?.amount || null,
asset: verified.requirement?.asset || null,
txHash: settled.transaction || null,
settlementStatus: pending ? 'pending' : 'success',
facilitatorResponse: settled,
durationMs: Date.now() - requestStartTime,
ipAddress: clientIp(req),
userAgent: req.headers?.['user-agent']?.slice(0, 512) || null,
});
// Axiom payment metric — success rate + per-network latency the audit DB
// can't aggregate live. Fire-and-forget no-op until AXIOM_* is set; carries
// only on-chain identifiers (route, network, tx signature), never PII.
recordPaymentMetric({
kind: 'x402',
status: 'ok',
network: settled.network || verified.requirement?.network,
amountUsd: atomicsToUsd(verified.requirement?.amount),
latencyMs: Date.now() - requestStartTime,
signature: settled.transaction || undefined,
});
// Post-settlement accrual hook (royalties). Fire-and-forget: the
// payment is final and the good is already delivered by the time any
// caller observes this, so a ledger hiccup must never surface here.
if (typeof onSettled === 'function') {
Promise.resolve()
.then(() =>
onSettled({
payer: settled.payer || verified.payer || null,
network: settled.network || verified.requirement?.network || null,
txHash: settled.transaction || null,
amountAtomics: verified.requirement?.amount || null,
asset: verified.requirement?.asset || null,
resourceUrl,
}),
)
.catch((err) => console.error(`paidEndpoint(${route}): onSettled hook failed`, err));
}
}
// STREAMING routes deliver the good by flushing their own body (binary
// download, res.pipe, SSE). Settle FIRST and emit the payment-response
// header up-front — headers must precede the streamed body — so the
// buyer is charged before a single byte of the good ships. A streamed
// body isn't buffered, so no idempotency cache entry is stored; the
// reservation is released once the handler finishes.
if (streaming) {
const outcome = await settleAndBuildResponse({ claimOutcome: 'running' });
if (!outcome) return;
const { settled, paymentResponseHeader, record } = outcome;
res.setHeader('x-payment-response', paymentResponseHeader);
res.setHeader('cache-control', 'no-store');
let result;
try {
result = await handler({
req,
res,
requirement: verified.requirement,
payer: verified.payer,
settled,
});
} catch (err) {
if (ownsReservation) await releaseSlot({ route, paymentId });
// The handler finished its body and then threw: the good shipped, so
// the payment is spent like any delivered one.
if (res.writableEnded) {
await markDelivered(spentKey);
recordSettledSuccess(settled);
return;
}
// The payment already settled on-chain and the good did not ship.
// Never answer "pay again": record the failure against this proof
// and tell the buyer the same payment re-runs the work. A 402 thrown
// by the handler is reported as a 500 here, because a 402 now would
// prompt the client to pay a second time.
const status = err?.status && err.status !== 402 ? err.status : 500;
await failAfterSettle({ status, code: err?.code || 'internal_error', err, record, claimed: true });
return;
}
if (ownsReservation) await releaseSlot({ route, paymentId });
// A streaming handler that returned a value instead of flushing gets
// the same buffered emission as the default path (content-type from the
// route mime), so streaming is a superset — not a different contract.
if (!res.writableEnded) {
res.setHeader('content-type', `${mimeType}; charset=utf-8`);
res.end(typeof result === 'string' ? result : JSON.stringify(result));
}
await markDelivered(spentKey);
recordSettledSuccess(settled);
return;
}
let result;
try {
result = await handler({
req,
res,
requirement: verified.requirement,
payer: verified.payer,
});
} catch (err) {
if (ownsReservation) await releaseSlot({ route, paymentId });
await cancelUptoDeposit('handler_threw');
// A paid retry is past settlement: the buyer paid on the first attempt,
// so this failure keeps the retry lane open rather than asking for a
// new payment.
if (paidRetry) {
const status = err?.status && err.status !== 402 ? err.status : 500;
const record = settlementRecord(settledFromRecord(paidRetry.record), verified, paidRetry.record.header, payloadHash);
await failAfterSettle({ status, code: err?.code || 'internal_error', err, record, claimed: true });
return;
}
if (err instanceof X402Error && err.status === 402) {
return await send402(res, { ...challenge, error: err.message });
}
// Deliver-then-settle: nothing was settled, so the buyer was not
// charged and the same payment can be sent again.
return respondError(res, err.status || 500, err.code || 'internal_error', err, { paid: false, retry_safe: true });
}
// Deliver-then-settle: the handler MUST return a value and leave the
// response unflushed so settlement runs below before the body ships. A
// handler that ended its own response has delivered the good WITHOUT
// settling — the buyer would get it for free. Fail loudly: release the
// slot, record the leak, and throw so wrap() alerts. A route that needs
// to write its own body must set `streaming: true` (settle-then-stream)
// so payment is captured before delivery.
if (res.writableEnded) {
if (ownsReservation) await releaseSlot({ route, paymentId });
await cancelUptoDeposit('handler_flushed');
logPaymentEvent({
eventType: 'payment_unsettled_flush',
route,
resourceUrl,
payer: verified.payer || null,
network: verified.requirement?.network || null,
amountAtomics: verified.requirement?.amount || null,
asset: verified.requirement?.asset || null,
settlementStatus: 'failed',
durationMs: Date.now() - requestStartTime,
ipAddress: clientIp(req),
userAgent: req.headers?.['user-agent']?.slice(0, 512) || null,
metadata: { reason: 'handler flushed response before settlement; set streaming:true to settle first' },
});
recordPaymentMetric({
kind: 'x402',
status: 'failed',
network: verified.requirement?.network,
amountUsd: atomicsToUsd(verified.requirement?.amount),
latencyMs: Date.now() - requestStartTime,
reason: 'unsettled_flush',
});
throw new Error(
`paidEndpoint(${route}): handler flushed its response before settlement — set streaming:true for routes that write their own body`,
);
}
// `upto`: price the work now that it ran. Everything downstream (the claim,
// receipts, spend ledgers, onSettled) reads the charge off
// verified.requirement.amount, so lowering it here is the single switch.
if (verified.upto && !paidRetry) {
let charge;
try {
const cap = verified.upto.capRequirement.amount;
const measured =
typeof upto.charge === 'function'
? await upto.charge({
req,
result,
requirement: verified.upto.capRequirement,
payer: verified.payer,
})
: cap;
charge = normaliseCharge(measured, cap);
} catch (err) {
await cancelUptoDeposit('charge_failed');
return respondError(res, err.status || 500, err.code || 'internal_error', err, {
paid: false,
retry_safe: true,
});
}
verified = {
...verified,
requirement: { ...verified.requirement, amount: charge.toString() },
};
}
const outcome = await settleAndBuildResponse();
if (!outcome) return;
const { settled, paymentResponseHeader } = outcome;
if (paidRetry) await markDelivered(spentKey);
// Roadmap phase 4: per-job metering. The settlement already landed, so
// the hook can bind the payment facts (payer, amount, tx) to the exact
// job core and sign the receipt. Runs before the flush so the receipt
// travels inside the response body it attests to.
if (typeof metered === 'function') {
try {
const metering = await metered({
req,
result,
settled,
payer: settled.payer || verified.payer || null,
requirement: verified.requirement,
});
if (
metering &&
typeof metering === 'object' &&
result &&
typeof result === 'object' &&
!Array.isArray(result)
) {
result = { ...result, ...metering };
}
} catch (err) {
// A metering failure must never break a settled response: the buyer
// paid and the work ran. Log and ship the un-metered result.
console.error(`paidEndpoint(${route}): metered hook failed`, err);
}
}
const contentType = `${mimeType}; charset=utf-8`;
const body = typeof result === 'string' ? result : JSON.stringify(result);
res.setHeader('x-payment-response', paymentResponseHeader);
res.setHeader('cache-control', 'no-store');
res.setHeader('content-type', contentType);
res.end(body);
recordSettledSuccess(settled);
if (paymentId) {
await storeResponse({
route,
paymentId,
payloadHash,
paymentHash,
status: 200,
body,
contentType,
paymentResponseHeader,
ttlSeconds: pidTtlSeconds,
});
}
});
}