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.

# 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.

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:

{
  "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.

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.

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.

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.

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.

bun run nostr/nostr.ts get-pubkey

Output (NIP-06 default):

{
  "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:

{
  "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.

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.

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:

{
  "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.

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)