x402 Merchant Check

merchant-check-mcp

Gradient Decisions provides merchant intelligence for autonomous commerce. x402 Merchant Check evaluates observable on-chain payment behavior so agents can make more informed decisions before paying unfamiliar x402 merchants. Agent-native, machine-readable, x402-native — $0.01 per check, paid via x402. It is a pre-payment decision primitive, not a certification, a guarantee of safety, or a replacement for an agent's own payment policy. See INTEGRATION.md for the full discover → check → decide → pay flow, the 402-response-to-input mapping, and the exact response shape. See the privacy policy for how data is handled. This file tracks what's actually built, what's stubbed, and what needs you before this goes further.

Privacy policy

Live at gradientdecisions.com/privacy (src/privacy.ts), linked from the homepage footer and here. Drafted 2026-08-13 by Claude at direct request, grounded in this system's actual data practices (what query_log and merchant_signals really store — see "Internal caller-tracking dashboard" above) rather than generic boilerplate. Not reviewed by a lawyer — the page itself says so, and that caveat should stay until it has been. Contact email is info@gradientdecisions.com (switched 2026-08-19 from the developer's personal address — see "Data access policy" below for why and how). src/privacy.ts's CONTACT_EMAIL constant is the source of truth if it ever needs to change again.

DISCOVER → IDENTIFY PAYMENT DESTINATION → GRADIENT MERCHANT CHECK → AGENT PAYMENT POLICY → X402 PAYMENT

Status: two live surfaces, one product

• Agents: https://mcp.gradientdecisions.com/mcp — the paid check_merchant MCP tool. Live on Base mainnet with real USDC (switched from Base Sepolia testnet — see "Going to mainnet"; real settled payments confirmed in query_log, real tx hashes on Base). Merchant coverage spans both Base and Solana (PayAI/Helius) — see "Solana data source". Payment flow verified end-to-end: free tools/list discovery → tools/call correctly 402s → agent builds and signs an x402 payment, submits it → facilitator settles it → real tier comes back. See "Try it yourself" below.
• Humans: https://gradientdecisions.com — as of 2026-08-19 a minimal static placeholder (src/homePlaceholder.ts), not a live dashboard. It used to render every scored merchant's recommendation/signals/pricing directly, plus serve the same dataset as raw JSON at /api/wallets — see "Data access policy" below for why that was locked down. The real redesigned homepage/dashboard is a separate later task, built from Figma mockups, not this placeholder.

Note: the two-chain merchant-signal *data* above is separate from this endpoint's own payment rail — check_merchant itself is still only paid via Base x402 (see "Payment flow" line above); nothing about that has changed.

Data access policy (2026-08-19)

Structured merchant data — recommendation, signals, pricing, reasons, platforms, anything check_merchant returns — is available only through the paid check_merchant MCP tool, paid per-query via x402. This wasn't always true, and the change is worth recording plainly:

• / and /dashboard used to render a full live dashboard: every scored merchant, with its recommendation, signals, reasons, and pricing, straight from D1. Now a static placeholder (src/homePlaceholder.ts) with no D1 query at all.
• /api/wallets used to serve the exact same dataset as raw JSON — no rendering, no throttling, trivially scriptable. Now returns 404 for every method and every sub-path (/api/wallets/, ?query strings, HEAD, OPTIONS, POST, ...), with Cache-Control: no-store and no CORS headers.
• /merchant/ (a per-merchant profile page, added 2026-08-18 — see git history) is retired the same way, same reasoning: it returned the same fields for one wallet, and an agent calling check_merchant already has the one address it would need to read that page for free instead of paying. Code stays in src/merchantProfile.ts, unused, not deleted, in case a future *paid* or curated variant reuses it.

All three existed because giving humans/agents a free read of the same data check_merchant charges $0.01/query for directly undercut the product. check_merchant itself (src/tool.ts) was never affected — it has always read directly from D1 via src/db/queries.ts (getMerchantSignals, getComparablePrices, getOwnPrices), never through any of the routes above, so none of this required touching the paid tool's logic or schema.

Contact email. The privacy policy's CONTACT_EMAIL (src/privacy.ts) is info@gradientdecisions.com, replacing the developer's personal Gmail address that used to appear there and in this file. It's set up as a Cloudflare Email Routing forward to that same personal inbox — mail to info@ arrives at the existing Gmail, but the personal address itself no longer appears anywhere public-facing or committed. Email Routing is receive/forward-only: it cannot *send* mail as info@gradientdecisions.com. If sending-as is ever needed, that's a separate manual task (Google Workspace or custom SMTP), not something Email Routing does.

To enable it (Cloudflare dashboard, since this session has no Cloudflare API token to do it via API — see "Manual steps" note in the PR/commit this section shipped with):

