Skip to main content
This guide covers everything you need to install and configure the Polymarket CLOB Client in your project.

​
Requirements

Before installing the CLOB Client, ensure your environment meets these requirements:

​
Node.js version

The CLOB Client requires Node.js version 20.10 or higher. Check your Node.js version: 
node --version
If you need to upgrade, we recommend using nvm (Node Version Manager): 
# Install nvm (if you don't have it)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install and use Node.js 20
nvm install 20
nvm use 20
While you can use the client with JavaScript, TypeScript is highly recommended for type safety and better IDE support: 
npm install -D typescript @types/node

​
Package installation

Install the CLOB Client using your preferred package manager: 
npm install @polymarket/clob-client
The package is published as @polymarket/clob-client on npm. The current version is 5.6.0.

​
Wallet library

You’ll need a wallet library to sign transactions. The CLOB Client supports both ethers.js and viem.

​
Option 1: ethers.js (v5.x)

npm install ethers@^5.8.0 @ethersproject/wallet @ethersproject/providers
The CLOB Client currently requires ethers v5.x. Support for ethers v6 is not yet available.

​
Option 2: viem (v2.x)

npm install viem@^2.0.0

​
Additional dependencies

Depending on your use case, you might need these additional packages:

​
Environment variables

For managing environment variables (recommended for security): 
npm install dotenv

​
Axios (included)

The CLOB Client uses axios for HTTP requests. This is included as a dependency and doesn’t need to be installed separately.

​
Environment setup

​
Create environment file

Create a .env file in your project root to store sensitive configuration:
.env
# Wallet Configuration
PK=your_private_key_without_0x_prefix

# Chain Configuration
# 137 = Polygon Mainnet
# 80002 = Polygon Amoy Testnet
CHAIN_ID=137

# CLOB API Configuration
CLOB_API_URL=https://clob.polymarket.com

# API Credentials (generate these using the SDK)
CLOB_API_KEY=
CLOB_SECRET=
CLOB_PASS_PHRASE=

# Optional: Funder address (usually same as your wallet address for EOA)
FUNDER_ADDRESS=

​
Add to .gitignore

Important: Never commit your .env file to version control. Add it to .gitignore:
.gitignore
# Environment variables
.env
.env.local
.env.*.local

# API credentials
api-keys.json
credentials.json

​
Configuration for different environments

​
Mainnet (Production)

For production trading on Polygon mainnet: 
import { Chain } from "@polymarket/clob-client";

const config = {
    host: "https://clob.polymarket.com",
    chainId: Chain.POLYGON, // 137
};

​
Testnet (Development)

For testing on Polygon Amoy testnet: 
import { Chain } from "@polymarket/clob-client";

const config = {
    host: "https://clob.polymarket.com",
    chainId: Chain.AMOY, // 80002
};
The CLOB API URL is the same for both mainnet and testnet. The chainId parameter determines which network you’re using.

​
Initializing the client

​
With ethers.js

import { ethers } from "ethers";
import { ClobClient, Chain, ApiKeyCreds, SignatureType } from "@polymarket/clob-client";
import { config as dotenvConfig } from "dotenv";

dotenvConfig();

// Create wallet from private key
const wallet = new ethers.Wallet(process.env.PK!);

// Set up API credentials
const creds: ApiKeyCreds = {
    key: process.env.CLOB_API_KEY!,
    secret: process.env.CLOB_SECRET!,
    passphrase: process.env.CLOB_PASS_PHRASE!,
};

// Initialize the client
const client = new ClobClient(
    "https://clob.polymarket.com", // host
    Chain.POLYGON,                  // chainId
    wallet,                         // signer
    creds,                          // API credentials
    SignatureType.EOA,              // signature type
    process.env.FUNDER_ADDRESS      // funder address (optional)
);

​
With viem

import { createWalletClient, http } from "viem";
import { polygon } from "viem/chains";
import { privateKeyToAccount } from "viem/accounts";
import { ClobClient, Chain, ApiKeyCreds } from "@polymarket/clob-client";
import { config as dotenvConfig } from "dotenv";

dotenvConfig();

// Create wallet client
const account = privateKeyToAccount(`0x${process.env.PK}`);
const walletClient = createWalletClient({
    account,
    chain: polygon,
    transport: http(),
});

// Set up API credentials
const creds: ApiKeyCreds = {
    key: process.env.CLOB_API_KEY!,
    secret: process.env.CLOB_SECRET!,
    passphrase: process.env.CLOB_PASS_PHRASE!,
};

// Initialize the client
const client = new ClobClient(
    "https://clob.polymarket.com",
    Chain.POLYGON,
    walletClient,
    creds
);

​
Advanced configuration

​
Constructor parameters

