Metadata-Version: 2.4
Name: kalshiwatch
Version: 0.1.0
Summary: Get pinged the second a Kalshi market moves. Tiny Python CLI, multi-channel alerts.
Author: creampig666
License: MIT
Project-URL: Homepage, https://github.com/creampig666/kalshiwatch
Project-URL: Issues, https://github.com/creampig666/kalshiwatch/issues
Keywords: kalshi,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

# kalshiwatch

> Get pinged the second a Kalshi market moves.
> 
> **Polymarket-side preview (live, no install): https://creampig666.github.io/prediction-markets-live/**

Tiny Python CLI that polls Kalshi's public market API, watches the tickers you care about, and fires alerts to your **console / Telegram / Discord** the moment a market's implied probability crosses a threshold you set.

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

```
[kalshiwatch] Elon to Mars in lifetime [UP] 0.080 -> 0.095 (+18.75%)
[kalshiwatch] Mamdani president by 45  [DN] 0.098 -> 0.080 (-18.37%)
```

> **Family of tools** (same author, same wallet, same UX):
> - 🟢 [**polywatch**](https://github.com/creampig666/polywatch) — same idea, Polymarket-side
> - 🟢 **kalshiwatch** — you're here
> - 🟢 [**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
> - 🟢 [**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

---

## Why

Kalshi is the regulated US-side counterpart to Polymarket. The trading day moves fast — political markets in particular can pop 5-15% within a few minutes after news drops, and the only "alerts" Kalshi gives you are weak email digests. This is **one Python file's worth of logic** that runs anywhere, MIT, and pings you on whatever channel you're already using.

Built to use alongside polywatch for cross-venue divergence trading.

## Install

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

Or clone:

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

## 60-second start

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

Sample `config.yaml`:

```yaml
poll_interval_sec: 30

markets:
  - ticker: KXELONMARS-99
    name: Elon to Mars in lifetime
    threshold_pct: 5       # alert when price moves >= 5% from last poll
    direction: any         # up | down | any

  - ticker: KXPERSONPRESMAM-45
    name: Mamdani president by 45
    threshold_pct: 3
    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 `ticker` is the Kalshi market identifier shown on each market page (e.g. `KXELONMARS-99`, `KXNEWPOPE-70-PPAR`). You can find it in the Kalshi URL or in the page metadata.

## How it works

1. Every `poll_interval_sec` seconds, fetch each configured market from `api.elections.kalshi.com`.
2. Compare each market's `last_price_dollars` (0.0 – 1.0, the implied probability) 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.

## Kalshi vs Polymarket

If you trade both, you probably want **both [polywatch](https://github.com/creampig666/polywatch) and kalshiwatch** running side by side — same alert channels, same UX. Divergence between a Polymarket "Yes" price and a Kalshi "Yes" price on the same underlying event is one of the simplest live arb signals.

## Run as a service

systemd (Linux):

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

[Service]
Type=simple
WorkingDirectory=/home/you/kalshiwatch
ExecStart=/usr/bin/kalshiwatch run -c /home/you/kalshiwatch/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/kalshiwatch run --once -c /home/you/kalshiwatch/config.yaml
```

## Roadmap (PRs welcome)

- [ ] Bid/ask alerts once an auth mode is added (orderbook-aware)
- [ ] Cross-venue divergence alerts (Polymarket vs Kalshi on matched underlyings)
- [ ] 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 kalshiwatch saved you a bad fill or a refresh tic, tips are welcome:

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

## License

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