@rich-apis/polymarket-sdk

TypeScript SDK for building on Polymarket. Typed clients for the Gamma, Data, and CLOB APIs with built-in rate limiting, retries, and error handling.

Save 40+ hours of API integration. Start building strategies, not infrastructure.

Install

npm install @rich-apis/polymarket-sdk

Requires Node.js >= 18. Zero runtime dependencies.

Quick Start

import { GammaClient } from "@rich-apis/polymarket-sdk";

const gamma = new GammaClient();

// Top markets by 24h volume
const markets = await gamma.getTopMarkets(10);
for (const m of markets) {
  console.log(`${m.question} — $${m.volume24hr.toLocaleString()}`);
}

// Search for specific markets
const results = await gamma.searchMarkets("presidential election");

// Markets closing in the next 12 hours
const closing = await gamma.getClosingSoon(12);

What's Included

Free (npm package)

| Client | API | What it does | |--------|-----|-------------| | GammaClient | gamma-api.polymarket.com | Markets, events, search, categories |

Full Version ($69 USDC)

Everything in free, plus:

| Client | API | What it does | |--------|-----|-------------| | DataClient | data-api.polymarket.com | Trades, positions, large trade streaming | | CLOBClient | clob.polymarket.com | Order books, spreads, depth, prices |

Plus three production-ready examples:

• top-whales.ts — Whale activity detector across top markets
• large-trades.ts — Real-time large trade stream with terminal UI
• market-scanner.ts — Find markets by liquidity, spread, and volume criteria

Get the full version: rich-apis.store/polymarket-sdk

API Reference

GammaClient

const gamma = new GammaClient({
  maxConcurrent: 5,    // parallel request limit (default: 5)
  maxRetries: 3,       // retries on 429/5xx (default: 3)
  timeoutMs: 15000,    // request timeout (default: 15s)
});

Markets

// Filtered query
const markets = await gamma.getMarkets({
  limit: 20,
  active: true,
  category: "politics",
  order: "volume24hr",
  ascending: false,
});

// Single market by slug
const market = await gamma.getMarket("will-trump-win-2024");

// Parsed markets (JSON fields decoded for you)
const parsed = await gamma.getParsedMarkets({ limit: 10 });
// parsed[0].parsedOutcomes => ["Yes", "No"]
// parsed[0].parsedOutcomePrices => [0.65, 0.35]
// parsed[0].parsedClobTokenIds => ["12345...", "67890..."]

Events

const events = await gamma.getEvents({
  limit: 10,
  active: true,
  category: "sports",
});

const event = await gamma.getEvent("super-bowl-2026");

Search & Shortcuts

// Keyword search
const results = await gamma.searchMarkets("bitcoin", 5);

// Top markets by volume
const top = await gamma.getTopMarkets(10);

// Closing soon
const expiring = await gamma.getClosingSoon(24); // next 24 hours

// By category
const politics = await gamma.getMarketsByCategory("politics", 20);

DataClient (Full Version)

import { setLicenseKey, createDataClient } from "@rich-apis/polymarket-sdk";

setLicenseKey(process.env.POLYMARKET_SDK_KEY!);
const data = createDataClient();

// Recent trades
const trades = await data.getTrades({ limit: 50 });

// Large trades only
const whales = await data.getLargeTrades(10_000, 20);

// Stream large trades in real-time
const { stop } = data.streamLargeTrades(5000, (trades) => {
  for (const t of trades) {
    console.log(`${t.side} $${t.size} on "${t.title}" by ${t.pseudonym}`);
  }
}, 10_000); // poll every 10s

// Stop streaming
stop();

CLOBClient (Full Version)

import { setLicenseKey, createCLOBClient } from "@rich-apis/polymarket-sdk";

setLicenseKey(process.env.POLYMARKET_SDK_KEY!);
const clob = createCLOBClient();

// Full order book
const book = await clob.getOrderBook(tokenId);
// book.bids => [{ price: "0.65", size: "1500" }, ...]
// book.asks => [{ price: "0.66", size: "800" }, ...]

// Derived metrics
const mid = await clob.getMidPrice(tokenId);     // 0.655
const spread = await clob.getSpread(tokenId);     // 0.01
const depth = await clob.getDepth(tokenId);       // { bidDepth: 45000, askDepth: 32000 }

// Last trade
const last = await clob.getLastTradePrice(tokenId);

// Order books for all outcomes of a market
const books = await clob.getOrderBooksForMarket(clobTokenIds);

Error Handling

Every client throws typed errors:

import {
  PolymarketError,
  RateLimitError,
  ApiNotFoundError,
  ApiValidationError,
  LicenseRequiredError,
} from "@rich-apis/polymarket-sdk";

try {
  const market = await gamma.getMarket("nonexistent-slug");
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log(`Rate limited. Retry in ${err.retryAfterMs}ms`);
  } else if (err instanceof ApiNotFoundError) {
    console.log("Market does not exist");
  } else if (err instanceof LicenseRequiredError) {
    console.log("Upgrade to full version for this feature");
  }
}

Rate Limiting

Built-in, no configuration needed:

• Concurrency cap: max 5 parallel requests (configurable)
• Automatic retry: 429 and 5xx responses trigger exponential backoff
• Respect Retry-After headers when the API sends them
• Timeout: 15s per request (configurable)

Configuration

All clients accept the same options:

interface BaseClientOptions {
  baseUrl?: string;         // Override API base URL
  maxConcurrent?: number;   // Max parallel requests (default: 5)
  maxRetries?: number;      // Retry count for 429/5xx (default: 3)
  retryBaseDelayMs?: number; // Base retry delay in ms (default: 1000)
  timeoutMs?: number;       // Request timeout in ms (default: 15000)
}

License Key Setup (Full Version)

Two ways to provide your license key:

// Option 1: In code
import { setLicenseKey } from "@rich-apis/polymarket-sdk";
setLicenseKey("POLY-SDK-xxxxxxxx-xxxxxxxxxxxx");

// Option 2: Environment variable
// export POLYMARKET_SDK_KEY="POLY-SDK-xxxxxxxx-xxxxxxxxxxxx"

Requirements

• Node.js >= 18 (uses native fetch)
• TypeScript >= 5.0 (for full type support)
• Zero runtime dependencies

Changelog

1.0.0

• GammaClient: markets, events, search, parsed markets
• DataClient: trades, positions, large trade streaming
• CLOBClient: order books, spreads, depth, prices
• Typed errors with automatic retry
• Rate limit handling with exponential backoff

This is an analytical tool. Not financial advice. Past data does not predict future results.