integrate-self-id

name: integrate-self-id description: > End-to-end integration guide for adding Self Agent ID to a project. Covers agent-side setup (SelfAgent class), service-side verification (SelfAgentVerifier), MCP server configuration, on-chain Solidity integration, and quick starts for TypeScript, Python, Rust, Express, FastAPI, Axum, and Hono. Use when the user asks to "add self agent id", "integrate self id", "setup self agent", "add agent verification to my project", "self agent id sdk", "install agent sdk", or "integrate proof of human". license: MIT metadata: author: Self Protocol version: 1.0.0 mcp-server: self-agent-id

Integrate Self Agent ID

Decision Tree — What Are You Building?

Before beginning integration, identify which components the project needs:

Start
  |
  +-- "Building an agent that needs identity"
  |     -> Agent-side integration (SelfAgent class)
  |        Install the SDK, generate/load a keypair, register, sign outbound HTTP requests.
  |
  +-- "Building a service/API that verifies agents"
  |     -> Service-side integration (SelfAgentVerifier class)
  |        Install the SDK, configure verification rules, protect API routes with middleware.
  |
  +-- "Building a smart contract that gates on agent identity"
  |     -> On-chain integration (Solidity)
  |        Import registry interfaces, add modifiers that check on-chain proof status and credentials.
  |
  +-- "Want AI tool (Claude Code / Cursor) to manage agent identity"
  |     -> MCP server setup
  |        Install @selfxyz/mcp-server, configure env vars, use MCP tools for registration and signing.
  |
  +-- Not sure?
        -> Most projects need BOTH agent-side AND service-side.
           Start with the agent-side to register and sign, then add
           service-side to verify incoming requests.

Select one or more paths below based on the project's requirements. Each section is self-contained.

Agent-Side Quick Start

Install the SDK for the agent's language, initialize with a private key (or generate a new one), and start making authenticated HTTP requests.

TypeScript

npm install @selfxyz/agent-sdk

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

const agent = new SelfAgent({
  privateKey: process.env.AGENT_PRIVATE_KEY!,
  network: "mainnet", // or "testnet"
});

// Check if registered
const info = await agent.getInfo();
if (!info.registered) {
  // Initiate registration — human scans QR with Self app
  // requestRegistration is a static method
  const session = await SelfAgent.requestRegistration({
    mode: "linked",
    network: "mainnet",
    disclosures: { minimumAge: 18, ofac: true },
    humanAddress: "0x...", // the human's wallet address
  });
  console.log("Scan QR:", session.deepLink);
}

// Make authenticated requests (auto-signs with 3-header system)
const res = await agent.fetch("https://api.example.com/data", {
  method: "POST",
  body: JSON.stringify({ query: "hello" }),
});

For Ed25519 agents (Python/Rust-friendly), use Ed25519Agent after registering with mode "ed25519-linked":

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

const agent = new Ed25519Agent({ privateKey: process.env.AGENT_PRIVATE_KEY! });
const res = await agent.fetch("https://api.example.com/data", {
  method: "POST",
  body: JSON.stringify({ query: "hello" }),
});

Python

pip install selfxyz-agent-sdk

import os
from self_agent_sdk import SelfAgent

agent = SelfAgent(private_key=os.environ["AGENT_PRIVATE_KEY"], network="mainnet")

# Check registration status
info = agent.get_info()

# Make authenticated requests
response = agent.fetch(
    "https://api.example.com/data",
    method="POST",
    body='{"query":"hello"}'
)

Rust

cargo add self-agent-sdk

use self_agent_sdk::SelfAgent;

let agent = SelfAgent::new(std::env::var("AGENT_PRIVATE_KEY").unwrap())?;
let info = agent.get_info().await?;

