REST API

# REST API Self Agent ID exposes REST endpoints for registration workflows, agent queries, and A2A discovery. All endpoints are served from the web app deployment. The full OpenAPI 3.1 spec is available at [`openapi.yaml`](https://github.com/selfxyz/self-agent-id/blob/main/openapi.yaml) in the main repository — import it into Postman or use it to generate clients. For interactive documentation, visit [selfagentid.xyz/api-docs](https://selfagentid.xyz/api-docs). ## Public Query Endpoints These endpoints require no authentication. ### Get Agent Info ``` GET /api/agent/info/{chainId}/{agentId} ``` Returns agent registration details, verification status, and credentials. **Example response:** ```json { "agentId": 5, "chainId": 11142220, "agentAddress": "0x83fa4380903fecb801F4e123835664973001ff00", "isVerified": true, "proofProvider": "0x5E61c3051Bf4115F90AacEAE6212bc419f8aBB6c", "verificationStrength": 2, "strengthLabel": "Standard", "credentials": { "nationality": "GBR", "olderThan": 18, "ofac": [false, false, false] }, "registeredAt": 1740000000, "network": "testnet" } ``` ### List Agents by Human Address ``` GET /api/agent/agents/{chainId}/{address} ``` Returns all agent IDs registered by a specific human wallet address. **Example response:** ```json { "agents": [5, 12, 37], "chainId": 11142220, "humanAddress": "0xabc..." } ``` ### Verify Agent Proof-of-Human ``` GET /api/agent/verify/{chainId}/{agentId} ``` Checks whether an agent has valid proof-of-human verification, the proof provider address, verification strength, and Sybil metrics. **Example response:** ```json { "agentId": 5, "isVerified": true, "proofProvider": "0x5E61c3051Bf4115F90AacEAE6212bc419f8aBB6c", "strengthLabel": "Standard", "humanAgentCount": 1, "maxAgentsPerHuman": 1 } ``` ### Get Agent Card ``` GET /api/cards/{chainId}/{agentId} ``` Returns the A2A-compatible agent identity card in JSON format. ### Get Reputation Score ``` GET /api/reputation/{chainId}/{agentId} ``` Returns the agent's verification strength score from the proof provider. **Example response:** ```json { "score": 2, "hasProof": true, "providerName": "Self Protocol", "proofType": "Standard" } ``` ### Get Verification Status ``` GET /api/verify-status/{chainId}/{agentId} ``` Returns real-time proof status and freshness. **Example response:** ```json { "verified": true, "proofType": "Standard", "registeredAtBlock": "12345678", "providerAddress": "0x5E61c3051Bf4115F90AacEAE6212bc419f8aBB6c" } ``` ### A2A Discovery ``` GET /.well-known/a2a/{agentId}?chain={chainId} ``` Redirects to the agent card resolver. Compatible with A2A agent discovery protocols. ### A2A Protocol (JSON-RPC) ``` POST /api/a2a ``` Agent-to-Agent JSON-RPC 2.0 endpoint for programmatic interaction. Agents can register, verify, look up, deregister, and check proof freshness through natural language or structured intents. **Example request:** ```json { "jsonrpc": "2.0", "id": 1, "method": "message/send", "params": { "message": { "role": "user", "parts": [{ "type": "data", "data": { "intent": "register" } }] } } } ``` Supported intents: `register`, `status`, `lookup`, `verify`, `deregister`, `freshness`, `help`. All intents default to mainnet. Add `network: "testnet"` or `chainId: 11142220` for Celo Sepolia (mock documents via the Self app — no real passport needed). ### Service Discovery ``` GET /.well-known/self-agent-id.json ``` Returns the service discovery document with API base URL, supported networks, registration modes, and capabilities. **Example response:** ```json { "name": "Self Agent ID", "version": "1.0", "apiBase": "https://selfagentid.xyz/api/agent", "networks": ["mainnet", "testnet"], "registrationModes": ["linked", "wallet-free", "ed25519", "ed25519-linked", "privy", "smartwallet"], "capabilities": ["register", "deregister", "verify", "credentials", "agent-card", "a2a"], "sessionTtlMs": 1800000 } ``` ### List Agents by Nullifier ``` GET /api/agent/agents-by-nullifier/{chainId}/{nullifier} ``` Returns all agent IDs associated with a given human nullifier. Useful for Sybil detection — check how many agents a single human has registered. **Example response:** ```json { "nullifier": "123456789...", "agents": [5, 12], "chainId": 42220 } ``` ### Health Check ``` GET /api/health ``` Returns service health status. No authentication required. ## Identify Endpoints Used to discover existing agents for a human without registering a new one. The human scans their passport and the system returns their nullifier, which can be used to look up all associated agents. ### Create Identify Session ``` POST /api/agent/identify ``` Creates a passport scan session for agent discovery. Returns a QR code and deep link for the Self app. **Request body:** ```json { "network": "mainnet" } ``` ### Poll Identify Status ``` GET /api/agent/identify/status?token={sessionToken} ``` Polls for identification completion. Returns the human's nullifier and agent count once the passport scan is complete. ## Proof Refresh Endpoints Used to refresh an existing agent's proof without re-registering. The human re-scans their passport to update the proof on-chain. ### Create Refresh Session ``` POST /api/agent/refresh ``` Creates a proof refresh session for an existing agent. **Request body:** ```json { "agentId": 42, "network": "mainnet", "disclosures": { "minimumAge": 18, "ofac": true } } ``` ### Poll Refresh Status ``` GET /api/agent/refresh/status?token={sessionToken} ``` Polls for refresh completion. Returns updated verification details once the proof is refreshed on-chain. ## Registration Endpoints Used by the dApp and CLI during registration flows. Sessions use encrypted tokens with a 30-minute TTL. ### Create Registration Session ``` POST /api/agent/register ``` Creates a new registration session. Returns session token, QR code data, deep link, and the generated agent address. **Request body:** ```json { "mode": "linked", "network": "mainnet", "humanAddress": "0xYourWalletAddress", "disclosures": { "minimumAge": 18, "ofac": true, "nationality": false, "name": false } } ``` Modes: `linked`, `wallet-free`, `ed25519`, `ed25519-linked`, `privy`, `smartwallet`. Networks: `mainnet` (default, real passports via Self app), `testnet` (mock documents via Self app, no real passport needed). **Example response:** ```json { "sessionToken": "enc_...", "deepLink": "selfapp://verify?scope=...", "qrData": "selfapp://verify?scope=...", "agentAddress": "0x83fa...ff00", "mode": "linked", "network": "mainnet" } ``` ### Poll Registration Status ``` GET /api/agent/register/status?token={sessionToken} ``` Polls for registration completion. Returns stage: `qr-ready`, `proof-received`, `completed`, or `failed`. **Example response:** ```json { "stage": "completed", "agentId": 42, "agentAddress": "0x83fa...ff00", "txHash": "0xabc...", "sessionToken": "enc_..." } ``` ### Get QR Code ``` GET /api/agent/register/qr?token={sessionToken} ``` Returns the QR code payload and deep link for the current session. ### Self App Callback ``` POST /api/agent/register/callback?token={sessionToken} ``` Webhook endpoint called by the Self app after the user scans the QR and submits a passport proof. ### Export Agent Private Key ``` GET /api/agent/register/export?token={sessionToken} ``` After registration completes, export the agent's private key. Only available for `linked`, `wallet-free`, `ed25519`, and `ed25519-linked` modes. **Example response:** ```json { "privateKey": "0xdeadbeef...", "agentAddress": "0x83fa...ff00", "agentId": 42 } ``` ## Deregistration Endpoints ### Create Deregistration Session ``` POST /api/agent/deregister ``` Creates a deregistration session for an existing agent. The human must re-prove identity to burn the agent NFT. **Request body:** ```json { "network": "testnet", "agentAddress": "0xAgentAddress", "disclosures": { "minimumAge": 18, "ofac": true } } ``` ### Poll Deregistration Status ``` GET /api/agent/deregister/status?token={sessionToken} ``` Returns current deregistration stage. Once completed, the agent NFT has been burned. ### Deregistration Callback ``` POST /api/agent/deregister/callback?token={sessionToken} ``` Webhook endpoint for the Self app after the user confirms deregistration. ## Demo Endpoints Used by the live demo page for testing agent verification patterns. All demo endpoints require `x-self-agent-*` signed headers (produced by `SelfAgent.signRequest()`). ### Verify Agent (Service Pattern) ``` POST /api/demo/verify ``` Accepts a signed agent request, verifies signature and on-chain status, returns agent info and credentials. ### Agent-to-Agent ``` POST /api/demo/agent-to-agent ``` Demo agent endpoint that verifies the caller, checks `sameHuman()`, and signs its response. Response headers include the demo agent's own `x-self-agent-*` signature for mutual verification. ### Chain Verify (Meta-Transaction) ``` POST /api/demo/chain-verify ``` Relayer endpoint that submits EIP-712 meta-transactions to the `AgentDemoVerifier` contract. Rate limited to 3 per hour per human nullifier. **Request body:** ```json { "agentKey": "0x...", "nonce": "0", "deadline": 1740001800, "eip712Signature": "0x...", "networkId": "celo-sepolia" } ``` ### Chain Verify Ed25519 (Meta-Transaction) ``` POST /api/demo/chain-verify-ed25519 ``` Same as chain-verify but for agents registered with Ed25519 keys. Relays EIP-712 meta-transactions signed with Ed25519. ### Census (Aggregated Stats) ``` POST /api/demo/census — contribute credentials GET /api/demo/census — read aggregate stats ``` Demonstrates agent-gated data contribution and reading. ### AI Chat ``` POST /api/demo/chat ``` AI agent chat endpoint backed by a LangChain agent. Signed requests are verified on-chain; unsigned requests are treated as anonymous. **Request body:** ```json { "query": "What is Self Agent ID?", "session_id": "user-123" } ``` ## AA Proxy Endpoints Account-abstraction proxy for the smart-wallet registration mode. These endpoints proxy JSON-RPC calls to a Pimlico bundler/paymaster, shielding the API key from the client. Origin-restricted and rate-limited. ### Issue AA Proxy Token ``` POST /api/aa/token?chainId={chainId} ``` Issues a short-lived token required by the bundler and paymaster endpoints. Rate limited to 30 requests per minute per IP. **Example response:** ```json { "token": "eyJhbGciOi...", "expiresAt": 1740001800000 } ``` ### Bundler Proxy ``` POST /api/aa/bundler?chainId={chainId} ``` Proxies ERC-4337 bundler JSON-RPC calls. Requires the `x-aa-proxy-token` header from the token endpoint. **Allowed methods:** `eth_chainId`, `eth_supportedEntryPoints`, `eth_estimateUserOperationGas`, `eth_sendUserOperation`, `eth_getUserOperationReceipt`, `eth_getUserOperationByHash`, `eth_gasPrice`, `eth_maxPriorityFeePerGas`. **Request body (JSON-RPC 2.0):** ```json { "jsonrpc": "2.0", "method": "eth_sendUserOperation", "params": [...], "id": 1 } ``` ### Paymaster Proxy ``` POST /api/aa/paymaster?chainId={chainId} ``` Proxies ERC-4337 paymaster JSON-RPC calls. Requires the `x-aa-proxy-token` header. **Allowed methods:** `pm_sponsorUserOperation`, `pm_getPaymasterData`, `pm_getPaymasterStubData`, `eth_chainId`. ## Authentication - **Public endpoints** (info, agents, verify, cards, reputation, verify-status, discovery): No authentication required - **Demo endpoints**: Require `x-self-agent-*` headers (signed via SDK) - **Registration endpoints**: Session-based with encrypted tokens, used by dApp/CLI - **AA Proxy endpoints**: Origin-restricted + `x-aa-proxy-token` header (from `/api/aa/token`) ## Chain ID Parameter All endpoints that accept a `chainId` parameter support: - `42220` — Celo Mainnet - `11142220` — Celo Sepolia Testnet :::warning Use chain ID `11142220` for Celo Sepolia, not `44787` (deprecated Alfajores). ::: ## 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 / missing auth headers | | 403 | Origin check failed or agent verification failed | | 404 | Agent not found on-chain | | 409 | Operation not available at current session stage / replay detected | | 410 | Session expired (30-minute TTL) | | 413 | Request too large (AA proxy, 200 KB limit) | | 429 | Rate limit exceeded | | 500 | Server error — RPC failure or configuration issue | | 503 | Service not configured (bundler, paymaster, or LangChain) |

