delphi-kit 0.1.0__py3-none-any.whl

delphi_kit/watch.py

@@ -0,0 +1,209 @@
+"""Alerts for Delphi. Delphi has no notifications, webhooks or websocket, so this polls the chain and reports:
+
+- new markets
+- big moves in a market's probabilities
+- markets about to close
+- markets that close, settle (with the winner), fail or expire
+- money a wallet can now collect
+
+Alerts go to the terminal, as JSON lines, to a webhook, or to a Telegram chat.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Callable, Iterable, Optional
+
+import httpx
+
+from .chain import Call
+from .client import Delphi, _cache_dir
+from .models import STATUSES, Market
+from .search import rank
+
+
+@dataclass
+class Alert:
+    kind: str            # new_market | move | closing_soon | closed | settled | failed | expired | claimable
+    market: str
+    question: Optional[str]
+    text: str
+    data: dict = field(default_factory=dict)
+    at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+    def to_dict(self) -> dict:
+        return {"kind": self.kind, "market": self.market, "question": self.question, "text": self.text,
+                "data": self.data, "at": self.at}
+
+
+@dataclass
+class WatchConfig:
+    move: float = 0.10                  # alert when an outcome moves this much (absolute) since the last alert
+    closing_hours: float = 6.0          # alert once when an open market is this close to closing
+    query: str = ""                     # only markets matching these words (empty = all)
+    markets: frozenset[str] = frozenset()  # only these markets (empty = all)
+    wallet: Optional[str] = None        # also alert when this wallet has something to collect
+    kinds: frozenset[str] = frozenset()  # only these alert kinds (empty = all)
+
+
+class Watcher:
+    def __init__(self, delphi: Delphi, config: WatchConfig, state_file: Path | None = None):
+        self.d = delphi
+        self.cfg = config
+        name = f"watch-{delphi.network.name}.json"
+        self.state_file = state_file or _cache_dir() / name
+        self.state = self._load()
+
+    def _load(self) -> dict:
+        try:
+            return json.loads(self.state_file.read_text())
+        except (FileNotFoundError, ValueError):
+            return {}
+
+    def _save(self) -> None:
+        self.state_file.write_text(json.dumps(self.state))
+
+    def _wanted(self, m: Market) -> bool:
+        if self.cfg.markets and m.address.lower() not in self.cfg.markets:
+            return False
+        if self.cfg.query.strip() and not rank([m], self.cfg.query):
+            return False
+        return True
+
+    def poll(self) -> list[Alert]:
+        """One pass over the chain. The first pass only records a baseline and returns no alerts."""
+        d, st = self.d, self.state
+        first = not st
+        seen: dict = st.setdefault("status", {})
+        base: dict = st.setdefault("base", {})
+        warned: list = st.setdefault("closing_warned", [])
+        alerts: list[Alert] = []
+
+        addrs = d.market_addresses()
+        statuses = d.reader.run([Call(d._gw[d._where[a.lower()]], "marketStatus", [a]) for a in addrs])
+        now_status = {a: STATUSES[s] for a, s in zip(addrs, statuses) if isinstance(s, int)}
+
+        live = [a for a, s in now_status.items() if s == "open"]
+        if first:  # baseline: remember every status, only load the open markets
+            seen.update({a.lower(): s for a, s in now_status.items()})
+            changed: list[str] = []
+        else:
+            changed = [a for a, s in now_status.items() if seen.get(a.lower()) != s]
+        load = list(dict.fromkeys(live + changed))
+        markets = {m.address.lower(): m for m in d._load(load, with_rules=True)} if load else {}
+
+        for a in changed:
+            key, s = a.lower(), now_status[a]
+            m = markets.get(key)
+            prev = seen.get(key)
+            seen[key] = s
+            if first or m is None or not self._wanted(m):
+                continue
+            if prev is None:
+                if s == "open":
+                    odds = ", ".join(f"{o} {p:.0%}" for o, p in zip(m.outcomes, m.probabilities))
+                    alerts.append(Alert("new_market", m.address, m.question, f"New market: {m.question} [{odds}]",
+                                        {"outcomes": m.outcomes, "probabilities": m.probabilities}))
+                continue
+            if s == "awaiting_settlement":
+                alerts.append(Alert("closed", m.address, m.question, f"Trading closed: {m.question}"))
+            elif s == "settled":
+                win = m.outcomes[m.winning_outcome] if m.winning_outcome is not None and m.winning_outcome < len(m.outcomes) else "?"
+                alerts.append(Alert("settled", m.address, m.question, f"Settled: {m.question} → {win}",
+                                    {"winning_outcome": m.winning_outcome, "winning_label": win}))
+            elif s in ("failed", "expired"):
+                alerts.append(Alert(s, m.address, m.question,
+                                    f"{s.capitalize()} with no winner: {m.question}. Holders can liquidate at final prices."))
+
+        now = time.time()
+        for a in live:
+            m = markets.get(a.lower())
+            if m is None or not self._wanted(m) or not m.probabilities:
+                continue
+            key = a.lower()
+            ref = base.get(key)
+            if ref is None or len(ref) != len(m.probabilities):
+                base[key] = m.probabilities
+            else:
+                moves = [p - r for p, r in zip(m.probabilities, ref)]
+                j = max(range(len(moves)), key=lambda i: abs(moves[i]))
+                if abs(moves[j]) >= self.cfg.move:
+                    base[key] = m.probabilities
+                    if not first:
+                        label = m.outcomes[j] if j < len(m.outcomes) else f"outcome {j}"
+                        alerts.append(Alert("move", m.address, m.question,
+                                            f"{label} {ref[j]:.0%} → {m.probabilities[j]:.0%}: {m.question}",
+                                            {"outcome": j, "from": ref[j], "to": m.probabilities[j]}))
+            close = m.trading_closes_at.timestamp() if m.trading_closes_at else None
+            if close and 0 < close - now <= self.cfg.closing_hours * 3600 and key not in warned:
+                warned.append(key)
+                if not first:
+                    hrs = (close - now) / 3600
+                    alerts.append(Alert("closing_soon", m.address, m.question,
+                                        f"Closes in {hrs:.1f} h: {m.question}", {"closes_at": m.trading_closes_at.isoformat()}))
+
+        if self.cfg.wallet:
+            have = set(st.setdefault("claimable", []))
+            for p in self.d.positions(self.cfg.wallet):
+                if p.action and f"{p.market}:{p.outcome}" not in have:
+                    have.add(f"{p.market}:{p.outcome}")
+                    if not first:
+                        amount = f" ${p.claimable_usd:.2f}" if p.claimable_usd else ""
+                        alerts.append(Alert("claimable", p.market, p.question,
+                                            f"You can {p.action}{amount}: {p.question}", p.to_dict()))
+            st["claimable"] = sorted(have)
+
+        st["closing_warned"] = warned[-2000:]
+        self._save()
+        if self.cfg.kinds:
+            alerts = [a for a in alerts if a.kind in self.cfg.kinds]
+        return alerts
+
+    def run(self, every: float, sinks: Iterable[Callable[[Alert], None]], once: bool = False) -> None:
+        sinks = list(sinks)
+        while True:
+            try:
+                for a in self.poll():
+                    for s in sinks:
+                        try:
+                            s(a)
+                        except Exception as e:  # noqa: BLE001
+                            print(f"alert delivery failed: {e}", file=sys.stderr)
+            except Exception as e:  # noqa: BLE001  (RPC hiccup: try again next round)
+                print(f"poll failed: {e}", file=sys.stderr)
+            if once:
+                return
+            time.sleep(every)
+
+
+# ------------------------------------------------------------------ sinks
+
+def print_sink(json_lines: bool = False) -> Callable[[Alert], None]:
+    def f(a: Alert) -> None:
+        print(json.dumps(a.to_dict()) if json_lines else f"[{a.kind}] {a.text}  {a.market}", flush=True)
+    return f
+
+
+def webhook_sink(url: str) -> Callable[[Alert], None]:
+    http = httpx.Client(timeout=15)
+
+    def f(a: Alert) -> None:
+        http.post(url, json=a.to_dict()).raise_for_status()
+    return f
+
+
+def telegram_sink(token: str | None = None, chat_id: str | None = None) -> Callable[[Alert], None]:
+    token = token or os.environ["TELEGRAM_BOT_TOKEN"]
+    chat_id = chat_id or os.environ["TELEGRAM_CHAT_ID"]
+    http = httpx.Client(timeout=15)
+
+    def f(a: Alert) -> None:
+        http.post(f"https://api.telegram.org/bot{token}/sendMessage",
+                  json={"chat_id": chat_id, "text": a.text, "disable_web_page_preview": True}).raise_for_status()
+    return f

delphi_kit-0.1.0.dist-info/METADATA

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: delphi-kit
+Version: 0.1.0
+Summary: Read and trade Delphi prediction markets from Python and AI agents, with no API key: every market type, quotes, trades, positions, search, alerts and an MCP server.
+Keywords: delphi,gensyn,prediction-markets,mcp,agents,web3
+License-Expression: MIT
+Requires-Dist: httpx>=0.27
+Requires-Dist: web3>=7
+Requires-Dist: mcp>=2.3 ; extra == 'mcp'
+Requires-Python: >=3.10
+Project-URL: Repository, https://github.com/neromtoobad/delphi-kit
+Provides-Extra: mcp
+Description-Content-Type: text/markdown
+
+# delphi-kit
+
+Python tools for [Delphi](https://delphi.fyi), the prediction market on the Gensyn chain. It has a library, a
+`delphi` command, an MCP server so AI agents can trade under spending limits, and alerts.
+
+It reads straight from the chain, so you need **no API key** to list, search, price or track anything. A wallet
+key is only needed to trade.
+
+It covers **every Delphi market on mainnet**: the current LMSR markets and both older parimutuel (DPM)
+generations. That's 1,027 markets as of November 2026.
+
+```bash
+pip install delphi-kit            # library + CLI
+pip install "delphi-kit[mcp]"     # + MCP server
+```
+
+## Find a market and price a trade
+
+```console
+$ delphi search bitcoin --limit 3
+0x44CF6d128e086961b7c0844dE6285c75046d7B7C  Dec 25 05:00  $  27.85  Yes 17%  No 83%
+    Will Bitcoin exceed $100,000 by Christmas 2026?
+0x662Bba4819098F000d33d1e09Dff5dC3C3a5aa87  Dec 31 00:00  $  19.11  Yes 33%  No 67%
+    Will Bitcoin's Coinbase BTC-USD price be above $80,000 at 00:00 UTC on Dec 31, 2026?
+0xc43F7318bf91915dba2A3A02489bdEd2aDC1731f  Jan 01 02:00  $  39.52  Yes 22%  No 78%
+    Will Bitcoin reach $100k in 2026?
+
+$ delphi quote 0x4F5DC6b636c226CeC0C2403f988f24431b9Cc463 Yes --usd 5
+buy 7.7223 Yes shares costs $4.9996 (avg 0.6474); probability 50.4% → 75.3%
+```
+
+Most Delphi pools hold $10–$50, so a $5 trade can move the price 25 points. Every quote shows the probability
+after your trade so you see that before you pay.
+
+`delphi market <address>` prints the rules the AI judge will apply and the sources it will read. It also checks
+that the rules file matches the hash stored on chain.
+
+## Library
+
+```python
+from delphi_kit import Delphi
+
+d = Delphi()                                   # mainnet, read-only
+for m in d.search("election", limit=5):
+    print(m.summary())
+
+m = d.market("0x4F5DC6b636c226CeC0C2403f988f24431b9Cc463")
+print(m.rules, m.sources, m.metadata_verified)
+
+q = d.quote_buy(m, "Yes", usd=2)               # shares, average price, probability before/after
+print(q.shares, q.average_price, q.probability_after)
+
+d = Delphi(private_key="0x...")                # or set DELPHI_PRIVATE_KEY
+t = d.buy(m, "Yes", usd=2, max_slippage=0.02)  # approves only what this trade needs
+d.sell(m, "Yes")                               # everything you hold in that outcome
+
+for p in d.positions():                        # every market, with what to do next
+    print(p.question, p.outcome_label, p.shares, p.value_usd, p.action)  # action: redeem | liquidate | None
+```
+
+You can pass an address or a `Market` anywhere one is expected, and outcomes take a label (`"Yes"`) or an index.
+Money comes back as USD floats and shares as decimal numbers; every object has `.to_dict()`.
+
+## Command line
+
+| command | does |
+|---|---|
+| `delphi markets [--status open\|settled\|…\|all]` | list markets with live odds, soonest to close first |
+| `delphi search <words>` | keyword search over questions, outcomes and rules |
+| `delphi market <address>` | one market in full: rules, sources, deadlines, fee, hash check |
+| `delphi quote <address> <outcome> --usd N \| --shares N \| --sell N` | price a trade, send nothing |
+| `delphi buy <address> <outcome> --usd N` | buy (asks you to type `yes` first unless `--yes`) |
+| `delphi sell <address> <outcome> [--shares N]` | sell, default everything |
+| `delphi positions [wallet]` | what a wallet holds and can collect |
+| `delphi collect <address>` | redeem a settled market, or liquidate an expired or failed one |
+| `delphi balance` | your USDC and gas |
+| `delphi watch …` | alerts, see below |
+
+Add `--json` to any command for machine output, and `--network testnet` or `--network competition-testnet` to
+leave mainnet.
+
+## MCP server: let an agent trade, with limits
+
+Claude Code:
+
+```bash
+claude mcp add delphi -- uvx --from "delphi-kit[mcp]" delphi-mcp
+```
+
+Claude Desktop, Cursor, or anything else that speaks MCP over stdio:
+
+```json
+{
+  "mcpServers": {
+    "delphi": {
+      "command": "uvx",
+      "args": ["--from", "delphi-kit[mcp]", "delphi-mcp"],
+      "env": {
+        "DELPHI_PRIVATE_KEY": "0x...",
+        "DELPHI_ALLOW_TRADING": "true",
+        "DELPHI_MAX_TRADE_USD": "2",
+        "DELPHI_MAX_DAILY_USD": "10"
+      }
+    }
+  }
+}
+```
+
+The read tools are `list_markets`, `get_market`, `quote_buy`, `quote_sell`, `get_positions` and `wallet_status`.
+The write tools are `buy`, `sell` and `collect`.
+
+Without a key or `DELPHI_ALLOW_TRADING=true` the server is read-only, and the write tools say so instead of
+sending anything. With trading on, every buy is checked first:
+
+| setting | default |
+|---|---|
+| `DELPHI_MAX_TRADE_USD` | 5 per trade |
+| `DELPHI_MAX_DAILY_USD` | 20 per UTC day, kept in a ledger file so a restart doesn't reset it |
+| `DELPHI_MAX_SLIPPAGE` | 0.03 |
+| `DELPHI_ALLOWED_MARKETS` | all (comma list of addresses to restrict) |
+
+Use a separate wallet for the agent and only put in what you're willing to lose.
+
+## Alerts
+
+Delphi has no notifications or webhooks, so `delphi watch` polls the chain and tells you about:
+
+- new markets
+- moves of 10 points or more (`--move`)
+- markets about to close (`--closing-hours`)
+- markets that close, settle (with the winner), fail or expire
+- money your wallet can now collect (`--wallet`)
+
+```bash
+delphi watch --query "bitcoin" --telegram            # TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID
+delphi watch --wallet 0xYou --webhook https://…      # each alert POSTed as JSON
+delphi watch --json --once                           # one pass, JSON lines (for cron)
+```
+
+The first run records a baseline, and alerts start from the second check.
+
+## What this does that the official SDK doesn't
+
+[`@gensyn-ai/gensyn-delphi-sdk`](https://www.npmjs.com/package/@gensyn-ai/gensyn-delphi-sdk) 2.1.0 is TypeScript
+only. Its mainnet config has the two DPM deployments but **not the LMSR one**, and LMSR is where most open markets
+are (56 of 82 when this was written). LMSR quote functions also return three values where DPM returns one. Full
+notes are in [docs/contracts.md](docs/contracts.md).
+
+| | SDK 2.1.0 | delphi-kit |
+|---|---|---|
+| Language | TypeScript | Python |
+| Mainnet LMSR markets | no | yes |
+| List markets and positions without an API key | no (REST API needs a key) | yes, from chain |
+| Keyword search | no (category filter only) | yes |
+| Rules-file hash check | no | yes |
+| Buy with a dollar budget | no (exact shares) | yes, never over budget |
+| Default approval | unlimited | exact amount |
+| Agent spending limits | no | yes |
+| Alerts | no | yes |
+
+## Tests
+
+```bash
+uv run pytest tests/test_unit.py      # offline, about a second
+uv run pytest tests/test_fork.py -s   # needs Foundry's anvil, about a minute, no real money
+```
+
+The fork tests run a private copy of Gensyn mainnet and put a throwaway wallet through two full lifecycles:
+
+- **LMSR:** buy with a $3 budget, sell half, jump the clock past the deadline, settle as Delphi's oracle relayer,
+  redeem the winnings.
+- **DPM:** buy, let the market expire unsettled, liquidate.
+
+## License
+
+MIT

delphi_kit-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+delphi_kit/__init__.py,sha256=DBWylaS-fB8-D2wQUWN2h1PrDvgBeASkC0_MUFOaxVk,420
+delphi_kit/abi/DelphiFactory.json,sha256=5lZlOQzliwey5i0or8XV81L5Nz5VhPwBL8zN9tZpxCE,5573
+delphi_kit/abi/DpmGateway.json,sha256=y39nHVO4Ittt5JCPvpcjNnW5x1xO-41sf8Agxo0ITEA,23823
+delphi_kit/abi/DpmGatewayLegacy.json,sha256=nsJkJ2WNxgUOgJLGz_SFdwnTOwP2ZJy8D15zZ57UHko,19787
+delphi_kit/abi/LmsrGateway.json,sha256=qZP4snpWC8M9TYvNZEIZluOSfAM6Z5uSXsUWc6R6qtw,22642
+delphi_kit/abi/LmsrMarket.json,sha256=VXg6wFHS7QAjWfWhM8kOooiPKumDSjOwDW0os2YG_68,25843
+delphi_kit/abi/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+delphi_kit/chain.py,sha256=uARqaC-nie58qkwBlc2p98aD0SckBoAYno7Gtvdo8g0,5318
+delphi_kit/cli.py,sha256=0tN0Yzvnkjkbop_C3zDYH42I2yy4cqmGxAx7jbnGu1Q,9253
+delphi_kit/client.py,sha256=Fo-51vRzX87Fda7kDJuEUj8y-7qPW8aAkZ_v3gesJu4,25181
+delphi_kit/limits.py,sha256=hkmLe06Twoex3e-_O5XjDQnkQptbxuNyPVeeqoq3fQk,3675
+delphi_kit/mcp_server.py,sha256=jVT6v7GtPIoGGTuqEZ0NhLatt9GvuzbxyrXAQsgFndk,6987
+delphi_kit/models.py,sha256=3KQsMBVvwPGGHvZeTACHTmpNTIlpLIUv65uPSE3xoAI,4171
+delphi_kit/networks.py,sha256=lEcwTMwySV9jH__Nvhlkrz5ulJCUIuO2z4I8NabrxwA,3854
+delphi_kit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+delphi_kit/search.py,sha256=edwi9C3aUMo3LJ5a_GE_VVNebBJ69j9Cp4GsUUG3Aw8,1466
+delphi_kit/watch.py,sha256=ndO7MQ8fW3MXThSHIvvG9HBOK5yDR4q1_e1EiYbeMs0,9146
+delphi_kit-0.1.0.dist-info/WHEEL,sha256=3OmCxFA0ffBIsX4x0o8CdfSvZAOvO3mzEG8U_z5TvV4,80
+delphi_kit-0.1.0.dist-info/entry_points.txt,sha256=W0brzA13OpRHa5tkggs7K5ppBCfsd6S8Gp9aOWyG-Rs,88
+delphi_kit-0.1.0.dist-info/METADATA,sha256=vc1W845HnJnTDsuxUeKgbFa716EYaDTE0Eg2YcZxEvU,7580
+delphi_kit-0.1.0.dist-info/RECORD,,

delphi_kit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.8
+Root-Is-Purelib: true
+Tag: py3-none-any

delphi_kit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+delphi = delphi_kit.cli:main
+delphi-mcp = delphi_kit.mcp_server:main
+