agentpay-mcp 4.1.7 → 4.1.10

package/dist/utils/x402-buyer-flow.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createX402IdempotencyKey = createX402IdempotencyKey;
+exports.classifyX402PaymentError = classifyX402PaymentError;
+exports.verifyX402BuyerFlow = verifyX402BuyerFlow;
+const node_crypto_1 = require("node:crypto");
+function normalizeMethod(method) {
+    return method.trim().toUpperCase();
+}
+function createX402IdempotencyKey(input) {
+    const hash = (0, node_crypto_1.createHash)('sha256');
+    hash.update(normalizeMethod(input.method));
+    hash.update('\n');
+    hash.update(input.url.trim());
+    hash.update('\n');
+    hash.update(input.body ?? '');
+    hash.update('\n');
+    hash.update(input.signer.toLowerCase());
+    return hash.digest('hex');
+}
+function parsePositiveAmount(value) {
+    if (typeof value === 'bigint')
+        return value > 0n ? value : null;
+    if (!value || !/^\d+$/.test(value))
+        return null;
+    const parsed = BigInt(value);
+    return parsed > 0n ? parsed : null;
+}
+function isNonZeroEvmAddress(value) {
+    if (!value)
+        return false;
+    const normalized = value.toLowerCase();
+    return /^0x[a-f0-9]{40}$/.test(normalized) && normalized !== '0x0000000000000000000000000000000000000000';
+}
+function parseNonNegativeEnvelopeValue(value) {
+    if (value === undefined)
+        return null;
+    if (typeof value === 'number') {
+        if (!Number.isInteger(value) || value < 0)
+            return null;
+        return BigInt(value);
+    }
+    if (!/^\d+$/.test(value))
+        return null;
+    return BigInt(value);
+}
+function hasQuotaVisibility(quota) {
+    if (!quota)
+        return false;
+    return Boolean(quota.limit !== undefined || quota.remaining !== undefined || quota.resetAt || Object.keys(quota.sourceHeaders ?? {}).length > 0);
+}
+function calculateRemainingAfterPayment(maxSpend, amountRequired) {
+    if (!maxSpend || !amountRequired || amountRequired > maxSpend)
+        return undefined;
+    return (maxSpend - amountRequired).toString();
+}
+function classifyX402PaymentError(error, quota) {
+    if (!error)
+        return 'do_not_retry';
+    switch (error.name) {
+        case 'PaymentRequiredError':
+            return 'retry_after_payment';
+        case 'QuotaExceededError':
+            return hasQuotaVisibility(quota) ? 'retry_after_quota_reset' : 'operator_review';
+        case 'TokenExpiredError':
+            return 'refresh_token_then_retry';
+        case 'ValidationFailureError':
+        case 'SpendLimitExceededError':
+            return 'do_not_retry';
+        case 'UnknownPaymentError':
+        default:
+            return 'operator_review';
+    }
+}
+function verifyX402BuyerFlow(input) {
+    const failures = [];
+    const warnings = [];
+    const expectedIdempotencyKey = createX402IdempotencyKey(input);
+    const maxSpend = parsePositiveAmount(input.maxSpendAtomic);
+    const amountRequired = parsePositiveAmount(input.challenge?.amountRequired);
+    const toolSet = new Set(input.mcpTools);
+    const quotaLimit = parseNonNegativeEnvelopeValue(input.quota?.limit);
+    const quotaRemaining = parseNonNegativeEnvelopeValue(input.quota?.remaining);
+    const quotaVisible = hasQuotaVisibility(input.quota);
+    const retryability = classifyX402PaymentError(input.typedError, input.quota);
+    try {
+        new URL(input.url);
+    }
+    catch {
+        failures.push('Buyer flow URL must be an absolute URL before any payment check runs.');
+    }
+    if (input.challengeSource === 'none') {
+        failures.push('Buyer flow must discover or inspect a 402 challenge before payment.');
+    }
+    if (!input.challenge?.network || !input.allowedNetworks.includes(input.challenge.network)) {
+        failures.push('Challenge network must match the buyer allowlist.');
+    }
+    const asset = input.challenge?.asset?.toLowerCase();
+    const allowedAssets = input.allowedAssets.map((item) => item.toLowerCase());
+    if (!asset || !allowedAssets.includes(asset)) {
+        failures.push('Challenge asset must match the buyer allowlist.');
+    }
+    if (!isNonZeroEvmAddress(input.challenge?.payTo)) {
+        failures.push('Challenge payTo must be a non-zero EVM recipient before signing.');
+    }
+    if (!maxSpend) {
+        failures.push('Buyer flow must set a positive max spend cap.');
+    }
+    if (!amountRequired) {
+        failures.push('Challenge must include a positive amount before dry-run or pay.');
+    }
+    if (maxSpend && amountRequired && amountRequired > maxSpend) {
+        failures.push('Challenge amount exceeds the buyer max spend cap.');
+    }
+    if (!input.dryRunCompleted) {
+        failures.push('Buyer flow must complete a dry-run plan before signing.');
+    }
+    if (input.approvalState !== 'approved' && input.approvalState !== 'not_required') {
+        failures.push(`Buyer flow approval state must be approved or not_required before signing; received ${input.approvalState}.`);
+    }
+    if (input.idempotencyKey && input.idempotencyKey !== expectedIdempotencyKey) {
+        failures.push('Provided idempotency key does not match method, URL, body, and signer.');
+    }
+    if (input.typedError && !input.typedError.noCharge) {
+        failures.push('Typed payment errors must explicitly preserve no-charge failure semantics before retry or operator action.');
+    }
+    if (input.typedError?.name === 'QuotaExceededError' && !quotaVisible) {
+        failures.push('QuotaExceededError must include quota visibility from X-Quota-* headers or an equivalent envelope.');
+    }
+    if (input.typedError?.name === 'TokenExpiredError' && retryability !== 'refresh_token_then_retry') {
+        failures.push('TokenExpiredError must map to refresh_token_then_retry recovery guidance.');
+    }
+    if (input.quota?.limit !== undefined && quotaLimit === null) {
+        failures.push('Quota envelope limit must be a non-negative integer when present.');
+    }
+    if (input.quota?.remaining !== undefined && quotaRemaining === null) {
+        failures.push('Quota envelope remaining must be a non-negative integer when present.');
+    }
+    if (quotaLimit !== null && quotaRemaining !== null && quotaRemaining > quotaLimit) {
+        failures.push('Quota envelope remaining must not exceed quota limit.');
+    }
+    for (const requiredTool of ['x402_pay', 'check_budget', 'set_spend_policy', 'get_transaction_history']) {
+        if (!toolSet.has(requiredTool)) {
+            failures.push(`MCP exposure is missing required AgentPay tool: ${requiredTool}.`);
+        }
+    }
+    if (!toolSet.has('queue_approval')) {
+        warnings.push('queue_approval is not listed. Human approval should be explicit for above-threshold payments.');
+    }
+    if (!input.audit.destination || !input.audit.correlationId || !input.audit.receiptSink) {
+        failures.push('Buyer flow audit must include destination, correlationId, and receiptSink.');
+    }
+    return {
+        ok: failures.length === 0,
+        idempotencyKey: expectedIdempotencyKey,
+        failures,
+        warnings,
+        parity: {
+            discover: input.challengeSource !== 'none',
+            check: Boolean(input.challenge?.network && input.challenge?.asset && input.challenge?.payTo && input.challenge?.amountRequired),
+            dryRun: input.dryRunCompleted,
+            pay: input.approvalState === 'approved' || input.approvalState === 'not_required',
+            spendLimit: Boolean(maxSpend && (!amountRequired || amountRequired <= maxSpend)),
+            idempotency: !input.idempotencyKey || input.idempotencyKey === expectedIdempotencyKey,
+            mcpExposure: ['x402_pay', 'check_budget', 'set_spend_policy', 'get_transaction_history'].every((tool) => toolSet.has(tool)),
+            audit: Boolean(input.audit.destination && input.audit.correlationId && input.audit.receiptSink),
+            typedErrors: Boolean(input.typedError?.name),
+            retryability: Boolean(input.typedError),
+            quotaEnvelope: quotaVisible,
+            noChargeFailures: input.typedError ? input.typedError.noCharge : true,
+        },
+        recovery: {
+            errorName: input.typedError?.name,
+            retryability,
+            noCharge: input.typedError ? input.typedError.noCharge : true,
+            quotaVisible,
+        },
+        envelope: {
+            quota: input.quota,
+            spend: {
+                maxSpendAtomic: maxSpend?.toString() ?? String(input.maxSpendAtomic),
+                amountRequiredAtomic: amountRequired?.toString(),
+                remainingAfterPaymentAtomic: calculateRemainingAfterPayment(maxSpend, amountRequired),
+            },
+        },
+    };
+}
+//# sourceMappingURL=x402-buyer-flow.js.map

