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

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

nostr