POST /api/v1/register

Register a new agent identity.

Base URL: https://provenonce.io

Registration is free and DB-only. For on-chain identity, purchase a SIGIL.

No-wallet registration (default, single-phase)

The simplest path - identity only, no economic layer.

curl -X POST https://provenonce.io/api/v1/register \
  -H "Content-Type: application/json" \
  -H "x-registration-secret: YOUR_SECRET" \
  -d '{
    "name": "my-agent",
    "metadata": {
      "version": "1.0",
      "purpose": "data-pipeline",
      "framework": "langchain"
    }
  }'

Response

{
  "ok": true,
  "hash": "0xfd75...",
  "api_key": "pvn_eyJo...",
  "secret": "abc123...",
  "type": "root",
  "parent": null,
  "depth": 0,
  "name": "my-agent",
  "metadata": { "version": "1.0", "purpose": "data-pipeline", "framework": "langchain" },
  "wallet_model": "self-custody",
  "wallet_chain": null,
  "birth_tx": "BmcxxSCk..."
}

Optional metadata

You can attach freeform metadata at registration. This is stored with the agent record and returned in /verify and /status responses.

Metadata is set once at registration. To update structured metadata fields (substrate, capability, tools, etc.), purchase a SIGIL and use PATCH /agent/metadata.

Operator wallet - Model B (two-phase)

Phase 1: same as above but add "wallet_model": "operator". Phase 2: sign provenonce-register-operator:<nonce>:<address>:<name> and send operator_wallet_address + wallet_signature.

Ethereum wallet (two-phase)

Phase 1: send "action": "challenge" with "wallet_chain": "ethereum". Phase 2: sign provenonce-register-ethereum:<nonce>:<address>:<name> using EIP-191 personal_sign and send wallet_chain, wallet_address, wallet_signature, wallet_nonce.

Child registration (single-phase)

curl -X POST https://provenonce.io/api/v1/register \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pvn_PARENT_KEY..." \
  -d '{"name": "child-agent", "parent": "0xPARENT_HASH...", "spawn_authorization": "SPAWN_TOKEN_FROM_PARENT"}'

Children inherit their parent’s lineage. No wallet is assigned to children. spawn_authorization is required and must be minted by the parent via POST /api/v1/agent/spawn preflight.

Supported chains

Headers

Rate limits

• No-wallet registration + child registration: 10/hour per IP
• Wallet challenge/register flow: 30/hour per IP