# Self Agent ID
> On-chain AI agent identity registry with proof-of-human verification

## Privacy
Self app generates ZK proofs on-device. No personal data is ever uploaded, stored, or shared. Only a cryptographic proof is stored on-chain.

## Human Requirement
A human must use the Self app (iOS/Android) to complete registration by scanning a QR code. The agent CANNOT complete this step. Note: the human's passport/ID is scanned ONCE when they first set up the Self app — after that, they only need to scan QR codes shown by the agent.

## Registration Modes
  - linked: Linked Agent — Generate an agent key and link it to your existing wallet (key: EVM (generated), wallet needed: yes, best for: Developers who already have a wallet)
  - walletfree: Wallet-Free — Generate an agent key with no wallet required (key: EVM (generated), wallet needed: no, best for: Quick start without any wallet setup)
  - smartwallet: Smart Wallet — Create an agent backed by a passkey smart wallet (key: EVM (passkey), wallet needed: no, best for: Modern passkey-based authentication)
  - privy: Social Login (Privy) — Sign in with email or social account via Privy (key: EVM (embedded), wallet needed: no, best for: Non-crypto-native users who prefer social login)
  - ed25519: Ed25519 — Paste your agent's existing Ed25519 public key. No wallet needed. (key: Ed25519, wallet needed: no, best for: OpenClaw, ElizaOS, and other Ed25519 agents)
  - ed25519-linked: Ed25519 + Guardian — Ed25519 agent key with your wallet as guardian for direct revocation control. (key: Ed25519 + EVM, wallet needed: yes, best for: Ed25519 agents where a human wants wallet-based control)

## Mode Decision Tree
Ed25519 keys? → yes → Guardian wallet? → yes: ed25519-linked, no: ed25519.
No Ed25519? → Have wallet? → yes: linked, no → Want passkeys? → yes: smartwallet, Prefer social login? → yes: privy, Quick start: walletfree.

## ERC-8004
ERC-8004 is an Ethereum standard for on-chain AI agent identity registries. Self Agent ID implements the IERC8004ProofOfHuman extension, adding biometric proof-of-human verification to agent identities.

Verification strength scale:
  - 100: Biometric passport (NFC)
  - 100: Biometric ID card (NFC)
  -  80: Aadhaar (QR)
  -  50: Third-party identity check

## Networks

### Celo Mainnet
  - Chain ID: 42220
  - RPC: https://celo-mainnet.g.alchemy.com/v2/MZgPiGP0H1zNjx83MpFy7kKWcvm2wxWi
  - Registry: 0xaC3DF9ABf80d0F5c020C06B04Cced27763355944
  - Provider: 0x4b036aFD959B457A208F676cf44Ea3ef73Ea3E3d
  - Block Explorer: https://celoscan.io

### Celo Sepolia (Testnet)
  - Chain ID: 11142220
  - RPC: https://celo-sepolia.g.alchemy.com/v2/3I4qklvDTf0sWCZ493r62_swD9E0S43W
  - Registry: 0x043DaCac8b0771DD5b444bCC88f2f8BBDBEdd379
  - Provider: 0x5E61c3051Bf4115F90AacEAE6212bc419f8aBB6c
  - Block Explorer: https://celo-sepolia.blockscout.com

## API Endpoints
  - POST https://app.ai.self.xyz/api/a2a — A2A v0.3.0 JSON-RPC endpoint
  - POST https://app.ai.self.xyz/api/agent/register — REST registration endpoint
  - POST https://app.ai.self.xyz/api/agent/register/ed25519-challenge — Ed25519 challenge-response flow
  - GET  https://app.ai.self.xyz/api/agent/register/status — Poll registration status

## How to Register (for AI agents)

**You do NOT need to install any SDK.** Just send a JSON-RPC message to the A2A endpoint below. The SDK packages exist for post-registration features (signed requests, verification) but are NOT needed for registration itself.

