merchant-check-mcp-

# 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](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](https://gradientdecisions.com/privacy) 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/<address>` (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 is