Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

35.8 KB
Raw Blame

ERC-8004 Blockchain Identity

Give your AI agent a permanent, verifiable, on-chain identity. ERC-8004 is a proposed Ethereum standard for registering agents in a public smart contract registry so that anyone — wallets, other agents, dApps — can look them up, verify their ownership, and trust their reputation without relying on any centralized database.

This document explains the standard, how the three contracts work, and how to register, resolve, and build with ERC-8004 agents programmatically.


What is ERC-8004?

ERC-8004 defines a protocol for registering AI agents on-chain. At its core it is three things:

  1. A registry smart contract — agents are minted as ERC-721 tokens. Each token ID is an agentId. The token's tokenURI points to the agent's metadata document.
  2. A standard JSON document — the metadata (called an agent card) describes the agent's name, avatar, services, and on-chain registration. It is hosted on IPFS so it is content-addressed and permanent.
  3. A resolution protocol — you can look up any agent by chain + ID, by wallet address, or by ENS name. The format eip155:<chainId>:<registryAddress>:<agentId> (CAIP-10) is the canonical global identifier.

Once registered, an agent has properties that no platform can revoke:

  • Ownership — cryptographic proof, via an ERC-721 NFT in your wallet
  • Permanence — the on-chain record can't be deleted or censored
  • Transferability — you can sell or transfer the agent like any NFT
  • Composability — other agents and dApps reference it by its CAIP-10 identifier
  • Reputation — users submit signed on-chain feedback that aggregates permanently
  • Validation attestations — third-party validators record technical quality checks on-chain

Why register on-chain?

The honest answer: you don't have to. The three.ws platform works without blockchain identity. But if you want your agent to exist beyond this platform, registration gives you things a database can't:

Discoverability without a central server. Anyone with a wallet and a chain ID can find your agent. There is no API key required, no account to create. The registry is a public contract.

Verifiable provenance. The registration transaction is timestamped and signed by your wallet. If someone forks your agent, the chain proves who registered first.

ENS integration. You can link your agent to youragent.eth so humans can find it by name rather than a numeric ID.

Cross-platform composability. Any EVM-compatible dApp, agent framework, or wallet can resolve your agent by its CAIP-10 ID without going through three.ws. The resolveOnchainAgent() resolver is open source.

Reputation that travels. Stars and reviews are on-chain. They follow the agent wherever it is displayed — your site, another platform, a Claude.ai artifact.


Supported chains

The registry contracts are deployed deterministically (via CREATE2) to the same addresses on every supported chain.

Mainnets

Chain Chain ID Explorer
Ethereum 1 etherscan.io
Base 8453 basescan.org
Optimism 10 optimistic.etherscan.io
Arbitrum One 42161 arbiscan.io
Polygon 137 polygonscan.com
BNB Chain 56 bscscan.com
Avalanche 43114 snowtrace.io
Celo 42220 celoscan.io
Gnosis 100 gnosisscan.io
Linea 59144 lineascan.build
Scroll 534352 scrollscan.com
Mantle 5000 explorer.mantle.xyz
zkSync Era 324 explorer.zksync.io
Moonbeam 1284 moonbeam.moonscan.io
Fantom 250 ftmscan.com

Testnets

Chain Chain ID
Ethereum Sepolia 11155111
Base Sepolia 84532
Arbitrum Sepolia 421614
Optimism Sepolia 11155420
Polygon Amoy 80002
Avalanche Fuji 43113
BSC Testnet 97

Base (chain ID 8453) is the recommended chain for new registrations. Gas costs are a fraction of Ethereum mainnet, finality is fast (~2 seconds), and it is EVM-compatible so every Ethereum tool works unchanged. Start on Base Sepolia (84532) to test for free before going to mainnet.


The three contracts

ERC-8004 uses three separate contracts so that identity, reputation, and validation concerns stay cleanly separated. All three are deployed at the same addresses on every supported chain.

Mainnet addresses (identical on all 15 mainnets listed above):

  • IdentityRegistry: 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432
  • ReputationRegistry: 0x8004BAa17C55a88189AE136b182e5fdA19dE9b63
  • ValidationRegistry: not yet deployed on mainnet

