oddsrail 0.3.0__tar.gz

oddsrail-0.3.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.pyc
+.env
+*.log

oddsrail-0.3.0/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.

oddsrail-0.3.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,214 @@
+# 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/llms.txt

@@ -0,0 +1,54 @@
+# oddsrail
+
+> An MCP server that gives AI trading agents access to prediction markets
+> across Polymarket and Kalshi, with on-chain builder-code attribution on
+> routed Polymarket orders and premium signal tools.
+
+Self-hosted and non-custodial: the operator runs the server themselves and
+private keys never leave their machine. Orders are dry-run by default.
+
+## What an agent can do with it
+
+- `search_markets(query, limit)` — find markets by text; returns token ids,
+  best bid/ask, spread, 24h volume, liquidity, end date, resolution status
+- `get_market(id_or_slug)` — one market's details
+- `get_orderbook(token_id)` — live bids/asks
+- `price_history(token_id, hours, fidelity_minutes)` — recent price series
+- `get_positions(address)` — a wallet's current positions
+- `overshoot_signal(token_id, hours, threshold)` — detects fresh price jumps
+  (panic moves) and reports whether a fade setup is active, plus that
+  market's historical reversion tendency
+- `dispute_risk(id_or_slug)` — 0-100 score for how likely a market's
+  resolution gets contested (UMA dispute risk), with transparent reasons
+- `place_order(token_id, side, price, size)` — limit order; price is an
+  implied probability in (0,1); dry-run unless the operator enables trading
+- `cancel_order(order_id)`, `open_orders()`
+- `builder_stats(time_period)` — public builder leaderboard and this
+  operator's attributed trades
+
+## Kalshi tools
+
+- `kalshi_search_markets(query, limit, min_volume)`, `kalshi_get_market(ticker)`,
+  `kalshi_get_orderbook(ticker, depth)`, `kalshi_get_trades(ticker, limit)`
+- `kalshi_balance()`, `kalshi_positions()`, `kalshi_open_orders()`
+- `kalshi_place_order(ticker, outcome, action, price, count)` — outcome yes|no,
+  action buy|sell, price is the probability of THAT outcome in (0,1)
+- `kalshi_cancel_order(order_id)`
+
+Kalshi notes: prices are dollar strings not cents; the raw orderbook is
+bids-only on both sides (a NO bid at 0.99 is a YES ask at 0.01) but
+`kalshi_get_orderbook` returns a normal best-first bid/ask view. Kalshi needs
+the operator's own API key for private endpoints; read tools do not.
+
+## Install
+
+python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
+claude mcp add --transport stdio oddsrail -- /abs/path/oddsrail/.venv/bin/python -m oddsrail.server
+
+## Notes for agents
+
+- Prices are implied probabilities in (0,1), not cents.
+- `place_order` returns `{"dry_run": true, ...}` unless the operator has set
+  ODDSRAIL_DRY_RUN=0 — check this before assuming an order was placed.
+- Polymarket API domains are blocked on some networks (e.g. Turkey); run the
+  server where they resolve.