Skip to main content

nostr-bot-kit

Make a nostr bot without writing code. You edit one text file (YAML), run one command, and your bot answers people on nostr — in public replies and in private messages. It can also talk to a Monero wallet so people can check a tip jar and you can send tips.

  • One Python file, three small dependencies (coincurve, websocket-client, pyyaml)
  • Rules like "when someone writes !balance, reply with the wallet balance"
  • Works on public mentions and encrypted DMs (NIP-04)
  • Fill-in-the-blank replies: {{author_npub}}, {{balance}}, {{date}} and more
  • Can run any program on your computer and put its output in the reply
  • Reconnects to relays automatically; runs forever on a cheap VPS with systemd
  • MIT licensed

1. Install (once)

a) Install Python 3.8 or newer

b) Install the kit. Open a terminal (Windows: "Command Prompt") and type:

pip install nostr-bot-kit

That pulls in coincurve websocket-client pyyaml automatically. If you downloaded the files instead, run pip install coincurve websocket-client pyyaml and use python nostr_bot_kit.py wherever this guide says nostr-bot-kit.

On Linux, if pip complains about an "externally managed environment", make a private folder for it first: python3 -m venv ~/nostrbot/venv && ~/nostrbot/venv/bin/pip install nostr-bot-kit and then use ~/nostrbot/venv/bin/nostr-bot-kit.

2. Give your bot an identity

Every nostr account is a pair of keys. Make one for the bot:

nostr-bot-kit keygen

You get two lines:

  • nsec1... — the bot's secret key. Anyone who has it is your bot. Never post it.
  • npub1... — the bot's public address. Share it; people mention or DM this.

Save the nsec1... line alone in a file called bot.nsec next to your config.

(Optional: log into any nostr app such as Primal or Damus with the nsec to give the bot a name and picture.)

3. Write your config

Copy example-config.yaml to bot.yaml and open it in any text editor (Notepad, TextEdit, nano). Everything is explained in the comments. The important part is the rules list:

rules:
  - match: exact            # message must be exactly this
    pattern: "!hello"
    reply: "Hi {{author_npub}}! It is {{date}}."

  - match: contains         # pattern appears anywhere
    pattern: "gm"
    on: [mention]           # only public posts (use [dm] for private only)
    reply: "gm!"

  - match: wildcard         # * = "anything", captured as {{arg1}}, {{arg2}}...
    pattern: "!weather *"
    run: "curl -s 'https://wttr.in/{{arg1}}?format=3'"
    timeout: 10
    reply: "{{output}}"

Rules are checked from top to bottom; the first one that matches answers. YAML tips: indentation uses spaces (not tabs), and put text with : # { or ! inside quotes.

Variables you can use in replies

