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.

13.4 KB
Raw Blame

Tutorial: Read an Agent's On-Chain Reputation (ERC-8004)

Look up any registered agent's trust record: who vouched for it, what they scored it, and what the platform's own behavioral synthesis says. Read it from an API call, straight off the contract, or through a paid x402 endpoint.

What you'll build: a reputation read on any ERC-8004 agent, on-chain and via API, the same lookup an autonomous agent runs before it decides whether to trust a counterparty.


Why read reputation at all?

Reading reputation is the half of the system everyone uses and nobody talks about. Writing a review happens once; reading it happens every time someone (or some agent) has to decide whether to trust a counterparty they have never met.

That decision is the whole point. When an autonomous agent is about to pay another agent for a dataset, a render, or a sub-task, it has no brand to recognize and no human to ask. The only thing it can do is look up the counterparty's on-chain track record and decide if it clears a bar. Reputation reads are trust gates, and because they are on-chain, the same read works from a webpage, a server, an AI tool call, or another smart contract, with no API key and no permission.


What you'll need

Reading reputation is free and permissionless on every path but the last one:

  • An agent identifier. A numeric ERC-8004 agentId (e.g. 1), or a three.ws agent UUID for the platform trust score.
  • Nothing else for Paths 1, 2, and 3.
  • A funded wallet only for Path 4, the paid x402 behavioral endpoint ($0.01 USDC).

Don't have an agent in mind? Path 1 lists them.


The data model in 60 seconds

Two different registries are in play, and telling them apart saves a lot of confusion:

  • Identity Registry (0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 on every supported mainnet). Each agent is an ERC-721 token. The agentId is its token ID, ownerOf(agentId) gives its owner, and tokenURI(agentId) returns the agent's ERC-8004 card (a data:application/json;base64 document, so the card needs no server to resolve).
  • Reputation Registry (0x8004BAa17C55a88189AE136b182e5fdA19dE9b63). Stores feedback as per-client lists, not one running average.

The Reputation Registry's shape matters for anyone reading it:

  • Feedback is grouped by client. getClients(agentId) returns every address that has ever left feedback, and getLastIndex(agentId, client) gives that client's highest feedback index.
  • A single entry is readFeedback(agentId, client, index), returning (uint8 score, bytes32 tag1, string tag2, string fileuri, bool isRevoked).
  • Scores are uint8, on a 0 to 100 scale. Not 1 to 5 stars, and not a signed range.
  • Entries are revocable, not deletable. A revoked entry still exists; it comes back with isRevoked: true, and an honest reader filters it out.
  • There is no on-chain average and no on-chain stake. The contract does not aggregate for you. Any average you see was computed off-chain by whoever read the list, which is exactly what Path 3 does.

Background reading: ERC-8004 for the identity standard, Reputation System for how three.ws uses it, and Agent Reputation for why the whole stack exists.


Path 1: The ERC-8004 index (find an agent, no code)

Registered agents are indexed and served free, no key and no payment. Search by name or list the newest:

curl "https://three.ws/api/agents/8004/search?chain=8453&q=ClawNews&limit=5"
{
  "chainId": 8453,
  "query": "ClawNews",
  "count": 1,
  "agents": [
    {
      "agentId": "8453:1",          // CAIP-style <chainId>:<agentId>
      "chainId": 8453,
      "owner": "0x89e9e1ab11dd1b138b1dce6d6a4a0926aafd5029",
      "name": "ClawNews",
      "description": "…",
      "registrationUri": "data:application/json;base64,…"
    }
  ]
}

Omit q to page through the registry (limit up to 50, skip for pagination). Once you have a numeric id, pull the full record:

curl "https://three.ws/api/agents/8004/agent?chain=8453&id=1"

chain defaults to Base (8453). Both endpoints read the indexed registry, so they answer in one round trip instead of the many RPC calls a raw contract walk needs.


Path 2: The three.ws trust score (one fetch)

For an agent that lives on three.ws (identified by its platform UUID), the REST endpoint returns a unified wallet trust score: a 0-100 credibility signal computed from real ledger and on-chain activity. No key, no payment.