Self Agent ID exposes REST endpoints for registration workflows, agent queries, and A2A discovery. All endpoints are served from the web app deployment.

The full OpenAPI 3.1 spec is available at openapi.yaml in the main repository — import it into Postman or use it to generate clients.

For interactive documentation, visit selfagentid.xyz/api-docs.

Public Query Endpoints

These endpoints require no authentication.

Get Agent Info

GET /api/agent/info/{chainId}/{agentId}

Returns agent registration details, verification status, and credentials.

Example response:

{
  "agentId": 5,
  "chainId": 11142220,
  "agentAddress": "0x83fa4380903fecb801F4e123835664973001ff00",
  "isVerified": true,
  "proofProvider": "0x5E61c3051Bf4115F90AacEAE6212bc419f8aBB6c",
  "verificationStrength": 2,
  "strengthLabel": "Standard",
  "credentials": {
    "nationality": "GBR",
    "olderThan": 18,
    "ofac": [false, false, false]
  },
  "registeredAt": 1740000000,
  "network": "testnet"
}

List Agents by Human Address

GET /api/agent/agents/{chainId}/{address}

Returns all agent IDs registered by a specific human wallet address.

Example response:

{
  "agents": [5, 12, 37],
  "chainId": 11142220,
  "humanAddress": "0xabc..."
}

