Polymarket API Reference

The @dicedhq/polymarket package provides a TypeScript client that combines both CLOB (order book) and Gamma (market data) APIs in a single convenient interface.

Installation

npm install @dicedhq/polymarket viem

yarn add @dicedhq/polymarket viem

pnpm add @dicedhq/polymarket viem

bun add @dicedhq/polymarket viem

Features

Unified Interface: Access both CLOB and Gamma APIs from a single client
Type-Safe: Comprehensive TypeScript types for all operations
Error Handling: Robust error handling with custom error types
Automatic Retries: Built-in retry logic for transient failures
Rate Limiting: Automatic handling of rate limit errors
Authentication: HMAC-SHA256 signature authentication
Flexible Configuration: Use with or without signing server

Requirements

Node.js >= 22.x or Bun >= 1.3.x
TypeScript >= 5.x (for development)

Client Initialization

Basic Setup

import { Polymarket, createConnectedWallet } from "@dicedhq/polymarket";
import type { Credentials } from "@dicedhq/polymarket";

const wallet = createConnectedWallet({
  privateKey: process.env.PRIVATE_KEY,
  chain: "polygon",
});

const credentials: Credentials = {
  key: process.env.POLYMARKET_API_KEY,
  secret: process.env.POLYMARKET_SECRET,
  passphrase: process.env.POLYMARKET_PASSPHRASE,
};

const client = new Polymarket({
  clob: {
    wallet,
    credentials,
  },
});

Order Attribution

const polymarket = new Polymarket({
  clob: {
    wallet,
    credentials,
    attributor: {
      url: "https://your-signing-server.com/api/sign",
      token: process.env.SIGNING_SERVER_TOKEN,
    },
  },
});

Benefits:

Earn Rebates: Orders attributed to your Builder Program account
Security: Builder credentials never exposed in client code
High Performance: Built with Bun for high-throughput signing
Easy Deployment: Simple Docker setup available

See the Order Attribution Guide for complete setup and deployment instructions.

API Access

The Polymarket client provides access to both CLOB and Gamma APIs through separate namespaces:

CLOB API

Access trading operations through client.clob:

// Get markets
const markets = await polymarket.clob.market.list();

// Create an order
const order = await polymarket.clob.order.createOrder({
  price: 0.5,
  side: "BUY",
  size: 10,
  tokenId: "...",
  expiration: 1000000000,
  taker: "public",
});

// Get your orders
const orders = await polymarket.clob.order.list();

// Cancel an order
await polymarket.clob.order.cancel({ orderId: "..." });

See the CLOB API Reference for complete documentation.

Gamma API

Access market data through client.gamma:

// Get current markets
const markets = await polymarket.gamma.market.listCurrent({ limit: 10 });

// Get events
const events = await polymarket.gamma.event.list({
  active: true,
  limit: 10,
});

// Get sports
const sports = await polymarket.gamma.sport.list();

// Get tags
const tags = await polymarket.gamma.tag.list({ limit: 10 });

See the Gamma API Reference for complete documentation.

Configuration Options

ClobConfig

Configuration options for the CLOB client:

interface ClobConfig {
  wallet: ConnectedWallet;      // Wallet for signing transactions
  credentials: Credentials;      // API credentials
  attributor?: AttributorConfig; // Optional signing server
  debug?: boolean;              // Enable debug logging
  retries?: number;             // Number of automatic retries
}

GammaConfig

Configuration options for the Gamma client:

interface GammaConfig {
  debug?: boolean;   // Enable debug logging
  retries?: number;  // Number of automatic retries
}

AttributorConfig

Configuration for external signing server:

interface AttributorConfig {
  url: string;  // Signing server endpoint URL
  token: string; // Bearer token for authentication
}

Wallet Configuration

Create a connected wallet for signing transactions:

import { createConnectedWallet } from "@dicedhq/polymarket";

const wallet = createConnectedWallet({
  privateKey: process.env.PRIVATE_KEY,
  chain: "polygon", // or "polygon-amoy" for testnet
});

Supported chains:

polygon - Polygon mainnet
polygon-amoy - Polygon Amoy testnet

API Credentials

CLOB API requires API credentials for authenticated endpoints:

interface Credentials {
  key: string;       // API key
  secret: string;    // API secret
  passphrase: string; // API passphrase
}

Error Handling

The Polymarket client uses the same error types as individual packages:

import {
  ApiError,
  RateLimitError,
  AuthenticationError,
  NetworkError,
  ValidationError,
} from "@dicedhq/polymarket";

try {
  const markets = await client.clob.market.list();
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log("Rate limited, retry after:", error.retryAfter);
  } else if (error instanceof AuthenticationError) {
    console.log("Authentication failed:", error.message);
  } else if (error instanceof NetworkError) {
    console.log("Network error:", error.message);
  }
}

See the Error Handling Guide for best practices.

When to Use Individual Packages

Consider using individual packages instead of the unified client when:

You only need CLOB or Gamma functionality (smaller bundle size)
You want more granular dependency management

import { Clob } from "@dicedhq/clob";
import { Gamma } from "@dicedhq/gamma";

const clob = new Clob({
  wallet,
  credentials,
});

const gamma = new Gamma();

Examples

Check out the examples in the repository: