NIP-XX: Unified Payment Gateway Descriptor Event (kind:10164) — Tags-Only

Summary

This NIP defines kind:10164 as a tags-only event to describe a single payment gateway with all supported methods, currencies, pricing, discounts, and conditions.

• One event = one gateway
• Multiple methods per gateway
• Multiple currencies and plans per method
• All data expressed via tags (no JSON in content)

---

Design Goals

• Pure Nostr-native (tags only)
• Compact, indexable, and relay-friendly
• Supports complex real-world pricing and conditions
• Easy for clients to render and filter

---

Event Kind

kind: 10164

• One event per gateway/provider
• Creators may publish multiple events (one per provider)

---

Event Structure

{
  "kind": 10164,
  "pubkey": "<creator_pubkey>",
  "created_at": <unix_timestamp>,
  "tags": [
    ["d", "<gateway_id>"],
    ["u", "<payment_url>"],
    ["name", "<gateway_name>"],
    ["p", "<optional_gateway_pubkey>"],

    ["method", "<method_id>", "<type>"],
    ["currency", "<method_id>", "<currency_code>"],
    ["price", "<method_id>", "<plan_id>", "<amount>", "<interval>"],
    ["discount", "<method_id|*>", "<plan_id|*>", "<type>", "<value>", "<condition>"],

    ["condition", "<type>", "<id>", "<discount>"],
    ["zap", "<enabled>", "<min_amount>", "<interval>", "<processor_pubkey?>"],
    ["payout", "<payout_method>"],
    ["manual", "true|false"],
    ["perk", "<description>"]
  ],
  "content": ""
}

---

Core Tags

Gateway Identity

• ["d", "<gateway_id>"] — unique identifier
• ["u", "<payment_url>"] — entry point URL
• ["name", "<gateway_name>"] — human-readable name
• ["p", "<gateway_pubkey>"] — optional processor pubkey

---

Methods

Each payment method is declared with a unique method_id.

["method", "<method_id>", "<type>"]

Examples:

["method", "m1", "bitcoin"]
["method", "m2", "fiat"]
["method", "m3", "ethereum"]

---

Currencies

Attach currencies to a method:

["currency", "<method_id>", "<currency_code>"]

Examples:

["currency", "m1", "BTC"]
["currency", "m2", "USD"]
["currency", "m2", "EUR"]

---

Pricing

Define plans per method:

["price", "<method_id>", "<plan_id>", "<amount>", "<interval>"]

Examples:

["price", "m1", "p1", "0.0002", "monthly"]
["price", "m2", "p1", "10", "monthly"]
["price", "m2", "p2", "50", "6-months"]

---

Discounts

Flexible discount system:

["discount", "<method_id|*>", "<plan_id|*>", "<type>", "<value>", "<condition>"]

• * means applies globally

Examples:

["discount", "m1", "*", "percentage", "10", "bitcoin"]
["discount", "m2", "p2", "percentage", "20", "6-months-upfront"]
["discount", "*", "*", "percentage", "15", "members_of:nostr-devs"]

---

Global Conditions

["condition", "<type>", "<id>", "<discount>"]

Examples:

["condition", "group", "nostr-devs", "15"]
["condition", "relay", "wss://relay.example", "10"]

---

Zap-Based Subscriptions

["zap", "<enabled>", "<min_amount>", "<interval>", "<processor_pubkey?>"]

Example:

["zap", "true", "1000", "monthly", "<pubkey>"]

---

Payout

["payout", "<method>"]

Examples:

["payout", "bank_transfer"]
["payout", "crypto_wallet"]

---

Manual Payments

["manual", "true"]

Indicates off-platform handling.

---

Perks

["perk", "<description>"]

Repeatable.

---

Subscriber Management

Handled externally via NIP-63 (e.g., kind 30000 lists).

This event only defines how to pay, not who paid.

---

Client Behavior

Clients SHOULD:

1. Fetch all 10164 events from a creator
2. Group by gateway (d)
3. Build UI:
   • Methods → Currencies → Plans
4. Apply discounts:
   • Method-specific
   • Plan-specific
   • Global (*)
5. Redirect user to u

---

Full Example

{
  "kind": 10164,
  "tags": [
    ["d", "main-gateway"],
    ["u", "https://pay.example"],
    ["name", "Main Gateway"],

    ["method", "m1", "bitcoin"],
    ["currency", "m1", "BTC"],
    ["price", "m1", "p1", "0.0002", "monthly"],

    ["method", "m2", "fiat"],
    ["currency", "m2", "USD"],
    ["currency", "m2", "EUR"],
    ["price", "m2", "p1", "10", "monthly"],
    ["price", "m2", "p2", "50", "6-months"],

    ["discount", "m1", "*", "percentage", "10", "bitcoin"],
    ["discount", "m2", "p2", "percentage", "20", "6-months-upfront"],
    ["discount", "*", "*", "percentage", "15", "members_of:nostr-devs"],

    ["condition", "group", "nostr-devs", "15"],

    ["zap", "true", "1000", "monthly"],
    ["payout", "bank_transfer"],

    ["perk", "Premium posts"],
    ["perk", "Early access"]
  ],
  "content": ""
}

---

Advantages

• Fully Nostr-native (no JSON parsing required)
• Easy indexing by relays
• Flexible and expressive
• Supports all discussed scenarios:
  • Multi-provider
  • Multi-currency
  • Discounts
  • Zap delegation
  • Manual flows

---

Conclusion

This version of 10164 provides a complete, tag-based payment descriptor system, enabling:

• Rich gateway definitions
• Clean client UX
• Maximum compatibility with Nostr primitives