@forgemeshlabs/x402-ads

@forgemeshlabs/x402-ads

Install one middleware. Monetize unused 402 responses with recommendations, discovery, and machine commerce analytics.

How it works

AI agents constantly probe x402 APIs, hit 402 Payment Required, and leave. This middleware turns that dead end into two things: recommendations the agent can act on, and analytics that show you who probed, what they wanted, and why they didn't pay.

                 AI Agent
                    │
                    ▼
              Your x402 API
                    │
                    ▼
           x402 Ads Middleware
                    │
         ┌──────────┴──────────┐
         │                     │
   Recommendations       Event Reporting
   (into your 402        (anonymous metadata
    response body)         only — never content)
         │                     │
         ▼                     ▼
    Agent gets a          Your free traffic
    useful answer         analytics at
    instead of a          ads.forgemesh.io
    dead end

The x402 payment-required header and payment challenge are never modified. Payments keep working exactly as before.

Quickstart — zero to working in 5 minutes

1. Register

One $0.10 USDC payment on Base registers you instantly. The paying wallet becomes your identity and your key is printed once. No emails, no forms, no approval step. The response includes your publisher_id (derived from your hostname, e.g. api-your-service-com) — that's also your serviceId for step 3.

# read the terms first: https://ads.forgemesh.io/terms
WALLET_PRIVATE_KEY=0xYOUR_WALLET npx -y @forgemeshlabs/x402-ads-mcp register \
  --url https://api.your-service.com --category weather --accept-terms

2. Install

npm install @forgemeshlabs/x402-ads

3. Start

Add three lines and restart your server:

const { x402Ads } = require("@forgemeshlabs/x402-ads");

// mount BEFORE your x402 payment middleware
app.use(x402Ads({
  publisherKey: process.env.X402_ADS_PUBLISHER_KEY, // from step 1
  serviceId: "api-your-service-com",                 // your publisher_id from step 1
  categories: ["weather"],
}));

4. Verify

Hit one of your paid endpoints without paying — the 402 body now carries recommendations:

curl https://api.your-service.com/your-paid-endpoint
# → { "error": "payment_required", ..., "recommendations": { "items": [...] } }

And your traffic report is live (free for your own services, forever):

curl "https://ads.forgemesh.io/api/intent/report?service=api-your-service-com" \
  -H "x-publisher-key: pub_YOUR_KEY"

5. Done

That's the whole integration. Everything below is detail.

What gets injected

A previously-empty 402 body becomes:

{
  "error": "payment_required",
  "recommendations": {
    "provider": "ForgeMesh x402 Ads",
    "items": [
      { "type": "sponsored", "title": "Need market signals?", "price": "$0.01", "endpoint": "https://x402.coinopai.com/api/kronos/signals", "link": "https://ads.forgemesh.io/r/ab12cd34ef56" },
      { "type": "similar", "title": "StormAPI", "price": "$0.005", "endpoint": "https://...", "link": "https://ads.forgemesh.io/r/cd34ef56ab12", "reputation": 87 }
    ]
  }
}

similar items come from an index of 800+ live x402 services, filtered by health checks and a reputation score of 60+ — placement is earned, not bought, and your key doesn't change that. sponsored items are paid placements, always labeled. The items array is typed so future kinds arrive without breaking your integration.

Guarantees

• Fail-open — our server down or slow (350 ms budget): your 402 passes through untouched.
• Zero hot-path latency — recommendations come from a local cache (60 s) refreshed in the background; a cold cache skips injection rather than wait.
• No PII — client IP addresses never leave your server, not even hashed.
• Zero dependencies — Node 18+ built-in fetch only.

What data leaves your server (complete list)

We measure machine commerce, not API content. We never see what your customers asked or what your API returned — only that a client hit /api/forecast, got a 402, and whether it later paid.

You contribute anonymized request metadata; in exchange you get the recommendations infrastructure and free analytics on your own traffic. The complete list:

Sent	Never sent
Request path (e.g. /api/forecast)	Request bodies
HTTP method + response status code	Response bodies / your API's actual data
User-agent string	Payment headers, signatures, wallet addresses
Your serviceId + optional category/price labels	Client IP addresses — raw or hashed, nothing IP-derived leaves your server
Timestamp	API keys, cookies, end-user personal data

Your API's response content never leaves your server — the middleware only observes status codes and paths. Read the 140-line source yourself; that's the point.

Your data rights

• Your own analytics are free. GET https://ads.forgemesh.io/api/intent/report?service=<your-serviceId> with your x-publisher-key header — no payment, ever, for your registered services (the service id is bound to your key at registration).
• Aggregates only. Network products (trends, demand reports) are category-level aggregates. We never sell or transfer your publisher-identifiable raw events to anyone.
• Opt out any time. reportEvents: false (inject-only), injectRecommendations: false (report-only), or uninstall. Raw event deletion on written request within 30 days.

Full terms + disclosure: https://ads.forgemesh.io/terms (mirrored in TERMS.md).

Options

Option	Default	Notes
publisherKey	—	required unless reportEvents: false
serviceId	—	required; must be your registered publisher_id — events for unbound ids are rejected
categories	[]	first entry drives recommendation matching
adsUrl	https://ads.forgemesh.io	recommendations/reporting server
timeoutMs	350	per-request budget to our server
cacheTtlMs	60000	recommendation cache TTL
injectRecommendations	true	set false for report-only mode
reportEvents	true	set false for inject-only mode

Paid analytics (for agents & builders)

The network sells aggregate demand data back to anyone — paid per call in USDC on Base, no account needed:

• GET /api/intent/trends — $0.01 — top endpoints/categories requested by autonomous agents
• GET /api/intent/demand?category= — $0.02 — demand depth for one category
• GET /api/intent/report?service= — $0.05 — why-agents-didn't-buy funnel (free on your own services)
• GET /api/network/stats — $0.005 — network totals

Machine-readable docs: https://ads.forgemesh.io/llms.txt · MCP server: @forgemeshlabs/x402-ads-mcp

Legal

By installing this middleware or using the network you agree to the Terms of Service. In short (the terms control): provided "as is" with no warranties; recommendations are not endorsements of third-party services; analytics and traffic classifications are statistical inferences, not facts, informational only — not business, financial, or legal advice; no earnings are guaranteed; you must operate the services you report events for, and fraudulent or synthetic traffic forfeits participation; liability is capped per the terms; x402 settlements are final.

License

MIT © ForgeMesh