Verify Agent Proof-of-Human

GET /api/agent/verify/{chainId}/{agentId}

Checks whether an agent has valid proof-of-human verification, the proof provider address, verification strength, and Sybil metrics.

Example response:

{
  "agentId": 5,
  "isVerified": true,
  "proofProvider": "0x5E61c3051Bf4115F90AacEAE6212bc419f8aBB6c",
  "strengthLabel": "Standard",
  "humanAgentCount": 1,
  "maxAgentsPerHuman": 1
}

Get Agent Card

GET /api/cards/{chainId}/{agentId}

Returns the A2A-compatible agent identity card in JSON format.

Get Reputation Score

GET /api/reputation/{chainId}/{agentId}

Returns the agent’s verification strength score from the proof provider.

Example response:

{
  "score": 2,
  "hasProof": true,
  "providerName": "Self Protocol",
  "proofType": "Standard"
}

Get Verification Status

GET /api/verify-status/{chainId}/{agentId}

Returns real-time proof status and freshness.

Example response:

{
  "verified": true,
  "proofType": "Standard",
  "registeredAtBlock": "12345678",
  "providerAddress": "0x5E61c3051Bf4115F90AacEAE6212bc419f8aBB6c"
}

A2A Discovery

GET /.well-known/a2a/{agentId}?chain={chainId}

