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
fix(x402): keep the other seventeen paid endpoints receiving on an empty sponsor
nirholas1d6fbbeda12b
diff --git a/api/_lib/x402-spec.js b/api/_lib/x402-spec.jsindex 859947f21..0e171cef4 100644--- a/api/_lib/x402-spec.js+++ b/api/_lib/x402-spec.js@@ -74,6 +74,9 @@ import {selfFacilitatorEnabled,selfFacilitatorUrl,} from './x402/ring-config.js';+// Safe to import here: self-facilitator.js pulls in env + the Solana connection+// only, never this module, so there is no cycle.+import { sponsorKnownBelowFloor } from './x402/self-facilitator.js';export { X402Error };// Re-export both gas-sponsoring declarators together so callers building 402@@ -184,7 +187,17 @@ export function paymentRequirements(resourceUrl, { amount } = {}) {// Solana-first platform default: the Solana accept leads so first-accept// clients and the payment modal settle on Solana unless the caller picks// another network explicitly. Base/BSC follow as alternatives.- if (env.X402_PAY_TO_SOLANA && solanaSettleable()) {+ // Sponsoring the buyer's Solana fee is a convenience, not a precondition for+ // being paid. When we settle in-house and the sponsor cannot co-sign (no key+ // loaded, or the wallet under its SOL floor), advertise the accept WITHOUT a+ // feePayer: the buyer signs as their own fee payer and the facilitator only+ // broadcasts. Mirrors the same fallback in x402-paid-endpoint.js, so the 17+ // hand-rolled paid endpoints on this builder keep receiving on an empty+ // sponsor wallet instead of going dark with it.+ const solanaSelfPayOnly =+ resolveSolanaFacilitator().self &&+ (!env.X402_FEE_PAYER_SOLANA || !solanaSettleable() || sponsorKnownBelowFloor());+ if (env.X402_PAY_TO_SOLANA && (solanaSettleable() || solanaSelfPayOnly)) {out.push({...common,network: NETWORK_SOLANA_MAINNET,@@ -192,22 +205,31 @@ export function paymentRequirements(resourceUrl, { amount } = {}) {asset: env.X402_ASSET_MINT_SOLANA,// PayAI's Solana facilitator requires clients to build the SPL transfer// with this account as fee payer; without it, /verify rejects with- // `missing_fee_payer`.- extra: { name: 'USDC', decimals: 6, feePayer: env.X402_FEE_PAYER_SOLANA },+ // `missing_fee_payer`. Omitted only in self-pay mode, which the guard+ // above restricts to the self-routed facilitator for exactly that reason.+ extra: {+ name: 'USDC',+ decimals: 6,+ ...(solanaSelfPayOnly ? {} : { feePayer: env.X402_FEE_PAYER_SOLANA }),+ },});// $THREE alongside USDC on the same Solana rail (opt-in via// X402_ACCEPT_THREE_SOLANA, see env.js). Pushed AFTER the USDC entry so// clients that pick the first Solana accept keep settling USDC; the modal// surfaces both as a token chooser. Same fee-payer co-sign path, the// checkout server transfers any SPL mint, so no extra wiring is needed.- if (env.X402_ACCEPT_THREE_SOLANA && env.X402_FEE_PAYER_SOLANA) {+ if (env.X402_ACCEPT_THREE_SOLANA && (env.X402_FEE_PAYER_SOLANA || solanaSelfPayOnly)) {out.push({...common,...(env.X402_THREE_AMOUNT_SOLANA ? { amount: String(env.X402_THREE_AMOUNT_SOLANA) } : {}),network: NETWORK_SOLANA_MAINNET,payTo: env.X402_PAY_TO_SOLANA,asset: env.THREE_TOKEN_MINT,- extra: { name: 'THREE', decimals: env.THREE_TOKEN_DECIMALS, feePayer: env.X402_FEE_PAYER_SOLANA },+ extra: {+ name: 'THREE',+ decimals: env.THREE_TOKEN_DECIMALS,+ ...(solanaSelfPayOnly ? {} : { feePayer: env.X402_FEE_PAYER_SOLANA }),+ },});}}@@ -1184,6 +1206,18 @@ export async function settlePayment(args) {// this refusal wearing a server-fault status code. Same treatment: 503 +// retryable code, so buyers back off instead of reading a funding cap as an// outage. Genuinely unexplained settle failures still stay 502.+ // Self-pay: the BUYER's wallet cannot cover the Solana network fee. Nothing+ // is wrong on our side and no top-up of ours will help, so this must not+ // wear the "we are refunding our wallet, retry later" message. It is a+ // 402: the buyer adds a little SOL and pays again.+ if (/^buyer_cannot_cover_fee/.test(reason)) {+ throw new X402Error(+ 'insufficient_fee_balance',+ 'your wallet does not have enough SOL to cover the Solana network fee for this payment; ' ++ `add a small amount of SOL and try again (${reason})`,+ 402,+ );+ }if (/^fee_runway_exhausted/.test(reason)) {throw new X402Error('settlement_unavailable',diff --git a/api/_lib/x402/self-facilitator.js b/api/_lib/x402/self-facilitator.jsindex ce0d2e494..3184c9801 100644--- a/api/_lib/x402/self-facilitator.js+++ b/api/_lib/x402/self-facilitator.js@@ -606,7 +606,14 @@ export async function settleRingPayment({ paymentPayload, requirement, conn, feeif (solLamports - estFeeLamports < floorFor) {return {success: false,- reason: `fee_wallet_cannot_cover_settle:${solLamports}-${estFeeLamports}<${floorFor}`,+ // Distinct reason per mode, because the two mean opposite things to the+ // person reading the error. In sponsor mode WE are short and the buyer+ // should retry later; in self-pay the BUYER's own wallet cannot cover+ // the network fee, and telling them we are topping up our wallet would+ // send them away waiting for something that will never help.+ reason: selfPay+ ? `buyer_cannot_cover_fee:${solLamports}<${estFeeLamports}`+ : `fee_wallet_cannot_cover_settle:${solLamports}-${estFeeLamports}<${floorFor}`,sponsorSolLamports: solLamports,estFeeLamports,feePayer: decoded.feePayer,diff --git a/tests/x402-floor-degradation.test.js b/tests/x402-floor-degradation.test.jsindex 1d3f5d8de..44914aebd 100644--- a/tests/x402-floor-degradation.test.js+++ b/tests/x402-floor-degradation.test.js@@ -10,8 +10,9 @@// 2. The settle path records the observed floor state, readable// synchronously via sponsorKnownBelowFloor().// 3. While the floor state is fresh, the 402 challenge builder stops-// advertising the Solana accept (and classifies an all-dropped accepts-// list as 503, never the 500 no_payto_configured misconfig error).+// advertising the SPONSORED Solana accept. It no longer drops Solana+// outright: it falls back to self-pay (see tests/x402-selfpay-fallback),+// so a receiving endpoint keeps taking money on an empty sponsor wallet.import { describe, it, expect, vi, beforeEach } from 'vitest';@@ -47,10 +48,6 @@ describe('settlePayment floor classification', () => {expect(err).toMatchObject({ code: 'settlement_unavailable', status: 503 });});- // The wallet fee governor refuses for the same reason class and was missed by- // the floor branch, so it kept answering 502 long after the floor stopped:- // 15,619 of the autonomous loop's 20,030 `http_502` rows in the 48h to- // 2026-08-06 were this one refusal wearing a server-fault status.// A wallet that clears the floor but cannot afford this settle's ATA rent is// the same transient funding gap, and must not read as a broken endpoint.it('maps fee_wallet_cannot_cover_settle to 503 settlement_unavailable', async () => {@@ -58,6 +55,21 @@ describe('settlePayment floor classification', () => {expect(err).toMatchObject({ code: 'settlement_unavailable', status: 503 });});+ // Self-pay puts the buyer's own wallet on the hook for the network fee, so a+ // shortfall there is the buyer's to fix. Reporting it as our sponsor being+ // refunded would send them away to wait for something that never helps.+ it('maps buyer_cannot_cover_fee to a 402 the buyer can act on', async () => {+ const err = await settleAgainst('buyer_cannot_cover_fee:1200<5000');+ expect(err).toMatchObject({ code: 'insufficient_fee_balance', status: 402 });+ expect(err.message).toMatch(/enough SOL/i);+ // It must not be mistaken for the platform-side pause.+ expect(err.code).not.toBe('settlement_unavailable');+ });++ // The wallet fee governor refuses for the same reason class and was missed by+ // the floor branch, so it kept answering 502 long after the floor stopped:+ // 15,619 of the autonomous loop's 20,030 `http_502` rows in the 48h to+ // 2026-08-06 were this one refusal wearing a server-fault status.it('maps fee_runway_exhausted to 503 settlement_unavailable', async () => {const err = await settleAgainst('fee_runway_exhausted:10132243+10000>10000000');expect(err).toMatchObject({ code: 'settlement_unavailable', status: 503 });diff --git a/tests/x402-self-facilitator-floor-accounting.test.js b/tests/x402-self-facilitator-floor-accounting.test.jsindex c3eb0efdb..12f84b90f 100644--- a/tests/x402-self-facilitator-floor-accounting.test.js+++ b/tests/x402-self-facilitator-floor-accounting.test.js@@ -202,7 +202,7 @@ describe('self-pay: a dry sponsor must not close a receiving endpoint', () => {conn,});- expect(res.reason || '').not.toMatch(/fee_wallet_below_floor|fee_wallet_cannot_cover_settle/);+ expect(res.reason || '').not.toMatch(/fee_wallet_below_floor|cannot_cover/);});it('still refuses a self-pay buyer who cannot cover the fee', async () => {@@ -217,7 +217,9 @@ describe('self-pay: a dry sponsor must not close a receiving endpoint', () => {});expect(res.success).toBe(false);- expect(res.reason).toMatch(/^fee_wallet_cannot_cover_settle:/);+ // Self-pay names the buyer, not us: a shortfall in their wallet must never+ // be reported as our sponsor needing a top-up.+ expect(res.reason).toMatch(/^buyer_cannot_cover_fee:/);});it('leaves the sponsor reserve fully in force for sponsored settles', async () => {diff --git a/tests/x402-self-facilitator-min-settle.test.js b/tests/x402-self-facilitator-min-settle.test.jsindex 7b0f024ca..91ad8ba34 100644--- a/tests/x402-self-facilitator-min-settle.test.js+++ b/tests/x402-self-facilitator-min-settle.test.js@@ -110,7 +110,7 @@ describe('settleRingPayment minimum-settle guard', () => {// A self-pay buyer is not held to the sponsor's reserve (that floor exists// to stop OUR wallet draining), only to affording the fee they are about// to pay. So the refusal is the affordability one against a zero floor.- expect(res.reason).toMatch(/^fee_wallet_cannot_cover_settle:0-\d+<0$/);+ expect(res.reason).toMatch(/^buyer_cannot_cover_fee:0<\d+$/);expect(res.selfPay).toBe(true);});});diff --git a/tests/x402-selfpay-fallback.test.js b/tests/x402-selfpay-fallback.test.jsindex ab0092b7b..5d799293a 100644--- a/tests/x402-selfpay-fallback.test.js+++ b/tests/x402-selfpay-fallback.test.js@@ -133,3 +133,36 @@ describe('a dry sponsor keeps the endpoint payable via self-pay', () => {});});});++// The same fallback on the OTHER accept builder. paymentRequirements() serves+// the 17 hand-rolled paid endpoints (asset-download, skill-call, print-order,+// cosmetic-purchase, knock and friends) that do not go through paidEndpoint,+// and it had the identical flaw: no sponsor meant no Solana accept at all.+describe('paymentRequirements shares the self-pay fallback', () => {+ async function requirements({ belowFloor }) {+ vi.doMock('../api/_lib/x402/self-facilitator.js', () => ({+ sponsorKnownBelowFloor: () => belowFloor,+ refreshSponsorFloorState: () => {},+ }));+ const { paymentRequirements } = await import('../api/_lib/x402-spec.js');+ return paymentRequirements('https://three.ws/api/x402/asset-download', { amount: '1000' });+ }++ it('keeps advertising Solana without a feePayer when the sponsor is dry', async () => {+ const accepts = solanaAccepts(await requirements({ belowFloor: true }));+ expect(accepts.length).toBeGreaterThan(0);+ for (const accept of accepts) {+ expect(accept.extra.feePayer).toBeUndefined();+ }+ // $THREE survives the sponsor going dry here too.+ expect(accepts.map((a) => a.asset)).toContain(THREE);+ });++ it('keeps sponsoring gas while the sponsor is healthy', async () => {+ const accepts = solanaAccepts(await requirements({ belowFloor: false }));+ expect(accepts.length).toBeGreaterThan(0);+ for (const accept of accepts) {+ expect(accept.extra.feePayer).toBe(SPONSOR);+ }+ });+});