package/dist/utils/x402-buyer-flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-buyer-flow.js","sourceRoot":"","sources":["../../src/utils/x402-buyer-flow.ts"],"names":[],"mappings":"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"}

package/dist/utils/x402-v211-compatibility.d.ts

@@ -0,0 +1,29 @@
+/**
+ * x402 v2.11 paid MCP compatibility helpers.
+ *
+ * These helpers keep buyer-facing documentation, tests, and downstream
+ * Streamable HTTP gateways aligned on the same header names and receipt links.
+ */
+export declare const X402_V211_PAYMENT_SIGNATURE_HEADER = "Payment-Signature";
+export declare const X402_V211_DEPRECATED_PAYMENT_HEADERS: string[];
+export declare const X402_V211_RECEIPT_HEADER = "payment-response";
+export declare const X402_V211_MCP_SESSION_HEADER = "mcp-session-id";
+export declare const X402_V211_BROWSER_EXPOSED_HEADERS: string[];
+export type SupportedReceiptChainId = 8453 | 84532;
+export type X402V211CompatibilityProof = {
+    paymentSignatureHeader: typeof X402_V211_PAYMENT_SIGNATURE_HEADER;
+    deprecatedPaymentHeaders: string[];
+    responseHeaders: string[];
+    corsExposeHeaders: string;
+    streamableHttpSequence: string[];
+    supportedReceiptChains: Array<{
+        chainId: SupportedReceiptChainId;
+        name: string;
+        explorerTxBaseUrl: string;
+        x402Network: string;
+    }>;
+};
+export declare function buildCorsExposeHeaders(existing?: string[]): string;
+export declare function buildReceiptLink(chainId: number, txHash: string): string;
+export declare function x402V211CompatibilityProof(): X402V211CompatibilityProof;
+//# sourceMappingURL=x402-v211-compatibility.d.ts.map

