bisq-bot/bot/QUICKSTART.md

Quick Start Guide

Get the Bisq Bot running in 10 minutes.

Prerequisites

• Debian/Ubuntu Linux VM
• Python 3.9+
• Bisq daemon running locally on port 4848
• Nostr account/private key for the bot

Step 1: Generate Bot Private Key

Generate a unique Nostr private key for the bot:

openssl rand -hex 32

Example output:

a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1

Save this securely - you'll need it in the next step.

Step 2: Install the Bot

Option A: Automated Setup (Recommended)

cd /tmp
git clone https://github.com/bisq-network/bisq-bot.git bisq-bot
cd bisq-bot/bot
sudo bash setup.sh

The script will:

• Install dependencies
• Create bot user and directories
• Set up systemd service
• Generate config file

Then edit the config:

sudo nano /opt/bisq-bot/.env

Add your private key:

BOT_PRIVATE_KEY=a1b2c3d4e5f6...  # Your key from Step 1

Option B: Manual Setup

# Clone repo
cd /opt
sudo git clone https://github.com/bisq-network/bisq-bot.git bisq-bot
cd bisq-bot/bot

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Create config
cp config/.env.example .env
nano .env
# Add BOT_PRIVATE_KEY

Step 3: Verify Configuration

Check your .env file has:

cat /opt/bisq-bot/.env

Should show (with your values):

NOSTR_RELAYS=wss://relay.nostr.band,wss://relay.damus.io
BOT_PRIVATE_KEY=a1b2c3d4e5f6...
BISQ_PORT=4848
BISQ_HOST=127.0.0.1

Step 4: Verify Bisq Daemon

Check Bisq is running:

bisq-cli --port=4848 getoffers --direction=BUY --currency-code=USD

Should return JSON with offers. If this fails:

• Bisq daemon may not be running
• Check port 4848 is listening: sudo netstat -tlnp | grep 4848

Step 5: Start the Bot

Option A: Systemd (Production)

sudo systemctl enable bisq-bot
sudo systemctl start bisq-bot
sudo systemctl status bisq-bot

View logs:

journalctl -u bisq-bot -f

Option B: Direct (Development/Testing)

cd /opt/bisq-bot
source venv/bin/activate
python -m src.bot

Step 6: Test the Bot

Find the Bot's Nostr Address

Check the logs for the bot's public key:

journalctl -u bisq-bot -n 5 | grep "pubkey"

Example output:

2024-01-01T12:00:00 INFO Nostr handler initialized for pubkey: a1b2c3d4e5...

Test via Nostr

1. Open a Nostr client (e.g., Snort.social, Iris.to, Amethyst)

2. Create a note mentioning the bot:

   @bisqbot USD BUY
   

   (Replace with bot's pubkey if available)

3. Wait 2-5 seconds for response

4. Bot should reply with top 10 USD buy offers

Test via CLI

You can manually test message parsing:

# SSH into bot server
ssh your-server

# Test parsing
python3 -c "
from src.message_parser import MessageParser, CommandType
from src.nostr_handler import NostrEvent

# Simulate an event
class MockEvent:
    def __init__(self):
        self.content = 'USD BUY'
        self.author = 'abc123'

cmd = MessageParser.parse_command(MockEvent(), 'bot_pubkey_here')
print(f'Command: {cmd.command_type}')
print(f'Currency: {cmd.currency_code}')
print(f'Direction: {cmd.direction}')
"

Step 7: Monitor

Check Bot Status

sudo systemctl status bisq-bot

View Recent Logs

journalctl -u bisq-bot -n 50

Follow Live Logs

journalctl -u bisq-bot -f

Check Relay Connections

Look for connection messages in logs:

journalctl -u bisq-bot | grep -i relay

Should show:

Connecting to 2 relays...
Added relay: wss://relay.damus.io
Added relay: wss://relay.nostr.band
Connected to Nostr relays
Subscribing to mentions of a1b2c3d4e5...

Common Issues

Bot doesn't respond to mentions

Check 1: Verify Nostr connection

journalctl -u bisq-bot | grep -i nostr

Should show successful connection.

Check 2: Verify you're mentioning the right pubkey

Get the bot's public key from logs:

journalctl -u bisq-bot -n 5 | grep pubkey

Make sure mentions use this exact pubkey (or the display name if you set it).

Check 3: Verify message format

Try simple format:

USD BUY

or with mention:

@bisqbot USD BUY

Bisq query fails

Check 1: Bisq daemon running

bisq-cli --port=4848 getoffers --direction=BUY --currency-code=USD

If this command fails, Bisq isn't responding.

Check 2: Check Bisq logs

journalctl -u bisq || tail -f ~/.local/share/Bisq/bisq.log

Check 3: Restart Bisq

sudo systemctl restart bisq

Bot crashes with errors

Check logs:

journalctl -u bisq-bot -e

Look for error messages and search the README troubleshooting section.

What's Next?

Monitor Production

# SSH to server
ssh your-server

# Check status daily
sudo systemctl status bisq-bot

# Archive logs periodically
journalctl -u bisq-bot --rotate
journalctl -u bisq-bot --vacuum-time=30d

Customize Behavior

Edit response formats:

nano /opt/bisq-bot/src/formatter.py

Add support for more relays:

# Edit .env
NOSTR_RELAYS=wss://relay1.com,wss://relay2.com,wss://relay3.com

Phase 2 Features

Watch for updates enabling:

• Direct messages
• Market alerts
• Advanced analytics

Support

For issues:

1. Check the README.md troubleshooting section
2. Review ARCHITECTURE.md for design details
3. Check logs: journalctl -u bisq-bot -f
4. Search GitHub issues
5. Open a new issue with logs

Success!

Your bot is now:

• ✅ Listening to Nostr mentions
• ✅ Querying Bisq marketplace
• ✅ Publishing offer lists
• ✅ Responding to users

Users can now mention your bot to get real-time Bisq market data directly from Nostr!