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 registration
2curl -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, ... }
10
11# 2. Show deepLink to user (or render QR)
12# User scans QR with Self app → passport proof submitted
13
14# 3. Poll for completion
15curl "https://self-agent-id.vercel.app/api/agent/register/status?token=SESSION_TOKEN"
16# → { stage: "completed", agentId: 42, ... }
17
18# 4. (Optional) Export agent private key
19curl "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";
2
3const agent = new SelfAgent({
4 endpoint: "https://self-agent-id.vercel.app",
5 network: "testnet",
6});
7
8// Request registration — returns session with QR link
9const session = await agent.requestRegistration({
10 mode: "agent-identity",
11 humanAddress: "0xYourWallet",
12 disclosures: { minimumAge: 18, ofac: true },
13});
14
15console.log(session.deepLink); // show to user
16console.log(session.sessionToken); // save for polling
17
18// Poll until complete
19const 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.

CodeMeaning
400Bad request — invalid parameters, missing fields, or wrong mode
401Invalid or tampered session token
404Agent not found on-chain
409Operation not available at current session stage
410Session expired (30-minute TTL)
500Server error — RPC failure or configuration issue

Full source code and SDK packages are available on GitHub. See the CLI Quickstart for command-line usage.