Redirects to the agent card resolver. Compatible with A2A agent discovery protocols.

A2A Protocol (JSON-RPC)

POST /api/a2a

Agent-to-Agent JSON-RPC 2.0 endpoint for programmatic interaction. Agents can register, verify, look up, deregister, and check proof freshness through natural language or structured intents.

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [{ "type": "data", "data": { "intent": "register" } }]
    }
  }
}

Supported intents: register, status, lookup, verify, deregister, freshness, help.

All intents default to mainnet. Add network: "testnet" or chainId: 11142220 for Celo Sepolia (mock documents via the Self app — no real passport needed).

Service Discovery

GET /.well-known/self-agent-id.json

Returns the service discovery document with API base URL, supported networks, registration modes, and capabilities.

Example response:

{
  "name": "Self Agent ID",
  "version": "1.0",
  "apiBase": "https://selfagentid.xyz/api/agent",
  "networks": ["mainnet", "testnet"],
  "registrationModes": ["linked", "wallet-free", "ed25519", "ed25519-linked", "privy", "smartwallet"],
  "capabilities": ["register", "deregister", "verify", "credentials", "agent-card", "a2a"],
  "sessionTtlMs": 1800000
}

List Agents by Nullifier

GET /api/agent/agents-by-nullifier/{chainId}/{nullifier}

