Polymarket API 엔드포인트에는 무엇이 있나요?

Polymarket은 네 개의 REST API를 운영합니다. 이벤트, 마켓, 메타데이터를 위한 Gamma(gamma-api.polymarket.com), 가격, 오더북, 거래를 위한 CLOB(clob.polymarket.com), 포지션과 활동을 위한 Data API(data-api.polymarket.com), 가스비 없는 트랜잭션을 위한 Relayer(relayer-v2.polymarket.com)입니다. 또한 공개 market 채널, 인증된 user 채널, 실시간 데이터, 스포츠를 다루는 네 개의 WebSocket 스트림이 있습니다.

Polymarket API는 무료인가요?

네. 유료 등급, 구독, API 요금 페이지가 없습니다. 접근은 결제가 아니라 요청 한도로 관리되며, 공개 마켓 데이터에는 API 키가 전혀 필요 없습니다. 늘어나는 유일한 것은 서명자별 거래 처리량 등급이며, 이는 결제가 아니라 지갑의 30일 거래량에 따라 결정됩니다.

Polymarket API 키는 어떻게 발급받나요?

Polygon 개인 키로 ClobAuth EIP-712 타입 데이터 페이로드에 서명한 다음, L1 헤더와 함께 POST /auth/api-key를 호출해 자격 증명을 생성하세요. 키, 시크릿, 패스프레이즈를 받게 되며, L2 요청 서명에는 세 가지 모두 필요합니다. 이후 실행에서는 새로 만들지 말고 GET /auth/derive-api-key로 기존 자격 증명을 가져오세요. 공개 마켓 데이터에는 키가 필요 없습니다.

Gamma API와 CLOB API의 차이는 무엇인가요?

Gamma는 탐색용입니다. 어떤 이벤트와 마켓이 있는지, 그 메타데이터, 다른 엔드포인트에 필요한 토큰 ID를 제공합니다. CLOB은 오더북용입니다. 현재 가격, 오더북 깊이, 주문 제출 및 취소를 다룹니다. 마켓을 찾아야 한다면 Gamma를, 가격을 확인하거나 거래해야 한다면 CLOB을 사용하세요.

Polymarket에 Python SDK가 있나요?

네. Polymarket은 네 개의 REST API를 모두 타입 인터페이스로 다루고 페이지네이션, 오류 형태, 지갑 설정을 처리하는 통합 TypeScript 및 Python SDK를 유지보수합니다. 이전 클라이언트에서 옮겨 오는 문서화된 마이그레이션 경로가 있습니다. 런타임이 지원되지 않거나, 서명과 재시도를 정밀하게 제어해야 하거나, SDK가 아직 노출하지 않은 엔드포인트가 필요할 때는 REST를 직접 사용하는 것이 합리적입니다.

Polymarket API로 과거 오더북 깊이를 받을 수 있나요?

아니요. 모든 Polymarket 엔드포인트는 현재 상태를 제공합니다. /prices-history 엔드포인트는 그 뒤의 깊이 없이 약 1분에 한 포인트의 가격 시계열을 반환하므로 특정 주문 규모가 어떤 가격에 체결되었을지 알려줄 수 없으며, 결과가 확정된 마켓의 오더북은 404를 반환합니다. 백테스팅에는 마켓이 진행되는 동안 기록된 특정 시점 스냅샷이 필요합니다. 예를 들어 PolyTest의 암호화폐 Up/Down 마켓 240M+개 스냅샷 아카이브가 있습니다.

API 레퍼런스Polymarket APICLOBGamma API

Polymarket API 지도: Gamma vs CLOB vs Data API

처음 시작하는 사람들은 같은 문제로 하루를 날립니다. Polymarket에는 API가 하나가 아니라 네 개 있고, 원하는 엔드포인트는 처음 시도한 API에 있는 경우가 드뭅니다. 이 글은 전체 지도입니다.

