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
- Windows: download from https://www.python.org/downloads/ and tick "Add Python to PATH" during setup.
- macOS: download from https://www.python.org/downloads/ (or
brew install python). - Linux (Debian/Ubuntu):
sudo apt install python3 python3-pip python3-venv
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-kitand 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 undermessages:in your own words. - Pick your own command names (
!jarinstead of!balance, etc.). - Keep
no_matchempty 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_secondsthrottles 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.