Overview
This node is a trigger designed to listen for specific events on the Nostr decentralized network, focusing on mentions of a particular public key. It connects to one or two specified relays and filters incoming events based on a "mention" strategy. The node supports rate limiting and filtering through blacklists and whitelists, making it useful for scenarios where you want to react to mentions of a user or entity in real-time while controlling event flow and access.
Common use cases:
- Trigger workflows when a specific user is mentioned in Nostr events.
- Monitor mentions with control over event threads inclusion.
- Apply rate limits to avoid flooding from too many events.
- Filter events by blacklisting or whitelisting certain public keys.
Practical example:
You could use this node to start a workflow whenever your application's public key is mentioned in a Nostr event of kind 1 (typically text notes), optionally including threaded replies, and only process events from trusted users (whitelist) while ignoring others (blacklist). Rate limiting ensures your workflow isn't overwhelmed by too many mentions in a short period.
Properties
| Name | Meaning |
|---|---|
| Strategy | Trigger strategy; currently supports only "Mention". |
| PublicKey | Public key of the mention target, in npub or HEX format. |
| Kind | Kind number of the target event, usually set to 1 (text note). |
| Threads | Boolean indicating whether to include events in threads (replies) in the scope. |
| Relay1 | URL of the primary Nostr relay to connect to (WebSocket endpoint). |
| Relay2 | URL of an optional secondary Nostr relay to connect to. |
| RatelimitingCountForAll | Maximum count of rate-limited requests allowed globally within the specified period. |
| RatelimitingCountForOne | Maximum count of rate-limited requests allowed per individual user identified by their npub. |
| PeriodSeconds | Time window in seconds for rate limiting counts. |
| DurationSeconds | Duration in seconds for which rate limiting applies per user. |
| BlackList | Comma-separated list of public keys (npub) to exclude from triggering. |
| WhiteList | Comma-separated list of public keys (npub) allowed to trigger the node. |
Output
The node outputs JSON data representing the matched Nostr events that triggered it. Each output item corresponds to a single event object containing all its properties as received from the relay.
- The
jsonfield contains the full event data. - No binary data output is produced by this node.
Dependencies
- Connects to Nostr relays via WebSocket URLs provided in the input properties.
- Uses the
nostr-toolslibrary for event handling, filtering, and verification. - Requires network access to the specified relay endpoints.
- No external API keys or credentials are required beyond the relay URLs and public key inputs.
Troubleshooting
- Invalid strategy error: The node currently supports only the "Mention" strategy. Using any other value will cause an error.
- Relay connection issues: If the relay WebSocket connection closes unexpectedly, the node attempts reconnection with exponential backoff. Frequent closures may lead to errors.
- Rate limiting: If too many events arrive within the configured limits, some events will be ignored to prevent overload.
- Blacklist/Whitelist misconfiguration: Incorrectly formatted lists (e.g., missing commas) may cause unexpected filtering behavior.
- Public key format: Ensure the public key is correctly formatted as npub or HEX; otherwise, events may not match.