2026년 9월 5일10분 분량

Polymarket API에 대해 가장 먼저 이해해야 할 점은 그런 것이 하나로 존재하지 않는다는 것입니다. REST API 네 개와 WebSocket 스트림 네 개가 있으며, 각각 연동의 서로 다른 부분을 담당하고, 각자 고유한 호스트명, 요청 한도, 인증 요구 사항을 갖습니다.

"Polymarket API에는 X가 없다"는 질문은 거의 모두 "X는 다른 호스트에 있다"로 밝혀집니다. 전체 구조를 한곳에 정리했습니다.

네 개의 REST API

API	Base URL	용도	인증
Gamma	`gamma-api.polymarket.com`	이벤트와 마켓 탐색, 메타데이터	없음
CLOB	`clob.polymarket.com`	가격, 오더북, 주문 제출 및 관리	읽기는 없음, 거래는 L1/L2
Data	`data-api.polymarket.com`	포지션, 활동, 마켓 참여	없음
Relayer	`relayer-v2.polymarket.com`	가스비용 POL 없이 지갑 트랜잭션 제출	서명 필요

30초 라우팅 규칙

어떤 마켓이 있나? → Gamma. 가격은 얼마인가 / 거래하고 싶다 → CLOB. 이 지갑은 무엇을 보유하고 있나? → Data API. 가스비 없이 자금을 옮겨야 한다 → Relayer. CLOB에서 이벤트 엔드포인트를 찾거나 Gamma에서 오더북을 찾고 있다면, 그게 바로 실수입니다.

Gamma API: 탐색과 메타데이터

Gamma가 출발점입니다. 무엇이 존재하는지에 답합니다. 이벤트, 그 안의 마켓, 태그, 검색, 그리고 다른 모든 작업에 필요한 메타데이터, 특히 모든 CLOB 엔드포인트가 요구하는 토큰 ID를 제공합니다.

/events: 이벤트 목록, 키셋 페이지네이션 지원
/markets: 마켓 목록, by id, by slug, by token 조회도 지원
/public-search: 이벤트와 마켓 전체 검색
/tags, /comments: 분류 체계와 토론
미결제 약정, 실시간 거래량, 상위 보유자

/markets는 플랫폼에서 가장 엄격한 한도를 가집니다

10초에 300회로, Gamma 자체의 일반 한도인 10초에 4,000회보다 13배 엄격합니다. 루프로 전체 마켓 목록을 페이지네이션한다면 가장 먼저 여기서 문제가 생깁니다. 마켓 메타데이터는 마켓 수명 동안 거의 바뀌지 않으므로 캐시하세요. 전체 수치는 요청 한도 레퍼런스에 있습니다.

CLOB API: 가격, 오더북, 주문

오더북 그 자체이자 거래할 수 있는 유일한 곳입니다. 읽기는 공개되어 있고, 거래에는 자격 증명이 필요합니다.

그룹	엔드포인트	인증
오더북	`/book`, `/books`, `/midpoint`, `/midpoints`, `/spread`, `/spreads`	공개
가격	`/price`, `/prices`, `/prices-history`, 최근 체결가, `/tick-size`, 수수료율	공개
주문	`POST /order`, `POST /orders`, `DELETE /order`, `/orders`, `/cancel-all`, `/cancel-market-orders`	L2 + 지갑 서명
원장	`/trades`, `/data/orders`, `/data/trades`, `/notifications`	L2
인증	`/auth/api-key`, `/auth/api-keys`, `/auth/derive-api-key`	L1
계정	잔액 허용량 (조회 / 업데이트)	L2

단수형과 복수형은 실제로 다릅니다

거의 모든 CLOB 마켓 데이터 엔드포인트에는 배치용 쌍이 있습니다. /book과 /books, /price와 /prices. 단수형 엔드포인트는 10초에 1,500회, 복수형은 10초에 500회이지만, 복수형 호출 한 번으로 여러 토큰을 처리하므로 배치를 쓰면 요청 한도 대비 훨씬 많은 데이터를 얻습니다. 사실상 항상 /book 루프보다 /books를 선택하세요.

