Warning

This package is deprecated. Please migrate to the unified Polymarket SDK. Follow the migration guide to get started.

PY Polymarket CLOB Client V2

Python client for the Polymarket CLOB (v2)

Usage

# pip install py_clob_client_v2

import os
from py_clob_client_v2 import ApiCreds, ClobClient, OrderArgs, OrderType, PartialCreateOrderOptions, Side

host = "<polymarket-clob-host>"
chain_id = 137  # or 80002 for Amoy testnet

# Step 1: obtain API credentials using your wallet (L1 auth)
client = ClobClient(host=host, chain_id=chain_id, key=os.environ["PK"])
creds = client.create_or_derive_api_key()

# Step 2: initialize a fully-authenticated client (L1 + L2)
client = ClobClient(host=host, chain_id=chain_id, key=os.environ["PK"], creds=creds)

# Place a resting limit buy (GTC)
resp = client.create_and_post_order(
    order_args=OrderArgs(
        token_id="",  # token ID of the market outcome — get from https://docs.polymarket.com
        price=0.4,
        side=Side.BUY,
        size=100,
    ),
    options=PartialCreateOrderOptions(tick_size="0.01"),
    order_type=OrderType.GTC,
)
print(resp)

For Polymarket V2 outcomes, pass position_id instead of token_id:

resp = client.create_and_post_order(
    OrderArgs(position_id="456", price=0.4, size=100, side=Side.BUY),
    options=PartialCreateOrderOptions(tick_size="0.01"),
    order_type=OrderType.GTC,
)

Provide exactly one identifier. position_id automatically selects Exchange V3 signing, including when using OrderBuilder directly, and ignores neg_risk and any requested exchange version. Existing token_id orders retain server-selected version routing; PartialCreateOrderOptions(version=1) or version=2 can override it. Signed orders and HTTP payloads still use the protocol field tokenId for both kinds of identifier.

See examples for more information.

Market Orders

from py_clob_client_v2 import MarketOrderArgs

# 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
resp = client.create_and_post_market_order(
    order_args=MarketOrderArgs(
        token_id="",
        amount=100,  # USDC
        side=Side.BUY,
        order_type=OrderType.FOK,
    ),
    options=PartialCreateOrderOptions(tick_size="0.01"),
    order_type=OrderType.FOK,
)
print(resp)

Position-backed market orders use the same workflow and amount units:

resp = client.create_and_post_market_order(
    MarketOrderArgs(position_id="456", amount=100, side=Side.BUY),
    options=PartialCreateOrderOptions(tick_size="0.01"),
    order_type=OrderType.FOK,
)

Authentication

The client has two authentication levels:

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

client = ClobClient(host=host, chain_id=chain_id, key=os.environ["PK"])
creds = client.create_or_derive_api_key()

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

creds = ApiCreds(
    api_key=os.environ["CLOB_API_KEY"],
    api_secret=os.environ["CLOB_SECRET"],
    api_passphrase=os.environ["CLOB_PASS_PHRASE"],
)
client = ClobClient(host=host, chain_id=chain_id, key=os.environ["PK"], creds=creds)