Verified Agent Identity

A decentralized identity management toolkit for AI agents using iden3 protocol on Billions Network.

Overview

This skill enables AI agents to create, manage, link, prove and verify ownership of decentralized identities (DIDs) using cryptographic signatures.

Installation

Agent CTA:

1. Ask bot to install the skill:

   Install with clawhub:

   Install the skill `npx clawhub@latest install verified-agent-identity`
   

   Or install with skills.sh:

   Intall the skill `npx skills add BillionsNetwork/verified-agent-identity`
   

   Or

   Install the `verified-agent-identity` skill from the OpenClaw clawhub.ai.
   

2. (Optional) If the verification process did not start automatically after installation, ask your bot to initialize the process by sending a message like:

   Please link your agent identity to me.
   

Human CTA:

1. Install the skill:

   Use clawhub to install the skill:

   npx clawhub@latest install verified-agent-identity
   

   Use skills.sh to install the skill:

   npx skills add BillionsNetwork/verified-agent-identity
   

2. Create a new identity:

   # Generate a new key and create a new identity
   node scripts/createNewEthereumIdentity.js
   

   Or

   # Use an existing private key to create an identity
   BILLIONS_NETWORK_MASTER_KMS_KEY="<your-strong-secret>" node scripts/createNewEthereumIdentity.js --key <your-ethereum-private-key>
   

   Warning: Only pass a dedicated identity key to --key — never an Ethereum wallet key that holds assets. If the key file is exposed, any key stored here could be used to impersonate the agent or, if reused, to control the associated wallet.

3. Generate a verification link to connect your human identity to the agent:

   node scripts/manualLinkHumanToAgent.js --challenge '{"name": "Agent Name", "description": "Short description of the agent"}'
   

   This prints the verification URL to the console. Open it in your browser to complete the identity linking process.

Features

• Identity Creation: Generate new DIDs with random or existing Ethereum private keys
• Identity Management: List and manage multiple identities with default identity support
• Human-Agent Linking: Link a human identity to an agent's DID through signed challenges
• Proof Generation: Generate cryptographic proofs to authenticate as a specific identity
• Proof Verification: Verify proofs to confirm identity ownership

Architecture

Runtime Requirements

• Node.js >= v20 and npm are required to run the scripts.

Dependency Surface

npm dependencies are intentionally minimal and scoped to well-established, audited packages:

Core libraries governing identity management use pinned, well-tested versions to ensure stability and security.

Key Storage and Isolation

All cryptographic material is persisted to $HOME/.openclaw/billions/ — a directory that lives outside the agent's workspace:

After the first run, restrict access to this directory: chmod 700 ~/.openclaw/billions

There are several ways of storing private keys, to enable master key encryption as described in the KMS Encryption section below.

KMS Encryption

See SECURITY.md for the full threat model, the rationale for shipping a plaintext storage mode, and the operator hardening checklist.

Set the environment variable BILLIONS_NETWORK_MASTER_KMS_KEY to enable AES-256-GCM at-rest encryption for the private keys inside kms.json. When set, every key value is individually encrypted on write; when absent, keys are stored as plain hex strings.

kms.json entry format

Each entry in the array is versioned. The alias is always stored in plaintext — only the key value is encrypted:

[
  {
    "version": 1,
    "provider": "plain",
    "data": {
      "alias": "secp256k1:abc123",
      "key": "deadbeef...",
      "createdAt": "2026-03-12T13:46:04.094Z"
    }
  },
  {
    "version": 1,
    "provider": "encrypted",
    "data": {
      "alias": "secp256k1:xyz456",
      "key": "<iv_hex>:<authTag_hex>:<ciphertext_hex>",
      "createdAt": "2026-02-11T13:00:02.032Z"
    }
  }
]

Behavior summary

Backward compatibility — the legacy format [ { "alias": "...", "privateKeyHex": "..." } ] is still read correctly. On the first write the file is automatically migrated to the new per-entry format. No manual step is required.

How to set the variable

Option 1 — openclaw skill config (recommended for agent deployments):

Add an env block for the skill inside your openclaw config:

"skills": {
  "entries": {
    "verified-agent-identity": {
      "env": {
        "BILLIONS_NETWORK_MASTER_KMS_KEY": "<your-strong-secret>"
      }
    }
  }
}

Option 2 — shell or process environment:

export BILLIONS_NETWORK_MASTER_KMS_KEY="<your-strong-secret>"
node scripts/createNewEthereumIdentity.js
node scripts/manualLinkHumanToAgent.js --challenge '{"name": "Agent Name", "description": "Short description of the agent"}'

For all other ways to pass environment variables to a skill see the OpenClaw environment documentation.

CRITICAL: Save master keys securely and do not share them. If the master key is lost, all encrypted keys will be lost.

Network and External Binary Policy

• All external https calls will be made to trusted resources. Signed JWS attestation (proof of agent ownership) is encoded securely by utilizing robust security practices. It requires an explicit user consent to pass it to any other source.
• All network calls are directed to legitimate DID resolvers (resolver.privado.id) or the project's own infrastructure (billions.network). These network calls cannot exfiltrate signed attestations or identity data to other third-party services by skill design. Wallet interaction is possible only through explicit action from the user side with consent. Also attestation contains only publicly verifiable information.
• Whitelisted domains:
  • resolver.privado.id (DID resolution)
  • billions.network (Billions Network interactions)
  • polygonid.me (Polygon ID interactions)

Documentation

See SKILL.md for detailed usage instructions and examples.