About clob-client-v2

clob-client-v2 is a TypeScript client library designed for interacting with Polymarket's Central Limit Order Book (CLOB) Version 2. It enables developers to build applications for trading prediction market outcomes on Polygon and Amoy testnet. The library supports placing resting limit orders (Good-Til-Cancelled) and market orders (Fill-or-Kill or Fill-and-Kill) via a simple API. Authentication is handled through a two-tier system: Level 1 uses EIP-712 wallet signatures to derive or create API keys, while Level 2 utilizes HMAC credentials for executing orders, cancellations, and retrieving account data or order books. The client prioritizes developer experience with robust error handling that can be configured to throw typed exceptions or return customizable error objects. Installation is via standard package managers like npm or yarn. Key features include support for multiple order types, seamless integration with viem for wallet management, and methods to manage the full trading lifecycle from authorization

d

Published by

dev-polymarket

Visit View Profile

README.md

View on GitHub

Polymarket CLOB Client V2

TypeScript client for the Polymarket CLOB (v2)

Installation (choose your package manager)

npm i @polymarkets/clob-client-v2           # npm / pnpm / yarn

Usage

// npm install @polymarkets/clob-client-v2
// npm install viem

import { ApiKeyCreds, Chain, ClobClient, OrderType, Side } from "@polymarkets/clob-client-v2";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";

const host = "<polymarket-clob-host>";
const chainId = Chain.POLYGON; // or Chain.AMOY for testnet

const account = privateKeyToAccount("0x..."); // your private key
const walletClient = createWalletClient({ account, transport: http() });

// Step 1: obtain API credentials using your wallet (L1 auth)
const clobClient = new ClobClient({ host, chain: chainId, signer: walletClient });
const creds = await clobClient.createOrDeriveApiKey();

// Step 2: initialize a fully-authenticated client (L1 + L2)
const client = new ClobClient({ host, chain: chainId, signer: walletClient, creds });

// Place a resting limit buy (GTC)
const resp = await client.createAndPostOrder(
    {
        tokenID: "", // token ID of the market outcome — get from https://docs.polymarket.com
        price: 0.4,
        side: Side.BUY,
        size: 100,
    },
    { tickSize: "0.01" },
    OrderType.GTC,
);
console.log(resp);

See examples for more information.

Market Orders

// Market buy — amount is in USDC
// OrderType.FOK: entire order must fill immediately or it is cancelled
// OrderType.FAK: fills as much as possible, remainder is cancelled
const resp = await client.createAndPostMarketOrder(
    {
        tokenID: "",
        amount: 100, // USDC
        side: Side.BUY,
        orderType: OrderType.FOK,
    },
    { tickSize: "0.01" },
    OrderType.FOK,
);
console.log(resp);

Authentication

The client has two authentication levels:

L1 — wallet signature (EIP-712). Required to create or derive API keys.

const client = new ClobClient({ host, chain: chainId, signer: walletClient });
const creds = await client.createOrDeriveApiKey();

L2 — HMAC with API credentials. Required for order placement, cancellation, and account data.

const creds: ApiKeyCreds = {
    key: process.env.CLOB_API_KEY,
    secret: process.env.CLOB_SECRET,
    passphrase: process.env.CLOB_PASS_PHRASE,
};
const client = new ClobClient({ host, chain: chainId, signer: walletClient, creds });

Error Handling

By default, API errors are returned as { error: "...", status: ... } objects. To have the client throw instead, pass throwOnError: true:

import { ApiError, ClobClient } from "@polymarkets/clob-client-v2";

const client = new ClobClient({ host, chain: chainId, signer: walletClient, creds, throwOnError: true });

try {
    const book = await client.getOrderBook(tokenID);
} catch (e) {
    if (e instanceof ApiError) {
        console.log(e.message); // "No orderbook exists for the requested token id"
        console.log(e.status);  // 404
        console.log(e.data);    // full error response object
    }
}

clob-client-v2