How polymarket/py-clob-client works
This repository is a Python SDK, not a service application. Its architecture is centered on a single client library that talks to the Polymarket CLOB HTTP API, plus a set of helper subsystems for authentication, order construction, and RFQ workflows.
Overall shape
The main runtime boundary is:
• User code / examples / tests
- calls into
• py_clob_client SDK
- which builds requests, signs them when needed, and sends them over HTTP to
• Polymarket CLOB API
- plus related RFQ endpoints and market/order endpoints
There is no database, queue, or background worker in this repo. The only external dependency of the library at runtime is the remote Polymarket API and, for signed flows, the wallet/key material used to generate signatures.
Primary entry point
py_clob_client.client.ClobClient
This is the central façade of the SDK. All example scripts instantiate ClobClient and then call methods like:
• read-only market and book queries
• authenticated account queries
• order creation and posting
• cancellations
• token/allowance and balance-related operations
• RFQ-related operations through the same high-level client surface or via the RFQ module
Architecturally, ClobClient is the orchestrator that ties together:
• endpoint paths from endpoints.py
• runtime config from config.py and constants.py
• auth/header generation from headers/
• HTTP request helpers from http_helpers/
• signing logic from signing/
• order-building utilities from order_builder/
• RFQ-specific logic from rfq/
Major subsystems
1. HTTP and endpoint layer
Files:
• py_clob_client/endpoints.py
• py_clob_client/http_helpers/helpers.py
• py_clob_client/http_helpers/__init__.py
This layer is responsible for:
• defining the API routes used by the SDK
• constructing query strings and request payloads
• executing HTTP calls
• normalizing low-level request/response handling
This is the boundary between SDK logic and the remote Polymarket service. It is where transport concerns live, separate from trading logic and signing.
2. Authentication and headers
Files:
• py_clob_client/headers/headers.py
• py_clob_client/headers/__init__.py
• py_clob_client/signer.py
The SDK supports multiple authorization levels, which the README describes as:
• Level 0 / read-only: no auth
• authenticated trading flows using key material and API credentials
The headers subsystem generates request headers required by the API. It likely combines:
• API credentials
• signature metadata
• request-specific values such as timestamps or nonces
This layer is the boundary between “plain HTTP request” and “authenticated API request.”
3. Signing subsystem
Files:
• py_clob_client/signing/eip712.py
• py_clob_client/signing/hmac.py
• py_clob_client/signing/model.py
• py_clob_client/signing/__init__.py
This is a distinct crypto/auth layer. The presence of both EIP-712 and HMAC indicates two different signing domains:
• EIP-712: structured Ethereum-style signing for order or account actions tied to wallet keys
• HMAC: API credential signing for request authentication
This subsystem is critical to the architecture because it separates:
• wallet/private-key signing
• API request authentication
• data models used to represent signed payloads
The README’s mention of different signature_type values and funder/proxy wallets maps directly to this layer: the same client can sign with different wallet semantics depending on the user’s wallet type.
4. Order builder
Files:
• py_clob_client/order_builder/builder.py
• py_clob_client/order_builder/helpers.py
• py_clob_client/order_builder/constants.py
This subsystem transforms user intent into exchange-compatible order structures.
From the README and examples, it supports:
• limit orders
• market orders
• order post-only / FOK / GTC semantics
• order signing and submission payload preparation
The order builder sits between:
• high-level order arguments such as token ID, price, size, side, and order type
• low-level signed order payloads that the API accepts
It is an important boundary because the SDK does not just pass through user input; it computes the correct order shape before signing and submitting.
5. RFQ subsystem
Files:
• py_clob_client/rfq/rfq_client.py
• py_clob_client/rfq/rfq_helpers.py
• py_clob_client/rfq/rfq_types.py
• py_clob_client/rfq/__init__.py
RFQ is treated as its own subsystem, not just another endpoint group. That suggests the request/quote flow has specialized payloads and query parameters.
The RFQ subsystem likely handles:
• quote creation and cancellation
• request creation and cancellation
• fetching best quotes, quotes, and requests
• RFQ-specific request payload shaping and query parameter encoding
In architecture terms, RFQ is a specialized trading workflow layered on top of the same HTTP/signing infrastructure, but with separate domain types and helpers because its payloads differ from normal order placement.
6. Type system / domain models
Files:
• py_clob_client/clob_types.py
• py_clob_client/rfq/rfq_types.py
• py_clob_client/signing/model.py
These files define the domain objects and typed arguments used across the SDK, such as:
• order arguments
• market order arguments
• book parameters
• open order filters
• RFQ request/quote types
They act as the internal contract between the public ClobClient API and lower-level builders/signers/http layers.
7. Configuration, constants, and exceptions
Files:
• py_clob_client/config.py
• py_clob_client/constants.py
• py_clob_client/exceptions.py
• py_clob_client/utilities.py
These files hold shared operational behavior:
• default values and environment-related configuration
• chain or API constants
• library-specific exception types
• helper functions used throughout the package
This is the “shared core” layer that supports the rest of the SDK and keeps repeated values and error handling consistent.
Data flow by use case
Read-only market and orderbook queries
Typical path:
1. user code instantiates ClobClient with only the host
2. ClobClient selects the correct endpoint and request parameters
3. HTTP helpers send a public request
4. response is returned as raw JSON-like data or wrapped types
This path does not require signing or API credentials.
Authenticated account and trading operations
Typical path:
1. user provides private key, chain ID, signature type, and funder address
2. ClobClient derives or creates API credentials
3. signing subsystem produces the necessary signatures
4. headers subsystem injects auth headers into the request
5. HTTP helpers submit the request to the CLOB API
6. API returns order/trade/account data
This path crosses multiple internal boundaries:
• wallet signing
• API credential signing
• authenticated HTTP request construction
Order submission
Typical path:
1. user supplies order intent through OrderArgs or MarketOrderArgs
2. order builder converts intent into exchange-ready order payload
3. signing layer signs the order or request as needed
4. ClobClient.post_order(...) sends it through the HTTP layer
5. response is returned, typically representing accepted/rejected order state
This is the most important end-to-end flow in the repo.
RFQ flow
Typical path:
1. user creates a request or quote using RFQ types
2. RFQ helpers build RFQ-specific payloads and query params
3. signing/auth layers produce any required authenticated headers or signatures
4. HTTP layer calls RFQ endpoints
5. response is returned as RFQ domain data
RFQ is distinct enough that it deserves a separate subsystem in any architecture diagram.
Public package boundary
The public package exposed to consumers is py_clob_client. From an external integrator’s perspective, the important public surfaces are:
• ClobClient
• clob_types
• order_builder.constants
• RFQ client/types
• signing-related behavior indirectly via client setup
The rest of the package is internal support code that enables those APIs.
Repository organization signals
examples/
This is a broad usage gallery, not just demo code. The examples cover:
• health/time endpoints
• markets and pricing
• order creation and cancellation
• API key lifecycle
• balances and allowances
• RFQ full lifecycle
That breadth indicates the SDK is intended as a full client surface for the exchange API, not a narrow helper library.
tests/
The test structure mirrors the implementation structure:
• headers
• http_helpers
• order_builder
• rfq
• signing
• top-level utility tests
This is a good clue to the architectural seams. Each subsystem is tested independently, which reinforces that these are the real internal modules rather than incidental helpers.
Packaging and delivery
Files:
• setup.py
• requirements.txt
• README.md
• GitHub workflow files
This is a standard distributable Python package published to PyPI. The GitHub workflows likely handle CI and release automation. No deployment target exists other than package distribution.
Important architectural boundaries to highlight in a diagram
If drawing this repository, the most important boundaries are:
1. Consumer boundary
- user scripts/examples/tests calling the SDK
2. SDK façade
- ClobClient as the main orchestrator
3. Domain helpers
- order builder
- RFQ subsystem
- domain types
4. Security/auth layer
- wallet signing
- API credential signing
- request headers
5. Transport layer
- endpoint definitions
- HTTP request execution
6. External system boundary
- Polymarket CLOB API and RFQ endpoints
- wallet/private key material provided by the user
In one sentence
This repository is a layered Python client library where ClobClient orchestrates order, market, and RFQ workflows by combining typed domain models, order-building logic, signing/authentication helpers, and HTTP transport to communicate with the Polymarket CLOB API.
Main entry points: client.py ClobClient · rfq_client.py RFQ Client · signer.py Signer · builder.py Order Builder
Components 22
Consumers
User code, examples, and tests that exercise the SDK
SDK Core
Central client façade and shared runtime support
- ClobClient · Main orchestrator for market, order, and RFQ workflows
py_clob_client/client.py - Types · Shared typed arguments and domain objects for client APIs
py_clob_client/clob_types.py - Config · Package configuration and environment-driven settings
py_clob_client/config.py - Constants · Common chain, API, and library constants
py_clob_client/constants.py - Exceptions · Library-specific exception classes
py_clob_client/exceptions.py - Utilities · Shared utility functions used across the package
py_clob_client/utilities.py
Security
Headers, signer, and signing primitives
- Headers · Builds request headers for authenticated API calls
py_clob_client/headers/headers.py - Signer · Connects wallet signing and request authentication flows
py_clob_client/signer.py - EIP-712 · Ethereum-style structured signing for exchange actions
py_clob_client/signing/eip712.py - HMAC · Credential-based request signing for API authentication
py_clob_client/signing/hmac.py - Signing Model · Data model for signed payloads and signature metadata
py_clob_client/signing/model.py
Transport
Endpoint definitions and HTTP request execution
- Endpoints · API route definitions used by the client and helpers
py_clob_client/endpoints.py - HTTP Helpers · Request execution and low-level response handling
py_clob_client/http_helpers/helpers.py
Trading
Order construction and shared trading domain models
- Order Builder · Converts order intent into exchange-ready order payloads
py_clob_client/order_builder/builder.py - Order Helpers · Supporting calculations and transformations for order creation
py_clob_client/order_builder/helpers.py
RFQ
RFQ-specific client and payload helpers
- RFQ Client · Specialized client for request-for-quote actions
py_clob_client/rfq/rfq_client.py - RFQ Helpers · Builds RFQ-specific payloads and query parameters
py_clob_client/rfq/rfq_helpers.py - RFQ Types · RFQ request, quote, and workflow data types
py_clob_client/rfq/rfq_types.py
External Systems
Remote API and user-held wallet material
- Polymarket CLOB API · External HTTP API for markets, orders, and RFQ
- Wallet Keys · User-provided private key material used for signing
Connections 26
- Examples → ClobClient: uses · Example scripts instantiate and call the client
- Tests → ClobClient: validates · Tests exercise the public client surface and helpers
- ClobClient → Config: reads · Uses runtime configuration for client setup
- ClobClient → Constants: uses · Relies on shared API and chain constants
- ClobClient → Endpoints: routes · Selects endpoint paths for each operation
- ClobClient → Headers: auths · Builds authenticated request headers when needed
- ClobClient → HTTP Helpers: sends · Delegates transport to the HTTP helper layer
- ClobClient → Order Builder: builds · Transforms order intent into executable payloads
- ClobClient → RFQ Client: delegates · Uses the RFQ subsystem for quote and request flows
- ClobClient → Types: types · Accepts and returns shared domain models
- ClobClient → Exceptions: raises · Surfaces library-specific errors
- ClobClient → Utilities: uses · Shares common helper functions
- Headers → Signer: uses · Combines request context with signing logic
- Signer → EIP-712: wallet · Uses structured Ethereum signing for order-related actions
- Signer → HMAC: api · Uses credential signing for authenticated requests
- Signer → Signing Model: formats · Uses signing data models and metadata
- Order Builder → Order Helpers: computes · Uses helper logic for order transformation
- Order Builder → Types: shapes · Consumes order-related domain types
- RFQ Client → RFQ Helpers: builds · Uses RFQ helper logic for payload and query construction
- RFQ Client → RFQ Types: uses · Consumes RFQ domain types
- RFQ Client → HTTP Helpers: calls · Executes RFQ requests through shared transport
- RFQ Client → Headers: auths · Reuses authenticated header generation
- HTTP Helpers → Polymarket CLOB API: requests · Sends HTTP traffic to the remote Polymarket service
- Endpoints → Polymarket CLOB API: maps · Defines the API routes exposed by the service
- EIP-712 → Wallet Keys: signs with · Requires user wallet key material
- HMAC → Polymarket CLOB API: authenticates · Produces request signatures for API authentication