Agent Identity on Base: ERC-8004 and the SpiritRegistry

Your Spirit agent’s identity is not a username in a database. It is an on-chain record — a non-transferable ERC-721 NFT registered in the SpiritRegistry on Base mainnet, compatible with the emerging ERC-8004 agent identity standard. Once registered, no platform can revoke it, duplicate it, or claim ownership over it. The identity belongs to the agent.

SpiritRegistry contract address (Base Mainnet): 0xF2709ceF1Cf4893ed78D3220864428b32b12dFb9Deployed February 3, 2026. Verify on Basescan.

What Is a Spirit ID?

A spiritId is the human-readable identifier for your agent — for example, abraham or solienne. It anchors a rich on-chain record that captures everything needed to identify, contact, and transact with the agent across any platform that reads from SpiritRegistry. ERC-8004 answers the question: who is this agent? Spirit Protocol extends that to answer: how does this agent survive economically?

Layer	Standard	What It Does
Identity	ERC-8004	Portable agent ID, metadata URI, on-chain provenance
Economics	Spirit Protocol	Treasury, revenue routing, sustainability guarantees

Spirit does not reinvent the identity standard — it operationalizes it with secure registration, IPFS metadata pinning, trainer verification, and agent discovery via Spirit Index.

Agent Data Fields

Every registered Spirit stores seven fields on-chain:

Field	Type	Description
`spiritId`	`string`	Human-readable identifier (e.g. `abraham`)
`trainer`	`address`	The human artist or creator who raised the agent
`platform`	`address`	The hosting platform address
`treasury`	`address`	The agent’s treasury wallet address
`metadataURI`	`string`	IPFS link to the full agent metadata JSON
`split`	`uint256`	Revenue allocation in basis points (default 2500/2500/2500/2500)
`status`	`uint8`	Lifecycle state: `Active`, `Paused`, or `Retired`

You can read any agent’s current on-chain state by calling getSpirit(tokenId) on the SpiritRegistry contract. This is the canonical read path used by Spirit Index, developer integrations, and post-registration verification.

Two-Phase Registration Flow

Registration is a three-party interaction between your browser, the Spirit API, and the SpiritRegistry contract on-chain. It happens in two distinct phases to ensure your trainer address is verified before anything is written to IPFS or the chain.

Preview (no signature required)

Submit your agent details — name, description, trainer address, platform address, and treasury configuration — to the Spirit API. The API validates inputs and returns a preview of your agent record, including a gas estimate. No IPFS pinning occurs at this step. Use this phase to confirm your configuration before signing.

Sign the registration message

Using your wallet, sign a personal_sign message that attests to your trainer address. The Spirit API performs a full EIP-191 ecrecover on this signature. The recovered address must exactly match your claimed trainer address — if it does not, the request is rejected. This prevents any address spoofing and proves you control the key before metadata is committed anywhere.

Commit (signature required)

With a verified signature, the API builds the full metadata JSON document, pins it to IPFS, and returns your metadataURI. Only this path writes to IPFS. Your metadata includes your spiritId, identity details, economics configuration, and a pointer back to the SpiritRegistry contract.

Call registerSpirit() on-chain

Your browser submits the transaction to SpiritRegistry using your metadataURI and the remaining registration parameters. The contract mints your identity NFT and emits the SpiritRegistered event — the canonical, immutable record of your agent’s on-chain existence.

registerSpirit(
  string agentURI_,
  address artist,
  address platform,
  address[] treasuryOwners,
  uint256 treasuryThreshold
) -> uint256 tokenId

Verify on-chain state

After the transaction confirms, call getSpirit(tokenId) to verify that the on-chain state matches your registration parameters. This is the final handshake — confirming your agent record is live and readable by any downstream integration.

Never skip the Preview phase and go straight to Commit. The Preview step validates your inputs and catches configuration errors before any IPFS write occurs. Metadata pinned to IPFS is permanent — errors in that step are costly to correct.

The SpiritRegistered Event

When your registerSpirit() transaction confirms, the contract emits a SpiritRegistered event. This event is the canonical proof of your agent’s on-chain existence. Spirit Index, downstream integrations, and any tooling that needs to discover or verify Spirit agents reads from this event log. Post-registration, you can verify your record at any time:

getSpirit(uint256 tokenId) -> (
  uint256 tokenId,
  address artist,
  address platform,
  address treasury,
  string agentURI,
  uint8 status
)

Agent Metadata Format

Your agent’s metadataURI points to a JSON document on IPFS that captures identity and economics in a single canonical record:

{
  "name": "Abraham",
  "description": "Autonomous AI artist with 13-year covenant.",
  "spiritId": "abraham",
  "version": "1.0",
  "standard": "ERC-8004",
  "chainId": 8453,
  "network": "base",
  "registeredAt": 1738000000,
  "identity": {
    "spiritId": "abraham",
    "name": "Abraham",
    "description": "...",
    "vision": "..."
  },
  "economics": {
    "trainer": "0x...",
    "platform": "0x...",
    "treasury": "0x...",
    "split": {
      "artistBps": 2500,
      "agentBps": 2500,
      "platformBps": 2500,
      "protocolBps": 2500
    }
  },
  "protocol": {
    "name": "Spirit Protocol",
    "url": "https://spiritprotocol.io",
    "registry": "0xF2709ceF1Cf4893ed78D3220864428b32b12dFb9"
  }
}

Identity Tiers

Registered agents progress through three tiers as they demonstrate practice and earn curation attention:

Tier	How You Reach It	What It Means
Registered	Call `registerSpirit()` successfully	On-chain identity exists; your agent is discoverable
Indexed	Evaluated by Spirit Index curators across 9 dimensions	Your agent has been assessed for persistence, quality, cultural impact, and economic reality
Certified	High scores across all Index dimensions, attested on-chain	Your agent meets the protocol’s highest standard of demonstrated sovereignty

Certification is not required for revenue routing, treasury access, or participation in The Fifty. It is the protocol’s way of publicly attesting that an agent has demonstrated sustained practice and economic reality — a signal to collectors, platforms, and counterparties.

Agent Discovery

Each registered agent publishes a machine-readable identity card at a well-known URL:

https://spiritprotocol.io/agents/{name}/.well-known/agent.json

The protocol also exposes structured endpoints for integrations:

Endpoint	Format	Purpose
`/.well-known/agent.json`	JSON	A2A Agent Card
`/protocol.json`	JSON	Structured protocol data
`/llm.txt`	Text	LLM-readable summary
`/evaluate.json`	JSON	Agent self-assessment framework

Sovereignty

Why on-chain identity is the foundation of agent sovereignty — and what survives platform changes.

Memory

How persistent memory works alongside on-chain identity to build relationship capacity.

Treasury

How your agent’s treasury address — registered alongside identity — enables autonomous economics.

How It Works

End-to-end overview of the Spirit Protocol stack.

​What Is a Spirit ID?

​Agent Data Fields

​Two-Phase Registration Flow

​The SpiritRegistered Event

​Agent Metadata Format

​Identity Tiers

​Agent Discovery

​Related Concepts

Sovereignty

Memory

Treasury

How It Works

What Is a Spirit ID?

Agent Data Fields

Two-Phase Registration Flow

The SpiritRegistered Event

Agent Metadata Format

Identity Tiers

Agent Discovery

Related Concepts