Data API: 포지션과 활동

포트폴리오에 관한 질문을 다룹니다. /positions, /closed-positions, /trades, 그리고 사용자 PNL API가 있습니다. 세 가지 주요 API 중 가장 엄격하다는 점에 유의하세요. 일반 한도는 10초에 1,000회이고, /positions와 /closed-positions는 각각 10초에 150회에 불과합니다. 폴링 루프가 아니라 대시보드를 위해 설계되었습니다.

네 개의 WebSocket 스트림

타이머로 /book을 폴링하고 있다면 멈추세요. 스트림이 바로 그것을 위해 존재합니다. 폴링은 아무 이득 없이 요청 한도를 소모하는 가장 흔한 방법입니다.

스트림	URL	전달 내용
CLOB Market	`wss://ws-subscriptions-clob.polymarket.com/ws/market`	공개 오더북, 가격, 마켓 수명 주기 업데이트
CLOB User	`wss://ws-subscriptions-clob.polymarket.com/ws/user`	내 계정의 인증된 주문 및 체결 업데이트
RTDS	`wss://ws-live-data.polymarket.com`	공개 기준 가격, 댓글, 거래 활동
Sports	`wss://sports-api.polymarket.com/ws`	실시간 경기 상태와 점수

사람들이 놓치는 것이 User 채널입니다. 봇이 주문 체결 여부를 알기 위해 /data/orders를 폴링한다면, User 채널이 발생 즉시 더 낮은 지연 시간으로 푸시해 줬을 정보에 요청 한도를 쓰고 있는 것입니다.

인증: L1과 L2

공개 마켓 데이터에는 자격 증명이 전혀 필요 없습니다. Gamma, CLOB 읽기 엔드포인트, Data API를 맨 curl로 호출할 수 있습니다. 거래에는 두 계층이 필요하며, 어느 것이 어느 것인지 이해하면 대부분의 인증 오류가 해결됩니다.

계층	동작 방식	목적
L1	지갑이 EIP-712 메시지에 서명	지갑 통제 증명, API 자격 증명 생성 또는 파생
L2	API 자격 증명으로 요청을 HMAC-SHA256 서명	비공개 CLOB 요청 인증

주문 제출에는 둘 다 사용됩니다. L2는 요청을 인증하고, 지갑 서명은 주문을 승인합니다. L1 타입 데이터는 chainId: 137(Polygon) 위의 ClobAuth 페이로드로, 서명자 주소, 초 단위 Unix 타임스탬프, nonce(여러 자격 증명 세트를 관리하지 않는다면 0 사용), 고정 메시지 문자열을 포함합니다.

API 키 발급받기

Polygon 개인 키로 ClobAuth EIP-712 페이로드에 서명합니다.
L1 헤더와 함께 POST /auth/api-key를 호출해 자격 증명을 생성합니다. 키, 시크릿, 패스프레이즈를 받게 되며, L2에는 세 가지 모두 필요합니다.
이후 실행에서는 새로 만드는 대신 GET /auth/derive-api-key를 호출해 기존 자격 증명을 가져옵니다.

지원 문의의 대부분을 차지하는 두 가지 인증 실패

불완전한 자격 증명: L2에는 키, 시크릿, 그리고 패스프레이즈가 필요합니다. 셋 중 둘만 있으면 형식은 올바르지만 검증할 수 없는 서명이 만들어집니다. 시계 오차: 서명에는 타임스탬프가 포함되므로, 시계가 몇 초 어긋난 컨테이너는 서버가 무효로 거부하는 서명을 만듭니다. 두 경우 모두 Unauthorized/Invalid api key로 나타나며, 그래서 이 메시지가 그렇게 많이 검색됩니다. 오류 레퍼런스를 참고하세요.