Testnet addresses (identical on all 7 testnets listed above):

  • IdentityRegistry: 0x8004A818BFB912233c491871b3d84c89A494BD9e
  • ReputationRegistry: 0x8004B663056A597Dffe9eCcC1965A193B7388713
  • ValidationRegistry: 0x8004Cb1BF31DAf7788923b405b754f57acEB4272

IdentityRegistry.sol

The core registry. Agents are ERC-721 tokens. Minting a token = registering an agent.

register()                                          → uint256 agentId
register(string agentURI)                           → uint256 agentId
register(string agentURI, MetadataEntry[] metadata) → uint256 agentId
setAgentURI(uint256 agentId, string newURI)
tokenURI(uint256 agentId)                           → string
setMetadata(uint256 agentId, string key, bytes val)
getMetadata(uint256 agentId, string key)            → bytes
setAgentWallet(uint256 agentId, address, deadline, sig)
getAgentWallet(uint256 agentId)                     → address
ownerOf(uint256 agentId)                            → address
isAgent(uint256 agentId)                            → bool

The typical registration flow calls register(agentURI) to mint the token and set a seed URI, then calls setAgentURI(agentId, finalMetadataURL) once the full agent card is pinned. Both calls emit events that indexers track.

setAgentWallet lets you delegate a separate hot wallet for agent operations without moving the ownership NFT. The delegation requires an EIP-712 signature from the NFT owner — this prevents anyone but the owner from rebinding the wallet.

ReputationRegistry.sol

Signed on-chain feedback about an agent. Two dialects exist, and the one that matters is not the one in this repo.

The canonical registries at the 0x8004... addresses run the ERC-8004 reference implementation (ReputationRegistryUpgradeable). Reputation there is a per-reviewer ledger with no global average:

giveFeedback(uint256 agentId, int128 value, uint8 valueDecimals,
             string tag1, string tag2, string endpoint, string feedbackURI, bytes32 feedbackHash)
getClients(uint256 agentId) → address[]
getSummary(uint256 agentId, address[] clientAddresses, string tag1, string tag2)
        → (uint64 count, int128 summaryValue, uint8 summaryValueDecimals)
readFeedback(uint256 agentId, address client, uint64 index) → (value, decimals, tag1, tag2, isRevoked)

getSummary reverts with "clientAddresses required" on an empty list: you must say whose feedback you count, which is the standard's sybil defence. Pass getClients(agentId) to count everyone. Values are 0 to 100 by convention, giveFeedback rejects the agent's own owner and operators, and there is no staking. The registries are upgradeable proxies, so treat this interface as something to detect, not assume.

contracts/src/ReputationRegistry.sol in this repo is an older, simpler dialect that only exists where someone deployed it themselves:

submitFeedback(uint256 agentId, int8 score, string uri)
getReputation(uint256 agentId) → (int256 avgX100, uint256 count)
getFeedbackCount(uint256 agentId) → uint256
getFeedback(uint256 agentId, uint256 index) → Feedback
getFeedbackRange(uint256 agentId, uint256 offset, uint256 limit) → Feedback[]

There, scores are signed integers from −100 to +100 and getReputation returns the average multiplied by 100 (divide by 100 on the client). The uri field is optional.

Never call either dialect directly. src/erc8004/reputation-read.js detects which one lives at an address by behaviour and reads it correctly; src/erc8004/reputation.js builds the write path, recent reviews and staking support on top of it.

On the legacy dialect three invariants are enforced by the contract: agents can't review themselves (SelfReviewForbidden), each address can only submit one review per agent (AlreadyReviewed), and scores outside −100..+100 are rejected (ScoreOutOfRange).

ValidationRegistry

The deployed registry is the ERC-8004 reference ValidationRegistryUpgradeable, not the contracts/src/ValidationRegistry.sol in this repo (that one is an alternative design and is deployed nowhere). Attestations are two-legged: the agent's owner opens a request naming a validator, and only that validator can answer it. There is no validator allowlist.

validationRequest(address validator, uint256 agentId, string requestURI, bytes32 requestHash)
validationResponse(bytes32 requestHash, uint8 response, string responseURI, bytes32 responseHash, string tag)
getValidationStatus(bytes32 requestHash) -> (validator, agentId, response, responseHash, tag, lastUpdate)
getAgentValidations(uint256 agentId) -> bytes32[]
getValidatorRequests(address validator) -> bytes32[]
getSummary(uint256 agentId, address[] validators, string tag) -> (count, avgResponse)

