Polymarket API 가이드 - 2026년에 첫 트레이딩 봇 만들기

33장 중 27장

간단 버전

Polymarket은 세 가지 공개 API를 제공합니다: CLOB(거래), Gamma(시장 탐색), Data(분석)입니다. 공식 Python SDK는 py-clob-client 0.34.6입니다. 인증은 API 키 + ECDSA 서명을 사용하며, 주문은 Polygon 프록시 지갑을 통해 EIP-712로 서명됩니다. 속도 제한은 키당 대략 분당 60개 주문으로 제한됩니다. 새 개발자에게 가장 큰 함정은 Gamma와 CLOB 사이의 condition_id → token_id 매핑 문제입니다 - 이것부터 해결하면 나머지는 자연스럽게 풀립니다. Polymarket에서는 유동성 보상과 봇이 포착한 스프레드로 한 달에 대략 4000만 달러가 벌리며, 거의 전부 API 사용자에게 돌아갑니다.

서로 분리된 세 가지 서비스: 거래용 CLOB(9,000/10초 인증), 탐색용 Gamma(4,000/10초 공개), 과거 분석용 Data(1,000/10초 공개).

1부: 세 가지 API

Polymarket는 세 가지 서로 다른 서비스로 역할을 깔끔하게 분리합니다. 각 작업에 맞는 올바른 API를 사용하면 봇을 빠르고 단순하게 유지하면서 rate limit 안에서 운영할 수 있습니다.

일반적인 봇 루프는 Gamma로 시장을 찾고, CLOB로 호가창을 가져오고 거래를 체결하며, Data로 전략 성과를 오프라인에서 백테스트합니다. Gamma는 "카탈로그", CLOB는 "거래소", Data는 "창고"라고 생각하면 됩니다.

L1은 chainId 137로 "ClobAuthDomain" EIP-712 구조체에 서명하여 자격 증명을 도출합니다. L2 HMAC-SHA256은 이후의 모든 요청에 POLY_SIGNATURE 헤더로 서명합니다.

Part 2: 인증 및 프록시 지갑 모델

Polymarket은 메인 지갑의 개인 키로 거래에 서명하지 않습니다. 대신 Gnosis Safe 스타일의 프록시 지갑을 사용합니다. 메인 지갑이 프록시에 권한을 부여하고, 프록시가 Polygon에서 모든 거래를 실행합니다. API 봇은 그 프록시와 통신합니다.

필요한 것

• API 키 - Polymarket 설정 → 개발자에서 생성
• 개인 키 - 트레이딩 지갑의 키입니다. (메인 MetaMask 시드 구문이 아님)
• 자금 제공자 주소 - 프록시 지갑 주소입니다. (설정 → 지갑에 표시됨)
• 체인 ID - 137 (Polygon 메인넷)
• 서명 유형 - 1 (POLY_PROXY, 일반 사용자용 표준)

Magic-link 계정은 서명 유형 1(POLY_PROXY), 브라우저 지갑 프록시는 유형 2(GNOSIS_SAFE), 직접 키는 유형 0(EOA)입니다. 유형 1과 2에는 자금 제공자가 필요합니다.

3부: py-clob-client 설치하기

공식 Python SDK는 처음부터 첫 주문까지 가장 빠르게 가는 방법입니다. 이번에는 2026년 4월 기준 최신 버전인 0.34.6을 사용합니다.

# 먼저 가상 환경을 생성합니다
python3 -m venv venv
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows

# SDK 설치
pip install py-clob-client==0.34.6 requests websocket-client python-dotenv

기본 클라이언트 설정

import os
from dotenv import load_dotenv
from py_clob_client.client import ClobClient
from py_clob_client.constants import POLYGON

load_dotenv()

client = ClobClient(
 host="https://clob.polymarket.com",
 key=os.environ["POLY_PRIVATE_KEY"],
 chain_id=POLYGON, # 137
 signature_type=1, # POLY_PROXY
 funder=os.environ["POLY_FUNDER"],
)

# 한 번만: API 인증 정보를 생성하고 캐시합니다
client.set_api_creds(client.create_or_derive_api_creds())

create_or_derive_api_creds() 호출은 개인 키로 메시지에 서명한 뒤, 이를 API 키, 비밀키, 패스프레이즈와 교환합니다. 처음 실행한 뒤에는 이 값들을 .env에 캐시해 두어 시작할 때마다 derive 엔드포인트를 호출하지 않도록 하세요.

Gamma /markets는 outcomePrices, clobTokenIds, volume24hr, tags를 반환합니다. 기본 봇 스캐너 쿼리로 tag_slug + order=volume24hr를 사용하세요.

4부: Gamma를 통해 시장 발견하기

거래를 하려면 먼저 거래할 만한 시장을 찾아야 합니다. Gamma는 Polymarket UI에 표시되는 모든 내용을 담은 JSON을 반환합니다: 질문, 결과, 가격, 24시간 거래량, 만기, 태그, 이미지.

import requests

