agentwallet-mcp 1.10.9 → 1.12.0

package/README.md

@@ -172,7 +172,10 @@ Add to your settings:
 | `get_allowance` | Check ERC-20 token allowance |
 | `wrap_eth` | Wrap native tokens to WETH/WAVAX/etc. |
 | `unwrap_eth` | Unwrap WETH back to native tokens |
-| `pay_x402` | Pay x402 invoices automatically (fetch, pay, retry) |
+| `pay_x402` | Pay x402 invoices (exact via EIP-3009, upto via Permit2), with approvals above the cap |
+| `check_approval` | Status of a human approval created by an over-cap `pay_x402` |
+| `approve_permit2` | One-time token approval to Permit2 for `upto` endpoints |
+| `check_token_risk` | Honeypot, tax, owner-power and holder-concentration flags for a token |
 | `create_paywall` | Create an x402 paywall to charge for a resource |
 | `list_paywalls` | List all your x402 paywalls |
 | `get_paywall` | Get paywall details by ID |
@@ -219,15 +222,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 +240,24 @@ 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` (EIP-3009, gasless for the payer) is preferred and works on every EVM chain AgentWallet knows. `upto` (a Permit2 maximum the seller settles at actual usage) is signed as a `PermitWitnessTransferFrom` bound to the endpoint's facilitator; it needs a one-time `approve_permit2` per token (or `AGENTWALLET_PERMIT2_AUTO_APPROVE=1`). An `upto` option without `extra.facilitatorAddress` is refused, never approximated with an upfront transfer. 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.
+
+**Approvals above the cap.** On a hosted wallet, a payment above the cap does not have to fail. With `request_approval` (default on; `AGENTWALLET_APPROVALS=0` turns it off) the wallet owner gets an email with approve and deny links, `pay_x402` returns an `approval_id`, and the agent retries with it once `check_approval` says approved. An approval is bound to one wallet, chain, asset, recipient and maximum, expires in 24 hours, and is consumed by one signature. Local mode has no approval channel: the caps in your environment are the policy.
+
+**Asset risk.** `check_token_risk` (and every `approve_token` result) reports honeypot, tax, owner-power, verified-source, holder-concentration and liquidity flags from GoPlus Security, with an on-chain fallback. A warning for the caller to weigh, never a block.
+
+**Proof.** Real settlements are listed in [PAYMENTS.md](PAYMENTS.md); the first is a 0.02 USDC `exact` payment on Base with the facilitator paying the gas.
+
+## Pay any x402 API from Claude in three steps
+
+1. Add the server (one of the snippets under Quick Start). Self-custody: set `AGENTWALLET_PRIVATE_KEY` to a key that holds USDC on Base. Hosted: `AGENTWALLET_USER` and `AGENTWALLET_PASS` from hifriendbot.com/wallet.
+2. Ask: *"Use pay_x402 to POST https://api.ozdreamtools.de/api/holidays with body {"year":2026,"state":"BY"} and a max_payment of 0.05."*
+3. Read the result: `payment_made: true`, the amount, `payment_method`, and `settlement.transaction`, the on-chain hash. No ETH needed for `exact`: the endpoint's facilitator pays the gas.
+
+
+**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,10 @@ 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, localSignPermit2Upto } from './local-wallet.js';
+import { buildUptoAuthorization, uptoPayload, permit2AllowanceCalldata, permit2ApproveCalldata, decodeUint, PERMIT2_ADDRESS, } from './x402-permit2.js';
+import { assessTokenRisk } from './token-risk.js';
+import { isLegacyAgentWalletAccept, requiredAmount, buildAuthorization, buildPaymentPayload, buildPaymentPayloadRaw, 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 +94,40 @@ 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 /wallets/{id}/x402/permit2  (x402 "upto": Permit2 max-authorization, signed here)
+    if (method === 'POST' && /^\/wallets\/[^/]*\/x402\/permit2$/.test(rawPath)) {
+        if (!isLocalMode())
+            refuseMissingLocalKey('evm');
+        const chainId = localChainId(body, qs);
+        return localSignPermit2Upto(chainId, {
+            from: getLocalAddress(),
+            permitted: { token: String(body?.asset || ''), amount: String(body?.amount ?? '0') },
+            spender: String(body?.spender || ''),
+            nonce: String(body?.nonce ?? '0'),
+            deadline: String(body?.deadline ?? '0'),
+            witness: { to: String(body?.to || ''), facilitator: String(body?.facilitator || ''), validAfter: String(body?.valid_after ?? '0') },
+        });
+    }
+    // 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 +461,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.12.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.
 
@@ -765,6 +803,17 @@ server.tool('approve_token', 'Approve a spender contract to transfer ERC-20 toke
         rawAmount = parseUnits(amount, decimals);
     }
     const calldata = '0x095ea7b3' + padAddress(spender) + encodeUint256(rawAmount);
+    // Asset risk rides along with the approval (issue #13). It never blocks; it is the
+    // caller's call. Skipped for Permit2, which only moves what a signature allows.
+    let risk = null;
+    if (spender.toLowerCase() !== PERMIT2_ADDRESS.toLowerCase()) {
+        try {
+            risk = await assessTokenRisk(chain_id, token, (to, data) => ethCallHex(chain_id, to, data));
+        }
+        catch {
+            risk = null;
+        }
+    }
     const result = await api(`/wallets/${wallet_id}/send`, 'POST', {
         to: token,
         value: '0',
@@ -776,6 +825,7 @@ server.tool('approve_token', 'Approve a spender contract to transfer ERC-20 toke
         token,
         spender,
         amount: amount.toLowerCase() === 'max' ? 'unlimited' : amount,
+        risk,
     });
 });
 // ─── Tool: get_allowance ────────────────────────────────────────
@@ -935,11 +985,76 @@ 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, approvalId) {
+    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,
+        ...(approvalId ? { approval_id: approvalId } : {}),
+    }, { '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;
+}
+/** Sign a Permit2 upto authorization with whichever custody mode is active. */
+async function signPermit2(walletId, chainId, auth, approvalId) {
+    const r = (await api(`/wallets/${walletId}/x402/permit2`, 'POST', {
+        chain_id: chainId, asset: auth.permitted.token, amount: auth.permitted.amount, spender: auth.spender, permit2: PERMIT2_ADDRESS,
+        nonce: auth.nonce, deadline: auth.deadline, to: auth.witness.to, facilitator: auth.witness.facilitator, valid_after: auth.witness.validAfter,
+        ...(approvalId ? { approval_id: approvalId } : {}),
+    }, { 'X-AGW-SKIP-X402': 'true' }));
+    const sig = String(r?.signature || '');
+    if (!/^0x[0-9a-fA-F]{130}$/.test(sig))
+        throw new Error(`x402 upto: the wallet did not return a valid Permit2 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)'),
@@ -954,7 +1069,10 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
         'to allow a larger single payment.'),
     prefer_chain: z.number().int().optional().describe('Preferred chain ID if the server accepts payment on multiple chains ' +
         '(e.g. 8453 for Base, 1 for Ethereum)'),