tag is a free-form suite name: "glb-schema" for glTF format checks, "a2a-card" for agent-to-agent protocol compatibility, and so on. response is a 0..100 score (three.ws writes 100 for a pass, 0 for a fail, and reads 50 and above as passing). responseHash is a keccak256 of the off-chain report JSON, so anyone can verify an attestation by re-running the validator, hashing the output, and comparing. responseURI is emitted in the event but not stored, so keep an index (or read the event) if you want the report link.

requestHash is chosen by the requester. three.ws derives it as keccak256(abi.encode(chainId, agentId, kind, subjectHash)), which keeps re-validation idempotent: the same subject answers the same request rather than creating a new one.

The Validation Registry is not yet deployed on mainnet. It is available on all testnets.


Registering an agent

Step 1: Connect your wallet

The three.ws app supports any injected EIP-1193 provider:

  • MetaMask — browser extension, desktop
  • WalletConnect — mobile wallets (Rainbow, Zerion, Trust, etc.)
  • Privy — email or social login with an embedded wallet (no browser extension required)
  • Brave Wallet, Coinbase Wallet, or any injected window.ethereum

Click "Connect Wallet" in the editor or dashboard. The app reads your current chain from the wallet and switches to your chosen target chain automatically.

Step 2: Prepare your agent

Before registering, your agent needs:

  • A GLB avatar file (uploaded in the 3D editor)
  • A name and description
  • Optionally: a 2D thumbnail, personality configuration, and service endpoints

The registration wizard auto-generates the agent card JSON from your editor state.

Step 3: Upload to IPFS

The agent card and GLB are pinned to IPFS to create stable, content-addressed URLs. The platform pins files automatically via its backend storage. If you prefer to pin yourself, you can provide a Pinata JWT token: the system will upload directly to Pinata and return ipfs:// URLs. That direct upload is bounded to 60 seconds, and a Pinata failure or timeout falls through to the platform's own pinning route (/api/erc8004/pin) rather than failing the registration mid-flow, so the token is a preference, not a requirement.

The GLB auto-thumbnail feature renders a PNG from your 3D model server-side so that NFT marketplaces and social cards display a 2D preview. You can supply your own image instead.

Step 4: Sign the on-chain transaction

The actual registration is a two-transaction sequence:

  1. register(seedURI) — mints the ERC-721 token and emits a Registered event with your agentId. The seed URI is the GLB URL; it makes the registration immediately useful even if the next step fails.
  2. setAgentURI(agentId, metadataURL) — updates the token URI to point at the full agent card JSON on IPFS.

Your wallet prompts you to sign both. Gas is paid in the native currency of your chosen chain (ETH on Base, ETH on Ethereum, etc.).

Typical confirmation time on Base: 2–4 seconds.

Step 5: Your agent URL

After registration, your agent is live at:

https://three.ws/a/<chainId>/<agentId>

This page resolves the agent card from the chain, renders the 3D avatar, shows the ERC-8004 Passport widget, and links to the on-chain explorer transaction. An embed-only version without chrome is available at:

https://three.ws/a/<chainId>/<agentId>/embed

Gasless agent registration on BNB

A brand-new wallet holding zero tBNB can mint its ERC-8004 identity on BSC Testnet in one click — no faucet, no funding, no wallet-connect step. This is BNB Chain's BEP-414 paymaster (MegaFuel, operated by NodeReal): a plain private-key EOA signs a normal transaction with gasPrice: 0, and a sponsor transaction pairs with it atomically at the block-builder layer. It's mechanically impossible on Ethereum L1/Base (EIP-1559 rejects a zero-fee tx; ERC-4337 needs a smart account; EIP-7702 needs delegation) — see prompts/bnb-chain/00-CONTEXT.md for the full verified-facts writeup.