SDK

Polymarket은 위의 모든 것을 타입 인터페이스로 감싸고 페이지네이션, 오류 형태, 지갑 설정을 처리하는 통합 TypeScript 및 Python SDK를 유지보수합니다. 두 언어 중 하나로 새로 시작한다면 SDK를 사용하세요. EIP-712 서명과 HMAC 요청 서명을 직접 구현하는 것은 주말을 날리기 딱 좋은, 실수하기 쉬운 작업입니다.

런타임이 SDK에서 지원되지 않거나, 서명, 헤더, 재시도, 전송을 정밀하게 제어해야 하거나, SDK가 아직 노출하지 않은 엔드포인트가 필요할 때는 REST를 직접 사용하세요. 이것들은 통합 SDK라는 점에 유의하세요. 이전 클라이언트를 쓰고 있다면 문서화된 마이그레이션 경로가 있으며, 오래된 자격 증명 관련 버그의 상당수가 이전 클라이언트에서 비롯됩니다.

Polymarket API의 비용은 얼마인가요?

무료입니다. 유료 등급도, API 요금 페이지도, 구독도 없습니다. Polymarket API는 무료로 사용할 수 있으며, 접근은 결제가 아니라 요청 한도로 관리됩니다. 공개 마켓 데이터에는 키조차 필요 없습니다.

돈과 연동되어 늘어나는 유일한 것은 서명자별 거래 한도로, 메이커 지갑의 30일 거래량에 따라 Standard의 초당 주문 토큰 40개부터 Elite의 600개까지 등급이 나뉩니다. 하지만 이것은 수수료가 아니라 처리량 할당입니다.

이 API들 중 어느 것도 제공하지 않는 한 가지

전체 구조를 정리했으니, 알아 두면 유용한 것은 여기에 없는 것입니다. 바로 과거 오더북 깊이입니다.

위의 모든 엔드포인트는 현재 상태를 제공합니다. /book은 지금의 오더북을 반환합니다. /prices-history는 가격은 주지만 깊이는 없으므로 체결이 어땠을지 알려줄 수 없습니다. 그리고 마켓 결과가 확정되면 /book은 404를 반환합니다. 남는 것은 시작과 끝을 명시해 가져올 수 있는 약 1분에 한 포인트의 성긴 가격 시계열뿐입니다. 어떤 플랜이나 요청 한도 등급으로도 이것은 바뀌지 않습니다.

질문	Polymarket API로 답할 수 있나요?
지금 오더북은 어떤가?	예. `/book`
어제 가격은 얼마였나?	예. 시작과 끝을 지정해 `/prices-history`에서 약 1분에 한 포인트
어제 14:03:17의 깊이는 어땠나?	아니요
내 500주 주문은 어떤 가격에 체결되었을까?	아니요
지난주에 결과가 확정된 마켓을 보여줘	레코드와 결과는 예(`closed=true`). 오더북은 아니요.

이 공백 때문에 Polymarket 전략을 백테스트하려면 마켓이 진행되는 동안 오더북을 기록한 별도의 데이터 소스가 필요합니다. PolyTest는 암호화폐 Up/Down 마켓에 대해 정확히 그 일을 합니다. 한쪽당 8단계 깊이를 갖춘 240M+개의 특정 시점 스냅샷, 1초 미만 단위 타임스탬프, 그리고 버리지 않고 보존하는 확정된 마켓. 헤더 하나, 깔끔한 JSON, 3일 무료 체험:

curl -H "X-API-Key: $POLYTEST_KEY" \
  "https://api.polytest.io/api/v1/markets?coin=btc&market_type=5m&limit=20"

전체 엔드포인트 레퍼런스는 PolyTest 문서에 있으며, 무료 체험을 시작할 수도 있습니다.

자주 묻는 질문