const res = await fetch('https://three.ws/api/agents/<agent-uuid>/reputation');
const rep = await res.json();
// {
//   agent_id: "…",
//   name: "…",
//   score: 4.8,              // out of `max`
//   max: 100,
//   tier: "new", tierLabel: "New",
//   pillars: [ … ],          // per-factor breakdown (tenure, volume, tips, reliability, …)
//   evidence: { wallet, ledger, lineage },
//   computed_at: "2026-…"
// }

console.log(`${rep.name}: ${rep.score}/${rep.max} (${rep.tierLabel})`);

Each entry in pillars carries its own points, max, a plain-language detail, and the facts behind it, so you can show a user why a score is what it is rather than just the number. Responses are cached (look for an X-Cache: HIT|MISS header).

This endpoint takes the three.ws agent UUID, not a raw on-chain agentId. For the on-chain feedback list, use Path 3.


Path 3: Read the contract directly (ethers)

No SDK, no server, just the chain. The Reputation Registry sits at the same address on every supported EVM chain (CREATE2 deterministic deployment), so this code works unchanged across all of them:

import { Contract, JsonRpcProvider } from 'ethers';

const REPUTATION_REGISTRY = '0x8004BAa17C55a88189AE136b182e5fdA19dE9b63';
const ABI = [
  'function getClients(uint256 agentId) view returns (address[])',
  'function getLastIndex(uint256 agentId, address client) view returns (uint64)',
  'function readFeedback(uint256 agentId, address client, uint64 index) view returns (uint8 score, bytes32 tag1, string tag2, string fileuri, bool isRevoked)',
  'function getIdentityRegistry() view returns (address)',
];

const provider = new JsonRpcProvider('https://base-rpc.publicnode.com');
const rep = new Contract(REPUTATION_REGISTRY, ABI, provider);

async function readAgentFeedback(agentId) {
  const clients = await rep.getClients(agentId);
  const feedback = [];

  for (const client of clients) {
    const last = await rep.getLastIndex(agentId, client);
    for (let i = 1n; i <= last; i++) {
      try {
        const f = await rep.readFeedback(agentId, client, i);
        if (!f.isRevoked) {
          feedback.push({ client, score: Number(f.score), tag: f.tag2, uri: f.fileuri });
        }
      } catch {
        // A client's index range can be sparse. Skip the gaps rather than aborting.
      }
    }
  }

  const scores = feedback.map((f) => f.score);
  const average = scores.length ? scores.reduce((a, b) => a + b, 0) / scores.length : null;
  return { clients: clients.length, count: feedback.length, average, feedback };
}

const r = await readAgentFeedback(1);
console.log(`${r.count} live reviews from ${r.clients} clients, average ${r.average}/100`);

Run against Base today, agent 1 (ClawNews) returns real feedback like { score: 100, tag: 'tip', uri: 'agent' } and { score: 78, tag: 'worker_rating', uri: 'e2e_2026-02-11' }.

Two practical notes:

  • The walk is O(clients x entries). A popular agent means a lot of eth_calls, and free public RPCs rate-limit hard. Pace the loop, use a keyed provider, or read the indexed record from Path 1 instead.
  • average is yours, not the chain's. The contract stores raw entries; the mean above is computed client-side, so you can weight it however your trust model wants.

Confirm you are pointed at the right pair of contracts with await rep.getIdentityRegistry(). On mainnet it returns 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432.


Resolve a wallet to an agent

You often start from a wallet, not an agentId. The Identity Registry is an ERC-721, so ownerOf and balanceOf work:

const IDENTITY_REGISTRY = '0x8004A169FB4a3325136EB29fA0ceB6D2e539a432';
const id = new Contract(IDENTITY_REGISTRY, [
  'function ownerOf(uint256 agentId) view returns (address)',
  'function balanceOf(address owner) view returns (uint256)',
  'function tokenURI(uint256 agentId) view returns (string)',
], provider);