How it works, end to end:

  1. The browser generates a fresh, page-local ephemeral BSC account (src/erc8004/gasless-register.js, getEphemeralAccount()). Its private key is stored in sessionStorage only — it never leaves the browser and is never sent anywhere.
  2. It signs a legacy register(agentURI) transaction against the Identity Registry with gasPrice: 0.
  3. The signed bytes (not the key) are POSTed to /api/bnb/register-agent, which probes MegaFuel's pm_isSponsorable and, if sponsorable, relays the exact bytes via eth_sendRawTransaction to MegaFuel's paymaster (api/_lib/bnb/megafuel.js, api/_lib/bnb/erc8004-gasless.js).
  4. If MegaFuel declines sponsorship, the endpoint returns { mode: 'declined', reason, hint } instead of failing — a zero-gasPrice transaction can never be broadcast to a normal node outside the paymaster path, so there is nothing to retry blindly. The UI shows the wallet address and a "fund it and retry" prompt; a self-pay retry re-signs the same call with a real gasPrice and broadcasts normally.

Try it: go to /deploy, pick BSC Testnet in the network selector, fill in a name and description, and on the final "Review & Deploy" step click ⚡ Register gasless (0 tBNB wallet) — no wallet extension required for this path.

Server endpoint — POST /api/bnb/register-agent:

curl -X POST https://three.ws/api/bnb/register-agent \
  -H 'content-type: application/json' \
  -d '{
    "signedRegisterTx": "0xf8...<a legacy, gasPrice:0, signed register() tx>",
    "network": "bscTestnet"
  }'

A real response, sponsored (zero-balance wallet, live BSC testnet, 2026-07-08):

{
  "mode": "sponsored",
  "address": "0xfb35130d94D80437eb3350c71e2c62898e9c57E3",
  "network": "bscTestnet",
  "sponsor": { "sponsorable": true, "sponsorName": "Yolin", "sponsorIcon": "Yolin" },
  "pending": false,
  "agentId": "1593",
  "hash": "0x29b2999e1543d7e6d4eba21b41b33718d8e0196e18c1510d39e4cffcfe52bc95",
  "blockNumber": 117842997,
  "explorerUrl": "https://testnet.bscscan.com/tx/0x29b2999e1543d7e6d4eba21b41b33718d8e0196e18c1510d39e4cffcfe52bc95"
}

That transaction's receipt shows effectiveGasPrice: 0x0 and status: 0x1 on the live public RPC — a genuinely free, sponsored mint, not a simulation.

Response shapes:

Shape When
{ mode: 'sponsored', hash, agentId, explorerUrl } MegaFuel accepted the probe and relayed the exact signed bytes.
{ mode: 'self-pay', hash, agentId, explorerUrl } The caller re-signed with a real gasPrice (after a decline, or knowing sponsorship was unavailable) and the endpoint broadcast it normally.
{ mode: 'declined', reason, hint, address } MegaFuel has no sponsor policy for this address right now. No broadcast was attempted — resign with a real gasPrice and POST again to self-pay.
{ alreadyRegistered: true, agentId, address, explorerUrl } This address already owns an agent on the registry — no new mint. agentId is null when the deployed registry doesn't implement tokenOfOwnerByIndex (confirmed live on the BSC Testnet Identity Registry, 2026-07-08 — balanceOf still proves the address is registered even when the id itself can't be resolved).

Known limits:

  • This flow targets the ERC-8004 Identity Registry only, on BSC Testnet (chainId 97) by default; network: "bscMainnet" is supported by the relay but real MegaFuel sponsor policies are provisioned per environment by the operator.
  • The mint seeds the token URI with the GLB/image URL only (matching the first transaction of the standard two-transaction flow above) — pointing it at the full agent card JSON still requires a follow-up setAgentURI call, which this gasless path does not perform automatically.
  • MegaFuel sponsorship is a NodeReal-operated service with whitelisted policies — a decline is a normal, expected response, not an error; the self-pay fallback always completes the mint once the wallet holds a small amount of tBNB (well under $0.01 at BSC Testnet gas prices).

The agent card format

The document your tokenURI resolves to is an agent card — a JSON file pinned to IPFS. Here is a minimal example:

