polyfill-rs

When adding new integration tests, follow this pattern to ensure proper configuration handling and graceful skipping when credentials are missing.

#[tokio::test]
async fn test_new_feature() -> Result<()> {
    let config = TestConfig::from_env();
    
    // Skip if requirements not met
    if !config.has_auth() {
        TestReporter::skip("test_new_feature", "no private key");
        return Ok(());
    }
    
    // Test implementation
    let client = config.create_auth_client()?;
    let result = client.some_new_method().await?;
    
    // Assertions
    assert!(result.is_valid());
    
    TestReporter::success("test_new_feature");
    Ok(())
}

Best Practices

1. Use TestConfig: Always use the shared test configuration.
2. Handle Missing Credentials: Skip tests gracefully using TestReporter::skip when credentials aren't available.
3. Measure Performance: Include timing measurements for performance-critical operations.
4. Provide Context: Use descriptive test names and error messages.
5. Clean Up: Don't leave test data in the system.

Integration tests that communicate with the real Polymarket API require specific environment variables. You can set these in a .env file or export them directly to your shell.

Required

• POLYMARKET_PRIVATE_KEY: Your private key.

Optional API Credentials

• POLYMARKET_API_KEY
• POLYMARKET_API_SECRET
• POLYMARKET_API_PASSPHRASE
• Note: POLYMARKET_SECRET and POLYMARKET_PASSPHRASE are accepted as backward-compatible aliases.

Optional Configuration

• POLYMARKET_HOST: Defaults to https://clob.polymarket.com.
• POLYMARKET_CHAIN_ID: Defaults to 137.
• POLYMARKET_SIGNATURE_TYPE: Defines wallet type: 0 (EOA), 1 (Proxy), 2 (Gnosis Safe/browser wallet), 3 (Poly1271).
• POLYMARKET_FUNDER_ADDRESS: Override the derived funder/proxy wallet address.
• POLYMARKET_RESOLVE_IP: Pin clob.polymarket.com to a specific A record if local DNS is blocked.

export POLYMARKET_PRIVATE_KEY="your_private_key_here"
export POLYMARKET_API_KEY="your_api_key"
export POLYMARKET_API_SECRET="your_api_secret"
export POLYMARKET_API_PASSPHRASE="your_passphrase"

For latency-sensitive applications that primarily need order book updates, use WebSocketBookApplier. This mode bypasses standard StreamMessage decoding to apply updates directly into an OrderBookManager using a WsBookUpdateProcessor.

Workflow:

1. Create an OrderBookManager and 'warm it up' by creating books for all target asset IDs.
2. Create a WebSocketStream.
3. Convert the stream using .into_book_applier(books, processor).
4. The resulting applier implements Stream, yielding Result<WsBookApplyStats> instead of generic messages.

Optimization Note: For maximum performance, use apply_bytes_message(&mut [u8]) with a reusable mutable buffer to avoid allocations.

let books = OrderBookManager::new(64);
// Warm up books
books.get_or_create_book("asset_id").unwrap();

let processor = WsBookUpdateProcessor::new(1024);
let stream = WebSocketStream::new("wss://...");
let mut applier = stream.into_book_applier(&books, processor);

// The applier can now be used as a Stream
while let Some(result) = applier.next().await {
    let stats = result?;
    // stats contains book_messages and book_levels_applied
}

For latency-sensitive applications that create many orders for the same market or token, use PreparedOrderPath. This object caches expensive computations and state, such as:

• Tick-size rounding configurations
• Exchange address parsing
• Token ID parsing (to U256)
• EIP-712 domain preparation
• Normalized bytes32 fields for builder_code and metadata

Once prepared, you can call create_limit_order or create_market_order directly on the PreparedOrderPath instance.

// 1. Initialize builder
let builder = OrderBuilder::new(signer, None, None);

// 2. Prepare the path (do this once per market/token)
let prepared_path = builder.prepare_order_path(
    137, 
    "123456", 
    Decimal::from_str("0.01").unwrap(), 
    false, 
    None, 
    None
).unwrap();

// 3. Create orders rapidly
let limit_order = prepared_path.create_limit_order(
    Side::BUY, 
    Decimal::from_str("0.45").unwrap(), 
    Decimal::from_str("12.34").unwrap(), 
    Some(1_900_000_000)
).unwrap();