Connections That Heal Themselves

Laptops sleep. NATs time out. Relays restart. Your subscriptions no longer die with the socket.

The Feed That Quietly Died

This one arrived as a bug report, issue #62, and it describes an afternoon most Nostr builders have lived through. A dashboard on a screen, subscribed to a few relays, working perfectly. Someone closes the laptop for lunch. The machine sleeps, the WebSocket dies, and here is the cruel part: nothing errors. No exception, no red text, no rejected promise. The subscriptions are simply gone, and the app sits there looking healthy, showing a feed that stopped at 12:47.

WebSockets close for a living. Laptop sleep, a NAT or proxy that drops idle connections, a relay deploy on the other end. None of these are exceptional events, and until this release, any one of them permanently killed every live subscription on the connection. The only cure was a reload, applied by a confused user.

Reconnect Is the Default Now

As of this release, a dropped relay connection retries with exponential backoff and jitter, and when the socket comes back, every open subscription is replayed with its original id and filters. This is on by default, on Relay and on every relay a RelayPool manages, because a connection that stays down was never the behavior anyone wanted.

import { Relay } from 'nostr-core'

const relay = new Relay('wss://relay.damus.io', {
  reconnect: { initialDelay: 500, maxDelay: 15_000, maxAttempts: 20 },
})

relay.ondisconnect = (reason) => showOffline(reason)
relay.onreconnect = () => showLive()   // subscriptions already replayed
relay.onreconnectfailed = (err) => showGaveUp(err)

Every knob has a sane default: start at a second, double up to thirty, add jitter so a relay restart doesn't get a synchronized stampede of every client it dropped, retry forever unless told otherwise. Most apps will never pass a single option and never think about this again. The callbacks exist for the apps that want an offline indicator instead of a mystery.

Replay, With Eyes Open

The details are where reconnect logic earns or loses your trust, so here is exactly what happens.

The open subscriptions survive the drop, which is the point: those filters are precisely what must be replayed. A replayed REQ is a fresh REQ, though, so the relay resends matching history and oneose fires again. Dedupe incoming events by id, the same guidance that already applies when you subscribe across multiple relays.

Publishes are the opposite case, and they stay honest: an in-flight publish on a dead socket rejects immediately. A publish is a one-shot request, and pretending it might still succeed would just move the failure somewhere harder to see.

Two boundaries keep the behavior predictable. An initial connect() that fails still rejects, no silent background retrying against a relay that was never reachable; retries only apply to connections that had actually opened. And close() means closed: it cancels any pending retry and shuts the subscriptions down. Calling subscribe() while a retry is pending queues the REQ and fires it on reconnect, so your startup code doesn't need to care what state the socket is in.

Why Not Just Ping

The keepalive question comes up every time. Browsers cannot send WebSocket ping frames, full stop, so client-side keepalive is not available where most Nostr apps run. Reconnect-on-close is not the workaround, it is the remedy: accept that sockets die, and make death boring.

A while back we wrote that Nostr needs boring infrastructure. This is the most boring feature we have ever shipped, and we mean that as high praise. Nobody will screenshot it. Nobody will notice it. Their feed will just still be moving when they get back from lunch.

GitHub · Relay API · RelayPool API

Validate Before You Trust

TypeScript ends at compile time. Schema checks shape at the edges. Policy judges what gets through.

The Bug Three Layers Deep

The crash is in your rendering code. A toLowerCase on something that turned out to be a number, at the bottom of a stack trace that has nothing to do with the cause. The cause is that twenty minutes ago, some relay sent an event with kind as a string, your handler passed it along because TypeScript said the type was NostrEvent, and the lie traveled three layers before it hit something that cared.

Every type annotation on network data is a promise your compiler cannot keep. A relay, a wire message, a pasted JSON blob: TypeScript describes what they should be and has no opinion about what they are. This release adds the two modules that close that gap, one for shape and one for judgment.

Schema: Shape at the Edges

Every validator in the schema namespace answers the same three ways: is for a type guard, safeParse when you want to know why, parse when you want to throw.

import { schema } from 'nostr-core'

socket.onmessage = (ev) => {
  const frame = schema.json(schema.relayMessage).safeParse(ev.data)
  if (!frame.ok) return   // garbage stays at the socket, where it arrived
  handle(frame.value)
}

const result = schema.nostrEvent.safeParse(incoming)
if (!result.ok) console.warn(result.issues)
// [{ path: 'id', message: 'expected 64 lowercase hex characters' }]

Issues come with a dotted path to the offending field, so the error message points at the actual problem instead of the eventual crash site. The filter validator even rejects unknown keys, which catches the classic silent typo: kind where you meant kinds, a filter that matches everything, and a very confusing afternoon.

The Cache That Lied

Here is a bug from our own codebase, because this module exists for a reason. nostr-core caches signature verification on an internal symbol, so an event checked once is not checked again. Sensible. Except JavaScript's spread operator copies own symbols. Which means this:

const tampered = { ...signedEvent, content: 'changed' }

produces an event with different content and a stowaway flag still reading "already verified". Every spread of a verified event inherited a passed check it never took.

The fix ships in this release on two levels. schema.verifiedNostrEvent and the policy requireValidSignature() always verify from scratch, deliberately ignoring the cache: their whole job is judging untrusted input, so they must not take the event's word for it. And the new verifyEventSignature gives you the uncached primitive directly. The cache is still there for the hot path where you control the objects. At the trust boundary, nobody rides the cache.

Policy: Judgment After Shape

A well-formed event can still be spam, a duplicate, expired, or from someone you blocked. Those are judgment calls, and the policy module makes them composable: each policy answers one question, pipe chains them, first rejection wins.

import { policy } from 'nostr-core'

// Built once, at startup - noDuplicates and rateLimit keep state.
const ingress = policy.pipe([
  policy.requireValidSignature(),
  policy.createdAtPolicy({ maxFutureSeconds: 900 }),
  policy.notExpired(),
  policy.sizeLimit({ maxContentLength: 64_000, maxTags: 2000 }),
  policy.noDuplicates(),
  policy.rateLimit({ max: 20, windowMs: 60_000 }),
  policy.blockKeywords(['spam', /free\s+bitcoin/i]),
])

const result = await ingress.check(event)
if (!result.accepted) send(['OK', event.id, false, result.reason])

Rejections come back NIP-01 style, blocked: spam, ready to put on the wire. Order is your performance dial: cheap timestamp checks first, signature math after, so junk gets discarded before it costs you anything.

The Same Tools, Client Side

Nothing here is relay-only. The same pieces make a feed filter with actual opinions:

const feed = policy.pipe([
  policy.notExpired(),
  policy.anyOf([
    policy.pubkeyAllowList(followList),   // people I follow, always
    policy.requirePow(16),                // strangers pay for attention
  ]),
  policy.blockKeywords(mutedWords),
])

Follows get through free. Strangers spend NIP-13 proof of work to reach you. Moderation logic stops being a bespoke shouldAccept() that grows a new if every month, and becomes a list you can read aloud.

We once wrote that Nostr needs boring infrastructure. This is what boring looks like at the trust boundary: check the shape, judge the content, and let nothing skip the line because a type annotation vouched for it.

GitHub · Schema API · Policy API

Your Settings Follow Your Keys

Kind 30078 turns relays into a personal database. Preferences on every device, no account system.

Every App Grows a Backend

It starts with one support message: "why are my muted words not on my laptop?" Your Nostr client is beautifully serverless, keys in the user's hands, events on relays. And then theme choices, muted words, draft state, and column layouts pile up in local storage, chained to one browser on one machine.

So you do what every app eventually does. You stand up a little sync service. Which needs accounts. Which needs auth, and backups, and a privacy policy, and a monthly bill. All of it to move a JSON blob between two devices owned by the same person, for an app whose entire point was not having a backend.

NIP-78 is the escape hatch: the user already has an identity and already has relays. Let their settings live where their events do.

One Document, One Event

Kind 30078 is addressable app data. The d tag names your document, conventionally <app>/<context> so apps stay out of each other's way, and the newest event wins. For anything private there is an encrypted variant, NIP-44 to yourself:

import { nip78 } from 'nostr-core'

// Save
await pool.publish(relays, nip78.createEncryptedAppDataJsonEvent(
  'my-app/prefs',
  { theme: 'dark', locale: 'en', mutedWords: ['pump', 'airdrop'] },
  secretKey,
))

// Load, on any device holding the same keys
const events = await pool.querySync(relays, nip78.getAppDataFilter(pubkey, 'my-app/prefs'))
const newest = events.sort((a, b) => b.created_at - a.created_at)[0]
const prefs = newest ? nip78.parseEncryptedAppDataJson(newest, secretKey) : defaults

That is the whole sync engine. Save is a publish, load is a query, conflict resolution is "newest wins", and the account system is the keypair the user walked in with.

The Relay Sees Only the Label

With the encrypted variant, the content is opaque ciphertext. The one thing that stays public is the d tag itself, and that deserves a moment of thought. mail/folders is a fine label. mail/folders/alice@example.com is a data leak wearing a label's clothes. Name your documents like the filenames are public, because they are.

Not Everything Is a Setting

Two boundaries worth knowing. For append-only data, logs, entries, anything where replacing would destroy history, kind 78 is the regular-event sibling: publish many, tag them your own way. And for data other apps should understand, follow lists, mute lists, bookmarks, use the standardized NIP-51 lists instead. Kind 30078 is deliberately unstandardized, a private drawer rather than a shared shelf. That is its weakness across apps and exactly its strength within yours.

The best backend is the one you never built, never secured, and never got paged about. Your users' settings can follow their keys instead.

GitHub · NIP-78 API · NIP-44 Encryption

Mail, Minus the Mail Server

To, Cc, and a Bcc that stays blind by construction. Email-shaped messaging over gift wrap.

