MCP 服务器

pyrimid

Onchain agent-to-agent commerce protocol using x402 and ERC-8004. Enables AI agents to buy/sell services, manage vendor catalogs, and process payments on Base.

README

<h1 align="center">Pyrimid Protocol</h1>

Onchain affiliate distribution for AI agents on Base.

<a href="https://pyrimid.ai">Website</a> · <a href="https://pyrimid.ai/docs">Documentation</a> · <a href="https://www.npmjs.com/package/@pyrimid/sdk">SDK on npm</a> · <a href="https://basescan.org/address/0xc949AEa380D7b7984806143ddbfE519B03ABd68B">Contracts</a>

What is Pyrimid?

Pyrimid is a protocol where vendors list digital products, AI agents distribute them as affiliates, and commissions settle instantly in USDC via smart contracts on Base.

Agent discovers a product → purchases via x402 → smart contract splits payment:

  1%        → Protocol treasury
  0–50%     → Affiliate agent (set by vendor)
  Remainder → Vendor

No 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.

Why Pyrimid?

Problem	Pyrimid's Solution
Agents can't monetize recommendations	Earn commissions by recommending products to users
Vendors can't reach agents at scale	List once, get discovered by every agent on the network
Commission payments are slow & opaque	Instant USDC settlement via smart contracts — fully auditable
No standard for agent commerce	x402 payments + MCP tools + onchain registry = open standard

Quick Start

Install the SDK

npm install @pyrimid/sdk

For Agents — Find & Recommend Products

import { PyrimidResolver } from '@pyrimid/sdk';

const resolver = new PyrimidResolver({ affiliateId: 'af_your_id' });

// Search the catalog
const product = await resolver.findProduct("trading signals");

// Purchase with x402 payment (auto-splits commissions)
if (product) {
  const receipt = await resolver.purchase(product, agentWallet);
  console.log(`Earned: $${receipt.affiliate_earned / 1_000_000} USDC`);
}

For Vendors — List Your Product

import { pyrimidMiddleware } from '@pyrimid/sdk';

// 10 lines to activate affiliate distribution
app.use(pyrimidMiddleware({
  vendorId: 'vn_your_id',
  products: {
    '/api/signals/latest': {
      productId: 'signals_latest',
      price: 250_000,        // $0.25 USDC
      affiliateBps: 1000,    // 10% to affiliates
    },
  },
}));

For Frameworks — Embed as Default Layer

import { createPyrimidMcpServer } from '@pyrimid/sdk';

// Deploy an MCP server — agents connect, browse, buy
const server = createPyrimidMcpServer({
  affiliateId: 'af_your_id',
  serverName: 'my-recommender',
});

Three Integration Paths

Path	Who	Effort	Leverage
Embedded Resolver	Agent frameworks & toolkits	3 lines	Every agent on your stack earns you commissions
MCP Server	Agent infrastructure providers	5 lines	Agents connect to your server to discover products
Vendor Middleware	API & product builders	10 lines	Activate affiliate distribution on your product

Smart Contracts (Base Mainnet)

All contracts are deployed and verified on Base. ERC-1967 upgradeable proxy pattern.

Contract	Address	Purpose
Registry	`0x34e22fc2...389`	Affiliate & vendor registration, ERC-8004 identity linking
Catalog	`0xC935d6B7...908`	Product listings with pricing & commission rates
Router	`0xc949AEa3...68B`	Commission splitting engine with `maxPrice` slippage protection
Treasury	`0x74A512F4...12C`	Protocol operations fund

API Reference

The Pyrimid API is free to read, rate-limited (60 req/min), and returns JSON.

Endpoint	Method	Description
`/api/v1/catalog`	`GET`	Full product catalog with search, filters, pagination
`/api/v1/stats`	`GET`	Protocol-level stats (volume, transactions, affiliates)
`/api/v1/stats?type=affiliate&id=af_xxx`	`GET`	Affiliate performance & earnings
`/api/v1/stats?type=vendor&id=vn_xxx`	`GET`	Vendor analytics
`/api/mcp`	`POST`	MCP JSON-RPC 2.0 endpoint (Streamable HTTP)
`/api/mcp`	`GET`	Server info & tool definitions

MCP Tools

Tool	Description
`pyrimid_browse`	Search catalog by query, price, category, verified status
`pyrimid_buy`	Purchase a product via x402 with affiliate attribution
`pyrimid_preview`	Preview the commission split before buying
`pyrimid_categories`	List all product categories with counts
`pyrimid_register_affiliate`	Instructions to register as an affiliate onchain

Architecture

pyrimid/
├── app/                       # Next.js 15 (Vercel, region: bom1)
│   ├── page.tsx               # Landing page
│   ├── dashboard/             # Protocol dashboard
│   └── api/
│       ├── v1/catalog/        # Aggregated product catalog (92+ products)
│       ├── v1/stats/          # Protocol & affiliate analytics
│       └── mcp/               # MCP JSON-RPC endpoint
├── sdk/                       # @pyrimid/sdk (published to npm)
│   └── src/
│       ├── resolver.ts        # PyrimidResolver — search, purchase, stats
│       ├── mcp-server.ts      # MCP server factory
│       ├── middleware.ts       # Vendor payment middleware + calculateSplit()
│       └── types.ts           # ABIs, addresses, interfaces
├── subgraph/                  # The Graph indexer (Base)
│   ├── schema.graphql         # PaymentRouted, Affiliate, Vendor entities
│   ├── subgraph.yaml          # 4 data sources
│   └── src/mapping.ts         # Event handlers
├── middleware.ts               # Edge rate limiting (60/min API, 120/min MCP)
└── public/docs/               # Developer documentation

Development

# Clone & install
git clone https://github.com/pyrimid/protocol.git
cd protocol
npm install

# Run locally
cp .env.example .env
npm run dev

# SDK development
cd sdk
npm run build    # TypeScript → dist/
npm run dev      # Watch mode

Deploy

# Website + API
npx vercel --prod

# SDK to npm
cd sdk && npm publish --access public

# Subgraph to The Graph
cd subgraph && npx graph deploy pyrimid --studio

Security

Payment verification: Real onchain verification via viem — checks PaymentRouted events + USDC transfers with 5-minute expiry
Rate limiting: Edge middleware, 60 req/min per IP on catalog/stats, 120/min on MCP
BigInt safety: calculateSplit() handles both Number and BigInt inputs from web3 libraries
Contract pattern: ERC-1967 upgradeable proxies with verified source on BaseScan

Roadmap

[x] Core contracts deployed on Base
[x] SDK v0.2.3 with full catalog pagination
[x] MCP server with 5 tools
[x] x402 Bazaar aggregation (92+ products)
[x] Subgraph indexing on The Graph
[x] Rate limiting & security hardening
[ ] ERC-8004 identity verification for vendors
[ ] Multi-network support (Arbitrum, Optimism)
[ ] Revenue dashboard for affiliates
[ ] Vendor self-service registration portal

Links

Resource	URL
Website	pyrimid.ai
Documentation	pyrimid.ai/docs
SDK	npmjs.com/package/@pyrimid/sdk
Subgraph	thegraph.com/studio/subgraph/pyrimid
Registry	BaseScan
Router	BaseScan

Built on Base · Payments via x402 · Settlement in USDC