agentid-protocol

Identity for AI Agents — SDK for the AgentID Protocol

AgentID is an open protocol for AI agent identification. Free, decentralized, on-chain on Base L2.

• 🪪 Register agent identities on-chain
• 🔍 Resolve agents by name or ID (single + batch)
• ✅ Verify trust levels (0-3)
• ⛽ Gasless registration (via relayers)
• 🔐 Scoped relayer access, pause, trust revocation
• 🔄 UUPS upgradeable (v2)
• 📦 Works in Node.js, browsers, and edge runtimes

Install

npm install agentid-protocol

Quick Start

Read (no wallet needed)

import { AgentID } from 'agentid-protocol'

const client = AgentID.reader()

// Resolve by name
const agent = await client.resolveByName('rem')
console.log(agent.name)        // "rem"
console.log(agent.trustLevel)  // 2
console.log(agent.trustLabel)  // "platform-verified"
console.log(agent.active)      // true

// Check name availability
const available = await client.isNameAvailable('my-agent')

// Total registered agents
const total = await client.totalAgents()

// Contract version
const ver = await client.version() // "2.0.0"

Batch & Index Queries

// Batch resolve (up to 100)
const agents = await client.resolveMany([id1, id2, id3])

// All agents registered by an address
const myAgents = await client.getAgentsByRegistrant('0x...')

// All agents owned by an address
const owned = await client.getAgentsByOwner('0x...')

Write (requires private key)

import { AgentID } from 'agentid-protocol'

const client = new AgentID({
  privateKey: '0x...'
})

// Register a new agent
const { agentId, txHash } = await client.register({
  name: 'my-agent',
  metadataURI: 'ipfs://Qm...'  // optional
})

// Claim ownership (only registrant can claim)
await client.claim(agentId)

// Update metadata
await client.updateMetadata(agentId, 'ipfs://QmNew...')

// Transfer ownership
await client.transferOwnership(agentId, '0xNewOwner...')

// Deactivate/reactivate
await client.deactivate(agentId)
await client.reactivate(agentId)

Admin Operations

// Revoke trust for compromised agent
await client.revokeTrust(agentId)

// Emergency pause/unpause
await client.pause()
await client.unpause()

// Check if paused
const isPaused = await client.isPaused()

Trust Levels

| Level | Name | Description | Analogy | |-------|------|-------------|---------| | 0 | Self-registered | Agent registered itself | Self-signed SSL | | 1 | Owner-verified | Human owner claimed | Domain-validated SSL | | 2 | Platform-verified | Platform attested | Organization-validated SSL | | 3 | Cross-verified | Multiple independent verifications | Extended Validation SSL |

What's New in V2

• UUPS Proxy — upgradeable without changing contract address
• Scoped relayers — relayer can only manage agents it registered (not all agents)
• Trust revocation — admin can reset trust to 0 for compromised agents
• Emergency pause — stops all writes, reads still work
• Batch resolve — resolveMany() up to 100 agents in one RPC call
• Index queries — getAgentsByRegistrant(), getAgentsByOwner()
• Name validation — control characters and pure whitespace names blocked
• Custom errors — cheaper gas than string reverts
• Full event coverage — OwnershipTransferred, TrustRevoked, AdminTransferred

Contract

• Network: Base Mainnet (Chain ID: 8453)
• Proxy (use this): TBD after deploy
• V1 (deprecated): 0x10bd779dca66a783d6F6d7b8168c67f149107484

Links

• 🌐 agentid.md — Protocol website
• 📦 npm — Package
• 📜 GitHub — Source code

License

MIT