feat(sell): x402scan discovery correctness for host-bound offers — companion to #668

[bussyjd]

Summary

#668 proposes binding each offer to its own hostname (one tunnel, N origins) — exactly the right substrate, because x402scan groups discovered resources per origin (scheme://host). This is a companion to #668: the set of discovery-correctness behaviors obol-stack should emit/validate by default so that a host-bound offer actually indexes cleanly on x402scan, rather than being silently skipped.

Grounded in (a) reading x402scan's discovery implementation (Merit-Systems/x402scan + @agentcash/discovery), and (b) field experience running three offers (an ~80-endpoint HTTP API, an OpenAI-compatible agent, and an ERC-8004 feed) behind a single cloudflared tunnel.

Why — x402scan's actual rules (from its source)

• Per-origin grouping → an offer needs its own hostname (feat(sell): host-based offer routing — bind offers to dedicated hostnames (one tunnel, N origins) #668). ✔
• An OpenAPI operation is treated as paid only if it carries x-payment-info ({ price: {mode,currency,amount}, protocols: [{x402:{}}] }). Operations marked security: [] or referencing an apiKey-typed security scheme are classified unprotected / apiKey and skipped (@agentcash/discovery inferAuthMode; SKIP_AUTH_MODES = {unprotected, apiKey}). This is the biggest footgun: the conventional way to model x402 in OpenAPI — an apiKey securityScheme (header X-PAYMENT) — makes every paid endpoint invisible to x402scan.
• It reads /openapi.json and /.well-known/x402 FREE at the origin root.
• It probes each endpoint and requires the 402 challenge's resource.url to byte-match the probed URL (scheme included).
• It indexes base + solana only (testnets are skipped).
• It does not expand {path} templates — templated routes register as literal %7B…%7D (effectively uncallable); query-param endpoints index cleanly.

Gaps in obol-stack today (what an operator must hand-fix)

1. No x-payment-info story. A service whose OpenAPI marks paid ops with an apiKey security scheme (the natural modeling) is silently skipped. We had to drop security and emit x-payment-info per op to get listed.
2. Discovery docs. feat(sell): host-based offer routing — bind offers to dedicated hostnames (one tunnel, N origins) #668 makes /skill.md, /api/services.json, and ERC-8004 host-aware, but x402scan reads /openapi.json + /.well-known/x402 at the origin root — those must be served free there. Today the operator wires that by hand.
3. resource.url exactness. The x402-verifier's 402 must carry the public https origin+path. We had to force X-Forwarded-Proto: https and pin the service's PUBLIC_BASE_URL. For a host-bound offer (feat(sell): host-based offer routing — bind offers to dedicated hostnames (one tunnel, N origins) #668 spec.hostname) the verifier could derive the public origin automatically.
4. No network lint. A stale/testnet payment.network silently makes an offer un-indexable (cf. x402: base-sepolia advertises wrong EIP-712 domain name "USD Coin" (on-chain is "USDC") #612). obol sell could warn when network ∉ {base, solana}.
5. Templated path params. Operators get %7B…%7D resources on x402scan unless they use query params — worth a doc note / lint.

Proposal (companion to #668; small, declarative)

• Verifier: when an offer is host-bound (feat(sell): host-based offer routing — bind offers to dedicated hostnames (one tunnel, N origins) #668 spec.hostname), emit the 402 resource.url as https://<hostname><path> (honoring X-Forwarded-Proto/X-Forwarded-Host), so probe == challenge holds by construction (closes gap 3 generically).
• Discovery: serve (or transparently proxy the upstream's) /openapi.json + /.well-known/x402 free at the offer origin root, alongside the feat(sell): host-based offer routing — bind offers to dedicated hostnames (one tunnel, N origins) #668/feat(sell): allow for the control of your storefront branding  #663 host-aware /skill.md + /api/services.json. (Relates to Idea: Publish a swagger file on the tunnel? #563 "publish a swagger file on the tunnel" and Make an llms.txt for tunnel storefronts #596 "llms.txt for tunnel storefronts".)
• obol sell validation / lint: warn if payment.network ∉ {base, solana}; optionally lint the upstream's /openapi.json for paid ops that are missing x-payment-info or that use security: [] / apiKey schemes (the two skip cases), and flag literal {path} / %7B%7D resources.
• Docs: an "x402scan discovery contract" operator checklist — per-origin host, x-payment-info (not apiKey security), free root /openapi.json + /.well-known/x402, exact https resource.url, base/solana, query-params over path-templates.
• DNS UX (relates to feat(sell): host-based offer routing — bind offers to dedicated hostnames (one tunnel, N origins) #668 step 5): prefer a remotely-managed (token) tunnel so adding a Public Hostname auto-creates its DNS record — removing the manual CNAME step. Today the default is a locally-managed config.yml with hand-created DNS, which is also where the "old catch-all rule shadows new hosts" ordering footgun comes from.

Field context (verified)

Three offers behind one cloudflared (currently locally-managed config.yml, explicit per-host ingress, manually-created DNS). Before addressing the above, x402scan listed 0 of ~80 paid endpoints — all classified apiKey/unprotected and skipped — even though every endpoint correctly returned a 402 challenge. After emitting x-payment-info, dropping the apiKey security scheme, serving free /openapi.json + /.well-known/x402 at the host root, pinning the public https resource.url, and moving path params to query params, all paid endpoints index cleanly, while infra/meta endpoints (/healthz, /openapi.json, MCP plumbing) are intentionally excluded via security: [].

References

• feat(sell): host-based offer routing — bind offers to dedicated hostnames (one tunnel, N origins) #668 host-based offer routing (substrate) · Architecture proposal: customizable public storefront via A2UI-style surface contract #669 storefront surface contract · feat(sell): allow for the control of your storefront branding  #663 storefront branding / /api/storefront.json · Architecture proposal: storefront paid chat via x402 batch-settlement channels #671 paid chat via batch settlement · sell --accept: cli/v3 comma-splits the value → "network is required" (multi-currency offers unreachable from CLI) #664 sell --accept CLI bug · Multiple storefronts in one stack #656 / Customisable storefronts #562 multiple storefronts · Make an llms.txt for tunnel storefronts #596 llms.txt for tunnel storefronts · Idea: Publish a swagger file on the tunnel? #563 publish a swagger file on the tunnel · x402: base-sepolia advertises wrong EIP-712 domain name "USD Coin" (on-chain is "USDC") #612 base-sepolia EIP-712 domain
• x402scan discovery: Merit-Systems/x402scan (apps/scan/src/lib/url.ts, apps/scan/src/lib/discovery/*, @agentcash/discovery inferAuthMode).

---

_{Filed via Claude Code from field experience running multiple x402 offers on obol-stack + reading the x402scan discovery source. https://claude.ai/code/session_01VquWN9UMaSHH7MHGcG8bw1}

[bussyjd]

Two recurring footguns to fold in (from running 3 paid offers + a paying agent on one cluster)

Beyond the discovery-correctness items, two platform behaviors repeatedly broke our seller UI and x402scan discovery. Both deserve acceptance criteria here because they're the difference between "per-offer subdomain works once" and "stays working".

A. obol tunnel hostname add must be idempotent — it must not swallow seller subdomains

Each obol tunnel hostname add <h> re-renders the tunnel-storefront HTTPRoute to include every hostname with PathPrefix /. That catch-all then shadows every seller per-host landing / discovery route (ties on hostname+path → the older storefront route wins). It bit us twice: custom landings and /.well-known/x402 silently reverted to the default Next.js storefront (404), which also breaks x402scan (it can't read the discovery doc).

• AC: adding a hostname must not modify routing for hostnames that already have seller-owned routes; the default storefront should be apex-only (or explicit opt-in per host); re-running for an existing host is a no-op.

B. The default storefront must DEFER to seller routes

Today a seller landing only wins by using an Exact path match (Exact > PathPrefix) — a workaround, not a contract. The platform storefront should never out-rank a seller's own route for the same host.

• AC: a seller HTTPRoute (or the Architecture proposal: customizable public storefront via A2UI-style surface contract #669 storefront profile) for <offer>.<zone>/ always wins over the default storefront; the storefront only serves hosts with no seller landing.

Why it matters

Combined with the discovery-by-default items, a seller gets a clean x402scan listing and a branded landing with zero manual route surgery. Until then the working manual recipe is: own subdomain origin, x-payment-info (not apiKey security), free /openapi.json + /.well-known/x402 at the root, https resource.url (X-Forwarded-Proto), network ∈ {base,solana}, and Exact carve-out routes so they survive the clobber above. Relates to #668 (native --hostname), #669/#663 (storefront profile), #656 (multiple storefronts).

[bussyjd]

Follow-up: 3 new findings from a live agentcash-CLI verification pass (2026-07-01)

Re-tested hyperliquid-data.v1337.org end-to-end against the real npx agentcash@latest {try,check,fetch} (not just curl) after an x402scan maintainer reported it "prevents working." Two of the reported symptoms turned out to be real bugs with simpler fixes than expected; one didn't reproduce. Adding for whoever picks this up.

1. servers.url should be the bare origin — no path suffix — because check/fetch do a raw path lookup, not OpenAPI server+path resolution.
Confirmed empirically: agentcash check against <origin>/services/<name>/v1/... (servers.url + path, textbook OpenAPI resolution) returns "error": "not_found". The same operation at <origin>/v1/... (bare path, no servers.url prefix) resolves correctly with full schema + pricing. So agentcash's matcher indexes directly off openapi.json's paths keys and never concatenates servers.url. This refines gap 3 in the issue body: a host-bound offer doesn't need the verifier to emit a host-aware resource.url for basic client compatibility — it needs servers.url to be the bare origin. (The verifier's resource.url can still report the internal /services/<name>-prefixed path — verified that mismatch does NOT block agentcash fetch, which reached a clean INSUFFICIENT_BALANCE past a correctly-parsed 402 on both URL shapes. So "byte-match" wasn't actually the blocker.)

2. apiKey+paid is a real, listed authMode distinct from apiKey — worth correcting gap 2's framing.
Decompiled @agentcash/discovery@1.7.5's inferAuthMode: an op with x-payment-info and a security ref to an apiKey-typed scheme classifies as "apiKey+paid", which is counted as a registerable paid route (hasPaidRoute = routes.some(r => r.authMode === "paid" || r.authMode === "apiKey+paid")). Only apiKey without x-payment-info gets skipped. So operators don't need to drop security entirely (as the current issue text implies) — just make sure x-payment-info is present alongside it.

3. The verifier has zero free-path-allowlist support inside a gated prefix — confirms gap 3's "operator must hand-wire this."
Read verifier.go/matcher.go: route matching is all-or-nothing per matched path pattern; there's no mechanism to exempt a sub-path (e.g. /v1/openapi.json) from payment while the rest of /v1/* stays gated. Every "free discovery route under a paid prefix" has to be a separate, higher-priority Exact route at the Gateway layer, hand-maintained per offer. Bonus finding while in the source: x402-verifier's bazaar.go BuildBazaarExtension hardcodes method: "POST"/bodyType: "json" for every non-chat-completion offer, regardless of the actual route's HTTP method or params — so GET endpoints get a misleading bazaar hint. Not in scope of #668/#679 but adjacent; happy to open a separate issue if useful.

Full write-up (with file:line citations) available if helpful — practical workaround for #1 and #2 already shipped in v1337's overlay, documented in deploy/x402scan-discovery/SELLER-PARITY-GUIDE.md on that fork.

[bussyjd]

Found a concrete instance of this gap on v0.13.0: the controller-rendered shared-origin routes (so-<name>, PathPrefix /services/<name> → verifier) carry NO X-Forwarded-Proto: https RequestHeaderModifier, while the host-bound routes (so-<name>-host) do (render.go:783). Because the shared-origin route is hostname-less and more path-specific, it wins the match for /services/<name> even on dedicated-hostname origins — so 402 challenges there advertise http:// resource URLs behind a TLS-terminating tunnel. Strict v2 clients and discovery crawlers see an http resource on an https endpoint. Fix candidates: add the same header filter to the shared-origin route rules, or document that operators should set entryPoints.web.forwardedHeaders.trustedIPs to the pod CIDR so the tunnel's own X-Forwarded-Proto survives Traefik (verified working).