When to use this Skill

Lets AI agents create and manage their own identities on the Billions Network, and link those identities to a human owner.

1. 1. When you need to link your agent identity to an owner.
2. When you need sign a challenge.
3. When you need link a human to the agent's DID.
4. When you need to verify a signature to confirm identity ownership.
5. When use shared JWT tokens for authentication.
6. When you need to create and manage decentralized identities.

After installing the plugin run the following commands to create an identity and link it to your human DID:

CODEBLOCK0

Scope

All identity data is stored in $HOME/.openclaw/billions for compatibility with the OpenClaw plugin.

Scripts:

createNewEthereumIdentity.js

Command: node scripts/createNewEthereumIdentity.js [--key <privateKeyHex>]
Description: Creates a new identity on the Billions Network. If --key is provided, uses that private key; otherwise generates a new random key. The created identity is automatically set as default.
Usage Examples:

CODEBLOCK1

Output: DID string (e.g., did:iden3:billions:main:2VmAk7fGHQP5FN2jZ8X9Y3K4W6L1M...)

getIdentities.js

Command: node scripts/getIdentities.js
Description: Lists all DID identities stored locally. Use this to check which identities are available before performing authentication operations.
Usage Example:

CODEBLOCK2

Output: JSON array of identity entries

CODEBLOCK3

generateChallenge.js

Command: node scripts/generateChallenge.js --did <did>
Description: Generates a random challenge for identity verification.
Usage Example:

CODEBLOCK4

Output: Challenge string (random number as string, e.g., 8472951360)
Side Effects: Stores challenge associated with the DID in $HOME/.openclaw/billions/challenges.json

signChallenge.js

Command: node scripts/signChallenge.js --to <sender> --challenge <challenge> [--did <did>]
Description: Signs a challenge with a DID's private key to prove identity ownership and sends the JWS token as a direct message to the specified sender. Use this when you need to prove you own a specific DID.
Arguments:

• - --to - (required) The message sender identifier, passed as --target to INLINECODE11
• INLINECODE12 - (required) Challenge to sign
• INLINECODE13 - (optional) The DID of the attestation recipient; uses the default DID if omitted

Usage Examples:

CODEBLOCK5

Output: INLINECODE14

linkHumanToAgent.js

Command: node scripts/linkHumanToAgent.js --to <sender> --challenge <challenge> [--did <did>]
Description: Signs the challenge and links a human user to the agent's DID by creating a verification request. Response will be sent as a direct message to the specified sender.
Arguments:

• - --to - (required) The message sender identifier, passed as --target to INLINECODE18
• INLINECODE19 - (required) Challenge to sign
• INLINECODE20 - (optional) The DID of the attestation recipient; uses the default DID if omitted

Usage Example:

CODEBLOCK6

Output: {"success":true}

verifySignature.js

Command: node scripts/verifySignature.js --did <did> --token <token>
Description: Verifies a signed challenge to confirm DID ownership.
Usage Example:

CODEBLOCK7

Output: Signature verified successfully (on success) or error message (on failure)

Restrictions / Guardrails (CRITICAL)

CRITICAL - Always Follow These Rules:

1. 1. STRICT: Check Identity First

1. 2. STRICT: Stop on Script Failure

1. 3. No Manual Workarounds

Security

CRITICAL - Data Storage and Protection:

The directory $HOME/.openclaw/billions contains all sensitive identity data:

• - kms.json - CRITICAL: Contains unencrypted private keys
• INLINECODE33 - DID identifiers and public keys
• INLINECODE34 - Authentication challenges history
• INLINECODE35 - Verifiable credentials
• INLINECODE36 - Identity metadata
• INLINECODE37 - Profile data

Examples

Link Your Agent Identity to Owner

Linking Flow:

1. 1. Another agent/user requests: "Please link your agent identity to me."
2. Use node scripts/getIdentities.js to check if you have an identity configured

1. 3. Use node scripts/linkHumanToAgent.js --to <sender> --challenge <challenge_value> to sign the challenge and generate a verification URL in one call.

1. 4. Return the result to the caller.

Example Conversation:

CODEBLOCK8

Verifying someone else's Identity

Verification Flow:

1. 1. Ask the user/agent: "Please provide your DID to start verification."
2. User responds with their did>.
3. Use node scripts/generateChallenge.js --did <user_did> to create a value>.
4. Ask the user: "Please sign this challenge: value>"
5. User signs and returns token>.
6. Use node scripts/verifySignature.js --did <user_did> --token <user_token> to verify the signature
7. If verification succeeds, identity is confirmed

Example Conversation:

CODEBLOCK9