1. Cloudflare dashboard → the gradientdecisions.com zone → Email → Email Routing.
2. Enable Email Routing for the zone. Cloudflare adds the required MX records (routing to its own mail servers) and a TXT record (v=spf1 include:_spf.mx.cloudflare.net ~all, or merged into an existing SPF record if one's already there) automatically — no manual DNS entry needed for a zone whose DNS Cloudflare already manages (true here, since custom_domain = true in wrangler.toml already put this zone on Cloudflare DNS).
3. Add a routing rule: info@gradientdecisions.com → Destination address → the existing personal Gmail address.
4. Cloudflare sends a verification email to that Gmail address the first time it's added as a destination — this needs a human to click the link, it can't be done programmatically. Until that's clicked, mail to info@ won't actually forward.

Additional payment protocols (researched 2026-08-19)

Prompted by Cloudflare's Agent Readiness "Commerce" checklist (ACP, AP2, MPP, UCP, x402) — the user explicitly said they don't care which protocol gets used, just that agents can actually pay, so each was researched against its real spec (not assumed) before deciding.

Shipped: GET /check (src/httpCheckEndpoint.ts) — a plain-HTTP x402 mirror of check_merchant, reusing the exact same facilitator/settlement path as /mcp. See that file's module comment for the full reasoning; short version, the MCP path's 402 challenge lives inside a JSON-RPC response body, invisible to any plain HTTP client (including Cloudflare's own scanner) that just sends a bare GET.

Researched, not implemented:

• ACP (Agentic Commerce Protocol — OpenAI/Stripe) and UCP (Universal Commerce Protocol — Google/Shopify/Etsy/Walmart): both are full retail-checkout standards — cart construction, delegated payment tokens, tax/shipping, returns, credential providers like Google Pay. Built for buying *products* from a *catalog*, not paying per metered API call. Confirmed via their actual specs (agenticcommerce.dev, developers.openai.com/commerce, orkes.io/blog/universal-commerce-protocol-ucp-explained) — the shape mismatch is structural, not a matter of more implementation effort.
• AP2 (Agent Payments Protocol — Google/PayPal): genuinely does support MCP as a transport, not only A2A as Cloudflare's scanner implies. Its core mechanic is cryptographically signed "mandates" — verifiable proof of a *user's* delegated purchase authority to an agent. Real and interesting, but solves a different problem (delegated consent for agent shopping on a user's behalf) than this service's model (an agent pays directly, no user-delegation layer needed). A proper project on its own, not a same-session addition.
• MPP (Machine Payments Protocol — Tempo/Stripe, mpp.dev): the closest conceptual fit — its own docs describe it for "paying for an API call... buying access to data," and its usdc charge method uses EIP-3009 transferWithAuthorization, the same signing primitive x402's exact scheme already uses. The blocker: MPP's spec has no facilitator model — unlike x402 (Coinbase's CDP facilitator submits/settles for us, never touching a private key on our side), MPP expects the *merchant's own server* to submit the transaction on-chain and pay gas directly. Real implementation needs:

1. A dedicated EVM wallet funded with ETH for gas, held as a new secret — a genuinely new operational responsibility (keeping it funded), unlike x402 where we never custody signing keys.
2. Server-side relayer code: parse the Authorization: Payment credential, submit the transferWithAuthorization call via an RPC provider, poll for confirmation, handle retries/failures.
3. A real security review before shipping — this is direct-custody, money-moving code, categorically different from x402's facilitator-mediated model.
4. WWW-Authenticate: Payment / Authorization: Payment header handling (RFC draft-ryan-httpauth-payment) alongside the existing x402 headers.

This is a multi-day infrastructure project (wallet funding, relayer, monitoring, security review), not a config change. Recommendation: revisit once GET /check or /mcp traffic shows real organic demand — query_log currently shows near-zero organic paid usage (see caller analytics), so a second payment rail isn't justified yet. Tracked here as a real roadmap item, not dropped.

Categorization

Additive to trust-tier scoring, doesn't touch src/scoring.ts. Every merchant gets a category from a fixed six-value set (src/categorize/types.ts: data_api, compute, content_generation, financial_data, storage, other) — never invented outside that set; anything the pipeline can't confidently place lands in other and is logged to category_review_log for a spot-check, not guessed.

Two passes, run once per wallet on first ingestion (not the 2-hour trust-signal cadence — a separate monthly cron force-re-runs everyone in case a listing's description changed, see wrangler.toml):

1. Rules (src/categorize/rules.ts) — keyword match against the Bazaar listing text. Only counts as confident if exactly one category matches; zero or multiple matches (ambiguous) fall through to pass 2.
2. Model (src/categorize/model.ts) — Claude Haiku (claude-haiku-4-5-20251001) given the fixed category list and the description, asked for exactly one value back. Response is validated against the fixed set before use — never trusted blindly; anything unparseable becomes other + logged.

`ANTHROPIC_API_KEY` (wrangler secret put ANTHROPIC_API_KEY) powers pass 2 — without it, every non-rule-matched description lands straight in other (logged as other_model_unavailable, not silently guessed). Set and confirmed working on 2026-08-11. POST /categorize (admin-token gated, same pattern as /refresh) processes the backlog — ?force=true re-categorizes everyone, ?limit=N caps how many per call (default 200) since a full force run across hundreds of wallets could exceed a single Worker invocation's execution time (confirmed by batching 4×100 manually).

Two real bugs found by actually running this against production, not by inspection — both fixed and redeployed:

• Rule matching used plain substring checks, which false-matched "compute" inside `