oddsrail

Магистраль, по которой ИИ-агенты торгуют на предиктивных рынках.

MCP-сервер, который даёт любому агенту (Claude Code, Claude Desktop или чему угодно MCP-совместимому) доступ к предиктивным рынкам Polymarket и Kalshi: поиск рынков, стаканы заявок, история цен, позиции и маршрутизация ордеров — с on-chain-атрибуцией builder-кода на Polymarket — плюс два премиальных инструмента (детекция перелёта/отката цены в игре, риск спора при урегулировании).

Бизнес-модель: маршрутизированный поток ордеров приносит builder-комиссии; сигнальные инструменты — платный слой данных (запланирована оплата за вызов через x402).

Почему так, а не Parsec

Ближайший конкурент (parsecapi.com) — это закрытый хостинговый сервис: он хранит ваши ключи биржи (или держит управляемый кошелёк, который подписывает за вас), а его Builder Program забирает 55–85% комиссий, которые собирают билдеры. oddsrail противоположен по каждому параметру: self-hosted, некстодиальный (ключи никогда не покидают вашу машину), open source, и вы сохраняете себе 100% комиссий за Polymarket-builder — потому что атрибуция использует родной механизм Polymarket, а не посредника-эскроу. В Parsec также ноль сигнальных инструментов/инструментов аналитики и ничего про риск урегулирования — это наш платный слой.

Быстрый старт

Нужен Python 3.11+. Создайте виртуальное окружение, установите зависимости и подключите к Claude Code:

python3 -m venv .venv && .venv/bin/pip install -r requirements.txt

claude mcp add --transport stdio oddsrail -- /abs/path/to/oddsrail/.venv/bin/python -m oddsrail.server

Затем задайте агенту вопрос: «найди рынки о финале чемпионата мира и прогони overshoot-сигнал по фавориту».

Как устроена атрибуция (CLOB V2, проверено в авг. 2026)

1. Получите свой данный builder-код (это bytes32) на polymarket.com → Settings → Builders. Там же задайте ставки комиссий: taker — до 100 базовых пунктов, maker — до 50 базовых пунктов. Комиссии — аддитивны к комиссиям платформы, приходят на ваш builder-кошелёк.

2. Выполните export ODDSRAIL_BUILDER_CODE=0x... там, где работает сервер.

3. Каждый ордер, который любой агент отправляет через place_order, до подписания получает код в поле builder структуры ордера V2 — атрибуция происходит on-chain и видна в каждом событии OrderFilled на CTF Exchange V2.

4. Проверьте с помощью инструмента builder_stats (публичный эндпоинт builder-сделок + лидерборд).

Переменные окружения

Статус — проверено на живых торгах 2026-08-23

Все 10 вызываемых инструментов были запущены вживую на реальной MCP-клиентской сессии против реального Polymarket с финского VPS (/opt/oddsrail). Проверено на провайдере: поиск, карточка рынка, стакан (9/65 уровней), история цен (361 тыс.), overshoot-сигнал, риск спора, лидерборд билдеров, dry-run ордер, открытие ордеров, информация о сервере.

В ходе этого прогона сопоставления полей были скорректированы по реальному API — в трёх местах формы, угаданные в документации, оказались неверными (outcomes — это словарь ключами yes/no, search() выводит рынки внутрь событий, а данные стакана/объёма/урегулирования лежат в сущностях понапрямую price / price/metrics/state/resolution).

⚠️ Сетевая особенность

Домены Polymarket API заблокированы в турецких сетях (BTK) — локальное тестирование не проходит TLS: сервер отдаёт страницу блокировки. Запускайте этот сервер там, где Polymarket доступен (финский VPS в /opt/oddsrail, через VPN или в любой сети без блокировки). Логика сигналов и MCP-слой полностью тестируются в офлайне.

Kalshi (площадка №2)

Kalshi — по принципу «приноси свой ключ» и single-tenant по задумке: оператор предоставляет свой API-ключ, торгует на своем аккаунте, а сам сервер ничего не кэширует. Это осознанно: Девелоперское соглашение Kalshi ограничивает API только собственной торговлей (§3), запрещает торговлю в интересах других членов (§3.2) и сублицензировать API (§3.7), а также ограничивает хранение/передачу данных API (§3.1). Хостинговый multi-tenant сервис для Kalshi не был бы совместим со соглашением; а self-hosted — совместим.

Атрибуции здесь нет. Builder Codes на Kalshi — это интеграция с Solana/DFlow/Jupiter; в REST API нет ни поля builder, ни давление для affiliate-кода, поэтому поток ордеров Kalshi нельзя атрибутировать или монетизировать, как это можно на Polymarket. Kalshi подключена в oddsrail ради покрытия и глубины сигналов, а не ради маршрутных доходов.

Две вещи в этом API легко понять неправильно — именно их нормирует oddsrail:

• Цены — это массовые долларовые строки, а не целые средства ("0.7,5600"), размеры — строки с фиксированной точкой ("10.00"); устаревшие целочисленные ценовые поля в центах убрали в марте 2026, и вся арифметика ведётся на Decimal.