package/dist/utils/x402-v211-compatibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-v211-compatibility.d.ts","sourceRoot":"","sources":["../../src/utils/x402-v211-compatibility.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,kCAAkC,sBAAsB,CAAC;AACtE,eAAO,MAAM,oCAAoC,UAAgB,CAAC;AAClE,eAAO,MAAM,wBAAwB,qBAAqB,CAAC;AAC3D,eAAO,MAAM,4BAA4B,mBAAmB,CAAC;AAE7D,eAAO,MAAM,iCAAiC,UAG7C,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,IAAI,GAAG,KAAK,CAAC;AAEnD,MAAM,MAAM,0BAA0B,GAAG;IACvC,sBAAsB,EAAE,OAAO,kCAAkC,CAAC;IAClE,wBAAwB,EAAE,MAAM,EAAE,CAAC;IACnC,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC,sBAAsB,EAAE,KAAK,CAAC;QAC5B,OAAO,EAAE,uBAAuB,CAAC;QACjC,IAAI,EAAE,MAAM,CAAC;QACb,iBAAiB,EAAE,MAAM,CAAC;QAC1B,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;CACJ,CAAC;AAeF,wBAAgB,sBAAsB,CAAC,QAAQ,GAAE,MAAM,EAAO,GAAG,MAAM,CAOtE;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CASxE;AAED,wBAAgB,0BAA0B,IAAI,0BAA0B,CAkBvE"}

