Polymarket API 크리덴셜을 생성해 Python 파일에 붙여넣고, 자는 동안 Claude가 내 실제 돈을 거래하게 했습니다. 여기 전체 코드, 수학, 실수, 그리고 결과가 있습니다.

이게 가능하다는 걸 깨달은 순간

어느 늦은 밤, Polymarket 개발자 문서를 읽다가 모든 것을 바꾼 문장을 봤습니다: “L2 인증은 L1 인증에서 생성된 API 크리덴셜을 사용합니다. 주문 배치, 취소, 계정 데이터에 사용됩니다.”

Polymarket은 완전히 문서화된 공개 API가 있습니다. 직접 키를 생성할 수 있습니다. 스크립트에서 프로그래매틱하게 주문할 수 있습니다. 자신의 프로필로 봇을 실행할 수 있습니다. 신청 과정 없음, 대기자 명단 없음, 특별 권한 없음 — 이 플랫폼은 1일 차부터 이걸 위해 설계되었습니다.

공식 Python 클라이언트는 GitHub에 있습니다. 이름은 py-clob-client. Polymarket이 직접 관리합니다. 2,500줄 미만의 코드. 딱 한 가지 일을 합니다: 스크립트에서 계정으로 거래할 수 있게 해줍니다.

두 가지 선택지가 있었습니다. 매일 일반 트레이더처럼 수동으로 시장을 클릭할 것인가? 아니면 키를 생성하고, 봇을 작성하고, Claude가 하게 둘 것인가?

3일 후, 라이브 봇이 내 계정을 거래하고 있었습니다. 2주 후, $120 의시작자본으로$ 26,880의 수익을 올렸습니다. 878회 거래. 14일. 실제 USDC.

이것은 완전한 연습입니다. 코드 포함. 숨긴 것 없음.

시작하기 전: 이것은 나에게 작동했습니다. 당신에게는 똑같이 작동하지 않을 것입니다. 시장은 변하고, 코드는 깨지고, 돈을 빨리 잃을 수 있습니다. 전체 글을 읽으세요. 먼저 읽기 전용 모드로 테스트하세요. 킬 스위치(Kill Switch)를 설정하세요.

A부터 Z까지 직접 구축하기

이하 모든 것은 완전한 운영 가이드입니다. 각 단계를 순서대로 따르고 위험 관리 설정을 건너뛰지 마세요. 하루 끝날 때까지 실행 중인 봇이 있을 것입니다. 4단계와 5단계를 건너뛰면 돈을 잃습니다. 이것은 헷지가 아닙니다. 그냥 일어나는 일입니다.

코드를 만지기 전에 전체 가이드를 읽으세요. 킬 스위치 설정. 먼저 읽기 전용 모드로 테스트. 소액 사용. API는 강력하고 플랫폼은 권한 없음 — 실수를 환불해줄 지원팀 없음.

코드 전 코드 3단계

1단계 - Polymarket 지갑 설정

polymarket.com/?r=ecosystem에 가서 MetaMask 또는 Coinbase Wallet 연결. Polygon 네트워크를 통해 USDC로 자금 충전 — Ethereum 메인넷이 아닙니다, 다른 체인도 아닙니다. Polygon은 Polymarket이 실행되는 네트워크이며, 잘못된 네트워크 사용은 자금에 접근할 수 없게 됨을 의미합니다.

2단계 - API 크리덴셜 생성

docs.polymarket.com로 가서 API 섹션 탐색, 지갑으로 메시지 서명하여 CLOB API 키 생성. 이것은 비밀번호 없이 소유권을 증명합니다. 개별 거래 트랜잭션에 서명하기 위해 지갑의 프라이빗 키도 필요합니다. 이 프라이빗 키를 로컬 환경 변수에 저장 — 봇 스크립트에 하드코딩하지 말고, GitHub에 커밋하지 말고, 누구와도 공유하지 마세요. 유출된 프라이빗 키는 지갑 탈취를 의미합니다. 운영 보안이 진짜로 중요한 유일한 단계입니다.

3단계 - Claude에게 봇 구축 프롬프트

Claude.ai 또는 Claude Code 열기. 이 글 뒤쪽의 프롬프트 구조는 일관되게 작동하는, 적절한 오류 처리, 속도 제한, 페이퍼 모드가 내장된 잘 구조화된 Python 봇을 생성했습니다. Claude Code가 선호됨 — 파일 시스템을 읽고, 코드를 실행하고, 오류를 자동으로 반복할 수 있기 때문입니다(창 간 복사-붙여넣기 불필요). 하지만 Claude.ai도 작동함 — 의존성을 직접 설치하고 코드를 실행해야 함.

