polymarket-paper-trader

Tests

ClawHub

License: MIT

실제 예측 시장에서 AI 에이전트를 위한 무위험 gym — 실제 주문장, 공식 수수료, 검증된 체결 충실도. 의사 결정 지능을 연습하고 평가하며 벤치마킹하세요.

에이전트는 하루 종일 확률적 판단을 내립니다. Polymarket은 세계 최대의 예측 시장이며, 그곳의 주문장은 정직한 점수판입니다: 실제 돈, 실제 가격, 실제 결과. 하지만 에이전트에게 학습할 지갑을 줄 수는 없습니다. 그래서 이 프로젝트는 모든 에이전트에게 코더(coders)에게 SWE-bench가 제공했던 것과 같은 것을 제공합니다 — 판단에 결과가 따르고 점수를 받을 수 있는 충실한 환경입니다:

• 연습 (Practice) — 사용자의 에이전트는 실제 Polymarket 주문장을 상대로 1만 달러의 가상 돈으로 거래하며, 실제 거래소와 동일한 수수료 모델과 체결 메커니즘을 적용합니다.
• 평가 (Evaluate) — 이 저장소의 polymarket-benchmark 하네스(별도 설치 필요)는 예측 시장 의사 결정 세트(Brier score, calibration, alpha)를 사용하여 모든 모델에 점수를 매깁니다.
• 비교 (Compare) — 다중 계정 배틀과 리더보드를 통해 에이전트들을 서로 순위화합니다.
• 경쟁 (Compete) — Forecast Arena: AI 모델과 간단한 베이스라인들이 매일 동일한 Polymarket 질문을 예측하고 실제 결과(Brier score)에 의해 점수를 받는 실시간 공개 리더보드입니다. 이 저장소에서 실행 가능합니다 (enter your model · workflow · raw data).

agent-next의 일부 — 에이전트적인 세계를 구축합니다.

60초 데모

pip install polymarket-paper-trader
pm-trader init --balance 10000 # $10k 가상 자금으로 시작
pm-trader markets search "bitcoin" # 시장 찾기
...

설치하지 않으려면? uvx --from polymarket-paper-trader pm-trader-mcp를 실행하면 에이전트가 연결하는 MCP 서버가 작동합니다 (아래 Works with 참조).

이제 끝입니다. 사용자의 AI 에이전트는 무위험 환경에서 Polymarket을 거래할 수 있습니다.

설치하기

# pip를 통해 (CLI + MCP 서버)
pip install polymarket-paper-trader

...

Python 3.10 이상 필요.

연동되는 환경 (Works with)

ChatGPT / Claude.ai / 개인 에이전트에서 사용하기

HTTP만 지원하는 호스트의 경우 원격 모드가 존재합니다: pm-trader-mcp --transport streamable-http를 옵션으로 --auth-issuer, --auth-audience, 그리고 --resource-url 플래그와 함께 실행한 다음, 서버의 /mcp URL을 해당 호스트의 원격-MCP 설정에 추가합니다. 이는 기본적으로 비활성화되어 있으며, 운영하는 OAuth/OIDC 발급자(issuer)가 필요합니다. pm-trader는 이 발급자를 대상으로 베어러 토큰(bearer tokens)을 검증하고, 모든 인증된 주체에게 자체 가상 계정을 부여합니다. 추가할 호스팅 엔드포인트가 없으므로 사용자가 직접 서버를 실행해야 합니다. 설정, 위협 모델 및 환경에 대한 동등한 내용은 docs/remote-mcp.md을 참조하세요.

빠른 시작 (Quick start)

# $10k 가상 자금으로 초기화하기
pm-trader init --balance 10000

...

작동 방식 — 그리고 신뢰할 수 있는 이유