package/dist/utils/x402-v211-compatibility.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * x402 v2.11 paid MCP compatibility helpers.
+ *
+ * These helpers keep buyer-facing documentation, tests, and downstream
+ * Streamable HTTP gateways aligned on the same header names and receipt links.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.X402_V211_BROWSER_EXPOSED_HEADERS = exports.X402_V211_MCP_SESSION_HEADER = exports.X402_V211_RECEIPT_HEADER = exports.X402_V211_DEPRECATED_PAYMENT_HEADERS = exports.X402_V211_PAYMENT_SIGNATURE_HEADER = void 0;
+exports.buildCorsExposeHeaders = buildCorsExposeHeaders;
+exports.buildReceiptLink = buildReceiptLink;
+exports.x402V211CompatibilityProof = x402V211CompatibilityProof;
+exports.X402_V211_PAYMENT_SIGNATURE_HEADER = 'Payment-Signature';
+exports.X402_V211_DEPRECATED_PAYMENT_HEADERS = ['X-Payment'];
+exports.X402_V211_RECEIPT_HEADER = 'payment-response';
+exports.X402_V211_MCP_SESSION_HEADER = 'mcp-session-id';
+exports.X402_V211_BROWSER_EXPOSED_HEADERS = [
+    exports.X402_V211_RECEIPT_HEADER,
+    exports.X402_V211_MCP_SESSION_HEADER,
+];
+const RECEIPT_EXPLORERS = {
+    8453: {
+        name: 'Base mainnet',
+        explorerTxBaseUrl: 'https://basescan.org/tx',
+        x402Network: 'base',
+    },
+    84532: {
+        name: 'Base Sepolia',
+        explorerTxBaseUrl: 'https://sepolia.basescan.org/tx',
+        x402Network: 'base-sepolia',
+    },
+};
+function buildCorsExposeHeaders(existing = []) {
+    const normalized = new Map();
+    for (const header of [...existing, ...exports.X402_V211_BROWSER_EXPOSED_HEADERS]) {
+        const clean = header.trim();
+        if (clean)
+            normalized.set(clean.toLowerCase(), clean);
+    }
+    return Array.from(normalized.values()).join(', ');
+}
+function buildReceiptLink(chainId, txHash) {
+    if (!/^0x[a-fA-F0-9]{64}$/.test(txHash)) {
+        throw new Error('txHash must be a 32-byte 0x-prefixed transaction hash');
+    }
+    const chain = RECEIPT_EXPLORERS[chainId];
+    if (!chain) {
+        throw new Error('Unsupported receipt chain. Use Base mainnet 8453 or Base Sepolia 84532.');
+    }
+    return `${chain.explorerTxBaseUrl}/${txHash}`;
+}
+function x402V211CompatibilityProof() {
+    return {
+        paymentSignatureHeader: exports.X402_V211_PAYMENT_SIGNATURE_HEADER,
+        deprecatedPaymentHeaders: [...exports.X402_V211_DEPRECATED_PAYMENT_HEADERS],
+        responseHeaders: [...exports.X402_V211_BROWSER_EXPOSED_HEADERS],
+        corsExposeHeaders: buildCorsExposeHeaders(),
+        streamableHttpSequence: [
+            'POST /mcp initialize with Payment-Signature when the gateway charges for initialize',
+            'Read payment-response and mcp-session-id from exposed response headers',
+            'Send notifications/initialized after initialize succeeds',
+            'Call tools/list only after initialize and initialized complete',
+            'Call tools/call with the returned mcp-session-id when the gateway requires session continuity',
+        ],
+        supportedReceiptChains: Object.entries(RECEIPT_EXPLORERS).map(([chainId, value]) => ({
+            chainId: Number(chainId),
+            ...value,
+        })),
+    };
+}
+//# sourceMappingURL=x402-v211-compatibility.js.map

