Agent-discovery metadata: Link headers, API catalog, content signals, llms.txt

[fmhall]

What

Makes x402scan discoverable to AI agents via standards-based mechanisms, directly addressing the isitagentready.com checks for link headers, API catalog, and content signals, plus a curated /llms.txt. All are pure code changes scoped to apps/scan.

1. RFC 8288 Link response header (all pages)

next.config.ts now emits a site-wide Link header advertising discovery resources, so an agent landing on any URL can bootstrap:

Link: </.well-known/api-catalog>; rel="api-catalog", </openapi.json>; rel="service-desc"; type="application/vnd.oai.openapi+json"

Next.js merges this with its own preload Link headers as separate header lines (correct RFC 8288 multi-header behavior).

2. RFC 9727 API catalog — /.well-known/api-catalog

New route handler returning application/linkset+json (an RFC 9264 link set) describing the existing /api/x402 API:

• service-desc → /openapi.json (machine-readable OpenAPI)
• service-doc → the GitHub repo (human docs)
• status → /api/health

Emits both the canonical relation-keyed members (RFC 9264 §4.2) and a flat links mirror for broad scanner compatibility.

3. /api/health

Dependency-free liveness endpoint (no DB/network) used as the catalog's status target.

4. Content Signals in robots.txt

Declares content-usage preferences for automated agents:

Content-Signal: search=yes, ai-train=yes, ai-input=yes

ai-input=yes because x402scan is an agent-facing explorer; ai-train=yes allows AI model training. These values are a site-owner policy decision — easy to change in src/app/robots.txt/route.ts if you want a different stance.

Converted from the robots.ts metadata convention to a route handler because that convention can't emit Content-Signal directives (existing sitemap reference preserved).

5. /llms.txt

Curated Markdown map of the site following the llmstxt.org format: H1 name, summary blockquote, then H2 link sections (Explore / For agents and developers / Documentation / Optional). Links point at clean-Markdown or machine-readable representations where they exist — the .md docs, the OpenAPI spec, and the API catalog. Every referenced path was status-checked (no 404s).

Notes

• tsconfig.json include gains an explicit src/app/.well-known/**/*.ts entry, because TypeScript's **/*.ts glob skips leading-dot directories (without it, eslint . fails to parse the api-catalog route). tsc + eslint now cover the file.
• All base URLs are env-driven via NEXT_PUBLIC_APP_URL (→ https://x402scan.com in prod, correct on preview deploys too).

Deliberately not included (and why)

• DNS-AID records / DNSSEC — DNS/ops change, not code.
• OAuth/OIDC discovery, OAuth protected-resource, auth.md — the API authenticates via x402 micropayments + SIWX, not OAuth. Publishing OAuth endpoints that 404 would mislead agents.
• MCP Server Card — the x402scan MCP is a stdio server (npx / .mcpb); there's no HTTP MCP endpoint to advertise.
• Agent-skills index — no SKILL.md files to list.
• Full Markdown content-negotiation (Accept: text/markdown) — genuinely useful but a larger, separate feature (needs per-route Markdown builders sourced from data, since the data pages render client-side). /llms.txt is the lightweight first step; the full version can follow.

Verification

Ran locally against next dev:

• GET / → carries the discovery Link header
• GET /.well-known/api-catalog → 200, Content-Type: application/linkset+json, valid linkset
• GET /robots.txt → 200, Content-Signal present
• GET /api/health → 200, {"status":"ok",...}
• GET /llms.txt → 200, text/plain; all referenced URLs status-checked (no 404s)

Prettier ✓, ESLint ✓ on all changed files. (The pre-existing Prisma schema-drift tsc errors and homepage/openapi 500s in local dev are unrelated — they need db:generate, which CI runs.)

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
x402scan	Ready	Preview, Comment	Jul 23, 2026 7:24pm