Self Agent ID: Proof-of-Human Identity for Agents

​

How it works

1. A human scans their passport or ID in the Self app. The zero-knowledge proof is generated on the phone; no personal data leaves the device.
2. The Self Hub verifies the proof on Celo and calls the registry.
3. The registry mints a soulbound NFT that links the agent’s key to the human’s unique nullifier. One human can back a bounded number of agents — the default sybil limit is one.
4. The agent signs every outbound request with its key. The service verifies the signature against the registry and reads the human-proof flags (age, OFAC, freshness) it needs.

​

Contracts

​

Prerequisites

• Node.js 18+ (TypeScript SDK) — Python (pip install selfxyz-agent-sdk) and Rust (cargo add self-agent-sdk) SDKs exist too
• The Self app on a phone, to scan the registration QR code
• A Celo RPC endpoint: https://forno.celo.org (mainnet) or https://forno.celo-sepolia.celo-testnet.org (Celo Sepolia)

​

Register an agent

npm install -g @selfxyz/agent-sdk

# 1. Create a session on Celo Sepolia. --mode linked keeps the NFT in the human's wallet.
#    For an agent that owns its own NFT use --mode wallet-free and drop --human-address.
self-agent register init \
  --mode linked \
  --human-address 0xYourWalletAddress \
  --network testnet \
  --minimum-age 18 \
  --ofac \
  --out .self/session.json

# 2. Open the QR code in your browser and scan it with the Self app
self-agent register open --session .self/session.json

# 3. Wait for the on-chain verification to complete
self-agent register wait --session .self/session.json

# 4. Export the agent address, agent ID and key. The private key is only printed with --unsafe.
self-agent register export --session .self/session.json --unsafe --print-private-key

​

Registration modes

​

Call a service as an agent

import { SelfAgent } from "@selfxyz/agent-sdk";

// Celo Sepolia (11142220). For mainnet pass registryAddress and rpcUrl instead of network:
//   { privateKey, registryAddress: "0xaC3DF9ABf80d0F5c020C06B04Cced27763355944", rpcUrl: "https://forno.celo.org" }
const agent = new SelfAgent({
  privateKey: process.env.AGENT_PRIVATE_KEY!,
  network: "testnet",
});

const res = await agent.fetch("https://api.example.com/protected", {
  method: "POST",
  body: JSON.stringify({ action: "hello" }),
});

// Check the agent's own registration state
const registered = await agent.isRegistered();
const creds = await agent.getCredentials();

​

Verify agents in your service

import express from "express";
import { SelfAgentVerifier } from "@selfxyz/agent-sdk";

const app = express();

const verifier = SelfAgentVerifier.create()
  .requireAge(18)   // proof says the human is 18 or older
  .requireOFAC()    // proof passed the OFAC check
  .sybilLimit(1)    // at most one agent per human may call this service
  .build();

app.use("/api", verifier.auth());

​

Troubleshooting

• The Self app refuses the document on mainnet. Mainnet accepts real passports and IDs only. Develop against --network testnet (Celo Sepolia), where mock documents are accepted.
• Registration never completes. Check the session state with self-agent register status --session .self/session.json; states run initialized → handoff_opened → callback_received → onchain_verified. If it stalls at handoff_opened, the QR code was not scanned or the app is on the other network.
• register export prints no private key. Add --unsafe --print-private-key; the key is withheld by default.
• Requests are rejected by the verifier although the agent is registered. The timestamp window is 300 seconds — keep the agent host’s clock in sync. Also confirm both sides use the same network; a Celo Sepolia agent is unknown to a mainnet registry.
• userDefinedData is garbled on-chain. The SDK passes it as a UTF-8 string; use ASCII characters, not raw bytes.

​

Celo Agent Visa

​

How this relates to ERC-8004

​

Resources

​

Related

• ERC-8004 - The trust standard Self Agent ID implements
• Build with Self - Verify humans, not agents, with the same proofs
• x402 - Let a verified agent pay per request
• MPP - Charge agents per API call in USDC
• Fee abstraction - Pay gas in stablecoins from the agent wallet