Build a Polymarket bot: scanner, sizing, execution, monitoring

이 가이드는 시장을 지속적으로 스캔하고, 기회를 사이징하며, CLOB를 통해 주문을 실행하고, 성과를 모니터링하는 Polymarket 봇을 구축하는 방법을 보여줍니다. 여기서는 Polymarket의 공개 API와 Relayer 모델을 사용해 구현할 수 있는 아키텍처와 개발 패턴에 집중합니다.

핵심 요점

• 봇을 네 개의 독립 서비스로 설계하세요: scanner, sizer, executor, monitor.
• 목록 조회와 주문 체결에는 Polymarket의 Gamma 및 CLOB API를, 실시간 북 업데이트에는 WebSocket을 사용하세요.
• 임의 속도의 실행에는 FAK 시장 주문을 선호하되 항상 슬리피지와 수수료를 고려하세요.
• 오라클 분쟁, 정산 지연, 예기치 않은 체결에 대비한 모니터링과 빠른 킬 스위치를 계측하세요.

이 구조를 택하는 이유

책임을 분리하면 트레이딩 시스템을 이해하고 운영하기가 쉬워집니다. scanner는 후보 엣지를 찾고, sizer는 엣지를 포지션으로 변환하며, executor는 CLOB를 통해 주문을 배치하고, monitor는 정확성과 안전을 보장합니다. 이 분리는 지연시간과 리스크를 독립적으로 확장, 테스트, 분석할 수 있게 합니다.

H2: 데이터 소스와 API

먼저 다음 Polymarket 엔드포인트를 서비스에 연결하세요:

• Gamma (시장 메타데이터): https://gamma-api.polymarket.com — markets, events, tags, series. after_cursor로 페이징하세요; offset은 피하세요.
• CLOB (오더북 및 트레이딩): https://clob.polymarket.com — 오더북 조회는 공개지만 트레이딩에는 API key + HMAC가 필요합니다. CLOB SDK가 주문 배치를 처리합니다.
• Market WebSocket (실시간 북): wss://ws-subscriptions-clob.polymarket.com/ws/market — book, price_change, best_bid_ask, tick_size_change를 구독하세요. 10초마다 PING이 필요합니다.
• Data API (포지션, 미결제약정): https://data-api.polymarket.com — 트레이드 이후 분석용입니다.

설계 노트: 효율적인 라이브 스캔을 위해 Gamma 목록과 WebSocket 피드를 결합하세요. Gamma의 레이트 리밋(/markets 제한 등)과 CLOB의 키 요구 사항을 준수하세요.

H2: Scanner — 후보 기회 찾기

기능

scanner는 전략에 맞는 기회를 발견합니다: intra-market 바이너리 스프레드, 다중 결과 합계, 또는 엔드게임 패턴 등. 상태 비저장(stateless)이면서 수평 확장 가능해야 하며, 원시 엣지 계산에 집중해야 합니다.

입력과 주기

• best_bid_ask와 tick 변경을 받으려면 custom_feature_enabled: true로 Market WebSocket을 구독하세요.
• 새로운 인스트루먼트를 처음 만날 때는 Gamma /markets로 백필해 메타데이터와 결과 목록을 가져오세요.
• 각 결과에 대해 소량의 인메모리 best asks/bids 뷰를 유지하세요.

엣지 계산

• 바이너리 intra-market: edge = 1.00 - (bestAsk(YES) + bestAsk(NO)). 양의 edge면 후보입니다.
• 다중 결과: edge = 1.00 - sum(bestAsk(결과들)).

임계치와 필터

• 최소 엣지 임계치(예: 구성된 센트 단위 초과)를 설정해 테이커 수수료와 실행 리스크를 커버하세요.
• 최소 유동성 검사: best ask의 깊이(depth)가 최소 체결 규모를 충족해야 합니다.
• 틱 사이즈 인지: tick_size_change 이벤트를 반영하세요 — 극단 가격 근처에서는 가격 단위가 $0.001로 조정될 수 있습니다.

H2: Sizing — 리스크 및 자본 배분

