affiliate-router-mcp

affiliate-router-mcp

Vendor-neutral monetization routing for agent tools. One MCP server that discovers, routes, and attributes revenue across paid APIs, referral links, and affiliate programs.

Source: https://github.com/forgemeshlabs/affiliate-router-mcp

The router is not tied to any single payment network or affiliate system. Adapters are pluggable. The registry is a local JSON file you control.

Status: experimental · v0.1.6

Disclaimer: This MCP does not guarantee payouts. It routes attribution data according to each vendor/program's rules. Commission distribution is enforced by the vendor's payment system, not by this router.

What it does

Agents need a way to call monetizable tools without hardcoding every affiliate or payment system. affiliate-router-mcp provides:

• Discovery — find vendors and products by category or intent
• Routing — choose the right payment/attribution path automatically
• Calling — execute payments with affiliate attribution
• Link generation — inject tracking params into referral URLs
• Telemetry — log every attributed call locally for tracking

8 Tools

Tool	Cost	Description
search_opportunities	Free	Find products by category or keyword
list_affiliate_programs	Free	List all vendors and their programs
get_opportunity_details	Free	Full details on a specific vendor/product
get_best_route	Free	Recommend the best route for an intent
generate_affiliate_link	Free	Build a tracked referral URL
call_affiliate_product	varies	Pay and call a product with attribution
estimate_commission	Free	Project monthly earnings at a call volume
get_affiliate_telemetry	Free	View local attribution log

Adapters

Each payment or attribution system is a separate adapter. Adding a new one does not affect existing adapters.

Adapter	How it works	Payment	Status
x402_pyrimid	Approve USDC → routePayment on-chain → retry with tx hash	On-chain USDC split	Tested
x402_direct	EIP-3009 transferWithAuthorization via Coinbase facilitator	On-chain USDC to vendor	Implemented
referral_link	Inject affiliate param into URL	None — program-dependent	Implemented

Pyrimid is the first fully tested paid affiliate adapter. It is not the only supported model. Future adapters may include: PartnerStack, Rewardful, Impact, Commission Junction, coupon/promo code injection, API-key partner programs, and other emerging agent commerce protocols.

Install

npm install -g affiliate-router-mcp

Or with Claude Code / any MCP client:

{
  "mcpServers": {
    "affiliate-router": {
      "command": "affiliate-router-mcp",
      "env": {
        "WALLET_PRIVATE_KEY": "0x...",
        "PYRIMID_AFFILIATE_ID": "af_your_id",
        "GUMROAD_AFFILIATE_ID": "your-gumroad-id"
      }
    }
  }
}

Environment Variables

Variable	Required	Notes
WALLET_PRIVATE_KEY	For call_affiliate_product with x402 adapters	Base wallet with USDC + ETH for gas
PYRIMID_AFFILIATE_ID	No	Default affiliate ID for Pyrimid-registered products
GUMROAD_AFFILIATE_ID	No	Gumroad tracking ID
PARTNERSTACK_CODE	No	PartnerStack referral code

Included Vendors

CoinOpAI (x402_pyrimid) — crypto intelligence API on Base mainnet

• Kronos Signals — $0.05/call, 20% commission
• Kronos Decision — $0.15/call, 20% commission
• Trade Preflight — $0.05/call, 20% commission
• Trade Audit — $0.07/call, 20% commission
• Image Generation — $0.10/call, 20% commission

Gumroad (referral_link) — digital product marketplace, ~30% commission per product

PartnerStack (referral_link) — SaaS affiliate programs stub (add your own products)

Routing Logic

call_affiliate_product(vendor_id, product_id, params, affiliate_id?)
    ↓
resolve affiliate_id: tool arg → env var → null
    ↓
adapter = vendor.affiliate_system
    ↓
x402_pyrimid + affiliate_id present?
  cache VALID   → Pyrimid split flow (affiliate earns commission)
  cache INVALID → x402_direct fallback (vendor gets 100%)
  cache UNKNOWN → try Pyrimid → cache result → fallback on failure

x402_direct → EIP-3009 payment, no affiliate split
referral_link → inject tracking param, no payment

Package vs. Product Updates

These are independent concerns.

Package updates (this repo):

• Adding or fixing adapters
• Updating tool schemas
• Changing routing or caching logic
• Dependency bumps

Product/catalog updates (registry.json):

• Registering new vendor endpoints
• Changing prices or commission rates
• Enabling affiliate eligibility on a product
• Assigning network-specific product IDs (e.g. Pyrimid product IDs)

Adding a vendor to registry.json does not require a package release. Releasing a new package version does not require products to be re-registered.

Adding a Vendor

Edit registry.json. No code changes needed for referral-link vendors. x402 vendors require a funded wallet. Pyrimid vendors additionally require on-chain registration to obtain a vendor_id and per-product pyrimid_product_id.

{
  "id": "my_vendor",
  "name": "My Vendor",
  "affiliate_system": "referral_link",
  "affiliate_config": {
    "tracking_param": "ref",
    "affiliate_id_env": "MY_VENDOR_REF_CODE",
    "commission_pct": 25
  },
  "products": [...]
}

Telemetry

All call_affiliate_product calls append to logs/affiliate-telemetry.jsonl:

{
  "ts": "2026-05-14T17:07:01Z",
  "vendor_id": "coinopai",
  "product_id": "kronos_signals",
  "amount_usd": 0.05,
  "affiliate_id": "af_your_id",
  "payment_type": "x402_pyrimid",
  "commission_est_usd": 0.0099,
  "status": "success",
  "tx_hash": "0x..."
}

What's Not in v0

• Remote registry sync
• PartnerStack / Impact.com / Rewardful API integrations
• Web dashboard
• Multi-level commissions
• Server-side redirect tracking for links

Part of the ForgeMesh Ecosystem

Infrastructure for monetized agent ecosystems.

Package	What	Install
affiliate-router-mcp	Vendor-neutral monetization routing (this package)	npm i affiliate-router-mcp
coinopai-mcp	Paid crypto intelligence via x402	npm i coinopai-mcp
forgemesh-imagegen	Paid image generation MCP	npm i forgemesh-imagegen

Each package works standalone. No shared dependency required.

License

MIT — CoinOpAI