NIP-30402: L402 Service Registry

NIP-30402 — L402 Service Registry#

draft optional

Abstract#

This NIP defines a standard Nostr event kind for publishing, discovering, and updating L402-enabled API service listings. Kind 30402 allows service operators — human or autonomous — to advertise their Lightning-native APIs on public Nostr relays. Clients can fetch, filter, and display these listings without a central registry.

Motivation#

L402 (HTTP 402 Payment Required + Lightning) enables machine-to-machine micropayments for API access. A decentralised, relay-based registry of L402 services allows:

• Agents to discover APIs autonomously (no central index to trust)
• Operators to publish and update their listings permissionlessly
• Clients to aggregate across relays and rank by community signals

Event Kind#

Kind	Description
30402	L402 Service Listing (addressable, replaceable per pubkey+d)

Event Structure#

{
  "kind": 30402,
  "pubkey": "<operator pubkey>",
  "created_at": <unix timestamp>,
  "content": "<markdown description of the service>",
  "tags": [
    ["d", "<unique-slug>"],
    ["name", "<human-readable service name>"],
    ["url", "<L402 API base URL>"],
    ["docs", "<documentation URL>"],
    ["category", "<category>"],
    ["pricing", "<pricing_model>"],
    ["sat", "<sats per call>"],
    ["t", "l402"],
    ["t", "<additional tag>"]
  ]
}

Tag Definitions#

Tag	Required	Description
d	✅	Unique slug identifier for this listing. Used as the replaceable event identifier. Must be stable — changing it creates a new listing.
name	✅	Human-readable name of the service.
url	✅	Base URL of the L402 API endpoint.
docs	✅	URL of the API documentation.
category	✅	One of: ai, data, media, compute, finance, storage, other.
pricing	✅	Pricing model: per_call, subscription, metered, tiered.
sat	⬜	Price per call in satoshis (integer string). Omit if pricing is not per-call.
t	✅	Must include "l402". Additional topic tags optional.

Categories#

Value	Description
ai	AI inference, embeddings, generation
data	Data feeds, oracles, search
media	Image, video, audio processing
compute	General computation, code execution
finance	Financial data, payments, Bitcoin
storage	File storage, CDN, IPFS
other	Anything not covered above

Pricing Models#

Value	Description
per_call	Fixed sats per API call. Include sat tag.
subscription	Fixed recurring fee. Describe in content.
metered	Pay per unit (tokens, bytes, requests). Describe in content.
tiered	Multiple pricing levels. Describe tiers in content.

Content Field#

The content field SHOULD contain a Markdown description of the service including:

• What the API does
• Supported endpoints
• Authentication flow (L402 challenge/response)
• Usage examples (curl, agent prompt, etc.)
• Any rate limits or constraints

Deletion#

To delist a service, publish a NIP-09 deletion event (kind: 5) referencing the kind 30402 event by its a tag:

{
  "kind": 5,
  "tags": [["a", "30402:<pubkey>:<d-tag>"]]
}

Agent Submission Instructions#

Autonomous agents that wish to publish an L402 service listing MUST:

1. Construct a kind 30402 event with all required tags.
2. Sign the event with the operator's private key (NIP-01).
3. Publish to at least 3 well-known relays (e.g. wss://relay.damus.io, wss://nos.lol, wss://relay.primal.net).

Example (using nak CLI):

nak event \
  --kind 30402 \
  --tag d=my-api \
  --tag name="My L402 API" \
  --tag url="https://api.example.com" \
  --tag docs="https://docs.example.com" \
  --tag category=ai \
  --tag pricing=per_call \
  --tag sat=10 \
  --tag t=l402 \
  --content "## My L402 API\n\nDoes something useful for sats." \
  wss://relay.damus.io wss://nos.lol wss://relay.primal.net

Human Submission (NIP-07)#

Clients implementing an L402 Index SHOULD provide a web form that:

1. Collects required fields from the user.
2. Constructs the kind 30402 event client-side.
3. Calls window.nostr.signEvent(event) (NIP-07) to sign.
4. Publishes to relays via a WebSocket connection.

This allows submission without exposing private keys to the application.

Discovery#

Clients SHOULD query relays for kind 30402 events using:

{"kinds": [30402], "#t": ["l402"]}

To filter by category:

{"kinds": [30402], "#category": ["ai"]}

Example Event#

{
  "kind": 30402,
  "pubkey": "44a3a93660c84b21006efd96da8e9dd728abda4853371584c5b15c1a1eedf548",
  "content": "## Lightning AI Inference\n\nGPT-4-class inference gated by L402. Pay 10 sats per 1k tokens.",
  "tags": [
    ["d", "lightning-ai-inference"],
    ["name", "Lightning AI"],
    ["url", "https://api.lightningai.example"],
    ["docs", "https://docs.lightningai.example"],
    ["category", "ai"],
    ["pricing", "per_call"],
    ["sat", "10"],
    ["t", "l402"],
    ["t", "ai"]
  ]
}

Implementations#

• L402 Index — community directory fetching kind 30402 events

See Also#

• NIP-31402 — SARA Revenue Share Offering Registry
• NIP-01 — Basic protocol
• NIP-07 — Browser signer
• NIP-09 — Event deletion