Resources for Agents

Shosho services

External tools

Nostr NIPs reference

Key methodologies

Never roll your own cryptography

Nostr uses secp256k1 Schnorr signatures. Always use established libraries (nostr-tools, NAK) for key generation, signing, and verification. Never implement signing or encryption from scratch.

Relay etiquette

• Don’t spam relays with high-frequency publishes. Batch where possible.
• Respect relay rate limits — most relays will disconnect you if you exceed them.
• For critical events (profile updates, relay lists), publish to multiple relays for redundancy.
• For stream events, prefer the user’s own write relays rather than broadcasting to every relay.

Event signing

All Nostr events must be signed by the user’s private key. When acting as an agent:

• Ask the user for their nsec or use a NIP-46 signer (Nostr Connect).
• Never store private keys in plaintext logs or transmit them over unencrypted channels.
• Shell history: commands using --sec $NSEC are recorded in shell history. Prefix the command with a space (requires HISTCONTROL=ignorespace) or unset NSEC after use to avoid persisting the key.
• NAK handles signing via the --sec flag.
• For programmatic use, nostr-tools provides finalizeEvent() which signs and hashes.

Addressable vs regular events

• Addressable events (kinds 30000-39999) are identified by kind:pubkey:d-tag and are replaceable — publishing a new event with the same d-tag replaces the old one.
• Regular events are identified by event ID and are immutable once published.
• Stream events (30311), addressable clips (34235 / 34236), and products (30402) are all addressable.
• Chat messages (1311), reactions (7), legacy clips (21 / 22), and clip comments (1111) are regular events.

Troubleshooting

Published something wrong to the network

Publish a kind 5 deletion request (NIP-09) to ask relays to remove the event. You can only delete events you authored.

# Delete a regular event by event ID
nak event -k 5 \
  --content "published in error" \
  -t e=<event_id_to_delete> \
  -t k=<kind_of_deleted_event> \
  --sec <nsec1...> \
  wss://relay.damus.io wss://relay.primal.net
 
# Delete an addressable event by coordinate
nak event -k 5 \
  --content "published in error" \
  -t a='<kind>:<author_hex_pubkey>:<d-tag>' \
  -t k=<kind_of_deleted_event> \
  --sec <nsec1...> \
  wss://relay.damus.io wss://relay.primal.net

Deletion is a request, not a guarantee. Relays may or may not honour it. For addressable events, you can also publish a corrected replacement with the same d tag.

For events Shosho signed on your behalf — i.e. 30311 events created via Shosho Server or the Show Chat API — your NIP-09 deletion will be invalid because you’re not the event author. Use the corresponding API delete endpoint instead (DELETE /stream/<d-tag> for Shosho Server; POST /show-chat/delete for Show Chat). The Shosho service publishes the kind 5 deletion with its own key.

Related

• Overview
• NIP-98 HTTP authentication