-}, async ({ url, wallet_id, method, headers: headersJson, body: reqBody, max_payment, prefer_chain }) => {
+    request_approval: z.boolean().optional().describe('Hosted wallets only. When the payment exceeds the cap, email the wallet owner an approve/deny link ' +
+        'instead of refusing, and return an approval_id to retry with. Default true unless AGENTWALLET_APPROVALS=0.'),
+    approval_id: z.string().optional().describe('An approval id from an earlier over-cap attempt. Once the owner has approved it, pass it here to make that one payment.'),
+}, async ({ url, wallet_id, method, headers: headersJson, body: reqBody, max_payment, prefer_chain, request_approval, approval_id }) => {
     // Build request headers
     const reqHeaders = { Accept: 'application/json' };
     if (headersJson) {
@@ -999,125 +1117,171 @@ 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];
-    }
-    // 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.`);
-    }
-    // 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)
-        : 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.
-    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)) {
+        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 (EIP-3009) first, then a signable upto (Permit2).
+    const picked = pickOption(accepts, resolveChainId, prefer_chain);
+    if (!picked.option || !picked.chainId) {
         return jsonResponse({
             status: 402,
             payment_required: true,
             payment_made: false,
-            error: `Payment of ${amount} ${option.extra?.name || 'tokens'} 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',
-            network: option.network,
-            chain_id: chainId,
-            pay_to: option.payTo,
-            description: option.description,
+            error: picked.reason,
+            offered: accepts.map(a => ({ scheme: a.scheme, network: a.network, amount: requiredAmount(a), asset: a.asset ?? a.extra?.token ?? null })),
         });
     }
-    // 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 option = picked.option;
+    const chainId = picked.chainId;
+    const isUpto = option.scheme === 'upto';
+    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 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 || '';
-    // 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,
-            }));
+    const trustedDecimals = tokenAddress
+        ? await resolveTrustedDecimals(chainId, tokenAddress)
+        : nativeDecimals(chainId); // 18 on EVM (wei), 9 on Solana (lamports)
+    if (typeof option.requiredDecimals === 'number')
+        assertDeclaredDecimals(option.requiredDecimals, trustedDecimals);
+    const amount = formatUnits(rawAmount, trustedDecimals);
+    const tokenLabel = option.extra?.name || (tokenAddress ? 'tokens' : 'native');
+    const skip = { 'X-AGW-SKIP-X402': 'true' };
+    // Step 4: Hard per-payment cap, ALWAYS applied. If the caller omits max_payment
+    // we fall back to AGENTWALLET_MAX_AUTOPAY (default "1"). Above the cap a hosted
+    // wallet can ask its owner instead of refusing: an approval is created, the
+    // owner gets approve/deny links by email, and the agent retries with the id.
+    // For upto the cap applies to the MAXIMUM the seller may settle.
+    const capSource = max_payment ? 'max_payment' : 'AGENTWALLET_MAX_AUTOPAY';
+    const effectiveMax = max_payment || process.env.AGENTWALLET_MAX_AUTOPAY || '1';
+    let approvalUsed = null;
+    if (!isWithinCap(rawAmount, trustedDecimals, effectiveMax)) {
+        const overCap = {
+            status: 402, payment_required: true, payment_made: false,
+            required_amount: amount, max_allowed: effectiveMax, cap_source: capSource, token: tokenLabel,
+            network: option.network, chain_id: chainId, pay_to: option.payTo, description: option.description,
+        };
+        const wantApproval = request_approval ?? (process.env.AGENTWALLET_APPROVALS !== '0');
+        if (approval_id) {
+            const a = (await api(`/approvals/${encodeURIComponent(approval_id)}`, 'GET', undefined, skip));
+            if (a?.status !== 'approved') {
+                return jsonResponse({ ...overCap, approval_id, approval_status: a?.status ?? null, error: `Approval ${approval_id} is ${a?.status ?? 'unknown'}, not approved.${a?.error ? ' ' + a.error : ''}` });
+            }
+            if (String(a.pay_to || '').toLowerCase() !== option.payTo.toLowerCase() || Number(a.chain_id) !== chainId || BigInt(String(a.value || '0')) < BigInt(rawAmount)) {
+                return jsonResponse({ ...overCap, approval_id, error: 'Approval does not cover this payment (recipient, chain or amount differ).' });
+            }
+            approvalUsed = String(approval_id);
+        }
+        else if (wantApproval && !anyLocalMode()) {
+            const created = (await api('/approvals', 'POST', {
+                wallet_id, chain_id: chainId, scheme: option.scheme, asset: tokenAddress, pay_to: option.payTo, value: rawAmount,
+                amount_human: amount, token_name: tokenLabel, url,
+            }, skip));
+            if (!created?.id) {
+                return jsonResponse({ ...overCap, error: `Payment of ${amount} ${tokenLabel} exceeds the ${effectiveMax} cap and the approval request failed: ${created?.error || 'unknown error'}.` });
+            }
+            return jsonResponse({
+                ...overCap, approval_pending: true, approval_id: String(created.id), expires_at: created.expires_at ?? null,
+                error: `Payment of ${amount} ${tokenLabel} exceeds the ${effectiveMax} cap (from ${capSource}). The wallet owner has been emailed approve/deny links ` +
+                    `(approval ${created.id}, valid 24 hours). Check it with check_approval, then call pay_x402 again with approval_id "${created.id}".`,
+            });
         }
         else {
-            // Native SOL payment
-            txResult = (await api(`/wallets/${wallet_id}/send`, 'POST', {
-                to: option.payTo,
-                value: option.maxAmountRequired,
-                chain_id: chainId,
-            }));
+            return jsonResponse({
+                ...overCap,
+                error: `Payment of ${amount} ${tokenLabel} exceeds the ${effectiveMax} cap (from ${capSource}).` +
+                    (max_payment ? '' : ' No max_payment was provided, so the default cap was applied.') +
+                    (anyLocalMode() ? ' Local mode has no approval channel: raise max_payment, AGENTWALLET_MAX_AUTOPAY or AGENTWALLET_MAX_TX_TOKEN yourself.'
+                        : ' Pass request_approval=true to email the wallet owner for a one-time approval, or raise the cap.'),
+            });
         }
     }
-    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,
-        }));
+    // Step 5: Pay. Standard x402 "exact" on EVM is an EIP-3009 authorization the
+    // facilitator settles; "upto" is a Permit2 max-authorization settled at actual
+    // usage; the payer broadcasts nothing and pays no gas for either. AgentWallet's
+    // own paywalls (verified by receipt), native-asset requests and Solana still use
+    // a broadcast transfer proved by hash.
+    const standardExact = !isUpto && !isSolanaChain(chainId) && Boolean(tokenAddress) && !isLegacyAgentWalletAccept(option);
+    let headerName = 'X-PAYMENT';
+    let paymentHeader = '';
+    let txHash = null;
+    let authorization = null;
+    let uptoAuth = null;
+    let payer = null;
+    let permit2ApprovalTx = null;
+    if (isUpto) {
+        payer = await payerAddress(wallet_id);
+        const allowance = decodeUint(await ethCallHex(chainId, tokenAddress, permit2AllowanceCalldata(payer)));
+        if (allowance < BigInt(rawAmount)) {
+            if (process.env.AGENTWALLET_PERMIT2_AUTO_APPROVE === '1') {
+                const r = (await api(`/wallets/${wallet_id}/send`, 'POST', { to: tokenAddress, value: '0', data: permit2ApproveCalldata(), chain_id: chainId }, skip));
+                permit2ApprovalTx = String(r?.tx_hash || '');
+                await new Promise(res => setTimeout(res, 4000));
+            }
+            else {
+                return jsonResponse({
+                    status: 402, payment_required: true, payment_made: false, permit2_approval_needed: true,
+                    token: tokenLabel, token_address: tokenAddress, chain_id: chainId, payer, permit2: PERMIT2_ADDRESS,
+                    error: `This endpoint uses the x402 "upto" scheme, which settles through Permit2. Wallet ${payer} has not approved ` +
+                        `${tokenLabel} to Permit2 on chain ${chainId}. Call approve_permit2 once for this token (a normal transaction that needs gas), ` +
+                        `or set AGENTWALLET_PERMIT2_AUTO_APPROVE=1, then call pay_x402 again.`,
+                });
+            }
+        }
+        uptoAuth = buildUptoAuthorization(payer, option);
+        const signature = await signPermit2(wallet_id, chainId, uptoAuth, approvalUsed);
+        const payload = buildPaymentPayloadRaw(x402Version, option, uptoPayload(uptoAuth, signature), paymentInfo.resource, paymentInfo.extensions);
+        const h = paymentHeaderFor(x402Version, payload);
+        headerName = h.name;
+        paymentHeader = h.value;
+    }
+    else 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, approvalUsed);
+        const payload = buildPaymentPayload(x402Version, option, authorization, signature, paymentInfo.resource, paymentInfo.extensions);
+        const h = paymentHeaderFor(x402Version, payload);
+        headerName = h.name;
+        paymentHeader = h.value;
     }
     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 };
+        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 {
+            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');
+    }
+    // Step 6: Retry with the payment header and read the settlement receipt.
+    const retryHeaders = { ...reqHeaders, [headerName]: paymentHeader };
     const retryOptions = {
         method,
         headers: retryHeaders,
@@ -1135,21 +1299,61 @@ 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: isUpto ? 'permit2-upto-authorization' : (standardExact ? 'eip3009-authorization' : 'onchain-transfer'),
+        approval_id: approvalUsed,
+        permit2_approval_tx: permit2ApprovalTx,
+        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 }
+            : (uptoAuth ? { scheme: 'upto', max_amount: amount, nonce: uptoAuth.nonce, deadline: uptoAuth.deadline, facilitator: uptoAuth.witness.facilitator } : null),
         description: option.description,
         response: retryParsed,
     });
 });
+// ─── Tool: check_approval ───────────────────────────────────────
+server.tool('check_approval', 'Status of a payment approval created when pay_x402 exceeded the cap on a hosted wallet. ' +
+    'Returns pending, approved, denied or expired. Once approved, call pay_x402 again with approval_id.', { approval_id: z.string().describe('Approval id returned by pay_x402') }, async ({ approval_id }) => jsonResponse(await api(`/approvals/${encodeURIComponent(approval_id)}`, 'GET', undefined, { 'X-AGW-SKIP-X402': 'true' })));
+// ─── Tool: approve_permit2 ──────────────────────────────────────
+server.tool('approve_permit2', 'One-time ERC-20 approval of a token to the Permit2 contract, needed before paying x402 "upto" endpoints with that token. ' +
+    'A normal on-chain transaction (needs gas). Approves the maximum so it never has to be repeated; Permit2 itself only moves ' +
+    'what each signed authorization allows.', {
+    wallet_id: z.number().int().describe('Wallet ID'),
+    token: z.string().regex(/^0x[a-fA-F0-9]{40}$/).describe('ERC-20 token address (e.g. USDC on Base)'),
+    chain_id: z.number().int().describe('Chain ID'),
+}, async ({ wallet_id, token, chain_id }) => {
+    if (isSolanaChain(chain_id))
+        throw new Error('Permit2 is an EVM contract; there is nothing to approve on Solana.');
+    const result = (await api(`/wallets/${wallet_id}/send`, 'POST', { to: token, value: '0', data: permit2ApproveCalldata(), chain_id }));
+    return jsonResponse({ ...result, token, spender: PERMIT2_ADDRESS, amount: 'unlimited', note: 'Permit2 only transfers what a signed authorization allows; the allowance itself moves nothing.' });
+});
+// ─── Tool: check_token_risk ─────────────────────────────────────
+server.tool('check_token_risk', 'Assess an ERC-20 token before approving or swapping it: honeypot, taxes, owner powers, verified source, ' +
+    'holder concentration, DEX liquidity. Uses GoPlus Security (free, no key) with an on-chain fallback. ' +
+    'A warning for the caller to weigh, never a block.', {
+    token: z.string().regex(/^0x[a-fA-F0-9]{40}$/).describe('ERC-20 token contract address'),
+    chain_id: z.number().int().describe('Chain ID'),
+}, async ({ token, chain_id }) => jsonResponse({ token, chain_id, risk: await assessTokenRisk(chain_id, token, (to, data) => ethCallHex(chain_id, to, data)) }));
 // ─── Tool: get_usage ─────────────────────────────────────────────
 server.tool('get_usage', 'Get the current month\'s usage statistics. ' +
     'Returns operations count, tier info, remaining quota, and fees.', {}, async () => {

package/build/local-wallet.d.ts

@@ -15,6 +15,8 @@
  * 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';
+import { type UptoPermit2Authorization } from './x402-permit2.js';
 /** True when the server is running non-custodially. */
 export declare function isLocalMode(): boolean;
 export declare function getLocalAccount(): {
@@ -88,3 +90,27 @@ 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;
+}>;
+/** x402 "upto": sign a Permit2 max-authorization in-process. The maximum goes through the token cap like a transfer would. */
+export declare function localSignPermit2Upto(chainId: number, auth: UptoPermit2Authorization): Promise<{
+    signature: `0x${string}`;
+    from: Address;
+    mode: 'local';
+}>;