{
  "markdown": "<p align=\"center\">\n  <img src=\"https://pyrimid.ai/opengraph-image\" width=\"600\" alt=\"Pyrimid Protocol\" />\n</p>\n\n<h1 align=\"center\">Pyrimid Protocol</h1>\n\n<p align=\"center\">\n  <strong>Agent-commerce infra for paid MCP tools and x402 AI/API products on Base.</strong>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://pyrimid.ai\">Website</a> ·\n  <a href=\"https://pyrimid.ai/quickstart\">Quickstart</a> ·\n  <a href=\"https://pyrimid.ai/api/mcp\">MCP Server</a> ·\n  <a href=\"https://www.npmjs.com/package/@pyrimid/sdk\">SDK on npm</a> ·\n  <a href=\"https://basescan.org/address/0xc949AEa380D7b7984806143ddbfE519B03ABd68B\">Contracts</a>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/@pyrimid/sdk\"><img src=\"https://img.shields.io/npm/v/@pyrimid/sdk?label=SDK&color=8b5cf6\" alt=\"npm version\" /></a>\n  <a href=\"https://pyrimid.ai/api/v1/catalog\"><img src=\"https://img.shields.io/badge/Products-92+-8b5cf6\" alt=\"Products\" /></a>\n  <a href=\"https://basescan.org\"><img src=\"https://img.shields.io/badge/Network-Base-0052FF\" alt=\"Base\" /></a>\n  <a href=\"https://pyrimid.ai/api/mcp\"><img src=\"https://img.shields.io/badge/MCP-Enabled-00d4aa\" alt=\"MCP\" /></a>\n</p>\n\n---\n\n## What is Pyrimid?\n\nPyrimid is a protocol where **vendors sell paid MCP tools / AI APIs**, **agents discover and buy them via x402**, and **commissions settle instantly in USDC** via smart contracts on Base.\n\n```\nAgent discovers a product → purchases via x402 → smart contract splits payment:\n\n  1%        → Protocol treasury\n  0–50%     → Affiliate agent (set by vendor)\n  Remainder → Vendor\n```\n\nNo affiliate? Vendor gets 99%. Vendors only pay for distribution that drives real sales. One layer only — no MLM, no pyramids. Just clean, transparent commission splitting onchain.\n\n---\n\n## Why Pyrimid?\n\n| Problem | Pyrimid's Solution |\n|---------|-------------------|\n| Agents can't monetize recommendations | Earn commissions by recommending products to users |\n| Vendors can't reach agents at scale | List once, get discovered by every agent on the network |\n| Commission payments are slow & opaque | Instant USDC settlement via smart contracts — fully auditable |\n| No standard for agent commerce | x402 payments + MCP tools + onchain registry = open standard |\n\n---\n\n## Quick Start\n\n### Install the SDK\n\n```bash\nnpm install @pyrimid/sdk\n```\n\n### For Agents — Find & Recommend Products\n\n```typescript\nimport { PyrimidResolver } from '@pyrimid/sdk';\n\nconst resolver = new PyrimidResolver({ affiliateId: 'af_your_id' });\n\n// Search the catalog\nconst product = await resolver.findProduct(\"trading signals\");\n\n// Purchase with x402 payment (auto-splits commissions)\nif (product) {\n  const receipt = await resolver.purchase(product, agentWallet);\n  console.log(`Earned: $${receipt.affiliate_earned / 1_000_000} USDC`);\n}\n```\n\n### For Vendors — List Your Product\n\n```typescript\nimport { pyrimidMiddleware } from '@pyrimid/sdk';\n\n// 10 lines to activate affiliate distribution\napp.use(pyrimidMiddleware({\n  vendorId: 'vn_your_id',\n  products: {\n    '/api/signals/latest': {\n      productId: 'signals_latest',\n      price: 250_000,        // $0.25 USDC\n      affiliateBps: 1000,    // 10% to affiliates\n    },\n  },\n}));\n```\n\n### For Frameworks — Embed as Default Layer\n\n```typescript\nimport { createPyrimidMcpServer } from '@pyrimid/sdk';\n\n// Deploy an MCP server — agents connect, browse, buy\nconst server = createPyrimidMcpServer({\n  affiliateId: 'af_your_id',\n  serverName: 'my-recommender',\n});\n```\n\n---\n\n## Live buyer-agent test surfaces\n\nCall these without payment to receive HTTP 402 with x402 `accepts[]` metadata. Retry with `X-PAYMENT` or `X-PAYMENT-TX` after payment.\n\n| Endpoint | Price | Use case |\n|----------|-------|----------|\n| `/api/v1/paid/signals` | $0.25 | BTC derivatives signal snapshot |\n| `/api/v1/paid/agentzone-search?q=agent-commerce` | $0.05 | Trusted agent search |\n| `/api/v1/paid/mya-agent-enrichment?agent=demo` | $0.10 | Agent listing enrichment |\n| `/api/v1/paid/mya-category-scout?category=developer-tools` | $0.05 | Category scouting for buyer agents |\n| `/api/v1/paid/vendor-lead-discovery?segment=mcp` | $0.25 | Vendor lead discovery |\n| `/api/v1/paid/mcp-server-audit?url=https://example.com/mcp` | $0.10 | MCP monetization audit |\n| `/api/v1/paid/x402-integration-plan?service=agent-api` | $0.10 | Vendor x402 integration plan |\n\n## Three Integration Paths\n\n| Path | Who | Effort | Leverage |\n|------|-----|--------|----------|\n| **Embedded Resolver** | Agent frameworks & toolkits | 3 lines | Every agent on your stack earns you commissions |\n| **MCP Server** | Agent infrastructure providers | 5 lines | Agents connect to your server to discover products |\n| **Vendor Middleware** | API & product builders | 10 lines | Activate affiliate distribution on your product |\n\n---\n\n## Smart Contracts (Base Mainnet)\n\nAll contracts are deployed and verified on Base. ERC-1967 upgradeable proxy pattern.\n\n| Contract | Address | Purpose |\n|----------|---------|---------|\n| **Registry** | [`0x34e22fc2...389`](https://basescan.org/address/0x34e22fc20D457095e2814CdFfad1e42980EEC389) | Affiliate & vendor registration, ERC-8004 identity linking |\n| **Catalog** | [`0xC935d6B7...908`](https://basescan.org/address/0xC935d6B73034dDDb97AD2a1BbD2106F34A977908) | Product listings with pricing & commission rates |\n| **Router** | [`0xc949AEa3...68B`](https://basescan.org/address/0xc949AEa380D7b7984806143ddbfE519B03ABd68B) | Commission splitting engine with `maxPrice` slippage protection |\n| **Treasury** | [`0x74A512F4...12C`](https://basescan.org/address/0x74A512F4f3F64aD479dEc4554a12855Ce943E12C) | Protocol operations fund |\n\n---\n\n## API Reference\n\nThe Pyrimid API is free to read, rate-limited (60 req/min), and returns JSON.\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v1/catalog` | `GET` | Full product catalog with search, filters, pagination |\n| `/api/v1/paid/*` | `GET` | Seed paid endpoints for x402 buyer-agent testing |\n| `/api/v1/stats` | `GET` | Protocol-level stats (volume, transactions, affiliates) |\n| `/api/v1/stats?type=affiliate&id=af_xxx` | `GET` | Affiliate performance & earnings |\n| `/api/v1/stats?type=vendor&id=vn_xxx` | `GET` | Vendor analytics |\n| `/api/mcp` | `POST` | MCP JSON-RPC 2.0 endpoint (Streamable HTTP) |\n| `/api/mcp` | `GET` | Server info & tool definitions |\n\n### MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `pyrimid_browse` | Search catalog by query, price, category, verified status |\n| `pyrimid_buy` | Purchase a product via x402 with affiliate attribution |\n| `pyrimid_preview` | Preview the commission split before buying |\n| `pyrimid_categories` | List all product categories with counts |\n| `pyrimid_register_affiliate` | Instructions to register as an affiliate onchain |\n\n---\n\n## Architecture\n\n```\npyrimid/\n├── app/                       # Next.js 15 (Vercel, region: bom1)\n│   ├── page.tsx               # Landing page\n│   ├── dashboard/             # Protocol dashboard\n│   └── api/\n│       ├── v1/catalog/        # Aggregated product catalog\n│       ├── v1/paid/           # Seed x402 paid endpoints\n│       ├── v1/stats/          # Protocol & affiliate analytics\n│       └── mcp/               # MCP JSON-RPC endpoint\n├── sdk/                       # @pyrimid/sdk (published to npm)\n│   └── src/\n│       ├── resolver.ts        # PyrimidResolver — search, purchase, stats\n│       ├── mcp-server.ts      # MCP server factory\n│       ├── middleware.ts       # Vendor payment middleware + calculateSplit()\n│       └── types.ts           # ABIs, addresses, interfaces\n├── subgraph/                  # The Graph indexer (Base)\n│   ├── schema.graphql         # PaymentRouted, Affiliate, Vendor entities\n│   ├── subgraph.yaml          # 4 data sources\n│   └── src/mapping.ts         # Event handlers\n├── middleware.ts               # Edge rate limiting (60/min API, 120/min MCP)\n└── public/docs/               # Developer documentation\n```\n\n---\n\n## Development\n\n```bash\n# Clone & install\ngit clone https://github.com/pyrimid/protocol.git\ncd protocol\nnpm install\n\n# Run locally\ncp .env.example .env\nnpm run dev\n\n# SDK development\ncd sdk\nnpm run build    # TypeScript → dist/\nnpm run dev      # Watch mode\n```\n\n### Deploy\n\n```bash\n# Website + API\nnpx vercel --prod\n\n# SDK to npm\ncd sdk && npm publish --access public\n\n# Subgraph to The Graph\ncd subgraph && npx graph deploy pyrimid --studio\n```\n\n---\n\n## Security\n\n- **Payment verification**: Real onchain verification via viem — checks `PaymentRouted` events + USDC transfers with 5-minute expiry\n- **Rate limiting**: Edge middleware, 60 req/min per IP on catalog/stats, 120/min on MCP\n- **BigInt safety**: `calculateSplit()` handles both `Number` and `BigInt` inputs from web3 libraries\n- **Contract pattern**: ERC-1967 upgradeable proxies with verified source on BaseScan\n\n---\n\n## Roadmap\n\n- [x] Core contracts deployed on Base\n- [x] SDK v0.2.3 with full catalog pagination\n- [x] MCP server with 5 tools\n- [x] x402 Bazaar aggregation (92+ products)\n- [x] Subgraph indexing on The Graph\n- [x] Rate limiting & security hardening\n- [ ] ERC-8004 identity verification for vendors\n- [ ] Multi-network support (Arbitrum, Optimism)\n- [ ] Revenue dashboard for affiliates\n- [ ] Vendor self-service registration portal\n\n---\n\n## Links\n\n| Resource | URL |\n|----------|-----|\n| Website | [pyrimid.ai](https://pyrimid.ai) |\n| Documentation | [pyrimid.ai/docs](https://pyrimid.ai/docs) |\n| SDK | [npmjs.com/package/@pyrimid/sdk](https://www.npmjs.com/package/@pyrimid/sdk) |\n| Subgraph | [thegraph.com/studio/subgraph/pyrimid](https://thegraph.com/studio/subgraph/pyrimid) |\n| Registry | [BaseScan](https://basescan.org/address/0x34e22fc20D457095e2814CdFfad1e42980EEC389) |\n| Router | [BaseScan](https://basescan.org/address/0xc949AEa380D7b7984806143ddbfE519B03ABd68B) |\n\n---\n\n<p align=\"center\">\n  <sub>Built on Base · Payments via x402 · Settlement in USDC</sub>\n</p>\n",
  "bytes": 9897,
  "sha": "126f939ea6617c091062f9562a3b4b233bd0b5a34f56644b69eea43b8f0b9efb",
  "repo_slug": "pyrimid-ai/pyrimid",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_pyrimid_pyrimid_0b807360/readme"
}