From 05f7a71f266f1a5592e28ee54e3653de38c71c7e Mon Sep 17 00:00:00 2001 From: Kartik Mehta Date: Wed, 10 Jun 2026 16:34:40 +0530 Subject: [PATCH] docs(agent-id): migrate API references to agent-api.self.xyz; retire consumer UI The Agent ID hosted web app is being retired and the API moved to a dedicated host. Update the docs to match while keeping every feature: - Point REST, A2A, CLI, visa, and AA proxy references at https://agent-api.self.xyz (was selfagentid.xyz). - Replace the retired dApp wizard with an SDK-first registration page (Register Without the Web App): render the QR client-side, mint on-chain, sign, and verify, with no hosted service required. - Note CLI/REST as alternatives that return the QR for you to display, and that the CLI fetches the QR from /api/qr. - mcp-user: SELF_AGENT_API_BASE default updated. No features dropped; on-chain registration and verification unchanged. Co-Authored-By: Claude Opus 4.8 --- SUMMARY.md | 1 + agent-id/celo-agent-visa.md | 2 +- agent-id/cli.md | 6 +- agent-id/guides/agent-builder.md | 36 ++----- agent-id/guides/mcp-user.md | 2 +- agent-id/overview.md | 14 ++- agent-id/register-without-the-app.md | 148 +++++++++++++++++++++++++++ agent-id/rest-api.md | 8 +- 8 files changed, 179 insertions(+), 38 deletions(-) create mode 100644 agent-id/register-without-the-app.md diff --git a/SUMMARY.md b/SUMMARY.md index 881e4d9..e7e708b 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -67,6 +67,7 @@ ## Self Agent ID * [Overview](agent-id/overview.md) +* [Register Without the Web App](agent-id/register-without-the-app.md) * [Registration Modes](agent-id/registration-modes.md) * [SDK Integration](agent-id/sdk-integration.md) * [Verification Patterns](agent-id/verification-patterns.md) diff --git a/agent-id/celo-agent-visa.md b/agent-id/celo-agent-visa.md index 9ef5781..5d0d709 100644 --- a/agent-id/celo-agent-visa.md +++ b/agent-id/celo-agent-visa.md @@ -37,7 +37,7 @@ The contract is a soulbound ERC-721 (non-transferable) using UUPS upgradeable pa ## API Endpoints -All visa endpoints are served from the Self Agent ID web app. +All visa endpoints are served at `https://agent-api.self.xyz`. The read endpoints are wrappers over `CeloAgentVisa` contract reads, so you can also call the contract directly; the claim and review endpoints use a relayer. ### Get Visa Status diff --git a/agent-id/cli.md b/agent-id/cli.md index 3e23039..1c5620c 100644 --- a/agent-id/cli.md +++ b/agent-id/cli.md @@ -6,6 +6,10 @@ description: Terminal-based agent registration and deregistration workflows Self Agent ID includes a cross-language CLI for registering and deregistering agents from the terminal. Available in TypeScript, Python, and Rust with identical command surfaces. +{% hint style="info" %} +The CLI talks to the API at `https://agent-api.self.xyz`. Override it with the `SELF_AGENT_API_BASE` environment variable if you run your own deployment. The CLI fetches the scannable QR from the API (`GET /api/qr/{sessionToken}`), so no consumer web app is needed. +{% endhint %} + ## Install {% tabs %} @@ -166,7 +170,7 @@ The session file (`.self/session.json`) contains: "agentAddress": "0x...", "agentPrivateKey": "0x...", "sessionId": "uuid", - "handoffUrl": "https://selfagentid.xyz/cli/register?session=...", + "handoffUrl": "https://agent-api.self.xyz/qr/...", "status": "pending", "createdAt": "2026-02-22T..." } diff --git a/agent-id/guides/agent-builder.md b/agent-id/guides/agent-builder.md index a31de6c..bd2cf92 100644 --- a/agent-id/guides/agent-builder.md +++ b/agent-id/guides/agent-builder.md @@ -29,27 +29,9 @@ Six registration modes — choose based on your use case: | `privy` | Social login (Google, Twitter) | No | | `smartwallet` | Consumer-facing, passkey UX | No | -### Via the dApp (simplest) +### Via the SDK (simplest) -1. Go to [selfagentid.xyz](https://selfagentid.xyz) -2. Select your registration mode and network -3. Scan your passport with the Self app -4. Copy the agent private key from the export page - -#### What your user will see - -The dApp walks users through a guided wizard: - -1. **Role selection** — "I'm building an agent" or "I'm a human registering for my agent" -2. **Key type** — ECDSA or Ed25519, with framework-specific hints (e.g. OpenClaw and Eliza use Ed25519) -3. **Mode selection** — The wizard narrows the six modes to the ones that match the chosen key type, with a comparison table showing wallet requirements, NFT ownership, and revocation methods -4. **Network** — Mainnet (real passport) or Testnet (mock documents) -5. **Verification config** — Optional age threshold and OFAC screening -6. **Key generation / import** — For ECDSA modes, a fresh keypair is generated in the browser. For Ed25519 modes, the user pastes the agent's existing public key -7. **Passport scan** — A QR code or deep link opens the Self app for ZK proof-of-human verification -8. **Confirmation** — On-chain registration completes and the agent key is available for export - -The entire flow takes under two minutes. No crypto knowledge is required for wallet-free, privy, or smartwallet modes. +Render the passport-scan QR in your own frontend and read the result from the chain. No hosted service is involved. This is the recommended path. See [Register Without the Web App](../register-without-the-app.md) for the full runnable example (generate the agent key, sign the challenge, build the QR with `@selfxyz/qrcode`, mint on-chain). ### Via CLI @@ -65,7 +47,7 @@ self-agent register init \ --minimum-age 18 \ --ofac -# Open the browser handoff URL +# Print the QR (fetched from the API) to scan with the Self app self-agent register open --session .self/session-*.json # Wait for verification to complete @@ -75,12 +57,14 @@ self-agent register wait --session .self/session-*.json self-agent register export --session .self/session-*.json --unsafe --print-private-key ``` +The CLI talks to `https://agent-api.self.xyz` by default (override with `SELF_AGENT_API_BASE`). + ### Via A2A Protocol (for agents) Agents can self-register by sending a JSON-RPC request to the A2A endpoint: ```bash -curl -X POST https://selfagentid.xyz/api/a2a \ +curl -X POST https://agent-api.self.xyz/api/a2a \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", @@ -100,7 +84,7 @@ The endpoint returns a QR code and deep link. A human scans the QR with the Self ### Via REST API ```bash -curl -X POST https://selfagentid.xyz/api/agent/register \ +curl -X POST https://agent-api.self.xyz/api/agent/register \ -H "Content-Type: application/json" \ -d '{ "mode": "linked", @@ -114,11 +98,7 @@ Poll `/api/agent/register/status?token=` until `stage: "completed"`. ### Via Smart Wallet (passkeys) -1. Go to [selfagentid.xyz](https://selfagentid.xyz) -2. Select "Smart Wallet" mode -3. Create a passkey — this generates a ZeroDev Kernel smart account as your guardian -4. Scan your passport with the Self app -5. On mainnet, transactions are gasless via Pimlico paymaster +Smart-wallet mode uses a passkey to create a ZeroDev Kernel smart account as the guardian, with gasless operations via the Pimlico paymaster on mainnet. Build the passkey step into your own frontend with `@zerodev/sdk` and `@zerodev/passkey-validator`; the agent keypair and challenge are generated the same way as `linked`. The gasless bundler and paymaster are proxied through `https://agent-api.self.xyz/api/aa/*`. See [Registration Modes](../registration-modes.md#smart-wallet). ## 3. Sign Outbound Requests diff --git a/agent-id/guides/mcp-user.md b/agent-id/guides/mcp-user.md index ba1cceb..5edb591 100644 --- a/agent-id/guides/mcp-user.md +++ b/agent-id/guides/mcp-user.md @@ -60,7 +60,7 @@ Add to your MCP configuration file: | `SELF_AGENT_PRIVATE_KEY` | No | — | Agent private key (hex). Enables identity and auth tools. | | `SELF_NETWORK` | No | `mainnet` | `mainnet` or `testnet` | | `SELF_RPC_URL` | No | Network default | Custom RPC endpoint | -| `SELF_API_URL` | No | `https://selfagentid.xyz` | Custom API base URL | +| `SELF_AGENT_API_BASE` | No | `https://agent-api.self.xyz` | API base URL. Override to use your own deployment. | {% hint style="info" %} **Mainnet is the default.** Registration on mainnet requires a real passport via the Self app. Use `SELF_NETWORK=testnet` for development — testnet also requires the Self app, but you can generate mock documents within the app instead of using a real passport. diff --git a/agent-id/overview.md b/agent-id/overview.md index d3d974a..c90d82a 100644 --- a/agent-id/overview.md +++ b/agent-id/overview.md @@ -8,6 +8,10 @@ Self Agent ID is an on-chain identity registry that binds AI agent identities to The system implements the [ERC-8004 Proof-of-Human extension](https://eips.ethereum.org/EIPS/eip-8004) and provides SDK implementations in TypeScript, Python, and Rust with identical feature parity. +{% hint style="info" %} +There is no consumer website. You use Agent ID through the SDK, the on-chain registry, the REST/A2A API at `https://agent-api.self.xyz`, or the `self-agent` CLI. See [Register Without the Web App](register-without-the-app.md) to register, sign, and verify an agent. +{% endhint %} + ## Who This Is For | Audience | What You Do | @@ -51,14 +55,16 @@ No personal data ever leaves the user's device. Only a ZK proof and nullifier ar Celo Sepolia chain ID is **11142220**, not 44787 (deprecated Alfajores). {% endhint %} -## Live Deployment +## Where It Lives -- Web app: [https://selfagentid.xyz](https://selfagentid.xyz) -- GitHub: [https://github.com/selfxyz/self-agent-id](https://github.com/selfxyz/self-agent-id) +- API (REST + A2A): `https://agent-api.self.xyz` +- Contracts: on Celo (addresses above) +- SDKs: `@selfxyz/agent-sdk` (TypeScript), `selfxyz-agent-sdk` (Python), `self-agent-sdk` (Rust) +- Source: [github.com/selfxyz/self-agent-id](https://github.com/selfxyz/self-agent-id) ## A2A Protocol -Agents can interact programmatically via the A2A JSON-RPC endpoint at `/api/a2a`. This supports registration, verification, lookup, deregistration, and proof freshness checks — all through structured intents or natural language. +Agents can interact programmatically via the A2A JSON-RPC endpoint at `https://agent-api.self.xyz/api/a2a`. This supports registration, verification, lookup, deregistration, and proof freshness checks — all through structured intents or natural language. Send `{ "intent": "help" }` to get a full list of capabilities and a decision guide for choosing the right registration mode. diff --git a/agent-id/register-without-the-app.md b/agent-id/register-without-the-app.md new file mode 100644 index 0000000..1e38213 --- /dev/null +++ b/agent-id/register-without-the-app.md @@ -0,0 +1,148 @@ +--- +description: Register, sign, and verify an agent using only the SDK and the on-chain registry, with no website +--- + +# Register Without the Web App + +There is no consumer website for Self Agent ID. You render the passport-scan QR in your own app, the Self mobile app submits the proof on-chain, and the registry mints the agent. Signing and verification are on-chain too. + +This page shows the full loop with the SDK: register, sign, verify. It needs no hosted service at all. If you prefer, you can also register through the [CLI](cli.md) or the [REST/A2A API](rest-api.md) at `https://agent-api.self.xyz`, which return the QR for you to display. + +## What you need + +- `npm install @selfxyz/agent-sdk @selfxyz/qrcode ethers` +- The Self mobile app on a phone. On testnet you can generate mock documents in the app, so no real passport is needed. +- A Celo RPC. Public defaults: `https://forno.celo.org` (mainnet), `https://forno.celo-sepolia.celo-testnet.org` (testnet). + +| Network | Chain ID | Registry | +|---------|----------|----------| +| Celo Mainnet | `42220` | `0xaC3DF9ABf80d0F5c020C06B04Cced27763355944` | +| Celo Sepolia (testnet) | `11142220` | `0x043DaCac8b0771DD5b444bCC88f2f8BBDBEdd379` | + +## 1. Register an agent + +Render the QR in your own frontend. The proof goes from the Self app to the on-chain Hub, which mints the agent NFT into the registry. No backend is involved. + +```tsx +import { useEffect, useState } from 'react'; +import { SelfAppBuilder, SelfQRcodeWrapper } from '@selfxyz/qrcode'; +import { signRegistrationChallenge, buildAdvancedRegisterUserDataAscii } from '@selfxyz/agent-sdk'; +import { Wallet } from 'ethers'; + +const REGISTRY = '0xaC3DF9ABf80d0F5c020C06B04Cced27763355944'; // Celo mainnet + +export function RegisterAgent({ humanAddress }: { humanAddress: string }) { + const [selfApp, setSelfApp] = useState(null); + const [agentKey] = useState(() => Wallet.createRandom()); + + useEffect(() => { + (async () => { + // The agent key signs a challenge proving it controls the key + const sig = await signRegistrationChallenge(agentKey.privateKey, { + humanIdentifier: humanAddress, + chainId: 42220, + registryAddress: REGISTRY, + nonce: 0, + }); + + // Encode the registration payload (config index is derived from disclosures) + const disclosures = { minimumAge: 18, ofac: true }; + const userDefinedData = buildAdvancedRegisterUserDataAscii({ + agentAddress: agentKey.address, + signature: sig, + disclosures, + }); + + // Build the Self verification request; the registry is the on-chain endpoint + setSelfApp( + new SelfAppBuilder({ + version: 2, + appName: 'My Agent', + scope: 'self-agent-id', + endpoint: REGISTRY, + endpointType: 'celo', // 'staging_celo' for testnet + userId: humanAddress, + userIdType: 'hex', + userDefinedData, + disclosures, + }).build(), + ); + })(); + }, [humanAddress]); + + return selfApp ? ( + { + // Minted. Save agentKey.privateKey securely — it is the agent's key. + }} + onError={() => console.error('verification failed')} + /> + ) : ( +

