Menu
Post notes, send encrypted messages, and interact with relays using the Nostr protocol.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | using-nostr |
| description | Post notes, send encrypted messages, and interact with relays using the Nostr protocol. |
Post 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.
Upload and host files anonymously using decentralized storage with Originless and IPFS.
Automate web browsers for AI agents using agent-browser CLI with deterministic element selection.
Log all file changes (write, edit, delete) to a SQLite database for debugging and audit. Use when: (1) Tracking code changes, (2) Debugging issues, (3) Auditing file modifications, or (4) The user asks to track file changes.
Fetch current and historical crypto prices and compute ATH or ATL over common time windows.
Host static websites and assets via zip upload to Originless IPFS. Use when: (1) Deploying static sites, (2) Hosting HTML/CSS/JS projects, (3) Sharing web assets publicly, or (4) User asks to host static files.
Search for torrents by title or IMDB ID via a Torznab-compatible API. Use when: (1) User asks to find a torrent for a movie or show, (2) You need a magnet link for a given title, or (3) User provides an IMDB ID and wants download options.