nothing-ever-happens-polymarket-bot

What this skill does

# Nothing Ever Happens Polymarket Bot

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

An async Python bot that scans Polymarket standalone non-sports yes/no markets and buys the "No" outcome on any market where the NO price is below a configured cap. Designed for paper trading by default with explicit opt-in to live order transmission.

---

## What It Does

- Scans Polymarket for standalone (non-grouped) yes/no markets
- Filters out sports markets
- Buys NO positions when NO price is below `max_no_price` threshold
- Tracks open positions and persists recovery state to a database
- Exposes a live dashboard (HTTP) showing portfolio and activity
- Uses `PaperExchangeClient` unless all three live-mode env vars are set

---

## Installation

```bash
git clone https://github.com/sterlingcrispin/nothing-ever-happens.git
cd nothing-ever-happens
pip install -r requirements.txt
cp config.example.json config.json
cp .env.example .env
```

---

## Configuration

### `config.json` (non-secret runtime settings)

Edit the `strategies.nothing_happens` block:

```json
{
  "strategies": {
    "nothing_happens": {
      "max_no_price": 0.08,
      "order_size_usdc": 1.0,
      "max_open_positions": 50,
      "scan_interval_seconds": 60,
      "min_liquidity_usdc": 100,
      "exclude_keywords": ["sport", "nfl", "nba", "mlb", "nhl", "soccer", "tennis"]
    }
  }
}
```

Point to a different config file:

```bash
CONFIG_PATH=/path/to/other_config.json python -m bot.main
```

### `.env` (secrets and runtime flags)

```dotenv
# Safety flags — ALL three required for live order transmission
BOT_MODE=paper               # set to "live" for real orders
DRY_RUN=true                 # set to "false" for real orders
LIVE_TRADING_ENABLED=false   # set to "true" for real orders

# Required only in live mode
PRIVATE_KEY=$PRIVATE_KEY
FUNDER_ADDRESS=$FUNDER_ADDRESS
DATABASE_URL=$DATABASE_URL
POLYGON_RPC_URL=$POLYGON_RPC_URL

# Optional
PORT=8080
DASHBOARD_PORT=8080
```

> **Never hardcode secrets.** Always use environment variable references.

---

## Running Locally

```bash
# Paper trading (default — safe, no real orders)
python -m bot.main

# Enable live trading (requires all three flags)
BOT_MODE=live DRY_RUN=false LIVE_TRADING_ENABLED=true python -m bot.main
```

The dashboard will bind to `$PORT` or `$DASHBOARD_PORT` when set.

---

## Project Structure

```
bot/
  main.py               # Entry point — starts the runtime loop
  strategies/
    nothing_happens.py  # Core strategy: scan, filter, buy NO
  exchange/
    client.py           # Live exchange client (Polymarket CLOB API)
    paper_client.py     # PaperExchangeClient for safe simulation
  dashboard.py          # HTTP dashboard server
  recovery.py           # Persist and restore open positions

scripts/
  db_stats.py           # Inspect DB table counts and recent activity
  export_db.py          # Export live DB tables
  wallet_history.py     # Positions, trades, balances for configured wallet
  parse_logs.py         # Convert Heroku JSON logs to readable output

tests/                  # Unit and regression tests
```

---

## Key Commands

### Run Tests

```bash
python -m pytest -q
```

### Operational Scripts

```bash
# Inspect live database
python scripts/db_stats.py

# Export database tables (uses DATABASE_URL or Heroku app)
python scripts/export_db.py

# Pull wallet history
python scripts/wallet_history.py

# Parse Heroku JSON logs into readable output
python scripts/parse_logs.py
```

---

## Heroku Deployment

### One-time setup

```bash
export HEROKU_APP_NAME=my-polymarket-bot

# Set runtime flags
heroku config:set BOT_MODE=live DRY_RUN=false LIVE_TRADING_ENABLED=true \
  -a "$HEROKU_APP_NAME"

# Set secrets
heroku config:set \
  PRIVATE_KEY="$PRIVATE_KEY" \
  FUNDER_ADDRESS="$FUNDER_ADDRESS" \
  POLYGON_RPC_URL="$POLYGON_RPC_URL" \
  DATABASE_URL="$DATABASE_URL" \
  -a "$HEROKU_APP_NAME"

# Deploy
git push heroku main:main

# Scale — ONLY the web dyno
heroku ps:scale web=1 worker=0 -a "$HEROKU_APP_NAME"
```

