feat(3rd-400): integrate @qbtlabs/x402 payment middleware

.env.example

@@ -1 +1,20 @@
-INDEXER_URL=https://analytics.indigoprotocol.io/api
+INDEXER_URL=https://analytics.indigoprotocol.io/api/v1
+
+# Required for write operations (transaction building). Get a free key at https://blockfrost.io/
+BLOCKFROST_API_KEY=
+
+# ── x402 payment gating (optional — omit or leave blank to disable) ──────────
+# EVM wallet address to receive USDC on Base (required to enable EVM payments)
+X402_EVM_ADDRESS=
+
+# Cardano address (optional) — NOTE: @qbtlabs/x402 v0.5.0 does not yet emit a
+# Cardano entry in 402 accepts[] because USDC_CONTRACTS has no cardano: entry.
+# Setting this enables Cardano payment *verification* but not advertisement.
+# Leave blank until a future x402 release adds native Cardano token support.
+X402_CARDANO_ADDRESS=
+
+# Set to "true" to use testnets (Base Sepolia = chainId 84532, Cardano preprod)
+X402_TESTNET=false
+
+# Override default facilitator URL (defaults to https://x402.org/facilitator)
+X402_FACILITATOR_URL=

.github/workflows/ci.yml

@@ -23,8 +23,14 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
 
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+          run_install: false
+
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile --ignore-scripts
 
       - name: Typecheck
         run: npm run typecheck
@@ -55,8 +61,14 @@ jobs:
           node-version: 22.x
           registry-url: https://registry.npmjs.org/
 
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+          run_install: false
+
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile --ignore-scripts
 
       - name: Build
         run: npm run build

README.md

@@ -554,6 +554,88 @@ npm run build
 echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}}' | node dist/index.js
 ```
 
+## x402 Payment Gating
+
+Indigo MCP optionally gates tools behind per-call micropayments using the [x402 protocol](https://x402.org). Payment is disabled by default — set at least one wallet address to enable it.
+
+### How it works
+
+- Read tools (`get_tvl`, `get_asset_price`, …) cost **$0.001 USDC** per call
+- Analysis tools (`analyze_cdp_health`) cost **$0.005 USDC** per call
+- Write tools (`open_cdp`, `mint_cdp`, …) cost **$0.01 USDC** per call
+- Tools called without a valid payment return a `402 Payment Required` JSON response with an `accepts[]` array listing supported chains and amounts
+
+### Environment variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `X402_EVM_ADDRESS` | to enable | — | EVM wallet to receive USDC on Base |
+| `X402_CARDANO_ADDRESS` | optional | — | Cardano address to receive USDM on Cardano |
+| `X402_TESTNET` | optional | `false` | Use Base Sepolia / Cardano preprod |
+| `X402_FACILITATOR_URL` | optional | `https://x402.org/facilitator` | Override facilitator |
+
+### Local development
+
+```bash
+# 1. Copy example env
+cp .env.example .env
+# Edit .env and fill in X402_EVM_ADDRESS (and optionally X402_CARDANO_ADDRESS)
+
+# 2. Start the HTTP server
+MCP_TRANSPORT=http PORT=3000 npm run dev
+
+# 3. Run the payment e2e tests
+X402_EVM_ADDRESS=0x... X402_TESTNET=true npm test -- x402-payment
+```
+
+The e2e tests work without a real wallet address — the "real env" test case is the only one that requires `X402_EVM_ADDRESS` to be set.
+
+### MCP client config with x402
+
+Add the `env` block to whichever MCP config file your client uses:
+
+**Claude Code** (`~/.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "indigo": {
+      "command": "npx",
+      "args": ["-y", "@indigoprotocol/indigo-mcp"],
+      "env": {
+        "INDEXER_URL": "https://analytics.indigoprotocol.io/api/v1",
+        "BLOCKFROST_API_KEY": "your-blockfrost-project-id",
+        "X402_EVM_ADDRESS": "0xYourEVMWalletAddress",
+        "X402_TESTNET": "true"
+      }
+    }
+  }
+}
+```
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "indigo": {
+      "command": "npx",
+      "args": ["-y", "@indigoprotocol/indigo-mcp"],
+      "env": {
+        "INDEXER_URL": "https://analytics.indigoprotocol.io/api/v1",
+        "BLOCKFROST_API_KEY": "your-blockfrost-project-id",
+        "X402_EVM_ADDRESS": "0xYourEVMWalletAddress",
+        "X402_TESTNET": "true"
+      }
+    }
+  }
+}
+```
+
+**Cursor / Windsurf** — same `env` block applies to `~/.cursor/mcp.json` or `~/.codeium/windsurf/mcp_config.json`.
+
+> Set `X402_TESTNET` to `false` (or omit it) for Base mainnet / Cardano mainnet.
+
 ## License
 
 ISC

package.json

@@ -53,13 +53,16 @@
     "@indigoprotocol/indigo-sdk": "^1.0.6",
     "@lucid-evolution/lucid": "^0.4.29",
     "@modelcontextprotocol/sdk": "^1.18.0",
+    "@qbtlabs/x402": "^0.5.0",
     "@types/node": "^24.3.1",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "@typescript-eslint/parser": "^8.0.0",
     "axios": "^1.12.2",
     "bech32": "^2.0.0",
+    "dotenv": "^17.3.1",
     "esbuild": "^0.27.3",
     "eslint": "^9.0.0",
+    "patch-package": "^8.0.1",
     "prettier": "^3.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.9.2",