2026년 Polymarket Python SDK (그리고 py-clob-client에서 옮겨 가기)

이 변화가 일반적인 버전 업데이트보다 중요한 이유는 하나입니다. 인터넷에 있는 거의 모든 Polymarket 코드 예제가 이보다 오래되었습니다. 블로그 글, Stack Overflow 답변, GitHub 예제, 그리고 그런 자료로 학습했기 때문에 Polymarket 봇을 요청하면 AI 어시스턴트가 작성하는 코드도 마찬가지입니다. 존재하지 않는 import를 디버깅하고 있었다면 이것이 이유입니다.

실제로 바뀐 것

이전 방식은 Polymarket 서비스마다 클라이언트가 하나씩 있었습니다. 오더북은 CLOB 클라이언트를 import하고, 마켓 탐색은 원시 HTTP로 Gamma를 호출하고, 포지션은 Data API를 따로 호출하고, relayer 트랜잭션이 필요하면 builder-signing 패키지를 가져왔습니다. 네 가지 사고 모델, 네 가지 오류 형태, 네 가지 페이지네이션 방식이었습니다.

통합 SDK는 이를 모든 영역을 다루는 하나의 클라이언트로 합칩니다.

설치

pip install polymarket-client
# uv add polymarket-client
# poetry add polymarket-client

네 가지 클라이언트: 신중하게 고르세요

import asyncio
from polymarket import AsyncPublicClient


async def main() -> None:
    async with AsyncPublicClient() as client:
        pages = client.list_markets(closed=False)
        first = await pages.first_page()
        for market in first.items:
            print(market.slug)


asyncio.run(main())

공개 데이터에는 자격 증명이 필요 없으므로, 키를 도입하기 전에 가능한 모든 것을 AsyncPublicClient로 만들고 테스트하세요. 탐색, 파싱, 페이지네이션, 신호 생성, 백오프를 모두 아무런 위험 없이 검증할 수 있습니다.

페이지네이션

모든 목록 메서드에서 하나의 페이지네이터 인터페이스를 사용합니다. 페이지 경계가 중요한지에 따라 세 가지 방식으로 사용할 수 있습니다:

pages = client.list_markets(closed=False, page_size=10)

# 1. Page at a time — use this when you need to control pacing
#    against the tight /markets rate limit (300 req / 10s).
async for page in pages:
    for market in page.items:
        ...

# 2. Item at a time, boundaries ignored.
async for market in pages.iter_items():
    ...

# 3. Manual, resumable.
page = await pages.first_page()
if page.next_cursor:
    nxt = await pages.from_cursor(page.next_cursor).first_page()

타입이 지정된 모델

메서드는 딕셔너리가 아니라 최상위 패키지에서 내보내는 실제 타입을 반환합니다:

from polymarket import Event, Market, OrderBook, PriceHistoryPoint

가장 화려하지 않은 개선이지만 아마 가장 가치 있는 개선입니다. 이전 클라이언트에서는 이름이 바뀌거나 빠진 필드가 런타임에 전략 루프 깊은 곳에서 KeyError로 나타났습니다. 흔히 프로덕션에서, 흔히 포지션을 보유한 상태에서였습니다. 타입 모델은 그 실패를 있어야 할 자리로 옮겨 줍니다.

실시간 구독

subscribe()는 여러 피드를 타입이 지정된 단일 이벤트 스트림으로 병합합니다. 여러 WebSocket 연결을 직접 관리하는 것보다 확실히 나아진 점입니다.

from polymarket.streams import MarketSpec, SportsSpec

async with await client.subscribe(
    [MarketSpec(token_ids=[token_id]), SportsSpec()],
) as stream:
    async for event in stream:
        # MarketBookEvent | MarketPriceChangeEvent
        # | MarketLastTradePriceEvent | MarketTickSizeChangeEvent
        # | MarketBestBidAskEvent | NewMarketEvent
        # | MarketResolvedEvent | SportsEvent
        handle(event)

SDK는 원래 직접 구현해야 했을 하트비트, 프레이밍, 재연결을 처리합니다. 원시 연결에서 10초마다 PING을 보내야 하는 요구 사항도 포함됩니다. 자세한 내용은 WebSocket 가이드에 있습니다.

주문 넣기

market = await client.get_market(slug="<market-slug>")
token_id = market.outcomes.yes.token_id
assert token_id is not None

response = await client.place_market_order(
    token_id=token_id,
    side="BUY",
    amount="10",     # pUSD to spend, not shares to buy
)

if not response.ok:
    raise RuntimeError(response.message)

