Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

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.js
index 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.js
index 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, fee
if (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.js
index 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.js
index 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.js
index 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.js
index 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);
+ }
+ });
+});