moltspay 1.4.1 → 1.6.0

package/README.md

@@ -27,6 +27,7 @@ MoltsPay enables agent-to-agent commerce using the [x402 protocol](https://www.x
 - **Multi-chain** - Base, Polygon, Solana, BNB, Tempo (mainnet & testnet)
 - **Agent-to-Agent** - Complete A2A payment flow support
 - **Multi-VM** - EVM chains + Solana (SVM) with unified API
+- **MCP Server** - Expose wallet + payments to Claude Desktop, Cursor, and other MCP hosts
 
 ## Installation
 
@@ -133,6 +134,192 @@ npx moltspay pay https://server.com service-id \
   --chain tempo_moderato --prompt "test"
 ```
 
+### For Web Apps (Browser)
+
+`moltspay@1.6.0` adds a browser client. Connect any EIP-1193 wallet (MetaMask, Rainbow, Frame, …) for EVM or a `@solana/wallet-adapter` wallet (Phantom, Solflare, Backpack, …) for Solana and pay for x402 services directly from the page — no private key ever in browser memory, no CLI wrapper.
+
+**Install:**
+
+```bash
+npm install moltspay
+```
+
+**Pay with MetaMask:**
+
+```ts
+import { MoltsPayWebClient, eip1193Signer } from 'moltspay/web';
+
+const client = new MoltsPayWebClient({
+  signer: eip1193Signer(window.ethereum),
+});
+
+// Discover what the provider accepts
+const { provider, services } = await client.getServices('https://provider.example.com');
+
+// Run a paid call — user sees one wallet signature prompt
+const result = await client.pay(
+  'https://provider.example.com',
+  'text-to-video',
+  { prompt: 'a cat dancing' },
+  { chain: 'base' }
+);
+```
+
+**Pay with Phantom (Solana):**
+
+```ts
+import { MoltsPayWebClient, solanaSigner } from 'moltspay/web';
+import { useWallet } from '@solana/wallet-adapter-react';
+
+const wallet = useWallet();
+const client = new MoltsPayWebClient({ signer: solanaSigner(wallet) });
+
+await client.pay(serverUrl, 'text-to-video', params, { chain: 'solana_devnet' });
+```
+
+**EVM + Solana in one client** — use `composeSigners` so the same `MoltsPayWebClient` instance routes to whichever signer matches the picked chain:
+
+```ts
+import { MoltsPayWebClient, composeSigners, eip1193Signer, solanaSigner } from 'moltspay/web';
+
+const client = new MoltsPayWebClient({
+  signer: composeSigners(
+    eip1193Signer(window.ethereum),
+    solanaSigner(phantomAdapter),
+  ),
+});
+```
+
+**Chain coverage.** All 8 chains the CLI supports work from the browser with one signature prompt each:
+
+| Chain | Scheme | User gas? | Notes |
+|---|---|---|---|
+| `base` / `polygon` / `base_sepolia` | EIP-3009 `transferWithAuthorization` | No (gasless) | Provider submits on success |
+| `tempo_moderato` | EIP-2612 `permit` | No (gasless) | Browser never switches to Tempo; server's settler submits permit + transferFrom |
+| `bnb` / `bnb_testnet` | MoltsPay `PaymentIntent` | One-time approve | Call `client.approveBnb({ chain, spender, token })` once, then intent signatures are gasless |
+| `solana` / `solana_devnet` | SPL transfer | No if provider sets a fee payer | `wallet.signTransaction` signs, provider submits |
+
+**BNB approval flow.** The first payment on BNB throws `NeedsApprovalError` with the details needed to approve — catch it, call `approveBnb()`, and retry:
+
+```ts
+try {
+  await client.pay(url, service, params, { chain: 'bnb' });
+} catch (err) {
+  if (err instanceof NeedsApprovalError) {
+    await client.approveBnb({
+      chain: 'bnb',
+      spender: err.details.spender,
+      token: err.details.token,
+    });
+    // User paid ~0.001 BNB gas for the approve. Retry now succeeds without further approve.
+    await client.pay(url, service, params, { chain: 'bnb' });
+  }
+}
+```
+
+**Tempo note.** Tempo Moderato pathUSD is a native precompile that implements EIP-2612 permit but **not** EIP-3009. The web client dispatches to the permit path automatically when the server advertises `scheme: "permit"`. The user signs typed data; the provider's settler submits the `permit()` + `transferFrom()` transactions on-chain. MetaMask never prompts for a chain switch because the browser wallet doesn't touch Tempo at all.
+
+**Solana mainnet RPC.** The public `api.mainnet-beta.solana.com` endpoint returns 403 to browser requests, so any Solana-mainnet traffic needs an authenticated RPC. Supply one via `solanaRpc`:
+
+```ts
+const client = new MoltsPayWebClient({
+  signer: composeSigners(
+    eip1193Signer(window.ethereum),
+    solanaSigner(phantomAdapter),
+  ),
+  solanaRpc: {
+    solana: 'https://mainnet.helius-rpc.com/?api-key=YOUR_KEY',
+    // solana_devnet falls back to `api.devnet.solana.com` automatically
+  },
+});
+```
+
+Accepts any Helius / QuickNode / Alchemy / Triton / self-hosted URL. Per-chain — override only `solana` if you only use mainnet. Devnet (`api.devnet.solana.com`) still serves browsers and does not need an override.
+
+**Error classes** — every error exposes a `code` field so you can branch without string-matching:
+
+```ts
+import {
+  NeedsApprovalError,        // code: 'NEEDS_APPROVAL'       — BNB, call approveBnb()
+  UnsupportedChainError,     // code: 'UNSUPPORTED_CHAIN'    — user picked a chain the server doesn't accept
+  PaymentRejectedError,      // code: 'PAYMENT_REJECTED'     — user cancelled in the wallet
+  InsufficientBalanceError,  // code: 'INSUFFICIENT_BALANCE' — not enough native gas for BNB approve
+  SpendingLimitExceededError,// code: 'SPENDING_LIMIT_EXCEEDED' — only when you opt in to SpendingLedger
+  ServerError,               // code: 'SERVER_ERROR'         — provider returned non-2xx
+  MoltsPayError,             // base class
+} from 'moltspay/web';
+```
+
+**Spending limits (opt-in).** Off by default. External wallets already prompt per-signature; per-browser localStorage limits don't sync across devices. If you want a session-level cap anyway:
+
+```ts
+const client = new MoltsPayWebClient({
+  signer: eip1193Signer(window.ethereum),
+  spendingLimits: { maxPerTx: 5, maxPerDay: 50 },
+});
+```
+
+**Provider CORS.** Providers must enable CORS on `MoltsPayServer` for browser callers — without it the 402 challenge header is invisible to the browser:
+
+```ts
+new MoltsPayServer({
+  // ...
+  cors: true,                              // allow all origins, or
+  cors: ['https://myapp.example.com'],     // explicit allowlist, or
+  cors: { origins: [...], maxAge: 86400 }, // fine-grained
+});
+```
+
+Servers advertising for the web need `cors` enabled; CLI callers are unaffected either way.
+
+**Security posture.** No private key ever enters browser memory. No filesystem access, no `~/.moltspay/` — the wallet is always external. The `signer` object the client receives only has permission to sign typed data and (for BNB) submit one `approve` transaction, which the user explicitly confirms in the wallet UI.
+
+**Reference demo.** `examples/web/` is a runnable React + Vite app that exercises every path above. `cd examples/web && npm install && npm run dev` — it connects to `https://moltspay.com/a/zen7` by default. See [`examples/web/README.md`](examples/web/README.md) for the full matrix of tested wallets + chains.
+
+## MCP Server (For AI Assistants)
+
+MoltsPay ships an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) stdio server that lets MCP-compatible hosts (Cursor, Windsurf, Claude Code, Zed, etc.) browse services, check wallet status, and pay for x402 services on your behalf.
+
+It is a thin wrapper around `MoltsPayClient` — wallet custody, spending limits, and all payment protocols (x402, MPP, Solana, BNB) are reused from the SDK.
+
+### Setup
+
+**1. Create a wallet and set spending limits** (the MCP server refuses to start without a wallet):
+
+```bash
+npx moltspay init
+npx moltspay config --max-per-tx 2 --max-per-day 10
+npx moltspay fund 5    # or: npx moltspay faucet for testnet
+```
+
+**2. Point your MCP host at the `moltspay-mcp` binary over stdio:**
+
+```bash
+npx -y moltspay-mcp              # normal mode
+npx -y moltspay-mcp --dry-run    # preview payments without signing
+```
+
+Each host has its own config file for registering stdio MCP servers — check your host's docs for the exact location. For a safer first run, use `--dry-run` so `moltspay_pay` returns a preview instead of spending real funds.
+
+### Tools
+
+| Tool | What it does | Destructive? |
+|---|---|---|
+| `moltspay_status` | Wallet address, balances across all supported chains, spending limits | No |
+| `moltspay_services` | Fetch services manifest from a provider URL; optional `query`/`maxPrice` filter | No |
+| `moltspay_pay` | Execute an x402/MPP/SOL/BNB payment and return the service result | **Yes** |
+| `moltspay_config` | Read or update `maxPerTx` / `maxPerDay` limits | Updates config file |
+
+### Safety Layers
+
+`moltspay_pay` is the only tool that moves money. Three guards stack on top of the MCP host's own tool-approval prompt:
+
+1. **SDK spending limits** — `maxPerTx` / `maxPerDay` enforced before signing.
+2. **Dry-run mode** — launch with `--dry-run` and payments return a preview instead of signing.
+3. **Confirmation gate** — set `MOLTSPAY_MCP_REQUIRE_CONFIRM=1` to require a second tool call (`confirmed: true`) for any payment exceeding `maxPerTx / 10`.
+
+Private keys and mnemonics are never exposed over MCP — wallet creation stays on the CLI (`npx moltspay init`) by design. See [`docs/MCP-USAGE.md`](docs/MCP-USAGE.md) for full tool arguments and troubleshooting.
+
 ## Payment Protocols
 
 MoltsPay supports multiple payment protocols, each optimized for different chains: