rs-clob-client

[!WARNING] This repository has been archived and is no longer maintained.

The client is no longer functional and should not be used for new or existing integrations.

Please migrate to the V2 client: https://github.com/Polymarket/rs-clob-client-v2

Polymarket Rust Client

An ergonomic Rust client for interacting with Polymarket services, primarily the Central Limit Order Book (CLOB). This crate provides strongly typed request builders, authenticated endpoints, alloy support and more.

Table of Contents

• Overview
• Getting Started
• Feature Flags
• Re-exported Types
• Examples
  • CLOB Client
  • WebSocket Streaming
  • Optional APIs
• Additional CLOB Capabilities
• Setting Token Allowances
• Minimum Supported Rust Version (MSRV)
• Contributing
• About Polymarket

Overview

• Typed CLOB requests (orders, trades, markets, balances, and more)
• Dual authentication flows
  • Normal authenticated flow
  • Builder authentication flow
• Type-level state machine
  • Prevents using authenticated endpoints before authenticating
  • Compile-time enforcement of correct transitions
• Signer support via alloy::signers::Signer
  • Including remote signers, e.g. AWS KMS
• Zero-cost abstractions — no dynamic dispatch in hot paths
• Order builders for easy construction & signing
• Full serde support
• Async-first design with reqwest

Getting started

Add the crate to your Cargo.toml:

[dependencies]
polymarket-client-sdk = "0.3"

or

cargo add polymarket-client-sdk

Then run any of the examples

cargo run --example unauthenticated

Feature Flags

The crate is modular with optional features for different Polymarket APIs:

Enable features in your Cargo.toml:

[dependencies]
polymarket-client-sdk = { version = "0.3", features = ["ws", "data"] }

Re-exported Types

This SDK re-exports commonly used types from external crates so you don't need to add them to your Cargo.toml:

From types module

use polymarket_client_sdk::types::{
    Address, ChainId, Signature, address,  // from alloy::primitives
    DateTime, NaiveDate, Utc,              // from chrono
    Decimal, dec,                          // from rust_decimal + rust_decimal_macros
};

From auth module

use polymarket_client_sdk::auth::{
    LocalSigner, Signer,          // from alloy::signers (LocalSigner + trait)
    Uuid, ApiKey,                 // from uuid (ApiKey = Uuid)
    SecretString, ExposeSecret,   // from secrecy
    builder::Url,                 // from url (for remote builder config)
};

From error module

use polymarket_client_sdk::error::{
    StatusCode, Method,           // from reqwest (for error inspection)
};

This allows you to work with the SDK without managing version compatibility for these common dependencies.

Examples

See examples/ for the complete set. Below are hand-picked examples for common use cases.

CLOB Client

Unauthenticated client (read-only)

use polymarket_client_sdk::clob::Client;

#[tokio::main]
async fn main() -> anyhow::Result {
    let client = Client::default();

    let ok = client.ok().await?;
    println!("Ok: {ok}");

    Ok(())
}

Authenticated client

Set POLYMARKET_PRIVATE_KEY as an environment variable with your private key.

EOA wallets

If using MetaMask or hardware wallet, you must first set token allowances. See Token Allowances section below.

…

Proxy/Safe wallets

For proxy/Safe wallets, the funder address is automatically derived using CREATE2 from your signer's EOA address:

let client = Client::new("https://clob.polymarket.com", Config::default())?
    .authentication_builder(&signer)
    .signature_type(SignatureType::GnosisSafe)  // Funder auto-derived via CREATE2
    .authenticate()
    .await?;

The SDK computes the deterministic wallet address that Polymarket deploys for your EOA. This is the same address shown on polymarket.com when you log in with a browser wallet.

If you need to override the derived address (e.g., for advanced use cases), you can explicitly provide it:

let client = Client::new("https://clob.polymarket.com", Config::default())?
    .authentication_builder(&signer)
    .funder(address!(""))
    .signature_type(SignatureType::GnosisSafe)
    .authenticate()
    .await?;

You can also derive these addresses manually:

use polymarket_client_sdk::{derive_safe_wallet, derive_proxy_wallet, POLYGON};

