forgemeshlabs/x402-ads-mcp

**Install one middleware. Monetize unused 402 responses with recommendations, discovery, and machine commerce analytics.**
This is the MCP side of that network: what autonomous agents probe, want, and abandon across the x402 ecosystem — as tools for your agent.
Wraps the ForgeMesh x402 Ads & Intent Network. Paid tools settle per call in USDC on Base mainnet over the x402 protocol — no account, no API key; your wallet is the login. Publishers get reports on their own services **free**.
Install
Both env vars are optional. With neither set, free tools work fully and paid tools return the x402 payment challenge (price, network, payTo) instead of settling — useful for inspection before spending anything.
Bonus: one-command publisher registration
This package doubles as the signup CLI for API operators (no MCP client needed):
One $0.10 USDC payment on Base; the paying wallet becomes your identity and your publisher key is printed once. Invalid requests are rejected **before** payment — you can't pay for a doomed registration.
Tools
| Tool | Price | What it returns |
|---|---|---|
| get_network_counters | free | Live network totals: 402s observed, agent-class requests, recommendations served |
| preview_recommendations | free | The exact recommendations block the middleware injects into a 402 |
| get_terms | free | Canonical terms + complete data-collection disclosure |
| get_network_stats | $0.005 | Network totals + monitor/indexer/agent classification split |
| get_intent_trends | $0.01 | Top endpoints & categories autonomous agents request |
| get_category_demand | $0.02 | Demand depth for one category: volume, buyer share, price points |
| get_intent_report | $0.05 / **free*** | Why-agents-didn't-buy funnel for one service |
\* get_intent_report is free with X402_ADS_PUBLISHER_KEY for services you contribute events to — the data co-op rule: your own data is free, forever.
Environment
| Variable | Required | Purpose |
|---|---|---|
| WALLET_PRIVATE_KEY | no | Base mainnet wallet holding USDC; enables automatic settlement of paid tools |
| X402_ADS_PUBLISHER_KEY | no | Publisher key from ads.forgemesh.io; free lane for your own reports |
| X402_MAX_PRICE_USD | no | Per-call price cap in USD; can only LOWER the built-in cap ($0.05, or $0.10 for register) |
| X402_SESSION_BUDGET_USD | no | Cumulative cap per process; can only LOWER the built-in $10 |
The backend URL is fixed to https://ads.forgemesh.io (the publisher key is only ever sent there). The server refuses to sign for any payee other than the ForgeMesh Ads wallet, any network other than Base mainnet, any asset other than USDC, or any amount over the cap. Use a dedicated, low-balance wallet. The key never leaves your machine — payments are signed locally (EIP-3009) and settle on-chain.