package/dist/utils/x402-v211-compatibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-v211-compatibility.js","sourceRoot":"","sources":["../../src/utils/x402-v211-compatibility.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAyCH,wDAOC;AAED,4CASC;AAED,gEAkBC;AA7EY,QAAA,kCAAkC,GAAG,mBAAmB,CAAC;AACzD,QAAA,oCAAoC,GAAG,CAAC,WAAW,CAAC,CAAC;AACrD,QAAA,wBAAwB,GAAG,kBAAkB,CAAC;AAC9C,QAAA,4BAA4B,GAAG,gBAAgB,CAAC;AAEhD,QAAA,iCAAiC,GAAG;IAC/C,gCAAwB;IACxB,oCAA4B;CAC7B,CAAC;AAkBF,MAAM,iBAAiB,GAAsG;IAC3H,IAAI,EAAE;QACJ,IAAI,EAAE,cAAc;QACpB,iBAAiB,EAAE,yBAAyB;QAC5C,WAAW,EAAE,MAAM;KACpB;IACD,KAAK,EAAE;QACL,IAAI,EAAE,cAAc;QACpB,iBAAiB,EAAE,iCAAiC;QACpD,WAAW,EAAE,cAAc;KAC5B;CACF,CAAC;AAEF,SAAgB,sBAAsB,CAAC,WAAqB,EAAE;IAC5D,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC7C,KAAK,MAAM,MAAM,IAAI,CAAC,GAAG,QAAQ,EAAE,GAAG,yCAAiC,CAAC,EAAE,CAAC;QACzE,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,KAAK;YAAE,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,KAAK,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACpD,CAAC;AAED,SAAgB,gBAAgB,CAAC,OAAe,EAAE,MAAc;IAC9D,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IACD,MAAM,KAAK,GAAG,iBAAiB,CAAC,OAAkC,CAAC,CAAC;IACpE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,yEAAyE,CAAC,CAAC;IAC7F,CAAC;IACD,OAAO,GAAG,KAAK,CAAC,iBAAiB,IAAI,MAAM,EAAE,CAAC;AAChD,CAAC;AAED,SAAgB,0BAA0B;IACxC,OAAO;QACL,sBAAsB,EAAE,0CAAkC;QAC1D,wBAAwB,EAAE,CAAC,GAAG,4CAAoC,CAAC;QACnE,eAAe,EAAE,CAAC,GAAG,yCAAiC,CAAC;QACvD,iBAAiB,EAAE,sBAAsB,EAAE;QAC3C,sBAAsB,EAAE;YACtB,qFAAqF;YACrF,wEAAwE;YACxE,0DAA0D;YAC1D,gEAAgE;YAChE,+FAA+F;SAChG;QACD,sBAAsB,EAAE,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;YACnF,OAAO,EAAE,MAAM,CAAC,OAAO,CAA4B;YACnD,GAAG,KAAK;SACT,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC"}

package/docs/agentpay-buyer-flow-parity.md

