Polymarket Gamma API tutorial

이 튜토리얼에서는 Polymarket의 Gamma surface에서 시장과 이벤트를 가져오는 방법, 페이지네이션 처리, 일반적인 필터 적용 방법을 설명합니다. 예제는 curl과 TypeScript를 사용하므로 봇, 대시보드 또는 분석 파이프라인에 읽기 기능을 통합하기 쉽습니다.

핵심 요약

• Gamma의 기본 URL은 https://gamma-api.polymarket.com 이며 읽기 작업에는 인증이 필요 없습니다.
• /markets 및 /events 엔드포인트는 after_cursor를 사용하는 커서 기반 페이지네이션을 지원합니다. offset을 사용하지 마십시오.
• 속도 제한을 준수하세요: /markets는 300 req / 10 s, /markets + /events의 목록 호출 합산 제한은 900 req / 10 s입니다. 전체 API 한도는 4000 req / 10 s입니다.
• condition_ids, clob_token_ids, slug, tag_id 같은 필드로 필터링하면 페이로드를 줄이고 한도 초과를 피할 수 있습니다.
• 프로덕션 클라이언트에서는 작은 페이지 크기와 지수 백오프를 사용하세요.

1. Gamma 기본: 엔드포인트와 한도

Gamma 읽기 기본 URL은 다음과 같습니다:

https://gamma-api.polymarket.com

이 튜토리얼에서 사용할 엔드포인트:

• GET /markets — 시장 목록 및 단일 시장 조회
• GET /events — 이벤트별 그룹화된 메타데이터(이벤트 수준의 메타데이터에 유용)

설계 시 고려해야 할 중요한 속도 제한:

• /markets: 10초당 300 요청
• /markets + /events 목록 호출 합산: 10초당 900 요청
• 전체 Gamma API: 10초당 4000 요청

클라이언트가 폴링하거나 대규모 데이터 세트를 백필(backfill)할 경우 요청을 배치하고 시차를 두어 이 한도들을 존중하세요.

2. 시장 조회: 최소한의 curl 예제

기본 매개변수로 시장을 나열하는 최소 요청:

curl "https://gamma-api.polymarket.com/markets"

페이지 크기(limit)와 정렬을 제어하려면:

curl "https://gamma-api.polymarket.com/markets?limit=100&order=volume24hr&ascending=false"

참고:

• limit의 최대값은 1000입니다. 기본값은 20입니다.
• Gamma는 offset 기반 페이지네이션을 거부(HTTP 422)합니다. 대신 after_cursor를 사용한 키셋 페이지네이션을 사용하세요.

3. 커서 기반 페이지네이션 (after_cursor)

Gamma는 목록 응답에 next_cursor를 반환합니다. 다음 페이지를 가져오려면 해당 값을 after_cursor로 사용하세요. 다음은 TypeScript 예제입니다.

TypeScript 예제 (node-fetch 또는 네이티브 fetch 사용):

import fetch from 'node-fetch';

const BASE = 'https://gamma-api.polymarket.com';

type MarketsResponse = {
  markets: any[];
  next_cursor?: string | null;
};

async function fetchAllMarkets(limit = 200) {
  let cursor: string | undefined;
  const all: any[] = [];

  while (true) {
    const url = new URL('/markets', BASE);
    url.searchParams.set('limit', String(limit));
    if (cursor) url.searchParams.set('after_cursor', cursor);

    const res = await fetch(url.toString());
    if (!res.ok) throw new Error(`Gamma error ${res.status}`);

    const body: MarketsResponse = await res.json();
    all.push(...body.markets);

    if (!body.next_cursor) break;
    cursor = body.next_cursor;

    // small delay to avoid spike; tune for your rate budget
    await new Promise((r) => setTimeout(r, 100));
  }

  return all;
}

보여준 모범 사례:

• limit로 페이지 크기와 네트워크 사용량을 제어하세요.
• next_cursor를 존중하고 값이 없으면 중단하세요.
• 속도 한도 근처에서는 작은 지연이나 백오프를 추가하세요.

4. 유용한 필터와 쿼리 매개변수

Gamma는 많은 쿼리 매개변수를 지원합니다. 표적화된 읽기가 필요할 때 가장 유용합니다:

• slug, id, question_ids, condition_ids, clob_token_ids, market_maker_address — 모두 배열로 전달
• closed (boolean), active, archived
• tag_id — 카테고리별 필터
• order — volume24hr, volume, liquidity, endDate 같은 콤마로 구분된 필드
• ascending — boolean (기본값 true)

예: 태그 내 활성 시장을 24시간 거래량 기준 내림차순으로 가져오기:

curl "https://gamma-api.polymarket.com/markets?active=true&tag_id=123&order=volume24hr&ascending=false&limit=100"

특정 시장만 필요한 경우 slug 또는 id 배열을 전달하여 페이로드를 줄이고 전체 스캔을 피하세요.

5. 이벤트 엔드포인트

/events 엔드포인트는 이벤트 수준 메타데이터 하에 시장들을 그룹화합니다(예: 여러 조건을 포함하는 "2026 Presidential Election" 같은 이벤트).

기본 호출:

curl "https://gamma-api.polymarket.com/events?limit=50"

이벤트도 after_cursor를 사용한 페이지네이션을 사용하며 /markets와 합산된 목록 호출 한도(목록 호출 합산: 10초당 900 요청)를 공유합니다.

6. 실용적인 TypeScript 예제: condition_ids로 시장 가져오기

