Overview
The Self Agent ID REST API lets you programmatically register, deregister, and query AI agents with on-chain proof-of-human verification. No API keys required — sessions use encrypted tokens with a 30-minute TTL.
Base URL: https://self-agent-id.vercel.app/api/agent
Discovery: GET /.well-known/self-agent-id.json
Session lifecycle:
POST /register → session token
↳ User scans QR with Self app → proof submitted on-chain
GET /register/status?token= → poll until completed
GET /register/export?token= → retrieve agent private key
Using an AI coding assistant? The MCP server wraps these REST APIs into 10 tools — no manual HTTP needed. Set up MCP →
Quick Start
Register an agent in 3 steps using curl:
1# 1. Initiate registration2curl -X POST https://self-agent-id.vercel.app/api/agent/register \3 -H "Content-Type: application/json" \4 -d '{5 "mode": "agent-identity",6 "network": "testnet",7 "humanAddress": "0xYourWalletAddress"8 }'9# → { sessionToken, deepLink, agentAddress, ... }1011# 2. Show deepLink to user (or render QR)12# User scans QR with Self app → passport proof submitted1314# 3. Poll for completion15curl "https://self-agent-id.vercel.app/api/agent/register/status?token=SESSION_TOKEN"16# → { stage: "completed", agentId: 42, ... }1718# 4. (Optional) Export agent private key19curl "https://self-agent-id.vercel.app/api/agent/register/export?token=SESSION_TOKEN"20# → { privateKey, agentAddress, agentId }
Endpoints
SDK Integration
SDKs wrap the REST API and provide typed helpers for registration, verification, and signed requests.
1import { SelfAgent } from "@selfxyz/agent-sdk";23const agent = new SelfAgent({4 endpoint: "https://self-agent-id.vercel.app",5 network: "testnet",6});78// Request registration — returns session with QR link9const session = await agent.requestRegistration({10 mode: "agent-identity",11 humanAddress: "0xYourWallet",12 disclosures: { minimumAge: 18, ofac: true },13});1415console.log(session.deepLink); // show to user16console.log(session.sessionToken); // save for polling1718// Poll until complete19const result = await agent.waitForRegistration(session.sessionToken);20console.log(result.agentId); // on-chain agent ID
Authentication
The API uses encrypted session tokens instead of API keys. Tokens are returned by POST /register and POST /deregister and must be passed as a token query parameter to all subsequent endpoints.
- Tokens expire after 30 minutes
- Each token is scoped to a single registration or deregistration session
- Updated tokens are returned in each response — always use the latest one
- Query endpoints (
/info,/agents,/verify) require no authentication
Error Codes
All errors return { "error": "message" } with the appropriate HTTP status.
| Code | Meaning |
|---|---|
| 400 | Bad request — invalid parameters, missing fields, or wrong mode |
| 401 | Invalid or tampered session token |
| 404 | Agent not found on-chain |
| 409 | Operation not available at current session stage |
| 410 | Session expired (30-minute TTL) |
| 500 | Server error — RPC failure or configuration issue |
Full source code and SDK packages are available on GitHub. See the CLI Quickstart for command-line usage.