Tutoriel de l'API Polymarket Gamma

Ce tutoriel de l'API Polymarket Gamma vous apprend à récupérer les marchés et événements depuis la surface Gamma de Polymarket, à gérer la pagination et à appliquer des filtres courants. Les exemples utilisent curl et TypeScript afin que vous puissiez intégrer les lectures dans des bots, tableaux de bord ou pipelines d'analyse.

Points clés

• L'URL de base de Gamma est https://gamma-api.polymarket.com et n'exige pas d'authentification pour les lectures.
• Utilisez les endpoints /markets et /events avec une pagination basée sur curseur via after_cursor ; n'utilisez pas offset.
• Respectez les limites de débit : /markets a 300 req / 10 s ; la limite combinée /markets + /events est de 900 req / 10 s. La limite globale de l'API est de 4000 req / 10 s.
• Filtrez par champs comme condition_ids, clob_token_ids, slug et tag_id pour réduire la charge utile et éviter de frapper les limites.
• Utilisez de petites tailles de page et un backoff exponentiel pour les clients de production.

1. Principes de base de Gamma : endpoints et limites

L'URL de base en lecture de Gamma est :

https://gamma-api.polymarket.com

Les endpoints que vous utiliserez dans ce tutoriel :

• GET /markets — liste des marchés et requêtes sur un marché unique
• GET /events — événements groupés (utile pour les métadonnées au niveau d'un événement)

Limites de débit importantes à prendre en compte :

• /markets : 300 requêtes par 10 secondes
• /markets + /events (listings combinés) : 900 requêtes par 10 secondes
• API Gamma globale : 4000 requêtes par 10 secondes

Si votre client effectue du polling ou remplit de grands jeux de données, regroupez et étalez les requêtes et respectez ces limites.

2. Récupérer des marchés : exemple curl minimal

Une requête minimale pour lister les marchés avec les paramètres par défaut :

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

Pour contrôler la taille de la page (limit) et l'ordre :

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

Remarques :

• la valeur maximale de limit est 1000. La valeur par défaut est 20.
• Gamma rejette la pagination basée sur offset (HTTP 422). Utilisez after_cursor pour la pagination par keyset à la place.

3. Pagination basée sur curseur (after_cursor)

Gamma renvoie un next_cursor dans les réponses de listing. Utilisez cette valeur dans after_cursor pour récupérer la page suivante. L'exemple en TypeScript suit.

Exemple TypeScript (node-fetch ou fetch natif) :

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;
}

Bonnes pratiques montrées :

• Utilisez limit pour contrôler la taille des pages et l'utilisation réseau.
• Respectez next_cursor et arrêtez-vous lorsqu'il est absent.
• Ajoutez de petits délais ou un backoff lorsque vous approchez des limites de débit.

4. Filtrage et paramètres de requête utiles

Gamma prend en charge de nombreux paramètres de requête. Les plus utiles lorsque vous voulez des lectures ciblées :

• slug, id, question_ids, condition_ids, clob_token_ids, market_maker_address — tous des tableaux
• closed (booléen), active, archived
• tag_id — filtrer par catégorie
• order — champs séparés par des virgules comme volume24hr, volume, liquidity, endDate
• ascending — booléen (par défaut true)

Exemple : récupérer les marchés actifs d'un tag, triés par volume 24h décroissant :

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

Quand vous n'avez besoin que de marchés spécifiques, passez des tableaux pour slug ou id afin de réduire la charge utile et éviter les scans larges.

5. Endpoint Events

Le endpoint /events regroupe les marchés sous des métadonnées au niveau d'un événement (par exemple : « 2026 Presidential Election » comme événement contenant plusieurs conditions de marché).

Appel de base :

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

Les events utilisent également after_cursor pour la pagination et partagent la limite de listing combinée avec /markets (900 req / 10 s pour les listings combinés).

6. Exemple TypeScript pratique : récupérer des marchés par condition_ids

