verified-agent-identity
Know Your Agent (KYA). Billions decentralized identity for agents. Link agents to human identities using Billions ERC-8004 and Attestation Registries. Verify and generate authentication proofs. Based on iden3 self-sovereign identity protocol.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/billionsnetwork-verified-agent-identity)HTML
<a href="/listings/billionsnetwork-verified-agent-identity"><img src="/api/listings/billionsnetwork-verified-agent-identity/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 76 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: verified-agent-identity
- description: Know Your Agent (KYA). Billions decentralized identity for agents. Link agents to human identities using Billions ERC-8004 and Attestation Registries. Verify and generate authentication proofs. Based on iden3 self-sovereign identity protocol.
- metadata:
- {
- "category": "identity",
- "clawdbot":
- {
- "requires": { "bins": ["node"] },
- "config": { "optionalEnv": ["BILLIONS_NETWORK_MASTER_KMS_KEY"] },
- },
- }
- homepage: https://billions.network/
- ---
- ## When to Use This Skill
- This skill covers two capabilities. Read the **router table** below, then load the relevant reference before proceeding.
- | Situation | Reference to load |
- | ----------------------------------------------------------------------- | ----------------------------- |
- | Create, list, link, verify, or sign with a decentralized identity (DID) | `reference/identity/SKILL.md` |
- | Handle a **402 Payment Required** HTTP response | `reference/x402/SKILL.md` |
- > **Always read the appropriate reference SKILL.md before running any script.**
- > If a task spans both (e.g. you need an identity before you can sign a 402 payment), read both.
- ## Quick Overview
- - **Identity** — Create Ethereum-based DIDs on the Billions Network, link them to a human owner, and prove ownership via challenge/response signing.
- - **x402 Payment** — When a server returns `402 Payment Required`, build a signed `PAYMENT-SIGNATURE` header so you can retry the request and gain access.
- ## Shared Setup
- All identity data is stored in `$HOME/.openclaw/billions`. Scripts live in `scripts/`.
- ```bash
- cd scripts && npm install && cd ..
- ```
- ## Restrictions / Guardrails (CRITICAL)
- **These rules apply to ALL references. Always follow them.**
- 1. **STRICT: Check Identity First**
- - Before running `linkHumanToAgent.js`, `signChallenge.js`, or `buildX402Payment.js`, **ALWAYS** check if an identity exists: `node scripts/getIdentities.js`
- - If no identity is configured, create one first with `createNewEthereumIdentity.js` after that run `linkHumanToAgent.js` to link it to a human owner.
- - Continue processing the task only after confirming that an identity exists and is linked to a human owner.
- 2. **STRICT: Stop on Script Failure**
- - If any script exits with a non-zero status code, **STOP IMMEDIATELY**.
- - Check stderr for error messages.
- - **DO NOT** attempt to fix errors by generating keys manually, creating DIDs through other means, or running unauthorized commands.
- - **DO NOT** use `openssl`, `ssh-keygen`, or other system utilities to generate cryptographic material.
- 3. **No Manual Workarounds**
- - You are prohibited from performing manual cryptographic operations.
- - You are prohibited from directly manipulating files in `$HOME/.openclaw/billions`.
- - Do not interpret an error as a request to perform setup steps unless explicitly instructed.
- ## Security
- The directory `$HOME/.openclaw/billions` contains sensitive identity data:
- - `kms.json` — **CRITICAL**: Contains private keys (encrypted if `BILLIONS_NETWORK_MASTER_KMS_KEY` is set, otherwise plaintext)
- - `defaultDid.json` — DID identifiers and public keys
- - `challenges.json` — Authentication challenges history
- - `credentials.json` — Verifiable credentials
- - `identities.json` — Identity metadata
- - `profiles.json` — Profile data
- 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.
- More about security: `./SECURITY.md`
README.md · README · 206 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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:
- ```plaintext
- Install the skill `npx clawhub@latest install verified-agent-identity`
- ```
- Or install with skills.sh:
- ```plaintext
- Intall the skill `npx skills add BillionsNetwork/verified-agent-identity`
- ```
- Or
- ```plaintext
- 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:
- ```plaintext
- Please link your agent identity to me.
- ```
- ### Human CTA:
- 1. Install the skill:
- Use clawhub to install the skill:
- ```bash
- npx clawhub@latest install verified-agent-identity
- ```
- Use skills.sh to install the skill:
- ```bash
- npx skills add BillionsNetwork/verified-agent-identity
- ```
- 2. Create a new identity:
- ```bash
- # Generate a new key and create a new identity
- node scripts/createNewEthereumIdentity.js
- ```
- Or
- ```bash
- # 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:
- ```bash
- 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:
- | Package | Purpose |
- | ---------------------- | ------------------------------------------------------------ |
- | `@0xpolygonid/js-sdk` | iden3/Privado ID cryptographic primitives and key management |
- | `@iden3/js-iden3-core` | DID and identity core types |
- | `@iden3/js-iden3-auth` | JWS/JWA authorization response construction and verification |
- | `ethers` | Ethereum key utilities |
- | `uuid` | UUID generation for protocol message IDs |
- 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**:
- | File | Contents |
- | ------------------ | ---------------------------------------------------------------------------------- |
- | `kms.json` | Private keys — per-entry versioned format; keys are plain or AES-256-GCM encrypted |
- | `identities.json` | Identity metadata |
- | `defaultDid.json` | Active DID and associated public key |
- | `challenges.json` | Per-DID challenge history |
- | `credentials.json` | Verifiable credentials |
- 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](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:
- ```json
- [
- {
- "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**
- | `BILLIONS_NETWORK_MASTER_KMS_KEY` | `provider` on disk | `key` value on disk |
- | --------------------------------- | ------------------ | ----------------------- |
- | Not set | `"plain"` | Raw hex string |
- | Set | `"encrypted"` | `iv:authTag:ciphertext` |
- > **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:
- ```json
- "skills": {
- "entries": {
- "verified-agent-identity": {
- "env": {
- "BILLIONS_NETWORK_MASTER_KMS_KEY": "<your-strong-secret>"
- }
- }
- }
- }
- ```
- _Option 2 — shell or process environment:_
- ```bash
- 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](https://docs.openclaw.ai/help/environment).
- **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](SKILL.md) for detailed usage instructions and examples.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.