Interop

It's just Nostr.

The Lightning FM catalog is ordinary signed Nostr events on an open-read relay, with media on an ordinary Blossom server. Any client, relay, or agent can consume all of it. This page documents the few places where we extend the standards, so you don't have to reverse-engineer anything.

ENDPOINTS

·wss://relay.lightning.fm: the catalog relay. Reads open to everyone; writes restricted to onboarded artists (see Relay policy).

·https://media.lightning.fm: Blossom media server. Public reads by sha256; uploads restricted to onboarded artists.

·/.well-known/nostr.json: NIP-05 names for artists on this domain.

·/.well-known/lnurlp/{name}: LNURL-pay resolver. It forwards to the Lightning address the artist published in their own profile. We resolve names; we never hold funds.

EVENT KINDS AT A GLANCE

·kind 0: artist profile. Plain NIP-01/NIP-24 metadata with the standard nip05 (NIP-05) and lud16 (LUD-16) fields. Nothing custom.

·kind 10002: relay list, NIP-65. Nothing custom.

·kind 31337: a track. Addressable music event, the interesting one; full contract below.

·kind 30402: a sale listing, NIP-99 classifieds plus three tags of ours; contract below.

·kind 24242: Blossom upload authorization, BUD-02.

·kind 5: deletions, NIP-09. The relay honors them.

TRACKS (KIND 31337)

31337 has no merged NIP: a community registry definition and a draft NIP (nips PR #1043, closed 2026-08 without merging) disagreed about required tags. We emit a superset so readers of either dialect parse our tracks, and we are preparing a successor proposal based on this shipped contract. Events are addressable: the d tag is the track's stable identity and republishing replaces.

dtrack slug, the stable addressable identity

title / subjecttrack title (same value in both; subject is for PR-#1043 readers)

type"audio" (registry-required pair with media)

url / mediaaudio URL (same value; media is the registry/PR name for it)

xsha256 of the audio file, the content address

mmime type, e.g. audio/mpeg

sizeaudio bytes

imetaNIP-92: url/m/x/size packed into one tag for PR-#1043 readers

duration ?seconds

image ?artwork URL

lightning_node_id ?artist's Lightning node pubkey, when they run one

album, genre, year, credits, isrc, lyrics, explicit, track_number, t ?descriptive metadata; present only when the artist filled it in (t = plain hashtags)

alt, artist, bitrate, format, released ?kind-36787 vocabulary alignment so existing music clients parse us unmodified (values like "320kbps", "flac"; tag names only, not the kind)

To play a track you need exactly: url, x, m. Event content, when non-empty, is the artist's description. Events carry a NIP-89 client tag.

SALE LISTINGS (KIND 30402)

Standard NIP-99: d, title, price (["price","1500","sats"]), status, t. Plus three of ours:

product_type"track" or "album"

acoordinate of the 31337 track(s) being sold, as 31337:<pubkey>:<slug>

endpointbase URL of the checkout gate that fulfills this listing

The checkout itself is an HTTP protocol at the endpoint, not a NIP: the gate has the buyer pay an invoice minted by the artist's own wallet, confirms settlement via LUD-21, and then releases the download. The money routes buyer → artist; the platform can't take a cut, structurally. The full gate API ships documented with the self-hosted release. Until then, write us if you're building against it.

MEDIA (BLOSSOM)

·Reads: standard BUD-01: GET/HEAD https://media.lightning.fm/<sha256>. Bare-hash URLs work, extensions optional. BUD-03 lists at /list/<pubkey>.

·Uploads: BUD-02 PUT /upload with kind-24242 auth, restricted to onboarded artists, plus one extra requirement: an X-SHA-256 header with the blob hash. Stock Blossom tooling that omits it gets a clear 400.

·Addressing: blobs are content-addressed; the sha256 in a track's x tag is the same hash you fetch from the media server.

RELAY POLICY

·Reads: open. Sync, mirror, index: all welcome. Deletions (kind 5) are honored, so mirrors that honor NIP-09 stay consistent with us.

·Writes: restricted to onboarded artists' pubkeys. Anything else is rejected with a message pointing here. It's an anti-junk policy, not a walled garden; the same events are on public relays too.

·Onboarding: artists get relay, media, and checkout access together.

Start selling

Questions, or building a client against this? hello@lightning.fm. This page changes rarely and versions with the wire format.