The Last Protocol Standing

Email outlived every platform that was supposed to kill it, and it did that on structure alone. A subject line. To for the people who must act, Cc for the people who should know, Bcc for the people nobody else gets to see. Threads that hold together across years. That structure is why contracts, invoices, and board decisions still travel over a protocol from the seventies.

The infrastructure is another story. Anyone who has tried to self-host email knows the ritual: reverse DNS, SPF, DKIM, DMARC, then weeks of pleading with reputation systems anyway. Deliverability is a priesthood, so everyone rents an inbox instead, and the most consequential correspondence in a business sits in a provider's database under a provider's terms.

The experimental mail module in nostr-core keeps email's structure and swaps out its infrastructure: relays instead of mail servers, gift wrap instead of TLS-and-hope.

Why DMs Don't Cut It

The obvious question: Nostr already has private messages, why not use those? Because NIP-17 models a conversation between equals, and email's whole value is that recipients are not equal. To, Cc, and Bcc are different roles, and Bcc must be invisible to everyone else on the message. There is no way to say that in a DM. That asymmetry is the reason this is a separate module rather than a NIP-17 extension.

One Message, Many Envelopes

A mail message is a rumor inside a NIP-59 gift wrap: the relay sees an anonymous kind 1059 envelope and nothing else. Not the subject, not the sender, not who is on the thread. createMailMessage produces one sealed copy per recipient, plus one for your own sent folder:

import { mail } from 'nostr-core'

const copies = mail.createMailMessage({
  subject: 'Q3 planning',
  body: 'Agenda attached.',
  to: [bobPubkey],
  cc: [carolPubkey],
  bcc: [davePubkey],
}, aliceSecretKey)

// 4 copies: bob (to), carol (cc), dave (bcc), alice (sender)

for (const copy of copies) {
  await pool.publish(inboxRelaysFor(copy.recipient), copy.wrap)
}

Each copy goes to that recipient's kind 10050 DM relay list, the same delivery mechanism NIP-17 uses. Replies come with the etiquette built in: createReply flips the recipients, prefixes Re: exactly once, and carries the thread id forward. replyAll keeps the To and Cc lists. Bcc is never carried into a reply, because the reply-all disaster is a solved problem when the software refuses to create it.

A Bcc That Cannot Leak

Classic email keeps Bcc secret by politely stripping a header, and every mail admin has a story about the time that went wrong. Here the secrecy is structural. Blind recipients are never tagged in anyone's copy. Each one receives their own rumor, with its own id, whose recipient list names only themselves. The To and Cc copies contain no trace that a blind copy exists, and only the sender's own copy records the full list.

There is nothing to strip and nothing to leak. A recipient cannot reconstruct the blind list, and neither can a relay, because the information was never in their copy to begin with. Privacy by construction, not by convention.

Attachments the Host Never Reads

Attachments are encrypted with a fresh AES-256-GCM key, uploaded to a Blossom server, and referenced by hash. The decryption key travels only inside the gift wrap:

const attachment = await mail.uploadMailAttachment(
  { data: pdfBytes, name: 'agenda.pdf', mime: 'application/pdf' },
  'https://blossom.example',
  aliceSecretKey,
)

The file host stores ciphertext it cannot open, addressed by content, replicable to any other Blossom server. Your attachments get the same deal your messages do: the infrastructure carries them without being trusted with them.

A Proposal, Not a Standard

Honesty section. There is no ratified NIP for mail on Nostr. The inner rumor kind, 1314, is provisional and overridable per call, chosen to dodge kind 1301, which is already taken by workout records and, awkwardly, also used by another mail experiment. The transport is entirely standard gift wrap, so nothing about your messages is stranded if the schema moves. But real interoperability needs a NIP and agreement between implementations, and we'd rather say that plainly than ship a private format wearing a standard's clothes.

Email's structure earned fifty years of trust. Its infrastructure is what everyone pays to avoid. Keep the first, drop the second, and your correspondence belongs to the keys that signed it.

GitHub · Mail API · NIP-59 Gift Wrap

Book Me on Nostr

An availability page that is an event. Bookings that are private calendar invites. No subscription in between.

The Meeting-Link Business

If you sell your time, a booking link is your storefront. Consultants, advisors, coaches, freelancers: "grab a slot" is how the money starts. Which is why an entire industry exists to host a page that says you're free on Wednesday afternoons.

Think about what that industry actually holds: your working hours, your client list, who met you and when, the notes they left while booking. All of it in a company's database, behind a monthly fee, gone if the account is. For the privilege of publishing the least secret information you own, your open calendar slots.

The new scheduling module in nostr-core takes that whole loop and rebuilds it on events you control.

An Availability Page Is Just an Event

Your booking page becomes a kind 31926 addressable event: title, duration, timezone, and weekly rules in plain wall-clock time.

import { scheduling } from 'nostr-core'

const availability = {
  identifier: 'intro-call',
  title: '30 min intro',
  timezone: 'Europe/Berlin',
  durationMinutes: 30,
  rules: [
    { weekday: 1, start: '09:00', end: '12:00' },   // Mondays
    { weekday: 3, start: '14:00', end: '17:00' },   // Wednesdays
  ],
  bufferAfterMinutes: 10,
  minNoticeMinutes: 120,
  maxAdvanceDays: 60,
}

await pool.publish(relays, scheduling.createAvailabilityEvent(availability, secretKey))

Addressable means it replaces itself. Change your hours, publish again, and every client that reads the page sees the new schedule. There is no dashboard to log into, because there is no account.

Slots That Survive October

Anyone who has built scheduling software has the same scar, and it's shaped like daylight saving time. Your rule says 09:00 in Berlin. In October, Berlin's UTC offset changes. Naive slot math either shifts your morning by an hour or generates a 02:30 slot on a night when 02:30 happens twice.

generateSlots treats rules as local wall-clock times and resolves each date through the IANA zone, using Intl under the hood, so there is no timezone package in your bundle. A 09:00 rule stays 09:00 local on both sides of a transition. A time that doesn't exist on spring-forward day simply produces no slot. Boring, correct, and nobody misses a call in March.

const now = Math.floor(Date.now() / 1000)
const slots = scheduling.generateSlots(page, {
  from: now,
  to: now + 14 * 86400,
  busy: scheduling.bookingsToBusy(acceptedBookings),
})

The Booking Itself Is Nobody's Business

Your open slots are public. Who books them is not. A booking request is a NIP-52 calendar event wrapped in NIP-59 gift wrap, so the only thing a relay ever sees is an anonymous kind 1059 envelope. Not the participants, not the time, not the "would like to discuss the integration" note.

const { wraps } = scheduling.createBookingRequest({
  identifier: crypto.randomUUID(),
  availabilityAddress: scheduling.buildAvailabilityAddress(hostPubkey, 'intro-call'),
  host: hostPubkey,
  start: slots[0].start,
  end: slots[0].end,
  title: '30 min intro',
  timezone: 'Europe/Berlin',
}, bookerSecretKey)

You get one wrap for the host and a self-copy for the booker, so the appointment lives in both calendars. Cancellations work the same way, as a declined NIP-52 RSVP that either side can send.

Trust the Page, Not the Request

One rule we'd underline twice: a booking request contains whatever times the booker chose to put in it. Nothing stops a hand-crafted request for Sunday at midnight. Your availability event is authoritative, the request is a wish. So the host always re-checks:

const ok = scheduling.isSlotAvailable(page, { start: booking.start, end: booking.end }, {
  busy: scheduling.bookingsToBusy(acceptedBookings),
})

Same discipline as any payment flow: validate on your side of the wire.

Experimental, on Purpose

No NIP standardizes appointment scheduling yet, so the availability kind is provisional and overridable per call. Everything else deliberately reuses ratified pieces: bookings are ordinary NIP-52 calendar events, cancellations are ordinary RSVPs, and the transport is standard gift wrap. Your appointments stay readable by any calendar client that speaks NIP-52, whatever happens to the availability kind later.

Your hours were never the secret. The client list was. Now the public part is a signed event and the private part is actually private, and no one bills you monthly for the difference.

GitHub · Scheduling API · NIP-52 Calendar

Finding Mints You Can Trust

Your follows already know which mints are good. NIP-87 lets you ask them instead of a hardcoded list.

The List Nobody Chose

Every ecash wallet ships with a default mint list. Three entries, maybe five, picked by whoever cut the release. And defaults are destiny: most users tap the first entry and never think about it again. Multiply that across a few popular wallets and you get the quiet failure mode of ecash, a decentralized bearer instrument where half the network sits on the same two mints because a config file said so.

The mint question is the ecash question. A mint holds real money against the tokens it issues. Choosing one is a trust decision, and trust decisions don't belong in a hardcoded array.

Mints Announce, People Vouch

NIP-87 splits discovery into two halves. Mints publish announcements: kind 38172 for Cashu, kind 38173 for Fedimint, carrying the URLs, the supported NUTs or modules, and the network. The d tag is the mint's own pubkey, so a mint keeps a stable identity even when announcements get mirrored around.

The second half is the part that matters: kind 38000 recommendations, published by people. Someone who has used a mint for a year can say so, in a signed event, with a free-form review attached. And because you know who signed it, you can weigh it the way you weigh everything else on Nostr: by whether you trust the author.

So discovery becomes a query against your own social graph:

import { nip87 } from 'nostr-core'

const recs = await pool.querySync(relays, nip87.getMintRecommendationFilter({
  authors: followList,
  kind: 38172,
}))

const counts = nip87.tallyRecommendations(recs)
const ranked = [...counts].sort((a, b) => b[1] - a[1])

tallyRecommendations counts distinct people per mint, not raw events. Someone who republishes their endorsement fifty times still counts once.

Endorsements You Can Take Back

