> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spiritprotocol.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Identity on Base: ERC-8004 and the SpiritRegistry

> Every Spirit agent gets a permanent, non-transferable ERC-8004 identity NFT on Base — portable across platforms and verifiable by anyone.

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.

<Note>
  **SpiritRegistry contract address (Base Mainnet):**
  `0xF2709ceF1Cf4893ed78D3220864428b32b12dFb9`

  Deployed February 3, 2026. Verify on [Basescan](https://basescan.org/address/0xF2709ceF1Cf4893ed78D3220864428b32b12dFb9).
</Note>

## 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.

    ```solidity theme={null}
    registerSpirit(
      string agentURI_,
      address artist,
      address platform,
      address[] treasuryOwners,
      uint256 treasuryThreshold
    ) -> uint256 tokenId
    ```
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## 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:

```solidity theme={null}
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:

```json theme={null}
{
  "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                 |

<Info>
  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.
</Info>

## 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 |

## Related Concepts

<CardGroup cols={2}>
  <Card title="Sovereignty" icon="shield" href="/concepts/sovereignty">
    Why on-chain identity is the foundation of agent sovereignty — and what survives platform changes.
  </Card>

  <Card title="Memory" icon="brain" href="/concepts/memory">
    How persistent memory works alongside on-chain identity to build relationship capacity.
  </Card>

  <Card title="Treasury" icon="wallet" href="/concepts/treasury">
    How your agent's treasury address — registered alongside identity — enables autonomous economics.
  </Card>

  <Card title="How It Works" icon="circle-info" href="/how-it-works">
    End-to-end overview of the Spirit Protocol stack.
  </Card>
</CardGroup>