이 가이드에서 다룰 내용

§03 실제로 필요한 3개 API (Gamma, CLOB, Data)
§04 signature_type 함정 (모두가 4시간씩 낭비하는 실수)
§05 설정 — 0에서 인증까지 15분
§06 Gamma API로 시장 찾기
§07 주문서 읽기 (VWAP — 절대 맹목적으로 거래하지 마세요)
§08 첫 실제 주문 배치 + 4가지 주문 유형 설명
§09 완전한 bot.py — 내 실제 운영 루프
§10 14일간 실행 — 실제 숫자, 실제 실수
§11 일반적인 오류와 정확한 수정법
§12 완전한 GitHub 저장소 목록 — 공식 + 커뮤니티

실제로 필요한 3개 API

Polymarket은 3개의 별도 API와 1개의 WebSocket 레이어를 노출합니다. 대부분의 튜토리얼은 이들을 혼동합니다. 나에게 클릭된 멘탈 모델:

4개 기본 URL (암기하세요):

# 모든 Polymarket API 기본 URL
CLOB = "https://clob.polymarket.com"  # 주문 + 가격 + 계정
GAMMA = "https://gamma-api.polymarket.com"  # 시장 발견
DATA = "https://data-api.polymarket.com"  # 포지션, P&L, 히스토리
WS_CLOB = "wss://ws-subscriptions-clob.polymarket.com/ws/"
WS_LIVE = "wss://ws-live-data.polymarket.com"  # 암호화폐 가격 스트림

Gamma API는 읽기 전용이며 인증 불필요. 시장을 탐색하고 토큰 ID를 가져오는 데 사용. CLOB API는 실제 거래가 일어나는 곳 — 주문서 읽기 및 주문 배치. Data API는 당신이 한 일을 추적하는 용도.

봇에는 딱 2개만 필요: 시장 찾기 위한 Gamma, 거래하기 위한 CLOB. Data API는 대시보드가 필요하지 않으면 선택사항.

모두가 4시간씩 낭비하는 signature_type 함정

이것은 Polymarket API에서 가장 혼란스러운 부분이며, 나는 이것을 알아내느라 밤을 지샀습니다.

Polymarket에는 3가지 다른 지갑 유형이 있습니다. 각각 다른 서명 구성이 필요합니다. 이걸 틀리면 다른 단서 없이 INVALID_SIGNATURE를 반환합니다.

이메일 또는 Magic Link로 가입 → signature_type=1 사용. MetaMask 연결 → signature_type=2 사용. Funder 주소는 MetaMask 주소가 아닌 Polymarket 프로필에 표시된 주소입니다.

Funder 주소 찾는 법: 로그인 후 polymarket.com/settings로 이동. 거기 표시된 주소가 당신의 funder. 정확히 복사하세요. 실수로 MetaMask 주소를 전달하면 Invalid Funder Address를 받고 몇 시간을 디버깅하며 낭비하게 됨.

설정 — 0에서 인증까지 15분

내가 실제로 실행한 정확한 순서입니다. 각 블록을 그대로 복사하세요.

1단계 - 공식 클라이언트 설치

# Python 3.9+ 필요
pip install py-clob-client python-dotenv websockets requests
# 프로젝트 폴더 만들기
mkdir polymarket-bot && cd polymarket-bot
touch .env bot.py

2단계 - 프라이빗 키 얻기

MetaMask 사용 시: 프라이빗 키 내보내기 (Account Details → Show Private Key). 이메일/Magic 사용 시: polymarket.com에서 적어도 한 번 거래 후 reveal.magic.link/polymarket 방문.

.env 파일에 넣으세요. 코드에 직접 붙여넣지 마세요. 커밋하지 마세요.

# 이 파일을 절대 커밋하지 마세요. .gitignore에 .env 추가.
PK=0x_your_64_character_hex_private_key_here
FUNDER=0x_your_polymarket_proxy_address_from_settings
SIGNATURE_TYPE=2  # MetaMask는 2, 이메일은 1

3단계 - 인증 및 API 크리덴셜 파생

Polymarket API는 2단계 인증 시스템 사용. L1은 지갑 소유 증명 (1회성). L2는 모든 주문에 HMAC 키 사용. 클라이언트가 둘 다 처리.

