@goplausible/algorand-mcp 4.2.7 → 4.2.8

package/README.md

@@ -21,7 +21,8 @@ Algorand is a carbon-negative, pure proof-of-stake Layer 1 blockchain with insta
 - TEAL compilation and disassembly
 - Full Algod and Indexer API access
 - NFDomains (NFD) name service integration
-- x402 and AP2 toolins for Algorand
+- x402 HTTP micropayments — automatic discovery and one-call paid requests using the active wallet (USDC/ALGO)
+- AP2 tooling for Algorand
 - Tinyman AMM integration (pools, swaps, liquidity)
 - Haystack Router DEX aggregation (best-price swaps across Tinyman, Pact, Folks)
 - Alpha Arcade prediction market trading (browse markets, orderbooks, limit/market orders, positions, claims)
@@ -319,6 +320,96 @@ The keychain backend is provided by [`@napi-rs/keyring`](https://github.com/nico
 
 All credentials are stored under the service name `algorand-mcp`. You can inspect them with your OS keychain app (e.g. Keychain Access on macOS).
 
+## x402 HTTP Payments
+
+[x402](https://x402.org) is an HTTP-native micropayments protocol. It uses the long-reserved `402 Payment Required` status as a real handshake: when a client requests a paid resource without paying, the server returns 402 with a JSON body listing what it accepts (networks, assets, amounts, the recipient address). The client constructs a payment, attaches it as an HTTP header, retries the same request, and the server returns 200 with the resource. No API keys, no Stripe webhooks, no accounts to manage — payment is part of the request itself.
+
+This MCP implements the Algorand flavor of x402, where payments are USDC (or native ALGO) transfers on Algorand. It exposes two tools that collapse the seven-step manual flow (probe → parse → opt-in check → build fee payer → build payment → group → sign → encode → header → retry) into a single tool call.
+
+### Protocol shape (Algorand variant)
+
+```
+  Agent (LLM)                  algorand-mcp                   Endpoint                Facilitator
+  ──────────                   ────────────                   ────────                ───────────
+       │                            │                            │                          │
+       │  make_http_request_       │                            │                          │
+       │  with_x402 { url, ... }   │                            │                          │
+       │ ────────────────────────► │  HTTP request              │                          │
+       │                            │ ─────────────────────────► │                          │
+       │                            │  402 PaymentRequired      │                          │
+       │                            │ ◄───────────────────────── │                          │
+       │                            │  pick accepts[i] for      │                          │
+       │                            │  Algorand network          │                          │
+       │                            │  build fee-payer + payment │                          │
+       │                            │  (atomic group of 2)       │                          │
+       │                            │  sign payment leg          │                          │
+       │                            │  via OS keychain           │                          │
+       │                            │  encode unsigned fee-payer │                          │
+       │                            │  base64 PAYMENT-SIGNATURE  │                          │
+       │                            │ ─────────────────────────► │                          │
+       │                            │  HTTP request +            │  forward + settle        │
+       │                            │  PAYMENT-SIGNATURE         │ ───────────────────────► │
+       │                            │                            │  sign fee-payer,         │
+       │                            │                            │  submit atomic group     │
+       │                            │  200 + resource            │ ◄─────────────────────── │
+       │                            │ ◄───────────────────────── │                          │
+       │ ◄─ { result, paid: {...}}│                            │                          │
+       │                            │                            │                          │
+```
+
+### What's different from the Coinbase/EVM version
+
+1. **Header name is `PAYMENT-SIGNATURE`**, not `X-PAYMENT`. The header body is base64-encoded JSON with `x402Version`, `scheme`, `network` (a CAIP-2 identifier like `algorand:wGHE2Pw…` for mainnet), a `payload`, and a verbatim copy of the `accepts[]` entry the client chose.
+2. **Payment is an atomic 2-transaction group.** Index 0 is a fee-payer transaction (sender = facilitator, amount = 0, fee = 2000 µAlgo for the whole group); index 1 is the actual USDC ASA transfer (sender = wallet, fee = 0). The wallet signs only index 1 — the facilitator signs index 0 server-side at settlement. The user's wallet pays only the USDC, not even network fees.
+3. **Network strings are Algorand CAIP-2.** This MCP recognizes mainnet (`wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=`) and testnet (`SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=`). Endpoints that only accept Base, Solana, or other non-Algorand networks are not satisfiable here and the tool returns a clear error.
+
+### Coinbase Wallet MCP compatibility (x402 surface)
+
+The x402 tools — `make_http_request_with_x402` and `x402_discover_payment_requirements` — are intentionally name- and shape-compatible with the Coinbase Wallet MCP's x402 tools. The input parameters (`baseURL`, `path`, `method`, `queryParams`, `body`, `headers`, `correlationId`, `maxAmountPerRequest`, `paymentRequirements`, `preferredNetwork`, `extensions`) are the same. The output envelope (`result`, `_atomicUnitsNote`) is the same.
+
+What this means in practice:
+- **Drop-in for Algorand x402.** Agents and MCP apps written against the Coinbase Wallet MCP's x402 tools work against this server without any prompt changes — they just hit Algorand x402 endpoints instead of Base/Solana ones.
+- **Same agent reflexes.** Models trained on tool-call traces from the Coinbase ecosystem use these tools correctly on first call. Nothing to relearn.
+- **Compatibility is scoped to the x402 surface only.** The wallet, account, transaction-building, and DEX tools in this MCP are Algorand-specific and do not mirror Coinbase's wallet API. Only `make_http_request_with_x402` and `x402_discover_payment_requirements` are drop-in compatible.
+
+The one parameter that necessarily differs: `preferredNetwork` accepts `mainnet | testnet | localnet` only (Algorand networks), because the wallet only signs Algorand transactions. Coinbase's enum lists `base | base-sepolia | solana | solana-devnet`. Agents that pass one of those values get a clear error indicating no Algorand-payable accepts entry exists.
+
+### Example — paid weather API
+
+```
+# Step 1 (optional): peek at the cost
+x402_discover_payment_requirements {
+  "baseURL": "https://example.x402.goplausible.xyz",
+  "path": "/weather",
+  "method": "GET"
+}
+# returns: { result: { accepts: [{ scheme: "exact", network: "algorand:SGO1...",
+#                                  maxAmountRequired: "100", asset: "10458941",
+#                                  payTo: "AAAA...", extra: { feePayer: "BBBB..." } }] } }
+
+# Step 2: pay and fetch in one call
+make_http_request_with_x402 {
+  "baseURL": "https://example.x402.goplausible.xyz",
+  "path": "/weather",
+  "method": "GET",
+  "maxAmountPerRequest": 10000,
+  "preferredNetwork": "testnet"
+}
+# returns: { result: <weather payload>, paid: { network: "testnet",
+#                                                asset: "10458941",
+#                                                amount: "100", payTo: "AAAA..." },
+#           paymentResponse: <decoded X-PAYMENT-RESPONSE> }
+```
+
+The active wallet account must be opted into the target ASA (e.g. USDC) and hold enough balance to cover `maxAmountRequired`. If it isn't opted in, the payment fails at settlement — opt in first with `wallet_optin_asset`.
+
+### Prerequisites
+
+- An active wallet account exists (`wallet_get_info` to verify)
+- That account is opted into the payment asset (USDC mainnet ASA `31566704`, testnet ASA `10458941`)
+- The account has enough of the payment asset for `maxAmountRequired`
+- The endpoint's `accepts[]` includes at least one entry with an Algorand network the MCP recognizes
+
 ## Optional Environment Variables
 
 Environment variables are only needed for special setups. Pass them via the `env` block in your MCP config.
@@ -368,6 +459,15 @@ See [Secure Wallet](#secure-wallet) for full architecture details.
 | `wallet_sign_data` | Sign arbitrary hex data with raw Ed25519 (noble, no SDK prefix) |
 | `wallet_optin_asset` | Opt the active account into an asset (creates, signs, and submits) |
 
+### x402 HTTP Payment Tools (2 tools)
+
+See [x402 HTTP Payments](#x402-http-payments) for the full protocol explanation.
+
+| Tool | Description |
+|---|---|
+| `x402_discover_payment_requirements` | Probe an x402-protected endpoint and return its `accepts[]` array (cost, asset, network, payTo) without paying. Read-only. |
+| `make_http_request_with_x402` | Call an x402-protected endpoint with automatic USDC/ALGO payment from the active wallet. Discovers internally if `paymentRequirements` is not supplied, builds the atomic fee-payer + payment group, signs, and retries with the `PAYMENT-SIGNATURE` header. |
+
 ### Account Management (8 tools)
 
 | Tool | Description |

package/dist/index.js

@@ -4,7 +4,7 @@ BigInt.prototype.toJSON = function () { return Number(this); };
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ErrorCode, ListResourcesRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema, PingRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { AccountManager, WalletManager, UtilityManager, TransactionManager, AlgodManager, transactionTools, apiManager, handleApiManager, arc26Manager, KnowledgeManager } from './tools/index.js';
+import { AccountManager, WalletManager, X402Manager, UtilityManager, TransactionManager, AlgodManager, transactionTools, apiManager, handleApiManager, arc26Manager, KnowledgeManager } from './tools/index.js';
 import { ResourceManager } from './resources/index.js';
 class AlgorandMcpServer {
     constructor(name = 'algorand-mcp-server', version = '2.7.5') {
@@ -72,6 +72,8 @@ class AlgorandMcpServer {
                 ...AccountManager.accountTools,
                 // Wallet Tools
                 ...WalletManager.walletTools,
+                // x402 Tools
+                ...X402Manager.x402Tools,
                 // Utility Tools
                 ...UtilityManager.utilityTools,
                 // Algod Tools
@@ -93,6 +95,10 @@ class AlgorandMcpServer {
             if (name.startsWith('wallet_')) {
                 return WalletManager.handleTool(name, args);
             }
+            // Handle x402 tools
+            if (name === 'make_http_request_with_x402' || name === 'x402_discover_payment_requirements') {
+                return X402Manager.handleTool(name, args);
+            }
             // Handle account tools
             if (name.startsWith('create_account') ||
                 name.startsWith('rekey_account') ||

package/dist/tools/index.d.ts

@@ -1,5 +1,6 @@
 export { AccountManager } from './accountManager.js';
 export { WalletManager } from './walletManager.js';
+export { X402Manager } from './x402Manager.js';
 export { KnowledgeManager } from './knowledgeManager.js';
 export { arc26Manager } from './arc26Manager.js';
 export { UtilityManager } from './utilityManager.js';

package/dist/tools/index.js

@@ -1,5 +1,6 @@
 export { AccountManager } from './accountManager.js';
 export { WalletManager } from './walletManager.js';
+export { X402Manager } from './x402Manager.js';
 export { KnowledgeManager } from './knowledgeManager.js';
 export { arc26Manager } from './arc26Manager.js';
 export { UtilityManager } from './utilityManager.js';

package/dist/tools/utilityManager.js

@@ -86,7 +86,7 @@ export class UtilityManager {
                                 type: 'text',
                                 text: JSON.stringify({
                                     name: 'Algorand MCP Server',
-                                    version: '4.2.7',
+                                    version: '4.2.8',
                                     builder: 'GoPlausible',
                                     description: 'A Model Context Protocol (MCP) server providing comprehensive access to the Algorand blockchain. Supports account management, transaction building and signing, smart contract interaction, asset operations, ARC-26 URI generation, and deep integration with Algorand ecosystem services including NFDomains, Tinyman, Vestige, and Ultrade.',
                                     blockchain: 'Algorand — a carbon-negative, pure proof-of-stake Layer 1 blockchain delivering instant finality, low fees, and advanced smart contract capabilities via AVM (Algorand Virtual Machine).',

package/dist/tools/x402Manager.d.ts

@@ -0,0 +1,25 @@
+export declare class X402Manager {
+    static readonly x402Tools: {
+        name: string;
+        description: string;
+        inputSchema: any;
+    }[];
+    static handleTool(name: string, args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    private static handleDiscover;
+    private static handlePaidRequest;
+    private static discover;
+    private static selectRequirement;
+    private static buildPaymentHeader;
+    private static httpRequest;
+    private static buildUrl;
+    private static requireHttpArgs;
+    private static tryParseJson;
+    private static decodeBase64Json;
+    private static snippet;
+    private static textResponse;
+}

package/dist/tools/x402Manager.js

@@ -0,0 +1,322 @@
+import algosdk from 'algosdk';
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { withCommonParams } from './commonParams.js';
+import { getAlgodClient, extractNetwork } from '../algorand-client.js';
+import { WalletManager } from './walletManager.js';
+// ── CAIP-2 ↔ MCP network mapping ─────────────────────────────────────────────
+const CAIP2_GENESIS_TO_NETWORK = {
+    'wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=': 'mainnet',
+    'SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=': 'testnet',
+};
+const NETWORK_TO_CAIP2 = {
+    mainnet: 'algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=',
+    testnet: 'algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=',
+    localnet: 'algorand:localnet',
+};
+function caip2ToNetwork(caip2) {
+    if (!caip2.startsWith('algorand:'))
+        return null;
+    const hash = caip2.slice('algorand:'.length);
+    return CAIP2_GENESIS_TO_NETWORK[hash] ?? null;
+}
+const ATOMIC_UNITS_NOTE = 'USDC amounts are expressed in atomic units. 1,000,000 atomic units = $1.00 USDC (USDC has 6 decimals).';
+const HTTP_METHODS = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
+// ── Tool schemas ─────────────────────────────────────────────────────────────
+const x402ToolSchemas = {
+    discoverPaymentRequirements: {
+        type: 'object',
+        properties: {
+            baseURL: { type: 'string', description: 'Base URL of the x402-protected endpoint, e.g. https://example.x402.goplausible.xyz' },
+            path: { type: 'string', description: 'Path under baseURL, e.g. /weather' },
+            method: { type: 'string', enum: HTTP_METHODS, description: 'HTTP method to probe' },
+            queryParams: { type: 'object', description: 'Optional query string parameters', additionalProperties: { type: 'string' } },
+            body: { description: 'Optional request body. Strings are sent verbatim; objects are JSON-encoded.' },
+        },
+        required: ['baseURL', 'path', 'method'],
+    },
+    makeHttpRequestWithX402: {
+        type: 'object',
+        properties: {
+            baseURL: { type: 'string', description: 'Base URL of the x402-protected endpoint' },
+            path: { type: 'string', description: 'Path under baseURL' },
+            method: { type: 'string', enum: HTTP_METHODS, description: 'HTTP method' },
+            queryParams: { type: 'object', description: 'Optional query string parameters', additionalProperties: { type: 'string' } },
+            body: { description: 'Optional request body. Strings are sent verbatim; objects are JSON-encoded.' },
+            headers: { type: 'object', description: 'Optional additional request headers', additionalProperties: { type: 'string' } },
+            correlationId: { type: 'string', description: 'Optional correlation id; forwarded as X-Correlation-ID header' },
+            maxAmountPerRequest: { type: 'integer', description: 'Maximum payment in USDC atomic units (1,000,000 = $1.00). If a payment requirement exceeds this, the call is refused.' },
+            paymentRequirements: { type: 'array', description: 'Pre-fetched accepts[] array from a prior x402_discover_payment_requirements call. If omitted, this tool discovers internally.' },
+            preferredNetwork: { type: 'string', enum: ['mainnet', 'testnet', 'localnet'], description: 'Preferred Algorand network. When multiple accepts entries match, this network wins. If omitted, the active wallet network is used.' },
+            extensions: { type: 'object', description: 'Optional pre-fetched PaymentRequired extensions (e.g. Bazaar resource details). Passed through to the response under `extensions`.' },
+        },
+        required: ['baseURL', 'path', 'method'],
+    },
+};
+// ── X402Manager ──────────────────────────────────────────────────────────────
+export class X402Manager {
+    // ── Public dispatch ────────────────────────────────────────────────────────
+    static async handleTool(name, args) {
+        try {
+            switch (name) {
+                case 'x402_discover_payment_requirements':
+                    return await X402Manager.handleDiscover(args);
+                case 'make_http_request_with_x402':
+                    return await X402Manager.handlePaidRequest(args);
+                default:
+                    throw new McpError(ErrorCode.MethodNotFound, `Unknown x402 tool: ${name}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof McpError)
+                throw error;
+            throw new McpError(ErrorCode.InternalError, `x402 operation failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    // ── Tool handlers ──────────────────────────────────────────────────────────
+    static async handleDiscover(args) {
+        const { baseURL, path, method, queryParams, body } = X402Manager.requireHttpArgs(args);
+        const result = await X402Manager.discover({ baseURL, path, method, queryParams, body });
+        return X402Manager.textResponse({ result });
+    }
+    static async handlePaidRequest(args) {
+        const { baseURL, path, method, queryParams, body } = X402Manager.requireHttpArgs(args);
+        const headers = args.headers ?? {};
+        const correlationId = typeof args.correlationId === 'string' ? args.correlationId : undefined;
+        const maxAmountPerRequest = typeof args.maxAmountPerRequest === 'number' ? args.maxAmountPerRequest : undefined;
+        const preferredNetwork = typeof args.preferredNetwork === 'string' ? args.preferredNetwork : undefined;
+        const extensions = args.extensions ?? undefined;
+        let accepts = Array.isArray(args.paymentRequirements) ? args.paymentRequirements : undefined;
+        // 1. Discover if needed
+        if (!accepts || accepts.length === 0) {
+            const discovered = await X402Manager.discover({ baseURL, path, method, queryParams, body });
+            if (!discovered.x402 || !Array.isArray(discovered.accepts) || discovered.accepts.length === 0) {
+                throw new McpError(ErrorCode.InvalidRequest, `Endpoint did not return an x402 payment requirement (status ${discovered.status}). Use a non-x402 HTTP tool, or pass paymentRequirements explicitly.`);
+            }
+            accepts = discovered.accepts;
+        }
+        // 2. Select a requirement we can satisfy on Algorand
+        const { requirement, mcpNetwork } = X402Manager.selectRequirement(accepts, preferredNetwork, maxAmountPerRequest);
+        // 3. Build and sign the payment group
+        const paymentHeader = await X402Manager.buildPaymentHeader(requirement, mcpNetwork);
+        // 4. Retry with PAYMENT-SIGNATURE
+        const paidHeaders = { ...headers, 'PAYMENT-SIGNATURE': paymentHeader };
+        if (correlationId)
+            paidHeaders['X-Correlation-ID'] = correlationId;
+        const response = await X402Manager.httpRequest({ baseURL, path, method, queryParams, body, headers: paidHeaders });
+        if (response.status === 402) {
+            // Surface the server's rejection rather than retrying.
+            throw new McpError(ErrorCode.InvalidRequest, `Payment rejected by server: ${X402Manager.snippet(response.bodyText)}`);
+        }
+        const result = X402Manager.tryParseJson(response.bodyText) ?? response.bodyText;
+        const paymentResponseHeader = response.headers['x-payment-response'] ?? response.headers['X-PAYMENT-RESPONSE'];
+        return X402Manager.textResponse({
+            result,
+            status: response.status,
+            paymentResponse: paymentResponseHeader ? X402Manager.decodeBase64Json(paymentResponseHeader) : undefined,
+            paid: {
+                network: mcpNetwork,
+                asset: requirement.asset,
+                amount: requirement.maxAmountRequired,
+                payTo: requirement.payTo,
+            },
+            extensions,
+        });
+    }
+    // ── x402 protocol helpers ──────────────────────────────────────────────────
+    static async discover(opts) {
+        const response = await X402Manager.httpRequest(opts);
+        if (response.status !== 402) {
+            return { status: response.status, x402: false, rawBody: X402Manager.tryParseJson(response.bodyText) ?? response.bodyText };
+        }
+        const parsed = X402Manager.tryParseJson(response.bodyText);
+        if (!parsed ||
+            typeof parsed !== 'object' ||
+            typeof parsed.x402Version !== 'number' ||
+            !Array.isArray(parsed.accepts)) {
+            return { status: 402, x402: false, rawBody: parsed ?? response.bodyText };
+        }
+        const body = parsed;
+        return { status: 402, x402: true, accepts: body.accepts, x402Version: body.x402Version };
+    }
+    static selectRequirement(accepts, preferredNetwork, maxAmountPerRequest) {
+        // Map each accepts entry to its MCP network (or null if non-Algorand).
+        const ranked = accepts
+            .map(req => ({ req, mcpNetwork: caip2ToNetwork(req.network) }))
+            .filter((e) => e.mcpNetwork !== null);
+        if (ranked.length === 0) {
+            throw new McpError(ErrorCode.InvalidRequest, `No payment requirement is satisfiable on Algorand. Endpoint accepts networks: [${accepts.map(r => r.network).join(', ')}]`);
+        }
+        const inBudget = (req) => maxAmountPerRequest === undefined || Number(req.maxAmountRequired) <= maxAmountPerRequest;
+        const affordable = ranked.filter(e => inBudget(e.req));
+        if (affordable.length === 0) {
+            throw new McpError(ErrorCode.InvalidRequest, `All Algorand payment requirements exceed maxAmountPerRequest=${maxAmountPerRequest}. Cheapest: ${Math.min(...ranked.map(e => Number(e.req.maxAmountRequired)))}.`);
+        }
+        if (preferredNetwork) {
+            const preferred = affordable.find(e => e.mcpNetwork === preferredNetwork);
+            if (preferred)
+                return { requirement: preferred.req, mcpNetwork: preferred.mcpNetwork };
+        }
+        // No preference (or preference not matched): pick the cheapest affordable.
+        const chosen = affordable.reduce((a, b) => Number(a.req.maxAmountRequired) <= Number(b.req.maxAmountRequired) ? a : b);
+        return { requirement: chosen.req, mcpNetwork: chosen.mcpNetwork };
+    }
+    static async buildPaymentHeader(requirement, mcpNetwork) {
+        const feePayer = requirement.extra?.feePayer;
+        if (!feePayer || typeof feePayer !== 'string') {
+            throw new McpError(ErrorCode.InvalidRequest, 'Payment requirement is missing `extra.feePayer` (facilitator address).');
+        }
+        const amount = Number(requirement.maxAmountRequired);
+        if (!Number.isFinite(amount) || amount < 0) {
+            throw new McpError(ErrorCode.InvalidRequest, `Invalid maxAmountRequired: ${requirement.maxAmountRequired}`);
+        }
+        const account = await WalletManager.getActiveWalletAccount();
+        const sk = await WalletManager.getActiveWalletSecretKey();
+        const algodClient = getAlgodClient(mcpNetwork);
+        const suggestedParams = await algodClient.getTransactionParams().do();
+        // Fee payer covers fees for both txns in the group.
+        const feePayerParams = { ...suggestedParams, fee: BigInt(2000), flatFee: true };
+        const innerParams = { ...suggestedParams, fee: BigInt(0), flatFee: true };
+        const feePayerTxn = algosdk.makePaymentTxnWithSuggestedParamsFromObject({
+            sender: feePayer,
+            receiver: feePayer,
+            amount: 0,
+            suggestedParams: feePayerParams,
+        });
+        const isAlgo = requirement.asset === '0' || requirement.asset === '';
+        const paymentTxn = isAlgo
+            ? algosdk.makePaymentTxnWithSuggestedParamsFromObject({
+                sender: account.address,
+                receiver: requirement.payTo,
+                amount,
+                suggestedParams: innerParams,
+            })
+            : algosdk.makeAssetTransferTxnWithSuggestedParamsFromObject({
+                sender: account.address,
+                receiver: requirement.payTo,
+                assetIndex: Number(requirement.asset),
+                amount,
+                suggestedParams: innerParams,
+            });
+        const grouped = algosdk.assignGroupID([feePayerTxn, paymentTxn]);
+        const groupedFeePayer = grouped[0];
+        const groupedPayment = grouped[1];
+        const signedPayment = algosdk.signTransaction(groupedPayment, sk);
+        const unsignedFeePayer = algosdk.encodeUnsignedTransaction(groupedFeePayer);
+        const headerBody = {
+            x402Version: 2,
+            scheme: requirement.scheme,
+            network: requirement.network,
+            payload: {
+                paymentGroup: [
+                    algosdk.bytesToBase64(unsignedFeePayer),
+                    algosdk.bytesToBase64(signedPayment.blob),
+                ],
+                paymentIndex: 1,
+            },
+            accepted: requirement,
+        };
+        return Buffer.from(JSON.stringify(headerBody), 'utf8').toString('base64');
+    }
+    // ── HTTP helpers ───────────────────────────────────────────────────────────
+    static async httpRequest(opts) {
+        var _a;
+        const url = X402Manager.buildUrl(opts.baseURL, opts.path, opts.queryParams);
+        const init = { method: opts.method, headers: { ...(opts.headers ?? {}) } };
+        if (opts.body !== undefined && opts.method !== 'GET') {
+            if (typeof opts.body === 'string') {
+                init.body = opts.body;
+            }
+            else {
+                init.body = JSON.stringify(opts.body);
+                (_a = init.headers)['content-type'] ?? (_a['content-type'] = 'application/json');
+            }
+        }
+        const response = await fetch(url, init);
+        const bodyText = await response.text();
+        const headers = {};
+        response.headers.forEach((value, key) => { headers[key.toLowerCase()] = value; });
+        return { status: response.status, bodyText, headers };
+    }
+    static buildUrl(baseURL, path, queryParams) {
+        const base = baseURL.endsWith('/') ? baseURL.slice(0, -1) : baseURL;
+        const tail = path.startsWith('/') ? path : `/${path}`;
+        const url = new URL(base + tail);
+        if (queryParams) {
+            for (const [k, v] of Object.entries(queryParams))
+                url.searchParams.set(k, String(v));
+        }
+        return url.toString();
+    }
+    // ── Misc helpers ───────────────────────────────────────────────────────────
+    static requireHttpArgs(args) {
+        const baseURL = typeof args.baseURL === 'string' ? args.baseURL : null;
+        const path = typeof args.path === 'string' ? args.path : null;
+        const method = typeof args.method === 'string' ? args.method.toUpperCase() : null;
+        if (!baseURL)
+            throw new McpError(ErrorCode.InvalidParams, 'baseURL (string) is required');
+        if (!path)
+            throw new McpError(ErrorCode.InvalidParams, 'path (string) is required');
+        if (!method || !HTTP_METHODS.includes(method)) {
+            throw new McpError(ErrorCode.InvalidParams, `method must be one of: ${HTTP_METHODS.join(', ')}`);
+        }
+        try {
+            new URL(baseURL);
+        }
+        catch {
+            throw new McpError(ErrorCode.InvalidParams, `baseURL is not a valid URL: ${baseURL}`);
+        }
+        return {
+            baseURL,
+            path,
+            method: method,
+            queryParams: args.queryParams,
+            body: args.body,
+        };
+    }
+    static tryParseJson(text) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+    }
+    static decodeBase64Json(b64) {
+        try {
+            return JSON.parse(Buffer.from(b64, 'base64').toString('utf8'));
+        }
+        catch {
+            return b64;
+        }
+    }
+    static snippet(text, max = 300) {
+        return text.length <= max ? text : `${text.slice(0, max)}…`;
+    }
+    static textResponse(payload) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ ...payload, _atomicUnitsNote: ATOMIC_UNITS_NOTE }, null, 2),
+                },
+            ],
+        };
+    }
+}
+X402Manager.x402Tools = [
+    {
+        name: 'x402_discover_payment_requirements',
+        description: 'Probe an x402-protected HTTP endpoint and return its payment requirements (the `accepts` array from the 402 response) without paying. Use this to inspect cost and supported networks/assets before calling `make_http_request_with_x402`.',
+        inputSchema: withCommonParams(x402ToolSchemas.discoverPaymentRequirements),
+    },
+    {
+        name: 'make_http_request_with_x402',
+        description: 'Call an x402-protected HTTP endpoint with automatic USDC/ALGO payment from the active wallet. If `paymentRequirements` is not supplied, this tool runs discovery internally (one extra request). Builds an atomic 2-transaction group (facilitator fee-payer + wallet payment), signs the payment leg with the wallet, and resends with the `PAYMENT-SIGNATURE` header.',
+        inputSchema: withCommonParams(x402ToolSchemas.makeHttpRequestWithX402),
+    },
+];
+// extractNetwork is imported above but the x402 tools do not currently use the
+// generic `network` arg — they derive the working network from the chosen
+// payment requirement's CAIP-2 identifier instead. The import remains for
+// future use (e.g. localnet discovery against a private facilitator).
+void extractNetwork;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goplausible/algorand-mcp",
-  "version": "4.2.7",
+  "version": "4.2.8",
   "publishConfig": {
     "access": "public"
   },