Returns all agent IDs associated with a given human nullifier. Useful for Sybil detection — check how many agents a single human has registered.

Example response:

{
  "nullifier": "123456789...",
  "agents": [5, 12],
  "chainId": 42220
}

Health Check

GET /api/health

Returns service health status. No authentication required.

Identify Endpoints

Used to discover existing agents for a human without registering a new one. The human scans their passport and the system returns their nullifier, which can be used to look up all associated agents.

Create Identify Session

POST /api/agent/identify

Creates a passport scan session for agent discovery. Returns a QR code and deep link for the Self app.

Request body:

{
  "network": "mainnet"
}

Poll Identify Status

GET /api/agent/identify/status?token={sessionToken}

Polls for identification completion. Returns the human’s nullifier and agent count once the passport scan is complete.

Proof Refresh Endpoints

Used to refresh an existing agent’s proof without re-registering. The human re-scans their passport to update the proof on-chain.

Create Refresh Session

POST /api/agent/refresh

Creates a proof refresh session for an existing agent.

Request body:

{
  "agentId": 42,
  "network": "mainnet",
  "disclosures": {
    "minimumAge": 18,
    "ofac": true
  }
}

Poll Refresh Status

GET /api/agent/refresh/status?token={sessionToken}

Polls for refresh completion. Returns updated verification details once the proof is refreshed on-chain.

Registration Endpoints

Used by the dApp and CLI during registration flows. Sessions use encrypted tokens with a 30-minute TTL.

Create Registration Session

POST /api/agent/register

Creates a new registration session. Returns session token, QR code data, deep link, and the generated agent address.

Request body:

{
  "mode": "linked",
  "network": "mainnet",
  "humanAddress": "0xYourWalletAddress",
  "disclosures": {
    "minimumAge": 18,
    "ofac": true,
    "nationality": false,
    "name": false
  }
}

Modes: linked, wallet-free, ed25519, ed25519-linked, privy, smartwallet. Networks: mainnet (default, real passports via Self app), testnet (mock documents via Self app, no real passport needed).

Example response:

{
  "sessionToken": "enc_...",
  "deepLink": "selfapp://verify?scope=...",
  "qrData": "selfapp://verify?scope=...",
  "agentAddress": "0x83fa...ff00",
  "mode": "linked",
  "network": "mainnet"
}

Poll Registration Status

GET /api/agent/register/status?token={sessionToken}

Polls for registration completion. Returns stage: qr-ready, proof-received, completed, or failed.

Example response:

{
  "stage": "completed",
  "agentId": 42,
  "agentAddress": "0x83fa...ff00",
  "txHash": "0xabc...",
  "sessionToken": "enc_..."
}

Get QR Code

GET /api/agent/register/qr?token={sessionToken}

Returns the QR code payload and deep link for the current session.

Self App Callback

POST /api/agent/register/callback?token={sessionToken}

Webhook endpoint called by the Self app after the user scans the QR and submits a passport proof.

Export Agent Private Key

GET /api/agent/register/export?token={sessionToken}

After registration completes, export the agent’s private key. Only available for linked, wallet-free, ed25519, and ed25519-linked modes.

Example response:

{
  "privateKey": "0xdeadbeef...",
  "agentAddress": "0x83fa...ff00",
  "agentId": 42
}

Deregistration Endpoints

Create Deregistration Session

POST /api/agent/deregister

Creates a deregistration session for an existing agent. The human must re-prove identity to burn the agent NFT.

Request body:

{
  "network": "testnet",
  "agentAddress": "0xAgentAddress",
  "disclosures": {
    "minimumAge": 18,
    "ofac": true
  }
}

Poll Deregistration Status

GET /api/agent/deregister/status?token={sessionToken}

Returns current deregistration stage. Once completed, the agent NFT has been burned.

Deregistration Callback

