폴리마켓 API 가이드 - 2026년에 첫 트레이딩 봇 만들기

33장 중 27장

간단 버전

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

1부: 세 가지 API

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

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

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

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

필요한 것

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

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 엔드포인트를 호출하지 않도록 하세요.

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

거래를 하려면 먼저 거래할 만한 시장을 찾아야 합니다. Gamma는 폴리마켓 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 쿼리 매개변수

5부: condition_id → token_id 매핑

이것은 폴리마켓 봇 개발에서 가장 큰 #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"일 수 있습니다 - 순서는 결정적이지만 시장마다 다릅니다.

파트 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가 있습니다. 더 큰 주문의 슬리피지를 추정하려면 호가창을 따라가며 목표 수량을 모두 체결할 때까지 명목가치를 누적하세요.

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: 참조용 봇 아키텍처

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

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

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

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

폴리마켓은 일반 유동성 리워드로 월 약 $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 - 폴리마켓 API를 위한 검증된 프로 팁

상황 → 조치 치트시트

다음은?

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