let response = agent.fetch(
    "https://api.example.com/data",
    "POST",
    Some(r#"{"query":"hello"}"#),
    None,
).await?;

All three SDKs expose identical API surfaces. The fetch() method wraps the native HTTP client, auto-attaching the x-self-agent-address, x-self-agent-signature, and x-self-agent-timestamp headers to every request.

Service-Side Quick Start

Install the SDK on the server, configure a verifier with the desired checks, and protect API routes.

TypeScript (Express)

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

const app = express();
app.use(express.json());

const verifier = SelfAgentVerifier.create()
  .network("mainnet")
  .requireAge(18)
  .requireOFAC()
  .requireSelfProvider() // CRITICAL: always include in production
  .sybilLimit(3)
  .build();

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

// Access verified agent info in handlers
app.get("/api/profile", (req, res) => {
  const agent = req.verifiedAgent;
  res.json({
    agentId: agent.agentId,
    nationality: agent.credentials.nationality,
  });
});

app.listen(3000);

Python (FastAPI)

from fastapi import FastAPI, Request, HTTPException
from self_agent_sdk import SelfAgentVerifier

app = FastAPI()

verifier = (
    SelfAgentVerifier.create()
    .network("mainnet")
    .require_age(18)
    .require_ofac()
    .require_self_provider()  # CRITICAL
    .sybil_limit(3)
    .build()
)

@app.middleware("http")
async def verify_agent(request: Request, call_next):
    if request.url.path.startswith("/api"):
        address = request.headers.get("x-self-agent-address")
        signature = request.headers.get("x-self-agent-signature")
        timestamp = request.headers.get("x-self-agent-timestamp")

        if not all([address, signature, timestamp]):
            raise HTTPException(status_code=401, detail="Missing agent auth headers")

        body = await request.body()
        result = await verifier.verify(
            address=address, signature=signature, timestamp=timestamp,
            method=request.method, path=request.url.path,
            body=body.decode("utf-8") if body else "",
        )

        if not result.valid:
            raise HTTPException(status_code=401, detail=result.error)

        request.state.agent = result

    return await call_next(request)

@app.get("/api/profile")
async def profile(request: Request):
    agent = request.state.agent
    return {"agent_id": agent.agent_id}

Rust (Axum)

use axum::{routing::get, Router, middleware};
use self_agent_sdk::SelfAgentVerifier;
use std::sync::Arc;

let verifier = SelfAgentVerifier::builder()
    .network("mainnet")
    .require_age(18)
    .require_ofac()
    .require_self_provider() // CRITICAL
    .sybil_limit(3)
    .build()?;

let state = AppState { verifier: Arc::new(verifier) };

let protected = Router::new()
    .route("/api/profile", get(profile_handler))
    .layer(middleware::from_fn_with_state(state.clone(), verify_agent_middleware));

let app = Router::new()
    .route("/health", get(health))
    .merge(protected)
    .with_state(state);

MCP Server Setup

Install the MCP server to give AI coding assistants (Claude Code, Cursor, Windsurf) access to Self Agent ID tools.

Installation

# Install globally
npm install -g @selfxyz/mcp-server

# Or run via npx (no install required)
npx @selfxyz/mcp-server

Claude Code Configuration

Add to the MCP settings (.claude/mcp_servers.json or project-level config):

{
  "self-agent-id": {
    "command": "npx",
    "args": ["-y", "@selfxyz/mcp-server"],
    "env": {
      "SELF_AGENT_PRIVATE_KEY": "0x...",
      "SELF_NETWORK": "testnet",
      "SELF_AGENT_API_BASE": "https://agent-api.self.xyz"
    }
  }
}

Cursor Configuration

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "self-agent-id": {
      "command": "npx",
      "args": ["-y", "@selfxyz/mcp-server"],
      "env": {
        "SELF_AGENT_PRIVATE_KEY": "0x...",
        "SELF_NETWORK": "testnet",
        "SELF_AGENT_API_BASE": "https://agent-api.self.xyz"
      }
    }
  }
}

Environment Variables

SELF_AGENT_API_BASE is the canonical environment variable. The previous SELF_API_URL has been removed.

Available MCP Tools

Once configured, the MCP server exposes 10 tools:

On-Chain Integration Quick Start (Solidity)

Import the registry interface and add modifiers that gate contract functions on agent identity.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.28;

import {IERC8004ProofOfHuman} from "./interfaces/IERC8004ProofOfHuman.sol";

interface ISelfAgentRegistryReader is IERC8004ProofOfHuman {
    function isVerifiedAgent(bytes32 agentKey) external view returns (bool);
    function getAgentId(bytes32 agentKey) external view returns (uint256);
    function getProofProvider(uint256 agentId) external view returns (address);
    function getAgentKey(uint256 agentId) external view returns (bytes32);
}