다음 예제는 condition ID 목록에 대해 동시성 제어와 지수 백오프를 적용해 시장을 가져옵니다.

import fetch from 'node-fetch';

const BASE = 'https://gamma-api.polymarket.com';

async function fetchMarketsByCondition(conditionIds: string[]) {
  const results: any[] = [];

  for (const id of conditionIds) {
    let cursor: string | undefined;
    let retries = 0;

    while (true) {
      const url = new URL('/markets', BASE);
      url.searchParams.set('limit', '200');
      url.searchParams.set('condition_ids', id);
      if (cursor) url.searchParams.set('after_cursor', cursor);

      const res = await fetch(url.toString());
      if (res.status === 429) {
        // respect rate limits with exponential backoff
        await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, retries)));
        retries = Math.min(retries + 1, 5);
        continue;
      }

      if (!res.ok) throw new Error(`Gamma ${res.status}`);

      const body = await res.json();
      results.push(...body.markets);

      if (!body.next_cursor) break;
      cursor = body.next_cursor;
    }
  }

  return results;
}

프로덕션 사용 시 참고사항:

• conditionIds가 많을 경우 concurrency limiter(p-map, p-limit 등)를 사용하세요.
• API가 지원하면 변경되지 않은 결과는 캐시(ETag/If-None-Match)하세요.
• 문서화된 한도에 대해 요청 속도를 모니터링하세요.

7. 일반적인 실수와 문제해결

• offset을 사용하지 마세요 — Gamma는 offset 매개변수에 대해 HTTP 422를 반환합니다.
• 커서 없이 큰 페이지를 요청하면 한도 초과나 메모리 압박이 발생할 수 있습니다. 작은 limit와 커서 순회 방식을 선호하세요.
• /markets + /events 목록 호출 합산 한도 때문에 두 엔드포인트를 모두 과도하게 폴링하면 빠르게 제한당할 수 있습니다.
• API는 키셋 페이지네이션을 위한 next_cursor를 반환합니다. 이 값은 불투명(opaque)하게 취급하고 그대로 다시 전달하세요.

8. 실시간 데이터와의 통합

Gamma는 메타데이터와 과거 목록에 대한 REST surface입니다. 실시간 주문서(order-book) 및 틱 이벤트는 Market WebSocket(wss://ws-subscriptions-clob.polymarket.com/ws/market)을 사용하세요. WebSocket은 연결당 최대 500개의 종목을 지원하며 price_change, best_bid_ask, last_trade_price, tick_size_change 이벤트를 방출합니다.

백필에는 REST를, 라이브 업데이트에는 WebSocket을 사용하세요.

9. 이것이 거래나 도구에 미치는 영향

거래 봇, 대시보드, 데이터 파이프라인을 구축하는 경우 Gamma는 시장 메타데이터, 태그, 목록의 표준 읽기 소스입니다. 커서 페이지네이션을 사용하고 공격적으로 필터링하며 Gamma 읽기를 CLOB API 또는 Market WebSocket의 가격·주문서 데이터와 조합하세요. 문서화된 속도 제한을 중심으로 폴링 간격을 설계하여 스로틀링을 피하세요.

Gamma는 공개 데이터에 대해 읽기 전용입니다; 위 예제에는 API 키가 필요하지 않습니다. 주문 배치와 북(book) 조작은 API 키 + HMAC가 필요한 CLOB API(https://clob.polymarket.com)를 사용하세요.

마무리

이 Polymarket Gamma API 튜토리얼은 시장과 이벤트를 가져오고, 커서 페이지네이션을 처리하며, 일반적인 함정을 피하는 실용적인 단계를 다뤘습니다. 이 패턴을 기반으로 Gamma의 속도 제한과 페이지네이션 모델을 존중하는 신뢰할 만한 봇과 분석 도구를 만드세요.

자주 묻는 질문

Gamma API에서 읽기 위해 API 키가 필요합니까?

아니요. Gamma의 공개 읽기 엔드포인트는 인증이 필요하지 않습니다. 기본 URL은 https://gamma-api.polymarket.com 입니다. 거래를 위해서는 API 키 + HMAC가 필요한 CLOB 엔드포인트를 사용하세요.

대규모 시장 목록을 어떻게 페이지 처리하나요?

커서 기반 페이지네이션을 사용하세요. 각 목록 응답은 next_cursor를 반환합니다. 그 값을 after_cursor로 전달하여 다음 페이지를 가져오세요. Gamma는 offset 기반 페이지네이션을 HTTP 422로 거부합니다.

고려해야 할 중요한 속도 제한은 무엇인가요?

/markets는 10초당 300 요청 제한이 있습니다. /markets + /events 목록 호출은 합산하여 10초당 900 요청 제한에 포함됩니다. 전체 Gamma API 한도는 10초당 4000 요청입니다. 요청을 시차를 두고 백오프를 구현하여 스로틀링을 피하세요.

실시간 데이터에는 Gamma와 Market WebSocket 중 어느 것을 사용해야 하나요?

메타데이터, 목록, 과거 조회에는 Gamma를 사용하세요. 실시간 주문서와 틱 이벤트에는 Market WebSocket(wss://ws-subscriptions-clob.polymarket.com/ws/market)을 사용하세요. WebSocket은 연결당 최대 500개의 종목을 지원합니다.

태그나 조건으로 시장을 필터링할 수 있나요?

예. Gamma는 tag_id, condition_ids, clob_token_ids, slug 등과 같은 필터를 지원합니다. 특정 필터를 전달하면 페이로드가 줄고 속도 제한 준수에 도움이 됩니다.