@mcpaid/sdk 2.0.0

package/LICENSE

@@ -0,0 +1,176 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/NPM_RESTRUCTURE.md

@@ -0,0 +1,86 @@
+# NPM Restructure Plan — v2.0.0 (client-only public package)
+
+> Status (implemented, unreleased): index exports trimmed to public-only;
+> `files` excludes worker/d1-store/page renderers/relayer/services/oracle;
+> `exports` map added; `relayer --run` gated behind `MCPAID_OPERATOR=1`.
+> Verified: `tsc` clean, 150/150 tests pass, `npm pack --dry-run` = 111 files /
+> 102kB package / 462kB unpacked (was 146 / 209kB / 1.0MB), zero operator
+> matches in tarball. Remaining: version bump + publish (see §6).
+
+## Goal
+`@mcpaid/sdk` 2.0.0 must contain everything needed to **USE** MCPaid (as an MCP developer or agent/user) and nothing needed to **OPERATE** a full MCPaid instance (own Cloudflare edge + ledger + relayer + contract deployment). Today's 1.5.x tarball ships the operator half (`dist/worker.js` 70kB, `d1-store`, dashboard/landing/docs HTML, `withdrawal-relayer`, `settle-withdrawals`, migrations) — 146 files / ~1MB unpacked. 2.0.0 removes it.
+
+Enforcement note: this is hygiene + license clarity, not a technical lock. The x402/402 flow is reimplementable; fee enforcement on production self-hosts stays via `OPERATOR-LICENSE.md` + official-router listing (see prior discussion).
+
+---
+
+## 1. Current tarball inventory (`npm pack --dry-run` @1.5.3)
+
+**REMOVE from public package (operate-an-instance):**
+- `dist/worker.js` (+ map/d.ts) — the entire Cloudflare edge app
+- `dist/gateway/d1-store.js` — D1 ledger/auth/sessions/withdrawals persistence
+- `dist/gateway/dashboard-html.js`, `landing-html.js`, `docs-html.js`, `docs-markdown.js` — worker-served site (keep sources in repo, just don't ship)
+- `dist/settlement/withdrawal-relayer.js` — cron settlement operator
+- `dist/settlement/base-contract-client.js` (operator half — receipt verification for settlement; client only needs permit verification)
+- `dist/services/email-service.js` — OTP mail sender (edge-only)
+- `dist/oracle/challenge-signer.js` — check usage; if edge-only, remove
+- `src/contracts/ToolPayRouter.json` (keep ABI? see §2) + `scripts/` (deploy/settle/bridge-to-base) + `migrations/` + `wrangler.jsonc` (already unshipped — confirm stays unshipped)
+
+**KEEP in public package (use MCPaid):**
+- `dist/sdk/client-agent.js` — agent 402 flow (core)
+- `dist/sdk/server-sdk.js` — embedded dev gateway (keep: this is "use", not "operate edge")
+- `dist/transports/stdio-bridge.js` (+ `sse-transport`) — Claude/Cursor wiring
+- `dist/cli.js` — **trimmed** command surface (see §3)
+- `dist/fee/fee-calculator.js`, `dist/utils/units.js` — pricing math clients need
+- `dist/settlement/permit-verifier.js`, `nonce-store.js`, `onchain-verifier.js` (verify-only), `session-wallet.js` (client session proofs)
+- `dist/circuit-breaker/` — agent safety
+- `dist/contracts/router-registry.js` (official router/treasury constants — trust signal) + `ToolPayRouter.json` ABI (read-only, for verification) + `ToolPayRouter.sol` reference via repo link, not shipped bytecode pipeline
+- `dist/types/*`, `dist/gateway/config-loader.js`, `server-registry.js`, `toolpay-gateway.js` (embedded path only — no D1/KV imports)
+- Docs: `README.md`, `SELF-HOSTING.md` (pointer only), `OPERATOR-LICENSE.md`, `LICENSE`
+
+## 2. Proposed split
+
+- **Public: `@mcpaid/sdk@2.0.0`** (this repo, restructured `src/`):
+  - `src/public/` (or keep paths, gate via build): `sdk/`, `transports/`, `cli/` (trimmed), `fee/fee-calculator`, `utils/units`, `settlement/{permit-verifier,nonce-store,onchain-verifier,session-wallet}`, `circuit-breaker/`, `contracts/{router-registry,ToolPayRouter.json}`, `types/`, `gateway/{config-loader,server-registry,toolpay-gateway}` (embedded only).
+  - `package.json`: `files` allowlist (not blocklist) — exactly the kept `dist/` subtrees + 4 md files. `exports`: `./*` limited to public entry points (`./dist/index.js`, `./dist/cli.js`); no `./dist/worker.js` export.
+- **Private: `@mcpaid/edge` (new private repo or `edge/` + `.npmrc` restricted, never published publicly):**
+  - `src/worker.ts`, `gateway/d1-store`, `gateway/{dashboard,landing,docs}-html`, `settlement/{withdrawal-relayer,base-contract-client}`, `services/email-service`, `oracle/challenge-signer` (if edge-only), `scripts/{deploy-contract,settle-withdrawals}`, `migrations/`, `wrangler.jsonc`, `.dev.vars` handling.
+  - Consumes `@mcpaid/sdk` as a dependency for shared types/fee math;its own CI runs `wrangler deploy`.
+- **Contracts:** keep `ToolPayRouter.sol` source public in repo for auditability (trust win), but the *deployment pipeline* (`scripts/deploy-contract.ts`, `deployments/`, treasury keys) lives private. Public package ships ABI JSON only.
+
+## 3. CLI surface trim (2.0.0 breaking)
+
+Keep (use hosted): `init`, `validate`, `dev`, `tunnel`, `bridge` (+ `agent-proxy` alias), `publish`, `server list|remove`, `login|logout|whoami`, `withdraw|withdrawals` (request + view), `wallet new|status`.
+Remove or gate: `relayer --run` (operator settlement — move to private `@mcpaid/edge` CLI or require explicit `MCPAID_OPERATOR=1` + big warning), `start` (decide: keep as local-dev convenience OR remove to push all traffic to hosted; recommendation: **keep** — removing it hurts legit local dev more than it hurts forkers, and forkers don't need it).
+
+## 4. Versioning & breaking changes (2.0.0)
+
+- Major bump: removed exports (`worker`, `d1-store`, page renderers, relayer, email-service), removed CLI `relayer --run`, tightened `files`/`exports`.
+- `TOOLPAY_PERMIT_DOMAIN.verifyingContract` already moved `0x0` → official router in 1.5.x — keep in 2.0.0; document as breaking for anyone self-signing against old domain.
+- Migration guide (one page in README): "If you imported `dist/worker.js` / `d1-store` / page HTML from the SDK, vendor 1.5.x or contact `business@mcpaid.dev` for an operator agreement."
+
+## 5. Implementation steps
+
+1. Create `edge/` (or new repo) + move operator sources; update imports to `@mcpaid/sdk`.
+2. Rewrite `src/index.ts` exports to public-only; add `exports` map in `package.json`; rewrite `files` as allowlist.
+3. Trim `cli.ts` (`relayer` path) + help text; update README CLI table.
+4. Move `migrations/`, `wrangler.jsonc`, deploy scripts out of the public publish path (keep in repo root but excluded via `files` + docs note, or move into `edge/`).
+5. Update `SELF-HOSTING.md` → "production edge = private/licensed; public SDK cannot stand one up."
+6. `npm pack --dry-run` audit: assert no `worker`, `d1-store`, `dashboard-html`, `withdrawal-relayer`, `email-service`, `migrations`, `wrangler` in tarball; assert tarball < ~400kB unpacked.
+7. Full `npm run build` + `npm test` (update/remove tests importing private modules; keep e2e via public embedded gateway).
+8. Publish `2.0.0` fresh (post-unpublish +24h window if going the delete route).
+
+## 6. Publish checklist (delete + fresh)
+
+- [ ] `npm pack` backup of 1.5.x; confirm `@mcpaid` scope ownership
+- [ ] `npm unpublish @mcpaid/sdk -f` (or Support ticket); start 24h clock
+- [ ] Land §§1–5 on main; `npm version 2.0.0`
+- [ ] `npm pack --dry-run` assert list (§5.6)
+- [ ] `npm publish --access public` + verify npm page (README, files, no `wrangler deploy` section)
+- [ ] Tag `v2.0.0`; note old versions unrecoverable (burned version numbers)
+
+## 7. Open decisions (need your call)
+
+1. `start` (local embedded gateway): keep or cut in 2.0.0?
+2. `ToolPayRouter.sol` source: keep public in repo (audit trust) — agreed? (Deployment stays private.)
+3. Private edge: same repo `edge/` folder vs separate private repo?

package/OPERATOR-LICENSE.md

@@ -0,0 +1,18 @@
+# MCPaid Operator License (Edge Gateway + Router)
+
+Client SDK (`src/sdk/`, `src/transports/`, `bridge`, agent) remains **Apache-2.0** (see `LICENSE`).
+
+## Operating your own gateway
+
+Running `src/worker.ts`, `wrangler.jsonc`, `migrations/`, `contracts/ToolPayRouter.sol`, or `scripts/deploy-contract.ts` in **production** (real users, real USDC, public network) requires either:
+
+1. **Use of the official hosted routers** — settle through the official `ToolPayRouter` contracts (`src/contracts/router-registry.ts`: Base mainnet `0x406240a9af02596a20ef9779aa214143c794ecee`), which atomically route the protocol fee to the official treasury; or
+2. **A commercial operator agreement** with MCPaid (contact `business@mcpaid.dev`) permitting an alternate treasury/fee.
+
+Non-production use (local dev, testnet `base-sepolia`, CI, evaluation) is permitted without an agreement.
+
+## Why
+
+The hosted `mcpaid.dev` network (discovery, dashboard auth, D1 ledger, 60-second relayer, support) is funded by the 3% protocol cut enforced on-chain by the official router. Changing `ROUTER_CONTRACT_ADDRESS`, `PLATFORM_TREASURY_WALLET`, or `PLATFORM_FEE_BPS` to divert that cut on a production self-host is a breach of this license and grounds for delisting from hosted discovery/clients.
+
+Technical measures (`verifyingContract` binding, `isOfficialRouter()` warnings in the agent client) are signals only — they can be removed in a fork. Enforcement is via this license.

package/README.md

@@ -0,0 +1,380 @@
+# MCPaid: Zero-Friction MCP Monetization & Micropayment Infrastructure
+
+[![npm version](https://img.shields.io/badge/npm-v1.5.1-green.svg)](https://www.npmjs.com/package/@mcpaid/sdk)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Base Mainnet](https://img.shields.io/badge/Base%20Mainnet-EVM%208453-blue)](https://basescan.org)
+[![Circle USDC](https://img.shields.io/badge/USDC-0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913-brightgreen)](https://basescan.org/token/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)
+[![Test Suite](https://img.shields.io/badge/tests-141%20passing-success.svg)](test)
+
+**MCPaid** enables developers of [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers to seamlessly monetize tools with pay-per-use micropayments (e.g. $0.005 / call), gasless AI agent authorizations via **HTTP 402 + EIP-712**, and **automated 60-second on-chain USDC payouts on Base L2**.
+
+---
+
+## ⚡ Key Capabilities
+
+1. **Sub-5ms Global Edge Gateway (Cloudflare Workers + V8 Isolates)**:
+   - High-throughput reverse proxy deployed across 310+ cities worldwide.
+   - Decorates MCP tool catalogs with pricing schemas and challenges unauthorized calls with RFC-compliant HTTP 402.
+   - Serverless SQLite persistence via Cloudflare D1 with global read replication and KV challenge nonces with 120s anti-replay TTL.
+
+2. **Gasless Micropayment Vouchers (EIP-712 on Base L2)**:
+   - Autonomous AI agents sign typed micro-vouchers off-chain without spending ETH on gas or waiting for block confirmations.
+   - Native support for Circle USDC on **Base Mainnet** (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`) and **Base Sepolia** (`0x036CbD53842c5426634e7929541eC2318f3dCF7e`).
+
+3. **Automated 1-Minute Base L2 Payout Relayer (`* * * * *`)**:
+   - Developers receive **97.00% net revenue** on every tool call (3.00% protocol fee).
+   - Earnings accumulate in real-time in the D1 edge financial ledger.
+   - When a developer requests a withdrawal, Cloudflare Workers' isolated cron relayer automatically executes the on-chain ERC-20 transfer on Base L2 every **60 seconds**, stamping confirmed BaseScan receipts directly into the dashboard.
+   - **Zero HTTP Attack Surface**: All payout execution paths run strictly via internal edge cron triggers or authenticated local operator scripts (`mcpaid relayer --run`).
+
+4. **Zero-Config Live Development Tunnel (`mcpaid dev`)**:
+   - Monetize MCP servers running locally on hardware (`http://127.0.0.1:3000/mcp`) without buying domains or renting cloud VPS servers.
+   - Launches an encrypted TLS 1.3 tunnel with an integrated **Security Shield** that drops direct bypass traffic with `403 Forbidden`.
+
+5. **Server Management & Anti-Hijacking Security**:
+   - Clean-slate server de-registration via Web Dashboard or CLI (`mcpaid server remove <id>`).
+   - Ownership verification ensures server IDs cannot be overwritten by unauthorized third parties.
+   - Passwordless 2FA email authentication with 30-day sliding-window sessions.
+
+6. **Agent Safety Circuit Breakers**:
+   - Built-in velocity limiters (sliding 1-minute window).
+   - Spend ceiling hard caps (`maxPricePerCallUsd`, `maxTotalBudgetUsd`).
+   - Infinite duplicate parameter loop detection.
+
+---
+
+## 🚀 Installation
+
+### Global CLI
+
+```bash
+npm install -g @mcpaid/sdk
+# or run directly with npx:
+npx @mcpaid/sdk --help
+```
+
+### TypeScript / Node.js SDK
+
+```bash
+npm install @mcpaid/sdk
+```
+
+---
+
+## 📖 Developer Quickstarts
+
+### Option A: The 3-Minute Local Developer Quickstart (`mcpaid dev`)
+
+Monetize an MCP server running on your laptop or workstation without cloud hosting:
+
+1. **Ensure your local MCP server is running** (e.g. on port 3000 at `http://127.0.0.1:3000/mcp`).
+2. **Generate your configuration & authenticate**:
+   ```bash
+   npx @mcpaid/sdk init
+   npx @mcpaid/sdk login
+   ```
+3. **Launch the Live Dev Tunnel & Security Shield**:
+   ```bash
+   npx @mcpaid/sdk dev
+   ```
+   *The CLI creates an encrypted tunnel, registers your server at `https://mcpaid.dev/mcp/:serverId`, activates the security shield, and streams live tool executions and earnings to your terminal.*
+4. **Give your public URL to agents or users**:
+   ```bash
+   npx @mcpaid/sdk bridge --gateway https://mcpaid.dev/mcp/:serverId
+   ```
+
+---
+
+### Option B: Cloud-Deployed Production Server (`mcpaid publish`)
+
+For MCP servers hosted on public cloud providers (Render, Fly.io, Railway, AWS, Cloudflare Workers):
+
+1. **Configure `mcpaid.config.json`**:
+   ```json
+   {
+     "serverId": "stock-oracle",
+     "name": "Market Intelligence MCP",
+     "upstreamUrl": "https://mcp.yourcompany.com/sse",
+     "payoutWallet": "0xYourBaseL2PayoutAddress",
+     "network": "base",
+     "currency": "USDC",
+     "tools": [
+       { "toolName": "health_ping", "type": "free" },
+       { "toolName": "get_stock_quote", "type": "paid", "priceUsd": "0.01" }
+     ]
+   }
+   ```
+2. **Validate and Publish to the Global Edge**:
+   ```bash
+   npx @mcpaid/sdk validate
+   npx @mcpaid/sdk publish mcpaid.config.json
+   ```
+3. **Manage & List Live Servers**:
+   ```bash
+   npx @mcpaid/sdk server list
+   ```
+4. **Decommission & Remove Servers Anytime**:
+   ```bash
+   npx @mcpaid/sdk server remove stock-oracle
+   ```
+
+---
+
+### Option C: Browser Web Dashboard ([mcpaid.dev/dashboard](https://mcpaid.dev/dashboard))
+
+Prefer a graphical interface? Manage everything from your browser:
+
+1. **Passwordless 2FA Login**: Enter your developer email and submit the 6-digit verification code. Check *"Remember this terminal"* for a persistent 30-day session.
+2. **Configure Payout Wallet**: Click **[ EDIT ]** in the dashboard header and set your Base EVM wallet address (`0x...`).
+3. **Publish Servers**: Click **>_ Publish MCP Server** to open the visual tool pricing builder.
+4. **Disconnect Servers**: Click **>_ Disconnect Server** on any server card to remove it from the network.
+5. **Withdraw Earnings**: Click **>_ Withdraw to Base L2** to cash out accrued USDC. Within 60 seconds, the automated relayer confirms the transfer on Base Mainnet and stamps the BaseScan transaction link.
+
+---
+
+## 🤖 For AI Agents & Users: Calling Monetized Tools
+
+Autonomous agents (Claude Desktop, Cursor, OpenCode, AutoGPT, LangChain, CrewAI) invoke monetized tools using off-chain EIP-712 micro-permits.
+
+### 1. Generate an Agent Wallet
+
+```bash
+npx @mcpaid/sdk wallet new --agent
+```
+
+Save the generated private key in your agent's environment:
+```env
+AGENT_PRIVATE_KEY=0xYourAgentPrivateKey...
+```
+
+### 2. Fund with Base USDC
+
+* **Base Mainnet (Production - 8453)**:
+  - Token Contract: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
+  - Withdraw USDC directly from **Coinbase** selecting the **Base** network (near-zero fees, instant), or bridge from Ethereum at [bridge.base.org](https://bridge.base.org).
+  - *Note: Agents only need USDC! Because micro-permits are signed off-chain, agents do not need ETH for gas.*
+* **Base Sepolia (Testnet - 84532)**:
+  - Token Contract: `0x036CbD53842c5426634e7929541eC2318f3dCF7e`
+  - Claim free testnet USDC at [faucet.circle.com](https://faucet.circle.com) (select Base Sepolia).
+
+---
+
+### 3. Connect Claude Desktop
+
+Edit your `claude_desktop_config.json` (Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "market-oracle": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@mcpaid/sdk",
+        "bridge",
+        "--gateway",
+        "https://mcpaid.dev/mcp/stock-oracle"
+      ],
+      "env": {
+        "AGENT_PRIVATE_KEY": "0xYourAgentPrivateKey..."
+      }
+    }
+  }
+}
+```
+
+### 4. Connect Cursor / Antigravity
+
+In your project root, create `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "market-oracle": {
+      "command": "npx -y @mcpaid/sdk bridge --gateway https://mcpaid.dev/mcp/stock-oracle",
+      "env": {
+        "AGENT_PRIVATE_KEY": "0xYourAgentPrivateKey..."
+      }
+    }
+  }
+}
+```
+
+---
+
+### 5. Programmatic Integration (TypeScript & Python)
+
+#### TypeScript Agent SDK
+
+```typescript
+import { ToolPayClientAgent } from '@mcpaid/sdk';
+
+const agent = new ToolPayClientAgent({
+  privateKey: process.env.AGENT_PRIVATE_KEY as `0x${string}`,
+  spendPolicy: {
+    autoApprove: true,
+    maxPricePerCallUsd: '0.05', // Maximum $0.05 per tool call
+    maxTotalBudgetUsd: '5.00',  // Maximum cumulative spend ceiling
+  },
+});
+
+// Automatically intercepts HTTP 402, signs EIP-712 voucher, and replays tool execution
+const result = await agent.executeToolCall(
+  {
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'tools/call',
+    params: { name: 'get_stock_quote', arguments: { symbol: 'AAPL' } },
+  },
+  async (req, proof) => {
+    return fetch('https://mcpaid.dev/mcp/stock-oracle', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${JSON.stringify(proof)}`,
+      },
+      body: JSON.stringify(req),
+    });
+  }
+);
+```
+
+#### Python Autonomous Agent
+
+```python
+import json, os, requests
+from eth_account import Account
+from eth_account.messages import encode_typed_data
+
+GATEWAY_URL = "https://mcpaid.dev/mcp/stock-oracle"
+agent = Account.from_key(os.getenv("AGENT_PRIVATE_KEY"))
+
+req = {
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "tools/call",
+    "params": {"name": "get_stock_quote", "arguments": {"symbol": "AAPL"}}
+}
+
+# 1. Initial invocation (returns 402 Challenge)
+resp = requests.post(GATEWAY_URL, json=req)
+
+if resp.status_code == 402:
+    challenge = resp.json()["error"]["data"]
+    
+    # 2. Sign EIP-712 Typed Data off-chain (zero gas)
+    typed_data = {
+        "types": {
+            "EIP712Domain": [
+                {"name": "name", "type": "string"},
+                {"name": "version", "type": "string"},
+                {"name": "chainId", "type": "uint256"},
+                {"name": "verifyingContract", "type": "address"}
+            ],
+            "ToolPayment": [
+                {"name": "serverId", "type": "string"},
+                {"name": "toolName", "type": "string"},
+                {"name": "challengeNonce", "type": "string"},
+                {"name": "amountMicro", "type": "uint256"},
+                {"name": "recipient", "type": "address"},
+                {"name": "deadline", "type": "uint256"}
+            ]
+        },
+        "primaryType": "ToolPayment",
+        "domain": {
+            "name": "ToolPay MicroPermit",
+            "version": "1",
+            "chainId": challenge["chainId"],
+            "verifyingContract": challenge.get("verifyingContract", "0x406240a9af02596a20ef9779aa214143c794ecee")
+        },
+        "message": {
+            "serverId": challenge["serverId"],
+            "toolName": challenge["toolName"],
+            "challengeNonce": challenge["challengeNonce"],
+            "amountMicro": int(challenge["amountMicro"]),
+            "recipient": challenge["recipientWallet"],
+            "deadline": int(challenge["expiresAt"])
+        }
+    }
+
+    signed = agent.sign_message(encode_typed_data(full_message=typed_data))
+
+    voucher = {
+        "scheme": "eip712-permit",
+        "challengeNonce": challenge["challengeNonce"],
+        "signerWallet": agent.address,
+        "signature": signed.signature.hex(),
+        "deadline": challenge["expiresAt"]
+    }
+
+    # 3. Replay with voucher in Authorization header
+    headers = {"Authorization": f"Bearer {json.dumps(voucher)}"}
+    resp = requests.post(GATEWAY_URL, json=req, headers=headers)
+
+print("Tool Result:", resp.json()["result"])
+```
+
+---
+
+## 🛠️ CLI Command Reference
+
+| Command | Arguments / Flags | Description |
+| :--- | :--- | :--- |
+| `mcpaid init` | `—` | Scaffold sample `mcpaid.config.json` in current directory. |
+| `mcpaid validate` | `[config-path]` | Validate JSON syntax, pricing rules, and upstream targets. |
+| `mcpaid dev` | `[config-path] [--gateway <url>]` | Launch zero-config encrypted dev tunnel with local Security Shield. |
+| `mcpaid tunnel` | `[port]` | Launch standalone Cloudflare tunnel for local port (default: 3000). |
+| `mcpaid publish` | `[config-path] [--gateway <url>]` | Publish and monetize an MCP server on MCPaid Edge Gateway. |
+| `mcpaid server list` | `—` | List all MCP servers and pricing rules registered under your account. |
+| `mcpaid server remove` | `<server-id>` | Disconnect and permanently remove an MCP server (clean slate). |
+| `mcpaid login` | `[--email <addr>]` | Sign in with passwordless 2FA email confirmation code. |
+| `mcpaid whoami` | `—` | Display authenticated developer profile and payout wallet. |
+| `mcpaid logout` | `—` | Revoke active session token and wipe local credentials. |
+| `mcpaid withdraw` | `[amount]` | Withdraw accrued USDC earnings to your verified Base L2 wallet. |
+| `mcpaid withdrawals` | `—` | View payout history, live batch states, and confirmed BaseScan receipts. |
+| `mcpaid relayer` | `[--run]` | Inspect 1-minute automated relayer status or run a local operator batch. |
+| `mcpaid wallet new` | `--developer \| --agent` | Generate dedicated EVM keypairs for developer payouts or agent spending. |
+| `mcpaid wallet status` | `—` | Inspect configured environment wallet addresses and network settings. |
+| `mcpaid bridge` | `--gateway <url> [--key <k>]` | Pipe local stdio from Claude Desktop or Cursor to remote gateway. |
+
+---
+
+## 🔐 Smart Contracts & Base Mainnet Deployment
+
+* **Contract**: [`ToolPayRouter.sol`](contracts/ToolPayRouter.sol)
+* **Network**: Base Mainnet (Chain ID `8453`)
+* **Contract Address**: [`0x406240a9af02596a20ef9779aa214143c794ecee`](https://basescan.org/address/0x406240a9af02596a20ef9779aa214143c794ecee)
+* **Deployment Tx**: [`0xdcd1d86775cba316b9d26a5878e3fab4b7bd1f0ebedf382d5bd1d4cef0dce7f7`](https://basescan.org/tx/0xdcd1d86775cba316b9d26a5878e3fab4b7bd1f0ebedf382d5bd1d4cef0dce7f7)
+* **Platform Treasury**: `0x49E9fEc4e08310Fb106de24711aBCe51028ECbad`
+* **Default Take Rate**: 3.00% (300 bps)
+
+---
+
+## 🧪 Comprehensive Test Suite
+
+MCPaid includes **150 automated unit and integration tests** across 23 suites covering edge handlers, cryptographic verifiers, smart contract splits, financial ledgers, and the automated relayer:
+
+```bash
+npm test
+```
+
+```
+# tests 150
+# suites 23
+# pass 150
+# fail 0
+```
+
+---
+
+## 🛠️ Self-Hosting Your Own Gateway?
+
+Using `mcpaid publish`, `mcpaid dev`, and `mcpaid.dev/dashboard` above means you are on the **hosted MCPaid network** (global edge, discovery at `mcpaid.dev/mcp/:id`, managed 60-second relayer, 3.00% protocol fee).
+
+If instead you want to operate your own isolated gateway (your own Cloudflare Worker + D1 + KV + `ToolPayRouter` contract + treasury), see [SELF-HOSTING.md](SELF-HOSTING.md). Note: a self-hosted gateway is a separate network — you lose hosted discovery, dashboard logins, and the managed relayer, and you take on all ops/settlement custody yourself.
+
+---
+
+## 📄 License
+
+Apache-2.0 © MCPaid Network. See [LICENSE](LICENSE) for details.