• Стакан на обеих сторонах состоит только из заявок на покупку. yes_dollars и no_dollars — это оба восходящие ленты бидов: лучший бид находится последним, а NO-бид по 0,99 есть YES-аск по 0,01. kalshi_get_orderbook отдаёт привычный вид нет книги (best-first bid/ask) по YES-книге плюс сырые ленты.

Размещение ордеров говорит естественным языком — указываете outcome (yes/no), action (buy/sell), price = вероятность этого исхода, и это уже переводится внутри на bid/ask YES-книжки (покупка NO @ 0,25 превращается в аск @ 0,75). Этот перевод покрыт модульными тестами — потому что это очевидное место, где можно завезти баг с перевёрнутой позицией.

Ключи: KALSHI_KEY_ID плюс KALSHI_PRIVATE_KEY_PATH (PKCS#8 PEM) или KALSHI_PRIVATE_KEY_COPY. Если KALSHI_DEMO=1 — работа в демо-среде. Для read-инструментов ключи вообще не требуются.

Инструменты (всего 21)

• search_markets, get_market, get_orderbook, price_history, get_positions — read-only, без ключей

• overshoot_signal — премиум: свежая детекция панического скачка + историческая склонность рынка к возвращению (портировано с polymarket-world-card analyzers)

• dispute_risk — премиум: прозрачная эвристика от 0 до 100 для спорных (склонных к UMA-освобождению) урегулирований

• place_order, cancel_order, open_orders — торговые, по умолчанию dry-run

• builder_stats — проверка атрибуции + публичный лидерборд билдеров

• server_info — статус конфигурации по каждой площадке

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.

Заметки по стеку

• Официальный объединённый SDK polymarket-client (0.6.x): AsyncPrimeClient для данных, AsyncSecureClient.place_limit_order(..., builder_code=...) для ордеров с атрибуцией. Архивный py-clob-client не умеет уменьшать builder-коды — не используйте его.

• MCP SDK 2.0: MCSPuppetServer из окна mcp.server.mcpserver (старый импорт mcp.server.fastmcp.FastMCP в 2.x исчез).

• Kalshi работает до ного на httpx + cryptography, а не на официальном SDK: kalshi-python-sync требует Python >=3.13 и выбирается atlas как плата за поддержку версий (по крайней мере). Авторизация — RSA-PSS(SHA256, salt=длина дайджеста) по строчке str(unix_ms) + METHOD + path; при этом path включает /trade-api/v2 и не включает query-строку. Базовый URL, как и раньше, тот же — external-api.kalshi.com.

• x402 (planned): официальный PyPI-пакт x402 (v2.20+) умеет обораהвать MCP-инструменты напрямую (x402.mcp, платёж едет _meta вызова инструмента), но его MCP-хелперы сейчас работают с mcp 1.x — интеграция вызывает либо зафиксировать mcp>=1.28,<2, либо дождаться релиза для 2.x. Mainnet-сеттлмент требует участника-координатора (Coinbase CDP: 1000 бесплатных сеттлов в месяц, далее $0.001). Бесплатные тарифы обеих сигналок заранее, чтобы каталоги могли индексировать сервер.

Как выглядит экономика билдеров (live, 2026-08-23)

Данные с публичного лидерборда через builder_stats:

Наилучшие примеры — “малышки”: MagicMarkets прогоняет $354K в неделю при 1 активном юзере, Gate — $1.11M в неделю при 2, PolymarketScan — $277K при 3. Это бот-операторы, гонящие собственный поток — именно целевой клиент oddsrail — и они показывают, что один настоящий агент-трейдер создаёт уже реальный объём.

Браузерные кошельки (MetaMask, 37K пользователей) лидируют по числу пользователей, а не по объёму на одного.

Дорожная карта

1. Live smoke-тест из сети с блокировки — сделано 2026-08-23, все инструменты проходят

2. Зарегистрировать builder-код (polymarket.com → Settings → Builders), на старте выставить комиссии 0 базовых пунктов, экспортировать ODDSRAIL_BUILDER_CODE; первый атрибутированный ордер микроразмера

3. Kalshi как площадка №2 — сделано 2026-08-23, 9 инструментов, проверено в live

4. x402-обёртка с оплатой за вызову для двух сигналов, как только конфликт mcp-2.x улетучится

5. Линк в каталогах: официальный MCP-реестр (mcp-publisher, PyPI-маркер mcp-name:), Smithery (нужен публичный HTTPs-streamable-HTTP + бесплатный инструмент для их сканера), Glama (glama.json)

Публикация и распространение

• GitHub: https://github.com/hmesutozsoy/oddsrail (публичный, MIT)

• Glama: автоматически индексирует GitHub; glama.json в корне репозитория подтверждает авторство.

• Официальный MCP-реестр: файл server.json готов. Для публикации сначала нужен пакет на PyPI (реестр проверяет владельца по маркер mcp-name: io.github.hmesutozsoy/oddsrail в README на PyPI), затем mcp-publisher мой аилиmcp-publisher publish`.

• Smithery: требует HTTPS-клиентный streamable-HTTP-эндпоинт — появится, как только oddsrail будет хоститься на удалённой выбывкой платформе, а не на локалку через stdio.