oddsrail 0.3.0__py3-none-any.whl

oddsrail/kalshi.py

@@ -0,0 +1,299 @@
+"""Kalshi venue: signed REST access for trading agents.
+
+Auth is RSA-PSS(SHA256, MGF1-SHA256, salt=digest length) over the exact string
+    str(unix_ms) + METHOD_UPPER + path
+where `path` INCLUDES the /trade-api/v2 prefix and EXCLUDES the query string,
+sent as KALSHI-ACCESS-KEY / -SIGNATURE / -TIMESTAMP headers.
+
+Deliberately built on httpx rather than the official SDK: kalshi-python-sync
+requires Python >=3.13 (this runs on 3.12), it re-releases weekly in lockstep
+with the spec version, and the surface used here is small enough that a
+pinned dependency costs more than it saves. Read endpoints need no key at all.
+
+Two shapes on this API bite hard, so both are normalised here:
+
+1. PRICES ARE DOLLAR STRINGS, NOT CENTS. Fields carry a `_dollars` suffix
+   ("0.5600") and sizes an `_fp` suffix ("10.00"); the legacy integer-cent
+   fields were removed in 2026-03. All arithmetic uses Decimal — float
+   rounding on a 1-tick market is a real money bug.
+
+2. THE ORDERBOOK IS BIDS-ONLY ON BOTH SIDES. `orderbook_fp.yes_dollars` and
+   `.no_dollars` are both BID ladders, ascending, so the best bid is the LAST
+   element. A NO bid at $0.99 IS a YES ask at $0.01. get_orderbook() converts
+   this into a conventional best-first bid/ask view of the YES book; the raw
+   ladders are returned alongside so nothing is hidden.
+
+Compliance note: Kalshi's Developer Agreement limits API use to a member's
+own trading and restricts storing/sharing API data. oddsrail is self-hosted
+and single-tenant — the operator supplies their own key and trades their own
+account — and this module caches nothing.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+import time
+from decimal import Decimal
+
+import httpx
+
+PROD = "https://external-api.kalshi.com"
+DEMO = "https://external-api.demo.kalshi.co"
+PREFIX = "/trade-api/v2"
+
+
+def base_url() -> str:
+    return DEMO if os.environ.get("KALSHI_DEMO", "").lower() in ("1", "true", "yes") else PROD
+
+
+def dry_run() -> bool:
+    return os.environ.get("ODDSRAIL_DRY_RUN", "1") not in ("0", "false", "no")
+
+
+def has_credentials() -> bool:
+    return bool(os.environ.get("KALSHI_KEY_ID")) and bool(
+        os.environ.get("KALSHI_PRIVATE_KEY_PATH") or os.environ.get("KALSHI_PRIVATE_KEY"))
+
+
+def _private_key():
+    from cryptography.hazmat.primitives import serialization
+    pem = os.environ.get("KALSHI_PRIVATE_KEY")
+    if not pem:
+        path = os.environ.get("KALSHI_PRIVATE_KEY_PATH")
+        if not path:
+            raise RuntimeError(
+                "no Kalshi key: set KALSHI_PRIVATE_KEY_PATH (PKCS#8 PEM) or "
+                "KALSHI_PRIVATE_KEY. Read tools work without one.")
+        with open(path, "rb") as fh:
+            pem_bytes = fh.read()
+    else:
+        pem_bytes = pem.encode()
+    return serialization.load_pem_private_key(pem_bytes, password=None)
+
+
+def _signed_headers(method: str, path: str) -> dict:
+    """path must start with /trade-api/v2 and carry no query string."""
+    from cryptography.hazmat.primitives import hashes
+    from cryptography.hazmat.primitives.asymmetric import padding
+
+    key_id = os.environ.get("KALSHI_KEY_ID")
+    if not key_id:
+        raise RuntimeError("KALSHI_KEY_ID not set")
+    ts = str(int(time.time() * 1000))
+    msg = (ts + method.upper() + path.split("?")[0].split("#")[0]).encode()
+    sig = _private_key().sign(
+        msg,
+        padding.PSS(mgf=padding.MGF1(hashes.SHA256()),
+                    salt_length=padding.PSS.DIGEST_LENGTH),
+        hashes.SHA256(),
+    )
+    return {
+        "KALSHI-ACCESS-KEY": key_id,
+        "KALSHI-ACCESS-SIGNATURE": base64.b64encode(sig).decode("ascii"),
+        "KALSHI-ACCESS-TIMESTAMP": ts,
+        "Content-Type": "application/json",
+    }
+
+
+async def _get(path: str, params: dict | None = None, signed: bool = False):
+    url = base_url() + PREFIX + path
+    headers = _signed_headers("GET", PREFIX + path) if signed else {}
+    async with httpx.AsyncClient(timeout=20.0) as c:
+        r = await c.get(url, params=params or {}, headers=headers)
+        r.raise_for_status()
+        return r.json()
+
+
+async def _post(path: str, body: dict):
+    url = base_url() + PREFIX + path
+    headers = _signed_headers("POST", PREFIX + path)
+    async with httpx.AsyncClient(timeout=20.0) as c:
+        r = await c.post(url, json=body, headers=headers)
+        r.raise_for_status()
+        return r.json()
+
+
+def _d(v) -> Decimal | None:
+    try:
+        return Decimal(str(v))
+    except Exception:
+        return None
+
+
+def slim_market(m: dict) -> dict:
+    """Kalshi market -> the same vocabulary oddsrail uses for Polymarket."""
+    return {
+        "venue": "kalshi",
+        "ticker": m.get("ticker"),
+        "event_ticker": m.get("event_ticker"),
+        "title": m.get("title"),
+        "yes_sub_title": m.get("yes_sub_title"),
+        "status": m.get("status"),
+        "yes_bid": m.get("yes_bid_dollars"),
+        "yes_ask": m.get("yes_ask_dollars"),
+        "no_bid": m.get("no_bid_dollars"),
+        "no_ask": m.get("no_ask_dollars"),
+        "last_price": m.get("last_price_dollars"),
+        "volume": m.get("volume_fp"),
+        "volume_24h": m.get("volume_24h_fp"),
+        "open_interest": m.get("open_interest_fp"),
+        "close_time": m.get("close_time"),
+        "rules_primary": (m.get("rules_primary") or "")[:400],
+        "market_type": m.get("market_type"),
+    }
+
+
+async def search_markets(query: str = "", limit: int = 10,
+                         status: str = "open", min_volume: float = 0.0):
+    """Kalshi has no text-search endpoint, so this pages recent open markets
+    and filters client-side on title/ticker. MVE combo shards are excluded —
+    they are auto-generated, illiquid, and drown real markets otherwise."""
+    out, cursor, pages = [], None, 0
+    q = (query or "").lower()
+    while len(out) < limit and pages < 5:
+        params = {"limit": 200, "status": status, "mve_filter": "exclude"}
+        if cursor:
+            params["cursor"] = cursor
+        data = await _get("/markets", params)
+        batch = data.get("markets") or []
+        for m in batch:
+            if float(_d(m.get("volume_fp")) or 0) < min_volume:
+                continue
+            hay = f"{m.get('title','')} {m.get('ticker','')} {m.get('yes_sub_title','')}".lower()
+            if q and q not in hay:
+                continue
+            out.append(m)
+        cursor = data.get("cursor")
+        pages += 1
+        if not cursor or not batch:
+            break
+    out.sort(key=lambda m: -float(_d(m.get("volume_fp")) or 0))
+    return [slim_market(m) for m in out[:limit]]
+
+
+async def get_market(ticker: str):
+    d = await _get(f"/markets/{ticker}")
+    return slim_market(d.get("market") or {})
+
+
+async def get_orderbook(ticker: str, depth: int = 10):
+    """Normalise Kalshi's bids-only ladders into a YES-book bid/ask view.
+
+    yes_dollars is the YES bid ladder; no_dollars is the NO bid ladder, and a
+    NO bid at q is a YES ask at (1 - q). Both arrive ascending, so the best
+    levels are at the END — everything below is returned best-first.
+    """
+    d = await _get(f"/markets/{ticker}/orderbook", {"depth": depth})
+    ob = d.get("orderbook_fp") or {}
+    yes_raw = ob.get("yes_dollars") or []
+    no_raw = ob.get("no_dollars") or []
+
+    yes_bids = [{"price": str(p), "size": str(s)} for p, s in reversed(yes_raw)]
+    yes_asks = [{"price": str(Decimal("1") - Decimal(p)), "size": str(s)}
+                for p, s in reversed(no_raw)]
+    return {
+        "venue": "kalshi",
+        "ticker": ticker,
+        "yes_bids": yes_bids[:depth],
+        "yes_asks": yes_asks[:depth],
+        "best_yes_bid": yes_bids[0]["price"] if yes_bids else None,
+        "best_yes_ask": yes_asks[0]["price"] if yes_asks else None,
+        "note": ("Kalshi publishes bid ladders only; yes_asks are derived as "
+                 "1 - (NO bid). Prices are dollar strings, not cents."),
+        "raw_ladders": {"yes_bids": yes_raw, "no_bids": no_raw},
+    }
+
+
+async def get_trades(ticker: str, limit: int = 50):
+    d = await _get("/markets/trades", {"ticker": ticker, "limit": limit})
+    return d.get("trades") or []
+
+
+async def get_balance():
+    if not has_credentials():
+        return {"note": "no Kalshi credentials configured"}
+    return await _get("/portfolio/balance", signed=True)
+
+
+async def get_positions(limit: int = 50):
+    if not has_credentials():
+        return {"note": "no Kalshi credentials configured"}
+    return await _get("/portfolio/positions", {"limit": limit}, signed=True)
+
+
+async def open_orders(limit: int = 50):
+    if not has_credentials():
+        return {"note": "no Kalshi credentials configured"}
+    return await _get("/portfolio/orders", {"limit": limit, "status": "resting"},
+                      signed=True)
+
+
+def _to_yes_book(outcome: str, action: str, price: Decimal):
+    """Translate (outcome, action, price-of-that-outcome) to the YES book.
+
+    Kalshi V2 quotes everything from the YES leg as bid/ask — there is no
+    yes/no side and no buy/sell action — so this is where an inverted-position
+    bug would live if it were done implicitly at the call site.
+
+        buy  YES @ p -> bid @ p          sell YES @ p -> ask @ p
+        buy  NO  @ q -> ask @ (1 - q)    sell NO  @ q -> bid @ (1 - q)
+    """
+    outcome, action = outcome.lower(), action.lower()
+    if outcome not in ("yes", "no"):
+        raise ValueError("outcome must be 'yes' or 'no'")
+    if action not in ("buy", "sell"):
+        raise ValueError("action must be 'buy' or 'sell'")
+    if outcome == "yes":
+        return ("bid" if action == "buy" else "ask"), price
+    return ("ask" if action == "buy" else "bid"), (Decimal("1") - price)
+
+
+async def place_order(ticker: str, outcome: str, action: str, price: float,
+                      count: float, time_in_force: str = "good_till_cancelled",
+                      client_order_id: str | None = None):
+    """Limit order. `price` is the probability of `outcome`, in (0,1)."""
+    p = Decimal(str(price))
+    if not (Decimal("0") < p < Decimal("1")):
+        raise ValueError("price is a probability in (0, 1)")
+    if count <= 0:
+        raise ValueError("count must be positive")
+
+    side, yes_price = _to_yes_book(outcome, action, p)
+    body = {
+        "ticker": ticker,
+        "side": side,
+        "price": f"{yes_price:.4f}",
+        "count": f"{Decimal(str(count)):.2f}",
+        "time_in_force": time_in_force,
+        "self_trade_prevention_type": "cancel_resting",
+    }
+    if client_order_id:
+        body["client_order_id"] = client_order_id
+
+    intent = {
+        "venue": "kalshi",
+        "requested": {"ticker": ticker, "outcome": outcome, "action": action,
+                      "price": str(p), "count": count},
+        "translated_to_yes_book": body,
+        "attribution": ("none — Kalshi has no builder-code field on REST; "
+                        "its builder program is a Solana/DFlow integration"),
+    }
+    if dry_run():
+        return {"dry_run": True, "would_post": intent,
+                "note": "set ODDSRAIL_DRY_RUN=0 to post real orders"}
+    if not has_credentials():
+        raise RuntimeError("Kalshi credentials required to place real orders")
+    resp = await _post("/portfolio/events/orders", body)
+    return {"dry_run": False, "posted": intent, "response": resp}
+
+
+async def cancel_order(order_id: str):
+    if dry_run():
+        return {"dry_run": True, "would_cancel": order_id}
+    url = base_url() + PREFIX + f"/portfolio/events/orders/{order_id}"
+    headers = _signed_headers("DELETE", PREFIX + f"/portfolio/events/orders/{order_id}")
+    async with httpx.AsyncClient(timeout=20.0) as c:
+        r = await c.delete(url, headers=headers)
+        r.raise_for_status()
+        return r.json()

oddsrail/polymarket.py

@@ -0,0 +1,170 @@
+"""Polymarket data access via the official unified SDK (polymarket-client).
+
+Read paths need no keys (AsyncPublicClient). Trading lives in trading.py.
+
+Field mappings below were verified against the live API (2026-08-23), not
+guessed from docs: `outcomes` is a DICT keyed yes/no (not a list), search
+returns {events, tags, profiles} with markets nested inside each event, and
+book/volume/resolution data live in the prices/metrics/state/resolution
+sub-objects rather than at the top level.
+"""
+
+import httpx
+
+CLOB = "https://clob.polymarket.com"
+
+_public = None
+
+
+async def public():
+    global _public
+    if _public is None:
+        from polymarket import AsyncPublicClient
+        _public = AsyncPublicClient()
+    return _public
+
+
+def dump(obj):
+    """Pydantic model / tuple / list -> plain JSON-able structure."""
+    if hasattr(obj, "model_dump"):
+        return obj.model_dump(mode="json")
+    if isinstance(obj, (list, tuple)):
+        return [dump(x) for x in obj]
+    if isinstance(obj, dict):
+        return {k: dump(v) for k, v in obj.items()}
+    return obj
+
+
+def slim_market(m: dict) -> dict:
+    """Reduce a dumped Market model to what an agent needs to decide."""
+    outs = m.get("outcomes") or {}
+    prices = m.get("prices") or {}
+    metrics = m.get("metrics") or {}
+    state = m.get("state") or {}
+    res = m.get("resolution") or {}
+
+    def leg(key):
+        o = outs.get(key) or {}
+        return {"label": o.get("label"), "token_id": o.get("token_id"),
+                "price": o.get("price")}
+
+    return {
+        "id": m.get("id"),
+        "slug": m.get("slug"),
+        "question": m.get("question"),
+        "condition_id": m.get("condition_id"),
+        "outcomes": {"yes": leg("yes"), "no": leg("no")} if outs else None,
+        "best_bid": prices.get("best_bid"),
+        "best_ask": prices.get("best_ask"),
+        "spread": prices.get("spread"),
+        "last_trade_price": prices.get("last_trade_price"),
+        "volume": metrics.get("volume"),
+        "volume_24hr": metrics.get("volume_24hr"),
+        "liquidity": metrics.get("liquidity"),
+        "active": state.get("active"),
+        "closed": state.get("closed"),
+        "accepting_orders": state.get("accepting_orders"),
+        "neg_risk": state.get("neg_risk"),
+        "end_date": state.get("end_date"),
+        "uma_resolution_status": res.get("uma_resolution_status"),
+        "resolution_source": res.get("source"),
+    }
+
+
+def _markets_from_search(results) -> list:
+    """search() yields {events, tags, profiles}; the markets hang off events."""
+    out = []
+    for r in results:
+        if not isinstance(r, dict):
+            continue
+        for ev in r.get("events") or []:
+            for mk in ev.get("markets") or []:
+                if isinstance(mk, dict):
+                    out.append(mk)
+    return out
+
+
+async def search_markets(query: str = "", limit: int = 10):
+    c = await public()
+    if query:
+        page = await c.search(q=query, sort="volume_24hr",
+                              page_size=max(limit, 5)).first_page()
+        found = _markets_from_search(dump(list(page.items)))
+        # open markets first, then by 24h volume
+        def vol(m):
+            try:
+                return float(((m.get("metrics") or {}).get("volume_24hr")) or 0)
+            except (TypeError, ValueError):
+                return 0.0
+        found.sort(key=lambda m: (bool((m.get("state") or {}).get("closed")), -vol(m)))
+        return [slim_market(m) for m in found[:limit]]
+
+    page = await c.list_markets(closed=False, page_size=limit).first_page()
+    return [slim_market(m) for m in dump(list(page.items))]
+
+
+async def get_market(id_or_slug: str, full: bool = False):
+    c = await public()
+    try:
+        m = await c.get_market(slug=id_or_slug)
+    except Exception:
+        m = await c.get_market(id=id_or_slug)
+    d = dump(m)
+    return d if full else slim_market(d)
+
+
+async def get_orderbook(token_id: str):
+    c = await public()
+    return dump(await c.get_order_book(token_id=token_id))
+
+
+async def price_history(token_id: str, hours: float = 6.0,
+                        fidelity_minutes: int = 1):
+    """Returns (times, prices) oldest->newest."""
+    c = await public()
+    interval = "1h" if hours <= 1 else "6h" if hours <= 6 else \
+               "1d" if hours <= 24 else "1w"
+    pts = dump(await c.get_price_history(token_id=token_id, interval=interval,
+                                         fidelity=fidelity_minutes))
+    times, prices = [], []
+    for p in pts:
+        t = p.get("t", p.get("timestamp"))
+        v = p.get("p", p.get("price"))
+        if t is not None and v is not None:
+            times.append(float(t))
+            prices.append(float(v))
+    return times, prices
+
+
+async def get_positions(address: str, limit: int = 25):
+    c = await public()
+    page = await c.list_positions(user=address, page_size=limit).first_page()
+    return dump(list(page.items))
+
+
+# The SDK accepts only these; agents will say "weekly"/"7d"/"week", so map.
+_PERIODS = {"day": "DAY", "daily": "DAY", "1d": "DAY", "24h": "DAY",
+            "week": "WEEK", "weekly": "WEEK", "7d": "WEEK",
+            "month": "MONTH", "monthly": "MONTH", "30d": "MONTH",
+            "all": "ALL", "alltime": "ALL", "all_time": "ALL"}
+
+
+def normalize_period(p: str) -> str:
+    return _PERIODS.get(str(p or "").strip().lower().replace("-", "_"), "WEEK")
+
+
+async def builder_leaderboard(time_period: str = "WEEK", limit: int = 25):
+    c = await public()
+    period = normalize_period(time_period)
+    page = await c.list_builder_leaderboard(
+        time_period=period, page_size=limit).first_page()
+    return dump(list(page.items))
+
+
+async def builder_trades(builder_code: str):
+    """Public attribution check: matched trades carrying this builder code."""
+    async with httpx.AsyncClient(timeout=15.0) as h:
+        r = await h.get(f"{CLOB}/builder/trades",
+                        params={"builder_code": builder_code})
+        r.raise_for_status()
+        return r.json()

oddsrail/server.py

@@ -0,0 +1,234 @@
+"""oddsrail — the rail AI agents use to trade prediction markets.
+
+MCP server exposing Polymarket market data, order routing with on-chain
+builder-code attribution (CLOB V2), and premium signal tools (overshoot,
+dispute risk). Self-hosted and non-custodial: keys never leave the machine.
+
+Run (stdio, for Claude Code / Desktop / any MCP client):
+    .venv/bin/python -m oddsrail.server
+"""
+
+import json
+import os
+
+from mcp.server.mcpserver import MCPServer
+
+from . import kalshi as kx
+from . import polymarket as pm
+from . import signals
+from . import trading
+
+srv = MCPServer(
+    name="oddsrail",
+    instructions=(
+        "Prediction-market rail for trading agents. Read tools need no keys. "
+        "place_order defaults to dry-run; the operator must set "
+        "ODDSRAIL_DRY_RUN=0 and POLYMARKET_PRIVATE_KEY to trade. Prices are "
+        "implied probabilities in (0,1). Orders carry the operator's builder "
+        "code (ODDSRAIL_BUILDER_CODE) signed into the order for on-chain "
+        "attribution. Kalshi tools are prefixed kalshi_ and need the "
+        "operator's own API key for private endpoints; Kalshi prices are "
+        "probabilities in (0,1) here, translated to its YES-book bid/ask "
+        "internally."
+    ),
+)
+
+
+def _j(x) -> str:
+    return json.dumps(x, default=str)
+
+
+# ------------------------------ market data -------------------------------- #
+
+@srv.tool(description="Search Polymarket markets by text (Gamma public-search "
+                      "under the hood); empty query lists open markets. "
+                      "Returns token ids, prices, metrics, resolution info.")
+async def search_markets(query: str = "", limit: int = 10) -> str:
+    return _j(await pm.search_markets(query=query, limit=limit))
+
+
+@srv.tool(description="Get one market's details by slug (or id).")
+async def get_market(id_or_slug: str) -> str:
+    return _j(await pm.get_market(id_or_slug))
+
+
+@srv.tool(description="Get the live orderbook (bids/asks) for a CLOB token id.")
+async def get_orderbook(token_id: str) -> str:
+    return _j(await pm.get_orderbook(token_id))
+
+
+@srv.tool(description="Recent price history for a CLOB token id: hours back, "
+                      "at fidelity_minutes resolution.")
+async def price_history(token_id: str, hours: float = 6.0,
+                        fidelity_minutes: int = 1) -> str:
+    times, prices = await pm.price_history(token_id, hours, fidelity_minutes)
+    return _j({"points": len(times),
+               "series": [[t, p] for t, p in zip(times, prices)]})
+
+
+@srv.tool(description="Current positions for a wallet address.")
+async def get_positions(address: str, limit: int = 25) -> str:
+    return _j(await pm.get_positions(address, limit))
+
+
+# ------------------------------ signals (premium) --------------------------- #
+
+@srv.tool(description="PREMIUM SIGNAL — overshoot/fade detector. Analyzes a "
+                      "token's recent price series for fresh panic jumps and "
+                      "reports whether a fade setup is active plus this "
+                      "market's historical reversion tendency.")
+async def overshoot_signal(token_id: str, hours: float = 6.0,
+                           threshold: float = 0.05,
+                           lookback_s: float = 60.0) -> str:
+    times, prices = await pm.price_history(token_id, hours, fidelity_minutes=1)
+    return _j(signals.overshoot_report(times, prices,
+                                       lookback=lookback_s,
+                                       threshold=threshold))
+
+
+@srv.tool(description="PREMIUM SIGNAL — dispute-risk triage. Scores 0-100 how "
+                      "likely a market's resolution gets contested (UMA "
+                      "dispute risk) with transparent reasons.")
+async def dispute_risk(id_or_slug: str) -> str:
+    market = await pm.get_market(id_or_slug, full=True)
+    flat = dict(market)
+    # V2 model nests resolution info; surface it for the heuristic
+    res = market.get("resolution") or {}
+    if isinstance(res, dict):
+        flat.setdefault("umaResolutionStatus", res.get("uma_resolution_status")
+                        or res.get("status"))
+    out = signals.dispute_risk(flat)
+    out["market"] = {"question": market.get("question"),
+                     "slug": market.get("slug")}
+    return _j(out)
+
+
+# ------------------------------ trading ------------------------------------ #
+
+@srv.tool(description="Place a limit order. DRY-RUN by default: returns the "
+                      "order it would post. Real trading needs "
+                      "ODDSRAIL_DRY_RUN=0 and POLYMARKET_PRIVATE_KEY. The "
+                      "operator's builder code is signed into the order. "
+                      "Price = implied probability.")
+async def place_order(token_id: str, side: str, price: float, size: float,
+                      order_type: str = "GTC") -> str:
+    return _j(await trading.place_order(token_id, side, price, size, order_type))
+
+
+@srv.tool(description="Cancel an open order by id (respects dry-run).")
+async def cancel_order(order_id: str) -> str:
+    return _j(await trading.cancel_order(order_id))
+
+
+@srv.tool(description="List the operator wallet's open orders.")
+async def open_orders() -> str:
+    return _j(await trading.open_orders())
+
+
+# ------------------------------ builder ------------------------------------ #
+
+@srv.tool(description="Builder attribution stats: the public builder "
+                      "leaderboard, and (if ODDSRAIL_BUILDER_CODE is set) "
+                      "matched trades attributed to this operator's code.")
+async def builder_stats(time_period: str = "WEEK") -> str:
+    out = {"leaderboard": await pm.builder_leaderboard(time_period)}
+    code = trading.builder_code()
+    if code:
+        try:
+            out["my_trades"] = await pm.builder_trades(code)
+        except Exception as e:
+            out["my_trades_error"] = str(e)
+    else:
+        out["note"] = "set ODDSRAIL_BUILDER_CODE to track your attributed flow"
+    return _j(out)
+
+
+# ------------------------------ kalshi (venue #2) --------------------------- #
+
+@srv.tool(description="Search Kalshi markets. Kalshi has no text-search "
+                      "endpoint, so this pages open markets and filters on "
+                      "title/ticker; auto-generated MVE combo shards are "
+                      "excluded. Prices are dollar strings, not cents.")
+async def kalshi_search_markets(query: str = "", limit: int = 10,
+                                min_volume: float = 0.0) -> str:
+    return _j(await kx.search_markets(query=query, limit=limit,
+                                      min_volume=min_volume))
+
+
+@srv.tool(description="Get one Kalshi market by ticker.")
+async def kalshi_get_market(ticker: str) -> str:
+    return _j(await kx.get_market(ticker))
+
+
+@srv.tool(description="Kalshi orderbook for a ticker, normalised to a YES-book "
+                      "bid/ask view (Kalshi publishes bid ladders only; asks "
+                      "are derived as 1 - NO bid). Raw ladders included.")
+async def kalshi_get_orderbook(ticker: str, depth: int = 10) -> str:
+    return _j(await kx.get_orderbook(ticker, depth))
+
+
+@srv.tool(description="Recent public trades for a Kalshi ticker.")
+async def kalshi_get_trades(ticker: str, limit: int = 50) -> str:
+    return _j(await kx.get_trades(ticker, limit))
+
+
+@srv.tool(description="Kalshi account balance (needs the operator's API key).")
+async def kalshi_balance() -> str:
+    return _j(await kx.get_balance())
+
+
+@srv.tool(description="Kalshi positions (needs the operator's API key).")
+async def kalshi_positions(limit: int = 50) -> str:
+    return _j(await kx.get_positions(limit))
+
+
+@srv.tool(description="Kalshi resting orders (needs the operator's API key).")
+async def kalshi_open_orders(limit: int = 50) -> str:
+    return _j(await kx.open_orders(limit))
+
+
+@srv.tool(description="Place a Kalshi limit order. State it naturally: "
+                      "outcome yes|no, action buy|sell, price = probability of "
+                      "THAT outcome in (0,1). Translated to Kalshi's YES-book "
+                      "bid/ask internally. DRY-RUN by default.")
+async def kalshi_place_order(ticker: str, outcome: str, action: str,
+                             price: float, count: float,
+                             time_in_force: str = "good_till_cancelled") -> str:
+    return _j(await kx.place_order(ticker, outcome, action, price, count,
+                                   time_in_force))
+
+
+@srv.tool(description="Cancel a Kalshi order by id (respects dry-run).")
+async def kalshi_cancel_order(order_id: str) -> str:
+    return _j(await kx.cancel_order(order_id))
+
+
+@srv.tool(description="Server status: dry-run state, attribution config, "
+                      "and which capabilities are enabled.")
+def server_info() -> str:
+    return _j({
+        "name": "oddsrail",
+        "version": "0.3.0",
+        "dry_run": trading.dry_run(),
+        "trading_key_configured": bool(os.environ.get("POLYMARKET_PRIVATE_KEY")),
+        "builder_code_configured": bool(trading.builder_code()),
+        "builder_code_source": trading.builder_code_source(),
+        "attribution": "on-chain (CLOB V2 builder field)",
+        "custody": "none — self-hosted, keys stay local",
+        "venues": {
+            "polymarket": {"attribution": "on-chain builder code",
+                           "trading_key": bool(os.environ.get("POLYMARKET_PRIVATE_KEY"))},
+            "kalshi": {"attribution": "none available on REST",
+                       "credentials": kx.has_credentials(),
+                       "environment": "demo" if os.environ.get("KALSHI_DEMO") else "production"},
+        },
+        "premium_tools": ["overshoot_signal", "dispute_risk"],
+    })
+
+
+def main() -> None:
+    srv.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

oddsrail/signals.py

@@ -0,0 +1,202 @@
+"""Signal tools: the premium layer of oddsrail.
+
+overshoot: adapted from the polymarket-wc in-play overshoot analyzer —
+detects endogenous price jumps in a recent price series and reports whether
+the market is currently inside a fresh jump window (the fade-the-overreaction
+setup) plus how much past jumps in this series reverted.
+
+dispute_risk: heuristic scoring of how likely a market's resolution gets
+messy (UMA disputes), from market metadata. Honest v0: a transparent
+rules-based score with reasons, not a trained model.
+"""
+
+import bisect
+import statistics
+
+
+# --------------------------------------------------------------------------- #
+# Overshoot                                                                    #
+# --------------------------------------------------------------------------- #
+
+def _price_at(times, prices, t):
+    i = bisect.bisect_right(times, t) - 1
+    return prices[i] if i >= 0 else None
+
+
+def detect_jumps(times, prices, *, lookback=60.0, threshold=0.05,
+                 settle=30.0, debounce=90.0, horizons=(30, 60, 120, 300)):
+    """Find jumps >= threshold within lookback seconds; measure reversion.
+
+    Returns a list of event dicts. Reversion fraction: +1.0 = fully retraced,
+    0.0 = sticky, <0 = kept running (momentum).
+    """
+    events = []
+    last_t = None
+    n = len(times)
+    for i in range(n):
+        t, p = times[i], prices[i]
+        ref = _price_at(times, prices, t - lookback)
+        if ref is None or abs(p - ref) < threshold:
+            continue
+        if last_t is not None and (t - last_t) < debounce:
+            continue
+
+        direction = 1 if p > ref else -1
+        ext_p, ext_t = p, t
+        j = i
+        while j < n and times[j] <= t + settle:
+            better = prices[j] > ext_p if direction == 1 else prices[j] < ext_p
+            if better:
+                ext_p, ext_t = prices[j], times[j]
+            j += 1
+
+        jump = (ext_p - ref) * direction
+        if jump <= 0:
+            continue
+
+        rev = {}
+        for h in horizons:
+            ph = _price_at(times, prices, ext_t + h)
+            rev[h] = None if ph is None else round(((ext_p - ph) * direction) / jump, 3)
+
+        events.append({
+            "detected_at": t, "direction": "up" if direction == 1 else "down",
+            "pre_jump_price": round(ref, 4), "extreme_price": round(ext_p, 4),
+            "extreme_at": ext_t, "jump_size": round(jump, 4),
+            "reversion_by_horizon_s": rev,
+        })
+        last_t = t
+    return events
+
+
+def overshoot_report(times, prices, *, lookback=60.0, threshold=0.05,
+                     settle=30.0, debounce=90.0, fresh_window=300.0):
+    """Live overshoot signal for one price series (oldest -> newest)."""
+    if len(times) < 5:
+        return {"ok": False, "error": "not enough price history points"}
+
+    events = detect_jumps(times, prices, lookback=lookback, threshold=threshold,
+                          settle=settle, debounce=debounce)
+    now = times[-1]
+    current = prices[-1]
+    fresh = [e for e in events if now - e["extreme_at"] <= fresh_window]
+
+    # historical tendency of this series: median reversion at 120s
+    hist = [e["reversion_by_horizon_s"].get(120) for e in events
+            if e["reversion_by_horizon_s"].get(120) is not None]
+    tendency = round(statistics.median(hist), 3) if hist else None
+
+    out = {
+        "ok": True,
+        "last_price": round(current, 4),
+        "jumps_detected": len(events),
+        "median_reversion_120s": tendency,
+        "series_span_s": round(now - times[0], 1),
+        "events": events[-5:],
+        "fade_setup_active": False,
+    }
+    if fresh:
+        e = fresh[-1]
+        elapsed = now - e["extreme_at"]
+        retraced = ((e["extreme_price"] - current)
+                    / e["jump_size"] if e["direction"] == "up"
+                    else (current - e["extreme_price"]) / e["jump_size"])
+        out.update({
+            "fade_setup_active": True,
+            "active_jump": e,
+            "seconds_since_extreme": round(elapsed, 1),
+            "retraced_so_far": round(retraced, 3),
+            "note": ("price jumped {} by {:.1%}; historically this series' jumps "
+                     "retrace a median of {} of the move within 120s"
+                     ).format(e["direction"], e["jump_size"],
+                              f"{tendency:.0%}" if tendency is not None else "n/a"),
+        })
+    return out
+
+
+# --------------------------------------------------------------------------- #
+# Dispute risk                                                                 #
+# --------------------------------------------------------------------------- #
+
+# words that historically correlate with contested resolutions: subjective
+# criteria, source ambiguity, or human-judgment resolution language
+_AMBIGUOUS = (
+    "consensus of", "credible report", "official announcement", "widely report",
+    "public statement", "in the opinion", "substantially", "materially",
+    "generally accepted", "confirmed by", "according to sources", "de facto",
+    "attempt", "significant", "major", "formal", "informal",
+)
+
+_CLEAN = (
+    "final score", "closing price", "settlement price", "official result",
+    "as reported by the associated press", "coin market cap", "coingecko",
+    "chainlink", "binance", "opening weekend", "box office",
+)
+
+
+def dispute_risk(market: dict) -> dict:
+    """Score 0-100 how likely this market's resolution gets contested.
+
+    Transparent heuristic v0 built from the failure patterns in 2026's UMA
+    dispute wave (subjective wording, long-tail topics, deadline-edge risk,
+    big open interest attracting oracle manipulation).
+    """
+    score = 0
+    reasons = []
+
+    desc = " ".join(str(market.get(k, "")) for k in
+                    ("description", "question", "title")).lower()
+
+    hits = [w for w in _AMBIGUOUS if w in desc]
+    if hits:
+        pts = min(35, 12 * len(hits))
+        score += pts
+        reasons.append(f"+{pts}: ambiguous resolution wording ({', '.join(hits[:4])})")
+
+    clean_hits = [w for w in _CLEAN if w in desc]
+    if clean_hits:
+        score -= 15
+        reasons.append(f"-15: objective settlement source named ({clean_hits[0]})")
+
+    uma = str(market.get("umaResolutionStatus", "") or
+              market.get("uma_resolution_status", "")).lower()
+    if "dispute" in uma:
+        score += 40
+        reasons.append("+40: UMA status shows an active or past dispute")
+    elif "proposed" in uma:
+        score += 10
+        reasons.append("+10: resolution proposed, challenge window open")
+
+    if market.get("negRisk") or market.get("neg_risk"):
+        score += 5
+        reasons.append("+5: neg-risk (multi-outcome) market — more edge cases")
+
+    try:
+        vol = float(market.get("volume", 0) or 0)
+        if vol > 5_000_000:
+            score += 15
+            reasons.append("+15: large open interest (>$5M) — worth manipulating")
+        elif vol > 1_000_000:
+            score += 8
+            reasons.append("+8: meaningful open interest (>$1M)")
+    except (TypeError, ValueError):
+        pass
+
+    # deadline-edge risk: events that can happen right at the boundary
+    for w in ("by ", "before ", "deadline", "by the end of"):
+        if w in desc:
+            score += 8
+            reasons.append("+8: deadline-conditioned question (boundary-case risk)")
+            break
+
+    score = max(0, min(100, score))
+    band = ("low" if score < 25 else
+            "moderate" if score < 50 else
+            "elevated" if score < 75 else "high")
+    return {
+        "score": score,
+        "band": band,
+        "reasons": reasons,
+        "disclaimer": ("heuristic v0 — transparent rules, not a model; "
+                       "treat as a triage flag, not a probability"),
+    }

oddsrail/trading.py

@@ -0,0 +1,125 @@
+"""Order routing with on-chain builder-code attribution (CLOB V2).
+
+How attribution works (verified against docs.polymarket.com, Aug 2026):
+the operator's bytes32 builder code — from polymarket.com/settings?tab=builder —
+is placed in the `builder` field of the V2 order struct BEFORE signing, so
+attribution is on-chain: every OrderFilled event on CTF Exchange V2 carries it,
+and builder fees (taker <= 100 bps, maker <= 50 bps, additive to platform fees)
+settle to the builder-profile wallet.
+
+Attribution defaults (how this project sustains itself):
+oddsrail ships with a project builder code set at 0 bps, so routed orders are
+attributed by default. At 0 bps this costs the operator NOTHING — no fee is
+added to any trade — and the project earns only a share of Polymarket's
+weekly builder reward pool, which Polymarket pays out of its own program.
+Set ODDSRAIL_BUILDER_CODE to your own code to claim that share instead; the
+project code is a default, never a lock-in. server_info reports which is
+in use.
+
+Safety model:
+- ODDSRAIL_DRY_RUN=1 (default): place_order returns the exact order it WOULD
+  post, never touches the exchange. Set ODDSRAIL_DRY_RUN=0 to trade.
+- Trading requires POLYMARKET_PRIVATE_KEY (+ POLYMARKET_WALLET_ADDRESS for
+  proxy/deposit wallets). Keys stay on this machine — oddsrail is self-hosted
+  and non-custodial by design.
+"""
+
+import os
+
+_secure = None
+
+
+def dry_run() -> bool:
+    return os.environ.get("ODDSRAIL_DRY_RUN", "1") not in ("0", "false", "no")
+
+
+# The project's own builder code ("oddsrail" builder profile), applied when the
+# operator has not set one. Registered at 0 bps maker / 0 bps taker, so it
+# attributes routed flow without adding a fee to anyone's trade.
+DEFAULT_BUILDER_CODE = "0xa576c5ce9fabba322d8fa3a8d16738221d1b6b2b0c57b544f757fa9e45a09a90"
+
+
+def builder_code() -> str | None:
+    """Operator's code if set, else the project default (may be empty)."""
+    return os.environ.get("ODDSRAIL_BUILDER_CODE") or DEFAULT_BUILDER_CODE or None
+
+
+def builder_code_source() -> str:
+    if os.environ.get("ODDSRAIL_BUILDER_CODE"):
+        return "operator (ODDSRAIL_BUILDER_CODE)"
+    if DEFAULT_BUILDER_CODE:
+        return "oddsrail project default (0 bps — no fee added; override with ODDSRAIL_BUILDER_CODE)"
+    return "none configured"
+
+
+async def _client():
+    global _secure
+    if _secure is None:
+        from polymarket import AsyncSecureClient
+        key = os.environ.get("POLYMARKET_PRIVATE_KEY")
+        if not key:
+            raise RuntimeError(
+                "POLYMARKET_PRIVATE_KEY not set — trading tools are disabled. "
+                "Read-only tools work without it.")
+        _secure = await AsyncSecureClient.create(
+            private_key=key,
+            wallet=os.environ.get("POLYMARKET_WALLET_ADDRESS"),
+        )
+    return _secure
+
+
+def _intent(token_id, side, price, size, order_type):
+    code = builder_code()
+    return {
+        "exchange": "polymarket",
+        "token_id": token_id,
+        "side": side,
+        "price": price,
+        "size": size,
+        "order_type": order_type,
+        "builder_code": code,
+        "attribution": ("on-chain: builder code signed into the order "
+                        f"[{builder_code_source()}]"
+                        if code else
+                        "NONE — no builder code configured"),
+    }
+
+
+async def place_order(token_id: str, side: str, price: float, size: float,
+                      order_type: str = "GTC"):
+    side = side.upper()
+    if side not in ("BUY", "SELL"):
+        raise ValueError("side must be BUY or SELL")
+    if not (0 < price < 1):
+        raise ValueError("price is an implied probability in (0, 1)")
+    if size <= 0:
+        raise ValueError("size must be positive (number of shares)")
+
+    intent = _intent(token_id, side, price, size, order_type)
+    if dry_run():
+        return {"dry_run": True, "would_post": intent,
+                "note": "set ODDSRAIL_DRY_RUN=0 to post real orders"}
+
+    client = await _client()
+    resp = await client.place_limit_order(
+        token_id=token_id, price=str(price), size=str(size), side=side,
+        builder_code=builder_code())
+    from .polymarket import dump
+    return {"dry_run": False, "posted": intent, "response": dump(resp)}
+
+
+async def cancel_order(order_id: str):
+    if dry_run():
+        return {"dry_run": True, "would_cancel": order_id}
+    client = await _client()
+    from .polymarket import dump
+    return dump(await client.cancel_order(order_id))
+
+
+async def open_orders():
+    if not os.environ.get("POLYMARKET_PRIVATE_KEY"):
+        return {"note": "no trading key configured; nothing to list"}
+    client = await _client()
+    from .polymarket import dump
+    page = await client.list_open_orders().first_page()
+    return dump(list(page.items))