• 주문이 실제 장터에서 체결됩니다. 매수 주문은 가장 낮은 가격부터 실시간 호가(live ask levels)를 소진하며, 이는 실제 테이커 주문과 정확히 동일합니다. 슬리피지(slippage)는 실제로 발생하고 베이시스 포인트(basis points)로 보고됩니다.
• 수수료는 공식적인 매치별 곡선을 따릅니다. fee = C × rate × p × (1-p)이며, 소수점 5자리까지 반올림되고 메이커(makers)에게는 면제됩니다 (정확한 사양은 CHANGELOG 참조). 각 시장의 공시된 수수료 일정에 따라 체결된 레벨별로 부과되며, 근사치가 아닙니다.
• 가상 현금, 실제 규율. 대기 중인 매수 주문은 자금을 예약하고, 부분 체결 시 남은 잔액을 유지하며, 마감되거나 일시 중지된 시장에서는 거래를 거부하고, 지정가(limit prices)는 틱 사이즈(tick size)에 맞춰 검증됩니다.
• 해결(Resolution) 시 $1/주 지급. 시장이 마감될 때 resolve (또는 resolve --all) 명령을 실행하면 승자에게 실제와 같이 대금이 지급됩니다.
• 검증된 충실도. 실시간 테스트 스위트(live test suite)는 시뮬레이션된 체결이 시장이 실제로 호가했던 가격 범위 내에 위치하는지 (Data API v2 가격 기록) 그리고 수수료가 공식 곡선과 정확히 일치하는지를 검증합니다. 이는 CI에서 실제 API를 대상으로 실행됩니다.
• 상위 스트림 정렬(Upstream-aligned). 클라이언트는 현재의 감마(Gamma) / CLOB(Central Limit Order Book) / Data API 표면을 추적하며, 이는 실시간 프로브(live probes)에 의해 계약 검증됩니다.
• 다중 결과 시장(Multi-outcome markets) — 단순히 YES/NO가 아닌 모든 수의 결과를 처리할 수 있습니다.
• Kalshi도 가능합니다. kalshi:<티커> 슬러그를 전달하여 동일한 명령어와 도구로 Kalshi 시장을 가상 거래할 수 있습니다 (pm-trader buy kalshi:KXNBAGAME-26OCT16DENLAL-LAL yes 25); kalshi markets로 검색하세요. 수수료는 각 시리즈의 공시된 곡선을 따릅니다 (docs/kalshi.md).
• 핵심 패키지에는 100% 커버리지 게이트가 적용되며, 실제 API에 대한 엔드투엔드 테스트도 포함됩니다.

CLI 명령어

MCP 서버 — 에이전트가 할 수 있는 일

에이전트는 Model Context Protocol을 통해 다음 도구들을 받습니다.
서버는 또한 전체 트레이딩 플레이북(trading playbook)을 가지고 있습니다 — MCP 서버 instructions로, trading_playbook 프롬프트로, 그리고 skill://trading-playbook 리소스로 — 따라서 MCP 전용 클라이언트들(Cursor, Claude.ai 커넥터, Grok API 원격 MCP, ChatGPT 앱)은 숙련된 에이전트가 얻는 것과 동일한 안내를 받습니다 skill/polymarket-paper-trader/SKILL.md.

pm-trader-mcp  # stdio에서 시작

# 또는, 로컬 설치가 없는 경우:
...

Claude Code 설정에 추가하세요:

