kachence/polymm 딥다이브
— 실제 돈을 굴린 Polymarket 차익거래 봇, 코드째로 공개되다

1프로젝트 한 줄 요약

먼저 무대를 이해하자. Polymarket은 "이 사건이 일어날까?"에 돈을 거는 예측시장(prediction market)이다. 각 결과는 0~1달러 사이의 "주식"처럼 거래된다. 예를 들어 "T1이 이번 경기를 이긴다" 토큰이 $0.60이면, 시장이 그 확률을 60%로 본다는 뜻이고, 실제로 T1이 이기면 그 토큰은 $1이 되고 지면 $0이 된다. polymm은 이 시장에서 사람 대신 24시간 지정가 주문을 걸고 관리하는 봇이다.

왜 "차익거래(arbitrage)"인가? 봇은 한 시장에서 방향에 베팅해 "맞히기"를 노리는 게 아니다. 두 시장의 가격 차이만 먹는다. 이상적으로는 A팀 토큰과 B팀 토큰을 합쳐 $1 미만에 사두면, 경기 결과와 무관하게 둘 중 하나가 반드시 $1이 되므로 그 차액이 확정 이익이 된다. 이게 polymm이 노리는 구조다. 물론 현실은 이 이상이 항상 성립하지 않고, 바로 그 균열이 이 프로젝트의 가장 흥미로운 이야기(4장·2장)로 이어진다.

2왜 주목받는가 — "지갑을 보여준다"는 정직함

GitHub에는 "Polymarket 봇 만들었다"는 저장소가 넘친다. 대부분은 돌려본 적 없는 코드와 장밋빛 README뿐이다. polymm이 눈에 띈 이유는 정반대의 태도 때문이다. 저자는 세 가지를 한꺼번에 공개했다.

• 실제 거래 기록 — 몇 달간 진짜 돈으로 돌렸고, 모든 체결이 온체인 공개 지갑 @b00k13에 남아 대조가 가능하다.
• 실제 코드 — 마케팅용 데모가 아니라, 저자가 돌린 그 봇 자체다(62개 모듈 + 56개 테스트).
• 실패의 부검 — "+EV(기대값 플러스)인 베팅들을 모아놨는데 왜 전체로는 돈을 잃었나"를 숫자와 함께 해부한 글까지 링크했다.

실제 손익 (저자 블로그 공개 수치)

여기서 이 프로젝트의 가장 값진 교훈이 나온다. 봇이 건 모든 방향성 베팅은 개별적으로는 +7% 이상 엣지를 가진, 이론상 이겨야 할 베팅이었다. 그런데 그것들을 모아놓으니 돈을 잃었다. 범인은 역선택(adverse selection)이다.

배울 점은 "평균적으로 이득인 전략"과 "실제로 체결되는 표본이 이득인 전략"은 다르다는 것. 이건 트레이딩뿐 아니라 모든 종류의 "선택되는 데이터"(설문 응답자, 병원에 온 환자, 광고를 클릭한 사용자)에 똑같이 적용되는 통계적 함정이다. polymm은 이 함정을 코드로 겪고 글로 남겼다.

3기술 스택 전체 지도

polymm의 기술 선택은 화려하지 않다. 오히려 그 절제가 배울 점이다. 무거운 프레임워크(Django·FastAPI 같은 것) 없이, 파이썬 표준 asyncio 하나로 열 개 남짓한 동시 루프를 돌려 실시간 트레이딩을 처리한다. 외부 의존성은 "꼭 필요한 것"만 골라 얇게 붙였다.

계층별 지도

4아키텍처 심화 — 차익거래 파이프라인과 반응형 두뇌

4-1. 큰 그림: 배당이 주문이 되기까지

봇의 핵심 데이터 흐름은 한 줄로 요약된다: 배당 소스 → Supabase → 기회 스캔 → 주문 실행 → Polymarket. 그리고 Polymarket에서 오는 두 개의 웹소켓(호가·체결)이 이 흐름에 실시간으로 피드백을 준다.

4-2. de-vig: 배당에서 "진짜 확률" 뽑아내기

