delphi-kit 0.1.0__py3-none-any.whl

delphi_kit/cli.py

@@ -0,0 +1,191 @@
+"""Command line: `delphi markets`, `delphi search`, `delphi market`, `delphi quote`, `delphi buy`, `delphi sell`,
+`delphi positions`, `delphi collect`, `delphi balance`, `delphi watch`."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .client import Delphi, DelphiError
+
+
+def _out(obj, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(obj, indent=2, default=str))
+
+
+def _market_line(m) -> str:
+    odds = "  ".join(f"{o} {p:.0%}" for o, p in zip(m.outcomes, m.probabilities))
+    close = m.trading_closes_at.strftime("%b %d %H:%M") if m.trading_closes_at else "?"
+    return f"{m.address}  {close:>12}  ${m.pool_usd or 0:>7.2f}  {odds}\n    {m.question}"
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="delphi", description="Read and trade Delphi prediction markets. No API key needed.")
+    p.add_argument("--network", default=None, help="mainnet (default), testnet or competition-testnet")
+    p.add_argument("--json", action="store_true", help="print JSON")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("markets", help="list markets with live odds")
+    s.add_argument("--status", default="open", help="open | awaiting_settlement | settled | expired | failed | all")
+    s.add_argument("--limit", type=int, default=25)
+
+    s = sub.add_parser("search", help="find markets by keywords")
+    s.add_argument("query", nargs="+")
+    s.add_argument("--status", default="open")
+    s.add_argument("--limit", type=int, default=10)
+
+    s = sub.add_parser("market", help="one market in full, with its rules and sources")
+    s.add_argument("address")
+
+    s = sub.add_parser("quote", help="price a buy or sell without sending anything")
+    s.add_argument("address")
+    s.add_argument("outcome", help='label ("Yes") or index')
+    g = s.add_mutually_exclusive_group(required=True)
+    g.add_argument("--usd", type=float, help="buy with this budget")
+    g.add_argument("--shares", type=float, help="buy this many shares")
+    g.add_argument("--sell", type=float, metavar="SHARES", help="sell this many shares")
+
+    s = sub.add_parser("buy", help="buy shares (needs DELPHI_PRIVATE_KEY)")
+    s.add_argument("address")
+    s.add_argument("outcome")
+    s.add_argument("--usd", type=float, required=True)
+    s.add_argument("--max-slippage", type=float, default=0.02)
+    s.add_argument("--yes", action="store_true", help="skip the confirmation prompt")
+
+    s = sub.add_parser("sell", help="sell shares (needs DELPHI_PRIVATE_KEY)")
+    s.add_argument("address")
+    s.add_argument("outcome")
+    s.add_argument("--shares", type=float, default=None, help="default: all you hold")
+    s.add_argument("--max-slippage", type=float, default=0.02)
+    s.add_argument("--yes", action="store_true")
+
+    s = sub.add_parser("positions", help="what a wallet holds and can collect")
+    s.add_argument("wallet", nargs="?")
+
+    s = sub.add_parser("collect", help="redeem a settled market or liquidate an expired/failed one")
+    s.add_argument("address")
+
+    sub.add_parser("balance", help="your wallet's USDC and gas")
+
+    s = sub.add_parser("watch", help="alerts: new markets, big moves, closing soon, settlements, money to collect")
+    s.add_argument("--every", type=float, default=60, help="seconds between checks")
+    s.add_argument("--move", type=float, default=0.10, help="alert on probability moves of this size (0.10 = 10 points)")
+    s.add_argument("--closing-hours", type=float, default=6)
+    s.add_argument("--query", default="", help="only markets matching these words")
+    s.add_argument("--market", action="append", default=[], help="only this market (repeatable)")
+    s.add_argument("--wallet", default=None, help="also alert when this wallet can collect money")
+    s.add_argument("--only", default="", help="comma list of alert kinds")
+    s.add_argument("--webhook", default=None, help="POST each alert as JSON to this URL")
+    s.add_argument("--telegram", action="store_true", help="send to TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID")
+    s.add_argument("--once", action="store_true", help="check once and exit")
+
+    a = p.parse_args(argv)
+    import os
+    d = Delphi(a.network or os.environ.get("DELPHI_NETWORK", "mainnet"))
+    try:
+        return _run(d, a)
+    except (DelphiError, ValueError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+
+def _confirm(text: str, yes: bool) -> bool:
+    if yes:
+        return True
+    return input(f"{text} Type yes to send: ").strip().lower() == "yes"
+
+
+def _run(d: Delphi, a) -> int:
+    if a.cmd in ("markets", "search"):
+        st = None if a.status == "all" else a.status
+        ms = d.search(" ".join(a.query), status=st, limit=a.limit) if a.cmd == "search" else d.markets(status=st, limit=a.limit)
+        if a.json:
+            _out([{k: v for k, v in m.to_dict().items() if k != "raw_metadata"} for m in ms], True)
+        else:
+            for m in ms:
+                print(_market_line(m))
+            print(f"\n{len(ms)} market(s)")
+        return 0
+    if a.cmd == "market":
+        m = d.market(a.address)
+        if a.json:
+            _out({k: v for k, v in m.to_dict().items() if k != "raw_metadata"}, True)
+            return 0
+        print(m.question, f"\n  status: {m.status}   type: {m.deployment}   pool: ${m.pool_usd:.2f}   fee: {m.trading_fee:.1%}")
+        for o, pr in zip(m.outcomes, m.probabilities):
+            print(f"  {o:<20} {pr:6.1%}")
+        print(f"  trading closes: {m.trading_closes_at}   settle by: {m.settlement_deadline}")
+        if m.rules:
+            print(f"\nRules the judge applies:\n  {m.rules}")
+        if m.sources:
+            print("Sources:\n  " + "\n  ".join(m.sources))
+        print(f"\nRules file matches on-chain hash: {m.metadata_verified}   judge: {m.judge_model}")
+        print(m.url)
+        return 0
+    if a.cmd == "quote":
+        q = d.quote_sell(a.address, a.outcome, a.sell) if a.sell is not None else d.quote_buy(a.address, a.outcome, usd=a.usd, shares=a.shares)
+        if a.json:
+            _out(q.to_dict(), True)
+        else:
+            after = f" → {q.probability_after:.1%}" if q.probability_after is not None else ""
+            verb = "costs" if q.side == "buy" else "returns"
+            print(f"{q.side} {q.shares:.4f} {q.outcome_label} shares {verb} ${q.usd:.4f} "
+                  f"(avg {q.average_price:.4f}); probability {q.probability_before:.1%}{after}")
+        return 0
+    if a.cmd == "buy":
+        q = d.quote_buy(a.address, a.outcome, usd=a.usd)
+        if not _confirm(f"Buy {q.shares:.4f} {q.outcome_label} for ${q.usd:.2f} (max +{a.max_slippage:.0%})?", a.yes):
+            return 1
+        t = d.buy(a.address, a.outcome, usd=a.usd, max_slippage=a.max_slippage)
+        _out(t.to_dict(), a.json) if a.json else print(f"bought {t.shares:.4f} {t.outcome_label} for ${t.usd:.4f}\n{t.explorer_url}")
+        return 0
+    if a.cmd == "sell":
+        if not _confirm(f"Sell {'all' if a.shares is None else a.shares} {a.outcome} shares?", a.yes):
+            return 1
+        t = d.sell(a.address, a.outcome, a.shares, max_slippage=a.max_slippage)
+        _out(t.to_dict(), a.json) if a.json else print(f"sold {t.shares:.4f} {t.outcome_label} for ${t.usd:.4f}\n{t.explorer_url}")
+        return 0
+    if a.cmd == "positions":
+        ps = d.positions(a.wallet)
+        if a.json:
+            _out([x.to_dict() for x in ps], True)
+        else:
+            for x in ps:
+                v = f"${x.value_usd:.2f}" if x.value_usd is not None else "–"
+                act = f"  → {x.action}" if x.action else ""
+                print(f"{x.shares:10.4f} {x.outcome_label or x.outcome!s:<12} {v:>9}  {x.status:<19}{act}\n    {x.question}  {x.market}")
+            print(f"\n{len(ps)} position(s)")
+        return 0
+    if a.cmd == "collect":
+        m = d.market(a.address, with_rules=False)
+        r = d.redeem(a.address) if m.status == "settled" else d.liquidate(a.address) if m.status in ("expired", "failed") else None
+        if r is None:
+            raise DelphiError(f"market is {m.status}; nothing to collect yet")
+        _out(r, True) if a.json else print(f"collected ${r['usd']:.4f}\n{r['explorer_url']}")
+        return 0
+    if a.cmd == "balance":
+        b = d.balance()
+        _out(b, True) if a.json else print(f"{b['wallet']}: ${b['usd']:.2f} USDC, {b['eth']:.6f} ETH for gas")
+        return 0
+    if a.cmd == "watch":
+        from .watch import WatchConfig, Watcher, print_sink, telegram_sink, webhook_sink
+        cfg = WatchConfig(move=a.move, closing_hours=a.closing_hours, query=a.query,
+                          markets=frozenset(x.lower() for x in a.market), wallet=a.wallet,
+                          kinds=frozenset(k.strip() for k in a.only.split(",") if k.strip()))
+        sinks = [print_sink(a.json)]
+        if a.webhook:
+            sinks.append(webhook_sink(a.webhook))
+        if a.telegram:
+            sinks.append(telegram_sink())
+        w = Watcher(d, cfg)
+        if not w.state:
+            print("first run: recording a baseline; alerts start from the next check", file=sys.stderr)
+        w.run(a.every, sinks, once=a.once)
+        return 0
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

delphi_kit/client.py

@@ -0,0 +1,483 @@
+"""The Delphi client: read every market straight from the chain, quote, trade, and track positions.
+
+No API key is needed. Every number comes from the Gensyn chain through a public RPC, and each market's rules
+file is checked against the hash stored on chain.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import os
+import time
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import Iterable, Optional
+
+import httpx
+from eth_account import Account
+from web3 import Web3
+
+from .chain import ERC20_ABI, Call, Reader, abi, checksum, connect
+from .models import STATUSES, Market, Position, Quote, Trade, ts
+from .networks import Deployment, Network, get_network
+
+SHARE = 10**18
+MAX_UINT = 2**256 - 1
+
+
+class DelphiError(Exception):
+    pass
+
+
+class InsufficientFunds(DelphiError):
+    pass
+
+
+def _cache_dir() -> Path:
+    base = os.environ.get("DELPHI_KIT_CACHE") or os.path.join(os.path.expanduser("~"), ".cache", "delphi-kit")
+    p = Path(base)
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+class Delphi:
+    """Read and trade Delphi prediction markets.
+
+    >>> d = Delphi()                                   # mainnet, read-only
+    >>> for m in d.markets(status="open")[:5]: print(m.summary())
+    >>> d.quote_buy(m.address, "Yes", usd=5)
+
+    Pass ``private_key`` (or set ``DELPHI_PRIVATE_KEY``) to trade.
+    """
+
+    def __init__(self, network: str | Network = "mainnet", *, private_key: str | None = None,
+                 rpc_url: str | None = None, cache: bool = True):
+        self.network = network if isinstance(network, Network) else get_network(network)
+        self.w3 = connect(self.network, rpc_url or os.environ.get("DELPHI_RPC_URL"))
+        self.reader = Reader(self.w3, self.network)
+        key = private_key or os.environ.get("DELPHI_PRIVATE_KEY")
+        self.account = Account.from_key(key) if key else None
+        self.cache = cache
+        self.token = self.w3.eth.contract(address=checksum(self.network.token), abi=ERC20_ABI)
+        self._dep = {d.name: d for d in self.network.deployments}
+        self._gw = {d.name: self.w3.eth.contract(address=checksum(d.gateway), abi=abi(d.kind)) for d in self.network.deployments}
+        self._fac = {d.name: self.w3.eth.contract(address=checksum(d.factory), abi=abi("factory")) for d in self.network.deployments}
+        self._where: dict[str, str] = {}            # market (lowercase) -> deployment name
+        self._addresses: dict[str, list[str]] = {}  # deployment name -> market addresses, oldest first
+        self._meta: dict[str, tuple[Optional[dict], Optional[bool]]] = {}
+        self._http = httpx.Client(timeout=20, follow_redirects=True, headers={"User-Agent": "delphi-kit"})
+
+    # ------------------------------------------------------------------ wallet
+
+    @property
+    def address(self) -> Optional[str]:
+        return self.account.address if self.account else None
+
+    def balance(self, wallet: str | None = None) -> dict:
+        """USDC and gas (ETH) held by a wallet."""
+        w = checksum(wallet or self._need_account().address)
+        return {
+            "wallet": w,
+            "usd": self.token.functions.balanceOf(w).call() / 10**self.network.token_decimals,
+            "eth": self.w3.eth.get_balance(w) / 1e18,
+        }
+
+    # ---------------------------------------------------------------- routing
+
+    def _deployment(self, market: str) -> Deployment:
+        key = market.lower()
+        if key not in self._where:
+            calls = [Call(self._fac[n], "marketProxyExists", [checksum(market)]) for n in self._dep]
+            for name, found in zip(self._dep, self.reader.run(calls)):
+                if found is True:
+                    self._where[key] = name
+                    break
+            else:
+                raise DelphiError(f"{market} is not a Delphi market on {self.network.name}")
+        return self._dep[self._where[key]]
+
+    def gateway_for(self, market: str) -> str:
+        """The gateway contract every call about this market must go through."""
+        return self._deployment(market).gateway
+
+    # ---------------------------------------------------------------- reading
+
+    def market_addresses(self, deployment: str | None = None) -> list[str]:
+        """Every market ever created, newest first, straight from the factories."""
+        names = [deployment] if deployment else list(self._dep)
+        totals = self.reader.run([Call(self._fac[n], "getTotalMarketProxiesCount") for n in names])
+        out: list[str] = []
+        for name, total in zip(names, totals):
+            if isinstance(total, Exception):
+                continue
+            have = self._addresses.setdefault(name, [])
+            if len(have) < total:
+                calls = [Call(self._fac[name], "getMarketProxies", [i, min(i + 499, total - 1)])
+                         for i in range(len(have), total, 500)]
+                for chunk in self.reader.run(calls):
+                    if not isinstance(chunk, Exception):
+                        have.extend(checksum(a) for a in chunk)
+            for a in have:
+                self._where[a.lower()] = name
+            out.extend(have)
+        return list(reversed(out))
+
+    def markets(self, status: str | Iterable[str] | None = "open", *, deployment: str | None = None,
+                limit: int | None = None, with_rules: bool = True) -> list[Market]:
+        """Markets with live odds. ``status`` is one of open, awaiting_settlement, settled, expired, failed,
+        a list of them, or None for all. Open markets are sorted by closing time, soonest first."""
+        wanted = {status} if isinstance(status, str) else (set(status) if status else None)
+        if wanted and not wanted <= set(STATUSES):
+            raise ValueError(f"status must be among {STATUSES}")
+        addrs = self.market_addresses(deployment)
+        status_calls = [Call(self._gw[self._where[a.lower()]], "marketStatus", [a]) for a in addrs]
+        statuses = self.reader.run(status_calls)
+        chosen = [a for a, s in zip(addrs, statuses)
+                  if not isinstance(s, Exception) and (wanted is None or STATUSES[s] in wanted)]
+        if limit and not (wanted == {"open"}):
+            chosen = chosen[:limit]
+        found = self._load(chosen, with_rules=with_rules)
+        if wanted == {"open"}:
+            found.sort(key=lambda m: m.trading_closes_at.timestamp() if m.trading_closes_at else math.inf)
+        return found[:limit] if limit else found
+
+    def market(self, address: str, *, with_rules: bool = True) -> Market:
+        self._deployment(address)
+        return self._load([checksum(address)], with_rules=with_rules)[0]
+
+    def _load(self, addrs: list[str], with_rules: bool) -> list[Market]:
+        if not addrs:
+            return []
+        calls: list[Call] = []
+        for a in addrs:
+            g = self._gw[self._deployment(a).name]
+            calls += [Call(g, "getMarket", [a]), Call(g, "marketStatus", [a]), Call(g, "marketMetadata", [a])]
+        base = self.reader.run(calls)
+        rows = [base[i:i + 3] for i in range(0, len(base), 3)]
+        for r in rows:  # marketMetadata decodes to {"uri", "uriContentHash"}; keep it as a pair
+            if isinstance(r[2], dict):
+                r[2] = (r[2]["uri"], r[2]["uriContentHash"])
+        n_out = [int(r[0]["config"]["outcomeCount"]) if isinstance(r[0], dict) else 0 for r in rows]
+        price_calls: list[Call] = []
+        for a, n in zip(addrs, n_out):
+            g = self._gw[self._deployment(a).name]
+            price_calls += [Call(g, "spotImpliedProbabilities", [a, list(range(n))]), Call(g, "spotPrices", [a, list(range(n))])]
+        prices = self.reader.run(price_calls)
+        metas = self._metadata([r[2] if not isinstance(r[2], Exception) else None for r in rows]) if with_rules else [(None, None)] * len(rows)
+        out: list[Market] = []
+        for i, (a, r) in enumerate(zip(addrs, rows)):
+            dep = self._deployment(a)
+            info, st, md = r
+            if isinstance(info, Exception):
+                continue
+            cfg = info["config"]
+            probs = prices[2 * i]
+            spot = prices[2 * i + 1]
+            meta, verified = metas[i]
+            win = info.get("winningOutcomeIdx")
+            n = int(cfg["outcomeCount"])
+            outcomes = list(meta.get("outcomes") or []) if meta else []
+            model = (meta or {}).get("model") or {}
+            out.append(Market(
+                address=checksum(a),
+                deployment=dep.name,
+                mechanism="lmsr" if dep.kind == "lmsr" else "dpm",
+                status=STATUSES[st] if isinstance(st, int) else "unknown",
+                question=(meta or {}).get("question"),
+                outcomes=outcomes if len(outcomes) == n else (outcomes or [f"Outcome {j}" for j in range(n)]),
+                probabilities=[p / 1e18 for p in probs] if not isinstance(probs, Exception) else [],
+                prices=[p / 10**self.network.token_decimals for p in spot] if not isinstance(spot, Exception) else [],
+                trading_closes_at=ts(cfg.get("tradingDeadline")),
+                settlement_deadline=ts(cfg.get("settlementDeadline")),
+                earliest_resolve_at=ts(cfg.get("earliestResolveTime")),
+                winning_outcome=None if win is None or win >= n else int(win),
+                pool_usd=info["pool"] / 10**self.network.token_decimals,
+                trading_fee=cfg["tradingFee"] / 1e18,
+                rules=model.get("prompt_context") or (meta or {}).get("resolutionPrompt"),
+                sources=list((meta or {}).get("data_sources") or (meta or {}).get("dataSources") or []),
+                judge_model=model.get("model_identifier"),
+                metadata_uri=md[0] if isinstance(md, tuple) else None,
+                metadata_verified=verified,
+                url=f"{self.network.explorer_url}/address/{checksum(a)}",
+                gateway=dep.gateway,
+                raw_metadata=meta,
+            ))
+        return out
+
+    def _metadata(self, entries: list[Optional[tuple]]) -> list[tuple[Optional[dict], Optional[bool]]]:
+        """Fetch each market's rules file, check it against the on-chain hash, cache it on disk."""
+        cache = _cache_dir() / "metadata" if self.cache else None
+        if cache:
+            cache.mkdir(exist_ok=True)
+
+        def get(entry: Optional[tuple]) -> tuple[Optional[dict], Optional[bool]]:
+            if not entry or not entry[0]:
+                return None, None
+            uri, h = entry[0], bytes(entry[1]).hex()
+            if uri in self._meta:
+                return self._meta[uri]
+            f = cache / f"{h}.json" if cache else None
+            body: Optional[bytes] = f.read_bytes() if f and f.exists() else None
+            if body is None and uri.startswith("http"):
+                for attempt in range(3):
+                    try:
+                        r = self._http.get(uri)
+                        if r.status_code == 200:
+                            body = r.content
+                        break
+                    except httpx.HTTPError:
+                        time.sleep(0.5 * (attempt + 1))
+            if body is None:
+                return None, None
+            verified = hashlib.sha256(body).hexdigest() == h or Web3.keccak(body).hex().removeprefix("0x") == h
+            try:
+                data = json.loads(body)
+            except ValueError:
+                return None, False
+            if f and verified and not f.exists():
+                f.write_bytes(body)
+            self._meta[uri] = (data, verified)
+            return data, verified
+
+        with ThreadPoolExecutor(max_workers=16) as pool:
+            return list(pool.map(get, entries))
+
+    def search(self, query: str, *, status: str | None = "open", limit: int = 10) -> list[Market]:
+        """Find markets by words in the question, outcomes or rules. Delphi's own app has no search."""
+        from .search import rank
+        return rank(self.markets(status=status), query)[:limit]
+
+    # ---------------------------------------------------------------- quotes
+
+    def _resolve(self, market: str | Market, outcome: int | str) -> tuple[Market, int]:
+        m = market if isinstance(market, Market) else self.market(market)
+        return m, m.outcome_index(outcome)
+
+    def _quote_raw(self, m: Market, idx: int, shares_raw: int, side: str) -> int:
+        g = self._gw[m.deployment]
+        fn = "quoteBuyExactOut" if side == "buy" else "quoteSellExactIn"
+        r = getattr(g.functions, fn)(checksum(m.address), idx, shares_raw).call()
+        return int(r[0] if isinstance(r, (list, tuple)) else r)
+
+    def quote_buy(self, market: str | Market, outcome: int | str, *, shares: float | None = None,
+                  usd: float | None = None) -> Quote:
+        """What a buy costs. Give ``shares`` for an exact share count, or ``usd`` for the most shares a budget
+        buys (fees included, never over budget)."""
+        if (shares is None) == (usd is None):
+            raise ValueError("give exactly one of shares= or usd=")
+        m, idx = self._resolve(market, outcome)
+        if m.status != "open":
+            raise DelphiError(f"market is {m.status}, not open for trading")
+        unit = 10**self.network.token_decimals
+        if shares is not None:
+            raw = int(round(shares * SHARE))
+            cost = self._quote_raw(m, idx, raw, "buy")
+        else:
+            raw, cost = self._fit_budget(m, idx, int(usd * unit))
+        return self._quote(m, idx, "buy", raw, cost)
+
+    def _fit_budget(self, m: Market, idx: int, budget: int) -> tuple[int, int]:
+        """Largest share count whose cost is within budget. Cost is convex in shares, so walk in from both sides."""
+        p = m.prices[idx] if m.prices and m.prices[idx] > 0 else 0.5
+        guess = budget / (10**self.network.token_decimals) / p
+        lo: tuple[float, int] | None = None
+        hi: tuple[float, int] | None = None
+        for _ in range(10):
+            raw = int(guess * SHARE)
+            try:
+                cost = self._quote_raw(m, idx, raw, "buy")
+            except Exception:  # noqa: BLE001  (too many shares for the pool)
+                cost = None
+            if cost is not None and cost <= budget:
+                if not lo or guess > lo[0]:
+                    lo = (guess, cost)
+            elif not hi or guess < hi[0]:
+                hi = (guess, cost if cost is not None else budget * 4)
+            if cost and abs(cost - budget) / budget < 0.002 and cost <= budget:
+                break
+            if lo and hi:
+                if (hi[0] - lo[0]) / hi[0] < 0.001:
+                    break
+                guess = lo[0] + (hi[0] - lo[0]) * (budget - lo[1]) / max(1, hi[1] - lo[1])
+                guess = min(max(guess, lo[0] * 1.0001), hi[0] * 0.9999)
+            else:
+                guess *= max(0.25, min(4, budget / cost)) if cost else 0.5
+        if not lo:
+            raise DelphiError("the budget is too small to buy any shares")
+        return int(lo[0] * SHARE), lo[1]
+
+    def quote_sell(self, market: str | Market, outcome: int | str, shares: float) -> Quote:
+        m, idx = self._resolve(market, outcome)
+        if m.status != "open":
+            raise DelphiError(f"market is {m.status}, not open for trading")
+        raw = int(round(shares * SHARE))
+        return self._quote(m, idx, "sell", raw, self._quote_raw(m, idx, raw, "sell"))
+
+    def _quote(self, m: Market, idx: int, side: str, shares_raw: int, usd_raw: int) -> Quote:
+        unit = 10**self.network.token_decimals
+        after = None
+        if m.mechanism == "lmsr":
+            fn = "quoteBuyExactOut" if side == "buy" else "quoteSellExactIn"
+            try:
+                _, new_exp, new_sum = getattr(self._gw[m.deployment].functions, fn)(checksum(m.address), idx, shares_raw).call()
+                after = new_exp / new_sum if new_sum else None
+            except Exception:  # noqa: BLE001
+                after = None
+        shares = shares_raw / SHARE
+        return Quote(market=m.address, outcome=idx, outcome_label=m.outcomes[idx] if idx < len(m.outcomes) else None,
+                     side=side, shares=shares, usd=usd_raw / unit,
+                     average_price=(usd_raw / unit / shares) if shares else None,
+                     probability_before=m.probabilities[idx] if m.probabilities else None,
+                     probability_after=after, shares_raw=shares_raw, usd_raw=usd_raw)
+
+    # ---------------------------------------------------------------- trading
+
+    def _need_account(self):
+        if not self.account:
+            raise DelphiError("no wallet: pass private_key= or set DELPHI_PRIVATE_KEY")
+        return self.account
+
+    def _send(self, fn) -> dict:
+        acct = self._need_account()
+        tx = fn.build_transaction({
+            "from": acct.address,
+            "nonce": self.w3.eth.get_transaction_count(acct.address, "pending"),
+            "chainId": self.network.chain_id,
+        })
+        signed = acct.sign_transaction(tx)
+        h = self.w3.eth.send_raw_transaction(signed.raw_transaction)
+        receipt = self.w3.eth.wait_for_transaction_receipt(h, timeout=180)
+        if receipt["status"] != 1:
+            raise DelphiError(f"transaction reverted: {self.tx_url(h.hex())}")
+        return receipt
+
+    def tx_url(self, tx_hash: str) -> str:
+        h = tx_hash if tx_hash.startswith("0x") else "0x" + tx_hash
+        return f"{self.network.explorer_url}/tx/{h}"
+
+    def _ensure_allowance(self, spender: str, amount: int, unlimited: bool) -> Optional[str]:
+        acct = self._need_account()
+        have = self.token.functions.allowance(acct.address, checksum(spender)).call()
+        if have >= amount:
+            return None
+        r = self._send(self.token.functions.approve(checksum(spender), MAX_UINT if unlimited else amount))
+        return "0x" + r["transactionHash"].hex().removeprefix("0x")
+
+    def buy(self, market: str | Market, outcome: int | str, *, usd: float | None = None, shares: float | None = None,
+            max_slippage: float = 0.02, approve_unlimited: bool = False) -> Trade:
+        """Buy shares of one outcome. ``usd`` spends up to that budget; ``shares`` buys an exact count.
+        Approves only the amount needed unless ``approve_unlimited``."""
+        acct = self._need_account()
+        m, idx = self._resolve(market, outcome)
+        q = self.quote_buy(m, idx, usd=usd, shares=shares)
+        max_in = math.ceil(q.usd_raw * (1 + max_slippage))
+        have = self.token.functions.balanceOf(acct.address).call()
+        if have < max_in:
+            raise InsufficientFunds(f"need up to ${max_in / 10**self.network.token_decimals:.2f}, wallet has ${have / 10**self.network.token_decimals:.2f}")
+        # trades go through the gateway, but the market contract itself pulls the USDC, so it is the spender
+        approval = self._ensure_allowance(m.address, max_in, approve_unlimited)
+        fn = self._gw[m.deployment].functions.buyExactOut(checksum(m.address), idx, q.shares_raw, max_in)
+        sim = fn.call({"from": acct.address})
+        r = self._send(fn)
+        paid = int(sim[0] if isinstance(sim, (list, tuple)) else sim)
+        h = "0x" + r["transactionHash"].hex().removeprefix("0x")
+        return Trade(market=m.address, outcome=idx, outcome_label=q.outcome_label, side="buy", shares=q.shares,
+                     usd=paid / 10**self.network.token_decimals, tx_hash=h, explorer_url=self.tx_url(h), approval_tx=approval)
+
+    def sell(self, market: str | Market, outcome: int | str, shares: float | None = None, *,
+             max_slippage: float = 0.02) -> Trade:
+        """Sell shares back to the market. ``shares=None`` sells everything held in that outcome."""
+        acct = self._need_account()
+        m, idx = self._resolve(market, outcome)
+        g = self._gw[m.deployment]
+        raw = int(round(shares * SHARE)) if shares is not None else g.functions.balanceOf(checksum(m.address), acct.address, idx).call()
+        if raw <= 0:
+            raise DelphiError("no shares to sell")
+        out = self._quote_raw(m, idx, raw, "sell")
+        min_out = math.floor(out * (1 - max_slippage))
+        fn = g.functions.sellExactIn(checksum(m.address), idx, raw, min_out)
+        sim = fn.call({"from": acct.address})
+        r = self._send(fn)
+        got = int(sim[0] if isinstance(sim, (list, tuple)) else sim)
+        h = "0x" + r["transactionHash"].hex().removeprefix("0x")
+        return Trade(market=m.address, outcome=idx, outcome_label=m.outcomes[idx] if idx < len(m.outcomes) else None,
+                     side="sell", shares=raw / SHARE, usd=got / 10**self.network.token_decimals, tx_hash=h, explorer_url=self.tx_url(h))
+
+    def redeem(self, market: str) -> dict:
+        """Collect winnings from a settled market."""
+        acct = self._need_account()
+        g = self._gw[self._deployment(market).name]
+        fn = g.functions.redeem(checksum(market))
+        shares_in, tokens_out = fn.call({"from": acct.address})
+        r = self._send(fn)
+        h = "0x" + r["transactionHash"].hex().removeprefix("0x")
+        return {"market": checksum(market), "shares": shares_in / SHARE, "usd": tokens_out / 10**self.network.token_decimals,
+                "tx_hash": h, "explorer_url": self.tx_url(h)}
+
+    def liquidate(self, market: str, outcomes: list[int] | None = None) -> dict:
+        """Recover funds from an expired or failed market (paid at final prices, not refunded at cost)."""
+        acct = self._need_account()
+        m = self.market(market, with_rules=False)
+        g = self._gw[m.deployment]
+        idxs = outcomes if outcomes is not None else [
+            i for i in range(len(m.probabilities)) if g.functions.balanceOf(checksum(market), acct.address, i).call() > 0]
+        fn = g.functions.liquidate(checksum(market), idxs)
+        shares_in, tokens_out = fn.call({"from": acct.address})
+        r = self._send(fn)
+        h = "0x" + r["transactionHash"].hex().removeprefix("0x")
+        return {"market": checksum(market), "shares": [s / SHARE for s in shares_in],
+                "usd": tokens_out / 10**self.network.token_decimals, "tx_hash": h, "explorer_url": self.tx_url(h)}
+
+    # ---------------------------------------------------------------- positions
+
+    def positions(self, wallet: str | None = None, *, markets: list[str | Market] | None = None,
+                  include_empty_closed: bool = False) -> list[Position]:
+        """Every share a wallet holds, in every market of every deployment (or just ``markets``), with what to
+        do next. No API key: balances are read from the chain in a few batched calls."""
+        w = checksum(wallet or self._need_account().address)
+        if markets is not None:
+            addrs = [checksum(m.address if isinstance(m, Market) else m) for m in markets]
+            for a in addrs:
+                self._deployment(a)
+        else:
+            addrs = self.market_addresses()
+        info = self.reader.run([Call(self._gw[self._where[a.lower()]], "getMarket", [a]) for a in addrs])
+        counts = [int(i["config"]["outcomeCount"]) if isinstance(i, dict) else 0 for i in info]
+        bal = self.reader.run([Call(self._gw[self._where[a.lower()]], "batchBalanceOf", [a, [w] * n, list(range(n))])
+                               for a, n in zip(addrs, counts)])
+        held = [(a, b) for a, b in zip(addrs, bal) if not isinstance(b, Exception) and any(b)]
+        if not held:
+            return []
+        markets = {m.address.lower(): m for m in self._load([a for a, _ in held], with_rules=True)}
+        out: list[Position] = []
+        for a, b in held:
+            m = markets.get(a.lower())
+            if not m:
+                continue
+            for idx, raw in enumerate(b):
+                if raw <= 0:
+                    continue
+                sh = raw / SHARE
+                p = m.probabilities[idx] if idx < len(m.probabilities) else None
+                action, claim, value = None, None, (sh * p if p is not None else None)
+                if m.status == "settled":
+                    won = m.winning_outcome == idx
+                    value = None
+                    if won:
+                        action = "redeem"
+                        try:
+                            claim = self._gw[m.deployment].functions.redeem(checksum(a)).call({"from": w})[1] / 10**self.network.token_decimals
+                        except Exception:  # noqa: BLE001  (already redeemed, or nothing to claim)
+                            claim = None
+                        value = claim
+                    elif not include_empty_closed:
+                        continue
+                elif m.status in ("expired", "failed"):
+                    action = "liquidate"
+                out.append(Position(market=m.address, question=m.question, outcome=idx,
+                                    outcome_label=m.outcomes[idx] if idx < len(m.outcomes) else None,
+                                    shares=sh, probability=p, value_usd=value, status=m.status,
+                                    action=action, claimable_usd=claim))
+        return out