Polymarket API 엔드포인트에는 무엇이 있나요?: Polymarket은 네 개의 REST API를 운영합니다. 이벤트, 마켓, 메타데이터를 위한 Gamma(gamma-api.polymarket.com), 가격, 오더북, 거래를 위한 CLOB(clob.polymarket.com), 포지션과 활동을 위한 Data API(data-api.polymarket.com), 가스비 없는 트랜잭션을 위한 Relayer(relayer-v2.polymarket.com)입니다. 또한 공개 market 채널, 인증된 user 채널, 실시간 데이터, 스포츠를 다루는 네 개의 WebSocket 스트림이 있습니다.
Polymarket API는 무료인가요?: 네. 유료 등급, 구독, API 요금 페이지가 없습니다. 접근은 결제가 아니라 요청 한도로 관리되며, 공개 마켓 데이터에는 API 키가 전혀 필요 없습니다. 늘어나는 유일한 것은 서명자별 거래 처리량 등급이며, 이는 결제가 아니라 지갑의 30일 거래량에 따라 결정됩니다.
Polymarket API 키는 어떻게 발급받나요?: Polygon 개인 키로 ClobAuth EIP-712 타입 데이터 페이로드에 서명한 다음, L1 헤더와 함께 POST /auth/api-key를 호출해 자격 증명을 생성하세요. 키, 시크릿, 패스프레이즈를 받게 되며, L2 요청 서명에는 세 가지 모두 필요합니다. 이후 실행에서는 새로 만들지 말고 GET /auth/derive-api-key로 기존 자격 증명을 가져오세요. 공개 마켓 데이터에는 키가 필요 없습니다.
Gamma API와 CLOB API의 차이는 무엇인가요?: Gamma는 탐색용입니다. 어떤 이벤트와 마켓이 있는지, 그 메타데이터, 다른 엔드포인트에 필요한 토큰 ID를 제공합니다. CLOB은 오더북용입니다. 현재 가격, 오더북 깊이, 주문 제출 및 취소를 다룹니다. 마켓을 찾아야 한다면 Gamma를, 가격을 확인하거나 거래해야 한다면 CLOB을 사용하세요.
Polymarket에 Python SDK가 있나요?: 네. Polymarket은 네 개의 REST API를 모두 타입 인터페이스로 다루고 페이지네이션, 오류 형태, 지갑 설정을 처리하는 통합 TypeScript 및 Python SDK를 유지보수합니다. 이전 클라이언트에서 옮겨 오는 문서화된 마이그레이션 경로가 있습니다. 런타임이 지원되지 않거나, 서명과 재시도를 정밀하게 제어해야 하거나, SDK가 아직 노출하지 않은 엔드포인트가 필요할 때는 REST를 직접 사용하는 것이 합리적입니다.
Polymarket API로 과거 오더북 깊이를 받을 수 있나요?: 아니요. 모든 Polymarket 엔드포인트는 현재 상태를 제공합니다. /prices-history 엔드포인트는 그 뒤의 깊이 없이 약 1분에 한 포인트의 가격 시계열을 반환하므로 특정 주문 규모가 어떤 가격에 체결되었을지 알려줄 수 없으며, 결과가 확정된 마켓의 오더북은 404를 반환합니다. 백테스팅에는 마켓이 진행되는 동안 기록된 특정 시점 스냅샷이 필요합니다. 예를 들어 PolyTest의 암호화폐 Up/Down 마켓 240M+개 스냅샷 아카이브가 있습니다.

Polymarket이 보관하지 않는 과거 데이터를 확보하세요

PolyTest는 Polymarket 암호화폐 Up/Down 마켓을 실시간으로 기록합니다. 8단계 오더북 깊이와 1초 미만 단위 타임스탬프를 갖춘 240M+개의 스냅샷을 제공하며, 결과가 확정된 마켓도 보존합니다. 3일 무료 체험으로 시작하세요.

무료 체험 시작 빠른 시작