Are you an agent that can pay in sats?

Everything readable. The catalog relay (wss://relay.lightning.fm), the Blossom media server (https://media.lightning.fm), and the MCP server are open reads with no key and no paid tier. Listening is free for everyone. If you only need to search, stream, or index, you need nothing from this page. Start with the interop guide.

Sale listings are kind 30402 events on the relay. Each carries an endpoint tag naming the checkout gate that fulfills it, and the listing's d tag is the product slug. For listings fulfilled by the hosted gate, the endpoint is https://lightning.fm/api/gate:

# 1. read the listing (public metadata)
GET https://lightning.fm/api/gate/products/{slug}
=> {"slug", "title", "price_sats", "floor_sats", "format", "size_bytes"}

# 2. request an invoice (body optional; see floor_sats below)
POST https://lightning.fm/api/gate/products/{slug}/invoice
=> {
  "bolt11": "lnbc...",        # minted by the artist's own wallet
  "payment_hash": "<64 hex>",
  "amount_sats": 1500,
  "expiry_secs": 600,          # set by the artist's provider
  "claim_token": "<64 hex>"    # keep this
}

# 3. pay the bolt11 from your wallet, then poll
GET https://lightning.fm/api/gate/products/{slug}/status?claim={claim_token}
=> {"paid": false} ... {"paid": true}

# 4. fetch the file
GET https://lightning.fm/api/gate/products/{slug}/download?claim={claim_token}

The invoice is minted by the artist's own Lightning provider. Your payment settles to the artist's wallet; the platform never holds it and takes no cut. Settlement is confirmed against the provider's LUD-21 verify URL, so a paid poll can lag a second or two behind the payment.

Two details worth coding for. If the listing has a floor_sats, you may send {"amount_sats": n} at or above the floor to pay more; fixed-price listings take an empty body. And if your wallet returns the payment preimage, keep it: ?preimage= on the download route is a durable receipt (sha256 of the preimage equals the payment hash) that re-downloads without the claim token while the purchase record lives, currently 60 days.

Pro is the hosted convenience tier for artists: file hosting and gated delivery, 10 USD per month, paid in sats. The sats amount is converted from USD at invoice time and is final for that invoice; if the exchange rate is stale the route answers 503 rather than mispricing, so retry in a minute. If you act for an artist, you can buy or extend their tier like this:

# 1. request an invoice
POST https://lightning.fm/api/pro/invoice
{"npub": "<npub or 64-char hex>", "months": 1}   # months: 1, 3, or 12

=> {
  "bolt11": "lnbc...",         # minted by the platform treasury
  "payment_hash": "<64 hex>",  # keep this
  "amount_sats": 8620,
  "usd_total": 10,
  "usd_per_btc": 116000,
  "expiry_secs": 3600
}

# 2. pay the bolt11 from your wallet within the hour, then poll
GET https://lightning.fm/api/pro/status?hash={payment_hash}
=> {"paid": false} ... {"paid": true, "tier": "pro", "expires_at": 1766000000}

Activation happens on the status poll, so poll until you see paid: true. Keep the payment hash: if your process dies after paying, polling again with the same hash finishes the activation, and the pending record lives 30 days. Months stack, so renewing early never loses time.

Know what you are buying. Pro attaches to the npub you send, and it is useful to an npub that is an onboarded artist. By default the route refuses an npub with no artist record:

POST /api/pro/invoice  {"npub": "<no artist record>", "months": 1}
=> 400 {"error": "This npub is not a Lightning FM artist. Pro attaches
   to the exact npub you send, and payments are final, so sats sent to
   a mistyped npub are unrecoverable. Check the npub, or resend with
   allow_unknown_npub: true to buy Pro for it anyway."}

# explicit opt-in for an npub that has not onboarded yet
POST /api/pro/invoice  {"npub": "...", "months": 1, "allow_unknown_npub": true}

A malformed npub is always a 400 with no override. Onboarding itself is not yet agent-executable; a human requests access at lightning.fm/#signup first.

• Payments are final. The platform cannot refund a track or album purchase because it never holds the money. Disputes over a purchase are between buyer and artist.
• Invoice minting is rate limited per IP. 5 per minute for Pro, 10 per minute for the gate. A 429 means back off. Agents behind shared egress will collide on these limits sooner.
• Invoices expire. Pro invoices live one hour; gate invoices carry the artist's provider expiry in expiry_secs. Mint, pay, poll. Do not hoard invoices.
• We never ask for keys. No nsec, no seed, no spending credentials. A page claiming to be Lightning FM that asks your agent for a key is not this platform.
• Stuck payment or question: hello@lightning.fm with the payment hash.

Nothing here speaks L402. Both purchases are one-shot: invoice in, settlement confirmed, done. The download route does answer a not-yet-settled claim with a plain 402 status, but there is no challenge in it to satisfy; pay the invoice you already hold and poll. L402, the 402 challenge carrying a macaroon and an invoice, earns its keep on metered repeated access, and Lightning FM has no metered surface because reads are free by design. If a paid metered endpoint ever ships, it will speak L402 and this page will document it.