oddsrail

AI 에이전트가 예측 시장 거래에 사용하는 레일입니다.

모든 에이전트(Claude Code, Claude Desktop 또는 MCP와 호환되는 무엇이든)가 Polymarket과 Kalshi 전반에서 예측 시장에 접근할 수 있게 해주는 MCP 서버입니다. 시장 검색, 오더북, 가격 이력, 포지션, 주문 라우팅을 제공하고, Polymarket에서는 온체인 빌더 코드 어트리뷰션이 적용되며, 두 가지 프리미엄 시그널 도구(경기 중 오버슈트/페이드 감지, 결과 해소 분쟁 리스크)가 포함됩니다.

비즈니스 모델: 라우팅되는 주문 흐름이 빌더 수수료를 벌어들이고, 시그널 도구는 유료 데이터 레이어입니다(x402 호출당 과금 예정).

왜 Parsec이 아니라 이건가?

가장 가까운 경쟁사는 파섹이 아니라 어차피 parsecapi.com이 압도적으로 가까운데... Simplest: 그 경쟁사(parsecapi.com)는 클로즈드 소스 호스팅 서비스입니다. 거래소 키를 보관하거나(또는 당신을 대신해 서명하는 관리형 지갑을 보유하며) 빌더 프로그램이 빌더들이 거두는 수수료의 55–85%를 가져갑니다. oddsrail은 모든 측면에서 반대입니다. 자체 호스팅, 비수탁(키는 절대 내 컴퓨터를 떠나지 않음), 오픈소스, 그리고 Polymarket 빌더 수수료의 100%를 그대로 지불하지 않습니다. — 어트리뷰션이 파중간자 에스크로가 아니라 Polymarket의 네이티브 메커니즘을 사용하기 때문입니다. Parsec은 또한 시그널/분석 도구가 전혀 없고 해소 리스크 관련 기능도 없는데, 그것이 바로 우리의 유료 계층입니다.

빠른 시작

Python 3.11 이상이 필요합니다. venv를 만들고 설치한 다음 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 signal을 실행해 줘".

어트리뷰션이 작동하는 방식 (CLOB V2, 2026-08 검증)

1. polymarket.com의 Settings → Builders 에서 빌더 코드(bytes32)를 받으세요. 여기서 수수료율(taker 최대 100bps, maker 최대 50bps)을 설정할 수 있습니다. 플랫폼 수수료 위에 더해져 빌더 지갑으로 정산됩니다.

2. 서버가 실행되는 곳에서 export ODDSRAIL_BUILDER_CODE=0x... 명령을 실행하세요.

3. 어떤 에이전트가 place_order로 보내는 모든 주문은 서명 전에 V2 주문 구조체의 builder 필드에 해당 코드가 포함됩니다. 어트리뷰션은 CTX Exchange V2의 모든 OrderFilled 이벤트에서 확인할 수 있습니다.

4. builder_stats 도구를 통해 검증하세요(공개 빌더 거래 엔드포인트 + 리더보드).

환경 변수

상태 — 라이브 검증 2026-08-23

핀란드 VPS(/opt/oddsrail)에서 실제 MCP 클라이언트 세션으로 라이브 Polymarket을 대상으로 10개 도구 전체를 구동했습니다. 검증 완료: search, market lookup, orderbook(9/65 레벨), price history(361개), overshoot signal, dispute statistics, builder leaderboard, dry-run order, open orders, server info.

이 작업 중에 실제 API를 기준으로 필드 매핑을 수정했습니다. 문서상 추측한 형태가 세 곳에서 잘못되어 있었습니다. 구체적으로는 outcomes는 yes/no로 키가제인 dict이고, search()는 시장을 이벤트로 반환내포하는 구조이며, book/volume/resolution 데이터는 prices/metrics/state/resolution 하위 객체에 들어 있는 형태입니다.

⚠️ 네트워크 참고

