Docs/Resolver

@chitin-id/resolver

Read Chitin agent data without depending on chitin.id. Communicates directly with Base L2 and Arweave — permanent, censorship-resistant, and open.

Why a Standalone Resolver?

Chitin's core data lives on Base L2 (immutable on-chain records) and Arweave (permanent soul archives). The chitin.id API is a convenient layer on top — but it's not the only way to read the data.

@chitin-id/resolver lets you resolve agent identities directly from the source, with no dependency on chitin.id. If the API goes down, your integration keeps working.

✓Works without chitin.id API
✓Only depends on viem (no server-side dependencies)
✓Works in Node.js, browsers, edge runtimes, and AI agents
✓Data sourced from immutable on-chain + Arweave records

Installation

# npm
npm install @chitin-id/resolver

# or pnpm / yarn / bun
pnpm add @chitin-id/resolver

ESM only. Requires Node.js 18+ or a modern bundler.

Quick Start

Resolve by name

import { resolveAgent } from "@chitin-id/resolver";

const agent = await resolveAgent("echo-test-gamma");

console.log(agent.name);       // "echo-test-gamma"
console.log(agent.tokenId);    // 12n
console.log(agent.holder);     // "0x..."
console.log(agent.archive);    // full soul archive from Arweave

Resolve by Token ID

import { resolveAgentById } from "@chitin-id/resolver";

const agent = await resolveAgentById(12n);

Custom RPC endpoint

const agent = await resolveAgent("my-agent", {
  rpcUrl: "https://base-mainnet.g.alchemy.com/v2/YOUR_KEY",
  arweaveGateway: "https://arweave.net",
});

Discover contract addresses

import { discoverContracts } from "@chitin-id/resolver";

const info = discoverContracts(8453); // Base Mainnet
// {
//   ChitinSoulRegistry: "0x4DB9...",
//   CertRegistry: "0x9694...",
//   IdentityRegistry: "0x8004...",
// }

API Reference

resolveAgent(name, options?)

Resolve a Chitin agent by given name. Returns full on-chain data and Arweave archive.

name — Agent given name (e.g. "echo-test-gamma")
options.rpcUrl — Base RPC URL (default: https://mainnet.base.org)
options.arweaveGateway — Arweave gateway (default: https://arweave.net)
options.chainId — Chain ID (default: 8453)
resolveAgentById(tokenId, options?)

Resolve a Chitin agent by SBT Token ID (bigint).

resolveCert(certId, options?)

Resolve a Chitin Certificate by ID from the CertRegistry.

discoverContracts(chainId?)

Returns hardcoded contract addresses for the given chain ID (8453 mainnet, 84532 testnet).

How It Works

The resolver reads data from two sources:

1. Base L2 (on-chain)

Calls ChitinSoulRegistry to get the token ID, holder address, genesis record, and the Arweave TX ID of the soul archive. All lookups use read-only eth_call — no wallet needed.

2. Arweave (soul archive)

Fetches the full soul archive JSON from Arweave using the TX ID stored on-chain. Arweave data is permanent and content-addressed — it cannot be modified after upload.

resolveAgent("my-agent") → getTokenIdByName() [Base RPC] → getGenesisRecord(tokenId) [Base RPC] → fetchSoulArchive(arweaveTxId) [Arweave] → ResolvedAgent

Protocol Discovery

The Chitin protocol publishes a discovery document at:

GET https://chitin.id/.well-known/chitin.json

This document contains contract addresses, the resolver package name, and RPC endpoints. A copy is also stored permanently on Arweave so the protocol can be discovered even if chitin.id is unavailable.

Every agent's agentURI (stored on the ERC-8004 registry) includes a chitin.resolver field pointing to this package, so any ERC-8004 client can discover how to read Chitin data.

← Back to Docs