목표

사이징은 원시 엣지를 주문 계획으로 변환합니다: 각 결과마다 몇 주를 매수할지, 그리고 슬리피지를 제한하기 위해 주문을 어떻게 분산할지 결정합니다.

구성 요소

• 노출 상한: 마켓별 및 전체 pUSD 노출 한도.
• 깊이 제한 사이징: 매도 측의 연속 가격 레벨에서 사용 가능한 누적 볼륨을 계산합니다; 기대 슬리피지가 허용 범위 내인 볼륨까지만 사이징하세요.
• 수수료 여유: 거래 결정 전에 총 엣지에서 예상 테이커 수수료(카테고리에 따라 변동, 최대 1.8%까지)를 차감하세요.

실용적 패턴

• 보수적으로 시작하세요: 책을 제어하지 않는 한 단일 대규모 주문보다 여러 개의 작은 FAK 시장 주문을 선호하세요.
• CTF split/merge 흐름으로 완전 세트를 매수하는 경우 split/merge 가스(Relayer가 처리)와 틱 사이즈로 인한 반올림 가능성을 포함하세요.

H2: Executor — 주문 배치 및 체결 처리

주문 유형과 제약

• 주문 배치에는 CLOB 트레이딩 엔드포인트를 사용하세요: https://clob.polymarket.com. CLOB SDK와 Relayer가 지갑 배포, 승인, 주문 서명을 관리합니다.
• 속도를 위해 적절한 경우 FAK(Fill-And-Kill) 시장 주문을 사용하세요. FAK는 즉시 체결되거나 취소되며 남는 익스포저를 피하는 데 도움이 되지만 부분 체결될 수 있습니다.

실행 흐름

1. 거래 의도 준비: sizer가 반환한 결과 토큰 id와 목표 수량 목록.
2. 다중 결과의 완전 세트를 실행하는 경우 CTF split(완전 세트 민팅)을 수행하고 다리(legs)를 판매할 수 있습니다 — Relayer와 SDK가 CTF 작업을 추상화합니다.
3. Builder Program에 속해 있다면 적절한 귀속(attribution) 헤더와 함께 CLOB 트레이딩 API로 주문을 제출하세요.
4. WebSocket의 last_trade_price 및 best_bid_ask 업데이트나 CLOB 트레이드 응답에서 체결을 관찰하세요.

안전 및 대조

• 부분 체결을 추적하고 잔여 주문은 취소하거나 즉시 리프라이싱 하세요.
• 체결 후 Data API를 통해 온체인 CTF 잔액을 대조해 기대한 결과 토큰을 실제로 보유하고 있는지 확인하세요.
• 주문 재시도를 위한 idempotency 키와 논스 처리 로직을 구현하세요.

H2: 모니터링 및 운영 안전

모니터링 항목

• 체결률, 예상 대비 평균 슬리피지, 수수료 후 실현 엣지.
• WebSocket 업데이트와 주문 제출 사이의 지연(latency).
• 비정상 이벤트: UMA 분쟁, tick_size_change, 마켓플레이스 전반의 장애.

알람 및 킬-스위치

• 자동 소프트 킬: 순 실현 P&L이 임계치 아래로 떨어지거나 체결 슬리피지가 한도를 초과하면 신규 주문 배치를 일시 중단하세요.
• 하드 킬: UMA가 보유 포지션이 있는 마켓에 대해 분쟁을 보고하거나 Relayer가 정산 문제를 알리면 즉시 모든 트래픽을 중단하세요.

감사 로그 및 관측성

• 모든 주문 의도, 원시 마켓 스냅샷, 체결된 내역을 저장하세요. 이 로그를 포스트모템과 백테스팅에 사용하세요.
• 로그에 market id, condition_ids, request ids를 태그해 Gamma 및 CLOB 기록과 매칭하세요.

H2: Builder Program, 자격증명 및 레이트 리밋