> Do **not** run the `worker` dyno. It exists only to fail fast if started accidentally.

### Shell helpers

```bash
./alive.sh              # Check if the app is alive
./logs.sh               # Tail logs
./live_enabled.sh       # Enable live trading
./live_disabled.sh      # Disable live trading (back to paper)
./kill.sh               # Stop the bot
```

All helpers use `$HEROKU_APP_NAME` or accept an app name as an argument:

```bash
./logs.sh my-polymarket-bot
```

---

## Safety Model

The bot defaults to `PaperExchangeClient` (simulated orders, no real money) unless **all three** of these are set:

| Variable | Required value |
|---|---|
| `BOT_MODE` | `live` |
| `LIVE_TRADING_ENABLED` | `true` |
| `DRY_RUN` | `false` |

If any one is missing or wrong, paper mode is used. This is intentional — it makes accidental live trading very hard.

Additional live-mode requirements:
- `PRIVATE_KEY` — wallet private key
- `FUNDER_ADDRESS` — required for signature types `1` and `2`
- `DATABASE_URL` — for recovery state persistence
- `POLYGON_RPC_URL` — for proxy-wallet approvals and redemption

---

## Code Examples

### Check if bot will use live or paper mode

```python
import os

def is_live_mode() -> bool:
    return (
        os.getenv("BOT_MODE") == "live"
        and os.getenv("LIVE_TRADING_ENABLED", "").lower() == "true"
        and os.getenv("DRY_RUN", "true").lower() == "false"
    )

print("Live mode:", is_live_mode())
```

### Load strategy config

```python
import json, os

config_path = os.getenv("CONFIG_PATH", "config.json")
with open(config_path) as f:
    config = json.load(f)

strategy_cfg = config["strategies"]["nothing_happens"]
max_no_price = strategy_cfg["max_no_price"]       # e.g. 0.08
order_size   = strategy_cfg["order_size_usdc"]    # e.g. 1.0
print(f"Will buy NO when price <= {max_no_price} USDC, size={order_size} USDC")
```

### Run the bot programmatically

```python
import asyncio
from bot.main import main

asyncio.run(main())
```

### Inspect DB stats

```bash
DATABASE_URL=$DATABASE_URL python scripts/db_stats.py
```

### Parse Heroku logs to HTML

```bash
heroku logs --num=1500 -a "$HEROKU_APP_NAME" | python scripts/parse_logs.py --html > report.html
```

### Export DB from a Heroku app

```bash
python scripts/export_db.py --app "$HEROKU_APP_NAME"
```

---

## Common Patterns

### Disabling live trading quickly (kill switch)

```bash
heroku config:set LIVE_TRADING_ENABLED=false -a "$HEROKU_APP_NAME"
# or use the helper:
./live_disabled.sh
```

The bot will immediately fall back to paper mode on next cycle without a restart.

### Adjusting the NO price cap without redeploying

Edit `config.json`, commit, and push:

```bash
# Lower the cap to only buy very cheap NOs
jq '.strategies.nothing_happens.max_no_price = 0.05' config.json > tmp.json && mv tmp.json config.json
git add config.json && git commit -m "lower max_no_price to 0.05"
git push heroku main:main
```

### Adding more keyword exclusions

```json
{
  "strategies": {
    "nothing_happens": {
      "exclude_keywords": ["sport", "nfl", "nba", "mlb", "nhl", "soccer", "tennis", "golf", "ufc", "esport"]
    }
  }
}
```

---

## Troubleshooting

| Symptom | Likely Cause | Fix |
|---|---|---|
| Bot uses paper mode unexpectedly | One of the three live flags is missing/wrong | Check all three: `BOT_MODE`, `LIVE_TRADING_ENABLED`, `DRY_RUN` |
| `DATABASE_URL` errors in live mode | Postgres not provisioned | `heroku addons:create heroku-postgresql -a "$HEROKU_APP_NAME"` |
| Orders never transmit | `DRY_RUN` still `true` | `heroku config:set DRY_RUN=false` |
| Dashboard not accessible | `PORT` not set | `heroku config:set PORT=8080` |
| Worker dyno crashes immediately | Don't run worker dyno | `heroku ps:scale worker=0` |
| Bot buys sports markets | Keywords not in `exclude_keywords` | Add sport/league names to config |
| Logs unreadable (JSON) | Heroku structured logging | Pipe through `scripts/parse_logs.py` |

---