diff --git a/examples/mcp-paid-tool/README.md b/examples/mcp-paid-tool/README.md index 9755841..60abf0e 100644 --- a/examples/mcp-paid-tool/README.md +++ b/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. diff --git a/package.json b/package.json index 6fb1a4b..a534086 100644 --- a/package.json +++ b/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" } -} +} \ No newline at end of file diff --git a/public/.well-known/agent.json b/public/.well-known/agent.json index 3577552..8ca5aad 100644 --- a/public/.well-known/agent.json +++ b/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" + ] + } ] -} +} \ No newline at end of file diff --git a/public/.well-known/mcp-registry-auth b/public/.well-known/mcp-registry-auth index 2980683..95a3390 100644 --- a/public/.well-known/mcp-registry-auth +++ b/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"] + } + ] +} diff --git a/public/.well-known/x402.json b/public/.well-known/x402.json new file mode 100644 index 0000000..5bf997c --- /dev/null +++ b/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" + } + } +} \ No newline at end of file diff --git a/public/agents.txt b/public/agents.txt index 1004b04..8557a69 100644 --- a/public/agents.txt +++ b/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 diff --git a/public/llms.txt b/public/llms.txt index 1ab3b6c..23b6aca 100644 --- a/public/llms.txt +++ b/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 diff --git a/scripts/check.mjs b/scripts/check.mjs new file mode 100644 index 0000000..f6b8b02 --- /dev/null +++ b/scripts/check.mjs @@ -0,0 +1,112 @@ +#!/usr/bin/env node + +/** + * No-spend verification script for paid MCP tool + * Checks that the endpoint returns 402 with proper payment metadata + * without actually making a payment. + */ + +const BASE_URL = process.env.BASE_URL || 'https://pyrimid.ai'; +const PRODUCT_ID = 'mcp-server-audit'; +const VENDOR_ID = 'pyrimid-growth'; +const NETWORK = 'base'; +const ASSET = 'USDC'; +const EXPECTED_PRICE = 0.10; +const EXPECTED_AFFILIATE_BPS = 4000; + +async function check() { + console.log(`\n🔍 Checking paid endpoint: ${BASE_URL}/api/v1/paid/${PRODUCT_ID}\n`); + + try { + const response = await fetch(`${BASE_URL}/api/v1/paid/${PRODUCT_ID}`, { + method: 'GET', + headers: { + 'Accept': 'application/json' + } + }); + + const status = response.status; + const headers = Object.fromEntries(response.headers.entries()); + + console.log(`Status: ${status}`); + console.log(`Headers:`, JSON.stringify(headers, null, 2)); + + // Check status is 402 + if (status !== 402) { + console.error(`❌ Expected status 402, got ${status}`); + process.exit(1); + } + console.log('✅ Status is 402 Payment Required'); + + // Check payment headers + const checks = { + 'X-Payment-Required': headers['x-payment-required'] === 'true', + 'X-Pyrimid-Network': headers['x-pyrimid-network'] === NETWORK, + 'X-Pyrimid-Product': headers['x-pyrimid-product'] === PRODUCT_ID, + 'X-Pyrimid-Vendor': headers['x-pyrimid-vendor'] === VENDOR_ID + }; + + let allHeadersPass = true; + for (const [header, passed] of Object.entries(checks)) { + if (passed) { + console.log(`✅ ${header} present and correct`); + } else { + console.error(`❌ ${header} missing or incorrect`); + allHeadersPass = false; + } + } + + if (!allHeadersPass) { + process.exit(1); + } + + // Parse and check body + const body = await response.json(); + console.log(`\nBody:`, JSON.stringify(body, null, 2)); + + const bodyChecks = { + 'accepts[] includes USDC': Array.isArray(body.accepts) && body.accepts.includes('USDC'), + 'payTo present': typeof body.payTo === 'string' && body.payTo.length > 0, + 'vendorId correct': body.vendorId === VENDOR_ID, + 'productId correct': body.productId === PRODUCT_ID, + 'affiliateBps correct': body.affiliateBps === EXPECTED_AFFILIATE_BPS, + 'docs present': typeof body.docs === 'string', + 'catalog present': typeof body.catalog === 'string' + }; + + let allBodyPass = true; + for (const [check, passed] of Object.entries(bodyChecks)) { + if (passed) { + console.log(`✅ ${check}`); + } else { + console.error(`❌ ${check}`); + allBodyPass = false; + } + } + + if (!allBodyPass) { + process.exit(1); + } + + console.log(`\n✅ All checks passed! No spend required.`); + console.log(`\nResult:`); + console.log(JSON.stringify({ + catalogProduct: PRODUCT_ID, + vendor: VENDOR_ID, + network: NETWORK, + asset: ASSET, + price: `$${EXPECTED_PRICE.toFixed(2)}`, + affiliateBps: EXPECTED_AFFILIATE_BPS, + status: status, + hasPaymentHeader: true, + hasAccepts: true, + noSpend: true + }, null, 2)); + + } catch (error) { + console.error(`❌ Error: ${error.message}`); + process.exit(1); + } +} + +check();