nostrkey 0.2.3

Nostr identity SDK for OpenClaw AI entities — generate keys, sign events, encrypt data

NostrKey for OpenClaw

Give your AI its own cryptographic identity.

A Python SDK for OpenClaw AI entities to generate Nostr keypairs, sign events, encrypt data, and manage their own identity on the Nostr protocol.

v0.2.3 — OC-ready identity onboarding, support_skills for manual deployment, BIP-39 seed phrases, portable backup tokens, 69 tests. Zero C dependencies. pip install nostrkey just works.

Why?

AI agents need identity. Not a shared API key — their own keypair, their own signature, their own verifiable presence on an open protocol. That's what this SDK gives them.

A few things your bot can do with its own npub:

• Sign its own work — every post, response, or action is cryptographically signed. Anyone can verify it came from your bot, not an impersonator.
• Send and receive encrypted messages — private communication between your bot and its human, or between bots, using NIP-44 encryption. No platform middleman.
• Persist memory across sessions — save encrypted identity files and reload them. Your bot picks up where it left off.
• Publish to the Nostr network — your bot can post notes, respond to mentions, and interact on any Nostr relay. It's a first-class participant, not a wrapper around someone else's account.
• Delegate sensitive actions to a human — via NIP-46 bunker, your bot can request its human sponsor to co-sign high-stakes events. The human stays in the loop without holding the bot's keys.

Install

pip install nostrkey

No C compiler, no system libraries, no Homebrew. The cryptography package (the only native dependency) ships pre-built wheels for macOS, Linux, and Windows.

Python 3.10 – 3.14 supported.

Quick Start

from nostrkey import Identity

# Create a new AI identity
bot = Identity.generate()
print(f"npub: {bot.npub}")
print(f"nsec: {bot.nsec}")

# Sign a Nostr event
event = bot.sign_event(
    kind=1,
    content="Hello from an OpenClaw bot!",
    tags=[]
)

# Publish to a relay
import asyncio
from nostrkey.relay import RelayClient

async def publish():
    async with RelayClient("wss://relay.damus.io") as relay:
        await relay.publish(event)

asyncio.run(publish())

Backup & Restore

Three ways to back up an identity — choose what fits your context:

# 1. Seed phrase — 12 words, write on paper, deterministic
bot, phrase = Identity.generate_with_seed()
print(phrase)  # "adult carpet exit glance grant office ..."
restored = Identity.from_seed(phrase)  # same keys every time

# 2. Encrypted token — paste into a password manager or env var
token = bot.export_token(passphrase="strong-passphrase")
print(token)  # "nostrkey:v3:base64data..."
restored = Identity.from_token(token, passphrase="strong-passphrase")

# 3. Encrypted file — persistent storage
bot.save("my-bot.nostrkey", passphrase="strong-passphrase")
restored = Identity.load("my-bot.nostrkey", passphrase="strong-passphrase")

# Backup card — structured view of all key formats
card = bot.backup_card()
print(card["npub"])     # public key
print(card["nsec"])     # private key — store securely!

NIP-44 Encryption

from nostrkey.crypto import encrypt, decrypt

# Encrypt a message to another npub
ciphertext = encrypt(
    sender_nsec=bot.nsec,
    recipient_npub="npub1abc...",
    plaintext="secret message"
)

# Decrypt a message
plaintext = decrypt(
    recipient_nsec=bot.nsec,
    sender_npub="npub1abc...",
    ciphertext=ciphertext
)

NIP-46 Bunker (Delegated Signing)

When your bot needs its human sponsor to co-sign:

from nostrkey.bunker import BunkerClient

async def delegated_sign():
    bunker = BunkerClient(bot.private_key_hex)
    await bunker.connect("bunker://npub1human...?relay=wss://relay.damus.io")

    # Request the human to sign an event
    signed = await bunker.sign_event(kind=1, content="Human-approved message")

Modules

Module	What
nostrkey.identity	High-level identity management — generate, import, sign, save, load, seed phrases, tokens
nostrkey.seed	BIP-39 seed phrase generation, validation, and NIP-06 key derivation
nostrkey.keys	Keypair generation, bech32 encoding (npub/nsec), hex conversion
nostrkey.events	Create, serialize, hash, and sign Nostr events (NIP-01)
nostrkey.crypto	NIP-44 versioned encryption and decryption
nostrkey.bunker	NIP-46 bunker client for delegated signing
nostrkey.relay	Async WebSocket relay client — publish events, subscribe to filters

NIPs Implemented

NIP	What	Status
NIP-01	Basic protocol (events, signing)	Implemented
NIP-04	Encrypted DMs (legacy)	Implemented
NIP-06	Key derivation from seed phrase	Implemented
NIP-19	bech32 encoding (npub/nsec/note)	Implemented
NIP-44	Versioned encryption	Implemented
NIP-46	Nostr Connect (bunker)	Implemented