Variable Becomes
{{npub}} the bot's npub
{{author_npub}} npub of the person who wrote
{{balance}} wallet balance (only asked when you use it)
{{timestamp}} / {{date}} Unix time / 2026-01-31 14:05 UTC
{{args}} everything the *s captured, {{arg1}}, {{arg2}} one by one
{{output}} what a run: command printed
{{message}} the full message (after removing the bot's own mention)
{{amount}} {{recipient}} {{address}} {{txid}} {{fee}} {{fee_message}} tip details
{{error}} error detail (in messages: templates)
anything under variables: your own constants, e.g. {{donate}}

Running programs (run:)

Any rule can run a command. Its printed output goes into {{output}}. Values typed by users ({{args}}, {{arg1}} …) are automatically quoted so nobody can sneak extra commands in. Use timeout: (seconds, default 10). If the command fails or is too slow, the error / timeout message is sent instead.

Wallet / tip bot

Add a wallet: section (see the example) and use action: in a rule:

action what it does
balance runs monero-wallet-cli ... balance, fills {{balance}}
register saves {{arg1}} as the sender's address (!register 4...)
tip sends amount to recipient (an npub that registered, or one in address_book)

The wallet program is called directly (no shell). Safety switches: max_amount, admin_only: true on the tip rule (only npubs listed under admins: may tip), allow_raw_addresses: false. Use a separate small hot wallet for the bot, never your main wallet. monero-wallet-rpc users can point cli: at a tiny script instead — any program that prints a balance works.

Other wallets: change cli, balance_args, send_args, and the *_regex lines to match what your wallet prints.

Problem messages

The messages: section holds what the bot says when something goes wrong: error, timeout, not_allowed, invalid_amount, too_much, unknown_recipient, invalid_address, insufficient_funds, the fee line used in {{fee_message}}, and no_match (reply to unknown commands; leave empty to stay quiet).

4. Test before going live

nostr-bot-kit check bot.yaml            # finds typos, prints the bot npub
nostr-bot-kit try bot.yaml "!hello"     # shows the reply, sends nothing to nostr
nostr-bot-kit try bot.yaml "gm" --as mention

try really runs run: commands and wallet commands, so test tips with tiny amounts.

5. Run it

nostr-bot-kit run bot.yaml

Leave the window open. Mention the bot's npub from your own nostr account, or DM it, and watch it answer. Stop with Ctrl+C. Add -v for more detail.

6. Run it 24/7 on a VPS (auto-restart)

Any $3–5/month Linux VPS works. Logged in as root:

adduser --disabled-password --gecos "" bot
su - bot -c "python3 -m venv ~/nostrbot/venv && ~/nostrbot/venv/bin/pip install nostr-bot-kit"
# copy bot.yaml and bot.nsec into /home/bot/nostrbot/  (e.g. with scp)
chmod 600 /home/bot/nostrbot/bot.nsec
cp nostrbot.service /etc/systemd/system/nostrbot.service
systemctl daemon-reload
systemctl enable --now nostrbot

Useful commands:

systemctl status nostrbot        # is it running?
journalctl -u nostrbot -f        # live log
systemctl restart nostrbot       # after editing bot.yaml

nostrbot.service has Restart=always, so the bot comes back after crashes and reboots. If you use a wallet, put the wallet files where the bot user can read them and run monerod or point --daemon-address at a node you trust.

7. Don't look like every other bot (fingerprinting)

Every bot built from this kit starts with the same default texts. Anyone can send !help or a nonsense command and recognise "a nostr-bot-kit bot" — and if a weakness were ever found, find all of them. So:

  • Rewrite every reply: and every line under messages: in your own words.
  • Pick your own command names (!jar instead of !balance, etc.).
  • Keep no_match empty unless you need it — silence reveals less.
  • Remember public replies are public: never put addresses, balances, or tx ids in on: [mention] rules unless you are fine with everyone seeing them. NIP-04 DMs hide the text but not who talks to whom or when.

Security notes

  • The secret key file and wallet password file should be readable only by the bot user (chmod 600).
  • Every incoming event's signature is checked; duplicates from multiple relays are ignored; cooldown_seconds throttles spammers; blocked: mutes npubs.
  • run: commands run with the bot's permissions. Don't give the bot user sudo.
  • NIP-04 is the widely supported DM format, but it is older and leaks metadata; newer clients also support NIP-17.

For developers

Everything lives in nostr_bot_kit.py (bech32, schnorr signing, NIP-04 with a built-in AES-256-CBC, relay pool, rule engine, wallet adapter). Run the offline test suite with:

python -m unittest -v test_kit

License: MIT.

Metadata

Release files for nostr-bot-kit 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nostr-bot-kit 0.1.0
File Size Uploaded Provenance Actions
nostr_bot_kit-0.1.0.tar.gz 25.6 kB Without provenance Details for nostr_bot_kit-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for nostr-bot-kit 0.1.0
File Interpreter ABI Platform Actions
nostr_bot_kit-0.1.0-py3-none-any.whl Python 3 none any Details for nostr_bot_kit-0.1.0-py3-none-any.whl

Total release size: 43.9 kB

Release files / nostr_bot_kit-0.1.0.tar.gz

Download URL nostr_bot_kit-0.1.0.tar.gz
Size 25.6 kB
Tags Source
SHA-256 checksum
How to use checksums
a6dad5d6a2480a4aad253a89119519fe88cc491528b09d282c9db1fd051c5853
BLAKE2b-256 checksum
How to use checksums
8dffb36ae0dc8fcaac77f5a9bc9f8dda5f7451f16095aba47ac271e850ee7979
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.12

Release files / nostr_bot_kit-0.1.0-py3-none-any.whl

Download URL nostr_bot_kit-0.1.0-py3-none-any.whl
Size 18.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ba6bb6f7adcf59c39b5ed11fa78d8bbaf853fcb1d294a7d6f8bb46a42d8797f1
BLAKE2b-256 checksum
How to use checksums
09ebebf3868445e3f9bb41225bfcff3ca4a9e925030462aa7c54414b22a00acf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.12

Security for nostr-bot-kit 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page