@@ -0,0 +1,149 @@
+# AgentPay buyer-flow parity for one-command x402 tools
+
+AgentScore Pay moved buyer-side x402 payments toward a single shell flow: discover, check, dry-run, pay, enforce local limits, preserve an idempotency key, and expose the flow through MCP tools. npm now shows `@agent-score/pay@0.1.0-rc.13`, one revision newer than the first 00:08 CT scan.
+
+rc.13 raised the bar again. Its release commit added typed SDK errors, quota envelope surfacing from `X-Quota-*` headers on `assess`, deterministic recovery guidance, and payment-path security patches. That means buyer-side competition is no longer only "can the agent pay?" It is "can the agent recover safely when payment, token, quota, or spend policy checks fail?"
+
+AgentPay MCP should not copy that CLI shape blindly. Its job is narrower and safer: make the payment decision auditable before an agent signs.
+
+## Buyer flow AgentPay must prove
+
+A buyer-agent payment path is acceptable only when these checks pass before signing:
+
+1. Discover or inspect the protected endpoint.
+2. Parse the HTTP 402 challenge from `payment-required`, `x-payment-required`, a trusted directory record, or a manual fixture.
+3. Verify the offered network and asset against the buyer allowlist.
+4. Verify `payTo` is non-zero and matches the expected recipient class.
+5. Compare the required amount against the caller's max spend.
+6. Produce a dry-run plan.
+7. Require approval when policy says approval is needed.
+8. Generate or verify a stable idempotency key from method, URL, body, and signer.
+9. Classify typed payment errors into deterministic retry guidance.
+10. Display quota and spend envelopes before retrying.
+11. Preserve no-charge failure semantics for validation, quota, token, and spend-cap failures.
+12. Record the audit destination, correlation ID, receipt sink, and payment result.
+13. Run through MCP tools that are visible to the host.
+
+The helper added in this response is `src/utils/x402-buyer-flow.ts`. It turns the checklist into a small fail-closed verifier:
+
+```ts
+import { verifyX402BuyerFlow } from './src/utils/x402-buyer-flow.js';
+
+const result = verifyX402BuyerFlow({
+  method: 'POST',
+  url: 'https://paid.example.com/mcp/search',
+  body: '{"query":"agent payments"}',
+  signer: '0x2222222222222222222222222222222222222222',
+  challengeSource: 'payment-required-header',
+  challenge: {
+    network: 'base-sepolia',
+    asset: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+    amountRequired: '10000',
+    payTo: '0x1111111111111111111111111111111111111111',
+  },
+  allowedNetworks: ['base-sepolia'],
+  allowedAssets: ['0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'],
+  maxSpendAtomic: '25000',
+  dryRunCompleted: true,
+  approvalState: 'approved',
+  typedError: {
+    name: 'PaymentRequiredError',
+    noCharge: true,
+  },
+  quota: {
+    limit: '100',
+    remaining: '99',
+    resetAt: '2026-05-02T10:00:00Z',
+    sourceHeaders: {
+      'X-Quota-Limit': '100',
+      'X-Quota-Remaining': '99',
+      'X-Quota-Reset': '2026-05-02T10:00:00Z',
+    },
+  },
+  mcpTools: ['x402_pay', 'check_budget', 'set_spend_policy', 'get_transaction_history', 'queue_approval'],
+  audit: {
+    destination: 'otel',
+    correlationId: 'tool-call-abc',
+    receiptSink: 'transaction-history',
+  },
+});
+
+if (!result.ok) throw new Error(result.failures.join('\n'));
+```
+
+The same helper now exposes `result.recovery` and `result.envelope`:
+
+```ts
+{
+  recovery: {
+    errorName: 'PaymentRequiredError',
+    retryability: 'retry_after_payment',
+    noCharge: true,
+    quotaVisible: true,
+  },
+  envelope: {
+    spend: {
+      maxSpendAtomic: '25000',
+      amountRequiredAtomic: '10000',
+      remainingAfterPaymentAtomic: '15000',
+    },
+    quota: {
+      limit: '100',
+      remaining: '99',
+      resetAt: '2026-05-02T10:00:00Z',
+    },
+  },
+}
+```
+
+## Typed error recovery map
+
+| Error | Agent recovery | Retryability | No-charge rule |
+|---|---|---|---|
+| `PaymentRequiredError` | Obtain or approve payment, then retry with the same idempotency key | `retry_after_payment` | No charge until a valid signed payment is submitted |
+| `QuotaExceededError` | Show quota limit, remaining units, reset time, and wait or change policy | `retry_after_quota_reset` when quota is visible, otherwise `operator_review` | No charge for quota rejection |
+| `TokenExpiredError` | Refresh the buyer credential, then retry only after policy re-check | `refresh_token_then_retry` | No charge for expired-token rejection |
+| `ValidationFailureError` | Do not retry automatically; fix recipient, chain, asset, amount, or challenge parsing | `do_not_retry` | No charge for validation failure |
+| `SpendLimitExceededError` | Do not retry automatically; require operator or policy change | `do_not_retry` | No charge for local spend-cap rejection |
+| `UnknownPaymentError` | Stop automation and route to operator review | `operator_review` | Treat charge state as unknown until audited |
+
+## Quota and spend envelope display
+
+Buyer-facing output should keep quota and spend in the same response object so an agent can decide without guessing:
+
+- `quota.limit`, `quota.remaining`, and `quota.resetAt` from `X-Quota-*` headers or an equivalent trusted envelope.
+- `spend.maxSpendAtomic`, `spend.amountRequiredAtomic`, and `spend.remainingAfterPaymentAtomic` from local policy plus the 402 challenge.
+- `recovery.retryability` as a machine-readable value, not prose.
+- `recovery.noCharge` as an explicit boolean for failed pre-payment checks.
+
+If a quota error arrives without quota visibility, AgentPay should fail closed and return `operator_review`. If a typed payment error does not assert `noCharge: true`, the helper fails before retry logic can run.
+
+## AgentScore Pay parity map
+
+| Buyer need | AgentScore Pay signal | AgentPay MCP response |
+|---|---|---|
+| Discovery | `discover` queries x402 Bazaar and MPP services | Keep x402 Bazaar readback in docs and require a challenge source before pay |
+| Check | `check` probes a protected endpoint | `verifyX402BuyerFlow` fails if network, asset, amount, or recipient is missing |
+| Dry-run | `pay --dry-run` prints a plan | `dryRunCompleted` must be true before payment can pass verification |
+| Spend cap | `--max-spend` and local limits | `maxSpendAtomic` and existing `set_spend_policy` / `check_budget` tools gate spend |
+| Typed errors | `PaymentRequiredError`, `QuotaExceededError`, `TokenExpiredError` | `classifyX402PaymentError()` maps typed errors to deterministic retryability |
+| Quota envelope | `X-Quota-*` surfacing on `assess` | `quota` keeps limit, remaining, reset, and source headers visible beside spend |
+| No-charge failures | Deterministic recovery guidance | `typedError.noCharge` must be explicit before retry or operator action |
+| Pay | One CLI command pays and retries | `x402_pay` stays the MCP payment tool, but only after policy checks pass |
+| Idempotency | Stable `X-Idempotency-Key` for retries | `createX402IdempotencyKey()` derives the key from method, URL, body, and signer |
+| MCP exposure | Every command can be an MCP tool | AgentPay exposes payment, budget, approval, session, and audit tools through MCP |
+| Audit | Local history and structured output | `get_transaction_history`, receipt sink, and correlation ID make the result auditable |
+
+## What AgentPay should not claim
+
+- Do not claim AgentPay MCP has a one-command buyer CLI unless we ship that CLI.
+- Do not claim Solana x402 signing support from this artifact. The verifier can detect allowlist mismatches, but AgentPay payment support remains tied to the configured supported network set.
+- Do not treat MPP or opaque credits as the AgentPay default. The positioning stays x402-native buyer verification and non-custodial signing.
+- Do not auto-retry quota, token, validation, or spend-limit failures unless the typed error, quota envelope, policy state, and audit trail make the retry safe.
+
+## Validation proof
+
+- Helper: `src/utils/x402-buyer-flow.ts`
+- Tests: `tests/x402-buyer-flow.test.ts`
+- README link: `README.md`
+- Validation command: `npm test -- --run tests/x402-buyer-flow.test.ts`

