Polymarket API rate limits — Gamma, Data & CLOB

Polymarket API 속도 제한은 봇, 대시보드, 분석 시스템을 설계할 때 반드시 고려해야 할 스로틀 장치입니다. 이 가이드는 각 공개 서피스(Gamma, Data, CLOB, Market WebSocket)에 대한 문서화된 한도를 정리하고, /markets의 10초당 300요청 규칙 및 커서 기반 페이징과 같은 중요한 제약을 설명하며, 클라이언트를 안정적으로 운영하기 위한 실무적 전략(배치, 캐싱, 커서 페이징, 지수 백오프 등)을 제공합니다.

핵심 요약

• Gamma의 /markets 엔드포인트: 10초당 300 요청; 페이징에는 limit 파라미터와 after_cursor를 사용하세요(절대 offset 사용 금지).
• 결합된 목록 한도: /markets + /events 호출은 합계 10초당 900요청 한도를 공유합니다; Gamma 전체 표면은 10초당 4000요청입니다.
• 전문적인 읽기 작업에는 CLOB 및 Data API를 사용하세요; CLOB의 트레이딩 호출은 API 키 + HMAC이 필요하고 읽기는 공개입니다.
• 실시간 데이터는 WebSocket(wss://ws-subscriptions-clob.polymarket.com/ws/market)을 통해 제공됩니다; 라이브 북 업데이트에는 폴링 대신 WS를 권장합니다.
• 완화 패턴: 요청 병합, 캐시 TTL, 지터가 있는 지수 백오프, 한도 인지 큐잉, 페이징 인지 페칭.

왜 속도 제한이 중요한가

속도 제한은 Polymarket의 공유 인프라를 보호하고 시끄러운 클라이언트가 다른 사용자의 경험을 저하시하는 것을 막습니다. 차익거래 봇이나 분석 시스템을 구축하는 개발자에게 한도에 도달하면 즉시 요청이 거부되고 시간에 민감한 흐름이 깨질 수 있습니다. 사전에 요청 패턴을 계획하면 놀라움을 줄이고 시스템을 더 견고하게 만듭니다.

문서화된 Polymarket 속도 제한 및 엔드포인트

Gamma (기본 시장 메타데이터)

• Base URL: https://gamma-api.polymarket.com
• 주목할 한도:
  • /markets: 10초당 최대 300 요청. 페이징에는 limit 파라미터(최대 1000)와 after_cursor 기반 커서 페이징을 사용하세요. API는 offset을 HTTP 422로 거부합니다.
  • 결합된 /markets + /events 목록 한도: 10초당 900 요청.
  • 전체 Gamma API 표면: 10초당 4000 요청.

실무 주의사항:

• 항상 이전 호출이 반환한 after_cursor를 사용하세요; offset을 흉내 내는 키셋 에뮬레이션을 시도하지 마십시오.
• 라운드 트립을 줄이려면 limit을 조정하세요. 전체 마켓 목록이 필요하면 limit=1000이 호출 수를 줄입니다.

Data (포지션, 트레이드, 홀더)

• Base URL: https://data-api.polymarket.com
• 인증: 공개 읽기에 대해 인증 없음.
• 이 문서는 Data 표면을 간단히 설명하지만 Data의 엔드포인트별 속도 수치는 제공하지 않습니다. Data를 공개 API로 간주하되 Gamma와 동일하게 보수적인 클라이언트 제어(배치, 캐싱, 백오프)를 구현하십시오.

CLOB (오더북 및 트레이딩)

• Base URL: https://clob.polymarket.com
• 읽기는 공개입니다. 트레이딩은 API 키 + HMAC이 필요합니다.
• CLOB 표면은 오더북, Midpoint, 가격 이력, 주문 생성/취소를 노출합니다. 문서는 CLOB 읽기에 대한 엔드포인트별 명시적 속도 수치를 공개하지 않습니다; 트레이딩 경로는 속도 민감 경로로 간주하고 가능하면 CLOB WebSocket 또는 Market WS를 사용해 실시간 북 데이터를 확보하세요.

Market WebSocket (실시간 시장 업데이트)

• URL: wss://ws-subscriptions-clob.polymarket.com/ws/market
• 시장 데이터에 대한 인증 불필요.
• 피드: 실시간 북, price_change, best_bid_ask(custom_feature_enabled: true로 활성화), last_trade_price, tick_size_change.
• 10초마다 PING 하트비트. 연결당 최대 500개 심볼.

준수해야 할 Gamma /markets 세부 규칙

• 페이징: after_cursor만 사용합니다. API는 next_cursor를 반환합니다 — 그대로 다음 호출에 전달하세요.
• limit 기본값은 20, 최대 1000입니다. 대량 동기화에는 큰 limit을 사용하세요.
• 허용되는 필터 파라미터는 slug, id, condition_ids, clob_token_ids, question_ids, market_maker_address 등의 배열과 closed, active, archived, tag_id 같은 값들입니다.
• 정렬: order는 쉼표로 구분된 필드 목록(예: volume24hr,liquidity)을 받으며 ascending은 기본값 true인 불리언입니다.

일반적인 에러 신호와 대응 방법

• HTTP 429 (rate limited): 즉시 폴링을 중단하고 백오프한 뒤 재시도하세요(지수 백오프 및 지터 사용).
• HTTP 422 (offset 사용 시): after_cursor 페이징으로 전환하세요.
• 부분 응답 또는 빈 페이지: 커서를 존중하고 필터를 확인하세요. 서버 측 쿼터에 도달한 것으로 의심되면 클라이언트 동시성을 줄이세요.

스로틀을 피하기 위한 설계 패턴

1. 적극적으로 캐시하세요

• 마켓 목록과 메타데이터는 짧은 TTL(30초–2분)으로 캐시하세요. 마켓과 이벤트 목록은 매초 바뀌는 경우가 드뭅니다.
• 쿼리 키(필터 + 정렬)별로 캐시하고, WebSocket으로 변경 이벤트를 받거나 TTL이 만료될 때만 무효화하세요.

2. 배치 처리 및 limit 증가

• 전체 동기화에는 /markets에 limit=1000을 사용해 라운드 트립을 줄이세요.
• 비혼잡 시간에 넓은 페이지를 가져오고 WebSocket으로 증분 업데이트를 적용하세요.

3. 실시간 데이터에는 WebSocket을 사용하세요

• 라이브 오더북 업데이트나 가격 변동을 위해서는 Gamma 또는 CLOB 읽기를 폴링하기보다는 Market WS에 구독하세요. WS는 연결당 최대 500개 심볼을 지원합니다; 500개 초과가 필요하면 클라이언트를 샤딩하세요.

4. 한도 인지 큐잉 및 백오프

• 클라이언트 측에서 누수 버킷(leaky-bucket) 또는 토큰 버킷(token-bucket) 한정기를 구현하여 문서화된 피크(예: /markets의 300/10s)에 맞추세요.
• 429를 받으면 지수 백오프와 지터를 적용하고 재시도 창을 점진적으로 늘리세요.

5. 동일한 동시 요청을 병합하세요

• 앱의 여러 부분이 동일한 /markets 쿼리를 동시에 요청하면 한 개의 인플라이트 요청으로 병합하고 응답을 공유하세요.

6. 커서 우선 동기화

• 항상 커서 기반 페이징을 따르세요. 라이브 동기화의 경우 첫 페이지를 요청한 뒤 델타(증분)를 구독하세요. Gamma의 엔드포인트 한도를 초과할 수 있는 단순 다중 동시 커서 페칭은 피하세요.

예시 페치 전략

• 대량 인덱싱 작업(비실시간): /markets?limit=1000을 가져오고 next_cursor가 소진될 때까지 반복하세요. 페이지 사이에 짧게 슬립을 넣고 /markets의 300/10s 엔드포인트 한도를 준수하세요.
• 준실시간 UI: 기본 세트는 한 번 페치하고(캐시 30s), 이후 델타와 best_bid_ask 업데이트를 위해 WebSocket을 엽니다.
• 워치리스트 마이크로 클라이언트: 500개 초과 심볼은 여러 WS 연결로 샤딩하세요.

봇 및 고처리량 클라이언트를 위한 운영 지침

• 책 수준(book-level) 데이터에는 CLOB WebSocket 또는 CLOB 읽기를 사용하고, 느리게 바뀌는 메타데이터에는 Gamma를 사용하세요.
• 트레이딩 자격증명(CLOB API 키 + HMAC)은 안전하게 보관하세요; 트레이딩 엔드포인트는 인증이 필요합니다.
• 429 비율과 엔드포인트별 지연(latency)을 모니터링하세요. 문서화된 한도에 정기적으로 근접하면 접근 권한을 요청하거나 공식 Polymarket 채널을 통해 문의하세요(Builder Program은 더 높은 볼륨 통합과 어트리뷰션의 경로입니다).

개발 및 배포에 미치는 영향

트레이딩 봇이나 분석 서비스를 구축한다면 계층화된 데이터 흐름을 계획하세요: 큰 limit로 Gamma에서 초기 대량 페치 후 WebSocket 구독으로 라이브 업데이트를 받고, WS 피드에 없는 메타데이터용으로는 소량의 주기적 Gamma 폴을(캐시) 유지합니다. 클라이언트 측 속도 제한, 병합, 커서 인지 페이징을 구현하면 /markets 10초당 300요청 한도와 결합된 목록 및 전체 Gamma 한도에 걸리는 것을 피할 수 있습니다.

요약

Polymarket API 속도 제한은 Gamma의 목록 표면에 대해 명시적이며 Market WS는 실시간 피드에 대한 확장 가능한 대안입니다. 커서 기반 페이징(after_cursor)을 기준으로 설계하고 limit을 전략적으로 사용하며 고빈도 데이터에는 WebSocket을 선호하세요. 이러한 패턴을 따르면 스로틀링이 줄고 통합이 더 신뢰성 있게 동작합니다.

자주 묻는 질문

Gamma의 /markets 속도 제한은 무엇인가요?

Gamma의 /markets 엔드포인트는 10초당 300 요청으로 제한됩니다. limit(최대 1000)과 after_cursor 기반 커서 페이징을 사용하세요. offset은 사용하지 마세요 — API가 HTTP 422로 거부합니다.

Gamma 엔드포인트에 결합된 한도가 있나요?

예. /markets와 /events에 대한 목록 호출은 합쳐서 10초당 900요청 한도를 공유합니다. 추가로 Gamma 전체 API 표면은 10초당 4000요청으로 제한됩니다.

실시간 업데이트를 위해 Gamma를 폴링해야 하나요, 아니면 WebSocket을 사용해야 하나요?

라이브 북과 가격 업데이트에는 Market WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market)을 우선 사용하세요 — 폴링보다 효율적이며 반복 폴링을 피할 수 있습니다. Gamma는 더 천천히 변하는 메타데이터와 초기 대량 동기화에 적합합니다.

HTTP 429 응답을 받으면 클라이언트는 무엇을 해야 하나요?

429는 공격적인 폴링을 중단하라는 신호로 처리하세요. 지수 백오프와 지터를 구현하고 동시성을 낮추며 동일 요청을 병합하세요. 429 발생률을 추적하여 동적으로 속도 제한기를 조정하십시오.

CLOB API는 인증이 필요한가요?

CLOB 읽기는 공개입니다. CLOB에서 트레이딩 작업은 API 키와 HMAC 인증이 필요합니다. 트레이딩 속도 제한을 준수하고 오더북 업데이트에는 WS 피드를 선호하세요.