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.

feat(x402): accept v1 payment requirements alongside v2 in every buyer

nirholas0a7085020a11
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 90d0a6c36..99dfdbbd8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -23,6 +23,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
- **The native $THREE launchpad now taxes snipers, not just steady trading**: Every pool on the native launchpad lane used to open at the same flat 1% trading fee a coin keeps forever, which is exactly what a sniper bot wants: the same price whether it buys in the pool's first block or an hour later. New pools now open at a 50% fee that decays exponentially down to the normal 1% over the first 100 slots (about 40 seconds), so a bot buying in the first block pays close to half its $THREE in fees while an organic buyer a minute later pays the standard rate. The coin creator's own bundled first buy stays exempt, since that is the creator funding their own launch, not a snipe. The schedule runs entirely on Meteora's own Dynamic Bonding Curve fee scheduler, no new contract. (`/docs/native-launchpad`) `[feature, security]`
- **The pre-push guard now catches a leaked Solana secret key, and withdrawals warn before a sweeper bot drains them**: scripts/check-secrets.mjs, the hook that blocks a push carrying a credential, now decodes every 86-90 character base58 run in added content and flags it only when the first 32 bytes derive the embedded public key in the last 32 bytes via Ed25519, catching a real Solana keypair secret while leaving the repo's thousands of genuine 64-byte transaction signatures untouched. Separately, the agent wallet's Withdraw tab now reads a destination's recent on-chain history before you send: a wallet that repeatedly drains to near-zero within seconds of receiving funds, the sweeper-bot fingerprint, surfaces a blocking warning on the confirm screen and again server-side if you retry, so a sweeper bot can't just wait for the preview to go stale. (`/docs/agent-abilities`) `[security]`
- **three.ws Avatar MCP clamps unbounded tool arguments before they reach generated HTML**: render_avatar's name and camera-orbit arguments flowed into the generated <model-viewer> HTML with no length bound, unlike the model URL, which already rejected oversized or unsafe values. Both are now clamped the same way, closing the one argument path that could still balloon a rendered page or chat payload. `[fix, security, sdk]`
+- **x402 agent buyers now pay v1 sellers, not just v2**: Every buyer path, the hosted a2a-hire/pay_and_call flow, the packages/x402-mcp stdio server, and the mcp-bridge stdio client, registered only x402's newer CAIP-2 wire format (network strings like solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp). Most of the open x402 bazaar, and every service in the owner's x402-suite, still speaks v1 (flat network strings like solana, price field maxAmountRequired), so agents paying through three.ws could not reach those sellers at all. All three buyers now call registerExactSvmScheme() instead, which registers both wire formats on the same Solana key; when a seller advertises both, v2 is always preferred. Settlement receipts already share field names (success, transaction, network, payer) across both versions, so /receipts and the session ledger need no changes. Fixing this also surfaced two real spend-cap bugs that only trigger on a v1 payment: the hosted buyer's enforceCap threw instead of admitting a capped v1 payment, and mcp-bridge's spending-cap hook silently read a v1 payment's price as zero, bypassing both the per-call and session ceilings. Both are fixed and covered by regression tests. (`/docs/mcp-agent`) `[feature, security]`
## 2026-10-13
diff --git a/api/_lib/x402-spending-cap.js b/api/_lib/x402-spending-cap.js
index 4c95beb32..d8f1e170b 100644
--- a/api/_lib/x402-spending-cap.js
+++ b/api/_lib/x402-spending-cap.js
@@ -85,11 +85,16 @@ function normalizeOpts(input = {}) {
// undo a strict-mode reserve without re-fetching from Redis.
export async function enforceCap({ requirement, opts }) {
const settings = normalizeOpts(opts);
- if (!requirement || !requirement.amount) {
+ // v2 requirements name the price `amount`; v1 requirements (still spoken by
+ // most of the open x402 bazaar and the owner's x402-suite) name it
+ // `maxAmountRequired`. Without this fallback every v1 payment threw here
+ // instead of being admitted and capped.
+ const amount = requirement?.amount ?? requirement?.maxAmountRequired;
+ if (!requirement || !amount) {
throw new Error('spending-cap: requirement.amount required');
}
- const microUsd = await toMicroUsd(requirement.amount, requirement);
+ const microUsd = await toMicroUsd(amount, requirement);
if (settings.maxPerCall != null && microUsd > settings.maxPerCall) {
return {
diff --git a/api/_lib/x402-user-payer.js b/api/_lib/x402-user-payer.js
index 2ab0d5c39..52838f23e 100644
--- a/api/_lib/x402-user-payer.js
+++ b/api/_lib/x402-user-payer.js
@@ -9,6 +9,13 @@
// install the platform spending cap (enforceCap → commit / rollback), and let
// @x402/axios run the full 402 → sign → settle dance.
//
+// registerExactSvmScheme() wires BOTH wire formats on the same client: v2's
+// CAIP-2 `solana:*` wildcard and v1's flat network strings (`solana`,
+// `solana-devnet`, `solana-testnet`), the format most of the open x402 bazaar
+// and the owner's x402-suite still speak. @x402/core's x402HTTPClient already
+// prefers the v2 `PAYMENT-REQUIRED` header over a v1-shaped JSON body when a
+// seller advertises both, so no extra selection logic is needed here.
+//
// SAFETY: spending is OFF unless THREEWS_AGENT_PAY_ENABLED=1. This is real money
// moving from a real user wallet; the flag exists so the capability ships dark
// and is only enabled after a funded-wallet integration test. When disabled,
@@ -158,7 +165,7 @@ async function buildUserPayingClient({ wallet, userId, maxPerCallOverride }) {
{ default: axios },
{ x402Client, x402HTTPClient },
{ wrapAxiosWithPayment },
- { ExactSvmScheme },
+ { registerExactSvmScheme },
{ createKeyPairSignerFromBytes },
] = await Promise.all([
import('axios'),
@@ -176,7 +183,7 @@ async function buildUserPayingClient({ wallet, userId, maxPerCallOverride }) {
const svmSigner = await createKeyPairSignerFromBytes(keypair.secretKey);
const client = new x402Client();
- client.register('solana:*', new ExactSvmScheme(svmSigner));
+ registerExactSvmScheme(client, { signer: svmSigner });
const envPerCall = envAtomic('X402_MAX_PER_CALL_ATOMIC', DEFAULT_MAX_PER_CALL);
const perCall =
diff --git a/data/changelog.json b/data/changelog.json
index 9c05bba4e..d33749e8b 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,16 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-10-14",
+ "title": "x402 agent buyers now pay v1 sellers, not just v2",
+ "summary": "Every buyer path, the hosted a2a-hire/pay_and_call flow, the packages/x402-mcp stdio server, and the mcp-bridge stdio client, registered only x402's newer CAIP-2 wire format (network strings like solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp). Most of the open x402 bazaar, and every service in the owner's x402-suite, still speaks v1 (flat network strings like solana, price field maxAmountRequired), so agents paying through three.ws could not reach those sellers at all. All three buyers now call registerExactSvmScheme() instead, which registers both wire formats on the same Solana key; when a seller advertises both, v2 is always preferred. Settlement receipts already share field names (success, transaction, network, payer) across both versions, so /receipts and the session ledger need no changes. Fixing this also surfaced two real spend-cap bugs that only trigger on a v1 payment: the hosted buyer's enforceCap threw instead of admitting a capped v1 payment, and mcp-bridge's spending-cap hook silently read a v1 payment's price as zero, bypassing both the per-call and session ceilings. Both are fixed and covered by regression tests.",
+ "tags": [
+ "feature",
+ "security"
+ ],
+ "link": "/docs/mcp-agent"
+ },
{
"date": "2026-10-14",
"title": "8 keyless live-data services join the x402 paid API: weather, grid carbon, domains, research, books, news, transit, places",
diff --git a/docs/mcp-agent.md b/docs/mcp-agent.md
index 2099a2979..515868d15 100644
--- a/docs/mcp-agent.md
+++ b/docs/mcp-agent.md
@@ -266,8 +266,15 @@ transactions:
1. Resolve the signed-in user's primary agent wallet (`agent_identities`, Solana).
2. Recover the keypair (`recoverSolanaAgentKeypair`) and build an `x402Client`
- with `ExactSvmScheme`.
-3. Install the platform spending cap (`enforceCap → commit / rollback`).
+ with `registerExactSvmScheme`, which registers both x402 wire formats on
+ the Solana scheme: v2 (`solana:*`, CAIP-2) and v1 (`solana`,
+ `solana-devnet`, `solana-testnet`), the format most of the open x402
+ bazaar, including the owner's `x402-suite`, still speaks. When a seller
+ advertises both, v2 is always preferred; settlement receipts come back in
+ the same shape (`success`, `transaction`, `network`, `payer`) either way.
+3. Install the platform spending cap (`enforceCap → commit / rollback`),
+ which reads either `amount` (v2) or `maxAmountRequired` (v1) so both
+ protocol versions are capped the same way.
4. `wrapAxiosWithPayment` runs the 402 → sign → retry → settle dance.
Per-call/hour/day caps come from `X402_MAX_PER_CALL_ATOMIC`,
diff --git a/mcp-bridge/README.md b/mcp-bridge/README.md
index 40af2b9a8..213c8da1a 100644
--- a/mcp-bridge/README.md
+++ b/mcp-bridge/README.md
@@ -100,7 +100,7 @@ Payment paths registered on the buyer client:
- `eip155:*` → `BatchSettlementEvmScheme` (preferred when the server advertises it; voucher-based, no per-call gas)
- `eip155:*` → `ExactEvmScheme` (used when the server advertises `scheme: "exact"`)
-- `solana:*` → `ExactSvmScheme` (USDC SPL transfer co-signed by the advertised fee payer)
+- `solana:*` and the x402 v1 Solana networks (`solana`, `solana-devnet`, `solana-testnet`) → `ExactSvmScheme` / `ExactSvmSchemeV1` (USDC SPL transfer co-signed by the advertised fee payer), registered together by `registerExactSvmScheme()`. v1 is the wire format most of the open x402 bazaar still speaks; the client always prefers v2 when a seller advertises both. The spending-cap hook reads either `amount` (v2) or `maxAmountRequired` (v1) so both are capped the same way.
Batch-settlement channel state is persisted to `~/.x402-mcp-bridge/channels/client/` so client restarts do not re-deposit on the next call.
diff --git a/mcp-bridge/src/x402-axios-client.js b/mcp-bridge/src/x402-axios-client.js
index 54d74d7da..afde9feea 100644
--- a/mcp-bridge/src/x402-axios-client.js
+++ b/mcp-bridge/src/x402-axios-client.js
@@ -4,7 +4,11 @@
// - eip155:* → BatchSettlementEvmScheme (cheaper per-call, channel-backed)
// - eip155:* → ExactEvmScheme (used when a server doesn't advertise
// batch-settlement for the network)
-// - solana:* → ExactSvmScheme (USDC SPL transfers, fee-payer co-signed)
+// - solana:* and the v1 Solana network strings (`solana`, `solana-devnet`,
+// `solana-testnet`) → ExactSvmScheme / ExactSvmSchemeV1, both registered in
+// one call by registerExactSvmScheme(). Most of the open x402 bazaar and
+// the owner's x402-suite still speak v1; the core client prefers the v2
+// `PAYMENT-REQUIRED` header over a v1 body whenever a seller offers both.
//
// The @x402 core client picks scheme-per-network based on what the 402
// response advertises in `accepts[].scheme`, so registering both EVM schemes
@@ -13,8 +17,9 @@
//
// Spend controls: `onBeforePaymentCreation` aborts payload creation when any
// of these is violated:
-// - per-call: selected accept's `amount` exceeds
-// MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC (default 100_000 = $0.10)
+// - per-call: selected accept's `amount` (v2) or `maxAmountRequired` (v1)
+// exceeds MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC (default
+// 100_000 = $0.10)
// - session: cumulative atomic spent this process would exceed
// MCP_BRIDGE_MAX_TOTAL_ATOMIC (default 1_000_000 = $1.00)
// - payee: selected `payTo` not in MCP_BRIDGE_ALLOWED_PAYTO (when set)
@@ -31,7 +36,7 @@ import { BatchSettlementEvmScheme } from '@x402/evm/batch-settlement/client';
// @x402/evm >= 2.14 moved the Node file-backed storage to its own subpath so
// the main client entry stays runtime-agnostic.
import { FileClientChannelStorage } from '@x402/evm/batch-settlement/client/file-storage';
-import { ExactSvmScheme } from '@x402/svm/exact/client';
+import { registerExactSvmScheme } from '@x402/svm/exact/client';
import { getEvmSigner, getSvmSigner } from './signers.js';
import { getChannelsDirectory } from './storage.js';
@@ -88,7 +93,12 @@ export function buildSpendingCapHook() {
const totalCap = maxTotalAtomic();
const payToAllow = allowedPayTo();
return async ({ selectedRequirements }) => {
- const amount = BigInt(selectedRequirements?.amount ?? '0');
+ // v2 requirements name the price `amount`; v1 requirements (still spoken
+ // by most of the open x402 bazaar and the owner's x402-suite) name it
+ // `maxAmountRequired`. Fall back so a v1 payment is capped too, instead
+ // of silently reading as 0 and bypassing both the per-call and session
+ // ceilings.
+ const amount = BigInt(selectedRequirements?.amount ?? selectedRequirements?.maxAmountRequired ?? '0');
const network = selectedRequirements?.network;
const asset = selectedRequirements?.asset;
const payTo = selectedRequirements?.payTo;
@@ -161,7 +171,7 @@ export async function buildBuyerAxios() {
const svmSigner = await getSvmSigner();
if (svmSigner) {
- client.register('solana:*', new ExactSvmScheme(svmSigner));
+ registerExactSvmScheme(client, { signer: svmSigner });
}
if (!evmSigner && !svmSigner) {
diff --git a/mcp-bridge/tests/spending-cap-v1.test.mjs b/mcp-bridge/tests/spending-cap-v1.test.mjs
new file mode 100644
index 000000000..1f9f4a4a9
--- /dev/null
+++ b/mcp-bridge/tests/spending-cap-v1.test.mjs
@@ -0,0 +1,80 @@
+// Regression test: buildSpendingCapHook must enforce the per-call cap against
+// a v1 x402 requirement too, not just v2.
+//
+// v2 requirements name the price `amount`; v1 requirements (the wire format
+// most of the open x402 bazaar and the owner's x402-suite still speak) name
+// it `maxAmountRequired`. Before this fix the hook only ever read
+// `selectedRequirements?.amount`, which is `undefined` on a v1 requirement:
+// `BigInt(undefined ?? '0')` silently resolved to 0, so a v1 payment of ANY
+// size passed the per-call and session caps for free. This is a real
+// spend-cap bypass once v1 sellers are registered, not a cosmetic bug.
+//
+// All addresses/assets are clearly-synthetic placeholders, no real mints or
+// wallets appear in fixtures.
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { buildSpendingCapHook } from '../src/x402-axios-client.js';
+
+const SYNTH_ASSET_SOLANA = 'THREEsynthetic1111111111111111111111111111';
+const SYNTH_PAYEE_SOLANA = 'THREEsynthetic2222222222222222222222222222';
+
+async function withEnv(overrides, fn) {
+ const saved = {};
+ for (const k of Object.keys(overrides)) {
+ saved[k] = process.env[k];
+ if (overrides[k] === undefined) delete process.env[k];
+ else process.env[k] = overrides[k];
+ }
+ try {
+ return await fn();
+ } finally {
+ for (const k of Object.keys(overrides)) {
+ if (saved[k] === undefined) delete process.env[k];
+ else process.env[k] = saved[k];
+ }
+ }
+}
+
+const BASE_ENV = {
+ MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC: undefined,
+ MCP_BRIDGE_MAX_TOTAL_ATOMIC: undefined,
+ MCP_BRIDGE_ALLOWED_PAYTO: undefined,
+};
+
+test('spending-cap hook: v1 requirements (maxAmountRequired) are capped like v2', async () => {
+ await withEnv(BASE_ENV, async () => {
+ const hook = buildSpendingCapHook();
+ // A v1-shaped selected requirement: flat network string, no `amount`
+ // field at all, price carried in `maxAmountRequired` instead. Far above
+ // the default $0.10 per-call cap (100_000 atomic).
+ const verdict = await hook({
+ selectedRequirements: {
+ scheme: 'exact',
+ network: 'solana',
+ maxAmountRequired: '5000000',
+ asset: SYNTH_ASSET_SOLANA,
+ payTo: SYNTH_PAYEE_SOLANA,
+ },
+ });
+ assert.equal(verdict?.abort, true, 'an over-cap v1 payment must be refused, not silently treated as free');
+ assert.match(verdict.reason, /exceeds per-call cap/);
+ });
+});
+
+test('spending-cap hook: a v1 requirement within cap is still accepted', async () => {
+ await withEnv(BASE_ENV, async () => {
+ const hook = buildSpendingCapHook();
+ const verdict = await hook({
+ selectedRequirements: {
+ scheme: 'exact',
+ network: 'solana',
+ maxAmountRequired: '1000',
+ asset: SYNTH_ASSET_SOLANA,
+ payTo: SYNTH_PAYEE_SOLANA,
+ },
+ });
+ assert.equal(verdict, undefined, 'an in-cap v1 payment must be allowed');
+ });
+});
diff --git a/packages/x402-mcp/README.md b/packages/x402-mcp/README.md
index 71f05fb41..3225c21ee 100644
--- a/packages/x402-mcp/README.md
+++ b/packages/x402-mcp/README.md
@@ -121,6 +121,10 @@ Both spawn this server over stdio and hit the real bazaar. Neither reads a key o
calls `pay_and_call`, so nothing is signed and nothing is spent. See
[`examples/README.md`](./examples/README.md) for expected output.
+## Protocol versions
+
+`pay_and_call` speaks both x402 wire formats on the same Solana key: v2 (CAIP-2 network strings, e.g. `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`) and v1 (flat network strings, e.g. `solana`), the format most of the open x402 bazaar, and services built on the original `x402`/`x402-fetch` packages, still speak. When a seller advertises both, v2 is always preferred. Settlement receipts come back in the same shape (`success`, `transaction`, `network`, `payer`) regardless of which version paid, so nothing downstream needs to know which one was used.
+
## Requirements
- **Node.js >= 20.**
diff --git a/packages/x402-mcp/src/lib/x402-buyer.js b/packages/x402-mcp/src/lib/x402-buyer.js
index 1cbcabca1..b9d03e76c 100644
--- a/packages/x402-mcp/src/lib/x402-buyer.js
+++ b/packages/x402-mcp/src/lib/x402-buyer.js
@@ -6,9 +6,14 @@
// 402 dance and sign the Solana `exact`-scheme payment — nothing is mocked.
//
// The flow:
-// 1. x402Client + ExactSvmScheme(signer) registered for solana:*
+// 1. x402Client + registerExactSvmScheme(client, { signer }) registers BOTH
+// wire formats: v2's CAIP-2 `solana:*` wildcard and v1's flat network
+// strings (`solana`, `solana-devnet`, `solana-testnet`), the format
+// most of the open x402 bazaar and the owner's x402-suite still speak.
// 2. wrapFetchWithPayment(fetch, client) → a fetch that, on a 402, signs and
// retries with the X-PAYMENT header, then exposes the settlement response.
+// @x402/core prefers the v2 `PAYMENT-REQUIRED` header over a v1-shaped
+// body whenever a seller advertises both.
import bs58 from 'bs58';
@@ -119,14 +124,14 @@ export async function getSigner(secretOverride) {
* @returns {Promise<{ payingFetch: typeof fetch, httpClient: any, address: string }>}
*/
export async function buildPayingFetch(secretOverride, opts = {}) {
- const [{ x402Client, x402HTTPClient }, { ExactSvmScheme }, { wrapFetchWithPayment }] = await Promise.all([
+ const [{ x402Client, x402HTTPClient }, { registerExactSvmScheme }, { wrapFetchWithPayment }] = await Promise.all([
import('@x402/core/client'),
import('@x402/svm/exact/client'),
import('@x402/fetch'),
]);
const signer = await getSigner(secretOverride);
const client = new x402Client();
- client.register('solana:*', new ExactSvmScheme(signer));
+ registerExactSvmScheme(client, { signer });
const httpClient = new x402HTTPClient(client);
const baseFetch = opts.preferToken ? makeTokenFilteringFetch(opts.preferToken) : globalThis.fetch;
const payingFetch = wrapFetchWithPayment(baseFetch, client);
diff --git a/packages/x402-mcp/test/x402-v1-buyer.test.mjs b/packages/x402-mcp/test/x402-v1-buyer.test.mjs
new file mode 100644
index 000000000..8a301312f
--- /dev/null
+++ b/packages/x402-mcp/test/x402-v1-buyer.test.mjs
@@ -0,0 +1,154 @@
+// integrate 18: let three.ws agents pay x402 v1 sellers.
+//
+// Most of the open x402 bazaar, and every service in the owner's x402-suite,
+// still speaks x402 v1 (`x402Version: 1`, flat network strings like
+// `"solana"`, price field `maxAmountRequired`) rather than v2's CAIP-2
+// network strings and `amount` field. buildPayingFetch() registers both wire
+// formats on the same client via registerExactSvmScheme() (see
+// ../src/lib/x402-buyer.js). These tests exercise the real @x402/core /
+// @x402/svm SDK classes directly, no reimplementation of their selection or
+// header-precedence logic, against a captured v1 402 shape and a
+// dual-version offer, with no network call and no signing.
+//
+// The v1 402 body below mirrors, field for field, the real shape the owner's
+// x402-domains service (an x402-suite member, read from its
+// src/payments.ts `challenge()`/`buildAccepts()` functions) sends on an
+// unpaid request. `payTo`/`asset` are replaced with the $THREE mint and
+// clearly-synthetic placeholders, never a real third-party wallet or mint.
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { x402Client, x402HTTPClient } from '@x402/core/client';
+import { encodePaymentRequiredHeader } from '@x402/core/http';
+import { registerExactSvmScheme } from '@x402/svm/exact/client';
+import { generateKeyPairSigner } from '@solana/kit';
+
+const THREE_MINT = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
+const SYNTH_PAYTO = 'THREEsynthetic1111111111111111111111111111';
+const SYNTH_FEE_PAYER = 'THREEsynthetic3333333333333333333333333333';
+
+// A captured v1 402 challenge body, shaped exactly like a real x402-suite
+// service's unpaid response (x402Version: 1, flat `network`,
+// `maxAmountRequired`, `resource` as a bare URL string).
+function capturedV1Body() {
+ return {
+ x402Version: 1,
+ error: 'X-PAYMENT header is required',
+ accepts: [
+ {
+ scheme: 'exact',
+ network: 'solana',
+ maxAmountRequired: '10000',
+ resource: 'https://example.invalid/v1/lookup',
+ description: 'Example x402-suite style paid lookup',
+ mimeType: 'application/json',
+ payTo: SYNTH_PAYTO,
+ maxTimeoutSeconds: 60,
+ asset: THREE_MINT,
+ extra: { name: 'THREE', decimals: 6, feePayer: SYNTH_FEE_PAYER },
+ },
+ ],
+ };
+}
+
+// The same offer restated in v2 shape (CAIP-2 network, `amount` instead of
+// `maxAmountRequired`, structured `resource`).
+function capturedV2Required() {
+ return {
+ x402Version: 2,
+ resource: { url: 'https://example.invalid/v2/lookup' },
+ accepts: [
+ {
+ scheme: 'exact',
+ network: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+ amount: '10000',
+ asset: THREE_MINT,
+ payTo: SYNTH_PAYTO,
+ maxTimeoutSeconds: 60,
+ extra: { name: 'THREE', decimals: 6, feePayer: SYNTH_FEE_PAYER },
+ },
+ ],
+ };
+}
+
+async function buildRegisteredClient() {
+ const signer = await generateKeyPairSigner();
+ const client = new x402Client();
+ // These tests exercise protocol-version selection, not the asset
+ // allowlist (default spend controls only allow USDC/the scheme's default
+ // assets, and $THREE is neither here).
+ client.setSpendControls(false);
+ registerExactSvmScheme(client, { signer });
+ return client;
+}
+
+test('v1 402 body: requirement selection returns a valid v1 requirement without signing', async () => {
+ const client = await buildRegisteredClient();
+ const body = capturedV1Body();
+
+ const selected = client.selectPaymentRequirements(1, body.accepts);
+
+ assert.equal(selected.scheme, 'exact');
+ assert.equal(selected.network, 'solana');
+ assert.equal(selected.maxAmountRequired, '10000');
+ assert.equal(selected.asset, THREE_MINT);
+ assert.equal(selected.payTo, SYNTH_PAYTO);
+ // Selection is pure accept-picking: no payload, no signature, nothing
+ // signer-shaped on the result.
+ assert.equal('payload' in selected, false);
+ assert.equal('signature' in selected, false);
+});
+
+test('v2 is preferred over v1 when a seller offers both', async () => {
+ const client = await buildRegisteredClient();
+ const httpClient = new x402HTTPClient(client);
+
+ const v1Body = capturedV1Body();
+ const v2Required = capturedV2Required();
+ // A dual-version seller sends the v2 `PAYMENT-REQUIRED` header AND a
+ // v1-shaped JSON body for legacy buyers. getPaymentRequiredResponse() must
+ // pick the header (v2) over the body (v1): this is the real SDK's own
+ // precedence, not reimplemented here.
+ const headers = { 'payment-required': encodePaymentRequiredHeader(v2Required) };
+ const getHeader = (name) => headers[name.toLowerCase()];
+
+ const paymentRequired = httpClient.getPaymentRequiredResponse(getHeader, v1Body);
+ assert.equal(paymentRequired.x402Version, 2, 'the v2 header must win over the v1 body fallback');
+
+ const selected = client.selectPaymentRequirements(paymentRequired.x402Version, paymentRequired.accepts);
+ assert.equal(selected.network, 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp');
+ assert.equal(selected.amount, '10000');
+});
+
+test('v1 and v2 settlement receipts expose the same field names (no normalization needed)', async () => {
+ // Task 3: /receipts and the session ledger must not care which protocol
+ // version paid. Both the real @x402/svm v1 facilitator's settle() output
+ // and the v2 scheme's settlement responses use the SAME field names
+ // (success, transaction, network, payer) -- confirmed by reading
+ // @x402/svm's exact/v1/facilitator source. getPaymentSettleResponse() does
+ // no version-specific decoding; it just base64-decodes whichever
+ // settlement header is present, so a v1 receipt already arrives in the
+ // shape every downstream reader (api/agents/a2a-hire.js's
+ // receiptSignature(), /api/x402/my-receipts.js) expects.
+ const client = await buildRegisteredClient();
+ const httpClient = new x402HTTPClient(client);
+
+ const v1Receipt = { success: true, transaction: 'sig-v1-example', network: 'solana', payer: SYNTH_PAYTO };
+ const v2Receipt = { success: true, transaction: 'sig-v2-example', network: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp', payer: SYNTH_PAYTO };
+
+ const { encodePaymentResponseHeader } = await import('@x402/core/http');
+ const decodedV1 = httpClient.getPaymentSettleResponse(
+ (name) => (name.toLowerCase() === 'x-payment-response' ? encodePaymentResponseHeader(v1Receipt) : undefined),
+ );
+ const decodedV2 = httpClient.getPaymentSettleResponse(
+ (name) => (name.toLowerCase() === 'payment-response' ? encodePaymentResponseHeader(v2Receipt) : undefined),
+ );
+
+ for (const receipt of [decodedV1, decodedV2]) {
+ assert.equal(typeof receipt.success, 'boolean');
+ assert.equal(typeof receipt.transaction, 'string');
+ assert.equal(typeof receipt.network, 'string');
+ assert.equal(typeof receipt.payer, 'string');
+ }
+});
diff --git a/public/changelog-recent.json b/public/changelog-recent.json
index 5d481a9ac..19ffdcfee 100644
--- a/public/changelog-recent.json
+++ b/public/changelog-recent.json
@@ -1,11 +1,11 @@
{
- "generated_at": "2026-10-14T23:21:31.804Z",
+ "generated_at": "2026-10-14T23:56:00.129Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
"url": "https://three.ws"
},
- "total": 4095,
+ "total": 4096,
"complete": false,
"full_feed": "/changelog.json",
"entries": [
@@ -190,6 +190,17 @@
"sdk"
]
},
+ {
+ "date": "2026-10-14",
+ "type": "update",
+ "title": "x402 agent buyers now pay v1 sellers, not just v2",
+ "summary": "Every buyer path, the hosted a2a-hire/pay_and_call flow, the packages/x402-mcp stdio server, and the mcp-bridge stdio client, registered only x402's newer CAIP-2 wire format (network strings like solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp). Most of the open x402 bazaar, and every service in the owner's x402-suite, still speaks v1 (flat network strings like solana, price field maxAmountRequired), so agents paying through three.ws could not reach those sellers at all. All three buyers now call registerExactSvmScheme() instead, which registers both wire formats on the same Solana key; when a seller advertises both, v2 is always preferred. Settlement receipts already share field names (success, transaction, network, payer) across both versions, so /receipts and the session ledger need no changes. Fixing this also surfaced two real spend-cap bugs that only trigger on a v1 payment: the hosted buyer's enforceCap threw instead of admitting a capped v1 payment, and mcp-bridge's spending-cap hook silently read a v1 payment's price as zero, bypassing both the per-call and session ceilings. Both are fixed and covered by regression tests.",
+ "link": "/docs/mcp-agent",
+ "tags": [
+ "feature",
+ "security"
+ ]
+ },
{
"date": "2026-10-13",
"type": "launch",
@@ -1546,16 +1557,6 @@
"feature",
"sdk"
]
- },
- {
- "date": "2026-10-10",
- "type": "update",
- "title": "Agents can find and register web domains",
- "summary": "Search any name across popular extensions with live availability and the exact yearly price, check a single name, and register it from your credits after a quote and an explicit yes. Coin pages now suggest available domains for the project name, and a registered domain can serve your agent's public page. Registration is for one year, renews at the same price, and has no markup.",
- "link": "/domains",
- "tags": [
- "feature"
- ]
}
]
}
diff --git a/public/changelog.json b/public/changelog.json
index f7c5ad85d..5c0fab5c0 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-10-14T23:21:31.782Z",
+ "generated_at": "2026-10-14T23:56:00.107Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
@@ -187,6 +187,17 @@
"sdk"
]
},
+ {
+ "date": "2026-10-14",
+ "type": "update",
+ "title": "x402 agent buyers now pay v1 sellers, not just v2",
+ "summary": "Every buyer path, the hosted a2a-hire/pay_and_call flow, the packages/x402-mcp stdio server, and the mcp-bridge stdio client, registered only x402's newer CAIP-2 wire format (network strings like solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp). Most of the open x402 bazaar, and every service in the owner's x402-suite, still speaks v1 (flat network strings like solana, price field maxAmountRequired), so agents paying through three.ws could not reach those sellers at all. All three buyers now call registerExactSvmScheme() instead, which registers both wire formats on the same Solana key; when a seller advertises both, v2 is always preferred. Settlement receipts already share field names (success, transaction, network, payer) across both versions, so /receipts and the session ledger need no changes. Fixing this also surfaced two real spend-cap bugs that only trigger on a v1 payment: the hosted buyer's enforceCap threw instead of admitting a capped v1 payment, and mcp-bridge's spending-cap hook silently read a v1 payment's price as zero, bypassing both the per-call and session ceilings. Both are fixed and covered by regression tests.",
+ "link": "/docs/mcp-agent",
+ "tags": [
+ "feature",
+ "security"
+ ]
+ },
{
"date": "2026-10-13",
"type": "launch",
diff --git a/public/changelog.xml b/public/changelog.xml
index 3a4fd0f09..90743310e 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -142,6 +142,14 @@
<category>fix</category>
<description>render_avatar's name and camera-orbit arguments flowed into the generated &lt;model-viewer&gt; HTML with no length bound, unlike the model URL, which already rejected oversized or unsafe values. Both are now clamped the same way, closing the one argument path that could still balloon a rendered page or chat payload.</description>
</item>
+ <item>
+ <title>x402 agent buyers now pay v1 sellers, not just v2</title>
+ <link>https://three.ws/docs/mcp-agent</link>
+ <guid isPermaLink="false">2026-10-14:x402 agent buyers now pay v1 sellers, not just v2</guid>
+ <pubDate>Wed, 14 Oct 2026 12:00:00 GMT</pubDate>
+ <category>feature</category>
+ <description>Every buyer path, the hosted a2a-hire/pay_and_call flow, the packages/x402-mcp stdio server, and the mcp-bridge stdio client, registered only x402's newer CAIP-2 wire format (network strings like solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp). Most of the open x402 bazaar, and every service in the owner's x402-suite, still speaks v1 (flat network strings like solana, price field maxAmountRequired), so agents paying through three.ws could not reach those sellers at all. All three buyers now call registerExactSvmScheme() instead, which registers both wire formats on the same Solana key; when a seller advertises both, v2 is always preferred. Settlement receipts already share field names (success, transaction, network, payer) across both versions, so /receipts and the session ledger need no changes. Fixing this also surfaced two real spend-cap bugs that only trigger on a v1 payment: the hosted buyer's enforceCap threw instead of admitting a capped v1 payment, and mcp-bridge's spending-cap hook silently read a v1 payment's price as zero, bypassing both the per-call and session ceilings. Both are fixed and covered by regression tests.</description>
+ </item>
<item>
<title>Docs · Staked Event Markets</title>
<link>https://three.ws/docs/event-markets-staking</link>
diff --git a/public/features.json b/public/features.json
index d5a66e919..18498ca78 100644
--- a/public/features.json
+++ b/public/features.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-10-14T23:21:31.769Z",
+ "generated_at": "2026-10-14T23:56:00.094Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json",
"site": {
"name": "three.ws",
diff --git a/tests/x402-spending-cap-v1-amount.test.js b/tests/x402-spending-cap-v1-amount.test.js
new file mode 100644
index 000000000..45afc360d
--- /dev/null
+++ b/tests/x402-spending-cap-v1-amount.test.js
@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest';
+import { Keypair } from '@solana/web3.js';
+
+// enforceCap() required `requirement.amount`, which is the v2 field name.
+// A v1 payment requirement (the wire format most of the open x402 bazaar and
+// the owner's x402-suite still speak) carries the price in
+// `maxAmountRequired` instead, so every v1 payment hit
+// "spending-cap: requirement.amount required" and could never be admitted at
+// all, defeating the point of registering v1 support in the buyer. This test
+// reproduces that, then (after the fix) proves a v1 requirement is admitted
+// and capped exactly like a v2 one.
+
+const { enforceCap } = await import('../api/_lib/x402-spending-cap.js');
+
+const USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
+const address = Keypair.generate().publicKey.toBase58();
+
+function v1Requirement(maxAmountRequired) {
+ return {
+ scheme: 'exact',
+ network: 'solana',
+ maxAmountRequired,
+ asset: USDC,
+ payTo: Keypair.generate().publicKey.toBase58(),
+ maxTimeoutSeconds: 60,
+ extra: { name: 'USDC', decimals: 6 },
+ };
+}
+
+describe('enforceCap: v1 requirements (maxAmountRequired)', () => {
+ it('admits an in-cap v1 payment instead of throwing on the missing `amount` field', async () => {
+ const res = await enforceCap({
+ requirement: v1Requirement('1000'), // $0.001 USDC, well under the per-call cap
+ opts: { address, maxPerCall: '100000', strict: false },
+ });
+ expect(res.abort).toBe(false);
+ });
+
+ it('still refuses an over-cap v1 payment (the cap is enforced, not bypassed)', async () => {
+ const res = await enforceCap({
+ requirement: v1Requirement('5000000'), // $5.00 USDC, far over the cap
+ opts: { address, maxPerCall: '100000', strict: false },
+ });
+ expect(res.abort).toBe(true);
+ expect(res.reason).toMatch(/exceeds per-call cap/);
+ });
+});