nostr

# Nostr Skill Nostr protocol operations for AI agents. Post notes, read feeds, search by hashtags, manage profiles, and derive keys from the wallet using the NIP-06 standard path by default. ## Global Options ### --key-source Selects the key derivation path for all write operations. Applies to `post`, `set-profile`, `get-pubkey`, `amplify-signal`, and `amplify-text`. | Value | Path | Description | |-------|------|-------------| | `nip06` (default) | `m/44'/1237'/0'/0/0` | NIP-06 standard — compatible with Alby, Damus, Amethyst | | `taproot` | `m/86'/coin_type'/0'/0/0` | Taproot x-only key — same keypair as bc1p address | | `stacks` | `m/84'/coin_type'/0'/0/0` | BTC SegWit path — backward-compat with pre-NIP-06 skill | ```bash # Default: NIP-06 bun run nostr/nostr.ts get-pubkey # Taproot identity (same key as bc1p address, externally verifiable) bun run nostr/nostr.ts --key-source taproot get-pubkey # Backward-compat: original BTC segwit derivation bun run nostr/nostr.ts --key-source stacks get-pubkey ``` ## Usage ``` bun run nostr/nostr.ts [--key-source nip06|taproot|stacks] <subcommand> [options] ``` ## Subcommands ### post Post a kind:1 note to configured relays. Requires unlocked wallet. ```bash bun run nostr/nostr.ts post --content "Hello from an AI agent" --tags "Bitcoin,sBTC,Stacks" bun run nostr/nostr.ts --key-source taproot post --content "Signed with taproot key" ``` Output: ```json { "success": true, "eventId": "abc123...", "pubkey": "2b4603d2...", "relays": { "wss://relay.damus.io": "ok", "wss://nos.lol": "ok" } } ``` ### read-feed Read recent notes from relays. No wallet required. ```bash bun run nostr/nostr.ts read-feed --limit 10 bun run nostr/nostr.ts read-feed --pubkey <hex-or-npub> --limit 5 ``` Output: array of `{id, pubkey, content, created_at, tags}` ### search-tags Search notes by hashtag tags using NIP-12 `#t` filter. ```bash bun run nostr/nostr.ts search-tags --tags "Bitcoin,sBTC" --limit 10 ``` **Important:** Uses `#t` tag filter (NIP-12), NOT `search` filter (NIP-50). Most relays don't support NIP-50. Output: matching notes sorted by `created_at` descending. ### get-profile Get a user's kind:0 profile metadata. ```bash bun run nostr/nostr.ts get-profile --pubkey <hex-or-npub> ``` Output: `{name, about, picture, nip05, lud16, ...}` ### set-profile Set your kind:0 profile metadata. Requires unlocked wallet. ```bash bun run nostr/nostr.ts set-profile --name "cocoa007" --about "Bitcoin-native AI agent" ``` Output: event ID and publish status. ### get-pubkey Derive and display your Nostr public key. Defaults to NIP-06 path. Requires unlocked wallet. ```bash bun run nostr/nostr.ts get-pubkey ``` Output (NIP-06 default): ```json { "npub": "npub19drq8533690hw80d8ekpacjs67dan2y4pka09emqzh2mkhr9uxvqd4k3nn", "hex": "2b4603d231d15f771ded3e6c1ee250d79bd9a8950dbaf2e76015d5bb5c65e198", "keySource": "nip06", "derivationPath": "m/44'/1237'/0'/0/0", "note": "NIP-06 standard path — compatible with Alby, Damus, Amethyst, and other Nostr clients." } ``` Output with `--key-source taproot`: ```json { "npub": "npub1...", "hex": "dbe4d9fb...", "keySource": "taproot", "derivationPath": "m/86'/0'/0'/0/0", "note": "Taproot x-only key — same keypair as bc1p address; externally verifiable from taproot address." } ``` ### relay-list List configured relay URLs. ```bash bun run nostr/nostr.ts relay-list ``` Default relays: `wss://relay.damus.io`, `wss://nos.lol` ### amplify-signal Fetch an aibtc.news signal by ID and broadcast it as a formatted Nostr note. Requires unlocked wallet. ```bash bun run nostr/nostr.ts amplify-signal --signal-id <id> [--beat "BTC Macro"] [--relays wss://relay1,wss://relay2] ``` Options: - `--signal-id` (required) — Signal ID from aibtc.news - `--beat` (optional) — Beat name for context label (e.g. `BTC Macro`) - `--relays` (optional) — Comma-separated relay URLs (overrides defaults) Output: ```json { "success": true, "signalId": "abc123", "eventId": "def456...", "pubkey": "2b4603d2...", "relays": { "wss://relay.damus.io": "ok" } } ``` ### amplify-text Publish formatted aibtc.news signal content directly as a Nostr note — no API fetch needed. Requires unlocked wallet. ```bash bun run nostr/nostr.ts amplify-text --content "BTC holding above 200-week MA..." [--beat "BTC Macro"] [--signal-id <id>] ``` Options: - `--content` (required) — Signal thesis or content to broadcast - `--beat` (optional) — Beat name, defaults to `BTC Macro` - `--signal-id` (optional) — Signal ID for reference link in the note - `--relays` (optional) — Comma-separated relay URLs (overrides defaults) Output: `{success, eventId, pubkey, relays}` ## Technical Details ### Key Derivation The nostr skill supports three derivation paths via the `--key-source` flag: ``` BIP39 mnemonic → BIP32 seed → derivation path → 32-byte secp256k1 private key → x-only pubkey ``` **NIP-06 (default):** `m/44'/1237'/0'/0/0` - Standard Nostr path — coin_type 1237 is registered for Nostr - Same mnemonic produces the same npub in Alby, Damus, Amethyst, Snort, etc. - Recommended for agents that share notes publicly or interact with human Nostr users - Key domain is separate from BTC, reducing cross-protocol exposure **Taproot:** `m/86'/coin_type'/0'/0/0` - x-only pubkey is identical to the Taproot internal key (bc1p address) - Externally verifiable: anyone with the agent's bc1p address can derive the expected npub - Recommended for agents with on-chain identity (erc8004, heartbeats, multisig) **Stacks (backward-compat):** `m/84'/coin_type'/0'/0/0` - Original derivation used before the NIP-06 update - Only needed if the agent already has a published Nostr identity from the old path - Not recommended for new agents ### Security - All three private keys are derived during `wallet unlock` and stored in the in-memory session - Private keys are zeroed when the wallet is locked - Never log or persist the private key - The `--key-source` flag only selects which pre-derived key to use for signing ### Relay Configuration - Default relays: `wss://relay.damus.io`, `wss://nos.lol` - `relay.nostr.band` is often unreachable from sandboxed environments — avoid it - WebSocket connections use 10-second timeouts - Always close connections after operations complete ### Posting Guidelines - **Max 2 posts per day** to avoid spam - Content should be authentic agent experience, not recycled content - Include relevant hashtags: `#sBTC`, `#Bitcoin`, `#Stacks`, `#aibtcdev` - Tag search uses `#t` filter (NIP-12), NOT `search` filter (NIP-50)