# ERC-8004 on a pay-per-call rail: a reference example

This is how the Genesis402 rail (https://twin.unykorn.org, operated by UnyKorn LLC, Wyoming) uses ERC-8004 end to end. It is written so another builder can copy the pattern. Every address and URL below is one you can open. The eight specialists were registered on Base on 2026-11-18 and are live; their ids are listed in section 1.

ERC-8004 gives an agent an on-chain identity (an NFT in an Identity Registry), a registration file the token points at, and registries for feedback and validation. It does not move money. The pattern here keeps money and identity separate on purpose.

## 1. The cast

| Role | Who | Identity |
|---|---|---|
| Collector | The rail's own agent. Its wallet (the treasury) receives every payment on the 376 treasury-paid routes. | ERC-8004 #95721 on Base |
| Specialists (8) | Prices, Chain Reader, DeFi, Web, Geo and Records, Research, AI Tools, Utilities. Each is the named seller of one family of routes. | #1208849 prices, #1208850 chain-reader, #1208851 defi, #1208852 web, #1208853 geo-records, #1208854 research, #1208855 ai-tools, #1208856 utilities |
| Desk sellers (5) | Five desk agents that sell one route each and are paid to their own wallets. | Own ERC-8004 ids |
| Desk, voice, owner-ready agents | The remaining vault agents. They sell nothing on the treasury routes. | Own ERC-8004 ids |

Chain: Base (eip155:8453). Identity Registry: `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432`. Validation Registry: `0x8004Cc8439f36fd5F9F049D9fF86523Df6dAAB58`. All 31 existing agents are owned by one vault address, `0xFCc1D28Ad797d65CDDb2A7219c5BE6B062653cb3`.

Why a collector and specialists: one wallet receiving payments keeps accounting simple (one treasury, one ledger), while eight named sellers let a buyer, an indexer and a reputation system tell a price feed from a chain reader. The collector is the money; the specialist is the product.

## 2. Identity: the registration file

Each agent has a registration file (type `https://eips.ethereum.org/EIPS/eip-8004#registration-v1`) at `https://twin.unykorn.org/agents/<slug>/registration.json`, and at `/agents/<agentId>/registration.json` once it has an id. Both return the same bytes, with CORS open.

A specialist card carries:

- `services`: one `x402` entry per route it sells (for example every `/price/...` route for Prices), plus `MCP` (`/mcp`), `A2A` (`/.well-known/agent-card.json`), `x402-discovery` (`/.well-known/x402`), the storefront (https://genesis402.com) and a `wallet` entry naming the treasury.
- `registrations`: one entry with the agent's `agentId` and the registry (an agent that is not registered yet would carry `[]`).
- `active`, `x402Support`, and a description that says plainly who collects the money.

Rule used throughout: a card lists only what exists. A service that does not exist is not listed; an id that does not exist is not printed.

Prices card: https://twin.unykorn.org/agents/1208849/registration.json (also by slug: /agents/prices/registration.json). Collector card: https://twin.unykorn.org/agents/95721/registration.json.

## 3. The seller in the 402

An unpaid call to any paid route answers HTTP 402 with the x402 payment requirements and a `seller` block. For a specialist route (the Prices route shown):

```json
{ "agent": "prices", "name": "Genesis402 Prices", "agent_id": 1208849, "specialist": "prices", "collector": 95721,
  "registry": "eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432", "chain": "base",
  "pay_to": "0x7d9a65d06dcc435a52D5880C6310Bd6E96c156DB", "card": "https://twin.unykorn.org/agents/prices/registration.json" }
```

- `specialist` is who sells the route; `collector` is whose wallet receives the payment; `pay_to` is read from the route's own `accepts[]`, never decided by the identity code.
- `agent_id` is the specialist's own id; `collector` is always 95721. (Before a specialist was registered, `agent_id` named the collector, 95721.)
- The `accepts[]` of every route is byte-identical before and after the change. A golden capture of all 381 routes pins it in the test suite.
- The same block is in the machine-readable `PAYMENT-REQUIRED` header, and each service in `/.well-known/x402` carries its `specialist`.

Try it: `curl -s -X POST https://twin.unykorn.org/price/bitcoin -H 'content-type: application/json' -d '{}'`

## 4. Receipts name the seller

Every paid call returns a signed receipt. For a specialist route the signed body adds `seller_specialist` and `collector_agent_id: 95721`, and `seller_agent_id` (the specialist's id, written since registration; earlier receipts carry only `seller_specialist` and the collector). Receipts are public in a sanitized view: https://twin.unykorn.org/receipts, and per agent at `/receipts?agent=<id-or-slug>`.

Treasury accounting does not change: a specialist's sale was paid to the treasury, so it is counted as a treasury sale and never as a sale paid to a separate wallet. The activity figure of the collector includes the specialists' sales; the fleet total does not add them twice.

## 5. Activity pages and badges

- Directory: https://twin.unykorn.org/agents (HTML) and https://twin.unykorn.org/agents.json. Five groups: Collector, Specialists, Desk agents, Voice agents, Owner-ready.
- Per agent: `/agents/<id-or-slug>/activity` and `.json`, newest first, filters `role=sold|paid` and `class=external|internal|tester|unattributed|sample`, with an explorer link per settled transaction.
- Badges: `/agents/<id-or-slug>/badge.svg` (external calls sold), `?variant=status`, `?variant=verified`, and the fleet badge `/agents/badge.svg`.
- Honest classes: a payer wallet the operator controls is `internal` and is shown beside the numbers, never counted as outside demand. Free first calls are counted apart. `/check` receipts are not listed.

## 6. Capability check

A card is a claim. The rail's guardian re-derives each agent's claims from its served card and checks them every 10 minutes without spending money: a GET for web, discovery and receipts entries, one free MCP `initialize`, and the unpaid 402 sweep for sold routes. Phone, email and wallet entries are not checked automatically and are shown as such. The badge variant `verified` is green only when every checkable claim passed in the last 30 minutes. A service that fails more than twice in a row is marked `degraded` on the card; it is never removed silently. Specialists are covered the same way.

## 7. Validation

The Validation Registry lets a validator publish a response about an agent's work. The rail's first published validation is for #95721: its manifest, request and response documents are served at https://twin.unykorn.org/validations/g402-2e35434d86f9e31e.json (and the two documents it names). A reader can hash the served documents with keccak256 and compare with the `request_hash` and `response_hash` in the manifest. Only ids on the publish list are served.

## 8. Cadence and internal activity

Our own desk agents buy one small call a day so identities appear on real receipts. Each specialist's own route is bought once a day (the cadence is configured and starts in dry-run) by a named desk agent, under the desk agent's spending policy, with per-call, per-agent and fleet caps and a kill file. Those receipts are internal and labelled so.

## 9. Registering the specialists

An owner-run script registered all eight with one confirmation word after printing every transaction, read each new id back from the mint event, checked owner and token URI, and wrote the ids to a config file (`data/specialists-ids.json` on the rail). The rail re-reads that file within 15 seconds, so naming the ids needed no release. To add an agent the same way: serve its card first, register it, then add its id to the file.

## 10. Copying the pattern

1. One wallet collects; name a seller per product family. Keep `payTo` out of the identity code.
2. Serve every card from the origin you operate, by slug first, by id once it exists. Never print an id you do not have.
3. Put the seller in the 402 and in the signed receipt. Pin `accepts[]` with a golden test.
4. Count per seller from the receipts ledger, and make the collector's figure the sum, so nothing is counted twice.
5. Publish a directory, per-agent activity and a badge; label internal activity.
6. Check every claim on every card on a schedule, and show the result.
7. Publish validations with hashes a stranger can recompute.

This document is served read-only at https://twin.unykorn.org/docs/erc-8004-reference.

The MCP server that exposes this rail to agents (`genesis402-mcp`) names the specialist seller in its tool results and groups its catalog by specialist; see its README section "How this rail uses ERC-8004".