package/docs/dependency-pin-policy.md

@@ -0,0 +1,53 @@
+# Payment-critical dependency pin policy
+
+AgentPay MCP treats crypto verifier and signing dependencies as payment-critical infrastructure. A floating semver range is not acceptable when a fresh install can change the code path that parses a 402 challenge, derives an account, signs a payment, verifies a receipt, or maps a chain.
+
+## Current pin
+
+- `viem`: pinned exactly to `2.48.7`
+- `package.json` dependency: `"viem": "2.48.7"`
+- root npm override: `"viem": "2.48.7"`
+- reason: `viem` `2.48.8` exposed a broken `@noble/curves` import path in the x402 payment ecosystem. AgentScore Pay rc.14 pinned `viem` `2.48.7`; AgentPay MCP follows the same buyer-safety posture and proves clean installs before release.
+
+## Libraries covered by this policy
+
+Pin exactly, or document an explicit hard override, for any package that touches:
+
+- wallet/account derivation
+- signature creation or verification
+- x402 payment-required parsing
+- receipt, transaction, or payment envelope validation
+- chain metadata used to decide whether a payment can be signed
+- crypto hash, curve, address, or ABI encoding paths
+
+Today that includes `viem` and its crypto import surface. If AgentPay adds a direct dependency on `@noble/*`, `@scure/*`, `ox`, an x402 SDK package, or a facilitator client, that dependency must be reviewed under this policy before release.
+
+## Release gate
+
+Before publishing a package that changes x402 payment paths or crypto dependencies, run:
+
+```bash
+npm run build
+npm run smoke:clean-install
+```
+
+The clean-install smoke creates a fresh temporary consumer project, installs the packed AgentPay MCP tarball, imports `viem`, `viem/accounts`, `viem/chains`, AgentPay's packaged `x402_pay` tool, and AgentPay's wallet client utility, then confirms the resolved `viem` version is exactly `2.48.7`.
+
+A release must fail if:
+
+- the root package uses `^`, `~`, `>=`, `latest`, or any non-exact range for `viem`
+- the root override does not match the dependency pin
+- a clean install resolves the x402 verifier path to a different `viem` version
+- packaged AgentPay x402 imports fail in a fresh consumer project
+- a payment path silently falls back to an unsupported chain or parser
+
+## Upgrade process
+
+1. Open a dependency-pin issue or PR explaining the market or security signal.
+2. Change the exact dependency and override together.
+3. Refresh `package-lock.json`.
+4. Run typecheck, tests, build, pack dry-run, and clean-install smoke.
+5. Preserve proof under `ops/proofs/` before publishing.
+6. Publish only after the proof shows the same exact dependency version in a clean consumer install.
+
+Do not relax this policy for convenience. Payment libraries can break buyer agents without changing AgentPay source code, so deterministic installs are part of the product contract.

