Polysqueeze

Polysqueeze is a Rust SDK for interacting with Polymarket's CLOB (trading), Gamma (market data), and WebSocket APIs. If you hit auth edge-cases (401s, signature mismatches, etc.), please open an issue with repro details.

Highlights

• Fully working REST helpers for the Gamma and CLOB APIs (markets, fills, single orders, authentication, helper types).
• Order creation flows have live regression coverage for the single-order path; batch/multi-order flows still need more testing and contributions are welcome.
• Gamma data types for markets, tokens, order books, rewards, etc.
• WebSocket helpers for public market events and authenticated user events (see examples/wss_*.rs).
• Configuration helpers for Polygon mainnet (137) and testnet (80002), plus shared utils for signing, math, and fills.

Quickstart

1. Add polysqueeze to your deps:

cargo add polysqueeze

2. Create a client, derive API keys, and post a sample order. This is the one path that currently runs against the live API (single-order placement); batch order flows and broader WebSocket handling still need more testing and are open for contributions.

use polysqueeze::{types::GammaListParams, ClobClient, OrderArgs, OrderType, Side};
use rust_decimal::Decimal;

#[tokio::main]
async fn main() -> polysqueeze::Result<()> {
    let base_url = "https://clob.polymarket.com";
    let private_key = std::env::var("POLY_PRIVATE_KEY")?;

    let l1_client = ClobClient::with_l1_headers(base_url, &private_key, 137);
    let creds = l1_client.create_or_derive_api_key(None).await?;

    let mut client = ClobClient::with_l2_headers(base_url, &private_key, 137, creds.clone());

    // Filter markets with various criteria
    let gamma_params = GammaListParams {
        limit: Some(10),
        closed: Some(false),                  // Exclude closed markets
        liquidity_num_min: Some(Decimal::from(1000)),  // Min liquidity
        liquidity_num_max: Some(Decimal::from(1000000)), // Max liquidity
        volume_num_min: Some(Decimal::from(10000)),    // Min volume
        cyom: Some(false),                    // Exclude create-your-own markets
        include_tag: Some(true),              // Include tag data
        ..Default::default()
    };
    let market_data = client.get_markets(None, Some(&gamma_params)).await?;
    println!("{} markets fetched", market_data.data.len());

    // Replace with a real CLOB token id (see `market_data` or use `.env.example` + examples).
    let token_id = "token-id-here";
    let order_args = OrderArgs::new(
        token_id,
        Decimal::new(5000, 4),
        Decimal::new(1, 0),
        Side::BUY,
    );

    let signed_order = client.create_order(&order_args, None, None, None).await?;
    client.post_order(signed_order, OrderType::GTC).await?;

    Ok(())
}

3. For WebSockets, start with the typed wss::{WssMarketClient, WssUserClient} helpers (see examples/wss_market.rs and examples/wss_user.rs). For lower-level streaming primitives, see the ws module.

Examples

• examples/order.rs: derive an API key and place a tiny order (opt-in).
• examples/wss_market.rs: subscribe to public market channel events.
• examples/wss_user.rs: authenticated user channel (orders/trades) events.
• examples/wss_cancel.rs: cancel an order by ID.
• examples/new_with_auth.rs: create a client using auth helpers.
• examples/balance_allowance.rs: inspect balances/allowances.

The smoke-testing logic from tests/place_order.rs is also available as examples/order.rs. To run it locally:

cargo run --example order

It expects the same environment variables as the test (private key, API creds, network, etc.) and drops a microscopic order when RUN_PLACE_ORDER_TEST=1 is set.

Copy .env.example to .env and fill in your wallet key plus any overrides (POLY_CHAIN_ID, POLY_API_URL, POLY_FUNDER, POLY_TEST_TOKEN). Only the private key is strictly required; the rest are optional fallbacks.