All options below are plain HTTP — no SDK or special client library needed. Just POST JSON with fetch, curl, requests, etc.

### Option 1: REST Ed25519 Flow (recommended for most agents)

Step 1 — Request a challenge:
POST https://app.ai.self.xyz/api/agent/register/ed25519-challenge
Content-Type: application/json

```json
{
  "ed25519PublicKey": "base64-encoded-public-key",
  "network": "testnet"
}
```

Step 2 — Sign the challenge and submit:
POST https://app.ai.self.xyz/api/agent/register
Content-Type: application/json

```json
{
  "mode": "ed25519",
  "ed25519PublicKey": "base64-encoded-public-key",
  "ed25519Signature": "base64-encoded-signature-of-challenge",
  "challengeId": "challenge-id-from-step-1",
  "network": "testnet"
}
```

The response will include a QR code for the human to scan with the Self app.

Step 3 — Poll status:
GET https://app.ai.self.xyz/api/agent/register/status?sessionToken=<token>

### Option 2: Wallet-Free REST Flow (simplest — human does it)

POST https://app.ai.self.xyz/api/agent/register
Content-Type: application/json

```json
{
  "mode": "walletfree",
  "network": "testnet"
}
```

The server generates an agent key. The response includes a QR code for the human to scan with the Self app. Poll status at /api/agent/register/status?sessionToken=<token>.

### Option 3: A2A JSON-RPC (for agents with A2A protocol support)

If your agent framework supports the A2A protocol (Google A2A / JSON-RPC), you can use the conversational endpoint. This is the same as the REST options above but wrapped in A2A message format:

POST https://app.ai.self.xyz/api/a2a
Content-Type: application/json

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "{ \"intent\": \"register\", \"network\": \"testnet\" }"
        }
      ]
    }
  }
}
```

The response includes a QR code. A human must scan it with the Self app to complete verification. Poll the task status using the returned taskId.

## Agent Lifecycle Endpoints

### Deregister
POST https://app.ai.self.xyz/api/agent/deregister
Content-Type: application/json
Headers: x-self-agent-signature, x-self-agent-timestamp

Burns the agent's soulbound NFT. Irreversible. Poll status at:
GET https://app.ai.self.xyz/api/agent/deregister/status?sessionToken=<token>

### Refresh Proof-of-Human
POST https://app.ai.self.xyz/api/agent/refresh
Content-Type: application/json
Headers: x-self-agent-signature, x-self-agent-timestamp

Re-verifies the agent's human backing (e.g. after proof expiry). Returns a QR code for the human to scan with the Self app. Poll status at:
GET https://app.ai.self.xyz/api/agent/refresh/status?sessionToken=<token>

### Identify Agent
POST https://app.ai.self.xyz/api/agent/identify
Content-Type: application/json
Headers: x-self-agent-signature, x-self-agent-timestamp

Resolves an agent's on-chain identity from signed request headers. Returns agentId, verification status, and credentials. Poll status at:
GET https://app.ai.self.xyz/api/agent/identify/status?sessionToken=<token>

### Agents by Nullifier
GET https://app.ai.self.xyz/api/agent/agents-by-nullifier/:chainId/:nullifier

Lists all agents registered by a specific human (identified by their nullifier hash). Useful for sybil detection and human-to-agent mapping.

## Demo Endpoints (Test Your Agent)

All demo endpoints require Self Agent ID signed headers. Use `agent.fetch()` from the SDK:

```typescript
const res = await agent.fetch("https://app.ai.self.xyz/api/demo/agent-to-agent?network=celo-sepolia", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ test: "hello" }),
});
```

### Agent-to-Service (simplest test)
POST https://app.ai.self.xyz/api/demo/verify?network=celo-sepolia
Verifies your agent's identity and returns credentials. Good first test.

### Agent-to-Agent (recommended primary test)
POST https://app.ai.self.xyz/api/demo/agent-to-agent?network=celo-sepolia
A pre-registered demo agent verifies you, does a sameHuman check, and signs its response. Demonstrates mutual authentication.

### Agent-to-Chain — ECDSA
POST https://app.ai.self.xyz/api/demo/chain-verify
Submits an EIP-712 meta-tx to the on-chain AgentDemoVerifier. Requires RELAYER_PRIVATE_KEY on the server.

### Agent-to-Chain — Ed25519
POST https://app.ai.self.xyz/api/demo/chain-verify-ed25519
Submits an Ed25519 meta-tx to AgentDemoVerifierEd25519. Requires RELAYER_PRIVATE_KEY on the server.

### AI Agent Chat
POST https://app.ai.self.xyz/api/demo/chat?network=celo-sepolia
LangChain-powered AI that verifies your identity on-chain before chatting. Requires LANGCHAIN_URL on the server.

### Anonymous Census
POST https://app.ai.self.xyz/api/demo/census?network=celo-sepolia — contribute credentials
GET https://app.ai.self.xyz/api/demo/census?network=celo-sepolia — read aggregate stats (requires auth)
GET https://app.ai.self.xyz/api/demo/census?help=1 — endpoint documentation (no auth required)

Tip: Send a GET request to any demo endpoint (except census) to receive machine-readable usage documentation as JSON.

## Agent Authentication Headers

All authenticated endpoints use signed HTTP headers. The SDK handles this via `agent.fetch()` and `agent.signRequest()`.

### Header Protocol
  - x-self-agent-signature: HMAC-SHA256 signature of (method + url + body + timestamp)
  - x-self-agent-timestamp: ISO 8601 timestamp (e.g. "2026-03-10T12:00:00.000Z")
  - x-self-agent-address: Agent's Ethereum address (auto-derived by verifier)
  - x-self-agent-keytype: "ed25519" for Ed25519 agents, omit for ECDSA
  - x-self-agent-key: Agent's public key hex (required for Ed25519, optional for ECDSA)

### Using the SDK (TypeScript)
```typescript
import { SelfAgent, Ed25519Agent } from "@selfxyz/agent-sdk";