resp = requests.get(
 "https://gamma-api.polymarket.com/markets",
 params={
 "active": "true",
 "closed": "false",
 "tag_slug": "politics",
 "limit": 20,
 "order": "volume24hr",
 "ascending": "false",
 },
 timeout=10,
)
resp.raise_for_status()
markets = resp.json()

for m in markets:
 print(f"{m['slug']:50} Yes ${float(m['outcomePrices'][0]):.3f} Vol24h ${m.get('volume24hr', 0):,.0f}")

유용한 Gamma 쿼리 매개변수

Gamma는 conditionId를 노출합니다(시장당 1개). CLOB는 token_id로 거래합니다(결과당 1개). clobTokenIds는 결과와 인덱스가 맞춰진 JSON 인코딩 문자열 배열입니다.

5부: condition_id → token_id 매핑

이것은 Polymarket 봇 개발에서 가장 큰 #1 고충입니다. Gamma는 condition_id를 반환합니다(시장당 하나). CLOB 거래는 token_id를 사용합니다(결과당 하나). 항상 둘 다 필요합니다.

# 각 Gamma 시장 객체에는 'clobTokenIds'가 포함되어 있습니다 - JSON 문자열 배열
import json

market = markets[0]
token_ids = json.loads(market['clobTokenIds']) # ['7410...', '1120...']
yes_token = token_ids[0] # 첫 번째 결과
no_token = token_ids[1] # 두 번째 결과

# 대안: condition_id를 사용해 CLOB에 직접 문의
info = client.get_market(condition_id=market['conditionId'])
yes_token = info['tokens'][0]['token_id']

결과 순서 주의사항

Gamma의 outcomes 배열과 clobTokenIds 배열은 인덱스가 일치합니다. 항상 0번 인덱스가 "Yes"라고 가정하지 말고 결과 라벨을 읽으세요. 다중 결과 시장(NegRisk, Oscars, 선거)에서는 0번 인덱스가 "Kamala Harris" 또는 "Taylor Swift"일 수 있습니다 - 순서는 결정적이지만 시장마다 다릅니다.

호가창은 매수호가 내림차순, 매도호가 오름차순으로 반환됩니다. 시장가와 유사한 FAK를 보내기 전에 각 레벨을 따라가며 어떤 목표 명목가치든 체결가를 추정하세요.

파트 6: 호가창 읽기

book = client.get_order_book(token_id=yes_token)

best_bid = float(book.bids[0].price) if book.bids else None
best_ask = float(book.asks[0].price) if book.asks else None
mid = (best_bid + best_ask) / 2 if best_bid and best_ask else None
spread = best_ask - best_bid if best_bid and best_ask else None

print(f"Bid {best_bid} Ask {best_ask} Mid {mid:.4f} Spread {spread:.4f}")

호가창은 정렬된 배열로 반환됩니다(bid는 내림차순, ask는 오름차순). 각 레벨에는 price와 size가 있습니다. 더 큰 주문의 슬리피지를 추정하려면 호가창을 따라가며 목표 수량을 모두 체결할 때까지 명목가치를 누적하세요.

GTC는 호가창에 남아 있고, GTD는 타임스탬프에 따라 자동 취소되며, FOK는 전량 체결 아니면 취소이고, FAK는 지정가에서 가능한 만큼 체결하고 나머지는 취소합니다.

7부: 주문 넣기

지정가 주문 (GTC - 기본값)

from py_clob_client.clob_types import OrderArgs, OrderType

args = OrderArgs(
 token_id=yes_token,
 price=0.45,
 size=100, # 주식 수이며, 달러가 아닙니다. 0.45달러에 100주 = 최대 비용 45달러.
 side="BUY",
)
signed_order = client.create_order(args)
response = client.post_order(signed_order, OrderType.GTC)
print(response)

create_order 호출은 개인 키로 EIP-712 구조화된 메시지에 서명합니다. post_order는 이를 CLOB에 제출합니다. 원시 개인 키를 전송하지는 않으며 - 서명된 주문만 전송합니다.

주문 유형

취소

# 단일 주문
client.cancel(order_id="0xabc...")

# 특정 시장의 모든 주문 취소
client.cancel_market_orders(market=market['conditionId'])

# 최후 수단: 전부 취소
client.cancel_all()

8부: WebSocket 스트리밍

매초 Gamma를 폴링하는 것은 비효율적이며, 곧 속도 제한에 걸리게 됩니다. WebSocket 피드는 실시간 호가창과 거래 업데이트를 서브초 지연으로 스트리밍합니다.

import json, websocket

WS_URL = "wss://ws-subscriptions-clob.polymarket.com/ws/market"

def on_open(ws):
 ws.send(json.dumps({
 "type": "market",
 "assets_ids": [yes_token, no_token],
 }))

def on_message(ws, message):
 event = json.loads(message)
 if event.get("event_type") == "price_change":
 print(f"{event['market']} {event['side']} {event['price']} size={event['size']}")

