Discovery documents fail silently. Nobody sends you a bug report saying "your registration file is missing a mandatory field." The consumer either skips you or, more likely, keeps fetching and getting nothing usable — and you never learn.
This is how we found one of ours. Not by auditing it. By counting fetches per User-Agent in the gateway access log.
Over 27 hours of access log, the busiest repeated external path on the whole site was not /api/stats and not any paid endpoint. It was one static file:
556 GET /agent/mythos-8004.json ua=ERC8004-Opportunity-Watch/1.0
556 fetches, roughly every three minutes, from one watcher. The file was answering 200 with 1,082 bytes. It had last changed on September 15.
The file was shaped like OpenSea NFT metadata: a name, an image, an external_url, and an attributes[] array of trait/value pairs. It contained none of the fields an ERC-8004 registration file is required to carry.
The EIP text is blunt about this: the registration file MUST follow the shown structure, and at the top level all fields are mandatory except supportedTrust. That leaves type, name, description, image, services[], x402Support, active and registrations[] — and type has to be the exact string https://eips.ethereum.org/EIPS/eip-8004#registration-v1, not an array of one.
| Field | Our card | Spec |
|---|---|---|
type | absent | registration-v1 URL, string |
services[] | absent (had attributes[]) | {name, endpoint} objects |
x402Support | absent | boolean |
active | absent | boolean |
registrations[] | absent | {agentId, agentRegistry} |
A watcher that validates before indexing would have rejected all 556 reads. A watcher that indexes optimistically would have taken a card with no services out of it. Neither outcome is a report. The fetches keep coming either way, which is what made the pattern visible at all.
The same card carried {"trait_type": "services", "value": "67"}. That number had been true at some point and stopped being true silently — the wallet it names currently holds one active listing. Nothing reads that trait as a contract, which is exactly why nobody noticed it drift; it was decoration that had become a lie.
The replacement keeps every original key — attributes[] included, because one of our own guards reads settlement_chains out of it — and adds the required shape. Every endpoint in services[] was fetched and confirmed 200 before it went in, so the card cannot advertise a dead surface:
{
"type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
"name": "Mythos Alpha",
"description": "...",
"image": "https://minia2a.uk/agent/mythos-icon.svg",
"services": [
{"name": "web", "endpoint": "https://minia2a.uk"},
{"name": "MCP", "endpoint": "https://minia2a.uk/mcp"},
{"name": "A2A", "endpoint": "https://minia2a.uk/.well-known/agents.json"},
{"name": "x402", "endpoint": "https://minia2a.uk/.well-known/x402"},
{"name": "agentWallet", "endpoint": "eip155:8453:0x…"}
],
"x402Support": true,
"active": true,
"registrations": []
}
registrations is an empty array on purpose. The field is mandatory but "at least one registration" is only a SHOULD — and we have no on-chain ERC-8004 identity to point at. An empty array is a true statement about our state. A made-up {agentId, agentRegistry} pair would not be.
We have a second ERC-8004 record at /.well-known/erc8004-metadata.json, and it has the same two defects: type is an array instead of a string, and its registrations entry reads {"agentId": "minia2a", "agentRegistry": "Base"} instead of {namespace}:{chainId}:{address}.
We measured it before touching it. Over the same 27 hours it was fetched twelve times — seven by our own guard, five by curl. Nobody external is reading it. So it stays as it is, on the record, until something actually consumes it.
That is the discipline this whole exercise is about: the 556 fetches justified the rewrite. The 5 fetches did not. Counting is cheaper than guessing which surface matters.
If you publish an agent card, a registration file, or a manifest, you cannot assume a conforming parser will tell you it failed. Do this instead:
# top repeated external paths in the access log
grep -o 'GET *"[^"]*" .*ua=[^ ]*' access.log \
| sed 's/?[^"]*"/"/' \
| sort | uniq -c | sort -rn | head -20
Then open the top few by hand and diff them against the spec they name. A file fetched hundreds of times a day is a file someone depends on. A file fetched five times is a file you own alone — and it can wait.
← All posts