The ClobClient constructor accepts these parameters: 
new ClobClient(
    host: string,                    // CLOB API URL
    chainId: Chain,                  // 137 (Polygon) or 80002 (Amoy)
    signer?: ClobSigner,             // Wallet for signing
    creds?: ApiKeyCreds,             // API credentials
    signatureType?: SignatureType,   // 0=EOA, 1=POLY_PROXY, 2=POLY_GNOSIS_SAFE
    funderAddress?: string,          // Address that holds USDC
    geoBlockToken?: string,          // Geo-blocking bypass token
    useServerTime?: boolean,         // Use server time for signatures
    builderConfig?: BuilderConfig,   // Builder API configuration
    getSigner?: () => Promise<ClobSigner> | ClobSigner, // Lazy signer loading
    retryOnError?: boolean,          // Auto-retry failed requests
    tickSizeTtlMs?: number,          // Tick size cache TTL (default: 300000)
    throwOnError?: boolean           // Throw exceptions on API errors
)

​
Signature types

Choose the appropriate signature type based on your wallet: 
import { SignatureType } from "@polymarket/clob-client";

// For standard Ethereum wallets (MetaMask, WalletConnect, etc.)
const signatureType = SignatureType.EOA; // 0

// For Polymarket email/Magic login
const signatureType = SignatureType.POLY_PROXY; // 1

// For Gnosis Safe multisig wallets
const signatureType = SignatureType.POLY_GNOSIS_SAFE; // 2

​
Error handling configuration

By default, API errors are returned as objects. You can configure the client to throw exceptions instead: 
import { ClobClient, ApiError } from "@polymarket/clob-client";

const client = new ClobClient(
    host,
    chainId,
    signer,
    creds,
    undefined,  // signatureType
    undefined,  // funderAddress
    undefined,  // geoBlockToken
    undefined,  // useServerTime
    undefined,  // builderConfig
    undefined,  // getSigner
    undefined,  // retryOnError
    undefined,  // tickSizeTtlMs
    true        // throwOnError - enables exception throwing
);

// Now you can use try/catch
try {
    const book = await client.getOrderBook(tokenId);
} catch (error) {
    if (error instanceof ApiError) {
        console.log(error.message); // Error message
        console.log(error.status);  // HTTP status code
        console.log(error.data);    // Full error response
    }
}

​
Server time synchronization

For better reliability, especially in serverless environments, enable server time synchronization: 
const client = new ClobClient(
    host,
    chainId,
    signer,
    creds,
    undefined,
    undefined,
    undefined,
    true // useServerTime - syncs with server clock
);
Enabling useServerTime prevents signature timestamp mismatches that can occur if your system clock is out of sync.

​
Verifying installation

Create a simple test script to verify your installation:
test.ts
import { ClobClient, Chain } from "@polymarket/clob-client";
import { config as dotenvConfig } from "dotenv";

dotenvConfig();

async function test() {
    // Create a client without authentication for public endpoints
    const client = new ClobClient("https://clob.polymarket.com", Chain.POLYGON);
    
    try {
        // Test server connectivity
        const serverTime = await client.getServerTime();
        console.log("✓ Server time:", new Date(serverTime));
        
        // Test market data access
        const markets = await client.getSimplifiedMarkets();
        console.log(`✓ Found ${markets.count} markets`);
        
        console.log("\n✓ Installation verified successfully!");
    } catch (error) {
        console.error("✗ Installation test failed:", error);
    }
}

test();
Run the test: 
npx tsx test.ts
You should see output confirming the server time and market count.

​
TypeScript configuration

If using TypeScript, ensure your tsconfig.json is configured correctly:
tsconfig.json
{
    "compilerOptions": {
        "target": "ES2022",
        "module": "ESNext",
        "lib": ["ES2022"],
        "moduleResolution": "bundler",
        "esModuleInterop": true,
        "skipLibCheck": true,
        "strict": true,
        "resolveJsonModule": true,
        "allowSyntheticDefaultImports": true
    }
}

​
Next steps

Quickstart

Follow the quickstart guide to place your first order

Authentication

Learn how to generate and manage API credentials

API Reference

Explore the complete API documentation

Examples

Browse code examples for common use cases

​
Troubleshooting

Make sure you’ve installed all required dependencies. If using TypeScript, you may need to install type definitions:
npm install -D @types/node
The CLOB Client is published as an ES module. If you’re using CommonJS, you may need to use dynamic imports:
const { ClobClient } = await import("@polymarket/clob-client");
Or configure your project to use ES modules by adding "type": "module" to your package.json.
The CLOB Client requires ethers v5.x. If you have ethers v6 installed, you’ll need to downgrade:
npm install ethers@^5.8.0
The package requires Node.js 20.10 or higher. Check your version with node --version and upgrade if necessary using nvm or your system’s package manager.
If you encounter SSL certificate errors, it may be due to corporate proxies or network issues. You can set:
export NODE_TLS_REJECT_UNAUTHORIZED=0
Warning: Only use this in development environments, never in production.

​
Additional resources

Build docs developers (and LLMs) love

Get started for freeTalk to us