Polymarket API 도메인은 튀르키예 네트워크(BTK)에서 차단되어 있습니다. 로컬 테스트는 차단 페이지로 인해 TLS가 실패합니다. Polymarket에 접근 가능한 환경에서기 서버를 실행하세요(예: /opt/oddsrail의 핀란드 VPS, VPN, 또는 비차단 네트워크). 시그널 로직과 MCP 레이어는 오픈에서 완전히 테스트할 수 있습니다.

Kalshi (두 번째 거래소)

Kalshi는 결제한 키와 단일 테넌트 방식을 기본 설계로 합니다. 운영자가 자체 API 키를 제공하고 자기 계정으로 거래하며, 서버는 아무것도 캐시하지 않습니다. 이는 의도적인 것입니다. Kalshi 개발 만약 계약은 API 사용을 회원 자신의 거래로만 한정하고, 타 회원의 거래를 돕는 행위를 금시키며, API 서브라이선스를 금지하고, API 데이터의 저장/공유를 제한한다는 것을 인지하고 있습니다. 실제 조항 (§3, §3.2, §3.7, §3.1)을 확인하세요. 호스팅형 멀티테넌트 Kalshi 서비스는 이를 준수할 수 없지만, 자체 호스팅은 준수할 수 있습니다.

어트리뷰션은 여기 존재하지 않습니다. Kalshi 빌더 프로그램은 Solana/DFlow/Jupiter 연동일 뿐, REST API에 내부적으로 builder나 affiliate 필드가 없습니다. 그래서 Kalshi 오더 흐름은 Polymarket처럼 어트리뷰트하거나 금전화할 수 없습니다. Kalshi 전용 시그널 범위와 커버리지를 위해 존재할 뿐 라우팅 수익을 위해 있는 것이 아닙니다.

이 API의 두 형태는 잘못 이해하기 쉽기 때문에 oddsload는 표준화합니다.

• 가격은 센트가 아니라 화폐 문자열 ("0.123"), 단, 크기는 고정 소수점 문자열 때문에 "10.15") · 기존 정수 센트 필드는 2026 年 3월에 삭제되었으며 모든 연산은 Decimal로 합니다.

• 오더북은 양쪽 모두 지정가 매수뿐입니다. yes_dollars와 no_dollars 모두 각각 매수 라더로서 오름차순으로 정렬되는데, 최고 매수 찬스는 마지막 요소이며, $0.99에 NO 매수는 $0.01에 YES 매도가 행동입니다. kalshi_get_orderbook은 일반적인 최정상 매수/매도 뷰 및 YES 북과 함께 real 수 있는 원래 ladder를 반환합니다.

주문 배치 하는 자연스러운 표현을 씁니다. outcome(yes/no), action(buy/sell), price = 해당 결과의 확률 이런 것을 Kalshi의 YES 북에 bid/ask 변환합니다(예: buy NO @ 0.25 → ask @ 0.75). 이 변환은 분명 역진입 위치 버그가 생길 수 있는 지점이므로 단위 테스트를 만들어 줍니다.

인증키: KALSHI_KEY_ID + KALSHI_PRIVATE_KEY_PATH(PKCS#8 PEM) 또는 KALSHI_PRIVATE_KEY. 데모환경으로 테스트하려면 KALSHI_DEMO=1로 설정. 읽기 도구는 키가 없어도 됩니다.

도구 (총 21개)

• search_markets, get_market, get_orderbook, price_history, get_positions — 읽기 전용, 키 없이 가능

• overshoot_signal — 프리미엄: 신선한 패닉 캐치 + 이 시장의 과거 되돌림 경향(polymarket-wc 분석기에서 포팅)

• dispute_risk — 프리미엄: 분colare(UMA 분쟁 등 위험)이 있는 해소에 대한 투명한 0–100 휴리스틱

• place_order, cancel_order, open_orders — 거래, 기본이 dry-run

• builder_stats — 어트리뷰션 검증 + 공개 빌더 리더보드

• server_info — 전 벤더별 계정 상태 설정

거래소 전용: 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): 데이터는 AsyncPublicClient, 어트리뷰트 주문은 AsyncSecureClient.place_order(order, 순서, builder_code=...)로 처리. 기존 py-clob-client는 아카이빙되어 빌더 코드를 못 붙이므로 사용 금지.

