Polymarket Python CLOB Client

To perform read-only operations (like checking server time or getting market data) without authentication, initialize ClobClient with only the host URL.

from py_clob_client.client import ClobClient

client = ClobClient("https://clob.polymarket.com")  # Level 0 (no auth)

ok = client.get_ok()
time = client.get_server_time()
print(ok, time)

Install the Polymarket Python CLOB client using pip. Requires Python 3.9 or higher.

# install from PyPI (Python 3.9>)
pip install py-clob-client

The ClobClient uses a tiered authentication model to control access to different API capabilities:

• Level 0 (L0): Unauthenticated. Use this for public data like market information or order books.
• Level 1 (L1): Signer-based authentication. Requires a private key. This level is necessary for signing and creating orders (create_order, create_market_order).
• Level 2 (L2): API Key authentication. Requires both a Signer (private key) and ApiCreds. This level is required for managing orders (cancel, get_orders), managing API keys, and accessing user-specific data like get_trades or get_notifications.

Methods like assert_level_1_auth() and assert_level_2_auth() are used internally to ensure the client is configured with sufficient permissions for the requested action.

The ClobClient is the primary entrypoint for interacting with the Polymarket CLOB API. It can be initialized in three authentication modes depending on the level of access required:

1. Level 0: Requires only the host URL. Provides access to unauthenticated/open endpoints.
2. Level 1: Requires host, chain_id, and a private key. Provides access to L1 authenticated endpoints (e.g., creating orders).
3. Level 2: Requires host, chain_id, key, and creds (ApiCreds). Provides access to all endpoints, including order management and API key operations.

If a key is provided, the client initializes a Signer and an OrderBuilder.

If you are using MetaMask or a hardware wallet, you must grant permission (allowance) to Polymarket exchange contracts to access your funds. This only needs to be done once per wallet.

Tokens to Approve

1. USDC (Trading currency): 0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174
2. Conditional Tokens (Outcome tokens): 0x4D97DCd97eC945f40cF65F87097ACe5EA0476045

Contracts to Approve For

You must approve both tokens for the following three contracts:

• 0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E (Main exchange)
• 0xC5d563A36AE78145C45a50134d48A1215220f80a (Neg risk markets)
• 0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296 (Neg risk adapter)

Use the authenticated or read-only client to retrieve market information. You will need a token_id (obtainable via the Gamma Markets API).

from py_clob_client.client import ClobClient
from py_clob_client.clob_types import BookParams

client = ClobClient("https://clob.polymarket.com")  # read-only

token_id = "<token-id>"  # Get a token ID: https://docs.polymarket.com/developers/gamma-markets-api/get-markets

mid = client.get_midpoint(token_id)
price = client.get_price(token_id, side="BUY")
book = client.get_order_book(token_id)
books = client.get_order_books([BookParams(token_id=token_id)])
print(mid, price, book.market, len(books))

Retrieve open orders using get_orders with OpenOrderParams and cancel them using cancel(order_id) or cancel_all().

from py_clob_client.client import ClobClient
from py_clob_client.clob_types import OpenOrderParams

HOST = "https://clob.polymarket.com"
CHAIN_ID = 137
PRIVATE_KEY = "<your-private-key>"
FUNDER = "<your-funder-address>"

client = ClobClient(
    HOST,  # The CLOB API endpoint
    key=PRIVATE_KEY,  # Your wallet's private key
    chain_id=CHAIN_ID,  # Polygon chain ID (137)
    signature_type=1,  # 1 for email/Magic wallet signatures
    funder=FUNDER  # Address that holds your funds
)
client.set_api_creds(client.create_or_derive_api_creds())

open_orders = client.get_orders(OpenOrderParams())

order_id = open_orders[0]["id"] if open_orders else None
if order_id:
    client.cancel(order_id)

client.cancel_all()

Manage active orders using the following methods. All require Level 2 authentication:

• cancel(order_id): Cancels a specific order by its ID.
• cancel_orders(order_ids: list): Cancels multiple orders by providing a list of IDs.
• cancel_all(): Cancels all available orders for the authenticated user.
• cancel_market_orders(market: str = "", asset_id: str = ""): Cancels orders associated with a specific market or asset ID.

Access user-specific data. These methods require Level 2 authentication:

• get_orders(params: OpenOrderParams = None, next_cursor="MA=="): Gets open orders for the API key. Supports pagination via next_cursor.
• get_order(order_id): Fetches a specific order by ID.
• get_trades(params: TradeParams = None, next_cursor="MA=="): Fetches trade history for the user. Supports pagination.
• get_balance_allowance(params: BalanceAllowanceParams = None): Fetches user balance and allowance.
• update_balance_allowance(params: BalanceAllowanceParams = None): Updates balance allowance.
• get_notifications(): Fetches user notifications.
• drop_notifications(params: DropNotificationParams = None): Drops user notifications.