besoeasy/using-nostr
Post notes, send encrypted messages, and interact with relays using the Nostr protocol.
npx skills add https://github.com/besoeasy/open-skills --skill using-nostrPost messages, send encrypted DMs, and interact with the Nostr decentralized social protocol using minimal direct exports from the nostr-sdk module.
Installation:
npm install nostr-sdk
Key Concepts:
nsec1)npub1)Default Relays:
Post a public text note to Nostr.
Usage:
const { posttoNostr } = require("nostr-sdk");
const result = await posttoNostr("Hello Nostr! #introduction", {
nsec: "nsec1...your-private-key",
tags: [],
relays: null,
powDifficulty: 4
});
console.log(result);
Parameters:
message: Text content to posttags: Optional array of tags (e.g., [['t', 'topic']])relays: Optional custom relay list (uses defaults if null)powDifficulty: Proof of work difficulty (default: 4, 0 to disable)Auto-extracted Tags:
#nostr → ["t", "nostr"]@npub1... → ["p", <pubkey>]note1... references → ["e", <event-id>]Response:
{
success: true,
eventId: "abc123...",
published: 12, // Successfully published to 12 relays
failed: 2, // Failed on 2 relays
totalRelays: 14,
powDifficulty: 4,
errors: []
}
When to use:
Reply to an existing Nostr post.
Usage:
const { replyToPost } = require("nostr-sdk");
const result = await replyToPost(
"note1...event-id", // Event ID (note or hex format)
"Great post! @npub1...author", // Reply message
"npub1...author-pubkey", // Author's public key
[], // Additional tags
null, // Use default relays
4 // POW difficulty
);
When to use:
Send encrypted direct message using legacy NIP-4 standard.
Usage:
const { sendmessage } = require("nostr-sdk");
const result = await sendmessage(
"npub1...recipient", // Recipient's public key
"Secret message here", // Message content
{ nsec: "nsec1...your-private-key" }
);
When to use:
Limitations:
Send gift-wrapped encrypted message using NIP-17 (recommended).
Usage:
const { sendMessageNIP17 } = require("nostr-sdk");
const result = await sendMessageNIP17(
"npub1...recipient", // Recipient's public key
"Private message!", // Message content
{ nsec: "nsec1...your-private-key" }
);
Benefits:
When to use:
Listen for incoming direct messages.
Usage:
const { getmessage } = require("nostr-sdk");
const unsubscribe = getmessage((message) => {
console.log("From:", message.senderNpub);
console.log("Message:", message.content);
console.log("Time:", new Date(message.timestamp * 1000));
}, {
nsec: "nsec1...your-private-key",
since: Math.floor(Date.now() / 1000) - 3600 // Last hour
});
// Stop listening:
// unsubscribe();
Message Object:
{
id: "event-id",
sender: "hex-pubkey",
senderNpub: "npub1...",
content: "decrypted message",
timestamp: 1234567890,
event: { /* full event */ }
}
When to use:
Listen for incoming NIP-17 gift-wrapped messages.
Usage:
const { getMessageNIP17 } = require("nostr-sdk");
const unsubscribe = getMessageNIP17((message) => {
console.log("From:", message.senderNpub);
console.log("Content:", message.content);
console.log("Wrapped ID:", message.wrappedEventId);
}, {
nsec: "nsec1...your-private-key",
since: Math.floor(Date.now() / 1000) - 300 // Last 5 minutes
});
// Stop listening:
// unsubscribe();
When to use:
Fetch recent posts from the global Nostr feed.
Usage:
const { getGlobalFeed } = require("nostr-sdk");
const events = await getGlobalFeed({
limit: 50, // Max 50 posts
since: Math.floor(Date.now() / 1000) - 3600, // Last hour
until: null, // Up to now
kinds: [1], // Text notes only
authors: null, // All authors
relays: null // Use defaults
});
events.forEach(event => {
console.log("Author:", event.authorNpub);
console.log("Content:", event.content);
console.log("Note ID:", event.noteId);
console.log("Posted:", event.createdAtDate);
});
When to use:
Generate new Nostr key pair.
Usage:
const { generateNewKey } = require("nostr-sdk");
const keys = generateNewKey();
console.log(keys);
// {
// privateKey: "hex-private-key",
// publicKey: "hex-public-key",
// nsec: "nsec1...",
// npub: "npub1..."
// }
Quick Generate:
const { generateRandomNsec } = require("nostr-sdk");
const nsec = generateRandomNsec();
console.log(nsec); // nsec1...
Convert between key formats.
Usage:
const { nsecToPublic } = require("nostr-sdk");
const publicInfo = nsecToPublic("nsec1...your-key");
console.log(publicInfo);
// {
// publicKey: "hex-public-key",
// npub: "npub1..."
// }
const { posttoNostr } = require("nostr-sdk");
async function postHello() {
const result = await posttoNostr("Hello from my bot! #nostr #automation", {
nsec: "nsec1...your-private-key"
});
console.log("Posted:", result.eventId);
}
postHello();
const { sendMessageNIP17 } = require("nostr-sdk");
async function sendPrivateMessage() {
const result = await sendMessageNIP17(
"npub1...recipient",
"This is a secret message!",
{ nsec: "nsec1...your-private-key" }
);
console.log("Sent:", result.success ? "Yes" : "No");
}
sendPrivateMessage();
const { getMessageNIP17 } = require("nostr-sdk");
console.log("Listening for messages...");
const unsubscribe = getMessageNIP17((msg) => {
console.log(`Message from ${msg.senderNpub}: ${msg.content}`);
}, {
nsec: "nsec1...your-private-key"
});
// Keep running or call unsubscribe() to stop
const { posttoNostr } = require("nostr-sdk");
// Auto-generates keys if not provided
const result = await posttoNostr("Quick post!", {
nsec: "nsec1...your-key" // Optional - generates new if omitted
});
User wants to post to Nostr?
├─ Is it a public post?
│ ├─ Is it a reply to another post?
│ │ ├─ YES → Use replyToPost()
│ │ └─ NO → Use posttoNostr()
│ └─ Need spam protection?
│ ├─ YES → Set powDifficulty to 4+
│ └─ NO → Set powDifficulty to 0
│
├─ Is it a private message?
│ ├─ Maximum privacy needed?
│ │ ├─ YES → Use sendMessageNIP17()
│ │ └─ NO → Use sendmessage()
│ │
│ └─ Need to receive messages?
│ ├─ Use NIP-17 → getMessageNIP17()
│ └─ Use NIP-4 (legacy) → getmessage()
│
└─ Need to read posts?
└─ Use getGlobalFeed()
Security Best Practices:
Environment Variables:
export NOSTR_NSEC="nsec1...your-private-key"
const { posttoNostr } = require("nostr-sdk");
await posttoNostr("Health check log", {
nsec: process.env.NOSTR_NSEC
});
Common Errors:
Private key not set → Provide nsec or generate keysInvalid nsec format → Check bech32 encodingFailed to post to Nostr → Check relay connectionsFailed to decrypt message → Wrong private key for recipientBest Practice:
const { posttoNostr } = require("nostr-sdk");
try {
const result = await posttoNostr("Hello", {
nsec: process.env.NOSTR_NSEC
});
if (!result.success) {
console.error("Failed to publish:", result.errors);
}
} catch (error) {
console.error("Error:", error.message);
}
Direct-export functions do not require a class instance, so there is no client cleanup step.
Take besoeasy/using-nostr from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.
The instructions reference npm.
Without those the skill loads but fails at the first command.