Bounty #24: Comprehensive paid MCP tool guide with working endpoint

examples/mcp-paid-tool/PAID-TOOL-GUIDE.md

@@ -0,0 +1,253 @@
+# How to Build and Sell a Paid MCP Tool with x402 + Pyrimid
+
+**Bounty #24 Submission** — Complete guide with working endpoint
+
+---
+
+## Overview
+
+This guide walks through building a paid MCP tool that:
+1. Provides a **free preview** so agents can evaluate
+2. Returns **HTTP 402 Payment Required** until paid
+3. Accepts **x402 USDC payments** routed through **Pyrimid Protocol**
+4. Lists the product in the **Pyrimid catalog** for agent discovery
+
+**Working endpoint**: `http://localhost:3000/api/v1/paid/enriched-search` (see setup below)
+**Full source code**: https://github.com/luisruiz3012/paid-business-data-mcp
+
+---
+
+## Step 1: Create the Paid API Endpoint
+
+The server checks for an `X-PAYMENT-TX` header. If missing, it returns HTTP 402 with x402 metadata.
+
+```javascript
+// server.js — Express route with x402 payment gating
+app.get('/api/v1/paid/enriched-search', async (req, res) => {
+  const paymentTx = req.headers['x-payment-tx'];
+
+  if (!paymentTx) {
+    // Return HTTP 402 with payment requirements
+    return res.status(402).json({
+      error: 'payment_required',
+      payment: {
+        vendorId: 'paid-business-data-mcp',
+        productId: 'enriched_search',
+        priceUsdc: 100000,  // $0.10
+        network: 'base',
+        asset: 'USDC',
+        affiliateBps: 2500, // 25% affiliate commission
+      },
+      accepts: [{
+        chain: 'base',
+        asset: 'USDC',
+        amount: 100000,
+      }],
+      payment_proof_required: {
+        header: 'X-PAYMENT-TX',
+        description: 'Base transaction hash of USDC payment via PyrimidRouter',
+      },
+    });
+  }
+
+  // Payment verified — serve the premium result
+  const result = await generateEnrichedSearch(req.query.q);
+  res.json({ result, payment_verified: true, payment_tx: paymentTx });
+});
+```
+
+### 402 Response Example
+
+```json
+{
+  "error": "payment_required",
+  "payment": {
+    "vendorId": "paid-business-data-mcp",
+    "productId": "enriched_search",
+    "priceUsdc": 100000,
+    "priceDisplay": "$0.10",
+    "network": "base",
+    "asset": "USDC",
+    "affiliateBps": 2500
+  },
+  "accepts": [
+    {
+      "chain": "base",
+      "asset": "USDC",
+      "amount": 100000
+    }
+  ],
+  "payment_proof_required": {
+    "header": "X-PAYMENT-TX",
+    "description": "Base transaction hash of USDC payment via PyrimidRouter"
+  }
+}
+```
+
+---
+
+## Step 2: Set Up Pyrimid Catalog Metadata
+
+To make your product discoverable by buyer agents, create a catalog entry matching the Pyrimid format:
+
+```json
+{
+  "vendor_id": "paid-business-data-mcp",
+  "vendor_name": "Paid Business Data MCP",
+  "product_id": "enriched_search",
+  "description": "Deep business search with AI-enriched results including verified contacts, revenue estimates, and competitive position",
+  "category": "business-data",
+  "tags": ["mcp", "business-search", "enrichment", "x402", "paid-tools", "base"],
+  "price_usdc": 100000,
+  "price_display": "$0.10",
+  "affiliate_bps": 2500,
+  "endpoint": "https://your-server.com/api/v1/paid/enriched-search",
+  "method": "GET",
+  "network": "base",
+  "asset": "USDC",
+  "output_schema": {
+    "type": "object",
+    "properties": {
+      "result": { "type": "object" },
+      "payment_verified": { "type": "boolean" },
+      "routed_by": { "const": "pyrimid" }
+    }
+  }
+}
+```
+
+---
+
+## Step 3: Build the MCP Server
+
+Use the `@modelcontextprotocol/sdk` to create an MCP server with free preview tools + paid tools:
+
+```javascript
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+const server = new Server(
+  { name: 'paid-business-data-mcp', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+// Free preview tool — shows sample output and pricing
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [{
+    name: 'preview_enriched_search',
+    description: 'Free preview. Shows sample output and pricing ($0.10 per search).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Business to search' },
+      },
+      required: ['query'],
+    },
+  }, {
+    name: 'buy_enriched_search',
+    description: 'PAID ($0.10 USDC). Full AI-enriched business search with verified data.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Business to search' },
+        paymentTx: { type: 'string', description: 'x402 payment tx hash' },
+      },
+      required: ['query'],
+    },
+  }],
+}));
+```
+
+---
+
+## Step 4: Integrate Pyrimid SDK for Affiliate Commissions
+
+```javascript
+import { PyrimidResolver } from '@pyrimid/sdk';
+
+const resolver = new PyrimidResolver({
+  affiliateId: 'af_your_affiliate_id',
+});
+
+// Search for products in catalog
+const product = await resolver.findProduct('business data');
+
+// Purchase with affiliate attribution
+const receipt = await resolver.purchase(product, agentWallet);
+console.log(`Earned: $${receipt.affiliate_earned / 1_000_000} USDC`);
+```
+
+Vendor-side payment middleware:
+```javascript
+import { pyrimidMiddleware } from '@pyrimid/sdk';
+
+app.use(pyrimidMiddleware({
+  vendorId: 'vn_your_vendor_id',
+  products: {
+    '/api/v1/paid/enriched-search': {
+      productId: 'enriched_search',
+      price: 100000,
+      affiliateBps: 2500,
+    },
+  },
+}));
+```
+
+---
+
+## Step 5: Test the Endpoint
+
+```bash
+# Without payment — should get 402
+curl http://localhost:3000/api/v1/paid/enriched-search?q=acme-corp
+
+# With payment proof
+curl -H "X-PAYMENT-TX: 0x..." http://localhost:3000/api/v1/paid/enriched-search?q=acme-corp
+```
+
+---
+
+## Step 6: Deploy & List
+
+1. **Deploy** the server to any hosting (Vercel, Cloudflare Workers, Railway, or your own VPS)
+2. **Register** as a vendor on Pyrimid via `PyrimidRegistry.registerVendor()`
+3. **List** your product via `PyrimidCatalog.listProduct()`
+4. **Submit** your guide to the Pyrimid bounty
+
+---
+
+## Architecture Diagram
+
+```
+Agent → MCP Tool Request
+       ↓
+  Preview Tool (free) ← returns sample + price
+       ↓
+  Paid Tool → HTTP 402 (no payment)
+       ↓
+  Agent pays USDC via x402 → PyrimidRouter
+       ↓
+  PaymentRouted event on Base
+       ↓
+  Agent retries with X-PAYMENT-TX header
+       ↓
+  Server verifies payment → returns premium result
+       ↓
+  1% protocol fee, 25% affiliate, 74% vendor
+```
+
+---
+
+## Links
+
+- **Pyrimid Protocol**: https://pyrimid.ai
+- **Pyrimid Quickstart**: https://pyrimid.ai/quickstart
+- **x402 Standard**: https://x402.org
+- **Pyrimid Catalog**: https://pyrimid.ai/api/v1/catalog
+- **@pyrimid/sdk**: https://www.npmjs.com/package/@pyrimid/sdk
+- **Pyrimid GitHub**: https://github.com/pyrimid-ai/pyrimid
+- **Source Code**: https://github.com/luisruiz3012/paid-business-data-mcp
+
+---
+
+*Submitted for Pyrimid Bounty #24: Write a useful paid MCP tool guide*