clob-client-v2: the TypeScript client for Polymarket's V2 CLOB

What clob-client-v2 actually does for a Polymarket trader

Polymarket's CLOB is a central limit order book, which means orders are signed messages rather than simple HTTP form posts. A wallet key signs an order, the exchange verifies that signature, and the order rests in the book until it fills or is cancelled. Doing that by hand means implementing EIP-712 typed data hashing, tracking tick sizes, and managing a second set of API credentials that are separate from the wallet. This package exists to absorb that work.

The intended user is a developer writing a bot, a market maker, or an internal tool in TypeScript or JavaScript. The package is published as @polymarkets/clob-client-v2, ships as ESM and CommonJS through its exports map, and declares viem, axios and two ethers v5 packages as runtime dependencies. It is not a trading UI and it is not a strategy library. It is the transport and signing layer between your code and the exchange.

Two authentication layers and how an order reaches the book

The design splits authentication in two, and the README is explicit about the boundary. L1 is a wallet signature using EIP-712, and it is required to create or derive API keys. L2 is HMAC with API credentials, and it is required for order placement, cancellation, and account data. A client constructed with only a signer can call createOrDeriveApiKey but cannot trade. A client constructed with signer and creds can do both.

The data flow for a limit order runs through createAndPostOrder, which takes the order parameters (tokenID, price, side, size) plus an options object carrying tickSize, and an OrderType. The client signs the order with the L1 wallet, attaches the L2 HMAC credentials, and posts it. Market orders take a different path: createAndPostMarketOrder uses an amount in USDC rather than a size in shares, and the order type determines fill behaviour. OrderType.FOK means the entire order must fill immediately or it is cancelled. OrderType.FAK fills as much as possible and cancels the remainder.

One structural detail worth noting: the package lists both viem and @ethersproject/wallet as dependencies. That is a real footprint for a client library, and it means a project already standardised on ethers v6 will be pulling in v5 packages alongside it.

Installing clob-client-v2 and placing a first order

Installation is a single npm command. The README notes it works with npm, pnpm or yarn.

npm i @polymarkets/clob-client-v2

The usage example also requires viem, which is where the wallet client and private key account come from. The README shows it as a separate install.

npm install viem

Authentication comes first. You build a wallet client from a private key, construct a ClobClient with the host, chain and signer, then call createOrDeriveApiKey to get L2 credentials. Chain.POLYGON is mainnet and Chain.AMOY is testnet.

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;
const account = privateKeyToAccount("0x...");
const walletClient = createWalletClient({ account, transport: http() });

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

With credentials in hand, you construct a second client and place a resting limit buy. The tokenID is the token ID of the market outcome, and the README points to https://docs.polymarket.com for it rather than supplying one.

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

const resp = await client.createAndPostOrder(
    { tokenID: "", price: 0.4, side: Side.BUY, size: 100 },
    { tickSize: "0.01" },
    OrderType.GTC,
);
console.log(resp);

If you already have credentials stored, you can skip the derivation step and pass them in directly as an ApiKeyCreds object with key, secret and passphrase. The README's example reads those three from environment variables named CLOB_API_KEY, CLOB_SECRET and CLOB_PASS_PHRASE. The repository also contains an examples/ directory with subfolders for abi, account, builders, keys, market, orders and scoring, which is where the README sends you for more detail.

Error handling, and the one option you should decide early

By default the client does not throw on API errors. It returns objects shaped like { error: "...", status: ... }. That is a deliberate choice and it suits batch jobs where you want to inspect a failure and continue. It does not suit code that expects exceptions, and a caller who forgets to check the returned object will silently treat a rejected order as a success.

Passing throwOnError: true switches the client to throwing ApiError instances instead. The README's example catches one and reads e.message, e.status and e.data, with a 404 and the message "No orderbook exists for the requested token id" as the illustration. The e.data field carries the full error response object, so nothing is lost by switching modes. Decide which mode you want before you write the surrounding control flow, because retrofitting try/catch around a dozen call sites is tedious.

Where the documentation stops and you have to supply the rest

The README does not document rollback, and it does not document rate limits, retry behaviour, or what happens to an in-flight order when the process dies. Those are the questions that matter in production, and the answers are not in the repository's front page.

More concretely, the README never gives the actual CLOB host. It shows the literal string "<polymarket-clob-host>" and defers to https://docs.polymarket.com. It also leaves tokenID empty with a comment pointing at the same docs site. So the first thing a new user must do is leave this repository and read the API documentation, which is a reasonable split but means the README alone is not enough to get an order onto the book.

The examples/ directory is the other place to look, and the README says so directly. It is organised by topic rather than by tutorial order, so expect to read several files to assemble a working flow. The licence is MIT, declared both in the LICENSE file and in package.json, which places essentially no conditions on commercial use, modification or redistribution beyond retaining the notice. That is not legal advice, and anyone embedding the client in a regulated trading product should have their own counsel review the exchange's terms separately from the library's licence.

When a TypeScript client is the wrong choice

The related search terms around this project include py-clob-client, py_clob_client v2, clob client v2 python, pip py_clob_client v2, clob client v2 python and rs clob client v2. That is the clearest signal of the alternative: if your stack is Python or Rust, this package is not for you. The difference is not cosmetic. A Python client lets you stay in the same runtime as your data pipeline and your notebook-based research, and a Rust client gives you a single static binary with no Node runtime to deploy. Choosing clob-client-v2 means committing to a Node process, a package manager, and a dependency tree that includes both viem and ethers v5.

There is also a category of user for whom no client library is right. If you are placing a handful of manual orders, the Polymarket web interface does the signing for you, and pulling in a wallet key to script three trades a month adds key-management risk for no gain. The client earns its place when order volume, latency or automation justify holding a private key in a process you control.

Maintenance, upgrades and what to check before you depend on it

The repository is not archived. Its last push was on 2026-06-06, and the most recent release is version 1.0.5 from 2026-05-13, preceded by 1.0.4 and 1.0.3 on 2026-05-09. Note that package.json in the repository still declares version 1.0.4 while the release list shows 1.0.5, so the manifest and the published tag are not in lockstep. If version pinning matters to you, check the published package rather than the file.

Upgrade cost is mostly driven by the dependency surface. The client depends on viem ^2.46.3, axios ^1.0.0, tslib ^2.8.1, browser-or-node ^3.0.0, and @ethersproject/providers and @ethersproject/wallet at ^5.8.0. The ethers v5 packages are the ones to watch: the wider ecosystem has moved on, and a project that standardises on ethers v6 will carry both trees. The build is tsup, linting and formatting are Biome, and tests run under vitest, all of which are current tooling choices rather than legacy ones.

Because the repository is a client for a hosted exchange, the API is the real versioning surface. A minor bump in the client can be forced by a change on the exchange side, and the README does not describe a compatibility policy for that. Pin the version you test against and read the examples/ directory on each upgrade.

Editorial conclusion

Adopt it if you are building a TypeScript or JavaScript service that places or cancels Polymarket CLOB orders and you want the EIP-712 signing and HMAC credentials handled for you. Do not adopt it if you need a Python or Rust client, or if you want the library to tell you the CLOB host, because the README leaves that as a placeholder. Before writing any order code, confirm the correct host value for mainnet and for Chain.AMOY, confirm the tick size for the specific market you intend to trade, and decide whether you want throwOnError set to true or the default error objects. The repository's last push was on 2026-06-06, so check the examples/ directory against the API you are calling rather than assuming the README is current.

Frequently asked questions

Official sources

1. dev-polymarket/clob-client-v2 on GitHub
2. License: MIT
3. Project website
4. README
5. Releases