Cet exemple récupère les marchés pour une liste d'IDs de condition, avec contrôle de concurrence et backoff exponentiel.

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;
}

Remarques pour un usage en production :

• Utilisez un limiteur de concurrence (p-map, p-limit) si conditionIds est volumineux.
• Mettez en cache les résultats inchangés (ETag/If-None-Match) si l'API les prend en charge pour votre cas d'usage.
• Surveillez votre taux de requêtes vis-à-vis des limites documentées.

7. Pièges courants et dépannage

• N'utilisez pas offset — Gamma renvoie HTTP 422 pour les paramètres offset.
• Demander de très grandes pages sans curseurs peut atteindre les limites de débit et provoquer des pressions mémoire ; privilégiez des limites plus petites et la traversée par curseur.
• Les limites combinées /markets + /events signifient qu'un polling intensif des deux endpoints peut vous throttler rapidement.
• L'API renvoie next_cursor pour la pagination par keyset ; traitez-le comme opaque et retransmettez-le tel quel.

8. Intégration avec les données en temps réel

Gamma est la surface REST pour les métadonnées et les listings historiques. Pour les ordres en temps réel et les événements de tick, utilisez le WebSocket Market à wss://ws-subscriptions-clob.polymarket.com/ws/market. Le WebSocket supporte jusqu'à 500 instruments par connexion et émet price_change, best_bid_ask, last_trade_price et tick_size_change.

Conservez REST pour les backfills et WebSocket pour les mises à jour live.

9. Impact sur vos outils ou votre trading

Si vous construisez des bots de trading, des tableaux de bord ou des pipelines de données, Gamma est la source canonique en lecture pour les métadonnées de marché, les tags et les listings. Utilisez la pagination par curseur, filtrez agressivement et associez les lectures Gamma à l'API CLOB ou au Market WebSocket pour les prix et le carnet d'ordres. Planifiez votre cadence de polling autour des limites documentées pour éviter les throttles.

Gamma est en lecture seule pour les données publiques ; aucune clé API n'est requise pour les exemples ci‑dessus. Pour le placement d'ordres et les opérations de carnet, utilisez l'API CLOB à https://clob.polymarket.com, qui requiert API key + HMAC.

Conclusion

Ce tutoriel Polymarket Gamma API a couvert les étapes pratiques pour récupérer marchés et événements, gérer la pagination par curseur et éviter les pièges courants. Utilisez ces modèles comme base pour des bots et des analyses fiables qui respectent les limites de débit et le modèle de pagination de Gamma.

Questions fréquentes

Ai-je besoin d'une clé API pour lire depuis l'API Gamma ?

Non. Les endpoints publics en lecture de Gamma n'exigent pas d'authentification. L'URL de base est https://gamma-api.polymarket.com. Seul l'endpoint CLOB requiert API key + HMAC pour le trading.

Comment parcourir de larges listes de marchés ?

Utilisez la pagination par curseur. Chaque listing renvoie next_cursor ; passez cette valeur comme after_cursor pour récupérer la page suivante. Gamma rejette la pagination basée sur offset avec HTTP 422.

Quelles sont les limites de débit importantes à considérer ?

/markets a une limite de 300 requêtes par 10 secondes. Les appels de listing combinés /markets + /events comptent pour une limite combinée de 900 req / 10 s. La limite globale de l'API Gamma est de 4000 req / 10 s. Étalez les requêtes et implémentez un backoff pour éviter le throttling.

Dois-je utiliser Gamma ou le Market WebSocket pour les données en temps réel ?

Utilisez Gamma pour les métadonnées, les listings et les lectures historiques. Utilisez le Market WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) pour le carnet d'ordres en temps réel et les événements de tick ; le WebSocket supporte jusqu'à 500 instruments par connexion.

Puis-je filtrer les marchés par tag ou condition ?

Oui. Gamma prend en charge des filtres tels que tag_id, condition_ids, clob_token_ids, slug, et d'autres. Fournir des filtres spécifiques réduit la charge utile et aide à rester dans les limites de débit.