{
  "mcpServers": {
    "polymarket-paper-trader": {
...

원격 전송 (streamable-http)

HTTP만 사용하는 MCP 클라이언트의 경우, 서버를 --transport streamable-http로 실행하세요:

pm-trader-mcp --transport streamable-http --host 127.0.0.1 --port 8000
# 또는: npm-trader mcp --transport streamable-http --host 127.0.0.1 --port 8000

MCP 엔드포인트는 http://<호스트>:<포트>/mcp입니다. 호출자 간에는 격리가 없습니다 — 서버에 도달하는 모든 사람은 그 서버의 모든 가상 계좌를 공유합니다; 이는 공개적인 다중 사용자 서비스가 아니라 자체 호스팅 전용입니다. 인증 기능은 없습니다 이 전송 방식에서는 포트에 접근할 수 있는 누구든 노출된 모든 도구를 호출할 수 있습니다. backtest와 pk_battle (로컬 파일 읽기 + 로컬 전략 모듈 실행)는 stdio 전용이며 streamable-http로 제공될 때는 등록되지 않습니다.

Docker

docker build -t pm-trader-mcp .
docker run -p 127.0.0.1:8000:8000 -v pm-trader-data:/root/.pm-trader pm-trader-mcp

컨테이너 자체에 인증 기능이 없으므로, 실제 인증 프록시를 앞에 두지 않는 한 포트는 127.0.0.1로만 게시하세요 (위와 같이).

MCP 도구

전략 예시

examples/에 세 가지 즉시 사용 가능한 전략이 있습니다:

모멘텀 (examples/momentum.py)

YES 가격이 0.55를 상회할 때 매수하고, 0.70에서 이익을 실현하며, 0.35에서 손실을 제한합니다.

pm-trader strategy run examples.momentum.run

평균 회귀 (Mean reversion) (examples/mean_reversion.py)

YES 가격이 공정 가치(fair value) 0.50보다 12센트 이상 하락할 때 매수하고, 반등할 때 매도합니다.

pm-trader strategy run examples.mean_reversion.run

리밋 그리드 (Limit grid) (examples/limit_grid.py)

현재 가격보다 낮은 곳에 지정가(limit buy orders) 매수 주문을 배치하고, 그 위쪽에 이익 실현(take-profit sells) 매도 주문을 배치합니다.

pm-trader strategy run examples.limit_grid.run

Jev edge (examples/jev_edge.py)

"Jev vs the market": 각 이진 시장(binary market)에 대한 YES 확률을 Jev에게 요청하고, 선호하는 쪽에 매수하며, 수수료가 지배적인 [0.05, 0.95] 밖에 가격이 책정된 시장은 건너뜁니다 — pm-trader strategy run examples.jev_edge.run (설치 필요: pip install -e "benchmark").

자신만의 전략 작성하기

전략은 examples. 패키지에서 가져와집니다(허용 목록은 pm_trader/benchmark.py에 있습니다). 따라서 파일을 여기에 넣으세요:

# examples/my_strategy.py
from pm_trader.engine import Engine

...

pm-trader strategy run examples.my_strategy.run

과거 데이터로 백테스팅을 하려면:

def backtest_strategy(engine, snapshot, prices):
    """역사적 가격 스냅샷마다 호출됩니다."""
    if snapshot.midpoint > 0.6:
...

에이전트 평가: polymarket-benchmark

페이퍼 트레이더(paper trader)는 gym이며, 이 저장소의 polymarket-benchmark 패키지는 스코어보드입니다. 이는 별도의 설치가 필요합니다 (pm-trader CLI 일부가 아님 — pm-trader strategy는 거래 전략을 재실행하고(pm-trader benchmark는 여전히 별칭으로 남아있음), 위 CLI 표 참조):

pip install -e "benchmark[dev]"
cd benchmark && polymarket-benchmark run --model opencode/jev-1.13-free --market-set mini

두 모델을 맞붙여서 어떤 판단이 실제로 더 나은지 확인해 보세요. 시장 세트, 채점(Brier, calibration, alpha) 및 모델 설정: benchmark/README.md.

다중 계정 지원

독립된 계정으로 병렬 전략 실행하기:

pm-trader --account aggressive init --balance 5000
pm-trader --account conservative init --balance 5000

...

결과 공유하기

공유 가능한 통계 카드(stats card)를 생성하고 X/트위터에 게시하세요:

pm-trader stats --tweet    # X/트위터 최적화
pm-trader stats --card     # 텔레그램/디스코드용 마크다운
pm-trader stats --plain    # 일반 텍스트

AI 에이전트는 stats_card MCP 도구를 사용하여 카드를 자동으로 생성하고 공유할 수 있습니다.

정직한 한계점 (Honest limits)

• 페이퍼 트레이딩 전용. 지갑, 키, 실제 거래, 실제 돈은 절대 사용하지 않습니다. 해결(Resolution) 지급액은 1/공유당 시뮬레이션됩니다.
• 시뮬레이션 품질은 라이브 오더북 및 가격 기록과 비교하여 검증되지만, 실제 실행에는 대기열 위치, 지연 시간, 상대방 행동이 추가되며 이는 어떤 시뮬레이터도 보장할 수 없습니다.
• 실시간 시장 데이터는 Polymarket의 공개 API에 네트워크 접근이 필요합니다 (키 불필요).

OpenClaw / ClawHub

ClawHub에서 polymarket-paper-trader로 이용 가능합니다:

npx clawhub install polymarket-paper-trader

GitHub 봇

이슈나 PR에 /oc 또는 /opencode를 댓글로 달아주세요. 새 이슈는 분류(triage) 답변을 받고; 초안이 아닌 PR은 간략한 검토(shallow review)를 받습니다. 구현은 사람이 bot:implement를 추가하거나 /oc implement를 댓글로 달아야 시작됩니다 (FreeInference deepseek-v4-flash; 이 구현 푸시는 contents/issues/PRs에만 제한된 GITHUB_TOKEN을 사용합니다 — Actions 접근 불가 — 따라서 별도의 dispatch-tests 작업이 actions: write를 보유하며, 푸시된 브랜치 참조를 재검증하고, .github/workflows/test.yml이 해당 참조에서 기본 브랜치와 동일한지 확인한 후, gh workflow run Tests --ref를 실행합니다 — 토큰 푸시는 CI를 트리거하지 않습니다). 병합은 항상 수동입니다: 봇은 절대 병합하지 않으며, 필수 검사는 브랜치 보호에 의해 강제됩니다. Q&A / 분류 / 검토는 qwen3.6-35b에서 유지됩니다. 지갑이나 실제 거래는 없습니다. 세션도 공유되지 않습니다.

이 저장소의 다른 내용들

페이퍼 트레이더가 제품이며, 그 옆에 세 개의 보조 패키지가 존재합니다.

각 패키지에서 작업하는 방법은 CONTRIBUTING.md를, 릴리스 기록은 CHANGELOG.md를 참고하세요.

테스트 (Tests)

pytest -m "not live"             # 단위 + 통합 테스트, 100% 커버리지 게이트
pytest                           # 전체 스위트 (네트워크 필요)
pytest tests/test_e2e_live.py    # 라이브 API 통합 테스트만

라이선스 (License)

MIT