모든 것의 출발점은 de-vig(디빅, 마진 제거)다. 스포츠 배당업체가 내건 배당에는 그들의 수수료(vig)가 숨어있어서, 배당을 그냥 확률로 바꾸면 합이 100%를 넘는다(그 초과분이 업체 마진). 이걸 벗겨내야 진짜 확률이 나온다.

polymm의 vig_removal.py는 이걸 가장 단순한 비례(proportional) 방법으로 처리한다 — 각 확률을 전체 합으로 나눠 100%에 맞춘다. 실제 코드의 계산을 숫자로 따라가 보자(배당 1.50 / 2.60인 경우):

배당:      A팀 1.50   ·   B팀 2.60
암시확률:  1/1.50 = 66.7%   ·   1/2.60 = 38.5%
합(overround) = 105.1%   →   vig = 5.1%   # 이 5.1%가 업체 마진

공정확률 = 각 확률 ÷ 105.1%
  A팀 fair = 66.7% / 105.1% = 63.4%
  B팀 fair = 38.5% / 105.1% = 36.6%   # 합 = 100%, 마진 제거 완료

이제 Polymarket을 본다. 만약 "A팀 승리" 토큰이 $0.55(=시장이 55%로 봄)에 팔린다면, 봇의 계산으로는 진짜 확률이 63.4%다. 그 차이 63.4% − 55% = 8.4%가 엣지(edge)다. 이게 기준선 min_edge = 7%를 넘으니 봇은 매수 주문을 건다. 만약 $0.58이었다면 엣지가 5.4%뿐이라 그냥 넘긴다.

4-3. 헤지: "누가 이기든 이득"을 잠그는 법

엣지를 보고 A팀을 샀다고 끝이 아니다. A팀이 지면 손해다. 그래서 한쪽이 체결되면 봇은 곧바로 반대편(B팀)도 사서 양쪽을 합쳐 $1 미만으로 만든다. 이게 hedge_finder.py의 일이다. 숫자로 보자:

# A팀 10주를 $0.55에 매수 체결
진입 비용 = 10주 × $0.55 = $5.50

# B팀 fair value($0.366)에 헤지 주문 → 체결되면
헤지 비용 = 10주 × $0.366 = $3.66

총비용   = $5.50 + $3.66 = $9.16   # 양쪽 10주씩 확보
정산금   = 누가 이기든 이긴 쪽 10주 × $1 = $10.00
확정이익 = $10.00 − $9.16 = $0.84  (약 +9.2%)   # 결과 무관

봇은 이 헤지가 최소 이익(min_profit, 기본 7%)을 못 넘기면 아예 걸지 않는다. 문제는 4-1에서 봤듯 헤지가 항상 체결되진 않는다는 것. 헤지가 안 붙으면 A팀 한쪽만 든 방향성 잔여분(residual)이 남고, 이 표본에 역선택이 작용해 -$3,184가 났다(2장).

4-4. 반응형 두뇌: 상태가 바뀌면 즉시 행동한다

polymm에서 가장 배울 만한 설계는 반응형(reactive) 이벤트 아키텍처다. 봇은 "15초마다 전부 다시 계산"하는 폴링에만 기대지 않는다. 대신 BotState가 상태 변화를 이벤트로 발행하고, ReactiveHandler가 그 이벤트를 듣고 즉시 결정한다.

state_events.py에 정의된 이벤트 종류를 보면 봇이 무엇에 반응하는지 한눈에 보인다:

세 종류의 봇이 이 공통 뼈대(BaseBot 추상클래스)를 공유한다: SportsBot(프리매치 e스포츠·럭비), LiveBot(경기 진행 중, 더 빠르고 빡빡한 기준), SpreadBot(놀랍게도 날씨 기온 마켓!). 전략별로 다른 부분(_scan_and_execute 등)만 갈아끼우고, 웹소켓·상태·헬스서버 같은 공통 인프라는 부모가 다 제공한다.

5디렉토리 구조 해부

polymm의 src/는 기능 계층별로 폴더를 나눈 교과서적 구조다. 4장의 데이터 흐름이 폴더 이름 순서와 거의 그대로 맞아떨어진다.

6학습 포인트 — 여기서 훔쳐올 설계

