Metadata-Version: 2.4
Name: nostr-bot-kit
Version: 0.1.0
Summary: Build nostr wallet/tip bots without coding: write one YAML file, run one command.
Author: nostr-bot-kit contributors
License-Expression: MIT
Project-URL: Homepage, https://bounties.monero.social/posts/163
Keywords: nostr,bot,monero,tip,wallet,no-code,yaml,nip-04
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: coincurve>=18
Requires-Dist: websocket-client>=1.6
Requires-Dist: pyyaml>=6.0
Dynamic: license-file

# 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-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:

```yaml
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:

```bash
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:

```bash
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.