{
  "type": [
    "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
    "https://three.ws/specs/3d-agent-card-v1"
  ],
  "name": "Coach Leo",
  "description": "A football coach who reviews your form.",
  "image": "ipfs://bafy.../poster.webp",
  "model": {
    "uri": "ipfs://bafy.../body.glb",
    "format": "gltf-binary",
    "sha256": "9f86d081..."
  },
  "registrations": [
    {
      "agentId": 42,
      "agentRegistry": "eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432"
    }
  ],
  "services": [
    { "name": "avatar", "endpoint": "ipfs://bafy.../body.glb", "version": "gltf-2.0" },
    { "name": "3D", "endpoint": "https://three.ws/#model=ipfs://...", "version": "1.0" }
  ],
  "supportedTrust": ["reputation", "validation"],
  "active": true
}

The type array declares both the base ERC-8004 spec and the three.ws Card v1 extension. The model block (required by the extension) provides a content-addressable pointer to the GLB and a SHA-256 hash so consumers can verify the model bytes independently of the hosting location. The services array lists endpoints for different consumers — the avatar entry is the raw GLB, the 3D entry is a renderer URL that works in any browser.


Resolving agents

Reference formats

The resolver understands several equivalent ways to refer to an agent:

Format Example
CAIP-10 full eip155:8453:0x8004A169...:42
CAIP-10 asset type eip155:8453/erc721:0x8004A169.../42
Shorthand onchain:8453:42
Agent URI agent://8453/42
URL path /a/8453/42

JavaScript SDK

The resolver lives in the open-source three.ws codebase at src/erc8004/resolver.js; it is not part of the @three-ws/sdk npm package, so vendor the module or import it in-repo:

import { resolveOnchainAgent, parseAgentRef } from './src/erc8004/resolver.js';

// By chain + agent ID
const agent = await resolveOnchainAgent({ chainId: 8453, agentId: 42 });

// By CAIP-10 string
const agent = await resolveOnchainAgent('eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432:42');

// By URL path
const agent = await resolveOnchainAgent('/a/8453/42');

// Result shape:
// {
//   ref: { chainId, agentId, registry },
//   caip: 'eip155:8453:0x8004A...:42',
//   publicUrl: 'https://three.ws/a/8453/42',
//   chain: { name: 'Base', testnet: false, explorer: 'https://basescan.org' },
//   onchain: { owner: '0xYourAddress', uri: 'ipfs://...' },
//   metadata: { ... full agent card ... },
//   name: 'Coach Leo',
//   description: '...',
//   image: 'https://ipfs.filebase.io/ipfs/...',
//   glbUrl: 'https://ipfs.filebase.io/ipfs/...',
//   services: [ ... ]
// }

The resolver caches results per page session. Pass { fresh: true } to bypass the cache.

publicUrl and the metadata proxy fallback (below) default to the current page's origin. When you call the resolver from a page that is not three.ws, pass { origin: 'https://three.ws' } so publicUrl links to the three.ws agent page and the proxy retry goes to three.ws rather than to your own host.

Web component

<!-- CAIP-10 format in the agent-id attribute -->
<agent-3d agent-id="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432:42"></agent-3d>

<!-- Shorthand -->
<agent-3d agent-id="onchain:8453:42"></agent-3d>

The <agent-3d> element boots the full agent runtime — 3D rendering, memory, skills, and conversation — using the on-chain identity as its manifest source.

IPFS fallbacks

resolveUrl(uri) turns an ipfs:// URI into a single URL on the primary gateway (ipfs.filebase.io, the head of the shared list). resolveUrlCandidates(uri) returns the full ordered chain for the same content, and it no longer keeps a gateway list of its own: it delegates to uriCandidates() in src/ipfs.js, which owns the one live, dead-host-free list for the whole platform. Today that chain is ipfs.filebase.io (the primary, kept at the head), then 4everland.io and gateway.pinata.cloud. ipfs.io, dweb.link, w3s.link and nftstorage.link were dropped in October 2026 when they began answering programmatic reads with HTTP 429, and a URL already baked onto one of them is rewritten onto the primary. uriCandidates() also re-extracts the CID from a URL whose gateway was already baked in upstream, so a card that hardcodes one gateway is still rotatable.

The manifest toManifest(resolved) builds keeps image and body.uri as single URLs (nothing that consumes them changes), and alongside them carries _gatewayCandidates.body and _gatewayCandidates.image: the ordered chain for each, starting with that same single URL. A consumer that can retry (an <img> fallback chain, a GLB loader) walks those instead of giving up on one dead gateway.

