An Agent Lands on Your Homepage — What Can It Actually Read?

#ai #web3 #agents #arcblockchain

An AI agent evaluating a vendor does what a human does: it opens the site and looks for proof. The difference is speed and format — the agent gives you seconds, not minutes, and it wants JSON, not hero banners. Until recently, an agent landing on agentbadge.xyz found a page built for humans and nothing else — while our own readiness scanner was grading other sites on exactly the signals we lacked. The cobbler had no shoes. We fixed that: the entire discovery surface is now generated from live sources, served free with no auth, and verified by our own scanner in CI.

What does an agent find in 200 milliseconds?

Eleven machine-readable manifests, all 200 OK, all free, all generated — not hand-maintained:

/.well-known/agent-card.json        A2A v1.0 — who we are, skills[]
/.well-known/api-catalog            RFC 9727 linkset — every API entry
/.well-known/erc8004-agent.json     on-chain identity registration
/.well-known/mcp/server-card.json   MCP capabilities + tools surface
/.well-known/agent-evaluation.json  verification ladder (claims→refs)
/.well-known/owner-questions.json   "who runs this" for due-diligence
/.well-known/did.json               did:web:agentbadge.xyz document
/.well-known/did-configuration.json signed domain linkage (VC-JWT)
/.well-known/jwks.json              real Ed25519 key, kid'd
/.well-known/security.txt           RFC 9116, Expires generated +1y
/llms.txt                           agent-oriented sitemap

The agent-card alone answers the A2A handshake: name, provider, supportedInterfaces[], skills[] with tags and examples, and securitySchemes declaring x402 as the payment rail. One GET and a foreign agent knows our identity, capabilities, and how to pay.

Where do the manifests come from?

Not from a copywriter — from the code itself. A manifest registry collects the same live sources the runtime uses (openapi.ts, route config, blog-data.ts, the SKU catalog), and every manifest is a projection of that truth:

Boot-time: env-dependent manifests generate into a manifest registry at server start; routes serve from it — one source.
Build-time: bun run gen:discovery writes snapshots under public/.well-known/; manual edits are banned.
CI drift-check: regenerate + git diff --exit-code — if a manifest drifted from code, the build fails.

Ours cannot go stale without the build telling us.

What does a machine-readable sitemap look like?

llms.txt — the de-facto convention for telling an LLM "start here": H1 title, a blockquote describing the platform, ## sections of named links. Ours is generated with machine-readable entry points, quick start, free and paid endpoints — and the services section anchors into the same /api/v1/services catalog that powers the bazaar extension on every 402.

Why serve the same page twice?

Because the reader might not be a browser. Accept: text/markdown on any page returns the markdown representation — verified live:

$ curl -sH "Accept: text/markdown" https://agentbadge.xyz/blog
content-type: text/markdown; charset=utf-8

Blog articles carry .md mirrors too (/blog/arc-c10-payer-binding.md → 200 text/markdown). HTML stays canonical; <link rel="alternate" type="text/markdown"> points machines at the twin.

Can an agent verify our claims without trusting us?

agent-evaluation.json — a verification ladder: claims ordered by check-time, each with action + ref:

{
  "depth": "5s",
  "checks": [
    { "claim": "mainnet deployment — AgentEventLog on Arc",
      "action": "open",
      "ref": "https://explorer.arc.io/address/0x1bb6…4700" }
  ]
}

5s: we exist on-chain and publish a card. 60s: manifest validity, live OpenAPI, refusal contract. Deeper: dogfood txs and audit trails. owner-questions.json answers enterprise due-diligence (operator, jurisdiction, contact) in the same shape.

How do we know it works?

We run our own scanner on ourselves — the same 142-rule engine that grades foreign sites: mcp/server-card.json (AB-006), llms.txt (AB-014), JSON-LD/OG (AB-015/016), ai.txt (AB-017) — against agentbadge.xyz in CI. 100% pass required. A broken manifest fails our own product's grade on our own domain.

Honest status

Live: all 11 manifests 200, markdown negotiation serving text/markdown, .md mirrors on articles — generated, not hand-edited.
Deliberately absent: ai-plugin.json (ChatGPT Plugins EOL 2024 — dead manifest is cargo cult); /.well-known/agent.json → 301 to agent-card.json.
Verify now: curl https://agentbadge.xyz/.well-known/agent-card.json — or scan us: npx agentbadge-scan agentbadge.xyz.

C14 in the Arc Campaign series. C15 continues — the agent found us, now it reads the price list.

Originally published at agentbadge.xyz.

DEV Community