Integration Guide

Everything you need to verify agents in your service, authenticate your agent with other services, or register agents from the terminal.

npm install @selfxyz/agent-sdkpip install selfxyz-agent-sdkcargo add self-agent-sdkmcp · @selfxyz/mcp-server

Verify Agents in Your Service

These code snippets are for service developers who want to verify agents in their applications. Pre-filled with the deployed contract address for Celo.

Smart contracts are currently deployed on Celo (mainnet & Sepolia testnet). Multichain support is coming soon.

Verify that an AI agent calling your API is human-backed. The SDK recovers the signer from the ECDSA signature, checks isVerifiedAgent() on-chain, and optionally reads ZK-attested credentials and enforces sybil limits.

Security default: requireSelfProvider: true. Turning this off accepts any approved proof provider, not only Self.

npm install @selfxyz/agent-sdk (or pip install selfxyz-agent-sdk or cargo add self-agent-sdk) → Create verifier → Add middleware → Done

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

3import express from "express";
4

5const app = express();
6app.use(express.json({
7  verify: (req: any, _res: any, buf: any) => {
8    req.rawBody = typeof buf === "string" ? buf : buf.toString("utf8");
9  },
10}));
11const verifier = SelfAgentVerifier.create().build();
12

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

15app.post("/api/data", (req, res) => {
16  console.log("Verified agent:", req.agent.address);
17

18  res.json({ ok: true });
19});

How to Use Your Agent

If you are the agent operator, use these snippets to authenticate your agent with services or submit on-chain transactions. Set AGENT_PRIVATE_KEY in your agent's environment first.

Your agent signs every outgoing HTTP request with ECDSA (timestamp + method + URL + body hash). Services recover the signer from the signature and check isVerifiedAgent() on-chain — no API keys or tokens needed.

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

3const agent = new SelfAgent({
4  privateKey: process.env.AGENT_PRIVATE_KEY,
5});
6

7// Every request is signed automatically
8const res = await agent.fetch("https://api.example.com/data", {
9  method: "POST",
10  body: JSON.stringify({ query: "test" }),
11});
12

13// Check your own registration status
14const registered = await agent.isRegistered();

CLI & Agent-Guided Registration

Register agents from your terminal or let your backend orchestrate the registration flow programmatically. The CLI creates a session, generates a browser handoff URL, and polls for completion.

Quick Start

1npx @selfxyz/agent-sdk register init \
2  --mode linked \
3  --human-address 0xYourWalletAddress \
4  --network mainnet \
5  --out .self/session.json
6

7# Open browser for Self proof
8npx @selfxyz/agent-sdk register open --session .self/session.json
9

10# Wait for completion
11npx @selfxyz/agent-sdk register wait --session .self/session.json
12

13# Export credentials
14npx @selfxyz/agent-sdk register export --session .self/session.json

Agent-guided flow (recommended): Your backend calls register init, forwards the handoff URL to the user, and polls register wait for completion. This is the recommended pattern for services that onboard users programmatically.

CLI QuickstartAPI Reference

MCP Server & Claude Code Plugin

Use Self Agent ID directly from your AI coding assistant. The MCP server exposes tools for identity management — register, sign, verify, and query agents without leaving your editor.

MCP Server (any MCP-compatible IDE)

Add this to your project's .mcp.json or IDE MCP settings:

1{
2  "self-agent-id": {
3    "command": "npx",
4    "args": ["-y", "@selfxyz/mcp-server"],
5    "env": {
6      "SELF_AGENT_PRIVATE_KEY": "0x...",
7      "SELF_NETWORK": "mainnet",
8      "SELF_AGENT_API_BASE": "https://app.ai.self.xyz"
9    }
10  }
11}

Claude Code Plugin (guided workflows)

The plugin adds 6 skills that guide Claude through registration, signing, verification, and integration — with full protocol context loaded automatically.

1# Clone the repo and install the plugin
2git clone https://github.com/selfxyz/self-agent-id.git
3claude plugin add ./self-agent-id/plugin
4

5# Or point to a local checkout
6claude plugin add /path/to/self-agent-id/plugin

10 MCP Tools

self_register_agentStart agent registration (QR URL)
self_check_registrationPoll registration status
self_get_identityGet current agent identity
self_deregister_agentInitiate deregistration
self_sign_requestGenerate auth headers
self_authenticated_fetchMake a signed HTTP request
self_lookup_agentLook up agent by ID or address
self_list_agents_for_humanList agents for a human
self_verify_agentVerify on-chain proof status
self_verify_requestVerify signed request headers

6 Plugin Skills

Each skill is a self-contained knowledge module with decision trees, code examples, and reference docs. They load automatically in Claude Code when triggered by your request.

self-agent-id-overviewArchitecture, contracts, trust model, ERC-8004 standard, provider system
register-agentStep-by-step registration in all modes (linked, wallet-free, smart-wallet, privy, ed25519, ed25519+guardian)
sign-requestsECDSA request signing, 3-header auth system, signed fetch patterns
verify-agentsOn-chain verification, SelfAgentVerifier middleware, reputation, freshness, sybil detection
query-credentialsZK-attested credentials, agent cards (A2A format), reputation scores
integrate-self-idEnd-to-end integration: agent-side, service-side, on-chain gating, MCP setup

Building a custom agent? Use our system prompts

For agents that don't support MCP (LangChain, AutoGPT, custom frameworks), paste one of these self-contained system prompts. No tools required — the agent gets full protocol knowledge and uses the REST API directly.

Full protocol Registration only Verification only