oddsrail-0.3.0.dist-info/METADATA

@@ -0,0 +1,261 @@
+Metadata-Version: 2.5
+Name: oddsrail
+Version: 0.3.0
+Summary: MCP server giving AI trading agents access to prediction markets (Polymarket, Kalshi) with on-chain builder-code attribution and trading signals.
+Project-URL: Homepage, https://github.com/hmesutozsoy/oddsrail
+Project-URL: Repository, https://github.com/hmesutozsoy/oddsrail
+Project-URL: Issues, https://github.com/hmesutozsoy/oddsrail/issues
+Author: oddsrail
+License: MIT License
+        
+        Copyright (c) 2026 oddsrail
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: ai-agents,kalshi,llm,mcp,model-context-protocol,polymarket,prediction-markets,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx>=0.28
+Requires-Dist: mcp[cli]>=2.0.0
+Requires-Dist: polymarket-client>=0.6.0
+Description-Content-Type: text/markdown
+
+# oddsrail
+
+<!-- mcp-name: io.github.hmesutozsoy/oddsrail -->
+
+**The rail AI agents use to trade prediction markets.**
+
+An MCP server that gives any agent (Claude Code, Claude Desktop, or anything
+MCP-compatible) prediction-market access across **Polymarket and Kalshi**:
+market search, orderbooks, price history, positions, and order routing — with
+**on-chain builder-code attribution** on Polymarket — plus two premium signal
+tools (in-play overshoot/fade detection, resolution dispute-risk).
+
+**Free to use, and free of fees.** oddsrail ships with a project builder code
+registered at **0 bps**, so orders routed through it are attributed without
+adding a single basis point to anyone's trade. The project's income is a share
+of Polymarket's weekly builder reward pool — paid by Polymarket's own program,
+not by you. Running your own builder profile instead is one environment
+variable (`ODDSRAIL_BUILDER_CODE`), and `server_info` always tells you which
+code is in use. No fee tiers, no paywalled tools, no account required.
+
+## Why this and not Parsec
+
+The closest competitor (parsecapi.com) is a closed-source hosted service:
+it stores your exchange keys (or holds a managed wallet that signs for you),
+and its Builder Program keeps **55–85% of the fees builders collect**.
+oddsrail is the opposite on every axis: **self-hosted, non-custodial (keys
+never leave your machine), open source, and you keep 100% of your Polymarket
+builder fees** because attribution uses Polymarket's native mechanism, not a
+middleman escrow. Parsec also ships zero signal/analytics tools and nothing
+on resolution risk — that's our paid layer.
+
+## Quickstart
+
+Python 3.11+ required.
+
+```bash
+pip install oddsrail
+```
+
+```bash
+claude mcp add --transport stdio oddsrail -- oddsrail
+```
+
+Or from a clone, without installing:
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
+```
+
+```bash
+claude mcp add --transport stdio oddsrail -- /abs/path/to/oddsrail/.venv/bin/python -m oddsrail.server
+```
+
+Then ask the agent: *"search markets about the World Cup final and run the
+overshoot signal on the favorite"*.
+
+## How attribution works (CLOB V2, verified Aug 2026)
+
+1. Get your **builder code** (a bytes32) at polymarket.com → **Settings →
+   Builders**. Set your fee rates there: taker up to 100 bps, maker up to
+   50 bps — additive on top of platform fees, settled to your builder wallet.
+2. `export ODDSRAIL_BUILDER_CODE=0x...` where the server runs.
+3. Every order any agent routes through `place_order` has the code placed in
+   the V2 order struct's `builder` field **before signing** — attribution is
+   on-chain, visible in every `OrderFilled` event on CTF Exchange V2.
+4. Verify with the `builder_stats` tool (public builder-trades endpoint +
+   leaderboard).
+
+If you skip this, orders carry the bundled oddsrail code at 0 bps — costing
+you nothing and funding the project. If you set your own, yours wins; the
+default is a default, not a lock-in.
+
+## Environment variables
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `ODDSRAIL_DRY_RUN` | `1` | `1` = orders are simulated and returned, never posted. Set `0` to trade. |
+| `ODDSRAIL_BUILDER_CODE` | project default | Your bytes32 builder code. Overrides the bundled project default so attribution (and any reward-pool share) accrues to you instead. |
+| `POLYMARKET_PRIVATE_KEY` | unset | Operator wallet key; required only for real trading. Never leaves this machine. |
+| `POLYMARKET_WALLET_ADDRESS` | unset | Proxy/deposit wallet address, if the account uses one. |
+
+## Status — live-verified 2026-08-23
+
+All 10 callable tools were driven end-to-end through a real MCP client
+session against live Polymarket, from the Finland VPS (`/opt/oddsrail`).
+Verified working: search, market lookup, orderbook (9/65 levels), price
+history (361 pts), overshoot signal, dispute-risk, builder leaderboard,
+dry-run order, open orders, server info.
+
+Field mappings were corrected against the real API during that run — the
+docs-guessed shapes were wrong in three places (`outcomes` is a dict keyed
+`yes`/`no`, `search()` nests markets inside events, and book/volume/
+resolution data live in `prices`/`metrics`/`state`/`resolution`
+sub-objects).
+
+## ⚠️ Network note
+
+Polymarket API domains are **blocked on Turkish networks (BTK)** — local
+testing fails TLS with a block page. Run the server where Polymarket is
+reachable (the Finland VPS at `/opt/oddsrail`, a VPN, or any unblocked
+network). The signal logic and MCP layer are fully testable offline.
+
+## Kalshi (venue #2)
+
+Kalshi is **bring-your-own-key and single-tenant by design**: the operator
+supplies their own API key, trades their own account, and this server caches
+nothing. That is deliberate — Kalshi's Developer Agreement limits API use to a
+member's own trading (§3), bars facilitating other members' trading (§3.2) and
+sublicensing the API (§3.7), and restricts storing/sharing API data (§3.1). A
+hosted multi-tenant Kalshi service would not be compliant; a self-hosted one is.
+
+**Attribution does not exist here.** Kalshi Builder Codes are a
+Solana/DFlow/Jupiter integration — there is no builder or affiliate field
+anywhere on the REST API, so Kalshi order flow cannot be attributed or
+monetised the way Polymarket's can. Kalshi is in oddsrail for coverage and
+signal reach, not for routing revenue.
+
+Two shapes on this API are easy to get wrong, so oddsrail normalises both:
+
+- **Prices are dollar strings, not cents** (`"0.5600"`), sizes are fixed-point
+  strings (`"10.00"`); the legacy integer-cent fields were removed in March
+  2026. All arithmetic uses `Decimal`.
+- **The orderbook is bids-only on both sides.** `yes_dollars` and `no_dollars`
+  are both bid ladders, ascending — so the best bid is the *last* element, and
+  a NO bid at $0.99 *is* a YES ask at $0.01. `kalshi_get_orderbook` returns a
+  conventional best-first bid/ask view of the YES book plus the raw ladders.
+
+Order placement speaks natural terms — `outcome` (yes/no), `action`
+(buy/sell), `price` = probability of that outcome — and translates to Kalshi's
+YES-book `bid`/`ask` internally (buy NO @ 0.25 becomes ask @ 0.75). That
+translation is unit-tested, since it is the obvious place to ship an
+inverted-position bug.
+
+Credentials: `KALSHI_KEY_ID` plus `KALSHI_PRIVATE_KEY_PATH` (PKCS#8 PEM) or
+`KALSHI_PRIVATE_KEY`. Set `KALSHI_DEMO=1` to hit the demo environment. Read
+tools need no key at all.
+
+## Tools (21)
+
+- `search_markets`, `get_market`, `get_orderbook`, `price_history`,
+  `get_positions` — read-only, no keys
+- `overshoot_signal` — premium: fresh panic-jump detection + this market's
+  historical reversion tendency (ported from the polymarket-wc analyzer)
+- `dispute_risk` — premium: transparent 0–100 heuristic for contested
+  (UMA-dispute-prone) resolutions
+- `place_order`, `cancel_order`, `open_orders` — trading, dry-run by default
+- `builder_stats` — attribution verification + public builder leaderboard
+- `server_info` — config status, per-venue
+
+Kalshi: `kalshi_search_markets`, `kalshi_get_market`, `kalshi_get_orderbook`,
+`kalshi_get_trades`, `kalshi_balance`, `kalshi_positions`,
+`kalshi_open_orders`, `kalshi_place_order`, `kalshi_cancel_order`.
+
+## Stack notes
+
+- Official unified SDK `polymarket-client` (0.6.x): `AsyncPublicClient` for
+  data, `AsyncSecureClient.place_limit_order(..., builder_code=...)` for
+  attributed orders. The legacy `py-clob-client` is archived and cannot
+  attach builder codes — do not use it.
+- MCP SDK 2.0: `MCPServer` from `mcp.server.mcpserver` (the old
+  `mcp.server.fastmcp.FastMCP` import is gone in 2.x).
+- Kalshi is on plain `httpx` + `cryptography`, not the official SDK:
+  `kalshi-python-sync` requires Python >=3.13 and re-releases weekly in
+  lockstep with the spec version. Auth is RSA-PSS(SHA256, salt=digest length)
+  over `str(unix_ms) + METHOD + path`, where the path includes `/trade-api/v2`
+  and excludes the query string. Base URL is now
+  `external-api.kalshi.com`.
+- x402 (planned): the official `x402` PyPI package (v2.20+) can wrap MCP
+  tools directly (`x402.mcp`, payment rides in tool-call `_meta`), but its
+  MCP helpers currently target mcp 1.x — integrating means pinning
+  `mcp>=1.28,<2` or waiting for the 2.x-compatible release. Mainnet
+  settlement needs a facilitator (Coinbase CDP: 1,000 free settlements/mo,
+  then $0.001). Keep free tiers of both signals so registries can index the
+  server.
+
+## What the builder economy looks like (live, 2026-08-23)
+
+Pulled from the public leaderboard via `builder_stats`:
+
+| | weekly | all-time |
+|---|---|---|
+| #1 (betmoar) | $2.31M | $2.10B |
+| median of top 25 | $127K | $88.2M |
+| **entry to top 25** | **$42K** | $36.8M |
+
+The instructive rows are the small-user ones: MagicMarkets routes $354K/week
+with **1 active user**, Gate $1.11M/week with 2, PolymarketScan $277K with 3.
+Those are bot operators routing their own flow — oddsrail's exact target
+customer — and they show a single serious agent trader is worth real volume.
+Wallets (MetaMask, 37K users) dominate on user count, not on volume per user.
+
+## Roadmap
+
+1. ~~Live smoke test from an unblocked network~~ — done 2026-08-23, all tools pass
+2. Register builder code (polymarket.com → Settings → Builders), set fees to
+   0 bps at launch, export `ODDSRAIL_BUILDER_CODE`; first attributed order on
+   a tiny size
+3. ~~Kalshi as venue #2~~ — done 2026-08-23, 9 tools, verified live
+4. x402 paid wrapping for the two signals once the mcp-2.x conflict clears
+5. Registry listings: official MCP registry (`mcp-publisher`, PyPI
+   `mcp-name:` marker), Smithery (needs public streamable-HTTP + a free
+   tool for their scanner), Glama (`glama.json`)
+
+## Listing / distribution
+
+- **GitHub**: https://github.com/hmesutozsoy/oddsrail (public, MIT)
+- **Glama**: auto-crawls GitHub; `glama.json` in the repo root claims
+  maintainership.
+- **Official MCP registry**: `server.json` is ready. Publishing needs the
+  package on PyPI first (the registry verifies ownership via an
+  `mcp-name: io.github.hmesutozsoy/oddsrail` marker in the PyPI README),
+  then `mcp-publisher login github && mcp-publisher publish`.
+- **Smithery**: requires a public HTTPS streamable-HTTP endpoint — available
+  once oddsrail is hosted rather than run locally over stdio.

oddsrail-0.3.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+oddsrail/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+oddsrail/kalshi.py,sha256=D3Z0PsBV4fcMbeC5J-LCPZlJBxETQm7weXwHNfzUNEY,11706
+oddsrail/polymarket.py,sha256=6l_fCx7bTb_-ZfOpT1SeL_vZTpbSVPDS38gybSF4eR8,6002
+oddsrail/server.py,sha256=U9XnXSF29ugfbDoZ4vmFkHGIki7pbDW-bMgGWk1htH8,9827
+oddsrail/signals.py,sha256=CbkAfAylvmiNzzD5DUTDXuKYhRggk2rbBOsqeZeA0Bs,7763
+oddsrail/trading.py,sha256=IeotYKrAI3Ox6miW8LSm-k9I8sBKurZY5gnG9ortlHY,4805
+oddsrail-0.3.0.dist-info/METADATA,sha256=UnLorL26WqBdR_yrVfADzaEI486B1rmQHwLRELwLTPs,12774
+oddsrail-0.3.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+oddsrail-0.3.0.dist-info/entry_points.txt,sha256=OUyo11JafqYpJ9xvI7bqRm0SKMlzwifAert3ZSKkKt8,50
+oddsrail-0.3.0.dist-info/licenses/LICENSE,sha256=x5otxHpKt24xA6z0y05NfPHyTdWd3K5SRN69W8v7mJk,1065
+oddsrail-0.3.0.dist-info/RECORD,,

oddsrail-0.3.0.dist-info/WHEEL

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

oddsrail-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+oddsrail = oddsrail.server:main

oddsrail-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 oddsrail
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.