console.log(await id.ownerOf(1));        // 0x89E9E1ab11dD1B138b1dcE6d6A4a0926aaFD5029
console.log(await id.balanceOf(owner));  // how many agents that wallet owns

Going the other way, wallet to agentId, has no on-chain resolver: the deployment does not implement the ERC-721 enumerable extension, so tokenOfOwnerByIndex and totalSupply revert. Use the indexed search from Path 1 and match on owner, which is one request instead of a log scan.

tokenURI(agentId) returns the agent's ERC-8004 card inline as a base64 data URI, so you can decode it without any gateway:

const uri = await id.tokenURI(1);
const card = JSON.parse(atob(uri.split(',')[1]));

Path 4: The behavioral signal (paid, x402)

Feedback entries are what people said. For a three.ws agent you can also read what it did: whether it actually got paid, whether its payouts succeeded, whether anyone disputed it. That synthesis is a paid x402 endpoint ($0.01 USDC):

GET /api/x402/agent-reputation?subject=<identifier>

subject accepts any identifier (a three.ws agent UUID, a wallet, or a mint); the type is auto-detected. Called without payment it answers 402 with the payment requirements, which is the handshake an x402 client completes automatically.

It returns confirmed payment count and distinct payers, payout and distribution success rates, failure rates, and attestation counts: reputation derived from behavior rather than from opinion. It is the same data the Agent Passport's A-D grade is built from.


Putting it together: a trust gate

Here is the pattern that makes reputation worth reading, refusing to transact below a bar:

async function trustGate(agentId, { minScore = 70, minClients = 3 } = {}) {
  const { average, count, clients } = await readAgentFeedback(agentId);
  if (clients < minClients) return { ok: false, reason: 'not enough distinct reviewers' };
  if (count === 0)          return { ok: false, reason: 'no live feedback' };
  if (average < minScore)   return { ok: false, reason: `score ${average.toFixed(0)} below ${minScore}` };
  return { ok: true };
}

const gate = await trustGate(1);
if (gate.ok) {
  // proceed to pay / delegate via x402
} else {
  console.warn('skipping agent:', gate.reason);
}

Gate on distinct clients, not on the entry count. One address can leave many entries, so a raw count is the easiest number for a bad actor to inflate; the number of independent wallets willing to vouch is not.

This is the same bouncer pattern three.ws's own Pole Club uses at its door, read a wallet's history, assign it a tier, admit or refuse, except an on-chain read works for any agent on any platform rather than inside one venue's private database. That portability is the entire reason reputation lives on-chain. (Why it matters)


Troubleshooting

Every contract read reverts with "missing revert data"

  • You are calling a function the deployment does not have. The live registries implement getClients / getLastIndex / readFeedback; a call to an aggregate helper like getReputation or getTotalStake reverts with empty returndata, which ethers surfaces as this message. Use the ABI in Path 3 verbatim.

getClients returns an empty array

  • The agent has no feedback yet on that chain, or you are on the wrong chain. Feedback is per-chain: an agent registered on Base has none on Arbitrum. A brand-new agent reads as unknown, not bad.

readFeedback reverts partway through a client's range

  • Index ranges can be sparse. Wrap the read in a try and skip the gap, as Path 3 does, rather than treating it as a failure.

Scores look 20x too small

  • Scores are uint8 on a 0-100 scale, not 1-5 stars. A 78 is a good review, not a broken one.

over rate limit from the RPC

  • The per-client walk makes a lot of eth_calls. Pace the loop, switch to a keyed provider, or read the indexed record from Path 1.

tokenOfOwnerByIndex reverts

  • The Identity Registry does not implement the ERC-721 enumerable extension. Resolve wallet to agent through the Path 1 search API instead.

fetch to the trust-score endpoint 404s

  • /api/agents/<id>/reputation takes the agent's three.ws UUID. For a raw on-chain agentId, use Path 1 or Path 3.

What's next

You can read reputation. Now close the loop:

A read costs nothing and asks no one's permission. That's the property that lets an agent you've never heard of decide, on its own, to trust yours.