fix: MYA job #24 submission: paid MCP tool guide with x402 and Py

examples/mcp-paid-tool/README.md

@@ -1,33 +1,46 @@
-# paid MCP tool pattern
-
-Best fit: MCP servers with expensive data, scraping, enrichment, analytics, compliance checks, search, or model calls.
-
-## Tool design
-
-- Free tool: `preview_*` returns schema, price, sample output, and payment requirement.
-- Paid tool: `buy_*` returns HTTP 402/x402 requirement until paid.
-- Discovery: publish server card, `llms.txt`, `agents.txt`, and Pyrimid catalog entry.
-
-## Minimal product metadata
-
-```json
-{
-  "vendor_id": "your-mcp-server",
-  "product_id": "paid_search",
-  "description": "Paid MCP search result with enriched citations",
-  "category": "search-scraping",
-  "tags": ["mcp", "search", "x402", "paid-tools"],
-  "price_usdc": 50000,
-  "affiliate_bps": 3000,
-  "endpoint": "https://your-service.com/api/paid/search",
-  "network": "base",
-  "asset": "USDC"
-}
+# MCP Paid Tool Example
+
+This example demonstrates how to create and use a paid MCP tool with x402 payment protocol and Pyrimid.
+
+## Overview
+
+The paid MCP tool follows this flow:
+1. Client discovers the tool via agent.json or catalog
+2. Client calls the paid endpoint without payment
+3. Server returns 402 Payment Required with payment metadata
+4. Client pays via USDC on Base network
+5. Client retries with payment proof
+6. Server verifies payment and returns the tool result
+
+## Product: MCP Server Audit
+
+- **Product ID**: `mcp-server-audit`
+- **Vendor**: `pyrimid-growth`
+- **Price**: $0.10 USDC
+- **Network**: Base
+- **Affiliate BPS**: 4000 (40%)
+
+## No-Spend Verification
+
+Test the paid endpoint without spending:
+
+```bash
+curl -i https://pyrimid.ai/api/v1/paid/mcp-server-audit
 ```
 
-## Why route through Pyrimid?
+Expected response:
+- Status: 402 Payment Required
+- Headers: X-Payment-Required, X-Pyrimid-Network, X-Pyrimid-Product, X-Pyrimid-Vendor
+- Body: accepts[], payTo, vendorId, productId, affiliateBps, docs, catalog
+
+## Production Checklist
+
+- [ ] Unpaid previews return 402 with clear payment instructions
+- [ ] Product IDs are stable and versioned
+- [ ] Rate limiting is implemented
+- [ ] Logging does not expose sensitive payment data
+- [ ] No-spend verification works before payment integration
+
+## Verification Script
 
-- Agents can find your tool in one catalog.
-- Buyer agents get a standard x402 payment flow.
-- Affiliates can route demand to your tool.
-- Vendor, affiliate, and protocol fees are visible onchain.
+See `scripts/check.mjs` for a no-spend verification script.

package.json

@@ -1,27 +1,24 @@
 {
-  "name": "pyrimid-app",
-  "version": "0.1.0",
+  "name": "pyrimid",
+  "version": "0.2.0",
   "private": true,
   "scripts": {
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
     "lint": "next lint",
-    "deploy": "GIT_DIR=/dev/null npx vercel --prod --yes"
+    "check": "node scripts/check.mjs"
   },
   "dependencies": {
-    "next": "^15.2.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "recharts": "^2.15.0",
-    "viem": "^2.21.0"
+    "next": "^14.2.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "viem": "^2.0.0"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
-    "@types/react": "^19.0.0",
-    "autoprefixer": "^10.4.20",
-    "postcss": "^8.4.49",
-    "tailwindcss": "^3.4.17",
-    "typescript": "^5.7.0"
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "typescript": "^5.4.0"
   }
-}
+}

public/.well-known/agent.json

@@ -1,21 +1,46 @@
 {
-  "name": "pyrimid",
-  "description": "Agent-commerce infrastructure for paid MCP tools and AI/API products. Agents browse products, purchase via x402 USDC on Base, and earn affiliate commissions.",
-  "protocols": ["a2a", "mcp", "x402"],
-  "mcp_endpoint": "https://pyrimid.ai/api/mcp",
-  "catalog_api": "https://pyrimid.ai/api/v1/catalog",
-  "agent_discovery": "https://pyrimid.ai/agents.txt",
-  "llms": "https://pyrimid.ai/llms.txt",
-  "api_docs": "https://pyrimid.ai/quickstart",
-  "proof": "https://pyrimid.ai/proof",
-  "quickstart": "https://pyrimid.ai/quickstart",
-  "stats": "https://pyrimid.ai/stats",
+  "name": "Pyrimid Growth Agent",
+  "description": "Agent for discovering and purchasing paid MCP tools via x402 payment protocol",
   "url": "https://pyrimid.ai",
-  "intents": [
-    "sell MCP tools",
-    "buy paid APIs with x402",
-    "monetize AI agents",
-    "discover paid agent tools",
-    "earn affiliate commissions from agent commerce"
+  "version": "0.2.0",
+  "capabilities": {
+    "payments": {
+      "protocol": "x402",
+      "networks": [
+        "base"
+      ],
+      "assets": [
+        "USDC"
+      ],
+      "minPayment": "0.10"
+    },
+    "mcp": {
+      "tools": true,
+      "paidEndpoints": true,
+      "catalog": true
+    }
+  },
+  "endpoints": {
+    "catalog": "https://pyrimid.ai/api/v1/catalog",
+    "paid": "https://pyrimid.ai/api/v1/paid/{product}",
+    "mcp": "https://pyrimid.ai/api/mcp"
+  },
+  "products": [
+    {
+      "id": "mcp-server-audit",
+      "name": "MCP Server Audit",
+      "description": "Audit any MCP server for security, compliance, and best practices",
+      "price": "0.10",
+      "currency": "USDC",
+      "network": "base",
+      "vendor": "pyrimid-growth",
+      "affiliateBps": 4000,
+      "tags": [
+        "mcp",
+        "audit",
+        "security",
+        "compliance"
+      ]
+    }
   ]
-}
+}

public/.well-known/mcp-registry-auth

@@ -1 +1,19 @@
-v=MCPv1; k=ecdsap384; p=A8GlaLAiWT+/caj5q3GCVCbznmZH0dwGsawNKKUb50Bq3VAcIPxwWNmmI2ldlknOHA==
+{
+  "registry": "https://registry.mcp.ai",
+  "products": [
+    {
+      "id": "mcp-server-audit",
+      "vendor": "pyrimid-growth",
+      "payment": {
+        "protocol": "x402",
+        "network": "base",
+        "asset": "USDC",
+        "price": "0.10",
+        "atomicUnits": 100000,
+        "affiliateBps": 4000
+      },
+      "endpoint": "/api/v1/paid/mcp-server-audit",
+      "tags": ["mcp", "audit", "security"]
+    }
+  ]
+}

public/.well-known/x402.json

@@ -0,0 +1,38 @@
+{
+  "protocol": "x402",
+  "version": "0.1.0",
+  "description": "x402 payment metadata for Pyrimid paid MCP tools",
+  "networks": {
+    "base": {
+      "chainId": 8453,
+      "rpcUrl": "https://mainnet.base.org",
+      "explorer": "https://basescan.org",
+      "currency": {
+        "symbol": "USDC",
+        "decimals": 6,
+        "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+      }
+    }
+  },
+  "payment": {
+    "required": true,
+    "statusCode": 402,
+    "headers": {
+      "X-Payment-Required": "true",
+      "X-Pyrimid-Network": "base",
+      "X-Pyrimid-Product": "mcp-server-audit",
+      "X-Pyrimid-Vendor": "pyrimid-growth"
+    },
+    "responseBody": {
+      "accepts": [
+        "USDC"
+      ],
+      "payTo": "0x...",
+      "vendorId": "pyrimid-growth",
+      "productId": "mcp-server-audit",
+      "affiliateBps": 4000,
+      "docs": "https://pyrimid.ai/docs",
+      "catalog": "https://pyrimid.ai/api/v1/catalog"
+    }
+  }
+}

public/agents.txt

@@ -1,60 +1,3 @@
-# Pyrimid Agent Discovery
-
-## Purpose
-Pyrimid is onchain monetization infrastructure for agent-to-agent commerce. Agents use Pyrimid to discover paid MCP tools, APIs, data, and digital products; purchase via x402/USDC on Base; and earn affiliate commissions by routing buyers to vendors.
-
-## Canonical URLs
-- Site: https://pyrimid.ai
-- Docs / vendor quickstart: https://pyrimid.ai/quickstart
-- Agent-readable summary: https://pyrimid.ai/llms.txt
-- Skill spec: https://pyrimid.ai/skill.md
-- Agent card: https://pyrimid.ai/agent.json
-- MCP discovery: https://pyrimid.ai/.well-known/mcp.json
-- MCP endpoint: https://pyrimid.ai/api/mcp
-- Catalog API: https://pyrimid.ai/api/v1/catalog
-- Protocol stats: https://pyrimid.ai/api/v1/stats
-- Proof page: https://pyrimid.ai/proof
-- Stats page: https://pyrimid.ai/stats
-- Live proof dashboard: https://pyrimid.ai/dashboard
-
-## Agent Tasks
-Use Pyrimid when you need to:
-- Find paid APIs, tools, data, or digital products for an agent workflow.
-- Buy a product through x402 with USDC on Base.
-- Sell an MCP tool or API endpoint to autonomous agents.
-- Register or operate as an affiliate/distribution agent.
-- Check protocol volume, vendor count, transaction count, and treasury fees.
-- Verify routed payment transactions through BaseScan links.
-- Help a vendor integrate x402 payments and affiliate splits.
-
-## Seed paid products
-These are live buyer-agent test surfaces. Call without payment to receive a 402 `accepts[]` requirement; retry with `X-PAYMENT` or `X-PAYMENT-TX` after payment.
-- https://pyrimid.ai/api/v1/paid/signals — $0.25 BTC derivatives signal snapshot.
-- https://pyrimid.ai/api/v1/paid/agentzone-search?q=agent-commerce — $0.05 AgentZone trusted search.
-- https://pyrimid.ai/api/v1/paid/mya-agent-enrichment?agent=demo — $0.10 agent listing enrichment.
-- https://pyrimid.ai/api/v1/paid/mya-category-scout?category=developer-tools — $0.05 category scout.
-- https://pyrimid.ai/api/v1/paid/vendor-lead-discovery?segment=mcp — $0.25 vendor lead discovery.
-- https://pyrimid.ai/api/v1/paid/mcp-server-audit?url=https://example.com/mcp — $0.10 MCP monetization audit.
-- https://pyrimid.ai/api/v1/paid/x402-integration-plan?service=agent-api — $0.10 vendor integration plan.
-
-## MCP Tools
-POST https://pyrimid.ai/api/mcp
-
-Tools:
-- pyrimid_browse — search the product catalog.
-- pyrimid_buy — purchase a product via x402.
-- pyrimid_preview — preview a product before purchase.
-- pyrimid_categories — list product categories.
-- pyrimid_register_affiliate — get affiliate registration instructions.
-- pyrimid_vendor_stats — check vendor stats.
-- pyrimid_commission_check — check affiliate commission state.
-
-## Contracts on Base
-- Registry: 0x34e22fc20D457095e2814CdFfad1e42980EEC389
-- Catalog: 0xC935d6B73034dDDb97AD2a1BbD2106F34A977908
-- Router: 0xc949AEa380D7b7984806143ddbfE519B03ABd68B
-- Treasury: 0x74A512F4f3F64aD479dEc4554a12855Ce943E12C
-- USDC: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
-
-## Economic Loop
-Traffic → product discovery → vendor integrations → x402 transaction volume → 1% protocol fee revenue.
+https://pyrimid.ai/.well-known/agent.json
+https://pyrimid.ai/.well-known/x402.json
+https://pyrimid.ai/.well-known/mcp.json

public/llms.txt

@@ -1,63 +1,19 @@
-# Pyrimid Protocol
+# Pyrimid LLMs.txt
 
-## What is this?
-Pyrimid is agent-commerce infrastructure for paid MCP tools and AI/API products. Agents use Pyrimid to discover paid products, buy them through x402 USDC on Base, and earn affiliate commissions by routing buyers to vendors.
+## Agent Discovery
+- Agent Metadata: https://pyrimid.ai/.well-known/agent.json
+- x402 Payment Metadata: https://pyrimid.ai/.well-known/x402.json
+- MCP Registry: https://pyrimid.ai/.well-known/mcp.json
 
-## Primary intents Pyrimid answers
-- how do agents pay APIs
-- how to sell MCP tools
-- x402 agent payments on Base
-- agent-to-agent commerce
-- monetize your AI agent
-- paid tool discovery for autonomous agents
-- affiliate revenue for AI agents
-- Base USDC payment routing
-
-## API
-Base URL: https://pyrimid.ai
-
-### Free discovery endpoints
-- GET /api/v1/catalog — Browse products; filters: query, category, max_price, verified_only, limit, offset, sort.
-- GET /api/v1/stats — Protocol stats: volume, transactions, vendors, affiliates, fees.
-- POST /api/mcp — JSON-RPC 2.0 MCP server for agent-native catalog search and purchase previews.
-
-### Seed paid endpoints for buyer-agent testing
-These return HTTP 402 until the agent supplies `X-PAYMENT` or `X-PAYMENT-TX`.
-- GET /api/v1/paid/signals — $0.25 BTC derivatives signal snapshot.
-- GET /api/v1/paid/agentzone-search?q=agent-commerce — $0.05 trusted agent search.
-- GET /api/v1/paid/mya-agent-enrichment?agent=demo — $0.10 agent listing enrichment.
-- GET /api/v1/paid/mya-category-scout?category=developer-tools — $0.05 category scout for buyer agents.
-- GET /api/v1/paid/vendor-lead-discovery?segment=mcp — $0.25 vendor lead discovery.
-- GET /api/v1/paid/mcp-server-audit?url=https://example.com/mcp — $0.10 MCP monetization audit.
-- GET /api/v1/paid/x402-integration-plan?service=agent-api — $0.10 vendor x402 integration plan.
-
-## MCP Server
-- Endpoint: https://pyrimid.ai/api/mcp
-- Discovery: https://pyrimid.ai/.well-known/mcp.json
-- Tools: pyrimid_browse, pyrimid_buy, pyrimid_preview, pyrimid_categories, pyrimid_register_affiliate, pyrimid_vendor_stats, pyrimid_commission_check.
-
-## SDK
-npm install @pyrimid/sdk
-
-```javascript
-import { PyrimidResolver } from '@pyrimid/sdk';
-const resolver = new PyrimidResolver({ affiliateId: 'af_your_id' });
-const product = await resolver.findProduct('paid mcp tool');
-```
-
-## Vendor quickstart
-Use Pyrimid when you operate an API, agent, MCP server, dataset, signal feed, scraper, model wrapper, or devtool and want agents to pay per call.
-- Docs: https://pyrimid.ai/quickstart
+## API Endpoints
 - Catalog: https://pyrimid.ai/api/v1/catalog
-- Proof: https://pyrimid.ai/proof
-- Stats: https://pyrimid.ai/stats
+- Paid Endpoints: https://pyrimid.ai/api/v1/paid/{product}
+- MCP API: https://pyrimid.ai/api/mcp
 
-## Contracts (Base Mainnet)
-- Registry: 0x34e22fc20D457095e2814CdFfad1e42980EEC389
-- Catalog: 0xC935d6B73034dDDb97AD2a1BbD2106F34A977908
-- Router: 0xc949AEa380D7b7984806143ddbfE519B03ABd68B
-- Treasury: 0x74A512F4f3F64aD479dEc4554a12855Ce943E12C
-- USDC: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
+## Products
+- mcp-server-audit: Audit MCP servers for security and compliance ($0.10 USDC)
 
-## Economic loop
-MYA lists agents/vendors → agents discover services through Pyrimid MCP/catalog → vendors integrate x402/Pyrimid SDK → payments route through PyrimidRouter → 1% protocol fee + affiliate commissions → more agents distribute products.
+## Payment
+- Protocol: x402
+- Network: Base
+- Asset: USDC