agentwallet-mcp 1.10.9 → 1.11.0

package/README.md

@@ -219,15 +219,15 @@ All on-chain. All through MCP. No frontend needed.
 
 ## x402 Payments
 
-AgentWallet natively supports the [x402 open payment standard](https://x402.org). When your Ai agent encounters an API that returns HTTP 402 Payment Required, the `pay_x402` tool handles the entire flow automatically:
+AgentWallet speaks the [x402 open payment standard](https://x402.org) the way the spec defines it. When your Ai agent hits an API that answers HTTP 402, `pay_x402` does the whole flow:
 
-1. Fetches the URL and detects the 402 response
-2. Parses the payment requirements (amount, token, chain)
-3. Executes the on-chain payment from your wallet
-4. Retries the request with proof of payment
-5. Returns the final response
+1. Fetches the URL and reads the payment requirements, from the v2 `PAYMENT-REQUIRED` header or the v1 JSON body.
+2. Picks an `exact` option (you can steer it with `prefer_chain`).
+3. Signs an **EIP-3009 `TransferWithAuthorization`** for exactly that amount. Nothing is broadcast and no gas is paid by the payer; the endpoint's facilitator settles it on-chain.
+4. Retries the request with the payment header (`PAYMENT-SIGNATURE` for v2, `X-PAYMENT` for v1).
+5. Returns the response, the settlement receipt (`PAYMENT-RESPONSE` / `X-PAYMENT-RESPONSE`) and, if the endpoint declined, its stated reason in `retry_error`.
 
-**Set `max_payment` to control spending:**
+Verified against Coinbase's public facilitator (`isValid: true` for v1 and v2 payloads) and live x402 servers on Base. Works in both custody modes: the local key signs in-process; hosted wallets sign through `POST /wallets/{id}/x402/authorize`, a narrow endpoint that only ever signs this one struct and runs the same pause and token-cap checks as a transfer.
 
 ```
 pay_x402(
@@ -237,9 +237,11 @@ pay_x402(
 )
 ```
 
-`max_payment` is enforced as a hard per-payment cap. If you omit it, `pay_x402` falls back to `AGENTWALLET_MAX_AUTOPAY` (default `1`), the same cap the auto-pay path uses, so a malicious or compromised 402 endpoint can never authorize an unbounded payment. Set `max_payment` explicitly (or raise `AGENTWALLET_MAX_AUTOPAY`) to allow a larger single payment.
+`max_payment` is a hard per-payment cap. If you omit it, `pay_x402` falls back to `AGENTWALLET_MAX_AUTOPAY` (default `1`), so a malicious or compromised 402 endpoint can never authorize an unbounded payment. In local mode `AGENTWALLET_MAX_TX_TOKEN` applies to authorizations too, because an authorization is a transfer somebody else executes.
 
-Supports ERC-20 tokens, SPL tokens, and native tokens on EVM and Solana. Compatible with x402 V1 and V2 (CAIP-2 chain identifiers), and reads the token address from the standard x402 `asset` field (falling back to `extra.token`).
+**Schemes.** `exact` is fully supported on every EVM chain AgentWallet knows. `upto` (a Permit2 maximum the seller settles below) is refused with a clear message rather than approximated with an upfront transfer; Permit2 support is next. Native-asset and Solana requests, and AgentWallet's own paywalls, are paid by an on-chain transfer proved by transaction hash, which is what those servers verify.
+
+**Token domains.** The EIP-712 domain comes from the endpoint's `extra.name` / `extra.version`, then a short registry of USDC deployments, then the token contract's own `name()` / `version()`. If none of those answer, the payment is refused rather than signed with a guessed domain.
 
 ## x402 Acceptance
 

package/build/index.js

@@ -15,6 +15,8 @@ import { z } from 'zod';
 import { assertPublicUrl, safeFetch } from './ssrf-guard.js';
 import { deriveX402Payment, isWithinCap, lookupTrustedDecimals, assertDeclaredDecimals, nativeDecimals, SOLANA_CHAIN_IDS, } from './x402-payment.js';
 import { isLocalMode, getLocalAddress, localWalletRecord, localSend, localNativeBalance, localTokenBalance, localSignMessage, resolveRpcUrl, } from './local-wallet.js';
+import { localSignAuthorization, localEthCall } from './local-wallet.js';
+import { isLegacyAgentWalletAccept, requiredAmount, buildAuthorization, buildPaymentPayload, paymentHeaderFor, parsePaymentRequired, parseSettlement, pickOption, knownTokenDomain, } from './x402-eip3009.js';
 import { isSolanaLocalMode, getSolanaAddress, solanaWalletRecord, localSolBalance, localSplBalance, localSolTransfer, localSplTransfer, resolveSolanaRpc, } from './local-solana.js';
 /** True when either chain family is running non-custodially. */
 function anyLocalMode() {
@@ -90,6 +92,26 @@ async function routeLocally(path, method, body) {
         const hasData = data && data !== '0x';
         return localSend(chainId, to, value, hasData ? data : undefined);
     }
+    // POST /wallets/{id}/x402/authorize  (x402 "exact": EIP-3009 authorization, signed here, broadcast by nobody)
+    if (method === 'POST' && /^\/wallets\/[^/]*\/x402\/authorize$/.test(rawPath)) {
+        if (!isLocalMode())
+            refuseMissingLocalKey('evm');
+        const chainId = localChainId(body, qs);
+        return localSignAuthorization(chainId, String(body?.asset || ''), { name: String(body?.name || ''), version: String(body?.version || '') }, {
+            from: getLocalAddress(),
+            to: String(body?.to || ''),
+            value: String(body?.value ?? '0'),
+            validAfter: String(body?.valid_after ?? '0'),
+            validBefore: String(body?.valid_before ?? '0'),
+            nonce: String(body?.nonce || ''),
+        });
+    }
+    // POST /eth-call  (read-only; answered from the local RPC so pure self-custody needs no hosted credentials)
+    if (method === 'POST' && rawPath === '/eth-call') {
+        if (!isLocalMode())
+            return NOT_HANDLED;
+        return localEthCall(localChainId(body, qs), String(body?.to || ''), String(body?.data || '0x'));
+    }
     // GET /wallets/{id}/balance
     if (method === 'GET' && /^\/wallets\/[^/]*\/balance$/.test(rawPath)) {
         const chainId = localChainId(body, qs);
@@ -423,7 +445,7 @@ function resolveChainId(network) {
 const AddressSchema = z.string().regex(/^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$/, 'Must be a 0x-prefixed 40-hex EVM address or a base58 Solana address');
 const server = new McpServer({
     name: 'agentwallet',
-    version: '1.10.9',
+    version: '1.11.0',
 }, {
     instructions: `AgentWallet gives AI agents their own blockchain wallets. Private keys are encrypted server-side and never exposed — agents sign and broadcast transactions without ever touching raw keys.
 
@@ -935,11 +957,63 @@ server.tool('get_token_info', 'Get the name, symbol, and decimals of any ERC-20
         decimals,
     });
 });
+// ─── x402 "exact" helpers ────────────────────────────────────────
+/** The paying address: the local key in self-custody mode, else the hosted wallet record. */
+async function payerAddress(walletId) {
+    const w = (await api(`/wallets/${walletId}`, 'GET', undefined, { 'X-AGW-SKIP-X402': 'true' }));
+    const a = String(w?.address || w?.wallet_address || '');
+    if (!/^0x[0-9a-fA-F]{40}$/.test(a))
+        throw new Error(`x402: could not resolve the EVM address of wallet ${walletId} (got "${a}").`);
+    return a;
+}
+async function ethCallHex(chainId, to, data) {
+    const r = (await api('/eth-call', 'POST', { chain_id: chainId, to, data }, { 'X-AGW-SKIP-X402': 'true' }));
+    return String(r?.result || '');
+}
+/**
+ * The token's EIP-712 domain. Order: what the 402 declared (extra.name/version,
+ * which is what the reference client requires), then a short list of USDC
+ * deployments we know, then the contract's own name()/version(). A wrong
+ * domain produces a signature that recovers to a stranger, so we refuse
+ * rather than guess.
+ */
+async function resolveTokenDomain(chainId, asset, extra) {
+    if (extra?.name && extra?.version)
+        return { name: String(extra.name), version: String(extra.version) };
+    const known = knownTokenDomain(chainId, asset);
+    if (known)
+        return known;
+    let name = '', version = '';
+    try {
+        name = decodeAbiString(await ethCallHex(chainId, asset, '0x06fdde03')); // name()
+        version = decodeAbiString(await ethCallHex(chainId, asset, '0x54fd4d50')); // version()
+    }
+    catch { /* refused below */ }
+    if (!name || !version) {
+        throw new Error(`x402: cannot determine the EIP-712 domain for token ${asset} on chain ${chainId}: the endpoint sent no ` +
+            `extra.name/extra.version and the contract did not answer name()/version(). Refused rather than signed with a guessed domain.`);
+    }
+    return { name, version };
+}
+/** Sign the authorization with whichever custody mode is active (local key, or the hosted signer). */
+async function signAuthorization(walletId, chainId, asset, domain, auth) {
+    const r = (await api(`/wallets/${walletId}/x402/authorize`, 'POST', {
+        chain_id: chainId, asset, name: domain.name, version: domain.version,
+        to: auth.to, value: auth.value, valid_after: auth.validAfter, valid_before: auth.validBefore, nonce: auth.nonce,
+    }, { 'X-AGW-SKIP-X402': 'true' }));
+    const sig = String(r?.signature || '');
+    if (!/^0x[0-9a-fA-F]{130}$/.test(sig)) {
+        throw new Error(`x402: the wallet did not return a valid authorization signature${r?.error ? ` (${r.error})` : ''}.`);
+    }
+    return sig;
+}
 // ─── Tool: pay_x402 ─────────────────────────────────────────────
 server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the server returns HTTP 402 Payment Required, ' +
-    'parses the payment requirements, executes the on-chain payment, and retries the request with ' +
-    'proof of payment. Returns the final response. Supports the x402 open payment standard ' +
-    '(https://x402.org). Set max_payment to prevent overspending.', {
+    'parses the payment requirements (v1 body or v2 PAYMENT-REQUIRED header), signs an EIP-3009 ' +
+    'TransferWithAuthorization for the "exact" scheme (no gas, nothing broadcast by the payer), and retries ' +
+    'the request with the payment header. AgentWallet paywalls are paid by on-chain transfer instead. ' +
+    'The "upto" scheme is refused, never approximated. Returns the final response and the settlement ' +
+    'receipt. Supports the x402 open payment standard (https://x402.org). Set max_payment to cap spend.', {
     url: z.string().url().describe('The URL to access (will handle 402 payment if required)'),
     wallet_id: z.number().int().describe('Wallet ID to pay from'),
     method: z.string().default('GET').describe('HTTP method (GET, POST, PUT, DELETE)'),
@@ -999,125 +1073,114 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
             response: parsed,
         });
     }
-    // Step 2: Parse x402 payment requirements from 402 response
-    let paymentInfo;
+    // Step 2: Requirements come from the PAYMENT-REQUIRED header (v2) or the JSON body (v1).
+    const initialText = await initialRes.text();
+    let initialBody = null;
     try {
-        paymentInfo = await initialRes.json();
+        initialBody = JSON.parse(initialText);
     }
     catch {
-        throw new Error('402 response body is not valid JSON. This server may not support x402.');
-    }
-    if (!paymentInfo.accepts || paymentInfo.accepts.length === 0) {
-        throw new Error('402 response has no payment options in "accepts" array.');
-    }
-    const options = paymentInfo.accepts;
-    let option;
-    if (prefer_chain) {
-        option = options.find(a => resolveChainId(a.network) === prefer_chain) || options[0];
-    }
-    else {
-        option = options[0];
+        initialBody = null;
+    }
+    const paymentInfo = parsePaymentRequired(n => initialRes.headers.get(n), initialBody);
+    if (!paymentInfo || !Array.isArray(paymentInfo.accepts) || paymentInfo.accepts.length === 0) {
+        throw new Error('402 response carried no x402 payment requirements (no PAYMENT-REQUIRED header and no "accepts" array in the body). ' +
+            'This server may not support x402.');
+    }
+    const x402Version = Number(paymentInfo.x402Version) || 1;
+    const accepts = paymentInfo.accepts;
+    // Step 3: Pick an option this client can sign. "exact" only; "upto" is refused, never approximated (issue #6).
+    const picked = pickOption(accepts, resolveChainId, prefer_chain);
+    if (!picked.option || !picked.chainId) {
+        return jsonResponse({
+            status: 402,
+            payment_required: true,
+            payment_made: false,
+            error: picked.reason,
+            offered: accepts.map(a => ({ scheme: a.scheme, network: a.network, amount: requiredAmount(a), asset: a.asset ?? a.extra?.token ?? null })),
+        });
     }
-    // Resolve the chain
-    const chainId = resolveChainId(option.network);
-    if (!chainId) {
-        throw new Error(`Unsupported x402 network: "${option.network}". ` +
-            `Supported: ${Object.keys(X402_NETWORKS).join(', ')}, or any CAIP-2 / numeric chain ID.`);
+    const option = picked.option;
+    const chainId = picked.chainId;
+    const rawAmount = requiredAmount(option);
+    if (!/^\d+$/.test(rawAmount)) {
+        throw new Error(`x402: invalid amount "${rawAmount}" in the payment requirements (expected integer base units).`);
     }
     // Decimals come from the registry or the token contract, NEVER from the 402
-    // body. The endpoint controls requiredDecimals, so trusting it lets a
-    // hostile server inflate the cap AND misreport the amount shown to the
-    // agent. The declared value is only used to detect a mismatch and refuse.
-    const assetForDecimals = option.asset || option.extra?.token || '';
-    const trustedDecimals = assetForDecimals
-        ? await resolveTrustedDecimals(chainId, assetForDecimals)
+    // body. The endpoint controls what it declares, so trusting it would let a
+    // hostile server inflate the cap and misreport the amount shown to the agent.
+    const tokenAddress = option.asset || option.extra?.token || '';
+    const trustedDecimals = tokenAddress
+        ? await resolveTrustedDecimals(chainId, tokenAddress)
         : nativeDecimals(chainId); // 18 on EVM (wei), 9 on Solana (lamports)
-    assertDeclaredDecimals(option.requiredDecimals, trustedDecimals);
-    // Human-readable amount, computed with trusted decimals so what the agent
-    // is told matches what will actually leave the wallet.
-    const amount = formatUnits(option.maxAmountRequired, trustedDecimals);
-    // Step 4: Enforce a hard per-payment cap. ALWAYS applied — if the caller
-    // omits max_payment we fall back to AGENTWALLET_MAX_AUTOPAY (default "1"),
-    // mirroring the internal auto-pay path (deriveX402Payment). Without this, an
-    // untrusted or compromised x402 endpoint could return an arbitrarily large
-    // maxAmountRequired and drain the wallet. The cap is never silently skipped.
+    if (typeof option.requiredDecimals === 'number')
+        assertDeclaredDecimals(option.requiredDecimals, trustedDecimals);
+    const amount = formatUnits(rawAmount, trustedDecimals);
+    const tokenLabel = option.extra?.name || (tokenAddress ? 'tokens' : 'native');
+    // Step 4: Hard per-payment cap, ALWAYS applied. If the caller omits max_payment
+    // we fall back to AGENTWALLET_MAX_AUTOPAY (default "1"), so an untrusted 402
+    // endpoint can never authorize an unbounded payment. Never silently skipped.
     const capSource = max_payment ? 'max_payment' : 'AGENTWALLET_MAX_AUTOPAY';
     const effectiveMax = max_payment || process.env.AGENTWALLET_MAX_AUTOPAY || '1';
-    if (!isWithinCap(option.maxAmountRequired, trustedDecimals, effectiveMax)) {
+    if (!isWithinCap(rawAmount, trustedDecimals, effectiveMax)) {
         return jsonResponse({
             status: 402,
             payment_required: true,
             payment_made: false,
-            error: `Payment of ${amount} ${option.extra?.name || 'tokens'} exceeds the ` +
-                `${effectiveMax} cap (from ${capSource}).` +
+            error: `Payment of ${amount} ${tokenLabel} exceeds the ${effectiveMax} cap (from ${capSource}).` +
                 (max_payment ? '' : ' No max_payment was provided, so the default cap was applied. ' +
                     'Pass max_payment (or raise AGENTWALLET_MAX_AUTOPAY) to allow a larger payment.'),
             required_amount: amount,
             max_allowed: effectiveMax,
             cap_source: capSource,
-            token: option.extra?.name || 'native',
+            token: tokenLabel,
             network: option.network,
             chain_id: chainId,
             pay_to: option.payTo,
             description: option.description,
         });
     }
-    // Standard x402 puts the token address in `asset`; AgentWallet's own server
-    // currently emits it under extra.token. Prefer the standard field, fall back.
-    const tokenAddress = option.asset || option.extra?.token || '';
-    // Step 5: Execute payment
-    let txResult;
-    if (isSolanaChain(chainId)) {
-        // Solana payment
-        if (tokenAddress) {
-            // SPL token payment (e.g. USDC on Solana)
-            txResult = (await api(`/wallets/${wallet_id}/send`, 'POST', {
-                to: option.payTo,
-                value: option.maxAmountRequired,
-                token_mint: tokenAddress,
-                token_decimals: trustedDecimals,
-                chain_id: chainId,
-            }));
+    // Step 5: Pay. Standard x402 "exact" on EVM is an EIP-3009 authorization the
+    // facilitator settles; the payer broadcasts nothing and pays no gas. AgentWallet's
+    // own paywalls (verified by receipt), native-asset requests and Solana still use
+    // a broadcast transfer proved by hash.
+    const standardExact = !isSolanaChain(chainId) && Boolean(tokenAddress) && !isLegacyAgentWalletAccept(option);
+    let headerName = 'X-PAYMENT';
+    let paymentHeader = '';
+    let txHash = null;
+    let authorization = null;
+    let payer = null;
+    if (standardExact) {
+        payer = await payerAddress(wallet_id);
+        const domain = await resolveTokenDomain(chainId, tokenAddress, option.extra);
+        authorization = buildAuthorization(payer, option);
+        const signature = await signAuthorization(wallet_id, chainId, tokenAddress, domain, authorization);
+        const payload = buildPaymentPayload(x402Version, option, authorization, signature, paymentInfo.resource, paymentInfo.extensions);
+        const h = paymentHeaderFor(x402Version, payload);
+        headerName = h.name;
+        paymentHeader = h.value;
+    }
+    else {
+        let txResult;
+        if (isSolanaChain(chainId)) {
+            txResult = (await api(`/wallets/${wallet_id}/send`, 'POST', tokenAddress
+                ? { to: option.payTo, value: rawAmount, token_mint: tokenAddress, token_decimals: trustedDecimals, chain_id: chainId }
+                : { to: option.payTo, value: rawAmount, chain_id: chainId }));
+        }
+        else if (tokenAddress) {
+            const calldata = '0xa9059cbb' + padAddress(option.payTo) + encodeUint256(rawAmount);
+            txResult = (await api(`/wallets/${wallet_id}/send`, 'POST', { to: tokenAddress, value: '0', data: calldata, chain_id: chainId }));
         }
         else {
-            // Native SOL payment
-            txResult = (await api(`/wallets/${wallet_id}/send`, 'POST', {
-                to: option.payTo,
-                value: option.maxAmountRequired,
-                chain_id: chainId,
-            }));
+            txResult = (await api(`/wallets/${wallet_id}/send`, 'POST', { to: option.payTo, value: rawAmount, data: '', chain_id: chainId }));
         }
+        txHash = String(txResult.tx_hash || txResult.signature || '');
+        if (!txHash)
+            throw new Error('x402: the payment transaction returned no hash.');
+        paymentHeader = Buffer.from(JSON.stringify({ x402Version, scheme: option.scheme, network: option.network, payload: { txHash } })).toString('base64');
     }
-    else if (tokenAddress) {
-        // EVM ERC-20 token payment (e.g. USDC)
-        const calldata = '0xa9059cbb' + padAddress(option.payTo) + encodeUint256(option.maxAmountRequired);
-        txResult = (await api(`/wallets/${wallet_id}/send`, 'POST', {
-            to: tokenAddress,
-            value: '0',
-            data: calldata,
-            chain_id: chainId,
-        }));
-    }
-    else {
-        // EVM native token payment (ETH, etc.)
-        txResult = (await api(`/wallets/${wallet_id}/send`, 'POST', {
-            to: option.payTo,
-            value: option.maxAmountRequired,
-            data: '',
-            chain_id: chainId,
-        }));
-    }
-    // Solana returns 'signature', EVM returns 'tx_hash'
-    const txHash = (txResult.tx_hash || txResult.signature);
-    // Step 6: Build x402 payment proof and retry
-    const paymentProof = {
-        x402Version: paymentInfo.x402Version || 1,
-        scheme: option.scheme,
-        network: option.network,
-        payload: { txHash },
-    };
-    const paymentHeader = Buffer.from(JSON.stringify(paymentProof)).toString('base64');
-    const retryHeaders = { ...reqHeaders, 'X-PAYMENT': paymentHeader };
+    // Step 6: Retry with the payment header and read the settlement receipt.
+    const retryHeaders = { ...reqHeaders, [headerName]: paymentHeader };
     const retryOptions = {
         method,
         headers: retryHeaders,
@@ -1135,17 +1198,31 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
     catch {
         retryParsed = retryText;
     }
+    const settlement = parseSettlement(n => retryRes.headers.get(n));
+    // A second 402 means the facilitator declined (unfunded payer, expired window, bad domain...). v2 servers
+    // put the reason in a fresh PAYMENT-REQUIRED header, v1 servers in the body; surface it instead of {}.
+    let retryError = null;
+    if (retryRes.status === 402) {
+        const again = parsePaymentRequired(n => retryRes.headers.get(n), retryParsed);
+        retryError = String(again?.error || retryParsed?.error || 'Payment was not accepted (no reason given).');
+    }
     return jsonResponse({
         status: retryRes.status,
         payment_required: true,
-        payment_made: true,
+        payment_made: retryRes.status !== 402,
+        retry_error: retryError,
+        payment_method: standardExact ? 'eip3009-authorization' : 'onchain-transfer',
+        x402_version: x402Version,
         amount,
-        token: option.extra?.name || 'native',
-        token_address: option.asset || option.extra?.token || null,
+        token: tokenLabel,
+        token_address: tokenAddress || null,
         network: option.network,
         chain_id: chainId,
         pay_to: option.payTo,
-        tx_hash: txHash,
+        payer,
+        tx_hash: txHash ?? settlement?.transaction ?? null,
+        settlement,
+        authorization: authorization ? { nonce: authorization.nonce, valid_before: authorization.validBefore } : null,
         description: option.description,
         response: retryParsed,
     });

package/build/local-wallet.d.ts

@@ -15,6 +15,7 @@
  * on the custodial path and say so explicitly rather than silently downgrading.
  */
 import { type Address, type Hex } from 'viem';
+import { type Eip3009Authorization } from './x402-eip3009.js';
 /** True when the server is running non-custodially. */
 export declare function isLocalMode(): boolean;
 export declare function getLocalAccount(): {
@@ -88,3 +89,21 @@ export declare function localWalletRecord(): {
     custody: string;
     note: string;
 };
+/**
+ * Sign a TransferWithAuthorization for an x402 payment. Nothing is broadcast;
+ * the resource server's facilitator settles it on-chain. The amount is put
+ * through the same AGENTWALLET_MAX_TX_TOKEN guard as a transfer, because that
+ * is exactly what the authorization lets someone else execute.
+ */
+export declare function localSignAuthorization(chainId: number, asset: Address, domain: {
+    name: string;
+    version: string;
+}, auth: Eip3009Authorization): Promise<{
+    signature: `0x${string}`;
+    from: Address;
+    mode: 'local';
+}>;
+/** Read-only eth_call against the local RPC, same shape as the hosted /eth-call route. */
+export declare function localEthCall(chainId: number, to: Address, data: Hex): Promise<{
+    result: string;
+}>;

package/build/local-wallet.js

@@ -18,6 +18,7 @@ import { readFileSync } from 'node:fs';
 import { createPublicClient, createWalletClient, http, encodeFunctionData, parseAbi, formatUnits, } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
 import { lookupTrustedDecimals } from './x402-payment.js';
+import { typedDataFor } from './x402-eip3009.js';
 /* ── Key loading ─────────────────────────────────────────────────── */
 /**
  * Read the key once at startup. Kept module-private: nothing exports the key
@@ -306,3 +307,31 @@ export function localWalletRecord() {
         note: 'Signed in-process. The private key is never sent to AgentWallet servers.',
     };
 }
+/* ── x402 "exact": EIP-3009 authorization signed in-process ──────── */
+/**
+ * Sign a TransferWithAuthorization for an x402 payment. Nothing is broadcast;
+ * the resource server's facilitator settles it on-chain. The amount is put
+ * through the same AGENTWALLET_MAX_TX_TOKEN guard as a transfer, because that
+ * is exactly what the authorization lets someone else execute.
+ */
+export async function localSignAuthorization(chainId, asset, domain, auth) {
+    if (!/^0x[a-fA-F0-9]{40}$/.test(asset))
+        throw new Error(`Local mode needs an EVM token address for x402, got "${asset}".`);
+    if (!/^0x[a-fA-F0-9]{40}$/.test(auth.to))
+        throw new Error(`Local mode needs an EVM payTo address for x402, got "${auth.to}".`);
+    if (!/^\d+$/.test(auth.value))
+        throw new Error(`x402 authorization value must be integer base units, got "${auth.value}".`);
+    const calldata = ('0xa9059cbb'
+        + auth.to.slice(2).toLowerCase().padStart(64, '0')
+        + BigInt(auth.value).toString(16).padStart(64, '0'));
+    await assertWithinTokenCap(chainId, asset, calldata);
+    const from = getLocalAddress();
+    const signature = await getLocalAccount().signTypedData(typedDataFor(chainId, asset, domain.name, domain.version, { ...auth, from }));
+    return { signature, from, mode: 'local' };
+}
+/** Read-only eth_call against the local RPC, same shape as the hosted /eth-call route. */
+export async function localEthCall(chainId, to, data) {
+    const client = createPublicClient({ transport: http(resolveRpcUrl(chainId)) });
+    const r = await client.call({ to, data });
+    return { result: r.data ?? '0x' };
+}

package/build/x402-eip3009.d.ts

@@ -0,0 +1,168 @@
+export declare const TRANSFER_WITH_AUTHORIZATION_TYPES: {
+    readonly TransferWithAuthorization: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validAfter";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validBefore";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }];
+};
+/** One entry of a 402 "accepts" array, v1 or v2 (and AgentWallet's own legacy shape). */
+export interface X402Requirement {
+    scheme: string;
+    network: string;
+    payTo: string;
+    asset?: string;
+    amount?: string;
+    maxAmountRequired?: string;
+    maxTimeoutSeconds?: number;
+    resource?: string;
+    description?: string;
+    mimeType?: string;
+    outputSchema?: Record<string, unknown>;
+    requiredDecimals?: number;
+    extra?: {
+        name?: string;
+        version?: string;
+        token?: string;
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}
+export interface X402PaymentRequired {
+    x402Version: number;
+    error?: string;
+    resource?: {
+        url: string;
+        description?: string;
+        mimeType?: string;
+    };
+    accepts: X402Requirement[];
+    extensions?: Record<string, unknown>;
+}
+export interface Eip3009Authorization {
+    from: `0x${string}`;
+    to: `0x${string}`;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: `0x${string}`;
+}
+export interface X402Settlement {
+    success?: boolean;
+    transaction?: string;
+    network?: string;
+    payer?: string;
+    amount?: string;
+    errorReason?: string;
+    errorMessage?: string;
+    [k: string]: unknown;
+}
+/**
+ * AgentWallet's own paywalls (hifriendbot.com /x402/access/{id}) predate the
+ * spec's field names: no `asset`, token under `extra.token`, `requiredDecimals`
+ * present, and they verify a broadcast transfer by receipt. Anything with an
+ * `asset` is treated as standard x402.
+ */
+export declare function isLegacyAgentWalletAccept(a: X402Requirement): boolean;
+/** Required amount in base units, whichever spelling the server used. */
+export declare function requiredAmount(a: X402Requirement): string;
+export declare function createNonce(): `0x${string}`;
+/** Authorization window mirrors the reference client: valid from 10 minutes ago until maxTimeoutSeconds from now. */
+export declare function buildAuthorization(from: string, req: X402Requirement, nowSeconds?: number, nonce?: `0x${string}`): Eip3009Authorization;
+/** EIP-712 typed data for the authorization. `name`/`version` are the token's own domain values. */
+export declare function typedDataFor(chainId: number, asset: string, name: string, version: string, auth: Eip3009Authorization): {
+    domain: {
+        name: string;
+        version: string;
+        chainId: number;
+        verifyingContract: `0x${string}`;
+    };
+    types: {
+        readonly TransferWithAuthorization: readonly [{
+            readonly name: "from";
+            readonly type: "address";
+        }, {
+            readonly name: "to";
+            readonly type: "address";
+        }, {
+            readonly name: "value";
+            readonly type: "uint256";
+        }, {
+            readonly name: "validAfter";
+            readonly type: "uint256";
+        }, {
+            readonly name: "validBefore";
+            readonly type: "uint256";
+        }, {
+            readonly name: "nonce";
+            readonly type: "bytes32";
+        }];
+    };
+    primaryType: "TransferWithAuthorization";
+    message: {
+        from: `0x${string}`;
+        to: `0x${string}`;
+        value: bigint;
+        validAfter: bigint;
+        validBefore: bigint;
+        nonce: `0x${string}`;
+    };
+};
+/**
+ * Token EIP-712 domains we know without asking the chain. USDC's domain name
+ * differs by deployment ("USD Coin" on most mainnets, "USDC" on Base Sepolia),
+ * which is exactly the kind of thing that silently produces an unrecoverable
+ * signature, so only well-known deployments are listed; anything else is read
+ * from the contract's name()/version().
+ */
+export declare const KNOWN_TOKEN_DOMAINS: Record<string, {
+    name: string;
+    version: string;
+}>;
+export declare function knownTokenDomain(chainId: number, asset: string): {
+    name: string;
+    version: string;
+} | null;
+/** Decode a single ABI-encoded string return value (name()/version()). */
+export declare function decodeAbiString(hex: string): string;
+/** Build the payment payload the resource server expects for this x402 version. */
+export declare function buildPaymentPayload(x402Version: number, req: X402Requirement, auth: Eip3009Authorization, signature: string, resource?: X402PaymentRequired['resource'], extensions?: Record<string, unknown>): Record<string, unknown>;
+/** 16-128 chars of [A-Za-z0-9_-], the shape the payment-identifier extension accepts. */
+export declare function generatePaymentId(): string;
+/**
+ * x402 v2 "payment-identifier" extension: the server may ask for a client-chosen
+ * id so it can de-duplicate retries. The 402's extensions are echoed back with
+ * info.id filled in. Other extensions pass through untouched.
+ */
+export declare function withPaymentIdentifier(extensions?: Record<string, unknown>, id?: string): Record<string, unknown> | null;
+export declare function paymentHeaderFor(x402Version: number, payload: Record<string, unknown>): {
+    name: string;
+    value: string;
+};
+/** v2 servers put the requirements in PAYMENT-REQUIRED; v1 servers put them in the JSON body. */
+export declare function parsePaymentRequired(getHeader: (name: string) => string | null | undefined, body: unknown): X402PaymentRequired | null;
+export declare function parseSettlement(getHeader: (name: string) => string | null | undefined): X402Settlement | null;
+/**
+ * Choose which accepts[] entry to pay. `exact` is the only scheme this client
+ * can sign today; `upto` needs Permit2 (a max authorization the seller settles
+ * below) and is refused rather than approximated with a full upfront transfer,
+ * which is what issue #6 caught. Returns the reason when nothing is payable.
+ */
+export declare function pickOption(accepts: X402Requirement[], resolveChainId: (network: string) => number | null, preferChain?: number): {
+    option: X402Requirement | null;
+    chainId: number | null;
+    reason?: string;
+};

package/build/x402-eip3009.js

@@ -0,0 +1,199 @@
+/**
+ * x402 "exact" scheme on EVM, done the way the spec says: an EIP-3009
+ * TransferWithAuthorization signed off-chain and handed to the resource server
+ * in the payment header. The facilitator settles it; the payer broadcasts
+ * nothing and pays no gas.
+ *
+ * Before v1.11.0 pay_x402 broadcast a plain ERC-20 transfer() and put the tx
+ * hash in the header. That only ever worked against AgentWallet's own paywalls
+ * (which verify by receipt); every standard x402 server rejected it (issue #7).
+ * The receipt-style flow is kept for those paywalls and detected by their
+ * shape, see isLegacyAgentWalletAccept().
+ *
+ * Wire formats, both supported (issue #7 endpoint speaks v1, newer servers v2):
+ *   v1: 402 body {x402Version:1, accepts:[{maxAmountRequired, asset, payTo, network:"base", ...}]}
+ *       request header  X-PAYMENT: base64({x402Version:1, scheme, network, payload:{signature, authorization}})
+ *       response header X-PAYMENT-RESPONSE
+ *   v2: 402 header PAYMENT-REQUIRED: base64({x402Version:2, resource, accepts:[{amount, asset, payTo, network:"eip155:8453", ...}]})
+ *       request header  PAYMENT-SIGNATURE: base64({x402Version:2, resource, accepted, payload:{signature, authorization}})
+ *       response header PAYMENT-RESPONSE
+ */
+import { randomBytes } from 'node:crypto';
+export const TRANSFER_WITH_AUTHORIZATION_TYPES = {
+    TransferWithAuthorization: [
+        { name: 'from', type: 'address' },
+        { name: 'to', type: 'address' },
+        { name: 'value', type: 'uint256' },
+        { name: 'validAfter', type: 'uint256' },
+        { name: 'validBefore', type: 'uint256' },
+        { name: 'nonce', type: 'bytes32' },
+    ],
+};
+/**
+ * AgentWallet's own paywalls (hifriendbot.com /x402/access/{id}) predate the
+ * spec's field names: no `asset`, token under `extra.token`, `requiredDecimals`
+ * present, and they verify a broadcast transfer by receipt. Anything with an
+ * `asset` is treated as standard x402.
+ */
+export function isLegacyAgentWalletAccept(a) {
+    if (a.asset)
+        return false;
+    return Boolean(a.extra?.token) || typeof a.requiredDecimals === 'number';
+}
+/** Required amount in base units, whichever spelling the server used. */
+export function requiredAmount(a) {
+    const v = a.amount ?? a.maxAmountRequired ?? '';
+    return String(v);
+}
+export function createNonce() {
+    return ('0x' + randomBytes(32).toString('hex'));
+}
+const DEFAULT_TIMEOUT_SECONDS = 300;
+/** Authorization window mirrors the reference client: valid from 10 minutes ago until maxTimeoutSeconds from now. */
+export function buildAuthorization(from, req, nowSeconds = Math.floor(Date.now() / 1000), nonce = createNonce()) {
+    const value = requiredAmount(req);
+    if (!/^\d+$/.test(value))
+        throw new Error(`x402: invalid required amount "${value}" (expected integer base units).`);
+    if (!/^0x[0-9a-fA-F]{40}$/.test(req.payTo))
+        throw new Error(`x402: payTo is not an EVM address: "${req.payTo}".`);
+    const timeout = Number.isFinite(req.maxTimeoutSeconds) && req.maxTimeoutSeconds > 0
+        ? Math.floor(req.maxTimeoutSeconds) : DEFAULT_TIMEOUT_SECONDS;
+    return {
+        from: from,
+        to: req.payTo,
+        value,
+        validAfter: String(nowSeconds - 600),
+        validBefore: String(nowSeconds + timeout),
+        nonce,
+    };
+}
+/** EIP-712 typed data for the authorization. `name`/`version` are the token's own domain values. */
+export function typedDataFor(chainId, asset, name, version, auth) {
+    return {
+        domain: { name, version, chainId, verifyingContract: asset },
+        types: TRANSFER_WITH_AUTHORIZATION_TYPES,
+        primaryType: 'TransferWithAuthorization',
+        message: {
+            from: auth.from,
+            to: auth.to,
+            value: BigInt(auth.value),
+            validAfter: BigInt(auth.validAfter),
+            validBefore: BigInt(auth.validBefore),
+            nonce: auth.nonce,
+        },
+    };
+}
+/**
+ * Token EIP-712 domains we know without asking the chain. USDC's domain name
+ * differs by deployment ("USD Coin" on most mainnets, "USDC" on Base Sepolia),
+ * which is exactly the kind of thing that silently produces an unrecoverable
+ * signature, so only well-known deployments are listed; anything else is read
+ * from the contract's name()/version().
+ */
+export const KNOWN_TOKEN_DOMAINS = {
+    '8453:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913': { name: 'USD Coin', version: '2' }, // USDC Base
+    '84532:0x036cbd53842c5426634e7929541ec2318f3dcf7e': { name: 'USDC', version: '2' }, // USDC Base Sepolia
+    '1:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48': { name: 'USD Coin', version: '2' }, // USDC Ethereum
+    '137:0x3c499c542cef5e3811e1192ce70d8cc03d5c3359': { name: 'USD Coin', version: '2' }, // USDC Polygon (native)
+    '42161:0xaf88d065e77c8cc2239327c5edb3a432268e5831': { name: 'USD Coin', version: '2' }, // USDC Arbitrum
+    '10:0x0b2c639c533813f4aa9d7837caf62653d097ff85': { name: 'USD Coin', version: '2' }, // USDC Optimism
+    '43114:0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e': { name: 'USD Coin', version: '2' }, // USDC Avalanche
+};
+export function knownTokenDomain(chainId, asset) {
+    return KNOWN_TOKEN_DOMAINS[`${chainId}:${asset.toLowerCase()}`] ?? null;
+}
+/** Decode a single ABI-encoded string return value (name()/version()). */
+export function decodeAbiString(hex) {
+    const h = (hex || '').replace(/^0x/, '');
+    if (h.length < 128)
+        return '';
+    const len = parseInt(h.slice(64, 128), 16);
+    if (!Number.isFinite(len) || len <= 0 || len > 256)
+        return '';
+    const bytes = Buffer.from(h.slice(128, 128 + len * 2), 'hex');
+    return bytes.toString('utf8');
+}
+/** Build the payment payload the resource server expects for this x402 version. */
+export function buildPaymentPayload(x402Version, req, auth, signature, resource, extensions) {
+    const payload = { signature, authorization: auth };
+    if (x402Version >= 2) {
+        const out = { x402Version, accepted: req, payload };
+        if (resource)
+            out.resource = resource;
+        const ext = withPaymentIdentifier(extensions);
+        if (ext)
+            out.extensions = ext;
+        return out;
+    }
+    return { x402Version: 1, scheme: req.scheme, network: req.network, payload };
+}
+/** 16-128 chars of [A-Za-z0-9_-], the shape the payment-identifier extension accepts. */
+export function generatePaymentId() {
+    return 'agw_' + randomBytes(16).toString('hex');
+}
+/**
+ * x402 v2 "payment-identifier" extension: the server may ask for a client-chosen
+ * id so it can de-duplicate retries. The 402's extensions are echoed back with
+ * info.id filled in. Other extensions pass through untouched.
+ */
+export function withPaymentIdentifier(extensions, id) {
+    if (!extensions || typeof extensions !== 'object')
+        return null;
+    const out = { ...extensions };
+    const pid = out['payment-identifier'];
+    if (pid && typeof pid === 'object' && pid.info && typeof pid.info === 'object') {
+        out['payment-identifier'] = { ...pid, info: { ...pid.info, id: pid.info.id || id || generatePaymentId() } };
+    }
+    return out;
+}
+export function paymentHeaderFor(x402Version, payload) {
+    const value = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64');
+    return { name: x402Version >= 2 ? 'PAYMENT-SIGNATURE' : 'X-PAYMENT', value };
+}
+function decodeBase64Json(v) {
+    if (!v)
+        return null;
+    try {
+        const parsed = JSON.parse(Buffer.from(v.trim(), 'base64').toString('utf8'));
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** v2 servers put the requirements in PAYMENT-REQUIRED; v1 servers put them in the JSON body. */
+export function parsePaymentRequired(getHeader, body) {
+    const fromHeader = decodeBase64Json(getHeader('PAYMENT-REQUIRED') ?? getHeader('payment-required'));
+    if (fromHeader && Array.isArray(fromHeader.accepts))
+        return fromHeader;
+    if (body && typeof body === 'object' && Array.isArray(body.accepts)) {
+        return body;
+    }
+    return null;
+}
+export function parseSettlement(getHeader) {
+    return (decodeBase64Json(getHeader('PAYMENT-RESPONSE') ?? getHeader('payment-response'))
+        ?? decodeBase64Json(getHeader('X-PAYMENT-RESPONSE') ?? getHeader('x-payment-response')));
+}
+/**
+ * Choose which accepts[] entry to pay. `exact` is the only scheme this client
+ * can sign today; `upto` needs Permit2 (a max authorization the seller settles
+ * below) and is refused rather than approximated with a full upfront transfer,
+ * which is what issue #6 caught. Returns the reason when nothing is payable.
+ */
+export function pickOption(accepts, resolveChainId, preferChain) {
+    const payable = accepts.filter(a => a.scheme === 'exact' && resolveChainId(a.network) !== null);
+    if (payable.length === 0) {
+        const schemes = Array.from(new Set(accepts.map(a => a.scheme))).join(', ') || 'none';
+        const reason = accepts.some(a => a.scheme === 'upto')
+            ? 'This endpoint only offers the x402 "upto" scheme (Permit2 max-authorization settled by usage). ' +
+                'AgentWallet does not sign upto authorizations yet and will not approximate one with an upfront transfer. ' +
+                'Ask the endpoint for an "exact" option, or wait for Permit2 support.'
+            : `No payable option: schemes offered were ${schemes}.`;
+        return { option: null, chainId: null, reason };
+    }
+    let option = payable[0];
+    if (preferChain)
+        option = payable.find(a => resolveChainId(a.network) === preferChain) ?? option;
+    return { option, chainId: resolveChainId(option.network) };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentwallet-mcp",
   "mcpName": "io.github.hifriendbot/agentwallet",
-  "version": "1.10.9",
+  "version": "1.11.0",
   "description": "MCP server for AgentWallet: self-custody local signing on EVM and Solana, or hosted wallets. Sign, broadcast, pay x402 invoices, and accept x402 payments.",
   "type": "module",
   "main": "build/index.js",
@@ -16,7 +16,7 @@
   "scripts": {
     "build": "tsc",
     "start": "node build/index.js",
-    "test": "node test/x402-payment.test.mjs && node test/token-cap.test.mjs && node test/spl-cap.test.mjs && node test/unknown-decimals-cap.test.mjs && node test/local-mode.test.mjs && node test/ssrf-guard.test.mjs",
+    "test": "node test/x402-payment.test.mjs && node test/eip3009.test.mjs && node test/token-cap.test.mjs && node test/spl-cap.test.mjs && node test/unknown-decimals-cap.test.mjs && node test/local-mode.test.mjs && node test/ssrf-guard.test.mjs",
     "prepublishOnly": "npm run build"
   },
   "keywords": [