# polymarket/py-clob-client architecture

> Architecture diagram of the GitHub repository polymarket/py-clob-client, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/polymarket/py-clob-client
- Repository: https://github.com/polymarket/py-clob-client

## Overview

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: [`py_clob_client/client.py`](https://github.com/polymarket/py-clob-client/blob/HEAD/py_clob_client/client.py) (ClobClient), [`py_clob_client/rfq/rfq_client.py`](https://github.com/polymarket/py-clob-client/blob/HEAD/py_clob_client/rfq/rfq_client.py) (RFQ Client), [`py_clob_client/signer.py`](https://github.com/polymarket/py-clob-client/blob/HEAD/py_clob_client/signer.py) (Signer), [`py_clob_client/order_builder/builder.py`](https://github.com/polymarket/py-clob-client/blob/HEAD/py_clob_client/order_builder/builder.py) (Order Builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Consumers"
  examples["Examples<br/>usage gallery"]
  tests["Tests<br/>test suite"]
end

subgraph "SDK Core"
  client["ClobClient<br/>SDK façade<br/>[client.py]"]
  types["Types<br/>domain models<br/>[clob_types.py]"]
  config["Config<br/>[config.py]"]
  constants["Constants<br/>[constants.py]"]
  exceptions["Exceptions<br/>error types<br/>[exceptions.py]"]
  utilities["Utilities<br/>helpers<br/>[utilities.py]"]
end

subgraph "Security"
  headers["Headers<br/>[headers.py]"]
  signer["Signer<br/>signing bridge<br/>[signer.py]"]
  eip712["EIP-712<br/>wallet signing<br/>[eip712.py]"]
  hmac["HMAC<br/>api signing<br/>[hmac.py]"]
  signing_model["Signing Model<br/>signing schema<br/>[model.py]"]
end

subgraph "Transport"
  endpoints["Endpoints<br/>route map<br/>[endpoints.py]"]
  http_helpers["HTTP Helpers<br/>transport layer<br/>[helpers.py]"]
end

subgraph "Trading"
  order_builder["Order Builder<br/>order composer<br/>[builder.py]"]
  order_helpers["Order Helpers<br/>order logic<br/>[helpers.py]"]
end

subgraph "RFQ"
  rfq_client["RFQ Client<br/>rfq workflow<br/>[rfq_client.py]"]
  rfq_helpers["RFQ Helpers<br/>rfq payloads<br/>[rfq_helpers.py]"]
  rfq_types["RFQ Types<br/>rfq models<br/>[rfq_types.py]"]
end

subgraph "External Systems"
  api[("Polymarket CLOB API<br/>remote api")]
  wallet{{"Wallet Keys<br/>user secret"}}
end

examples -->|"uses"| client
tests -->|"validates"| client
client -->|"reads"| config
client -->|"uses"| constants
client -->|"routes"| endpoints
client -->|"auths"| headers
client -->|"sends"| http_helpers
client -->|"builds"| order_builder
client -->|"delegates"| rfq_client
client -->|"types"| types
client -->|"raises"| exceptions
client -->|"uses"| utilities
headers -->|"uses"| signer
signer -->|"wallet"| eip712
signer -->|"api"| hmac
signer -->|"formats"| signing_model
order_builder -->|"computes"| order_helpers
order_builder -->|"shapes"| types
rfq_client -->|"builds"| rfq_helpers
rfq_client -->|"uses"| rfq_types
rfq_client -->|"calls"| http_helpers
rfq_client -->|"auths"| headers
http_helpers -->|"requests"| api
endpoints -->|"maps"| api
eip712 -->|"signs with"| wallet
hmac -->|"authenticates"| api

click examples "https://github.com/polymarket/py-clob-client/tree/main/examples"
click tests "https://github.com/polymarket/py-clob-client/tree/main/tests"
click client "https://github.com/polymarket/py-clob-client/blob/main/py_clob_client/client.py"
click types "https://github.com/polymarket/py-clob-client/blob/main/py_clob_client/clob_types.py"
click config "https://github.com/polymarket/py-clob-client/blob/main/py_clob_client/config.py"
click constants "https://github.com/polymarket/py-clob-client/blob/main/py_clob_client/constants.py"
click exceptions "https://github.com/polymarket/py-clob-client/blob/main/py_clob_client/exceptions.py"
click utilities "https://github.com/polymarket/py-clob-client/blob/main/py_clob_client/utilities.py"
click endpoints "https://github.com/polymarket/py-clob-client/blob/main/py_clob_client/endpoints.py"
click http_helpers "https://github.com/polymarket/py-clob-client/blob/main/py_clob_client/http_helpers/helpers.py"
click headers "https://github.com/polymarket/py-clob-client/blob/main/py_clob_client/headers/headers.py"
click signer "https://github.com/polymarket/py-clob-client/blob/main/py_clob_client/signer.py"
click eip712 "https://github.com/polymarket/py-clob-client/blob/main/py_clob_client/signing/eip712.py"
click hmac "https://github.com/polymarket/py-clob-client/blob/main/py_clob_client/signing/hmac.py"
click signing_model "https://github.com/polymarket/py-clob-client/blob/main/py_clob_client/signing/model.py"
click order_builder "https://github.com/polymarket/py-clob-client/blob/main/py_clob_client/order_builder/builder.py"
click order_helpers "https://github.com/polymarket/py-clob-client/blob/main/py_clob_client/order_builder/helpers.py"
click rfq_client "https://github.com/polymarket/py-clob-client/blob/main/py_clob_client/rfq/rfq_client.py"
click rfq_helpers "https://github.com/polymarket/py-clob-client/blob/main/py_clob_client/rfq/rfq_helpers.py"
click rfq_types "https://github.com/polymarket/py-clob-client/blob/main/py_clob_client/rfq/rfq_types.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class examples,tests,api,wallet toneBlue
class client,types,config,constants,exceptions,utilities toneAmber
class headers,signer,eip712,hmac,signing_model toneMint
class endpoints,http_helpers toneRose
class order_builder,order_helpers toneIndigo
class rfq_client,rfq_helpers,rfq_types toneTeal
```

## Components

### Consumers

User code, examples, and tests that exercise the SDK

- [Examples](https://github.com/polymarket/py-clob-client/tree/HEAD/examples): usage gallery · Example scripts covering read, trading, and RFQ flows · `examples`
- [Tests](https://github.com/polymarket/py-clob-client/tree/HEAD/tests): test suite · Subsystem-focused tests mirroring the package seams · `tests`

### SDK Core

Central client façade and shared runtime support

- [ClobClient](https://github.com/polymarket/py-clob-client/blob/HEAD/py_clob_client/client.py): SDK façade · Main orchestrator for market, order, and RFQ workflows · `py_clob_client/client.py`
- [Types](https://github.com/polymarket/py-clob-client/blob/HEAD/py_clob_client/clob_types.py): domain models · Shared typed arguments and domain objects for client APIs · `py_clob_client/clob_types.py`
- [Config](https://github.com/polymarket/py-clob-client/blob/HEAD/py_clob_client/config.py): runtime config · Package configuration and environment-driven settings · `py_clob_client/config.py`
- [Constants](https://github.com/polymarket/py-clob-client/blob/HEAD/py_clob_client/constants.py): shared constants · Common chain, API, and library constants · `py_clob_client/constants.py`
- [Exceptions](https://github.com/polymarket/py-clob-client/blob/HEAD/py_clob_client/exceptions.py): error types · Library-specific exception classes · `py_clob_client/exceptions.py`
- [Utilities](https://github.com/polymarket/py-clob-client/blob/HEAD/py_clob_client/utilities.py): helpers · Shared utility functions used across the package · `py_clob_client/utilities.py`

### Security

Headers, signer, and signing primitives

- [Headers](https://github.com/polymarket/py-clob-client/blob/HEAD/py_clob_client/headers/headers.py): auth headers · Builds request headers for authenticated API calls · `py_clob_client/headers/headers.py`
- [Signer](https://github.com/polymarket/py-clob-client/blob/HEAD/py_clob_client/signer.py): signing bridge · Connects wallet signing and request authentication flows · `py_clob_client/signer.py`
- [EIP-712](https://github.com/polymarket/py-clob-client/blob/HEAD/py_clob_client/signing/eip712.py): wallet signing · Ethereum-style structured signing for exchange actions · `py_clob_client/signing/eip712.py`
- [HMAC](https://github.com/polymarket/py-clob-client/blob/HEAD/py_clob_client/signing/hmac.py): api signing · Credential-based request signing for API authentication · `py_clob_client/signing/hmac.py`
- [Signing Model](https://github.com/polymarket/py-clob-client/blob/HEAD/py_clob_client/signing/model.py): signing schema · Data model for signed payloads and signature metadata · `py_clob_client/signing/model.py`

### Transport

Endpoint definitions and HTTP request execution

- [Endpoints](https://github.com/polymarket/py-clob-client/blob/HEAD/py_clob_client/endpoints.py): route map · API route definitions used by the client and helpers · `py_clob_client/endpoints.py`
- [HTTP Helpers](https://github.com/polymarket/py-clob-client/blob/HEAD/py_clob_client/http_helpers/helpers.py): transport layer · Request execution and low-level response handling · `py_clob_client/http_helpers/helpers.py`

### Trading

Order construction and shared trading domain models

- [Order Builder](https://github.com/polymarket/py-clob-client/blob/HEAD/py_clob_client/order_builder/builder.py): order composer · Converts order intent into exchange-ready order payloads · `py_clob_client/order_builder/builder.py`
- [Order Helpers](https://github.com/polymarket/py-clob-client/blob/HEAD/py_clob_client/order_builder/helpers.py): order logic · Supporting calculations and transformations for order creation · `py_clob_client/order_builder/helpers.py`

### RFQ

RFQ-specific client and payload helpers

- [RFQ Client](https://github.com/polymarket/py-clob-client/blob/HEAD/py_clob_client/rfq/rfq_client.py): rfq workflow · Specialized client for request-for-quote actions · `py_clob_client/rfq/rfq_client.py`
- [RFQ Helpers](https://github.com/polymarket/py-clob-client/blob/HEAD/py_clob_client/rfq/rfq_helpers.py): rfq payloads · Builds RFQ-specific payloads and query parameters · `py_clob_client/rfq/rfq_helpers.py`
- [RFQ Types](https://github.com/polymarket/py-clob-client/blob/HEAD/py_clob_client/rfq/rfq_types.py): rfq models · 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**: remote api · External HTTP API for markets, orders, and RFQ
- **Wallet Keys**: user secret · User-provided private key material used for signing

## Connections

- 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
