Download the PHP package innis/nostr-client without Composer

innis/nostr-client

AMPHP-based async WebSocket client for Nostr protocol

A PHP client library for connecting to Nostr relays over WebSocket, subscribing to events, and publishing. Built with AMPHP for non-blocking concurrent relay connections and clean architecture principles.

Features

• Multi-relay connections - Connect to multiple relays concurrently
• AMPHP async - Non-blocking WebSocket I/O with fibers
• Subscription management - Subscribe with single or multiple filters, receive events via handler callbacks
• Event publishing - Publish signed events with OK response handling
• NIP-42 authentication - Automatic auth challenge handling with transparent publish retry
• Connection lifecycle - Automatic state tracking, health checks, reconnection, ping
• Keep-alive handling - WebSocket heartbeats and application-level ping responses
• PSR-3 logging - Standard logging interface throughout
• Clean Architecture - Strict layer separation with domain objects from innis/nostr-core

Requirements

• PHP 8.4 or higher
• innis/nostr-core - Core Nostr protocol entities
• amphp/amp ^3.0 - Async runtime
• amphp/websocket-client ^2.0 - WebSocket client
• psr/log ^3.0 - Logging interface

Installation

Quick Start

Connect and Subscribe

Publish Events

A relay accepting or rejecting an event (duplicate, rate-limited, blocked, …) is an anticipated outcome carried in the PublishResult; only a broken connection throws.

Health Checking

healthCheck() pings every currently connected relay over its existing connection and reports whether each is still reachable. To probe a relay you are not connected to, use the standalone health checker below.

Multiple Filters Per Subscription

Connection Configuration

connect() accepts an optional ConnectionConfig. It controls the connection timeout, request headers, user agent, and auto-reconnect behaviour. It is immutable; construct it with named arguments, defaulting anything you do not set.

Auto-reconnect is enabled by default. A dropped connection retries on jittered exponential backoff between reconnectInitialDelayMs and reconnectMaxDelayMs. reconnectMaxAttempts of 0 means unlimited retries; a positive value bounds them.

Connection Management

getConnectionStatus() returns a ConnectionState: DISCONNECTED, CONNECTED, DISCONNECTING, or FAILED.

Reconnection Listener

Register a listener to re-establish per-connection state (re-subscribe, re-authenticate) after a dropped connection is restored. The listener fires only on a successful reconnect.

Awaiting Publishes

publishEvent() returns a Future<PublishResult> as soon as the event has been sent — await each future for that publish's individual outcome. To instead block until every in-flight publish for a relay has been acknowledged (including any parked on a NIP-42 auth challenge) without inspecting each result, drain them with an optional timeout in seconds.

NIP-42 Authentication

Register an auth handler to sign relay challenges. When publishEvent() is rejected with auth-required, the client completes the challenge-response flow and retransmits the queued event transparently.

Standalone Health Checker

Check relay health without an active connection:

See examples/ for complete working examples.

Error Handling

Anticipated outcomes (a well-formed operation whose answer is "no") are returned as typed values (?T or a *Failure); faults are thrown. nostr-client's faults are ClientException (abstract) extending NostrException, with ConnectionException (final) extending ClientException. Catch NostrException to handle faults from any nostr-* library, or ConnectionException for connection faults specifically. See ADR-0002 for how faults are rooted.

Retry logic belongs in your application layer where you have full business context.

Architecture

This package follows Clean Architecture principles:

Testing

Licence

MIT License. See LICENSE file for details.