contract MyContract {
    ISelfAgentRegistryReader public immutable registry;
    address public immutable selfProvider;

    constructor(address _registry, address _selfProvider) {
        registry = ISelfAgentRegistryReader(_registry);
        selfProvider = _selfProvider;
    }

    modifier onlyVerifiedAgent(uint256 agentId) {
        require(
            registry.isVerifiedAgent(registry.getAgentKey(agentId)),
            "Not verified"
        );
        require(
            registry.getProofProvider(agentId) == selfProvider,
            "Wrong provider"
        );
        _;
    }

    function protectedAction(uint256 agentId) external onlyVerifiedAgent(agentId) {
        // Only verified agents reach this point
    }
}

Compile with Foundry:

forge build --evm-version cancun

The --evm-version cancun flag is required because Hub V2 uses the PUSH0 opcode introduced in the Cancun upgrade.

Contract Addresses

Handling Proof Expiry

Human proofs expire after maxProofAge (default: 365 days) or when the passport document expires, whichever comes first. Integrations should handle this gracefully.

Service-Side: Detect Expired Proofs

The SelfAgentVerifier checks proof freshness via isProofFresh() as part of its verify() flow. When a proof has expired, the verifier returns valid: false with an error message. Handle this in your error responses to guide agents toward re-registration:

// TypeScript
const result = await verifier.verify({
  address,
  signature,
  timestamp,
  method,
  path,
  body,
});
if (!result.valid && result.error?.includes("proof has expired")) {
  return res.status(401).json({
    error: "Agent proof has expired",
    action: "deregister_and_reregister",
  });
}

Agent-Side: Monitor Expiry

Check proofExpiresAt proactively and warn before expiry:

// TypeScript
const info = await agent.getInfo();
const THIRTY_DAYS = 30 * 24 * 60 * 60;
const now = Math.floor(Date.now() / 1000);
if (info.proofExpiresAt > 0 && info.proofExpiresAt - now < THIRTY_DAYS) {
  console.warn("Proof expiring soon — initiate refresh");
}

On-Chain: Use isProofFresh()

// Gate on freshness, not just proof existence
require(registry.isProofFresh(agentId), "Proof expired");

Refresh Flow

In-place refresh (preferred): Use requestProofRefresh({ agentId, network, disclosures }) — the human scans their passport again and proofExpiresAt is updated without changing the agentId.

Deregister + re-register: If changing verification config or key type, deregister first then re-register. The agentId changes — update any stored references.

Troubleshooting

These are the most frequently encountered issues during integration. Read through all of them before starting.

Testing End-to-End

Follow this sequence to validate a full integration from registration through verification:

1. Register on testnet first — Use chain 11142220 (Celo Sepolia). No real funds needed. Set network: "testnet" in the SDK or SELF_NETWORK=testnet in MCP config.

2. Scan QR with Self app — The registration flow generates a QR code. Open the Self app, scan the QR, and scan the passport NFC chip. The Self app generates a ZK proof locally and submits it on-chain.

3. Poll for completion — Call agent.getRegistrationStatus() (SDK) or self_check_registration (MCP) every 5-10 seconds. The flow typically takes 30-90 seconds. Sessions expire after 30 minutes.

4. Test request signing — Use agent.signRequest() or self_sign_request to generate the 3 auth headers. Verify them using SelfAgentVerifier or self_verify_request.

5. Verify credentials match — Call agent.getCredentials() or self_get_identity and confirm the stored credentials (nationality, age threshold, OFAC status) match the selected verification config.

6. Test signed fetch — Make a full round-trip: agent signs a request to a protected endpoint, the server verifies the signature and on-chain state, and returns agent-specific data.

7. Test failure cases — Verify that the server correctly rejects: missing headers (401), expired timestamps (401), invalid signatures (401), unregistered agents (401), wrong provider (401), and sybil limit exceeded (403).

Reference Documentation

For the complete SDK API reference covering all classes, methods, types, and constants across TypeScript, Python, and Rust, see references/sdk-reference.md.

For full runnable integration examples across Express, FastAPI, Axum, Hono, Next.js, LangChain, and Solidity, see references/framework-examples.md.