// For browser wallet users (GnosisSafe)
let safe_address = derive_safe_wallet(signer.address(), POLYGON);

// For Magic/email wallet users (Proxy)
let proxy_address = derive_proxy_wallet(signer.address(), POLYGON);

Funder Address

The funder address is the actual address that holds your funds on Polymarket. When using proxy wallets (email wallets like Magic or browser extension wallets), the signing key differs from the address holding the funds. The SDK automatically derives the correct funder address using CREATE2 when you specify SignatureType::Proxy or SignatureType::GnosisSafe. You can override this with .funder(address) if needed.

Signature Types

The signature_type parameter tells the system how to verify your signatures:

• signature_type=0 (default): Standard EOA (Externally Owned Account) signatures - includes MetaMask, hardware wallets, and any wallet where you control the private key directly
• signature_type=1: Email/Magic wallet signatures (delegated signing)
• signature_type=2: Browser wallet proxy signatures (when using a proxy contract, not direct wallet connections)

See SignatureType for more information.

Place a market order

…

Place a limit order

…

Builder-authenticated client

For institutional/third-party app integrations with remote signing:

…

WebSocket Streaming

Real-time orderbook and user event streaming. Requires the ws feature.

polymarket-client-sdk = { version = "0.3", features = ["ws"] }

…

Available streams:

• subscribe_orderbook() - Bid/ask levels for assets
• subscribe_prices() - Price change events
• subscribe_midpoints() - Calculated midpoint prices
• subscribe_orders() - User order updates (authenticated)
• subscribe_trades() - User trade executions (authenticated)

See examples/clob/ws/ for more WebSocket examples including authenticated user streams.

Optional APIs

Data API

Trading analytics, positions, and leaderboards. Requires the data feature.

use polymarket_client_sdk::data::Client;
use polymarket_client_sdk::data::types::request::PositionsRequest;
use polymarket_client_sdk::types::address;

#[tokio::main]
async fn main() -> anyhow::Result {
    let client = Client::default();
    let user = address!("0x0000000000000000000000000000000000000000"); // Your address

    let request = PositionsRequest::builder().user(user).limit(10)?.build();
    let positions = client.positions(&request).await?;
    println!("Open positions: {:?}", positions);
    Ok(())
}

See examples/data.rs for trades, leaderboards, activity, and more.

Gamma API

Market and event discovery. Requires the gamma feature.

…

See examples/gamma.rs for tags, series, comments, and sports endpoints.

Bridge API

Cross-chain deposits from EVM chains, Solana, and Bitcoin. Requires the bridge feature.

…

See examples/bridge.rs for supported assets and minimum deposits.

Additional CLOB Capabilities

Beyond basic order placement, the CLOB client supports:

• Rewards & Earnings - Query maker rewards, daily earnings, and reward percentages
• Streaming Pagination - stream_data() for iterating through large result sets
• Batch Operations - post_orders() and cancel_orders() for multiple orders at once
• Order Scoring - Check if orders qualify for maker rewards
• Notifications - Manage trading notifications
• Balance Management - Query and refresh balance/allowance caches
• Geoblock Detection - Check if trading is available in your region

See examples/clob/authenticated.rs for comprehensive usage.

Token Allowances

Do I need to set allowances?

MetaMask and EOA users must set token allowances. If you are using a proxy or Safe-type wallet, then you do not.

What are allowances?

Think of allowances as permissions. Before Polymarket can move your funds to execute trades, you need to give the exchange contracts permission to access your USDC and conditional tokens.

Quick Setup

You need to approve two types of tokens:

1. USDC (for deposits and trading)
2. Conditional Tokens (the outcome tokens you trade)

Each needs approval for the exchange contracts to work properly.

Setting Allowances

Use examples/approvals.rs to approve the right contracts. Run once to approve USDC. Then change the TOKEN_TO_APPROVE and run for each conditional token.

Pro tip: You only need to set these once per wallet. After that, you can trade freely.

Minimum Supported Rust Version (MSRV)

MSRV: Rust 1.88

Older versions may compile, but are not supported.

This project aims to maintain compatibility with a Rust version that is at least six months old.

Version updates may occur more