# Settlement is on-chain and asynchronous.
hashes = await client.wait_for_order_fill_settlement(response)

# Reconcile rather than assuming.
page = await client.list_positions(market=[market.condition_id]).first_page()
position = next((p for p in page.items if p.token_id == token_id), None)

py-clob-client에서 마이그레이션하기

1. 모든 Polymarket 호출을 목록으로 정리하세요. Gamma와 Data API에 대한 원시 requests 호출도 포함됩니다. 이것들도 대상입니다. 통합 SDK가 다루며, 이들을 합치는 것이 이점의 대부분입니다.
2. polymarket-client를 설치하고 이전 패키지를 제거하세요. 점진적으로 마이그레이션하려고 둘 다 설치해 두면 잘못된 client 심볼을 import하게 됩니다.
3. 클라이언트 생성 코드를 교체하세요. AsyncSecureClient.create(...) 하나가 이전의 서비스별 클라이언트와 별도의 자격 증명 처리를 대체합니다.
4. 딕셔너리 접근을 속성 접근으로 바꾸세요. market["condition_id"]는 market.condition_id가 됩니다. 지루한 작업이지만, 타입 검사기가 제값을 하기 시작하는 지점입니다.
5. 페이지네이션을 수동 offset이나 커서 루프 대신 페이지네이터 인터페이스로 다시 작성하세요.
6. 직접 만든 WebSocket 코드를 subscribe()로 교체하고, 하트비트와 재연결 로직을 삭제하세요.
7. 읽기 전용 경로를 먼저 다시 실행하세요. 무엇이든 주문을 넣게 하기 전에 공개 클라이언트로 실행합니다.

AI 어시스턴트가 이것을 틀리는 이유

많은 사람이 이 글에 오게 되는 경로이므로 직접 다룰 가치가 있습니다. LLM에게 Polymarket Python 코드를 요청하면 py_clob_client import, ClobClient(...) 생성, OrderArgs 객체가 아주 자주 나옵니다. 모델이 오작동하는 것이 아닙니다. 통합 SDK 이전의, 모델이 본 압도적 다수의 Polymarket 코드를 재현하고 있는 것입니다.

• import 줄을 먼저 확인하세요. from polymarket import ...가 현재 방식이고, from py_clob_client...는 아닙니다.
• 현재 문서를 컨텍스트에 붙여 넣으세요. Polymarket은 docs.polymarket.com/llms.txt에 기계가 읽을 수 있는 Markdown을 공개하며, 모든 페이지에 .md 버전이 있습니다. 모델과 논쟁하는 것보다 진짜 문서를 주는 편이 낫습니다.
• 실행되지 않는 자신만만한 코드를 의심하세요. 생성된 코드는 이전 API와 새 API를 섞어 존재한 적 없는 무언가를 만드는 경우가 많습니다.

데이터 제공업체에도 같은 문제가 있습니다. 저희는 어시스턴트가 추측 없이 올바른 PolyTest 연동 코드를 작성할 수 있도록 llms.txt, llms-full.txt, OpenAPI 명세를 공개하고 AI 크롤러를 허용합니다. 일부 제공업체는 이런 크롤러를 차단하는데, 정당한 선택이지만 그러면 어시스턴트가 그들의 API 형태를 즉흥적으로 지어내게 됩니다.

SDK로도 여전히 할 수 없는 것

통합 SDK는 Polymarket API에 대한 훨씬 나은 인터페이스입니다. 하지만 그 API에 담긴 내용을 바꾸지는 않으며, 봇 개발자가 가장 원하는 것은 거기에 없습니다.

과거 오더북은 없습니다. client.get_market()은 결과가 확정된 마켓의 메타데이터를 반환하지만 오더북은 사라졌습니다. /book은 404를 반환하고, prices-history는 약 1분에 한 포인트만 보관합니다. 어떤 SDK 메서드, 플랜, 자격 증명으로도 오더북을 되살릴 수 없습니다.

백테스팅에는 마켓이 진행되는 동안 기록된 스냅샷이 필요합니다. PolyTest는 암호화폐 Up/Down 마켓에 대해 이를 제공합니다. 240M+개의 특정 시점 스냅샷, 한쪽당 8단계 깊이, 1초 미만 단위 타임스탬프, 결과가 확정된 마켓 보존. X-API-Key 헤더를 쓰는 평범한 REST API이므로 SDK와 같은 비동기 코드에 그대로 넣을 수 있습니다. 무료로 시작하거나, 전체 과정은 봇 만드는 방법을 읽어 보세요.