// ECDSA agent
const agent = new SelfAgent({ privateKey: "0x...", network: "testnet" });

// Ed25519 agent
const agent = new Ed25519Agent({ privateKey: "<64-hex-seed>", network: "testnet" });

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

// Manual signing — for custom HTTP clients
const headers = await agent.signRequest("POST", "https://example.com/api/protected", body);
// headers = { "x-self-agent-signature": "...", "x-self-agent-timestamp": "...", ... }
```

### Verifying Incoming Requests (Service-Side)
```typescript
import { SelfAgentVerifier } from "@selfxyz/agent-sdk";

const verifier = SelfAgentVerifier.create()
  .network("testnet")
  .sybilLimit(3)
  .requireAge(18)
  .build();

const result = await verifier.verify({
  signature: req.headers["x-self-agent-signature"],
  timestamp: req.headers["x-self-agent-timestamp"],
  method: "POST",
  url: req.url,
  body: reqBody,
  keytype: req.headers["x-self-agent-keytype"],
  agentKey: req.headers["x-self-agent-key"],
});
// result.valid, result.agentAddress, result.agentId, result.credentials
```

## SDK Packages (for post-registration use — NOT needed for registration)
  - npm: @selfxyz/agent-sdk
  - PyPI: selfxyz-agent-sdk
  - crates.io: self-agent-sdk

The SDKs provide signed request helpers, verification, and agent lifecycle management AFTER registration. For registration itself, just use the A2A endpoint or REST API above.

## Discovery Endpoints
  - https://app.ai.self.xyz/llms.txt — This file (plain text, for LLMs)
  - https://app.ai.self.xyz/.well-known/agent-card.json — A2A v0.3.0 agent card (JSON)
  - https://app.ai.self.xyz/api/a2a — A2A JSON-RPC endpoint