@goplausible/algorand-mcp 4.2.7 → 4.2.9

package/README.md

@@ -13,7 +13,7 @@ Algorand is a carbon-negative, pure proof-of-stake Layer 1 blockchain with insta
 
 ## Features
 
-- Secure wallet management via OS keychain — private keys never exposed to agents or LLMs
+- Agent wallet — mnemonics stored in a local SQLite database, used by the MCP server to sign on the agent's behalf (mnemonics never returned in tool responses)
 - Wallet accounts with human-readable nicknames
 - Account creation, key management, and rekeying
 - Transaction building, signing, and submission (payments, assets, applications, key registration)
@@ -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)
@@ -267,57 +268,148 @@ If no `network` is provided, tools default to **mainnet**.
 
 API responses are automatically paginated. Every tool accepts an optional `itemsPerPage` parameter (default: 10). Pass the `pageToken` from a previous response to fetch the next page.
 
-## Secure Wallet
+## Agent Wallet
 
 ### Architecture
 
-The wallet system has two layers of storage, each with a distinct security role:
+The agent wallet is a local SQLite database that the MCP server controls on the agent's behalf. The server holds the mnemonics and signs transactions for the agent — the agent never sees the mnemonics in any tool response.
 
-| Layer | What it stores | Where | Encryption |
-|---|---|---|---|
-| **OS Keychain** | Mnemonics (secret keys) | macOS Keychain / Linux libsecret / Windows Credential Manager | OS-managed, hardware-backed where available |
-| **Embedded SQLite** | Account metadata (nicknames, active-account index) | `~/.algorand-mcp/wallet.db` | Plaintext (no secrets) |
+| Layer | What it stores | Where |
+|---|---|---|
+| **SQLite (`wallet.db`)** | Account rows (`address`, `public_key`, `nickname`, `mnemonic`, `created_at`) and the active-account index | `~/.algorand-mcp/wallet.db` (mode `0600`) |
 