import os
from dotenv import load_dotenv
from py_clob_client.client import ClobClient
 
load_dotenv()
 
client = ClobClient(
    host="https://clob.polymarket.com",
    key=os.getenv("PK"),  # 프라이빗 키
    chain_id=137,  # Polygon
    signature_type=int(os.getenv("SIGNATURE_TYPE")),
    funder=os.getenv("FUNDER")  # 프록시 지갑
)
 
# API 크리덴셜 파생 + 저장. 한 번 실행.
client.set_api_creds(client.create_or_derive_api_creds())
 
# 작동 확인:
print("Server time:", client.get_server_time())
print("Auth OK")

python auth.py 실행. 서버 시간이 출력되면 인증된 것입니다. 출력된 api_key, secret, passphrase를 저장하세요. 필요하게 됨.

시장 찾기 - Gamma API 트릭

거래하기 전에 토큰 ID가 필요합니다. 각 시장에는 두 개 — YES용, NO용. 78자리 문자열로 아무것도 아닌 것처럼 보입니다. Gamma API에서 가져옵니다.

import requests
 
GAMMA = "https://gamma-api.polymarket.com"
 
def get_active_markets(min_volume=10000, limit=20):
    """실제 유동성을 갖춘 시장 찾기, 거래량순 정렬."""
    r = requests.get(f"{GAMMA}/markets", params={
        "active": True,
        "closed": False,
        "volume_num_min": min_volume,
        "order": "volume",
        "ascending": False,
        "limit": limit,
    })
    return r.json()
 
for mkt in get_active_markets():
    # clobTokenIds는 리스트 — 인덱스 0은 YES, 1은 NO
    yes_id, no_id = mkt["clobTokenIds"]
    print(f"{mkt['question'][:60]}:60} | vol: ${mkt['volumeNum']:,.0f}")
    print(f" YES token: {yes_id}")

토큰 ID 혼란: 토큰 ID는 Gamma API에서 옴니다, CLOB API가 아닙니다. GET /markets의 clobTokenIds 필드 사용. 리스트는 보통 [YES, NO]지만 항상 outcomes 필드와 대조 확인. 모두가 처음에 당황하는 부분.

주문서 읽기 - 베팅 전 필수

두 가지 방식으로 주문 배치 가능. **시장 주문(Market Order)**은 사용 가능한 가격에 즉시 체결 — 호가가 얇으면 위험. **지정가 주문(Limit Order)**은 선택한 가격에 주문서에 대기 — 더 안전하지만 체결 안 될 수도.

항상 먼저 주문서를 읽으세요. 항상.

def analyze_book(client, token_id, your_size_usdc=10):
    book = client.get_order_book(token_id)
    midpoint = client.get_midpoint(token_id)
    best_bid = float(book.bids[0].price) if book.bids else 0
    best_ask = float(book.asks[0].price) if book.asks else 1
    spread = best_ask - best_bid
    
    # 내 사이즈에서 호가 측 깊이가 얼마나 깊은가?
    filled, cost = 0, 0
    for ask in book.asks:
        p, q = float(ask.price), float(ask.size)
        take = min(q, your_size_usdc/p - filled)
        cost += take * p
        filled += take
        if filled * p >= your_size_usdc: break
    vwap = cost / filled if filled else 0
    
    return {
        "midpoint": midpoint, "spread": spread,
        "best_ask": best_ask, "vwap_at_size": vwap,
        "slippage_pct": (vwap - best_ask) / best_ask * 100
    }

왜 중요한가: 주문서에 호가 측에 $50 만있고$ 200어치 사려 하면, 4개 가격 레벨을 뚫고 지나가며 예상보다 훨씬 나쁜 가격 지불. 위의 VWAP 함수는 실제 지불할 가격 알려줌 — 헤드라인 가격이 아님.

첫 실제 주문 배치

이것은 모든 것이 실제가 되는 순간. 아래 코드는 처음에 아주 소액으로 실행.

from py_clob_client.clob_types import MarketOrderArgs, OrderType
from py_clob_client.order_builder.constants import BUY, SELL
 
# 주문 전 항상 책 확인
analysis = analyze_book(client, token_id, your_size_usdc=5.00)
 
if analysis["slippage_pct"] > 2.0:
    print("Skipping — slippage too high")
