Metadata-Version: 2.4
Name: polywatch
Version: 0.1.0
Summary: Get pinged the second a Polymarket market moves. Tiny Python CLI, multi-channel alerts.
Author: creampig666
License: MIT
Project-URL: Homepage, https://github.com/creampig666/polywatch
Project-URL: Issues, https://github.com/creampig666/polywatch/issues
Keywords: polymarket,prediction-markets,alerts,trading,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.25
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# polywatch

> Get pinged the second a Polymarket market moves.
> 
> **No install? Try the live dashboard first: https://creampig666.github.io/prediction-markets-live/**

Tiny Python CLI that polls Polymarket's public gamma API, watches the outcomes you care about, and fires alerts to your **console / Telegram / Discord** the moment a price crosses a threshold you set.

No keys, no auth, no signup. Just a YAML file and a wallet for tips.

> **Family of tools** (same author, same wallet, same UX):
> - 🟢 **polywatch** — you're here
> - 🟢 [**kalshiwatch**](https://github.com/creampig666/kalshiwatch) — same idea, Kalshi-side
> - 🟢 [**manifold-watch**](https://github.com/creampig666/manifold-watch) — same idea, Manifold-side. Run all three for tri-venue divergence
> - 🟢 [**polywatch-presets**](https://github.com/creampig666/polywatch-presets) — ready-made polywatch configs (politics / crypto / sports / geopolitics / tech-AI)
> - 🟢 [**prediction-market-mcp**](https://github.com/creampig666/prediction-market-mcp) — MCP server exposing all 3 venues to Claude/LLMs, with 3-venue arb discovery
> - 🟢 [**prediction-markets-live**](https://github.com/creampig666/prediction-markets-live) — read-only browser dashboard
> 
> Writeup on the whole family + what I'd skip if I did it again: [**Six prediction-market tools in a day**](https://github.com/creampig666/notes/blob/main/posts/2026-06-04-six-prediction-market-tools-in-a-day.md)

```
[polywatch] Newsom 2028 D nomination :: Yes [UP] 0.420 -> 0.461 (+9.76%)
[polywatch] Netherlands 2026 WC      :: Yes [DN] 0.180 -> 0.155 (-13.89%)
```

---

## Why

If you trade prediction markets, you already know: **the move happens in the 30 seconds you weren't looking**. Manual refresh tabs don't cut it. Most "Polymarket alert bots" are SaaS lock-ins or pay-walled Discord servers. This is **one Python file's worth of logic**, MIT, and it runs on your laptop / cheap VPS / Raspberry Pi.

Built because I wanted it for my own poly trading and it didn't exist in a form I'd actually trust.

## Install

```bash
pip install git+https://github.com/creampig666/polywatch.git
```

Or clone:

```bash
git clone https://github.com/creampig666/polywatch.git
cd polywatch && pip install -e .
```

## 60-second start

```bash
polywatch init           # writes config.yaml
$EDITOR config.yaml      # change the slugs to ones you actually care about
polywatch test-alert     # verify your Telegram / Discord wiring
polywatch run            # go
```

Sample `config.yaml`:

```yaml
poll_interval_sec: 30

markets:
  - slug: will-gavin-newsom-win-the-2028-democratic-presidential-nomination-568
    name: Newsom 2028 D nomination
    watch:
      - outcome: "Yes"
        threshold_pct: 3       # alert when price moves >= 3% from last poll
        direction: any         # up | down | any

  - slug: will-netherlands-win-the-2026-fifa-world-cup-739
    name: Netherlands 2026 WC
    watch:
      - outcome: "Yes"
        threshold_pct: 5
        direction: up          # only on upward crossings

alerts:
  console: true
  # telegram:
  #   bot_token: ${TELEGRAM_BOT_TOKEN}   # env vars supported
  #   chat_id: ${TELEGRAM_CHAT_ID}
  # discord:
  #   webhook: https://discord.com/api/webhooks/.../...
```

The `slug` is whatever's in the Polymarket URL after `/event/`. Multiple `watch` rules per market are fine.

## How it works

1. Every `poll_interval_sec` seconds, fetch each configured market from `gamma-api.polymarket.com`.
2. Compare each rule's outcome price to the price seen last tick.
3. If the change ≥ threshold (and direction matches), build an `AlertEvent` and dispatch to every enabled channel.
4. Failed channels log the error and don't break the loop.

State is in-memory — restart resets the comparison baseline, no DB.

## Run as a service

systemd (Linux):

```ini
[Unit]
Description=polywatch
After=network.target

[Service]
Type=simple
WorkingDirectory=/home/you/polywatch
ExecStart=/usr/bin/polywatch run -c /home/you/polywatch/config.yaml
Restart=on-failure
Environment=TELEGRAM_BOT_TOKEN=xxx
Environment=TELEGRAM_CHAT_ID=yyy

[Install]
WantedBy=multi-user.target
```

cron mode (one-shot):

```cron
* * * * * /usr/bin/polywatch run --once -c /home/you/polywatch/config.yaml
```

## Roadmap (PRs welcome)

- [ ] Whale-trade alerts (volume spike, not just price)
- [ ] Cross-venue divergence (Polymarket vs Kalshi vs Manifold)
- [ ] State persistence so restarts don't reset baselines
- [ ] Per-rule cooldown to avoid noisy markets

If any of these would change your workflow, open an issue.

## Tip jar

This is free and stays free. If polywatch saved you a bad trade or a refresh tic, tips are welcome:

```
0x17Fb06dE9D5945eaFf6FBBf4c264E505D38182A4   # EVM (ETH / USDC / any EVM L2)
```

## License

MIT. See [LICENSE](./LICENSE).
