Know Your Agent (KYA). Billions decentralized identity for agents. Link agents to human identities using Billions ERC-8004 and Attestation Registries. Verify...
---
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`
don't have the plugin yet? install it then click "run inline in claude" again.