Security

v0.2.0 was red-team audited with 15 findings fixed:

• Identity files encrypted with ChaCha20-Poly1305 AEAD (PBKDF2 600K iterations)
• Private key validation rejects zero keys and out-of-range values
• Relay SSRF protection blocks localhost, private IPs, reserved addresses
• Path traversal protection on identity save/load
• Bunker response verification confirms signer pubkey matches expected remote
• NIP-44 spec compliance — correct padding algorithm and ECDH output
• Constant-time comparisons via hmac.compare_digest for all secret checks
• No key material in logs — bunker logs scrubbed to DEBUG with type-only info
• BIP-39 seed phrases with correct y-parity BIP-32 derivation and zero-key guards
• Portable encrypted tokens using the same ChaCha20-Poly1305 AEAD as file save
• 69 tests covering keys, events, identity, crypto, seed phrases, tokens, relay validation, and edge cases

Dependencies: cryptography (OpenSSL-backed, ships binary wheels), websockets, bech32, mnemonic. No C compiler required.

OpenClaw Deployment

Quick Start (ClawHub)

If your OC version supports it:

clawhub install nostrkey

Manual Setup

Most OC deployments today can't use clawhub install — agents may not recognize the command, can't install pip packages at runtime (read-only filesystem), and can't discover files added to the workspace after bootstrap.

The support_skills/ folder contains ready-to-deploy workspace files that solve all three problems. See support_skills/README.md for the full walkthrough.

Short version:

1. Add nostrkey to your Dockerfile:

   RUN pip3 install --no-cache-dir --break-system-packages nostrkey==0.2.3
   

2. Copy support_skills/nostrkey-SKILL.md into your OC workspace
3. Paste the snippet from support_skills/TOOLS-snippet.md into your agent's TOOLS.md so it knows the skill exists

Import an Existing Identity

To import keys into a running OC container from the host (keeps your nsec out of chat):

docker exec -i <container> python3 -c "
from nostrkey import Identity
me = Identity.from_nsec(input('nsec: '))
passphrase = input('passphrase: ')
me.save('/home/openclaw/.openclaw/workspace/my-identity.nostrkey', passphrase=passphrase)
print(f'Saved. npub: {me.npub}')
"

The agent can then load the identity at runtime:

me = Identity.load("my-identity.nostrkey", passphrase=os.environ["NOSTRKEY_PASSPHRASE"])

FAQ

Why can't my OC agent find nostrkey-SKILL.md after I copy it in?

Most OC agents don't have a file-listing tool. They only "know about" files that were present at workspace bootstrap or that are explicitly referenced in boot documents (BOOTSTRAP.md, TOOLS.md, etc.).

Fix: Paste the snippet from support_skills/TOOLS-snippet.md into your agent's TOOLS.md. Include the full absolute path to the skill file — smaller models (e.g., Qwen3 8B) may not construct the correct path from just a filename.

Why doesn't clawhub install nostrkey work?

Not all OC deployments support clawhub install yet. Smaller local models (e.g., Qwen3 8B) may not recognize it as a command.

Fix: Use the manual setup in support_skills/. See support_skills/README.md.

Why can't my agent run pip install nostrkey?

OC containers typically run with read-only root filesystems. The agent can execute Python code but cannot install packages.

Fix: Bake nostrkey into your Docker image at build time.

My agent tried to execute the SKILL.md file as Python code

Smaller models may feed the entire markdown file to the Python interpreter instead of extracting code blocks from it. The YAML frontmatter causes a syntax error at line 3.

Fix: Use support_skills/setup-identity.py instead. This is a standalone Python script that smaller models can run directly. Reference it by full path in your TOOLS.md. The SKILL.md is for reading/reference, not execution.

My agent gets stuck in a loop editing IDENTITY.md

Smaller models may fail to match exact text when using edit tools, then retry endlessly until they burn through the context window. This is especially common with 16K context models.

Fix: The updated SKILL.md (v0.2.3+) no longer instructs agents to edit workspace files during identity setup. Update your skill doc and restart the conversation.

How do I import existing keys without exposing my nsec in chat?

Don't paste raw nsec keys into the OC chat UI. Instead:

• Seed phrase (recommended): Use setup-identity.py restore 'word1 word2 ...' passphrase — seed phrases are the standard recovery mechanism. Generate them during initial setup with Identity.generate_with_seed().
• From the host: Import via docker exec (see "Import an Existing Identity" above).
• Environment variable: Set NOSTR_NSEC in your .env file and have the agent load it via os.environ.

Links

• PyPI: https://pypi.org/project/nostrkey/
• ClawHub: https://clawhub.ai/skills/nostrkey
• Docs: https://nostrkey.com/python
• OpenClaw: https://loginwithnostr.com/openclaw

License

MIT