ws = websocket.WebSocketApp(
 WS_URL,
 on_open=on_open,
 on_message=on_message,
)
ws.run_forever(ping_interval=20)

두 가지 피드가 있습니다. /market 피드(공개 호가창 + 거래)와 /user 피드(인증된, 자신의 주문 및 체결 이벤트)입니다. 운영 봇은 일반적으로 둘 다에 연결하고, 연결이 끊기면 자동으로 재연결하며, 현재 호가 상태의 진실된 출처로 WebSocket을 사용합니다.

파트 9: 속도 제한 및 백오프

HTTP 429에 도달하면 서버는 Retry-After 헤더를 반환합니다. 지터가 포함된 지수 백오프를 구현하세요:

import random, time

def post_with_backoff(fn, *args, max_retries=6):
 for attempt in range(max_retries):
 try:
 return fn(*args)
 except Exception as e:
 if "429" in str(e):
 sleep = (2 ** attempt) + random.random()
 time.sleep(min(sleep, 30))
 continue
 raise
 raise RuntimeError("Too many retries")

파트 10: 참조용 봇 아키텍처

모든 견고한 Polymarket 봇은 같은 6개 구성요소를 갖습니다. 각 요소를 독립된 모듈로 만들고, 서로 느슨하게 결합되게 유지하세요.

파트 11: 일반적인 실패 모드

• 오래된 WebSocket 데이터 - 자산별 마지막 메시지 시간을 추적하세요. 활성 시장에서 30초 이상 업데이트가 없으면 REST 새로고침을 강제로 수행하세요.
• Nonce 충돌 - py-clob-client가 주문 nonce를 처리해 주지만, 직접 서명기를 구현한다면 모든 주문마다 nonce를 증가시키세요.
• 잔액 부족 - 주문을 넣기 전에 항상 USDC 잔액을 확인하세요. 호가창에는 주문이 보이더라도 매칭 단계에서 거절될 수 있습니다.
• 시장 일시중지 또는 정산 중 - 거래 전에 market.active && !market.closed를 확인하세요. 정산 전후 몇 초 동안 Gamma 업데이트는 CLOB보다 늦을 수 있습니다.
• NegRisk 어댑터 불일치 - 다중 결과 시장은 별도의 NegRisk 어댑터를 통해 라우팅됩니다. SDK가 처리하지만, 주문이 올바른 거래 장소로 갔는지 확인하세요.

파트 12: API를 통한 유동성 리워드

Polymarket은 일반 유동성 리워드로 월 약 $5M, 스포츠 전용 리워드로 월 $5M+를 운영합니다(see 유동성 리워드). 대부분은 수천 개의 시장에서 촘촘한 양방향 호가를 유지할 수 있는 API 기반 마켓 메이커에게 흘러갑니다.

리워드 공식은 중간가 근처의 주문, 크기, 호가창 체류 시간을 보상합니다. 최소한의 마켓 메이킹 루프는 다음과 같습니다:

1. 대상 시장의 호가창 읽기
2. 공정한 중간가 계산하기(예: 양쪽 상위 3단계의 VWAP)
3. mid − spread_target/2에 bid를, mid + spread_target/2에 ask를 제출
4. 모든 WebSocket 업데이트마다, 호가가 목표에서 한 틱 이상 벗어나면 재가격 책정
5. 호가창이 얇아지거나 뉴스가 터지면 취소하고 종료

파트 13: 프로덕션으로 가기

• 호스팅: 유럽 또는 US-East의 월 $6 VPS(Hetzner, DigitalOcean)면 대부분의 봇에 충분합니다. 10ms 미만 지연이 필요하면 Polygon RPC와 코로케이션하세요.
• RPC: 안정적인 Polygon RPC를 위해 Alchemy, Infura, 또는 QuickNode를 사용하세요. 분당 수백 건의 주문을 넣기 전까지는 무료 요금제로도 충분합니다.
• 모니터링: 지표는 Prometheus + Grafana로, 알림은 Telegram 봇으로 처리하세요. 보내는 모든 주문 ID와 받는 모든 체결을 기록하세요.
• 백업: 매분 상태를 영구 저장하세요. VPS가 체결 도중 죽더라도, 수동 정리 없이 몇 초 안에 재개할 수 있어야 합니다.
• 세금: 로거는 감사 추적이기도 합니다 - 세금 가이드를 보세요.

파트 14 - Polymarket API를 위한 검증된 프로 팁

상황 → 조치 치트시트

다음은?

• 도구 및 리소스 - API를 보완하는 제3자 대시보드, 분석, 데이터 피드
• 고급 전략 - 봇에 적합한 다중 레그 차익거래와 옵션 유사 구조
• 유동성 보상 - 마켓 메이킹 리베이트를 얻기 위한 정확한 공식
• 호가창 가이드 - 코드로 접근하기 전에 호가창을 읽는 것에 대한 더 깊은 직관
• 용어집 - 이 가이드의 모든 용어에 대한 쉬운 영어 정의