npm package: @igoforth/polymarket-api
Description: Polymarket API clients with fluent MarketBuilder, WebSocket clients, rate limiting, and generated endpoints from OpenAPI specs
Author: Ian Goforth
Latest version: 1.0.0

# @igoforth/polymarket-api

TypeScript API clients for [Polymarket](https://polymarket.com) 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

```bash
pnpm add @igoforth/polymarket-api
```

## Quick Start

### MarketBuilder

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

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

### WebSocket — CLOB Orderbook

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

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

### Generated API Clients

```typescript
// 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

```typescript
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:

```bash
pnpm generate
```

This runs [Orval](https://orval.dev) against the Gamma, CLOB, and Data API specs.

## License

MIT