-**Private key material never appears in tool responses, MCP config files, environment variables, or logs.** The agent only sees addresses, public keys, and signed transaction blobs.
+**Threat model.** The wallet.db file is the secret. Anyone with read access to it can recover every mnemonic stored in the wallet. The mitigations are filesystem permissions (`0600`, owner-only), keeping the data directory off shared/world-readable volumes, and treating the data directory like any other secret store (snapshot it carefully, restrict backups, encrypt the host disk for at-rest protection). For Docker deployments, mount `~/.algorand-mcp` as a named volume and restrict access to it like you would any secret material.
 
 ### How it works
 
 ```
-  Agent (LLM)                    MCP Server                     Storage
-  ──────────                     ──────────                     ───────
-       │                              │                              │
-       │  wallet_add_account          │                              │
-       │  { nickname: "main" }        │                              │
-       │ ──────────────────────────►  │  generate keypair            │
-       │                              │  store mnemonic ──────────►  │  OS Keychain (encrypted)
-       │                              │  store metadata ──────────►  │  SQLite (nickname)
-       │  ◄─ { address, publicKey }   │                              │
-       │                              │                              │
-       │  wallet_sign_transaction     │                              │
-       │  { transaction: {...} }      │                              │
-       │ ──────────────────────────►  │  retrieve mnemonic ◄──────  │  OS Keychain
-       │                              │  sign in memory              │
-       │  ◄─ { txID, blob }          │  (key discarded)             │
-       │                              │                              │
-```
-
-1. **Account creation** (`wallet_add_account`) — Generates a keypair, stores the mnemonic in the OS keychain, and stores the nickname in SQLite. Returns **only** address and public key.
+  Agent (LLM)                    MCP Server                          Storage
+  ──────────                     ──────────                          ───────
+       │                              │                                  │
+       │  wallet_add_account          │                                  │
+       │  { nickname: "main" }        │                                  │
+       │ ──────────────────────────►  │  generate keypair                │
+       │                              │  INSERT (address, public_key,    │
+       │                              │           nickname, mnemonic) ──►│  wallet.db
+       │  ◄─ { address, publicKey,    │                                  │
+       │       nickname, index }      │                                  │
+       │                              │                                  │
+       │  wallet_sign_transaction     │                                  │
+       │  { transaction: {...} }      │                                  │
+       │ ──────────────────────────►  │  SELECT mnemonic FROM accounts ◄─│
+       │                              │   WHERE address=<active>         │
+       │                              │  sign in memory                  │
+       │  ◄─ { txID, blob }           │  (key discarded after sign)      │
+       │                              │                                  │
+```
+
+1. **Account creation** (`wallet_add_account`) — Generates a keypair and inserts a row containing the mnemonic into `accounts`. Returns address, public key, nickname, and index. The mnemonic is never returned.
 2. **Active account** — One account is active at a time. `wallet_switch_account` changes it by nickname or index. All signing and query tools operate on the active account.
-3. **Transaction signing** (`wallet_sign_transaction`) — Retrieves the key from the keychain, signs in memory, discards the key. Returns only the signed blob.
+3. **Transaction signing** (`wallet_sign_transaction`) — Reads the mnemonic from the DB, signs in memory, returns only the signed blob.
 4. **Data signing** (`wallet_sign_data`) — Signs arbitrary hex data using raw Ed25519 via the [`@noble/curves`](https://github.com/paulmillr/noble-curves) library (no Algorand SDK prefix). Useful for off-chain authentication.
 5. **Asset opt-in** (`wallet_optin_asset`) — Creates, signs, and submits an opt-in transaction for the active account in one step.
 
-### Platform keychain support
+### Backward compatibility (silent migration from OS keychain)
 
-The keychain backend is provided by [`@napi-rs/keyring`](https://github.com/nicolo-ribaudo/napi-keyring) (Rust-based, prebuilt binaries):
+Older installs of this MCP stored mnemonics in the OS keychain (`@napi-rs/keyring`). On first startup after upgrading, the server runs a one-shot, silent migration:
 
-| Platform | Backend |
-|---|---|
-| macOS | Keychain Services (the system Keychain app) |
-| Linux | libsecret (GNOME Keyring) or KWallet |
-| Windows | Windows Credential Manager |
+- For every `accounts` row whose `mnemonic` column is `NULL` or empty, it attempts to read the mnemonic from the OS keychain under the service name `algorand-mcp` keyed by the address.
+- If found, the mnemonic is copied into the DB column.
+- The original keychain entry is left in place as a redundant backup; nothing is deleted.
+
+After this completes, the DB is the sole source of truth. The keychain is consulted only as a fallback if the DB still has a `NULL` mnemonic for an address (e.g., the keychain was unavailable during startup and became available later). All new accounts created after the upgrade are written directly to the DB and never touch the keychain.
+
+No user action is required. No prompts, no env vars, no migration logs.
+
+## 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 agent wallet DB       │                          │
+       │                            │  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.
 
-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).
+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
 
@@ -361,13 +453,22 @@ See [Secure Wallet](#secure-wallet) for full architecture details.
 | `wallet_remove_account` | Remove an account from the wallet by nickname or index |
 | `wallet_list_accounts` | List all accounts with nicknames and addresses |
 | `wallet_switch_account` | Switch the active account by nickname or index |
-| `wallet_get_info` | Get info for the **active account this MCP server owns** (keychain-backed): address, public key, balance, opted-in counts. For arbitrary on-chain accounts use `api_algod_get_account_info`. |
+| `wallet_get_info` | Get info for the **active account this MCP server owns** (DB-backed): address, public key, balance, opted-in counts. For arbitrary on-chain accounts use `api_algod_get_account_info`. |
 | `wallet_get_assets` | Get all ASA holdings for the **active account this MCP server owns**. For arbitrary on-chain accounts use `api_algod_get_account_info` or `api_algod_get_account_asset_info`. |
 | `wallet_sign_transaction` | Sign a single transaction with the active account |
 | `wallet_sign_transaction_group` | Sign a group of transactions with the active account (auto-assigns group ID) |
 | `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 |
@@ -587,7 +688,7 @@ algorand-mcp/
 │   │   └── wallet/              # Wallet resources
 │   ├── tools/                   # MCP Tools
 │   │   ├── commonParams.ts      # Network + pagination schema fragments
-│   │   ├── walletManager.ts     # Secure wallet (keychain + SQLite)
+│   │   ├── walletManager.ts     # Agent wallet (SQLite-backed)
 │   │   ├── accountManager.ts    # Account operations
 │   │   ├── utilityManager.ts    # Utility functions
 │   │   ├── algodManager.ts      # TEAL compile, simulate, submit
@@ -867,7 +968,7 @@ describeIf(testConfig.isCategoryEnabled('your-category'))('Your Tools (E2E)', ()
 
 - [algosdk](https://github.com/algorand/js-algorand-sdk) v3 — Algorand JavaScript SDK
 - [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) — MCP TypeScript SDK
-- [@napi-rs/keyring](https://github.com/nicolo-ribaudo/napi-keyring) — Native OS keychain access (macOS Keychain, Linux libsecret, Windows Credential Manager)
+- [@napi-rs/keyring](https://github.com/nicolo-ribaudo/napi-keyring) — Native OS keychain access (macOS Keychain, Linux libsecret, Windows Credential Manager). Used as a backward-compatibility read fallback for accounts created by pre-DB-migration installs; new mnemonics are written only to `wallet.db`.
 - [sql.js](https://github.com/sql-js/sql.js) — Embedded SQLite (WASM) for wallet metadata persistence
 - [@noble/curves](https://github.com/paulmillr/noble-curves) — Pure JS Ed25519 for raw data signing (`wallet_sign_data`)
 - [@tinymanorg/tinyman-js-sdk](https://github.com/tinymanorg/tinyman-js-sdk) — Tinyman AMM SDK

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.9",
   "publishConfig": {
     "access": "public"
   },