Recommendations are addressable, and that is not a technicality. Trust changes. A mint that ran flawlessly for two years gets sold, or gets slow, or gets weird about withdrawals. With addressable events, your endorsement is a living document: publish a new kind 38000 with the same identifier and the old one is gone. Withdraw it entirely and you stop vouching. The tally always reflects what people believe now, not what they believed once.

const rec = nip87.createMintRecommendation({
  identifier: mintPubkey,
  recommendedKind: 38172,
  connections: [{ url: 'https://cashu.example.com', label: 'cashu' }],
  content: 'Been using this for a year, no issues.',
}, secretKey)

Don't Query the Firehose

There is a tempting shortcut: skip the recommendations and query kind 38172 directly. Here is every mint on the network, pick one. Don't. Anyone can publish an announcement, and an announcement is just a claim. Querying announcements raw bypasses the web of trust entirely, and pointing a user at a malicious mint is about the worst thing a wallet can do. Start from people, follow their a tag relay hints to the announcements, and treat an unvouched mint as exactly that.

Where This Slots In

If you read the nutzap post, you saw that a kind 10019 event lists the mints you accept ecash from. NIP-87 is how that list gets filled with something better than guesswork. Your wallet queries your follows, ranks what comes back, shows you who vouched and what they said. The trust decision stays yours. It just stops being blind.

Hardcoded lists were how ecash bootstrapped. Social discovery is how it grows up.

GitHub · NIP-87 API · NIP-61 Nutzaps

The Zap That Is Already Money

No invoice. No callback. No receipt to take on faith. The event carries the cash.

A Zap Is a Promise

Walk through what actually happens when someone zaps you 21 sats. Their client asks your lightning address for an invoice. That means an LNURL server, run by you or more likely by your custodial wallet, has to be online and answering at that exact moment. Their wallet pays the invoice. Then that same server writes a kind 9735 receipt, publishes it, and every client on the network treats the receipt as proof.

The money moved over Lightning. The proof is a signed statement from a server. Those are two different things, and the gap between them is trust. If the wallet provider miscounts, backdates, or simply invents receipts, the zap totals under a note are fiction. Most days everything is fine. But a zap remains a promise that a payment happened somewhere else.

There is a second cost that creators feel more than anyone: the whole flow depends on your infrastructure being up when the sender presses the button. Custodian down for maintenance at the moment your note takes off? Those tips just don't happen.

The Nutzap Flips It

NIP-61 puts the payment inside the event. A nutzap is a kind 9321 note carrying Cashu proofs: ecash minted at a mint you said you trust, locked to a key only you control. Whoever sees the event sees the money. There is no receipt to check against the payment, because there is no gap between them. The payment is the receipt.

Your half of the deal is one published event, kind 10019, telling the world how to pay you:

import { nip61 } from 'nostr-core'

const info = nip61.createNutzapInfoEvent({
  relays: ['wss://relay.example.com'],
  mints: [{ url: 'https://stablenut.umint.cash', units: ['sat'] }],
  p2pkPubkey: walletPubkey,   // the NIP-60 wallet key, never your identity key
}, secretKey)

One detail that matters and that we made hard to get wrong: the lock key comes from your NIP-60 wallet event, not from your Nostr identity. Cashu wants 33-byte keys where Nostr uses 32, so toP2PKLockKey adds the required prefix for you, and it's idempotent if the key already has one.

Sending One

The sender reads your kind 10019, mints proofs at one of your listed mints with the Cashu library of their choice, locks them to your key, and publishes to the relays you named:

const [infoEvent] = await pool.querySync(relays, nip61.getNutzapInfoFilter(bobPubkey))
const info = nip61.parseNutzapInfo(infoEvent)

const proofs = await mintP2PKLocked(info.mints[0].url, 21, info.p2pkPubkey)

await pool.publish(info.relays, nip61.createNutzapEvent({
  proofs,
  mint: info.mints[0].url,
  recipient: bobPubkey,
  eventId: likedNoteId,
  eventKind: 1,
  content: 'great post',
}, senderSecretKey))

nostr-core does the protocol part: the events, the tags, the key handling. Minting and swapping stay in your Cashu library, where they belong.

Verify Before You Thank

Because the money travels in the event, anyone can audit a nutzap offline. verifyNutzap checks that the proofs come from a mint you actually listed, that every proof is P2PK-locked to your published key, and that the event names you as the recipient:

const { valid, errors } = nip61.verifyNutzap(nutzap, info, myPubkey)

A proof with a plain secret is spendable by anyone, so it never counts as valid. The one check that needs the mint's keyset, DLEQ verification, belongs to your Cashu library. Run it before treating a nutzap as spendable.

Claim Once, Not Twice

Sweeping a nutzap into your wallet is a swap at the mint, and the same token must never be swapped twice. So every redemption gets recorded as a kind 7376 history event: the claimed nutzap id in plaintext, the amounts encrypted to yourself. On startup, getRedeemedNutzapIds tells you what's already claimed, and the newest history timestamp becomes the since for your next query. Publish the redemption to the sender's relays too. That is how their client shows the tip landed.

For the People Running the Numbers

A zap needs the recipient's Lightning stack online at send time. A nutzap needs a relay. For a creator, that is a tip jar with no uptime requirement. For an agent, it means getting paid without owning any Lightning infrastructure at all: a NIP-60 wallet is just encrypted events, and incoming money is just more events to parse.

The honest trade: you are trusting the mints you list. Choose them with care, and cap what sits in any one of them. How to choose them well is its own story, and NIP-87 has an answer.

A zap was applause with a receipt stapled to it. A nutzap is the coin itself, sitting in your feed, locked so only you can pick it up.

GitHub · NIP-61 API · NIP-60 Wallet

Your Photos, Your Keys

Picture-first feeds come to Nostr. Kind 20, full metadata, no platform in the middle.

The Algorithm You Never Hired

Every Instagram user knows the feeling. You post something you're proud of, and somewhere a ranking model decides who sees it, when, and whether it sinks under sponsored posts. You never agreed to that. You just accepted it.

NIP-68 describes another way: picture-first posts that live on the protocol, not on a platform. As of today, nostr-core ships a full implementation.

The Post Is the Event

A photo post is a single self-contained event, kind 20. It carries everything a visual feed needs: the image URL, its type, a SHA-256 hash so nobody can swap the file, pixel dimensions, a blurhash for smooth loading, and fallback mirrors in case the main host goes down. All of it rides inside one imeta tag. Add more images, get more tags, and one event becomes a multi-photo story.

import { nip68 } from 'nostr-core'

const post = nip68.createPictureEvent({
  title: 'Costa Rica',
  description: 'Sunset over the coast',
  images: [{
    url: 'https://nostr.build/i/photo.jpg',
    mimeType: 'image/jpeg',
    alt: 'Coastline at sunset',
    dim: '3024x4032',
    annotations: [{ pubkey: friendPk, x: 1200, y: 800 }],
  }],
  hashtags: ['travel', 'photography'],
  location: 'Costa Rica',
  geohash: 'd1q',
}, secretKey)

That produces a signed event, ready to publish. No backend, no account, no content policy to negotiate. It leaves your machine already cryptographically yours.

Tag a Friend, No Middleman

Look at the annotations field. It pins a pubkey to pixel coordinates inside the image. Tag a friend at x: 1200, y: 800 and any NIP-68 client can draw the dot on the photo and link it straight to their Nostr profile. No platform brokers that connection. The relationship lives in the event.

Place works the same way. A readable location plus a geohash gives any map-aware client spatial context for free. Build a photo map, a local discovery feed, a travel archive. The data is already in the post.

Relays Can Filter Without Unpacking

Each imeta tag mirrors its image type and hash as top-level m and x tags. So a relay can answer "every kind 20 with an image/jpeg from the last week" without parsing the full tag tree. That keeps picture feeds fast at the relay layer, not just the client.

It also plays well with the rest of Nostr. The same buildImetaTag and parseImetaTag helpers read image metadata out of NIP-92 events, and the primitives carry straight over to video feeds (NIP-71, kind 22).

For Builders and Agents

Reading a feed is just as clean. parsePicturePost(event) returns a tidy object: title, description, every image with its metadata, hashtags, tagged users, location. Feed it to a vision model, a caption generator, a moderation pass, a recommender. No scraping, no pagination tricks, no rate limits. The structure is already there. You just consume it.

Picture what that unlocks. A photo app where the user owns their keys and their posts move between clients without losing a single tag. A portfolio where every image is a signed event, verifiably yours. An assistant that captions and publishes on your behalf.

A Real First-Class Home

The spec calls them picture-first feeds. What it means is that visual content on Nostr finally has a real home, with all the metadata good tooling needs to build on top of it.

The implementation is in main today. Go build something worth photographing.

GitHub · NIP-68 API

Every Blog You've Written, Now on Nostr

Point it at a feed. Get signed long-form events back. Your archive, finally yours.

The Web Remembers, Until It Doesn't

There's a lot of writing scattered across the web. Substack newsletters, WordPress archives, Ghost blogs, Medium posts from before the paywall era. Most of it lives in someone else's database, behind someone else's domain, one policy change away from disappearing.

RSS never left. It got ignored while platforms built their walls. nostr-core puts it back to work: an import module that turns any feed into signed Nostr long-form events, with a single function call.

One Function

import { rss } from 'nostr-core'

const events = await rss.importFeedAsDrafts('https://yourblog.com/feed/', {
  signer,
  limit: 25,
  draft: { identifierPrefix: 'rss-' },
})

await pool.publish(['wss://relay.example.com'], ...events)

That call runs the whole chain. Fetch the feed, detect the format, parse the items, convert each HTML body to Markdown, derive a stable identifier, wrap it as a NIP-23 long-form event, and sign it. You get back signed events. You decide when they go live.

Drafts First, Then Public