귀속을 가진 주문 라우팅을 계획한다면 Builder Program에 가입하고 Polymarket 설정에서 키를 관리하세요. Builder 티어는 일일 Relayer 한도와 보상을 제어합니다. CLOB를 통해 트레이딩하려면 API key + HMAC가 필요하며 레이트 리밋과 Relayer 쿼터를 준수해야 합니다.

H2: 일반적인 리스크와 완화책

수학적 엣지가 보장된다고 가정하지 마세요. 고려해야 할 리스크:

• 결제(Resolution) 리스크: UMA 분쟁은 페이아웃을 일시정지하거나 변경할 수 있습니다.
• 슬리피지와 부분 체결: FAK는 부분 체결될 수 있으므로 잔여 익스포저를 계획하세요.
• 수수료: 테이커 수수료는 카테고리별로 달라 작거나 마진이 작은 엣지를 잠식할 수 있습니다(Geopolitics 카테고리는 수수료가 없습니다).
• 정산 타이밍: redeem/merge 타이밍 및 오라클 결의 지연이 자본을 묶을 수 있습니다.
• 스마트 계약 또는 Relayer 실패: 대체 방안과 사람에 의한 알림을 계측하세요.

이것이 거래에 미치는 영향

각 거래 단위를 작고 관찰 가능하며 리스크 한도 내에서 되돌릴 수 있도록 설계하세요. 보수적 사이징, 빠른 모니터링, 명확한 킬 조건이 꼬리 리스크를 줄입니다. Gamma와 CLOB 엔드포인트를 사용해 결정론적 마켓 상태를 얻고, 빠른 실행을 위해 FAK 주문을 선호하되 항상 실현된 슬리피지를 기대치와 비교하세요.

마무리

위 아키텍처는 Polymarket 트레이딩 봇을 구축하기 위한 실용적인 청사진을 제공합니다: 고처리량 스캐너, 보수적 사이저, CLOB와 Relayer를 이용한 견고한 실행기, 그리고 계층화된 모니터링. 작게 시작하고 적극적으로 계측한 뒤 실거래 데이터를 쌓으면서 사이징과 필터를 반복하세요.

자주 묻는 질문

어떤 API를 사용해 시장 목록과 실시간 북 데이터를 얻어야 하나요?

실시간 주문서와 best_bid_ask 이벤트는 wss://ws-subscriptions-clob.polymarket.com/ws/market을 사용하세요. 시장 메타데이터(/markets)는 https://gamma-api.polymarket.com을 사용하세요. 오더북 조회와 트레이딩은 https://clob.polymarket.com을 사용하세요; 조회는 공개지만 트레이딩에는 API key + HMAC가 필요합니다.

차익거래에 리밋 주문을 써야 하나요, 아니면 시장(FAK) 주문이 좋나요?

속도와 남는 익스포저 회피를 위해 FAK(Fill-And-Kill) 시장 주문이 흔히 사용됩니다. 부분 체결될 수 있으니 사이징과 대조 로직을 설계하세요. CLOB SDK는 FAK 시장 주문 생성용 헬퍼를 제공합니다.

거래 사이징 시 수수료는 어떻게 반영하나요?

거래 전에 총 엣지에서 예상 테이커 수수료를 차감하세요. 테이커 수수료는 카테고리별로 달라(현재 0%~1.8%) 작은 엣지를 잠식할 수 있습니다. 수수료, 예상 슬리피지 및 모니터링 버퍼를 포함한 순 엣지 임계값을 사용하세요.

실거래 봇에 필수적인 모니터링은 무엇인가요?

체결률, 실현 슬리피지, 지연(latency), UMA 분쟁 통지, tick_size_change 이벤트, Relayer 상태를 모니터링하세요. 큰 슬리피지, P&L 드로우다운, 오라클 분쟁에 대해 소프트 및 하드 킬-스위치를 구현하세요.

Builder Program을 통해 주문을 라우팅할 수 있나요?

예. Builder Program은 제3자가 귀속을 포함해 주문을 라우팅하고 빌더 수수료를 벌 수 있게 합니다. 티어는 일일 Relayer 한도와 보상을 제어하며 자격증명은 polymarket.com/settings에서 얻습니다.