else:
    order = MarketOrderArgs(
        token_id=token_id,
        amount=5.00,  # 달러, 주식 아님
        side=BUY,
        order_type=OrderType.FOK  # fill-or-kill
    )
    signed = client.create_market_order(order)
    resp = client.post_order(signed, OrderType.FOK)
    print(f"Order ID: {resp['orderID']}")
    print(f"Status: {resp['status']}")

알아야 할 4가지 주문 유형

내 봇은 진입 시 FOK 사용 (나쁜 포지션으로 부분 체결되는 것 방지), 목표가 도달 시 GTC 사용.

완전한 봇 — 내 실제 메인 루프

이것이 내 봇의 핵심. 전략: BTC 상승/하락 5분 시장. Polymarket은 BTC 종가 기준 5분마다 해결되는 단기 창을 운영. 봇은 Binance 감시, 종료 10초 전 결정, 체결-or-kill 베팅.

import asyncio, time, requests
from py_clob_client.clob_types import MarketOrderArgs, OrderType
from py_clob_client.order_builder.constants import BUY
 
async def trading_loop(client, starting_balance):
    bal = starting_balance
    day_start = bal
    trades = wins = 0
    
    while True:
        # ── 킬 스위치 — 하루에 20% 이상 잃지 마세요 ──
        if bal < day_start * 0.80:
            print("KILL: -20% daily loss. Stopping."); break
        
        # ── 활성 5분 BTC 시장 찾기 ──
        now = int(time.time())
        window_start = now - (now % 300)
        close_time = window_start + 300
        seconds_left = close_time - now
        
        if seconds_left > 15:
            await asyncio.sleep(1); continue
        
        # ── Binance에서 현재 BTC 가격 가져오기 ──
        btc = float(requests.get(
            "https://api.binance.com/api/v3/ticker/price?symbol=BTCUSDT"
        ).json()["price"])
        
        # ── 스트라이크 가격(창 시작 시 가격) 가져오기 ──
        strike = get_strike_price(window_start)
        
        # ── 안전 마진으로 방향 결정 ──
        if btc > strike * 1.0008:
            direction = "UP"
        elif btc < strike * 0.9992:
            direction = "DOWN"
        else:
            print("Skip — too close to flat"); continue
        
        # ── 토큰 ID + 주문서 읽기 ──
        token_id = find_btc_market(window_start, direction)
        book = analyze_book(client, token_id, 20)
        
        # ── 가격이 이미 너무 높으면 건너뛰기 (엣지 없음) ──
        if book["vwap_at_size"] > 0.85:
            print("Skip — price too high"); continue
        
        # ── 베팅 사이즈 결정 (Kelly fraction) ──
        edge = 0.92 - book["vwap_at_size"]  # 예상 승리 확률
        size = min(bal * edge * 0.5, bal * 0.08)  # half-Kelly, 8% cap
        if size < 5: continue  # Polymarket 최소
        
        # ── 실행 ──
        order = MarketOrderArgs(
            token_id=token_id, amount=size,
            side=BUY, order_type=OrderType.FOK
        )
        signed = client.create_market_order(order)
        resp = client.post_order(signed, OrderType.FOK)
        trades += 1
        print(f"#{trades} {direction} ${size:.2f} → {resp['status']}")
        
        # ── 해결 대기 ──
        await asyncio.sleep(320)
        # Then update balance from Data API...

내 계정을 구한 두 줄: if bal < day_start * 0.80: break (킬 스위치) and if size < 5: continue (최소 베팅 체크). 킬 스위치 없었으면 4일 차에 3연패로 전체 잃을 뻔했을 것. 최소 체크 없었으면 API가 조용히 모든 주문 거부.

14일간 실행 — 실제로 일어난 일

2주. 878회 거래. 실제 돈. 여기 커브가 있습니다.

실수들 — 나에게 비용이 든 것들

4일 차 - 플래시 폭락으로 9% 증발

종료 직전 BTC가 $400 폭락. 3연패. 킬 스위치 발동, 다음 날까지 중지. 교훈: 킬 스위치를 믿으세요.

7일 차 - 얇은 시장에서 슬리피지(Slippage)

호가 측에 $60 밖에없는데$ 40 진입 시도. 3개 가격 레벨을 뚫고 체결. 예상보다 4% 더 지불. 교훈: 항상 실제 사이즈로 VWAP 체크하세요.

11일 차 - RPC 속도 제한

무료 Polygon RPC가 오류 반환 시작. 봇이 6개 진입 창 놓침. Alchemy 유료 티어($49/월)로 전환. 그 후 누락 없음. 교훈: 인프라에 짜게 굴지 마세요.