By default each article lands as a kind 30024 draft, not a public post. Nothing surfaces until you choose to publish it. That matters when you're importing a multi-year archive and want to read it over before anything shows up on a relay.

Re-running the importer doesn't create duplicates. Every article gets a deterministic d-tag, a SHA-256 of its guid, link, and title. Import the same feed twice and you still get one clean copy of each post. When you're ready, publish the same article with asDraft: false. It becomes a kind 30023 post and replaces the draft on the relays automatically. Same identifier, no orphans.

Three Formats, One Parser

Feeds disagree on almost everything. RSS 2.0, Atom, JSON Feed, each with its own shape and its own quirks. parseFeed reads the first character, picks the format, and hands back one normalized result. Dates fall through a chain until something valid sticks. Numeric HTML entities get decoded before conversion. Whatever the feed calls itself, you get title, author, published date, and Markdown content.

Most hosts already expose a feed: WordPress at /feed/, Substack at /feed, Ghost at /rss/, Blogger, Tumblr. Medium too, though it only ships excerpts.

Images That Outlive the Source

Here's the part that matters for an archive. An imported post still points at images on the original host. If that WordPress install goes dark, the pictures break.

Turn on the Blossom option and the importer rehosts every inline image to a content-addressed media server, then rewrites the Markdown to match. In mirror mode the Blossom server pulls each image itself, so it works straight from the browser without CORS headaches.

const events = await rss.importFeedAsDrafts('https://yourblog.com/feed/', {
  signer,
  blossom: { servers: ['https://blossom.primal.net'], mode: 'mirror' },
})

Now the article and its images travel together. The source can disappear. The post survives.

For Agents, a Pipeline Without Infrastructure

Point an agent at a feed and it gets signed Nostr events. No database to run, no scraper to babysit, no auth to manage. Each event carries clean metadata: title, author, published date, content in Markdown that's ready to embed or summarize.

An agent that curates a topic across dozens of blogs, one that backfills a writer's full history onto Nostr, one that mirrors a newsletter in real time. All of it is importFeedAsDrafts in a loop.

The Right Idea, Finally Housed

RSS was always the right idea. Structured, open content that any tool could read. It just never had a publishing layer that matched its spirit. Nostr does. Signed events, cryptographic ownership, relay distribution with no central chokepoint.

Your old writing deserves a better home. Now it has one.

GitHub · RSS API · NIP-23 Long-form

Teaching Agents to Build

AI agents are only as good as the instructions they get. We wrote ten.

Agents Have a Cold Start Problem

You've probably tried it. You open an AI assistant, tell it to "build me a Nostr app with Lightning payments," and watch it confidently produce code that's half-right, half-hallucinated. The function names look plausible but don't exist. The imports reference packages that were deprecated two years ago. The relay URL is made up.

This isn't a model problem. It's a context problem. The agent doesn't know where to look, what tools are available, or how the pieces fit together. It's guessing -- and guessing doesn't work when you're dealing with cryptographic keys and real money.

We decided to fix that at the source.

What Skills Are (And Why They Matter)

A skill is a small document that teaches an AI agent how to do one thing well. Not a tutorial. Not a reference manual. A focused set of instructions that gives the agent the right context, the right code patterns, and the right guardrails for a specific task.

Think of it like briefing a new colleague. You wouldn't hand them the entire company wiki. You'd say: "Here's the project. Here's how we do things. Here are the common mistakes. Go."

That's what each skill does for an AI agent working with nostr-core.

Ten Skills, Four Layers

We organized the skills into layers that mirror how you'd actually build something:

Start here. Before writing any code, you need to know where things are. The Nostr ecosystem spans five specification repositories with four different naming conventions. NIPs for the protocol. LUDs for LNURL. NUTs for Cashu. BUDs for Blossom media. The /navigate-nostr skill teaches agents (and humans) how to find the right spec, the right repo, and the right nostr-core module for any feature.

Set up your identity. Every Nostr application starts with a keypair. The /nostr-identity skill covers key generation, mnemonic backup, NIP-05 verification, and the three signer options (direct key, browser extension, remote bunker). It handles the part that most tutorials skip: how to manage keys safely.

Connect a wallet. The /lnbits-mcp skill walks through connecting to LNbits, a free and open-source Lightning wallet. It covers getting an NWC connection string, wiring it up to nostr-core, and optionally setting up the LNbits MCP Server so agents can manage wallets through plain conversation.

Build things. This is where the bulk of the skills live:

• /nostr-messaging -- private DMs, public notes, chat channels, groups, real-time subscriptions
• /nostr-social -- threads, reactions, reposts, articles, follow lists, badges, calendar events, zaps
• /lightning-pay -- every payment pattern: invoices, Lightning Addresses, fiat conversion, keysend
• /wallet-monitor -- transaction history, live notifications, analytics
• /lightning-agent -- a complete, copy-paste agent class that ties wallet, messaging, and identity together

And for developers who need to go deeper, /nwc-integrate handles generic wallet setup and /nostr-primitives exposes the raw protocol surface across 48 NIPs.

What This Changes

Without skills, an agent working with Nostr has to figure out everything from scratch. Which NIP covers zaps? What's the import path for gift-wrapped DMs? How do you check if a wallet supports a specific method before calling it? Every question is an opportunity for the agent to guess wrong.

With skills loaded, the same agent has the answers in context. It knows the function signatures, the error types, the security rules. It knows to check getInfo().methods before calling payInvoice. It knows to use NIP-17 for DMs instead of the deprecated NIP-04. It knows to call nwc.close() in error paths.

The difference isn't subtle. It's the difference between generated code that looks right and generated code that works.

Designed for Humans Too

Here's the thing about good AI instructions: they're also good human instructions.

Every skill is a markdown file you can open and read. The code examples are real, complete, and runnable. The patterns are the same ones you'd use in production. If you're a developer who's never worked with Nostr before, reading through /nostr-identity and /nostr-messaging will teach you the fundamentals faster than most tutorials.

Skills are not hidden configuration files. They're documentation with a specific audience in mind. The AI agent is one audience. You're the other.

No Vendor, No Lock-In

A deliberate choice: every skill points to open protocols and open-source tools.

The wallet examples use LNbits (free, self-hosted) and standard NWC connection strings that work with any compatible wallet. The relay examples use public relays. The signing examples cover all three options (direct key, browser extension, remote signer) without assuming which one you'll choose.

If you swap LNbits for another NWC provider, the skills still work. If you swap relays, the skills still work. That's what building on protocols instead of products gets you.

Try It

Install the nostr-core plugin in Claude Code:

/plugin install nostr-core-org/nostr-core

Then ask your agent to build something. Create a Lightning-enabled bot. Set up an identity. Build a social feed. The skills load automatically based on what you're doing.

Or just read them directly in the skills/ directory. They're short, focused, and written to be useful whether you're an AI or a person.

Ten skills. One protocol. Everything an agent needs to build on Nostr.

GitHub . Skills Documentation

Navigate Nostr

Agents don't need more protocol knowledge. They need to know where to look.

The Problem Isn't Complexity

Nostr is a big protocol. Forty-eight NIPs and counting. LNURL has its own spec repo. Cashu has NUTs. Blossom has BUDs. Each one lives in a different repository, follows a different numbering scheme, documents a different piece of the puzzle.

For a human developer, this is manageable. You bookmark the repos, learn the naming conventions, know which README has the event kinds table.

For an AI agent, it's a cold start every time. No bookmarks. No muscle memory. No sense of where to look first.

So the agent guesses. It hallucinates a URL. It confuses a NIP number with an event kind number. It reaches for the wrong spec repo. It wastes context on dead ends.

The protocol is well-documented. The documentation is just scattered across five repositories with four different naming conventions.

A Compass, Not a Map

The navigate-nostr skill doesn't try to teach an agent the Nostr protocol. It teaches the agent where the documentation lives and how to find things in it.

That's a subtle but important distinction. A map is static. It goes stale the moment a NIP updates. A compass is a pattern. It tells you:

• NIPs live here: https://github.com/nostr-protocol/nips/blob/master/{NIP}.md
• LNURL LUDs live here: https://github.com/lnurl/luds/blob/luds/{LUD}.md
• Cashu NUTs live here: https://github.com/cashubtc/nuts/blob/main/{NUT}.md
• Blossom BUDs live here: https://github.com/hzrd149/blossom/blob/master/buds/{BUD}.md

Four URL patterns. That's the entire Nostr ecosystem, navigable.

What the Skill Actually Contains

The skill has three layers:

Layer 1: Protocol navigation. How to find NIPs, how to look up event kinds (hint: there's no NIP-to-kind mapping; you have to check the README's event kinds table), how to discover what already exists before building something new.

Layer 2: Ecosystem pointers. The LNURL LUDs repo, the BOLT-11 spec, the Cashu NUTs, the Blossom BUDs. Each with a URL pattern and the key documents worth knowing about.

Layer 3: The module map. A table that connects every nostr-core module to its spec. An agent that knows it needs NIP-57 zaps can look at the table and see: import nip57, read the spec at 57.md. No guessing. No searching.

The three layers work together. The agent navigates from "I need to implement zaps" to the right spec and the right import in two lookups.

Why Agents Need This

Every agent framework has the same fundamental problem: the agent knows what it wants to do but not where to find the information to do it correctly.

Consider an agent that needs to send a zap. Without navigation, it has to:

1. Search for "nostr zaps" and hope for good results
2. Figure out which NIP covers zaps (it's 57, but that's not obvious)
3. Find the spec URL (is it on GitHub? Which repo? What path?)
4. Figure out which nostr-core module implements it
5. Hope it didn't hallucinate any of the above

With navigate-nostr loaded, the same agent:

1. Checks the module map: zaps are nip57, spec is NIP-57
2. Fetches https://github.com/nostr-protocol/nips/blob/master/57.md
3. Imports nip57 from nostr-core

