Registration modes

# Registration modes Every mode produces the same on-chain result: a soulbound agent NFT backed by a human proof. The modes differ in who holds the agent key and who owns the NFT. Pass the mode to `requestRegistration({ mode })`, `POST /api/agent/register` or the A2A `register` intent. ## Mode comparison | Mode | Agent key | NFT owner | Human address | | ---------------- | ---------------------------------------------------------------- | ------------------------------- | ------------- | | `linked` | Server-generated EVM key (you export it) | Human's wallet | Required | | `wallet-free` | Server-generated EVM key (you export it) | The agent's own address | Not used | | `privy` | Same as `linked` | Human's Privy embedded wallet | Required | | `smartwallet` | Same as `linked` | Human's passkey smart wallet | Required | | `ed25519` | The agent's own Ed25519 key | Address derived from the pubkey | Not used | | `ed25519-linked` | The agent's own Ed25519 key, with the human's wallet as guardian | Address derived from the pubkey | Required | The API also accepts the aliases `walletfree` and `smart-wallet`. The SDK, REST API and A2A support all six modes; the [CLI](/docs/agent-id/cli/) supports `linked` and `wallet-free`. ## Which mode? - **The agent already has an Ed25519 key** (OpenClaw, ElizaOS, and similar): `ed25519`, or `ed25519-linked` if a human wallet should be able to revoke it. - **The human has a wallet**: `linked`. Use `privy` or `smartwallet` when that wallet is a Privy embedded wallet or a passkey smart wallet. - **No wallet at all**: `wallet-free`, the quickest start. ## Linked The server generates a dedicated EVM key for the agent, and the human's wallet (`humanAddress`) owns the agent NFT. The human's wallet key is never shared with the agent. After the scan, [export](/docs/agent-id/rest-api/#export-the-agent-key) the agent key within 30 minutes. Use it for autonomous agents that need their own key while a human wallet keeps ownership. ## Wallet-free Like `linked`, but the agent's own address owns its NFT, so the human needs no wallet. The agent key can manage its own metadata (for example with `setAgentCard`). To remove the agent, the human scans again to deregister. :::note Store the exported key securely. If it is lost, deregister with a passport scan and register a new agent. ::: ## Privy and smart wallet `privy` and `smartwallet` behave exactly like `linked` on the server: send the human's Privy embedded wallet or passkey smart wallet address as `humanAddress`, and that wallet owns the NFT. Wallet creation and login happen in your own frontend. ## Ed25519 For agents that already sign with Ed25519. The agent keeps its key, so there is nothing to export. 1. `POST /api/agent/register/ed25519-challenge` with the 64-hex `pubkey` and `network` returns `challengeHash`. 2. The agent signs the 32 raw bytes of `challengeHash` with its Ed25519 key. 3. Register with `ed25519Pubkey` and the 128-hex `ed25519Signature`, and the human scans the QR code. The NFT is minted to an address derived from the public key (`Ed25519Agent.deriveAddress(pubkey)`). Full example: [Ed25519 challenge](/docs/agent-id/rest-api/#ed25519-challenge). ## Ed25519-linked `ed25519` plus a guardian: send the human's wallet as `humanAddress` to both the challenge and the register call. The guardian can revoke the agent on-chain at any time with `guardianRevoke(agentId)`. :::note Ed25519 agents are revoked on-chain, not with a deregistration scan: the guardian calls `guardianRevoke(agentId)`, or the NFT owner calls `selfDeregister(agentId)`. ::: ## Verification configs `disclosures.minimumAge` (`0`, `18` or `21`) and `disclosures.ofac` select one of six on-chain verification configs. The response's `configIndex` tells you which one. | Config index | Minimum age | OFAC screening | | ------------ | ----------- | -------------- | | 0 | None | Off | | 1 | 18 | Off | | 2 | 21 | Off | | 3 | None | On | | 4 | 18 | On | | 5 | 21 | On | Use the same disclosures when you deregister or refresh the agent. ## Disclosed credentials The human can also disclose `nationality`, `name`, `date_of_birth`, `gender` and `issuing_state` (each a JSON boolean in `disclosures`). Disclosed values are stored on-chain as ZK-attested credentials and returned by [`getCredentials()`](/docs/agent-id/sdk-integration/) and [`/api/agent/info`](/docs/agent-id/rest-api/#agent-info). Every disclosure is optional, and raw passport data never leaves the phone.

