Nostreon API

Public API for third-party Nostr clients to integrate creator subscriptions.

Nostreon is a creator subscription platform on Nostr and Bitcoin. This API lets any Nostr client (Primal, Damus, Amethyst, etc.) embed subscription creation natively so their users can subscribe to creators without leaving the app.

Quick Start

# 1. Fetch a creator's tiers (no auth required)
curl https://nostreon.com/api/v1/creators/npub1.../tiers

# 2. Subscribe a user (requires API key + NIP-98 signed event)
curl -X POST https://nostreon.com/api/v1/subscribe \
  -H "Authorization: Nostr <base64_signed_event>" \
  -H "X-Api-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"tier_id": "...", "billing": "monthly"}'

# 3. Poll for payment (after user pays the Lightning invoice)
curl "https://nostreon.com/api/v1/subscribe/status?invoice_id=..." \
  -H "X-Api-Key: <your_api_key>"

How it Works

┌──────────┐       ┌──────────┐       ┌───────────┐       ┌──────────┐
│ Your     │──(1)─▶│ Nostreon │──(2)─▶│ Lightning │       │ Creator  │
│ Client   │       │ API      │       │ Network   │       │          │
│          │◀─(3)──│          │       │           │       │          │
│          │◀─(4)──│          │◀──────│           │──(5)─▶│          │
└──────────┘       └──────────┘       └───────────┘       └──────────┘
   User pays          Creates         Settles the         Auto-payout
  invoice in          invoice         invoice             via Lightning
  your UI

1. Your client calls POST /v1/subscribe with a signed NIP-98 event and API key
2. Nostreon creates a BTCPay invoice and returns a BOLT11 Lightning invoice
3. Your client displays the QR code / invoice for the user to pay
4. When payment settles, Nostreon automatically creates the subscription, publishes a NIP-63 membership event, and pays the creator
5. The user can now access premium content from any NIP-63 compatible relay

Documentation

Reference

• Authentication — API keys and NIP-98 HTTP auth
• Creators — fetch profiles and tiers
• Subscriptions — create and poll subscriptions

Generic examples (any HTTP-capable client)

• Node.js — full subscription flow with NIP-98 signing
• Browser — vanilla JavaScript integration

Client-specific examples (idiomatic for each Nostr client)

• Primal — web/iOS/Android, integrates with Primal Wallet for one-tap payment
• Damus — iOS Swift, hands off payment to the user's Lightning wallet via lightning: URI
• Amethyst — Android Kotlin, opens the user's Lightning wallet via Android intent

Each client example walks through the full flow (discover tiers → sign auth event → create invoice → handle payment → poll for settlement) using the language and patterns idiomatic to that client. The HTTP API is identical regardless of which client you're integrating into; the examples differ in how they sign events, how they pay invoices, and how they show subscription state to the user.

Revenue Share

Nostreon takes a 5% platform fee on subscriptions. When a subscription is created through your API integration, Nostreon shares 50% of the platform fee with you (configurable per partner).

Example on a $5/month subscription:

• Creator gets: $4.75 (95%)
• Nostreon gets: $0.125 (2.5%)
• Your client gets: $0.125 (2.5%)

Payouts are sent automatically to your Lightning address on each successful subscription.

Get an API Key

API keys come in two flavors:

• Test keys (npk_test_*) — for development against dev.nostreon.com. BTCPay is skipped entirely; invoices are mocked and auto-settle on polling. No money moves, but real subscription records and kind 1163 membership events are created in the dev environment so you can test your full integration.
• Live keys (npk_live_*) — for production against nostreon.com. Real invoices, real payments, real payouts.

We recommend starting with a test key, building your integration, then requesting a live key once everything works end-to-end. See authentication.md for full details on test mode.

To request a key, open an issue in this repo with:

• Client name
• Your npub (we'll deliver the API key via Nostr DM, never in the issue)
• Lightning address for receiving referral payouts
• Which key you want: test, live, or both
• Expected monthly volume (optional)

We'll reply in the issue to confirm receipt, then send the API key to your npub as an encrypted Nostr direct message (NIP-04). Never share API keys in public channels.

Base URL

• Production: https://nostreon.com/api/v1
• Staging: https://dev.nostreon.com/api/v1

Rate Limits

Endpoint type	Default limit
Read-only (no auth)	60 requests / minute per IP
Authenticated (with API key)	30 requests / minute per API key

Rate limits are configurable per partner. If you need higher limits, contact us.

Rate-limited responses return HTTP 429 with a Retry-After header.

Errors

All errors return JSON with an error field:

{ "error": "Invalid or inactive API key" }

Status	Meaning
400	Bad request (invalid parameters)
401	Missing or invalid authentication
404	Resource not found
429	Rate limited
500	Server error

License

MIT