① 반응형 이벤트 아키텍처 (상태 → 이벤트 → 반응)

"상태를 바꾸는 쪽(BotState)"과 "상태 변화에 반응하는 쪽(ReactiveHandler)"을 분리하고, 그 사이를 이벤트(StateEvent)로 잇는다. 이 패턴은 트레이딩 봇뿐 아니라 실시간 대시보드·게임·협업 도구·알림 시스템 어디에나 쓰인다. 배울 것: "무엇이 바뀌었나"를 값이 아니라 이벤트 타입으로 표현하면, 반응 로직을 한곳에 모아 테스트하기 쉬워진다.

② 비동기 오케스트레이션 — 한 루프에 열 개의 일

base_bot.py는 asyncio로 스캔·감시·웹소켓·헬스체크를 동시에 돌리면서, 종료 시그널(SIGINT/SIGTERM)을 받으면 모든 태스크를 깔끔하게 취소한다. "Task was destroyed but it is pending!" 같은 흔한 async 잡음을 없애는 우아한 종료(graceful shutdown) 패턴은 그 자체로 좋은 교본이다.

③ 단일 진실원(Single Source of Truth)

match_id.py가 팀명 정규화를 독점하듯, "여러 곳에서 같은 판단을 하면 반드시 어긋난다 → 한 곳에서만"이라는 원칙. 설정값도 config.py 한 곳에 모아 세 봇이 공유한다. 규모가 커질수록 위력이 커지는 습관이다.

④ 정직한 관측 가능성(observability)과 부검

타임스탬프 찍힌 print 오버라이드, 텔레그램 실시간 알림, 그리고 "아무 공개 지갑에나 물려 손익을 뜯어보는" 분석 스크립트 5종. 특히 polymarket_attribution.py는 손익을 차익 vs 방향성 잔여분으로 쪼개, "어디서 벌고 어디서 잃었나"를 정확히 짚는다. 자기 시스템을 사후에 해부할 수 있게 만들어 두는 습관이 이 프로젝트의 백미다.

⑤ 점진적 재작성 — Rust를 "그림자"로 먼저 검증

속도 병목인 스캐너만 Rust로 다시 쓰되, 한 번에 갈아엎지 않는다. shadow_diff.py가 파이썬과 Rust를 동시에 돌려 결과를 비교(shadow mode)하고, 완전히 일치할 때만 Rust를 주력(primary)으로 승격한다. 리스크 큰 재작성을 안전하게 굴리는 실전 전략이다.

7하드웨어 / 시스템 요구사항

polymm은 계산이 무거운 프로젝트가 아니다. GPU도, 큰 메모리도 필요 없다. 진짜 요구사항은 속도(지연시간)와 외부 서비스 연결이다.

실행은 세 모드로 갈린다: python src/main.py(프리매치 스포츠), --live(라이브), --spread(날씨). 기본 주문 크기는 10주로 아주 작게 시작하도록 설정돼 있다 — 저자가 "규모를 키우기 전에 한동안 지켜보고, 부검 글부터 읽으라"고 당부하는 이유다.

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

프로젝트

• github.com/kachence/polymm — 저장소 원본(MIT)
• 저장소 내 README.md — 전략·아키텍처·손익 요약(먼저 읽을 것)
• 저자 블로그 kacho.io — 실제 숫자 · 역선택 부검 — ★ 2장의 근거

핵심 소스(먼저 읽을 파일)

• src/core/vig_removal.py — de-vig 수학(독립 실행 가능)
• src/state/state_events.py · reactive_handler.py — 반응형 두뇌의 뼈대
• src/execution/hedge_finder.py — 헤지 계산·수익성 검증
• src/bots/base_bot.py — 비동기 오케스트레이션·우아한 종료
• analytics/polymarket_attribution.py — 손익을 차익/방향성으로 쪼개는 분석

기반 기술 / 배경

• Python asyncio 공식 문서 — 비동기의 출발점(1주차)
• Polymarket 개발자 문서 · py-clob-client — 거래소 연동
• the-odds-api — 봇이 쓰는 배당 소스
• Supabase 문서 · pytest — 저장소·테스트 스택