Arweave (ar://) URIs are resolved through arweave.net.

When the registration host blocks the browser

An agent card lives wherever its registrant put it, and most of those hosts send no Access-Control-Allow-Origin header. A browser therefore cannot read them at all: the fetch is blocked before the response is delivered, and the agent page used to render "Could not fetch registration JSON: Failed to fetch" for every such agent.

The browser tries the card's URL directly first (fast, no extra hop). When that fetch fails, it retries through a first-party proxy that fetches server-side, where the same-origin policy does not apply:

GET /api/erc8004/metadata?uri=<registration uri>
curl -s 'https://three.ws/api/erc8004/metadata?uri=ipfs://bafyExampleAgentCard'
# → { "data": { ...the agent card... }, "resolvedUrl": "https://ipfs.filebase.io/ipfs/bafyExampleAgentCard" }

Public, keyless, and rate-limited per IP. ipfs:// and ar:// are resolved to their public gateways first, and successful lookups are edge-cached for ten minutes. Because the URI comes off-chain from whoever registered the agent, the fetch runs behind the platform SSRF guard (api/_lib/ssrf-guard.js): DNS is validated, the socket is pinned to the checked address, every redirect hop is re-validated, and the response is capped at 2 MB. A URI pointing at a private or cloud-metadata address is refused with 400 blocked_uri, a body over the cap with 413 too_large; a host that answers with something other than JSON is reported as 502 invalid_json rather than passed through.


ENS and DNS integration

You can link your agent to a human-readable name using ENS or a DNS TXT record. This creates a bidirectional, verifiable binding between a name and an on-chain agent.

ENS (recommended)

  1. Go to app.ens.domains and open your ENS name
  2. Navigate to Records → Text records
  3. Add a text record with key agent and value:
    eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432/42
    
  4. Save (requires one gas transaction)

Now resolvers can look up yourname.eth and get your agent's CAIP-10 identifier.

DNS TXT record

For domains without ENS, publish a TXT record at _agent.<yourdomain>:

_agent.example.com.  IN  TXT  "v=agent1; ref=eip155:8453:0x8004A169.../42"

Reverse verification

For a binding to be verified (not just claimed), both directions must match:

  • Forward: the ENS or DNS record points to the agent's CAIP-10 ID
  • Reverse: the agent card's claims array lists the ENS/DNS name
"claims": [
  { "type": "ens",  "name": "yourname.eth" },
  { "type": "dns",  "name": "yourdomain.com" }
]

A name-only claim with no reverse record, or a reverse record with no name binding, is shown as unverified in the UI. Either direction alone is useful for discovery but not for trust. ENS-verified bindings are treated as stronger than DNS-verified because ENS is not susceptible to DNS hijacking.


Reputation

After registering, your agent starts accumulating on-chain reputation. Any wallet except the agent's own owner can submit feedback.

How scoring works

Every three.ws surface shows reputation as 1 to 5 stars. On the canonical registries a star is 20 points on the 0 to 100 scale, so a 5-star review is written as 100 and an on-chain average of 82 reads as 4.1. The helpers do the conversion in both directions and work against either registry dialect:

import { getReputation, getRecentReviews } from './src/erc8004/reputation.js';

const { count, average, rawAverage, reviewers, dialect } = await getReputation({
  agentId: 1,
  chainId: 8453,
  runner: provider,  // ethers Provider or Signer
});
// average: 4.1 (stars, 0 when count is 0)   rawAverage: 82 (the registry's own unit)
// count: 41 feedback entries from 22 reviewers   dialect: 'reference'

Server code that needs the raw figure (a reputation gate, a trust score) reads it with readAgentReputation({ address, runner, agentId, reviewers?, tag1?, tag2? }) from src/erc8004/reputation-read.js. Pass reviewers to count only feedback from addresses you trust.

To paginate through individual reviews:

const reviews = await getRecentReviews({
  agentId: 42,
  chainId: 8453,
  runner: provider,
  fromBlock: 0,
});
// [{ agentId, from, score, comment, blockNumber, txHash }, ...]

Submitting feedback

import { submitReputation } from './src/erc8004/reputation.js';

const txHash = await submitReputation({
  agentId: 42,
  score: 90,          // -100 to +100
  comment: 'Extremely helpful coach, great form feedback.',
  signer,             // ethers Signer from connected wallet
  chainId: 8453,
});

Two constraints are enforced: one review per wallet address per agent, and agents cannot review themselves. Both are checked at the contract level — there's no way to bypass them from the client side.

Displaying reputation

The ERC-8004 Passport widget type in Widget Studio (three.ws/studio, implemented in src/widgets/passport.js) renders the reputation score as part of the agent's on-chain identity card, embeddable via /w/{widget-id}. Agent profile pages mount the ReputationPanel component from src/erc8004/reputation-panel.js automatically, and the standalone Reputation Explorer works for any (chainId, agentId) pair.


Validation attestations

When a GLB model is run through the glTF validator, the result can be permanently attested on-chain. This creates a verifiable audit trail: anyone can re-run the validator, hash the output, and compare it to the on-chain proof hash to confirm the attestation is authentic.

How it works

  1. The validator runs the GLB and produces a JSON report
  2. hashReport(report) computes keccak256 of the canonicalized report JSON
  3. The report is optionally pinned to IPFS (responseURI)
  4. The agent's owner opens the request: validationRequest(validator, agentId, requestURI, requestHash)
  5. The named validator answers it: validationResponse(requestHash, 100, responseURI, responseHash, 'glb-schema')
  6. The ValidationResponse event is emitted with the score, hash and report URI

The registry has no allowlist, so the meaningful question is who answered. Only the validator named in the owner's request can respond, and three.ws presents a verdict as "Validated" only when the responder is in its recognized set (public/.well-known/validators.json, policy in specs/VALIDATORS.md). A random wallet cannot claim your model passed validation: it can only answer a request you addressed to it.

Reading the latest validation

import { getLatestValidation } from './src/erc8004/validation-recorder.js';

const result = await getLatestValidation({
  agentId: 42,
  chainId: 84532,   // testnet — ValidationRegistry not yet on mainnet
  runner: provider,
  kind: 'glb-schema',
});
// { requestHash, validator, passed, response, responseHash, tag, lastUpdate }  (null when there is no verdict yet)

Verifying independently

import { hashReport, reportPassed } from './src/erc8004/validation-recorder.js';

// Re-run the validator and hash the new report
const freshReport = await runGltfValidator(glbBytes);
const freshHash = hashReport(freshReport);

// Compare against the on-chain hash
console.log(freshHash === onchainResult.responseHash);  // true = authentic

Programmatic registration

To integrate ERC-8004 registration into your own application, you can call the contract functions directly using the ethers v6 API. The helpers below live in the open-source three.ws codebase under src/erc8004/ (import in-repo or vendor them); the @three-ws/sdk npm package ships a leaner variant (connectWallet, registerAgent, getIdentityRegistry, buildRegistrationJSON, REGISTRY_DEPLOYMENTS, agentRegistryId) with a simplified registerAgent({ name, description, endpoint, imageFile, services, apiToken, onStatus }) signature.

Full registration flow

import {
  connectWallet,
  registerAgent,
  getIdentityRegistry,
} from './src/erc8004/agent-registry.js';

// Connect the user's wallet
const { signer, chainId, address } = await connectWallet();

// Full registration (pins files + mints + updates URI)
const { agentId, registrationUrl, txHash } = await registerAgent({
  name: 'My Agent',
  description: 'An AI assistant with a 3D avatar.',
  glbFile: myGlbFile,            // File object — auto-pinned to IPFS
  autoThumbnail: true,           // Render a 2D PNG thumbnail from the GLB
  services: [],                  // Additional service endpoints
  x402Support: false,
  onStatus: (msg) => console.log(msg),
});

console.log(`Agent ${agentId} registered at ${registrationUrl}`);
console.log(`Transaction: ${txHash}`);

The onStatus callback fires at each step so you can show progress in your UI. The flow is: pin GLB → render thumbnail → pin thumbnail → connect wallet → register(seedURI) → build agent card JSON → pin JSON → setAgentURI(agentId, jsonURL).

Reading agents

import { getIdentityRegistry } from './src/erc8004/agent-registry.js';
import { BrowserProvider } from 'ethers';

const provider = new BrowserProvider(window.ethereum);
const registry = getIdentityRegistry(8453, provider);

// Token URI (points to IPFS agent card JSON)
const uri = await registry.tokenURI(agentId);

// Owner
const owner = await registry.ownerOf(agentId);

// All agents owned by an address (ERC-721Enumerable)
const balance = await registry.balanceOf(owner);
const agentIds = [];
for (let i = 0; i < balance; i++) {
  agentIds.push(await registry.tokenOfOwnerByIndex(owner, i));
}

// Arbitrary metadata
const val = await registry.getMetadata(agentId, 'myKey');

Building the agent card manually

import { buildRegistrationJSON } from './src/erc8004/agent-registry.js';
import { agentRegistryId, REGISTRY_DEPLOYMENTS } from './src/erc8004/abi.js';

const card = buildRegistrationJSON({
  name: 'My Agent',
  description: 'Description here.',
  imageUrl: 'https://three.ws/avatars/thumbs/default.png',   // 2D thumbnail
  glbUrl: 'ipfs://bafy.../body.glb',               // 3D model
  agentId: 42,
  chainId: 8453,
  registryAddr: REGISTRY_DEPLOYMENTS[8453].identityRegistry,
  services: [
    { name: 'chat', endpoint: 'https://api.example.com/chat', version: '1.0' }
  ],
  x402Support: false,
});

// card is plain JSON — pin it to IPFS then call setAgentURI

Transferring an agent

Agent ownership is standard ERC-721 transfer. Use any NFT marketplace or transfer directly:

const registry = getIdentityRegistry(8453, signer);
await registry.transferFrom(currentOwner, newOwner, agentId);
// or: await registry['safeTransferFrom(address,address,uint256)'](from, to, agentId);

Gas estimates

Gas costs vary by chain and network congestion. On Base (chain 8453) as a reference point, expect:

Operation Approximate cost
register(agentURI) ~$0.01–0.05
setAgentURI ~$0.005–0.02
submitFeedback ~$0.005–0.02
validationRequest + validationResponse ~$0.01 to $0.04

Ethereum mainnet (chain 1) typically runs 10–50x more expensive than Base at equivalent network utilization. If cost is a concern, register on Base first. You can register the same agent on multiple chains later — there is no cross-chain coordination requirement.

Testnet gas is free from faucets:


Contract addresses reference

// From src/erc8004/abi.js (the @three-ws/sdk npm package exports the same table)
import { REGISTRY_DEPLOYMENTS } from './src/erc8004/abi.js';

// Example: Base mainnet
REGISTRY_DEPLOYMENTS[8453] === {
  identityRegistry:   '0x8004A169FB4a3325136EB29fA0ceB6D2e539a432',
  reputationRegistry: '0x8004BAa17C55a88189AE136b182e5fdA19dE9b63',
  validationRegistry: '',  // not yet on mainnet
}

// Example: Base Sepolia testnet
REGISTRY_DEPLOYMENTS[84532] === {
  identityRegistry:   '0x8004A818BFB912233c491871b3d84c89A494BD9e',
  reputationRegistry: '0x8004B663056A597Dffe9eCcC1965A193B7388713',
  validationRegistry: '0x8004Cb1BF31DAf7788923b405b754f57acEB4272',
}

The same MAINNET addresses apply to all 15 mainnets. The same TESTNET addresses apply to all 7 testnets. This is possible because the contracts are deployed via CREATE2 with the same salt on each chain.


Related specs and source files

Resource Path
three.ws Card v1 spec /specs/3D_AGENT_CARD.md
ENS/DNS agent claim spec /specs/ENS_AGENT_CLAIM.md
Contract ABIs + addresses /src/erc8004/abi.js
Registration flow /src/erc8004/agent-registry.js
Resolver /src/erc8004/resolver.js
Reputation helpers /src/erc8004/reputation.js
Validation recorder /src/erc8004/validation-recorder.js
Chain metadata /src/erc8004/chain-meta.js
IdentityRegistry contract /contracts/src/IdentityRegistry.sol
ReputationRegistry contract /contracts/src/ReputationRegistry.sol
ValidationRegistry contract /contracts/src/ValidationRegistry.sol