examples/wss_market.rs shows how to consume the public MARKET channel for price/book updates. Set POLY_WSS_MARKETS and/or POLY_WSS_ASSET_IDS to the condition/asset IDs you care about, then run:

cargo run --example wss_market

The example prints book, price_change, tick_size_change, and last_trade_price events for the subscribed markets.

For authenticated events, examples/wss_user.rs shows how to derive an API key, construct WssUserClient, and stream WssUserEvent::Order/Trade messages. Run it via cargo run --example wss_user once POLY_PRIVATE_KEY is set. It places a tiny limit order on a ≥1M-liquidity market (you can tweak POLY_WSS_MIN_LIQUIDITY) and prints the resulting order ID, then waits for user events so you can observe partial fills/cancellations. While that example runs, start POLY_WSS_ORDER_ID=… cargo run --example wss_cancel from another terminal to cancel the order and trigger a WssUserEvent::Order update.

If you already have API credentials, WssUserClient exposes the authenticated user channel so you can react to your own orders and trades. Construct WssUserClient::new(api_creds.api_key.clone()), subscribe to the markets you're trading, and drive next_event() to consume WssUserEvent::Order and WssUserEvent::Trade payloads that mirror the data shown above.

Gamma and Data APIs

Use the client module to call Gamma endpoints such as /markets, /events, /tags, and NegRisk data. Only the Gamma markets and single-order creation paths have live regression coverage today; feel free to extend coverage to more endpoints or submit fixes. The types module contains strongly typed responses such as Market, MarketOrderArgs, and OrderBookSummary.

GammaListParams Reference

The following parameters are available for filtering markets when calling ClobClient::get_markets():

Parameter	Type	Description
limit	Option<i32>	Maximum number of markets to return
closed	Option<bool>	Include or exclude closed markets
liquidity_num_min	Option<Decimal>	Minimum liquidity threshold
liquidity_num_max	Option<Decimal>	Maximum liquidity threshold
volume_num_min	Option<Decimal>	Minimum trading volume threshold
volume_num_max	Option<Decimal>	Maximum trading volume threshold
cyom	Option<bool>	Include create-your-own markets (CYOM)
include_tag	Option<bool>	Include tag metadata in response
tag	Option<String>	Filter by specific tag
related	Option<bool>	Include related markets
archived	Option<bool>	Include archived markets
order_by	Option<String>	Sort field (e.g., "volume", "liquidity", "created_date")
order_dir	Option<String>	Sort direction ("asc" or "desc")
currency	Option<String>	Currency for pricing (default: "USD")
maker_fee	Option<f64>	Maker fee filter
taker_fee	Option<f64>	Taker fee filter
pfm	Option<bool>	Profit/fee mode
search	Option<String>	Free text search across markets

Using GammaClient

For market, event, and tag queries, use the dedicated GammaClient:

use polysqueeze::api::GammaClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let gamma_client = GammaClient::new();
    
    // Fetch markets
    let markets = gamma_client.get_markets(None, None).await?;
    println!("Markets: {:?}", markets);
    
    // Fetch events
    let events = gamma_client.get_events(None).await?;
    println!("Events: {:?}", events);
    
    // Fetch tags
    let tags = gamma_client.get_tags().await?;
    println!("Tags: {:?}", tags);
    
    Ok(())
}

Testing

Test order placement with this command (make sure env variables are set). This exercise is what we currently rely on as basic coverage for the order APIs:

# WARNING: this test places a small real order on Polymarket
RUN_PLACE_ORDER_TEST=1 cargo test place_order -- --nocapture

Other live tests are opt-in as well:

• RUN_AUTH_TEST=1 (auth derivation/verification)
• RUN_GAMMA_TESTS=1 (Gamma live endpoints / ClobClient::get_markets)
• RUN_DATA_API_TESTS=1 (data-api /value + /positions)

Formatting and Lints

cargo fmt
cargo clippy

Contributing

Contributions are welcome! See CONTRIBUTING.md for setup, test commands, and PR guidelines.