On this page

Mode comparison
Which mode?
Linked
Wallet-free
Privy and smart wallet
Ed25519
Ed25519-linked
Verification configs
Disclosed credentials

Every mode produces the same on-chain result: a soulbound agent NFT backed by a human proof. The modes differ in who holds the agent key and who owns the NFT. Pass the mode to requestRegistration({ mode }), POST /api/agent/register or the A2A register intent.

Mode comparison

Mode	Agent key	NFT owner	Human address
`linked`	Server-generated EVM key (you export it)	Human’s wallet	Required
`wallet-free`	Server-generated EVM key (you export it)	The agent’s own address	Not used
`privy`	Same as `linked`	Human’s Privy embedded wallet	Required
`smartwallet`	Same as `linked`	Human’s passkey smart wallet	Required
`ed25519`	The agent’s own Ed25519 key	Address derived from the pubkey	Not used
`ed25519-linked`	The agent’s own Ed25519 key, with the human’s wallet as guardian	Address derived from the pubkey	Required

The API also accepts the aliases walletfree and smart-wallet. The SDK, REST API and A2A support all six modes; the CLI supports linked and wallet-free.

Which mode?

The agent already has an Ed25519 key (OpenClaw, ElizaOS, and similar): ed25519, or ed25519-linked if a human wallet should be able to revoke it.
The human has a wallet: linked. Use privy or smartwallet when that wallet is a Privy embedded wallet or a passkey smart wallet.
No wallet at all: wallet-free, the quickest start.

Linked

The server generates a dedicated EVM key for the agent, and the human’s wallet (humanAddress) owns the agent NFT. The human’s wallet key is never shared with the agent. After the scan, export the agent key within 30 minutes.

Use it for autonomous agents that need their own key while a human wallet keeps ownership.

Wallet-free

Like linked, but the agent’s own address owns its NFT, so the human needs no wallet. The agent key can manage its own metadata (for example with setAgentCard). To remove the agent, the human scans again to deregister.

Privy and smart wallet

privy and smartwallet behave exactly like linked on the server: send the human’s Privy embedded wallet or passkey smart wallet address as humanAddress, and that wallet owns the NFT. Wallet creation and login happen in your own frontend.

Ed25519

For agents that already sign with Ed25519. The agent keeps its key, so there is nothing to export.

POST /api/agent/register/ed25519-challenge with the 64-hex pubkey and network returns challengeHash.
The agent signs the 32 raw bytes of challengeHash with its Ed25519 key.
Register with ed25519Pubkey and the 128-hex ed25519Signature, and the human scans the QR code.

The NFT is minted to an address derived from the public key (Ed25519Agent.deriveAddress(pubkey)). Full example: Ed25519 challenge.

Ed25519-linked

ed25519 plus a guardian: send the human’s wallet as humanAddress to both the challenge and the register call. The guardian can revoke the agent on-chain at any time with guardianRevoke(agentId).

Verification configs

disclosures.minimumAge (0, 18 or 21) and disclosures.ofac select one of six on-chain verification configs. The response’s configIndex tells you which one.

Config index	Minimum age	OFAC screening
0	None	Off
1	18	Off
2	21	Off
3	None	On
4	18	On
5	21	On

Use the same disclosures when you deregister or refresh the agent.

Disclosed credentials

The human can also disclose nationality, name, date_of_birth, gender and issuing_state (each a JSON boolean in disclosures). Disclosed values are stored on-chain as ZK-attested credentials and returned by getCredentials() and /api/agent/info. Every disclosure is optional, and raw passport data never leaves the phone.

Was this page helpful?