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

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

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

```bash
sudo nano /opt/bisq-bot/.env
```

Add your private key:
```
BOT_PRIVATE_KEY=a1b2c3d4e5f6...  # Your key from Step 1
```

### Option B: Manual Setup

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

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

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

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

View logs:
```bash
journalctl -u bisq-bot -f
```

### Option B: Direct (Development/Testing)

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

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

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

```bash
sudo systemctl status bisq-bot
```

### View Recent Logs

```bash
journalctl -u bisq-bot -n 50
```

### Follow Live Logs

```bash
journalctl -u bisq-bot -f
```

### Check Relay Connections

Look for connection messages in logs:

```bash
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**
```bash
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:
```bash
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**
```bash
bisq-cli --port=4848 getoffers --direction=BUY --currency-code=USD
```

If this command fails, Bisq isn't responding.

**Check 2: Check Bisq logs**
```bash
journalctl -u bisq || tail -f ~/.local/share/Bisq/bisq.log
```

**Check 3: Restart Bisq**
```bash
sudo systemctl restart bisq
```

### Bot crashes with errors

Check logs:
```bash
journalctl -u bisq-bot -e
```

Look for error messages and search the README troubleshooting section.

## What's Next?

### Monitor Production

```bash
# 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:
```bash
nano /opt/bisq-bot/src/formatter.py
```

Add support for more relays:
```bash
# 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](README.md) troubleshooting section
2. Review [ARCHITECTURE.md](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!