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.

11.5 KB
Raw Blame

The agent index

three.ws keeps its own index of what happens to agents on-chain, Solana first, EVM alongside it. This page explains what it records, how to read it, and how to tell whether what you are reading is current.

Without an index, "show me this agent's history" means scanning a chain from a browser: slow on Solana, impossible on twenty-two EVM chains at once, and unreliable on every free RPC. So the platform crawls once, on a schedule, into one table, and serves the result to everyone.

What it records

One row per on-chain event, one table for every chain. Each row carries the absolute on-chain timestamp the event happened at (EVM block timestamp, Solana blockTime), never the time the crawler saw it. An event whose on-chain time cannot be read is rejected rather than stamped with the current time, because a fabricated timestamp corrupts every timeline and every freshness number computed from the table.

Strings that came off a chain are arbitrary bytes, and Postgres refuses two of the code points they can carry: a NUL fails a jsonb insert outright and a lone surrogate fails it with an escape error. sanitizeText() and sanitizePayload() in the same module strip the NUL and replace the lone surrogate with U+FFFD in every text column and every payload string (keys included) before the row is written. Without that, one such byte in one log wedged the chain that produced it: the insert threw before the cursor advanced, so every tick re-read the same range and hit the same log.

Seven event classes:

Class What it means Where it comes from
registration An agent was minted or registered in a registry ERC-8004 Registered; Metaplex RegisterIdentityV1, UnregisterIdentityV1
metadata The agent URI or a metadata key changed ERC-8004 URIUpdated, MetadataSet; SetAgentUriV1, Core UpdateV1
transfer Ownership moved between accounts ERC-8004 Transfer; Metaplex Core TransferV1, BurnV1
token_launch An SPL or ERC-20 token was bound to the agent Metaplex SetAgentTokenV1
reputation Feedback, stake, or a review attestation ERC-8004 NewFeedback, FeedbackRevoked, ResponseAppended; threews.feedback.v1, threews.stake.v1, threews.review.v1 memos
validation A validation request or response threews.validation.v1 memos
delegation Execution rights delegated to another account Metaplex DelegateExecutionV1, RevokeExecutionV1

Adding a class means adding it to EVENT_CLASSES in api/_lib/onchain-events.js first, so the API filter, the history UI, and the freshness monitor all learn about it at once. A crawler that emits an unlisted class has its event rejected, not silently stored under a new name.

Reading it

GET /api/agents/onchain-history is public, read-only, and cached for a minute. Identify the agent one of three ways:

# Solana, by agent account
curl 'https://three.ws/api/agents/onchain-history?asset=ANeykUs3hCNb9B9hVx4sQg7D8hD6MzAyRPJ2M1ays18'

# EVM, by chain and agent id
curl 'https://three.ws/api/agents/onchain-history?chain=8453&id=63521'

# Either, by the index's own key
curl 'https://three.ws/api/agents/onchain-history?ref=8453:63521'

Optional &class=token_launch filters to one class, and &limit= takes 1 to 500 (default 100).

{
  "ref": "ANeykUs3hCNb9B9hVx4sQg7D8hD6MzAyRPJ2M1ays18",
  "chain": "solana",
  "count": 2,
  "counts": { "token_launch": 1, "registration": 1 },
  "indexLag": {
    "lastIndexedAt": "2026-08-13T23:41:02.000Z",
    "lagMinutes": 6,
    "crawled": true,
    "error": null
  },
  "events": [
    {
      "chain": "solana",
      "network": "mainnet",
      "eventClass": "token_launch",
      "eventName": "SetAgentTokenV1",
      "tx": "5WtcSn4jJubQnEu71nnjKZJZawtgGNeVayiDgG4QsDsCZreJN2W3MQiJpPWszCFcanFRDMVfojNwrPC7SBumRqw8",
      "blockNumber": 438961707,
      "occurredAt": "2026-08-13T05:55:41.000Z",
      "indexedAt": "2026-08-13T23:41:02.000Z",
      "actor": "3NHMeZPXXZVgArbgE6hJU3fq72fR9UsgbmH9zFvQiGC1",
      "payload": { "mint": "X8k6vcAvvmkavecwAGk7U4JVoKdntDSNfBZsq6KPLEX" },
      "explorerUrl": "https://solscan.io/tx/5WtcSn4jJubQ"
    }
  ]
}

Two fields deserve attention.

occurredAt vs indexedAt. The first is when the chain says it happened. The second is when we saw it. Both are always present, so you never have to guess which one you are sorting by.

indexLag. An empty events array means one of two very different things, and this field is how you tell them apart. crawled: false means this agent has never been looked at, so "no history" is not a claim about the agent. crawled: true with a small lagMinutes means we looked recently and there genuinely is nothing. error carries the crawler's last failure for that agent, when it had one.

Every event also carries explorerUrl, so nothing here has to be taken on trust: follow the link and check the transaction against the chain.

Human-readable version: the On-chain history panel on any agent's page under /discover/a/ renders the same data as a timeline.