16일 차 - 0.001 사이즈 오류로 주문 거부

베팅 사이즈를 4.999로 계산, Polymarket 최소는 $5.00. 조용히거부됨 . 이제내림해서$ 1 단위로 올림. 교훈: 최솟값을 패딩하세요.

수동 vs Claude 기반 거래 — 무엇이 바꼈나

가장 큰 예상치 못한 이점은 속도나 규모가 아니었습니다. 나 자신을 결정에서 제거한 것이었습니다. 규칙이 코딩되고 나면, 새벽 2시에 떨리는 손으로 추측할 수 없습니다. 봇은 그냥 실행합니다.

잘못될 것들 — 그리고 고치는 법

GitHub 저장소 — 이것으로 구축하는 데 필요한 모든 것

이 글의 모든 코드 줄은 공식, 공개, MIT 라이선스 저장소를 기반으로 합니다. 북마크하세요 — 지금 프로덕션에서 실행 중인 모든 심각한 Polymarket 봇의 기초입니다.

공식 Polymarket 저장소

Polymarket / py-clob-client 공식 Python SDK. 주문 배치, 서명, 인증. 이 글의 모든 코드 블록이 이것 사용.
Polymarket / py-clob-client-v2 더 깨끗한 API와 명시적 L1/L2 인증을 갖춘 차세대 SDK. 새 프로젝트에 사용.
Polymarket / clob-client TypeScript / JavaScript SDK. Node.js 봇용 py-clob-client와 동일 기능.
Polymarket / rs-clob-client 저지연 실행을 위한 Rust SDK. 지연 경쟁에서 승리하는 지갑들이 사용.
Polymarket / agents Polymarket 자체 AI 거래 에이전트 프레임워크. Langchain + Chroma + LLM 기반 자율 거래.
Polymarket / examples Proxy/Safe 지갑, 분할, 병합, 환매 예제. 서명 오류 디버깅 전 읽으세요.
Polymarket / polymarket-cli 시장 탐색, 잔액 확인, 주문 배치를 위한 명령줄 도구. 코드 작성 없이 디버깅하기 좋음.
Polymarket / magic-proxy-builder-example 이메일/Magic 계정용 Next.js 예제. MetaMask 대신 이메일로 가입했다면 필수.
Polymarket / clob-order-utils 주문 구축 및 서명용 저수준 유틸리티. 커스텀 서명자를 구축 중이라면 필요.
Polymarket / ctf-exchange-v2 실제 온체인 거래 계약. 주문이 어떻게 결제되는지 이해하려면 소스 읽기.

커뮤니티 저장소 (북마크 가치)

HuakunShen / polymarket-kit WebSocket 클라이언트와 OpenAPI 스키마를 갖춘 완전 타입 지정 TypeScript SDK. 타입화된 개발에 최고의 DX.
GiordanoSouza / polymarket-copy-trading-bot 오픈소스 카피 트레이딩 봇. Supabase + py-clob-client 사용해 실시간으로 상위 지갑 미러링. 참조 아키텍처.
PyPI / polymarket-apis 모든 4개 API(CLOB, Gamma, Data, WebSocket)를 감싼 통합 Python 래퍼. Pydantic 검증 포함.

실제 사용법: 공식 Polymarket 저장소에 스타 표시하세요. py-clob-client 클론하고 /example 폴더 읽기 — 공식 예제가 온라인 튜토리얼 90%보다 낫습니다. 오류 발생 시 Googling 전에 GitHub Issues 검색 — 당신 전에 누군가 겪었을 가능성 높고 관리자가 응답했을 것.

연결 및 팔로우

AI, 수학적 전략, Polymarket 인사이트 세계에 더 깊이 들어가고 싶다면 커뮤니티 참여:

Polymarket 링크 — https://polymarket.com/?r=adiix

Copy Trades Bot on Polymarket — https://t.me/AresProTradingBot?start=r_wallet

Private Telegram — https://t.me/+bkqbSTOD9z02OTQy

이 글을 읽어주셔서 감사합니다. 이 글을 쓰는 데 많은 시간, 시행착오, 실수가 들어갔습니다. 앞으로 많은 멋진 것들이 당신을 기다리고 있습니다. 팔로우와 리포스트 부탁드립니다.

LLM Wiki

탐색기

Claude에게 Polymarket 계정 키를 줬을 때 일어난 일 (전체 가이드 + 13개 GitHub)