Loading…

+ ); +} +``` + +The user scans the QR with the Self app. On `onSuccess` the agent NFT is minted. **Save the agent private key.** This example uses `linked` mode; for other modes (wallet-free, Ed25519, etc.) see [Registration Modes](registration-modes.md). + +{% hint style="info" %} +For a headless flow, use `getUniversalLink(selfApp)` from `@selfxyz/qrcode` to produce the deep link instead of the React component, and read the new agent from the registry with `getAgentId` / `isVerifiedAgent`. +{% endhint %} + +## 2. Publish the agent's identity document (optional but recommended) + +Agents minted this way start with a blank `agentURI`. Publish a JSON document so services and indexers can discover the agent, then point the agent at it. + +```typescript +import { generateRegistrationJSON } from '@selfxyz/agent-sdk'; + +const doc = generateRegistrationJSON({ + name: 'My Agent', + description: 'A human-backed AI agent', + image: 'https://my-agent.example.com/avatar.png', + services: [{ name: 'A2A', endpoint: 'https://my-agent.example.com/a2a', version: '1.0' }], +}); +// Host doc over HTTPS, then call registry.setAgentURI(agentId, url) +``` + +## 3. Sign requests as the agent + +```typescript +import { SelfAgent } from '@selfxyz/agent-sdk'; + +const agent = new SelfAgent({ + privateKey: process.env.AGENT_PRIVATE_KEY!, + registryAddress: '0xaC3DF9ABf80d0F5c020C06B04Cced27763355944', + rpcUrl: 'https://forno.celo.org', +}); + +const res = await agent.fetch('https://some-service.example.com/api/protected', { + method: 'POST', + body: JSON.stringify({ hello: 'world' }), +}); +``` + +## 4. Verify the agent in a service + +The verifier recovers the signer and checks the registry on-chain. No API, no shared secret. + +```typescript +import { SelfAgentVerifier } from '@selfxyz/agent-sdk'; + +const verifier = new SelfAgentVerifier({ + registryAddress: '0xaC3DF9ABf80d0F5c020C06B04Cced27763355944', + rpcUrl: 'https://forno.celo.org', +}); + +app.use('/api', verifier.auth()); // rejects requests from unverified agents +``` + +That is the whole product: register on-chain, sign, verify on-chain. Nothing here depends on a hosted Self website. + +## Next steps + +- [Registration Modes](registration-modes.md) — pick the key type and ownership model +- [SDK Integration](sdk-integration.md) — signing and verification in TypeScript, Python, and Rust +- [Verification Patterns](verification-patterns.md) — `sameHuman`, proof freshness, policy controls +- [Smart Contracts](smart-contracts.md) — gate a contract on verified agents diff --git a/agent-id/rest-api.md b/agent-id/rest-api.md index 24eaecf..ffbbbc4 100644 --- a/agent-id/rest-api.md +++ b/agent-id/rest-api.md @@ -4,11 +4,13 @@ description: REST API endpoints for agent registration, queries, and discovery # 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. +Self Agent ID exposes REST endpoints for registration workflows, agent queries, and A2A discovery. The base URL is `https://agent-api.self.xyz`. There is no consumer web app, but the full API stays available at this host. Prefix the paths below with the base URL. 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). +{% hint style="info" %} +Most query endpoints are thin wrappers over registry contract reads, so you can also reproduce them directly with the SDK or a plain RPC call. See [Smart Contracts](smart-contracts.md). To register without calling the API at all, render the QR in your own frontend with the SDK — see [Register Without the Web App](register-without-the-app.md). +{% endhint %} ## Public Query Endpoints @@ -178,7 +180,7 @@ Returns the service discovery document with API base URL, supported networks, re { "name": "Self Agent ID", "version": "1.0", - "apiBase": "https://selfagentid.xyz/api/agent", + "apiBase": "https://agent-api.self.xyz/api/agent", "networks": ["mainnet", "testnet"], "registrationModes": ["linked", "wallet-free", "ed25519", "ed25519-linked", "privy", "smartwallet"], "capabilities": ["register", "deregister", "verify", "credentials", "agent-card", "a2a"],