@igoforth/polymarket-api

TypeScript API clients for Polymarket with a fluent MarketBuilder, WebSocket clients, rate limiting, and generated endpoints from OpenAPI specs.

Features

• MarketBuilder — Fluent API that selects which upstream APIs to call based on requested fields, with presets like withBackfill() and withPricing()
• WebSocket clients — CLOB orderbook, Polymarket LiveData, and Binance price feeds with automatic reconnection
• Connection manager — WebSocket connection pooling with bandwidth monitoring and rebalancing
• Rate limiting — Per-endpoint Bottleneck limiters with burst/sustained modes and lazy initialization (Cloudflare Workers compatible)
• Generated clients — Orval-generated endpoints for Gamma, CLOB, and Data APIs from official OpenAPI specs
• Retry logic — Exponential backoff with 429/5xx handling and Chainlink-specific error recovery

Installation

pnpm add @igoforth/polymarket-api

Quick Start

MarketBuilder

import { queryMarkets } from "@igoforth/polymarket-api/builder";

const markets = await queryMarkets()
  .withPricing()
  .where({ closed: false, active: true })
  .limit(10)
  .execute();

WebSocket — CLOB Orderbook

import { ClobWebSocketClient } from "@igoforth/polymarket-api/websocket/clob";

const ws = new ClobWebSocketClient();
ws.subscribeToMarket(tokenId, (update) => {
  console.log("Orderbook update:", update);
});

Generated API Clients

// Gamma API
import { listMarkets } from "@igoforth/polymarket-api/gamma/markets";
const result = await listMarkets({ limit: 10, active: true });

// CLOB API
import { getBook } from "@igoforth/polymarket-api/clob/orderbook";
const book = await getBook({ token_id: "0x..." });

// Data API
import { getActivity } from "@igoforth/polymarket-api/data/core";
const activity = await getActivity({ user: "0x..." });

Binance Price Feed

import { BinanceWebSocketClient } from "@igoforth/polymarket-api/websocket/binance";

const ws = new BinanceWebSocketClient();
ws.subscribe("btcusdt@ticker", (data) => {
  console.log("BTC price:", data.c);
});

API Coverage

| API | Module | Description | |-----|--------|-------------| | Gamma | gamma/* | Markets, events, tags, series, profiles, search, comments | | CLOB | clob/* | Orderbook, pricing, spreads, market metadata, rewards | | Data | data/* | Trades, positions, activity, builder queries | | Crypto | crypto/* | Website crypto markets, prices, OHLCV candles | | WebSocket | websocket/* | CLOB, LiveData, Binance with connection pooling | | Builder | builder | Fluent market query API with field-level source resolution |

Regenerating API Clients

The generated clients are built from Polymarket's official OpenAPI specs:

pnpm generate

This runs Orval against the Gamma, CLOB, and Data API specs.

License

MIT