• MCP SDK 2.0은 일반 mcp.server.mcpserver에서 MCPServer를 가져옵니다. (옛 mcp.server.fastmcp.FastMCP 가져오기는 2.x에서 제거됨).

• Kalshi는 일반 httpx + cryptography를 사용하며 공식 SDK가 아닙니다: kalshi-python-sync는 Python >=3.13을 요구하고 스펙 버전에 맞춰 주마다 새로 배포됩니다. 인증은 str(unix_ms) + METHOD + path에 대해 RSA-Pinne(same length ± SHA256 salt)으로, 이때 path는 /trade-api/v2를 포함하며 쿼리 문자열은 제외합니다. 기본 URL은 현재 external-api.kalshi.com입니다.

• x402(계획): 공식 PyPI 패키지 x402(v2.20+)는 MCP 도구를 직접 랩핑할 수 있습니다(x402.mcp, 결제는 토션 _meta에 싣는 방식). 다만 x402의 MCP 도우미가 현재 MCP 1.x를 대상으로 하므로, 통합 시 mcp>=1.28,<2로 고정 하나 나 2.x 호환 버전을 기다려야 합니다. 메인넷 결산에는 파실리테이 터가 들어가는데(Coinbase CDP: 월 1,000건 무료 정산, 이후 0.001달러). 레지스트리가 서버를 인덱싱할 수 있도록 두 시그널의 무료 티어는 유지하세요.

빌더 경제의 실제 형태 (라이브, 2026–08–23)

공용 리더보드를 통해 제공받은 수치:

가장 관심 있는 줄은 소규모 사용자 통계입니다: MagicMarkets는 활성 사용자 1명으로 $354K/週 를 라우팅하고, Gate는 사용자 2명, with $1.11M/週, PolymarketScan은 사용자 3명 with $277K. 이들은 봇 운영자로 자기 오더 플로우를 스스로 라우팅하는데, 이들이 바로 oddsrail이 노릴 정확한 타깃 고객입니다. 단 한 명의 진지한 에이전트 트레이더가 실제 거래 볼륨을 만들어 냄을 보여줍니다. 지갑 계열(MetaMask, 37K users)이 사용자 수 기준으로는 지배하지만, 사용자당 볼륨은 그만 큽니다.

로드맵

1. 비차단 네트워크에서 라이브 스모크 테스트 — 2026-08-23 완료, 전 도구 통과

2. 빌더 코드 등록(polymarket.com → Settings → Builders), 확인 하실 금지하고 0 bps 설정한 뒤 ODDSRAIL_BUILDER_CODE 내보내기; 크기 작게 첫 어트리뷰된 주문 체결

3. Kalshi 두 번째 거래소 지원 — 2026-08-23 완료, 9개의 도구, 라이브 검증 완료

4. MCP 2.x 충돌이 해결된 후 두 시그널에 x402 유료 래퍼 적용

5. 레지스트리 등재: 공식 MCP 레지스트리(mcp-publisher, PyPI mcp-name: 마커), Smithery(공개 streamable-HTTP 엔드포인트와 scanner용 무료 도구 필요), Glama(glama.json)

등록 / 배포

• GitHub: <https://github .com/hmesutozsoy/oddsrail> (public, MIT)

• Glama: GitHub을 자동으로 목록; repo 루트의 glama.json이 메인트니셔 권한 확보.

• 공식 MCP 레지스트리: server.json은 준비됨. 배포 시 먼저 PyPI에 패키지가 있어야 합니다(레지스트리는 PyPI README의 mcp-name: io.github.hmesutozsoy/oddsrail 마커를 통해 소유권을 확인함). 이후 mcp-publisher login github && mcp-publisher publish 실행.

• Smithery: 공용 HTTPS streamable-HTTP 엔드포인트 필요 — 로컬 stdio 실행이 아니라 호스팅 상태가 되면 가능해집니다.