Kind 31990: Nostr Software Application

Overview

A Nostr Software Application event (officially known as "Handler Information") defines a Nostr client or application that can handle specific event kinds. In practice, these events are used to create app-store style listings of Nostr clients, providing discovery and installation information for applications that can handle various types of Nostr content.

Specification

Property	Value
Kind Number	31990
Event Range	Replaceable (by d tag)
Official Name	Handler Information
Common Usage	Nostr Software Application
Defined in	NIP-89

Content Format

The content field contains optional application metadata in a JSON format similar to Kind 0 (User Metadata). This metadata is used to display the application in app-store style listings and is especially useful when the pubkey creating the event is not the application itself.

Schema

{
  "name": "Application Name",
  "display_name": "Friendly Display Name",
  "picture": "https://example.com/app-icon.png",
  "banner": "https://example.com/app-banner.png",
  "about": "Description of the application and its features",
  "web": "https://app.example.com",
  "nip05": "[email protected]",
  "lud16": "[email protected]"
}

Common Fields for App Listings

• name: The technical name of the application
• display_name: A user-friendly display name for the application
• picture: Application icon/logo URL (recommended: square format, 256x256px or larger)
• banner: Application banner image URL (recommended: 16:9 aspect ratio)
• about: Detailed description of the application's purpose and features
• web: Main website or web application URL
• nip05: NIP-05 identifier for the application
• lud16: Lightning address for supporting the application

If the content is empty, clients should use the application's Kind 0 event for displaying information.

Tags

Tag Name	Description	Format	Required
d	Unique identifier	["d", "<random-id>"]	Yes
k	Supported event kind	["k", "<event-kind-number>"]	Yes
web	Web URL template	["web", "<url-with-bech32-placeholder>", "<optional-entity-type>"]	No
ios	iOS URL template	["ios", "<url-with-bech32-placeholder>", "<optional-entity-type>"]	No
android	Android URL template	["android", "<url-with-bech32-placeholder>", "<optional-entity-type>"]	No

• The d tag contains a random identifier for this handler event.
• The k tag specifies which event kind this application can handle. Multiple k tags can be included if the application handles multiple kinds.
• Platform tags (web, ios, android, etc.) provide URL templates where <bech32> in the URL should be replaced with the NIP-19 encoded entity to be loaded.
• The optional entity type (e.g., "nevent", "nprofile") specifies which NIP-19 entity type the URL handles.

Client Behavior

App Discovery and Listings

Clients can use these events to create app-store style interfaces by:

1. Querying for kind 31990 events to discover available Nostr applications
2. Displaying applications with their metadata (name, icon, description) from the content field
3. Organizing applications by the event kinds they support (using k tags)
4. Providing installation or access links using the platform-specific URL templates

Event Handler Redirection

When encountering unknown event kinds, clients should:

1. Fetch these events when a user wants to open an unknown event kind in a specialized application
2. Parse the URL templates and replace the <bech32> placeholder with the appropriate NIP-19 encoded entity
3. Direct the user to the appropriate application using the platform-specific URL
4. Display application information from either the content field or the application's Kind 0 event

App Store Features

Clients may implement additional app-store features such as:

• Categorizing applications by supported event kinds
• Rating and review systems (using separate events)
• Installation tracking and recommendations
• Featured application sections

Relay Behavior

Relays treat this kind like any other event. These events are replaceable by the d tag, so relays should replace old events with newer ones that have the same pubkey and d tag value.

Use Cases

App Store Listings

• Creating discoverable listings of Nostr clients and applications
• Providing installation and access information for specialized applications
• Displaying application metadata, icons, and descriptions in app directories
• Categorizing applications by their supported event kinds and features

Event Handler Registration

• Defining how a code editor application can open code snippets (kind 1337)
• Specifying how a music player application can handle audio tracks
• Providing URLs for opening marketplace listings in specialized applications
• Enabling cross-application navigation for specialized content types

Client Discovery

• Helping users find clients that support specific features or event kinds
• Providing alternatives when the current client doesn't support certain content
• Facilitating ecosystem growth through application discoverability

Examples

Code Editor Application

{
  "kind": 31990,
  "pubkey": "1743058db7078661b94aaf4286429d97ee5257d14a86d6bfa54cb0482b876fb0",
  "content": "{\"name\":\"Code Viewer\",\"display_name\":\"Nostr Code Viewer\",\"picture\":\"https://codeviewer.example.com/icon.png\",\"banner\":\"https://codeviewer.example.com/banner.png\",\"about\":\"A specialized application for viewing and editing code snippets shared on Nostr. Supports syntax highlighting for 50+ programming languages.\",\"web\":\"https://codeviewer.example.com\",\"nip05\":\"[email protected]\"}",
  "tags": [
    ["d", "code-viewer-v1"],
    ["k", "1337"],
    ["web", "https://codeviewer.example.com/view/<bech32>", "nevent"],
    ["web", "https://codeviewer.example.com/user/<bech32>", "nprofile"],
    ["ios", "codeviewer://<bech32>"],
    ["android", "intent://codeviewer.example.com/view/<bech32>#Intent;scheme=https;end"]
  ],
  "created_at": 1671217411
}

Social Media Client

{
  "kind": 31990,
  "pubkey": "2743058db7078661b94aaf4286429d97ee5257d14a86d6bfa54cb0482b876fb1",
  "content": "{\"name\":\"NostrSocial\",\"display_name\":\"Nostr Social\",\"picture\":\"https://nostrsocial.app/icon.png\",\"banner\":\"https://nostrsocial.app/banner.png\",\"about\":\"A modern social media client for Nostr with advanced filtering, media support, and seamless cross-platform experience.\",\"web\":\"https://nostrsocial.app\",\"nip05\":\"[email protected]\",\"lud16\":\"[email protected]\"}",
  "tags": [
    ["d", "nostrsocial-main"],
    ["k", "1"],
    ["k", "6"],
    ["k", "7"],
    ["web", "https://nostrsocial.app/note/<bech32>", "nevent"],
    ["web", "https://nostrsocial.app/profile/<bech32>", "nprofile"],
    ["ios", "nostrsocial://<bech32>"],
    ["android", "nostrsocial://<bech32>"]
  ],
  "created_at": 1671217411
}

References

• NIP-89: Recommended Application Handlers
• NIP-19: bech32-encoded entities

Related Kinds

• Kind 31989: Handler Recommendation
• Kind 0: User Metadata
• Kind 1337: Code Snippet

Notes

Dual Purpose

While officially called "Handler Information" events, kind 31990 serves a dual purpose in the Nostr ecosystem:

1. Technical Handler Registration: Defining how applications handle specific event kinds with URL templates
2. App Store Listings: Providing discoverable application metadata for client directories and app stores

App Store Implementation

When implementing app-store functionality, clients should:

• Use the content field metadata for rich application displays
• Group applications by supported event kinds (k tags)
• Provide clear installation/access paths using platform-specific URLs
• Consider implementing rating, review, and recommendation systems using separate events

Cross-Platform Compatibility

The URL templates provide flexibility for different platforms while maintaining compatibility across the ecosystem. Applications can specify different URLs for web, iOS, Android, and other platforms, enabling seamless user experiences regardless of the client being used.

Privacy Considerations

Applications publishing these events should be mindful that they are creating public listings of their capabilities and metadata. Users discovering applications through these events should verify the authenticity of applications before installation or use.