python-nostr

A Python library for making Nostr clients

Usage

Generate a key

fromnostr.keyimportPrivateKeyprivate_key=PrivateKey()
public_key=private_key.public_keyprint(f"Private key: {private_key.bech32()}")
print(f"Public key: {public_key.bech32()}")

Connect to relays

importjsonimportsslimporttimefromnostr.relay_managerimportRelayManagerrelay_manager=RelayManager()
relay_manager.add_relay("wss://nostr-pub.wellorder.net")
relay_manager.add_relay("wss://relay.damus.io")
relay_manager.open_connections({"cert_reqs": ssl.CERT_NONE}) # NOTE: This disables ssl certificate verificationtime.sleep(1.25) # allow the connections to openwhilerelay_manager.message_pool.has_notices():
notice_msg=relay_manager.message_pool.get_notice()
print(notice_msg.content)
relay_manager.close_connections()

Publish to relays

importjsonimportsslimporttimefromnostr.eventimportEventfromnostr.relay_managerimportRelayManagerfromnostr.message_typeimportClientMessageTypefromnostr.keyimportPrivateKeyrelay_manager=RelayManager()
relay_manager.add_relay("wss://nostr-pub.wellorder.net")
relay_manager.add_relay("wss://relay.damus.io")
relay_manager.open_connections({"cert_reqs": ssl.CERT_NONE}) # NOTE: This disables ssl certificate verificationtime.sleep(1.25) # allow the connections to openprivate_key=PrivateKey()
event=Event("Hello Nostr")
private_key.sign_event(event)
relay_manager.publish_event(event)
time.sleep(1) # allow the messages to sendrelay_manager.close_connections()

Reply to a note

fromnostr.eventimportEventreply=Event(
content="Hey, that's a great point!",
)
# create 'e' tag reference to the note you're replying toreply.add_event_ref(original_note_id)
# create 'p' tag reference to the pubkey you're replying toreply.add_pubkey_ref(original_note_author_pubkey)
private_key.sign_event(reply)
relay_manager.publish_event(reply)

Send a DM

fromnostr.eventimportEncryptedDirectMessagedm=EncryptedDirectMessage(
recipient_pubkey=recipient_pubkey,
cleartext_content="Secret message!"
)
private_key.sign_event(dm)
relay_manager.publish_event(dm)

Receive events from relays

importjsonimportsslimporttimefromnostr.filterimportFilter, Filtersfromnostr.eventimportEvent, EventKindfromnostr.relay_managerimportRelayManagerfromnostr.message_typeimportClientMessageTypefilters=Filters([Filter(authors=[<anostrpubkeyinhex>], kinds=[EventKind.TEXT_NOTE])])
subscription_id=<astringtoidentifyasubscription>request= [ClientMessageType.REQUEST, subscription_id]
request.extend(filters.to_json_array())
relay_manager=RelayManager()
relay_manager.add_relay("wss://nostr-pub.wellorder.net")
relay_manager.add_relay("wss://relay.damus.io")
relay_manager.add_subscription(subscription_id, filters)
relay_manager.open_connections({"cert_reqs": ssl.CERT_NONE}) # NOTE: This disables ssl certificate verificationtime.sleep(1.25) # allow the connections to openmessage=json.dumps(request)
relay_manager.publish_message(message)
time.sleep(1) # allow the messages to sendwhilerelay_manager.message_pool.has_events():
event_msg=relay_manager.message_pool.get_event()
print(event_msg.event.content)
relay_manager.close_connections()

NIP-26 delegation

fromnostr.delegationimportDelegationfromnostr.eventimportEventKind, Eventfromnostr.keyimportPrivateKey# Load your "identity" PK that you'd like to keep safely offlineidentity_pk=PrivateKey.from_nsec("nsec1...")
# Create a new, disposable PK as the "delegatee" that can be "hot" in a Nostr clientdelegatee_pk=PrivateKey()
# the "identity" PK will authorize "delegatee" to sign TEXT_NOTEs on its behalf for the next monthdelegation=Delegation(
delegator_pubkey=identity_pk.public_key.hex(),
delegatee_pubkey=delegatee_pk.public_key.hex(),
event_kind=EventKind.TEXT_NOTE,
duration_secs=30*24*60*60
)
identity_pk.sign_delegation(delegation)
event=Event(
"Hello, NIP-26!",
tags=[delegation.get_tag()],
)
delegatee_pk.sign_event(event)
# ...normal broadcast steps...

The resulting delegation tag can be stored as plaintext and reused as-is by the "delegatee" PK until the delegation token expires. There is no way to revoke a signed delegation, so current best practice is to keep the expiration time relatively short.

Hopefully clients will include an optional field to store the delegation tag. That would allow the "delegatee" PK to seamlessly post messages on the "identity" key's behalf, while the "identity" key stays safely offline in cold storage.

Installation

pip install nostr

Note: I wrote this with Python 3.9.5.

Test Suite

See the Test Suite README

Disclaimer

• This library is in very early development.
• It might have some bugs.
• I need to add more tests.

Please feel free to add issues, add PRs, or provide any feedback!