refactor(x402)!: drop flat back-compat fields from _meta.x402 (#1458)

## Why

Closes #892.

`_meta.x402` on paid tools currently carries the same payment data
twice: the spec-shaped `accepts[]` array and a flat copy of the
server-preferred entry (`scheme`, `network`, `amount`, ...). The flat
copy was a shim for clients from before #876 that don't iterate
`accepts[]`. Two shapes invite drift, and the flat one can't express
more than one scheme.

Consumer check before removing it:
- `apify/mcpc` (v0.7.0, main a8c34fc): `selectAcceptFromToolMeta` walks
`accepts[]` first and uses the flat fields only when `accepts[]` is
absent; if that fails too it defers to the 402 response. PR
apify/mcpc#238 merged 2026-05-26.
- `apify/agentic-payments-e2e-tester` x402 canary: reads `accepts[]`
first, flat shape is a legacy fallback.
- Third-party clients: none on file, not verifiable from here.

## What changed

Before: `_meta.x402 = { paymentRequired, ...preferredEntry, accepts }`.
Now: `_meta.x402 = { paymentRequired, accepts }`.

`selectPreferredAcceptEntry` and `X402_PREFERRED_SCHEMES` are deleted
with it. `accepts[]`, the `structuredContent` in 402 results and `upto`
support are untouched.

## Notes for reviewers (human-written)

## Proof it works

Unit: `tests/unit/tools.x402.test.ts` asserts `_meta.x402` equals
exactly `{ paymentRequired: true, accepts: [...] }`. The
`tests/test_kit` payments case no longer expects the flat fields.
Type-check and lint clean. No end-to-end mcpc transcript yet.

Author: MQ37

src/payments/x402.ts

@@ -26,16 +26,6 @@ const X402_TOOL_INSTRUCTIONS = [
     'Your MCP client must support the x402 payment protocol.',
 ].join(' ');
 
-/**
- * Preferred scheme order when selecting the flat fields exposed on `_meta.x402`.
- *
- * `exact` first to keep the flat-fields contract back-compatible with clients
- * that don't iterate `accepts[]` — they continue to sign `exact` payments as
- * before this PR. Clients that walk `accepts[]` (post-#876 — the current
- * mcpc, the canary) can opt into `upto` via their scheme preference.
- */
-const X402_PREFERRED_SCHEMES = ['exact', 'upto'] as const;
-
 /**
  * One entry in a 402 `accepts` array. Mirrors the public x402 v2 wire shape;
  * carried verbatim from the Apify API.
@@ -223,25 +213,11 @@ export class X402PaymentProvider implements PaymentProvider {
         return new X402PaymentProvider(requirements);
     }
 
-    /**
-     * Picks the preferred accept entry for flat `_meta.x402` advertising.
-     * Order follows `X402_PREFERRED_SCHEMES`; falls back to the first entry
-     * when no preferred scheme matches.
-     */
-    private selectPreferredAcceptEntry(accepts: X402PaymentAccept[]): X402PaymentAccept {
-        for (const preferred of X402_PREFERRED_SCHEMES) {
-            const match = accepts.find((entry) => entry.scheme === preferred);
-            if (match) return match;
-        }
-        return accepts[0];
-    }
-
     decorateToolSchema(tool: ToolEntry): ToolEntry {
         if (!tool.paymentRequired) return tool;
 
         const cloned = cloneToolEntry(tool);
 
-        // Flat preferred fields stay for back-compat with clients that don't iterate `accepts[]`.
         if (!cloned._meta) {
             cloned._meta = {};
         }
@@ -250,10 +226,8 @@ export class X402PaymentProvider implements PaymentProvider {
             const reqs = this.requirements ? structuredClone(this.requirements) : undefined;
             const acceptsRaw = reqs?.accepts;
             const accepts = Array.isArray(acceptsRaw) && acceptsRaw.length > 0 ? acceptsRaw : undefined;
-            const preferred = accepts ? this.selectPreferredAcceptEntry(accepts) : undefined;
             metaRecord.x402 = {
                 paymentRequired: true,
-                ...(preferred ?? {}),
                 ...(accepts && { accepts }),
             };
         }

tests/test_kit/cases/payments.cases.ts

@@ -76,8 +76,7 @@ export const paymentsCases: Case[] = [
             try {
                 const toolsList = await client.listTools();
 
-                // Positive: paid tools advertise _meta.x402 with both shapes —
-                // flat preferred-scheme fields (back-compat) and the full accepts[] array.
+                // Positive: paid tools advertise _meta.x402 with the full accepts[] array.
                 for (const toolName of paidToolNames) {
                     const tool = toolsList.tools.find((t) => t.name === toolName);
                     expect(tool, `Tool "${toolName}" should exist in the tools list`).toBeDefined();
@@ -86,10 +85,6 @@ export const paymentsCases: Case[] = [
                     expect(x402, `Tool "${toolName}" should advertise _meta.x402`).toBeDefined();
                     expect(x402?.paymentRequired, `Tool "${toolName}" x402.paymentRequired should be true`).toBe(true);
 
-                    for (const field of ['scheme', 'network', 'asset', 'payTo', 'amount'] as const) {
-                        expect(x402?.[field], `Tool "${toolName}" should advertise x402.${field}`).toBeDefined();
-                    }
-
                     const accepts = x402?.accepts as Record<string, unknown>[] | undefined;
                     expect(accepts, `Tool "${toolName}" should advertise x402.accepts[]`).toBeInstanceOf(Array);
                     expect(

tests/unit/tools.x402.test.ts

@@ -155,56 +155,32 @@ describe('decorateToolSchema()', () => {
         expect(decorated._meta).toBeUndefined();
     });
 
-    it('selects the exact entry over upto for flat fields and exposes both in accepts[]', () => {
-        // Back-compat: clients that read only flat fields keep signing `exact` like before #876.
+    it('exposes every scheme in accepts[] and no flat fields', () => {
         const requirements: X402PaymentRequirements = { x402Version: 2, accepts: [EXACT_ACCEPT, UPTO_ACCEPT] };
         const decorated = new X402PaymentProvider(requirements).decorateToolSchema(makePaidTool());
 
         const x402 = getX402Meta(decorated);
-        expect(x402?.paymentRequired).toBe(true);
-        expect(x402?.scheme).toBe('exact');
-        expect(x402?.amount).toBe(EXACT_ACCEPT.amount);
-        expect(x402?.accepts).toEqual([EXACT_ACCEPT, UPTO_ACCEPT]);
+        expect(x402).toEqual({ paymentRequired: true, accepts: [EXACT_ACCEPT, UPTO_ACCEPT] });
     });
 
-    it('falls back to upto when exact is not present', () => {
-        const requirements: X402PaymentRequirements = { x402Version: 2, accepts: [UPTO_ACCEPT] };
-        const decorated = new X402PaymentProvider(requirements).decorateToolSchema(makePaidTool());
-
-        const x402 = getX402Meta(decorated);
-        expect(x402?.scheme).toBe('upto');
-        expect(x402?.accepts).toEqual([UPTO_ACCEPT]);
-    });
-
-    it('falls back to the first entry when neither exact nor upto is present', () => {
-        const customAccept = { ...EXACT_ACCEPT, scheme: 'custom-scheme' };
-        const requirements: X402PaymentRequirements = { x402Version: 2, accepts: [customAccept] };
-        const decorated = new X402PaymentProvider(requirements).decorateToolSchema(makePaidTool());
-
-        const x402 = getX402Meta(decorated);
-        expect(x402?.scheme).toBe('custom-scheme');
-        expect(x402?.accepts).toEqual([customAccept]);
-    });
-
-    it('preserves the configured order in accepts[] regardless of preference selection', () => {
+    it('preserves the configured order in accepts[]', () => {
         // Server-emitted order may be non-deterministic upstream; whatever we receive is
-        // what we forward. Preference only drives the flat-field selection.
+        // what we forward.
         const requirements: X402PaymentRequirements = { x402Version: 2, accepts: [UPTO_ACCEPT, EXACT_ACCEPT] };
         const decorated = new X402PaymentProvider(requirements).decorateToolSchema(makePaidTool());
 
         const x402 = getX402Meta(decorated);
         expect(x402?.accepts).toEqual([UPTO_ACCEPT, EXACT_ACCEPT]);
-        expect(x402?.scheme).toBe('exact');
     });
 
-    it('marks paymentRequired without flat fields or accepts[] when requirements were not fetched', () => {
+    it('marks paymentRequired without accepts[] when requirements were not fetched', () => {
         const decorated = new X402PaymentProvider(undefined).decorateToolSchema(makePaidTool());
 
         const x402 = getX402Meta(decorated);
         expect(x402).toEqual({ paymentRequired: true });
     });
 
-    it('marks paymentRequired without flat fields or accepts[] when accepts is empty', () => {
+    it('marks paymentRequired without accepts[] when accepts is empty', () => {
         const requirements: X402PaymentRequirements = { x402Version: 2, accepts: [] };
         const decorated = new X402PaymentProvider(requirements).decorateToolSchema(makePaidTool());