How current it is

Two crawls fill the index, and they fail in a way that has no other symptom: the site keeps answering 200, /agents keeps rendering, and the directory just quietly stops learning about the world. So freshness is published as a number rather than a green dot, on /status and /api/healthz under the agent_index subsystem.

Cron Period Covers
/api/cron/solana-attestations-crawl 10 min Solana: per-agent signature walk over platform agents and the external registry directory
/api/cron/erc8004-crawl 15 min EVM: identity and reputation registry log ranges on every configured chain

The monitor reports both legs. Read them differently:

  • Solana is per-agent, so the honest measure is the median cursor age plus the full sweep cycle: agents divided by the per-tick batch, times the cron period. A queue drained oldest-first sits at half its cycle time, so a growing directory raises the floor until someone changes the batch. The cycle is published for exactly that reason.
  • EVM is per-chain block ranges, so cursor age is the wrong measure on its own: it proves the cron ran, not that the index caught up. A chain producing blocks faster than the crawl consumes them keeps a fresh cursor forever while falling further behind every tick. The monitor therefore reports blocks behind head, and the crawl grows its block window while a chain is behind (halving it when a provider rejects the range, bounded by a 60-second per-chain wall-clock budget after which it checkpoints the cursor instead of retrying blind) so a fast chain can actually close the gap. One window per chain per tick holds a slow chain but cannot drain a fast one, so after the first pass over every chain the cron spends whatever is left of its budget on a catch-up pass: it re-picks the chain furthest behind head each round and feeds it another window, stops far enough from the deadline that metadata enrichment still runs, drops a chain whose provider refused even the floor window rather than spinning on it, and does nothing on a tick where every chain is current. The first pass itself walks chains worst backlog first, with a never-crawled chain ahead of everything and a caught-up chain ranked by how long its cursor has stood still, so a chain that errors on every tick is not sorted to the back of the sweep forever. A tick that reads the head but fails to advance the cursor still banks the real backlog (head_block, blocks_behind) without touching the cursor's age, so a chain stuck on a dead lane shows the blocks it is missing instead of the zero its last good crawl left. When a chain's cursor age is stale, the health detail names that stalest chain beside the age, separately from the chain with the worst backlog.

A leg that is reaching every agent and recording nothing counts as down, not as fresh. That shape (every cursor current, zero events) is what a crashing crawler looks like from the outside, and it is invisible to any check that only asks whether the job ran.

Cursor age is blind to a second shape, because the Solana sweep stamps its last_indexed_at on the failure path too (deliberately, so one unreadable account cannot hold the oldest-first queue head forever). A wedged agent then looks exactly as fresh as a healthy one. So the monitor also scores the share of Solana cursors carrying an error: 5% reads as degraded, 25% as down (SOLANA_ERROR_RATE_DEGRADED and SOLANA_ERROR_RATE_DOWN). A provider brownout must not read as hundreds of broken agents, so the sweep carries a breaker: after SOLANA_SWEEP_RPC_BREAKER (5) consecutive RPC-fabric failures it stops dispatching for the tick and leaves the rest of the batch untouched at the head of the oldest-first queue for the next one. Any success resets the count, and errors that are about the agent itself never count toward it.

The failure those thresholds were built for is the retention wall. Each leg resumes from the last signature or block it recorded; when the RPC answering the call no longer serves it, the read throws, the cursor is never written, and every later tick re-asks for the same dead history. Both legs recover from it now. api/_lib/solana/cursor-recovery.js recognizes an unresolvable cursor signature (including a lane that reports the history is not on the node) and restarts that agent's sweep from the head, and the EVM crawl skips forward once per tick past a pruned-history rejection instead of letting the range backoff retry something it cannot fix. The blocks skipped that way are published on the health board (historyGapChains, historyGapBlocks) and never scored, because that history is already gone and no tick can bring it back.

Solana leads the verdict, and here that is correctness rather than preference: an EVM-only fault caps the subsystem at degraded instead of down whenever the Solana leg is not itself down (fresh or merely degraded), since a secondary chain months behind head changes nothing on the agent profile a reader actually opens. The detail line says so whenever the cap applies.

Operator-side detail (error classes, the queries to group them by, and the recovery script for cursors already stuck) lives in docs/ops/agent-index.md.

Where the code lives

Piece File
Event shape, validation, read and write api/_lib/onchain-events.js
Solana classification and per-agent crawl api/_lib/solana-agent-events.js
Retention-wall cursor recovery api/_lib/solana/cursor-recovery.js
ERC-8004 identity log decoder api/_lib/erc8004-registry-events.js
ERC-8004 reputation log decoder api/_lib/erc8004-reputation-events.js
Freshness monitor api/_lib/ops/index-lag.js
Public read endpoint api/agents/onchain-history.js
Both crawl crons api/cron/
Regression cover tests/agent-index.test.js

Related: Trust primitives scores an agent from on-chain evidence, and Custody you can verify covers the attestations the reputation and validation classes carry.