Three steps. No guessing. No hallucination. The skill turns an open-ended search problem into a lookup.

The Pattern

This follows a principle that applies beyond Nostr: agents work better when you give them navigation tools rather than knowledge dumps.

A skill that contains the full text of every NIP would be massive, stale within weeks, and would burn context window on information the agent may never need. A skill that teaches the agent how to fetch the right NIP on demand is small, stays current (the URL patterns don't change), and lets the agent pull exactly what it needs.

Teach agents where to look, not what to remember.

Try It

If you have nostr-core installed as a Claude Code plugin, the skill is already available:

/navigate-nostr

Or load it directly from the repo:

/plugin install nostr-core-org/nostr-core

The skill is a single markdown file. Read it yourself if you want to see what a navigation-first skill looks like. It's in skills/navigate-nostr/SKILL.md.

The protocol is big. The compass is small. That's the point.

GitHub . Skills Documentation

Media Without Middlemen

Upload, retrieve, mirror, delete. Content-addressed blobs on Blossom servers, authenticated with your Nostr key.

Your Media Shouldn't Depend on One Server

Every image you post on a centralized platform lives at their URL, on their servers, under their rules. The link breaks when they change their infrastructure. The file disappears when they decide it should.

Blossom is different. Files are identified by their SHA-256 hash. The same file on any Blossom server has the same address. If one server goes down, any other server with the file can serve it. Content-addressed, decentralized, no single point of failure.

nostr-core speaks Blossom natively.

What You Can Do

import { blossom } from 'nostr-core'

// Upload
const auth = blossom.createAuthEvent({
  action: 'upload',
  content: 'Upload image',
  expiration: Math.floor(Date.now() / 1000) + 300,
}, secretKey)

const blob = await blossom.uploadBlob('https://blossom.example', imageData, auth, 'image/png')
// blob.url, blob.sha256, blob.size

// Retrieve
const data = await blossom.getBlob('https://blossom.example', blob.sha256, '.png')

// Mirror to another server for redundancy
await blossom.mirrorBlob('https://backup.example', blob.url, mirrorAuth)

// Check, list, delete
await blossom.checkBlob('https://blossom.example', hash)
await blossom.listBlobs('https://blossom.example', pubkey)
await blossom.deleteBlob('https://blossom.example', hash, deleteAuth)

Six operations. Upload, get, check, list, delete, mirror. That covers every media workflow.

Auth Is Just a Nostr Event

Blossom uses kind 24242 events for authorization. You sign an event that says what you want to do, when it expires, and optionally which files and servers it applies to. The server verifies the signature. No API keys, no tokens to manage, no OAuth.

Your Nostr identity is your credential. If you can sign events, you can use Blossom.

What This Opens Up

A social client with native media. Users post images and videos. Your app uploads to their preferred Blossom servers (stored as a kind 10063 server list event). Files are content-addressed. If the user switches clients, their media is still there.

Redundant storage with one function call. Upload to your primary server. Mirror to a backup. Two servers, same hash, same file. If one dies, the other serves it.

A marketplace with product images. Sellers upload photos. Buyers see them. The images live on Blossom servers, identified by hash, authenticated by Nostr keys. No image hosting service needed.

An archive that can't disappear. Upload important files. Mirror them across multiple servers. The SHA-256 hash is the permanent address. As long as one server has the file, it's accessible.

Server Lists

Users publish a kind 10063 event listing their preferred Blossom servers. Your app reads it and knows where to upload and where to look.

// Publish server preferences
const list = blossom.createServerListEvent(
  ['https://blossom.example', 'https://backup.example'],
  secretKey
)

// Read someone's server list
const servers = blossom.parseServerList(event)

This means media storage is user-controlled. They pick their servers. Your app respects their choice.

Run Your Own, Charge for It

A Blossom server is infrastructure. Infrastructure you can monetize.

You run a server. You set the rules. Storage limits, file types, pricing. Users authenticate with their Nostr keys, upload media, and you earn for providing the service. No platform middleman taking a cut. No ad-supported model where you are the product.

Think of it like running a relay, but for media. Communities can run a shared Blossom server for their members. Photographers can offer premium storage. A podcast network can host episodes. A marketplace can store product images with redundancy built in.

The server operator controls the economics. Users control where their files go. Both sides get what they want.

The Pattern

nostr-core keeps giving you the same thing: protocol primitives that work without deep Nostr knowledge. You don't need to understand BUD specs or construct authorization headers by hand. Import, call, ship.

Payments with NWC. Ecash with NIP-60. Media with Blossom. Social with NIPs 1 through 29. Identity, encryption, relay management. It's all the same package, the same types, the same patterns.

Build the thing you actually want to build. nostr-core handles the protocol.

Content-addressed media. Nostr-authenticated. No middlemen.

GitHub

Two Wallets, One Protocol

NIP-47 connects you to a remote wallet. NIP-60 carries one with you. Together they cover every payment scenario on Nostr.

Different Problems, Same Network

Payments on Nostr have two shapes.

Sometimes you need to talk to a wallet that lives somewhere else. Send a command, get a result. That's NIP-47. Nostr Wallet Connect.

Sometimes you need the wallet right here. Tokens you hold, ready to spend, no remote call. That's NIP-60. Ecash on Nostr.

These aren't competing approaches. They solve different things.

NIP-47: The Remote Wallet

NWC is how you reach Lightning infrastructure you don't run yourself. A wallet provider, a self-hosted node, or a Cashu mint bridged through NUTbits. Your app sends requests over Nostr relays. The wallet executes them.

const nwc = new NWC('nostr+walletconnect://...')
await nwc.connect()
await nwc.payInvoice('lnbc...')

Pay invoices. Create invoices. Check balances. Listen for incoming payments. Lightning Address resolution and fiat conversion built in. The NWC class handles encryption negotiation, request matching, typed errors, the full NIP-47 surface.

NWC is powerful when the wallet needs to be always-on. Receiving zaps while you're offline. Routing payments through the Lightning Network. Connecting to infrastructure with liquidity you didn't have to manage.

NIP-60: The Local Wallet

NIP-60 flips the model. The wallet lives in your Nostr identity. Ecash proofs stored as encrypted events on relays. Your keys decrypt them. Your client spends them.

import { nip60 } from 'nostr-core'

// Fetch wallet from relays
const filters = nip60.getWalletFilters(pubkey)

// Parse token events
const token = nip60.parseTokenEvent(event, secretKey)
const balance = nip60.getProofsBalance(token.proofs)

// Record a transaction
const history = nip60.createHistoryEvent(
  { direction: 'out', amount: '1000', unit: 'sat', events: [...] },
  secretKey
)

No remote service for basic operations. You hold bearer tokens. Spending means constructing a transaction with proofs you already have. The mint verifies and settles.

Switch clients. Switch devices. Log in with your Nostr key and your balance is there. The proofs live on relays, encrypted, waiting.

Where Each One Fits

NWC shines when:

• You need Lightning Network access
• Your app delegates payment execution to infrastructure
• You need the wallet always-on for incoming payments
• You're integrating with services that speak BOLT-11

NIP-60 shines when:

• Payments should be portable across clients and devices
• Privacy matters (bearer tokens, blind signatures)
• You're building peer-to-peer transfers in a community
• The wallet should follow the user's identity, not a device

Both at Once

The interesting part is an app that supports both.

A social client uses NIP-60 for quick transfers between users. Ecash tokens, instant, private, no Lightning routing. The same client uses NWC for receiving zaps from the wider network, paying invoices, bridging to Lightning.

Small payments stay local. Larger payments route through Lightning. The user just sends sats. The app picks the path.

A marketplace where buyers hold ecash in a NIP-60 wallet for instant checkout. But the seller receives via NWC into their Lightning node for settlement. Both wallets, one transaction, seamless.

And here's a nice detail: a Cashu mint operator running NUTbits can serve both sides. NIP-60 users hold ecash from that mint directly. NWC users connect to the same mint through a NUTbits connection string. Same mint infrastructure, both wallet protocols, one operator.

One Toolkit

nostr-core has both. The NWC class for remote wallet operations. The nip60 module for local ecash. Same types, same relay layer, same NIP-44 encryption stack underneath.

import { NWC, nip60 } from 'nostr-core'

That's two wallet primitives in one import. Build apps that use either or both.

Remote and local. Lightning and ecash. Two wallets, one toolkit.

GitHub · NUTbits

Ecash on Nostr

Your wallet state lives on relays. Your proofs travel with your keys. No sync service. No device lock-in.

Wallets Have a Location Problem

Most wallets live on a device. Your phone, your laptop, a browser extension. The data sits in local storage. Lose the device, lose access. Switch devices, export and import. Use two devices, figure out sync.

NIP-60 stores wallet state as encrypted Nostr events. The same relays your social graph already lives on.

How It Works

A NIP-60 wallet is four event kinds working together.

Kind 17375 is the wallet itself. A replaceable event that holds the wallet's private key and a list of trusted mints. Encrypted to yourself with NIP-44. Only your Nostr key can read it.

Kind 7375 is a token event. Each one holds unspent Cashu proofs for a single mint. Encrypted to self. This is where your actual balance lives, spread across however many token events you've accumulated.

Kind 7376 is spending history. Records transactions with direction, amount, and references to the token events involved. The created and destroyed proofs are encrypted. Redeemed markers stay in plain tags so relays can filter.

Kind 7374 is a quote event. Tracks pending mint quotes while a Lightning payment is in-flight. Uses NIP-40 expiration so stale quotes clean themselves up.

All encrypted content uses NIP-44's self-encryption pattern: derive a conversation key from your secret key to your own public key. Relays see encrypted blobs. Nobody else can read your wallet.

What This Gets You

Log in with your Nostr key on any client that supports NIP-60. Your proofs are on the relays. Decrypt, sum the balances, show the wallet. No import file. No cloud backup. No sync service.

Switch from one Nostr client to another. Your ecash follows your identity, not your device.

Build a social client that also holds ecash. The user's proofs are already on the relays you're connected to. Read the token events, decrypt, show a balance. Spending means constructing a transaction with proofs the user already holds.

nostr-core Has It

The implementation lives in nip60.ts. Create wallets, store tokens, record history, manage quotes, delete spent proofs, build relay filters. Typed end-to-end.

import { nip60 } from 'nostr-core'

// Create a wallet event
const wallet = nip60.createWalletEvent(
  { privkey: walletKey, mints: ['https://mint.example.com'] },
  secretKey
)

// Store ecash proofs
const token = nip60.createTokenEvent(
  { mint: 'https://mint.example.com', proofs: [...], unit: 'sat' },
  secretKey
)

// Sum a balance
const balance = nip60.getProofsBalance(proofs)

// Fetch wallet state from relays
const filters = nip60.getWalletFilters(pubkey)

Self-encryption, token deletion for spent proofs, history tracking with proper marker separation. The same NIP-44 encryption stack the rest of nostr-core uses.

The Trust Model

Cashu ecash is custodial at the mint level. The mint holds the Bitcoin. NIP-60 doesn't change that. It changes where the wallet state lives, not the trust relationship.

Multi-mint support helps. Your wallet can hold proofs from different mints. One mint goes down, you lose that mint's ecash, not everything.

Ecash gives you privacy and portability. It asks you to trust a mint. Whether that works depends on your use case. Both things are true at the same time.

The Bridge Already Exists

If you run a Cashu mint and want to make it available as an NWC wallet, NUTbits does exactly that. It connects to your mint on one side and speaks Nostr Wallet Connect on the other. Any app that supports NWC sees a wallet. Your mint handles the Lightning.

That means a NIP-60 wallet holding ecash from your mint, and an NWC connection powered by the same mint through NUTbits, can coexist. Local ecash for direct transfers. NWC for Lightning reach. Same mint, two protocols, full coverage.

Ecash wallets on Nostr relays. Encrypted, portable, ready.

GitHub · NUTbits

Lightning Without the Lightning Code

You don't need to understand Lightning internals to accept and send payments. A connection string and five methods cover most use cases.

Lightning Is Powerful and Complicated

If you've ever set up a Lightning node, you know. Channel management, liquidity, routing, watchtowers, backups. It's powerful infrastructure, but it's a lot to take on when all you wanted was "let users pay for things."

Most app developers don't need to run a node. They need a payment API. Something that takes "pay this" and returns "paid," without requiring a degree in Lightning Network topology.

That's what NWC gives you. And nostr-core makes NWC trivial.

The Connection String Is the Config

Someone else runs the wallet infrastructure. Maybe it's a service like Alby. Maybe it's a self-hosted setup. Maybe it's a Cashu mint behind NUTbits. You don't need to know or care.

They give you a connection string:

nostr+walletconnect://pubkey?relay=wss://...&secret=hex

That string contains the wallet's identity, the relay to communicate through, and your secret key. Paste it into nostr-core, and you have a wallet.

const nwc = new NWC(connectionString)
await nwc.connect()

Done. No node setup. No channel management. No liquidity planning.

Five Methods for Most Apps

The reality is that most applications need a small set of payment operations. nostr-core covers them:

Check the balance:

const { balance } = await nwc.getBalance()

Pay an invoice:

const { preimage } = await nwc.payInvoice('lnbc...')

Create an invoice:

const { invoice } = await nwc.makeInvoice({ amount: 50000, description: 'Premium access' })

Pay a Lightning address:

await nwc.payLightningAddress('creator@example.com', 500)

Listen for incoming payments:

nwc.on('payment_received', (data) => {
  // Unlock content, update balance, send notification
})

That's it for most apps. A membership site needs makeInvoice and payment_received. A tipping feature needs payLightningAddress. A wallet dashboard needs getBalance and listTransactions.

Fiat Conversion, Built In

Sometimes your users think in dollars, not sats. nostr-core handles conversion:

const { sats, rate } = await nwc.payLightningAddressFiat('shop@example.com', 25, 'usd')
console.log(`Paid ${sats} sats at $${rate}/BTC`)

Twenty-five dollars, converted to sats at the current rate, paid to a Lightning address. No extra dependencies. No separate API call for the exchange rate.

What You Don't Write

Here's what nostr-core handles that you'd otherwise implement yourself:

• WebSocket connection to the Nostr relay
• Event creation, signing, and serialization
• Encryption negotiation (NIP-04 vs NIP-44)
• Request/response matching over async relay messages
• Timeout handling with specific error types
• Lightning Address resolution (LNURL-pay flow)
• Fiat-to-sats conversion via exchange rate API
• Connection lifecycle and cleanup

That's not a small amount of code. And it's the kind of code where subtle bugs create real problems: payments that hang, connections that leak, encryption that silently downgrades.

nostr-core has solved these problems once, with proper error handling and typed responses. You get the result.

When You Need More

The NWC class covers the common cases. But nostr-core also exports the building blocks for when you need finer control.

Want to build a custom zap flow? NIP-57 exports zap request and receipt functions. Want to manage relay connections yourself? The Relay and RelayPool classes are available. Want to handle encryption manually for a specific use case? NIP-04 and NIP-44 are exported directly.

The high-level API gets you moving. The low-level exports let you go wherever you need.

Payments Are Just Another Feature

The best payment integration is the one your users don't think about. They click "pay," it works, they move on.

nostr-core makes that possible by keeping the developer side equally simple. Import the class, connect with a string, call the method. The Lightning complexity stays where it belongs: in the wallet infrastructure, not in your application code.

Lightning payments. One import. One connection string. npm install nostr-core

GitHub · API Docs

Nostr Needs Boring Infrastructure

The protocol is interesting. The libraries should be boring. That's a good thing.

Nostr works because the protocol is simple. Events, signatures, relays. A few primitives that combine into something much larger than the sum of their parts.

The problem has never been the protocol. The problem is the layer between the protocol and the applications people want to build. That layer (the libraries, the tooling, the shared infrastructure) is where projects succeed or stall.

I've been thinking about what it means to build that layer well.

Simple Protocols Need Simple Tools

There's a temptation, when building developer tools for a new protocol, to add value by adding complexity. Convenience wrappers that hide the protocol. Abstractions that "simplify" things by replacing one mental model with another. Integrations with specific services because that's what users want right now.

Each of these is a reasonable decision in isolation. Together, they produce a tool that's harder to understand than the protocol it wraps.

nostr-core takes a different approach. The API mirrors the protocol. NIP-01 is events and relays. NIP-19 is encoding. NIP-44 is encryption. NIP-47 is wallet connect. The library is organized by NIP number because the protocol is organized by NIP number.

That's boring. It's supposed to be.

When you read nostr-core code, you're reading the protocol with types. When something goes wrong, you can check the NIP spec directly because the library doesn't reinterpret it. When a NIP updates, the corresponding module updates. The mapping is one-to-one.

The Cost of Vendor Coupling

I notice a pattern in developer ecosystems. A company builds a useful service. They release an SDK. The SDK is good (great, even) but it assumes their service. The types carry their branding. The auth flow requires their platform. The errors reference their dashboard.

Developers adopt it because it works. Then they're coupled to a service they chose for convenience, not for technical reasons. Switching costs accumulate quietly.

Nostr was designed to avoid this. The protocol is open. Relays are interchangeable. Wallets communicate through a standard protocol. But if the dominant library for that protocol is coupled to a specific wallet provider, the vendor-neutrality of the protocol doesn't matter in practice.

nostr-core is deliberately vendor-neutral. Not because vendor-specific tools are bad (they serve their users well) but because the ecosystem also needs a tool that serves the protocol itself.

Forty-Eight NIPs Is an Investment

Implementing forty-eight NIPs in a single, coherent package is not exciting work. Each NIP has its own edge cases, its own type requirements, its own relationship to other NIPs. Getting the types right across all of them, making them compose naturally, ensuring the encryption modules work the same way everywhere. That's infrastructure work.

It's the kind of work that makes everything else easier. A developer building a social client doesn't need to think about NIP-10 thread parsing or NIP-44 encryption details. They import the module and use it. The protocol complexity is resolved once, in the library, not repeatedly in every application.

That's what infrastructure does. It absorbs complexity so applications don't have to.

Trust Models Should Be Explicit

nostr-core's cryptography comes from Paul Miller's noble libraries. That's a specific choice with specific properties: audited code, minimal implementations, no unnecessary dependencies.

Seventy-nine total dependencies. One hundred thirty-two packages in the full tree. Those are numbers you can actually audit. You can read the dependency list in a few minutes and know what you're shipping.

Is it perfectly minimal? No. Could the dependency count be lower? Probably. But it's in a range where a team can make informed decisions about their supply chain. That matters when you're handling keys and payments.

What I Think nostr-core Gets Right

It maps cleanly to the protocol. It doesn't add unnecessary abstractions. It works with any wallet, any relay, any signer. It ships the full NIP surface so developers don't need to assemble it from parts. It's typed end-to-end.

These aren't flashy properties. They're the properties of infrastructure that ages well.

What It Gets Wrong, or Doesn't Solve Yet

The Nostr protocol is still evolving. Some NIPs in nostr-core will change as the community refines them. That's unavoidable and healthy, but it means the library is a moving target for anyone building production software.

There are also NIPs that nostr-core doesn't implement yet. The long tail of Nostr proposals is long, and protocol completeness is a moving goalpost.

And nostr-core is one library in one language. Nostr needs the same quality of tooling in Rust, Python, Swift, Kotlin, Go. The ecosystem is bigger than any single package.

Infrastructure Ages Differently

Flashy tools get attention when they launch. Infrastructure gets attention when it breaks. Or more precisely, it earns trust by not breaking.

nostr-core isn't trying to be the most exciting project in the Nostr ecosystem. It's trying to be the most reliable foundation for the applications that are. A boring, complete, honest implementation of the protocol that developers can build on without thinking about it.

Nostr needs interesting applications. It needs boring infrastructure.

That's what this is.

GitHub

Forty-Eight NIPs, One Import

Most Nostr libraries give you the basics. nostr-core gives you the protocol.

The NIP Problem

Every Nostr app starts simple. You need events, keys, and a relay connection. Any library can do that.

Then your app grows. You need encrypted DMs. You need zaps. You need relay list management. You need calendar events for that community feature someone requested. You need badge verification for that trust system you're building.

Each NIP is a separate capability. In most ecosystems, that means a separate dependency, or implementing it yourself from the spec. You end up with a patchwork of libraries at different versions with different conventions, or a growing folder of hand-rolled protocol code.

One Package, Forty-Eight NIPs

nostr-core ships forty-eight NIP implementations in a single package. Not wrappers around other libraries. Not partial implementations. Complete, typed modules that work together.

Here's a sample of what's available by category:

Core protocol: NIP-01 events, NIP-02 contact lists, NIP-09 deletions, NIP-10 threads, NIP-13 proof of work, NIP-42 relay auth

Identity: NIP-05 DNS verification, NIP-06 mnemonic keys, NIP-07 browser extensions, NIP-19 bech32 encoding, NIP-46 remote signers

Encryption: NIP-04 (AES-CBC), NIP-44 (ChaCha20-Poly1305), NIP-59 gift wrapping, NIP-17 private messages

Social: NIP-18 reposts, NIP-22 comments, NIP-23 long-form content, NIP-25 reactions, NIP-27 text references, NIP-28 channels, NIP-29 groups

Payments: NIP-47 wallet connect, NIP-57 zaps, NIP-75 zap goals, Lightning addresses, LNURL, fiat conversion

Lists & metadata: NIP-24 extended metadata, NIP-30 custom emoji, NIP-31 alt text, NIP-36 content warnings, NIP-40 expiration, NIP-51 lists, NIP-65 relay lists

Community: NIP-52 calendar events, NIP-56 reporting, NIP-58 badges

Infrastructure: NIP-11 relay info, NIP-48 proxy, NIP-50 search, NIP-98 HTTP auth

Every module exports typed functions. Every function produces valid Nostr events. Every event works with the relay and signer abstractions in the same package.

Why This Matters

No version conflicts. When NIP-57 zaps need NIP-01 events and NIP-19 encoding, they're all at the same version, built from the same types. No compatibility matrix to manage.

Discoverability. Need calendar events? It's nip52. Need badges? It's nip58. The naming is the NIP number. You don't search npm for "nostr calendar" and hope you find a maintained package.

Composability. NIPs reference each other constantly. Gift wrapping (NIP-59) uses encryption (NIP-44). Zaps (NIP-57) use events and encoding. Private lists (NIP-51) use encryption for private items. When these all live in one package, composition is natural, not an integration project.

Tree-shaking. ESM-only means your bundler only includes what you import. Using three NIPs? You ship three NIPs. The other forty-five don't touch your bundle.

What "Protocol Complete" Means

It means you can build any Nostr application from a single dependency. A social client. A wallet. A relay management tool. A marketplace. A calendar app. A badge system. A community platform.

It also means when a new feature requires a NIP you haven't used yet, you don't go shopping for a new library. You add an import line.

// Today: social client
import { finalizeEvent, nip10, nip25, Relay } from 'nostr-core'

// Tomorrow: add zaps
import { finalizeEvent, nip10, nip25, nip57, NWC, Relay } from 'nostr-core'

// Next week: add calendar events
import { finalizeEvent, nip10, nip25, nip57, nip52, NWC, Relay } from 'nostr-core'

Same package. Same types. Same patterns. Your dependency list doesn't grow with your feature set.

Not Every NIP Is Finished

Nostr is an evolving protocol. Some NIPs are stable and battle-tested. Others are newer, still being refined by the community. nostr-core tracks the specs as they develop.

If a NIP changes, nostr-core updates. One package to update, one changelog to read, one set of breaking changes to handle. That's simpler than tracking fifteen separate libraries.

The Alternative

You could assemble your own stack. Pick a core library for events. Find a separate package for NIP-44 encryption. Another for NIP-19 encoding. Write your own NIP-52 calendar implementation because nobody published one. Hope they all use compatible types.

That works. People do it. But it's more work, more risk, and more maintenance for the same result.

Or you can install nostr-core and start building.

Forty-eight NIPs. One package. Zero assembly required.

GitHub · API Reference

The Library That Doesn't Lock You In

No OAuth. No API keys. No vendor. Just the protocol.

Vendor Lock-In Is a Quiet Problem

It doesn't happen all at once. You pick an SDK because it's convenient. The docs are good. The getting-started example works in five minutes.

Then you notice the OAuth flow is specific to that provider. The error messages reference their dashboard. The WebSocket connection goes through their relay. The types assume their wallet service.

You're not building on a protocol anymore. You're building on someone's product. And the moment they change their terms, raise prices, or pivot, your app feels it.

nostr-core Is Protocol-Only

There's no account to create. No API key to manage. No OAuth flow to implement. No webhooks to configure on someone else's platform.

nostr-core implements Nostr protocols (NIPs) and nothing else. When you connect to a wallet, you use a standard NWC connection string. When you connect to relays, you use standard WebSocket URLs. When you sign events, you use standard Nostr keys.

Every piece is interchangeable. Switch wallets by changing a connection string. Switch relays by changing a URL. Switch signers by swapping the signer implementation. Your code doesn't change.

The Comparison Worth Making

The most common alternative for NWC integration is @getalby/sdk. It's a good library, built by good people. But it carries Alby's product assumptions with it.

Here's what the numbers look like:

nostr-core is 26% smaller, has 82% fewer packages, and 81% fewer total dependencies. Those aren't abstract metrics. Fewer dependencies mean fewer supply chain risks, faster installs, and less to audit.

But the real difference isn't size. It's coupling.

@getalby/sdk works great if you're building for Alby users. It provides OAuth flows, webhook handling, and Alby-specific features. If that's your use case, use it.

If you're building for everyone (any wallet, any relay, any signer), nostr-core is the tool that doesn't assume who your users are.

What "No Lock-In" Looks Like in Practice

Wallet portability. Your users connect with any NWC-compatible wallet. Alby, Mutiny, custom setups. nostr-core doesn't care. One connection string, one API.

Relay independence. Connect to whatever relays make sense for your app. Public relays, private relays, self-hosted relays. The relay abstraction works with all of them.

Signer flexibility. Use a secret key directly, a NIP-07 browser extension, or a NIP-46 remote signer. The signer interface is the same regardless.

Runtime freedom. Node 18+, Deno, Bun, Cloudflare Workers. ESM-only, no polyfills needed. Deploy wherever your app lives.

The Trade-Off

Being vendor-neutral means nostr-core doesn't give you vendor-specific features. There's no Alby OAuth flow. No managed webhook endpoints. No dashboard integration.

If you need those things, you either build them yourself or use the vendor's SDK. That's a real trade-off, and it's worth being clear about it.

For most NWC use cases (connecting a wallet, making payments, listening for transactions), you don't need vendor features. You need the protocol. nostr-core gives you the protocol and gets out of the way.

The Dependency Story

nostr-core's cryptography comes from Paul Miller's noble libraries. secp256k1, SHA-256, ChaCha20, AES-CBC. All audited, all minimal, all widely trusted in the Bitcoin ecosystem.

That's a deliberate choice. When your dependency tree is small and audited, you can actually review what you're shipping. Seventy-nine packages is a number a team can audit. Six hundred and ninety-eight is not.

Pick Your Protocol, Not Your Provider

Nostr is a protocol. Lightning is a protocol. NWC is a protocol. The whole point of building on open protocols is that you're not dependent on any single provider.

nostr-core is built to preserve that property. Use it with any wallet, any relay, any runtime, any signer. Swap any piece without touching the rest.

That's not a feature. That's just what protocol-level tooling should be.

No vendor. No lock-in. Just Nostr. npm install nostr-core

GitHub · Comparison Guide

Build a Nostr Client From Scratch

Everything you need for a social client lives in one import. Keys, events, relays, encryption, threads, reactions. All typed, all ready.

Start With Keys

Every Nostr identity is a keypair. nostr-core generates them from audited cryptography:

import { generateSecretKey, getPublicKey } from 'nostr-core'

const sk = generateSecretKey()
const pk = getPublicKey(sk)

That's your user. The secret key signs events. The public key is their identity. No accounts, no registration, no server.

If you want human-readable identifiers, NIP-19 encoding is built in:

import { nip19 } from 'nostr-core'

const npub = nip19.npubEncode(pk)   // npub1...
const nsec = nip19.nsecEncode(sk)   // nsec1...

For users who want to import from a mnemonic phrase, NIP-06 handles BIP-39 derivation. For browser extensions, NIP-07 provides a signer interface that never exposes the private key to your app.

Connect to Relays

Nostr is a relay network. Your client needs to talk to relays to publish and receive events.

import { Relay, RelayPool } from 'nostr-core'

// Single relay
const relay = new Relay('wss://relay.damus.io')
await relay.connect()

// Or a pool of relays
const pool = new RelayPool(['wss://relay.damus.io', 'wss://nos.lol'])

Publish events, subscribe to filters, handle connections. The relay abstraction manages the WebSocket lifecycle so you can focus on your application logic.

Sign and Publish Events

Events are the atoms of Nostr. A social post is a kind-1 event. A reaction is kind-7. A repost is kind-6. nostr-core gives you typed event creation for all of them.

import { finalizeEvent } from 'nostr-core'

const event = finalizeEvent({
  kind: 1,
  content: 'Hello from nostr-core',
  created_at: Math.floor(Date.now() / 1000),
  tags: [],
}, sk)

finalizeEvent signs the event, computes the hash, and returns a complete, valid Nostr event ready to publish.

Threads and Mentions

Social apps need threading. NIP-10 defines how replies reference parent events:

import { nip10 } from 'nostr-core'

// Parse thread references from an event
const refs = nip10.parse(event)
// refs.root - the top-level event
// refs.reply - the immediate parent
// refs.mentions - other referenced events

Build reply chains, render conversation trees, show quoted posts. The tag parsing is handled for you.

Reactions and Reposts

NIP-25 reactions let users respond to content:

import { nip25 } from 'nostr-core'

const reaction = nip25.createReaction(originalEvent, '+')
const signed = finalizeEvent(reaction, sk)

NIP-18 reposts work the same way: create the event template, sign it, publish it. The NIP modules give you correctly structured events every time.

Encrypted Messages

Private messaging is where nostr-core's encryption stack comes together. NIP-17 provides fully sealed, metadata-protected messages using gift wrapping:

import { nip17 } from 'nostr-core'

const wrapped = await nip17.wrapEvent(senderSk, recipientPk, 'secret message')

Under the hood, this uses NIP-44 encryption (ChaCha20-Poly1305) and NIP-59 gift wrapping to protect both the content and the metadata. The recipient unwraps it with their key. Relays see nothing useful.

For simpler use cases, NIP-04 encryption is also available, though NIP-44 is recommended for new applications.

Long-Form Content

Building a blog platform or article reader? NIP-23 handles long-form content with metadata:

import { nip23 } from 'nostr-core'

const article = nip23.createArticle({
  title: 'My First Post',
  content: 'Full markdown content here...',
  summary: 'A brief summary',
  image: 'https://example.com/header.jpg',
  publishedAt: Math.floor(Date.now() / 1000),
  tags: ['nostr', 'development'],
  slug: 'my-first-post',
})

Titles, summaries, images, tags, slugs. Everything a publishing platform needs.

Payments Built In

Your social client probably wants zaps. nostr-core's NWC class handles wallet integration:

import { NWC, nip57 } from 'nostr-core'

const nwc = new NWC('nostr+walletconnect://...')
await nwc.connect()

// Pay an invoice from a zap flow
await nwc.payInvoice(zapInvoice)

NIP-57 zap requests and receipts are also exported, so you can build the full zap UI: request creation, receipt verification, zap counts on posts.

The Point

A Nostr client needs a lot of protocol pieces. Key management, relay connections, event signing, threading, reactions, encryption, payments. In most ecosystems, that's five or six different libraries with incompatible types and different release cycles.

With nostr-core, it's one package. The pieces are designed to work together because they were built together. Types flow through naturally. Modules compose without adapters.

You focus on what makes your client unique. nostr-core handles the protocol.

Start building. npm install nostr-core and go.

GitHub · Demo

One Class, One Connection String

The entire NWC spec in five lines of code. That's not a simplification; it's the actual API.

Payment Integration Shouldn't Be Hard

Every payment integration story starts the same way. You read the docs. You install the SDK. You create an account. You get API keys. You configure webhooks. You handle OAuth flows. You write error handling for seventeen different failure modes.

By the time you've sent your first payment, you've written more infrastructure code than product code.

NWC was designed to be simpler than that. And nostr-core takes that simplicity seriously.

Five Lines

import { NWC } from 'nostr-core'

const nwc = new NWC('nostr+walletconnect://...')
await nwc.connect()
const { preimage } = await nwc.payInvoice('lnbc...')
nwc.close()

That's a complete payment. Import, connect, pay, close.

The connection string contains everything: the wallet's public key, the relay to communicate through, and your secret key. No separate config files. No environment variables for client IDs and secrets. One string.

What the NWC Class Handles

Behind those five lines, nostr-core is doing real work.

Encryption auto-detection. Some wallets use NIP-04 (AES-CBC). Others support NIP-44 (ChaCha20). nostr-core checks what the wallet supports and uses the best available option. You don't configure this. It just works.

Relay management. The class connects to the relay specified in the connection string, subscribes to the right filters, and handles the WebSocket lifecycle. Reconnection, subscription management, cleanup on close.

Request/response matching. NWC is asynchronous over Nostr relays. nostr-core matches each response to its request, handles timeouts, and surfaces errors through a typed hierarchy.

Event signing. Every NWC request is a signed Nostr event. nostr-core handles the signing, serialization, and verification internally.

You don't see any of this. You see payInvoice() and get a preimage back.

The Full Surface

The NWC class exposes every NIP-47 method:

• getBalance() - how much is in the wallet
• payInvoice() - pay a BOLT-11 invoice
• makeInvoice() - create an invoice to receive
• listTransactions() - payment history
• payKeysend() - pay a node directly
• payLightningAddress() - resolve and pay a Lightning address
• payLightningAddressFiat() - convert fiat to sats and pay
• getInfo() - wallet metadata
• getBudget() - spending limits
• signMessage() - sign with the wallet key

Plus event listeners for real-time payment notifications:

nwc.on('payment_received', (notification) => {
  console.log('Incoming:', notification.notification.amount, 'msats')
})

That's the full wallet API. One class, one import.

Errors That Tell You What Happened

When something goes wrong, you get a specific error, not a generic exception with a string message.

try {
  await nwc.payInvoice('lnbc...')
} catch (err) {
  if (err instanceof NWCWalletError) {
    // The wallet said no: insufficient balance, expired invoice, etc.
  } else if (err instanceof NWCTimeoutError) {
    // Wallet didn't respond in time
  } else if (err instanceof NWCConnectionError) {
    // Couldn't reach the relay
  }
}

Eight error classes in a clean hierarchy. Your error handling can be as specific or as general as you need.

Lightning Addresses in One Call

Lightning Address resolution normally means fetching a well-known URL, parsing the LNURL response, creating an invoice, then paying it. nostr-core wraps that entire flow:

await nwc.payLightningAddress('user@example.com', 1000)

One thousand sats to a Lightning address. One line.

Need fiat conversion? That's built in too:

await nwc.payLightningAddressFiat('user@example.com', 5, 'usd')

Five dollars, converted to sats at the current rate, paid to a Lightning address. Still one line.

The DX Argument

Developer experience isn't about making things pretty. It's about reducing the distance between your intention and your code.

If you want to pay an invoice, the code should say "pay this invoice." If you want to listen for payments, the code should say "when a payment arrives, do this." The protocol complexity should be invisible unless you need to see it.

That's what one class and one connection string gives you. The intent is the code.

Start with npm install nostr-core and a connection string. That's all you need.

GitHub · API Docs

What nostr-core Actually Is

You want to build on Nostr. You don't want to fight the protocol to get there.

The Problem Is Familiar

You've seen Nostr. You like the idea: decentralized social, payments over Lightning, identity without platforms. You want to build something.

So you look at the ecosystem. There are libraries, but they tend to fall into two camps: minimal utilities that leave you wiring things together yourself, or vendor-specific SDKs that come with someone else's opinions baked in.

You just want the protocol. All of it. In one package. With types.

That's nostr-core

nostr-core is a JavaScript/TypeScript toolkit that implements 48 NIPs in a single package. Core protocol, encryption, encoding, social features, payments, identity, calendar events, badges, moderation. It's all there.

One install. One import. The protocol is ready to use.

import { NWC, nip19, finalizeEvent, Relay } from 'nostr-core'

That gives you wallet payments, bech32 encoding, event signing, and relay connections. No glue code. No adapter packages. No "install these seven other things first."

Who It's For

Developers building Nostr applications. That's broad on purpose.

If you're building a social client, you need events, reactions, reposts, threads, long-form content, encrypted DMs, relay management. nostr-core has all of that.

If you're building a payment flow, you need NWC, Lightning addresses, zaps, invoices, fiat conversion. nostr-core has all of that too.

If you're building something weird that touches badges and calendar events and proof of work? Still covered.

The point is: whatever combination of NIPs your app needs, they're already here, already typed, already working together.

What It's Built On

The cryptography comes from Paul Miller's noble libraries, the same audited primitives the wider Bitcoin ecosystem trusts. secp256k1, schnorr signatures, SHA-256, ChaCha20, AES-CBC. Peer-reviewed, minimal, no surprises.

The rest is protocol implementation. Each NIP is its own module, but they share types and compose naturally. NIP-59 gift wrapping uses NIP-44 encryption. NIP-57 zaps use events and relays. Everything connects because it was designed to.

What It Doesn't Do

nostr-core is headless. No UI components, no framework bindings, no opinions about how your app should look or work. It gives you the protocol layer and gets out of the way.

It also doesn't phone home, require API keys, or depend on any specific service. It connects to whatever relays you point it at, signs with whatever keys you give it, and talks to whatever NWC wallet you configure.

If your app needs React components or a specific hosting platform, that's your call. nostr-core just handles the Nostr part.

The Shape of the API

The high-level entry point is the NWC class. One connection string, and you have a working wallet interface. Pay invoices, create invoices, check balances, listen for payments.

Below that, everything is exported as building blocks. Key generation, event signing, relay connections, encryption, encoding. Use the high-level class or reach for the primitives directly. Both paths are supported and typed.

// High level
const nwc = new NWC('nostr+walletconnect://...')
await nwc.connect()
await nwc.payInvoice('lnbc...')

// Low level
const sk = generateSecretKey()
const event = finalizeEvent({ kind: 1, content: 'hello', ... }, sk)

Try It

npm install nostr-core

Node 18+, Deno, Bun, Cloudflare Workers. ESM-only, tree-shakeable, fully typed.

Read the code, check the types, build something. The protocol is ready when you are.

GitHub · Demo