POST /api/agent/deregister/callback?token={sessionToken}

Webhook endpoint for the Self app after the user confirms deregistration.

Demo Endpoints

Used by the live demo page for testing agent verification patterns. All demo endpoints require x-self-agent-* signed headers (produced by SelfAgent.signRequest()).

Verify Agent (Service Pattern)

POST /api/demo/verify

Accepts a signed agent request, verifies signature and on-chain status, returns agent info and credentials.

Agent-to-Agent

POST /api/demo/agent-to-agent

Demo agent endpoint that verifies the caller, checks sameHuman(), and signs its response. Response headers include the demo agent’s own x-self-agent-* signature for mutual verification.

Chain Verify (Meta-Transaction)

POST /api/demo/chain-verify

Relayer endpoint that submits EIP-712 meta-transactions to the AgentDemoVerifier contract. Rate limited to 3 per hour per human nullifier.

Request body:

{
  "agentKey": "0x...",
  "nonce": "0",
  "deadline": 1740001800,
  "eip712Signature": "0x...",
  "networkId": "celo-sepolia"
}

Chain Verify Ed25519 (Meta-Transaction)

POST /api/demo/chain-verify-ed25519

Same as chain-verify but for agents registered with Ed25519 keys. Relays EIP-712 meta-transactions signed with Ed25519.

Census (Aggregated Stats)

POST /api/demo/census  — contribute credentials
GET  /api/demo/census  — read aggregate stats

Demonstrates agent-gated data contribution and reading.

AI Chat

POST /api/demo/chat

AI agent chat endpoint backed by a LangChain agent. Signed requests are verified on-chain; unsigned requests are treated as anonymous.

Request body:

{
  "query": "What is Self Agent ID?",
  "session_id": "user-123"
}

AA Proxy Endpoints

Account-abstraction proxy for the smart-wallet registration mode. These endpoints proxy JSON-RPC calls to a Pimlico bundler/paymaster, shielding the API key from the client. Origin-restricted and rate-limited.

Issue AA Proxy Token

POST /api/aa/token?chainId={chainId}

Issues a short-lived token required by the bundler and paymaster endpoints. Rate limited to 30 requests per minute per IP.

Example response:

{
  "token": "eyJhbGciOi...",
  "expiresAt": 1740001800000
}

Bundler Proxy

POST /api/aa/bundler?chainId={chainId}

Proxies ERC-4337 bundler JSON-RPC calls. Requires the x-aa-proxy-token header from the token endpoint.

Allowed methods: eth_chainId, eth_supportedEntryPoints, eth_estimateUserOperationGas, eth_sendUserOperation, eth_getUserOperationReceipt, eth_getUserOperationByHash, eth_gasPrice, eth_maxPriorityFeePerGas.

Request body (JSON-RPC 2.0):

{
  "jsonrpc": "2.0",
  "method": "eth_sendUserOperation",
  "params": [...],
  "id": 1
}

Paymaster Proxy

POST /api/aa/paymaster?chainId={chainId}

Proxies ERC-4337 paymaster JSON-RPC calls. Requires the x-aa-proxy-token header.

Allowed methods: pm_sponsorUserOperation, pm_getPaymasterData, pm_getPaymasterStubData, eth_chainId.

Authentication

Public endpoints (info, agents, verify, cards, reputation, verify-status, discovery): No authentication required
Demo endpoints: Require x-self-agent-* headers (signed via SDK)
Registration endpoints: Session-based with encrypted tokens, used by dApp/CLI
AA Proxy endpoints: Origin-restricted + x-aa-proxy-token header (from /api/aa/token)

Chain ID Parameter

All endpoints that accept a chainId parameter support:

42220 — Celo Mainnet
11142220 — Celo Sepolia Testnet

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 / missing auth headers
403	Origin check failed or agent verification failed
404	Agent not found on-chain
409	Operation not available at current session stage / replay detected
410	Session expired (30-minute TTL)
413	Request too large (AA proxy, 200 KB limit)
429	Rate limit exceeded
500	Server error — RPC failure or configuration issue
503	Service not configured (bundler, paymaster, or LangChain)