package/docs/fixtures/paid-provider-health-proof-voidly-2026-05-02.json

@@ -0,0 +1,104 @@
+{
+  "schema": "agentpay-paid-provider-health-proof/v1",
+  "generated_at": "2026-05-02T21:26:24.103Z",
+  "source": {
+    "name": "Voidly Pay public pay-health feed",
+    "url": "https://raw.githubusercontent.com/voidly-ai/voidly-pay/main/pay-health/latest.json",
+    "commit": "a907e56db0782e43ff36adf448e493d5632fba42",
+    "raw_schema": "voidly-pay-network-health/v1"
+  },
+  "health": {
+    "ok": true,
+    "latency_ms": 720
+  },
+  "ok": false,
+  "summary": {
+    "providers_probed": 5,
+    "providers_ok": 2,
+    "providers_failing": 3,
+    "success_rate": 0.4
+  },
+  "providers": [
+    {
+      "provider_id": "did:voidly:Ck56rQkhsBe3bJa62bg81t",
+      "capability": "echo.text-1777170057372",
+      "capability_id": "4f862bbb-050b-47a6-a189-71a23d10b936",
+      "status": "failed",
+      "stale_streak": 207,
+      "receipt_state": "missing",
+      "verified": false,
+      "latency_ms": 61778,
+      "error": "hire did not reach claimed state"
+    },
+    {
+      "provider_id": "did:voidly:3bzjV3jSMCuTwZ6NRzrS8m",
+      "capability": "echo.text-1777170066728",
+      "capability_id": "ea0ac3a8-b35c-44c2-bf76-4c964c8dd559",
+      "status": "failed",
+      "stale_streak": 207,
+      "receipt_state": "missing",
+      "verified": false,
+      "latency_ms": 61721,
+      "error": "hire did not reach claimed state"
+    },
+    {
+      "provider_id": "did:voidly:AsAVzZ2dtMrntgGRco8KkW",
+      "capability": "hash.sha256",
+      "capability_id": "e00a3caf-5090-4414-aab9-89e5420bf871",
+      "status": "ok",
+      "stale_streak": 0,
+      "receipt_state": "pending_acceptance_verified",
+      "receipt_id": "22640d76-9eca-4730-bbbc-b10e42e7a736",
+      "verified": true,
+      "latency_ms": 13750,
+      "x402_payment": {
+        "scheme": "exact",
+        "network": "base-sepolia",
+        "asset": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+        "payTo": "0x1111111111111111111111111111111111111111",
+        "maxAmountRequired": "800",
+        "resource": "https://api.voidly.example/pay/hash.sha256"
+      }
+    },
+    {
+      "provider_id": "did:voidly:Eg8JvTNrBLcpbX3r461jJB",
+      "capability": "hash.sha256",
+      "capability_id": "1b32805f-07e0-426e-a7a2-53ac41396303",
+      "status": "ok",
+      "stale_streak": 0,
+      "receipt_state": "pending_acceptance_verified",
+      "receipt_id": "df261343-afc2-49f4-8f25-4fc32e291d9e",
+      "verified": true,
+      "latency_ms": 8999,
+      "x402_payment": {
+        "scheme": "exact",
+        "network": "base-sepolia",
+        "asset": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+        "payTo": "0x2222222222222222222222222222222222222222",
+        "maxAmountRequired": "1000",
+        "resource": "https://api.voidly.example/pay/hash.sha256"
+      }
+    },
+    {
+      "provider_id": "did:voidly:mkt-b-1776622972",
+      "capability": "translate",
+      "capability_id": "af7719a4-f4bf-4a8c-aafb-8c1a7b8e226c",
+      "status": "failed",
+      "stale_streak": 312,
+      "receipt_state": "missing",
+      "verified": false,
+      "latency_ms": 61627,
+      "error": "hire did not reach claimed state"
+    }
+  ],
+  "routing": {
+    "fail_closed": true,
+    "decision": "deny",
+    "reason": [
+      "Provider success_rate is 0.4 across five probed providers.",
+      "Three providers have repeated stale failure streaks.",
+      "Only two providers have verified receipt state.",
+      "Buyer must verify x402 network, asset, and payTo before signing."
+    ]
+  }
+}