polymarket-rs-sdk 0.1.14

//! Polymarket CLOB REST API Client
//!
//! This module provides a high-level client for interacting with the
//! Polymarket CLOB (Central Limit Order Book) REST API.
//!
//! ## Features
//!
//! - **API Credential Management**: Create, derive, and manage API credentials
//! - **Order Submission**: Submit, cancel, and query orders
//! - **Market Data**: Get order books and market information
//!
//! ## Example
//!
//! ```rust,ignore
//! use polymarket_sdk::clob::{ClobClient, ClobConfig};
//! use alloy_signer_local::PrivateKeySigner;
//!
//! let signer: PrivateKeySigner = "0x...".parse()?;
//! let client = ClobClient::new(ClobConfig::default(), signer)?;
//!
//! // Create API credentials (first time)
//! let creds = client.create_api_credentials().await?;
//!
//! // Submit an order
//! let order = client.submit_order(&signed_order).await?;
//! ```

use std::collections::HashMap;
use std::num::NonZeroU32;
use std::sync::Arc;
use std::time::Duration;

use alloy_primitives::U256;
use alloy_signer_local::PrivateKeySigner;
use governor::{Quota, RateLimiter as GovRateLimiter};
use reqwest::Client;
use serde::{Deserialize, Serialize};
use tracing::{debug, info, instrument, warn};

use crate::auth::{
    create_l1_headers, create_l2_headers_with_address, create_l2_headers_with_body_string,
    get_current_unix_time_secs,
};
use crate::core::clob_api_url;
use crate::core::{PolymarketError, Result};
use crate::types::{
    ApiCredentials, BalanceAllowanceParams, BalanceAllowanceResponse, OrderType,
    SignedOrderRequest,
};

// Builder API authentication
use crate::auth::{BuilderApiKeyCreds, BuilderSigner};

type RateLimiter = GovRateLimiter<
    governor::state::NotKeyed,
    governor::state::InMemoryState,
    governor::clock::DefaultClock,
>;

/// CLOB API configuration
#[derive(Debug, Clone)]
pub struct ClobConfig {
    /// CLOB API base URL
    pub base_url: String,
    /// Request timeout
    pub timeout: Duration,
    /// Rate limit (requests per second)
    pub rate_limit_per_second: u32,
    /// User agent string
    pub user_agent: String,
}

impl Default for ClobConfig {
    fn default() -> Self {
        Self {
            // Use helper function to support env var override (POLYMARKET_CLOB_URL)
            base_url: clob_api_url(),
            timeout: Duration::from_secs(30),
            rate_limit_per_second: 5,
            user_agent: "polymarket-sdk/0.1.0".to_string(),
        }
    }
}

impl ClobConfig {
    /// Create a new configuration builder with defaults.
    #[must_use]
    pub fn builder() -> Self {
        Self::default()
    }

    /// Create config from environment variables.
    ///
    /// **Deprecated**: Use `ClobConfig::default()` instead.
    /// The default implementation already supports `POLYMARKET_CLOB_URL` env var override.
    #[must_use]
    #[deprecated(
        since = "0.1.0",
        note = "Use ClobConfig::default() instead. URL override via POLYMARKET_CLOB_URL env var is already supported."
    )]
    pub fn from_env() -> Self {
        Self::default()
    }

    /// Set base URL
    #[must_use]
    pub fn with_base_url(mut self, url: impl Into<String>) -> Self {
        self.base_url = url.into();
        self
    }

    /// Set request timeout
    #[must_use]
    pub fn with_timeout(mut self, timeout: Duration) -> Self {
        self.timeout = timeout;
        self
    }

    /// Set rate limit (requests per second)
    #[must_use]
    pub fn with_rate_limit(mut self, rate_limit: u32) -> Self {
        self.rate_limit_per_second = rate_limit;
        self
    }

    /// Set user agent string
    #[must_use]
    pub fn with_user_agent(mut self, user_agent: impl Into<String>) -> Self {
        self.user_agent = user_agent.into();
        self
    }
}

/// Derive API key response
#[derive(Debug, Deserialize)]
pub struct DeriveApiKeyResponse {
    /// The derived API key
    #[serde(rename = "apiKey")]
    pub api_key: String,
    /// The API secret (base64 encoded)
    pub secret: String,
    /// The passphrase
    pub passphrase: String,
}

/// API key response
#[derive(Debug, Deserialize)]
pub struct ApiKeyResponse {
    /// API key
    #[serde(rename = "apiKey")]
    pub api_key: String,
    /// API secret
    pub secret: String,
    /// Passphrase
    pub passphrase: String,
}

/// Create API key request
#[derive(Debug, Serialize)]
struct CreateApiKeyRequest {
    /// Nonce from derive endpoint
    nonce: String,
}

/// Order response from CLOB
/// Matches official Polymarket API response format
#[derive(Debug, Deserialize)]
pub struct OrderResponse {
    /// Whether the order submission was successful
    pub success: bool,
    /// Error message (empty string if no error)
    #[serde(rename = "errorMsg")]
    pub error_msg: String,
    /// Order ID assigned by the CLOB
    #[serde(rename = "orderID")]
    pub order_id: String,
    /// Transaction hashes if any
    #[serde(rename = "transactionsHashes", default)]
    pub transactions_hashes: Vec<String>,
    /// Order status
    pub status: String,
}

/// Paginated response wrapper from CLOB /data/* endpoints
#[derive(Debug, Deserialize)]
pub struct PaginatedResponse<T> {
    /// Limit used for this page
    pub limit: Option<i32>,
    /// Total count
    pub count: Option<i32>,
    /// Cursor for next page
    pub next_cursor: String,
    /// Data items
    pub data: Vec<T>,
}

/// Open order from CLOB /data/orders endpoint
/// Field names match the actual API response (TypeScript client format)
#[derive(Debug, Deserialize)]
pub struct OpenOrder {
    /// Order ID
    pub id: String,
    /// Order status
    pub status: String,
    /// Owner address
    #[serde(default)]
    pub owner: Option<String>,
    /// Maker address
    pub maker_address: String,
    /// Market slug
    #[serde(default)]
    pub market: Option<String>,
    /// Asset ID (token ID)
    pub asset_id: String,
    /// Side (BUY/SELL)
    pub side: String,
    /// Original size
    pub original_size: String,
    /// Size matched
    pub size_matched: String,
    /// Price
    pub price: String,
    /// Associated trades
    #[serde(default)]
    pub associate_trades: Option<Vec<String>>,
    /// Outcome
    #[serde(default)]
    pub outcome: Option<String>,
    /// Created at timestamp (unix timestamp as number)
    pub created_at: Option<i64>,
    /// Expiration
    #[serde(default)]
    pub expiration: Option<String>,
    /// Order type (GTC, FOK, GTD, FAK)
    #[serde(default, rename = "type")]
    pub order_type: Option<String>,
}

impl OpenOrder {
    /// Get token_id (alias for asset_id for backward compatibility)
    #[must_use]
    pub fn token_id(&self) -> &str {
        &self.asset_id
    }

    /// Get maker (alias for maker_address for backward compatibility)
    #[must_use]
    pub fn maker(&self) -> &str {
        &self.maker_address
    }

    /// Get signer (same as maker for CLOB orders)
    #[must_use]
    pub fn signer(&self) -> &str {
        // Note: CLOB API doesn't return signer separately, it's the same as maker
        &self.maker_address
    }
}

/// Cancel single order request (DELETE /order)
///
/// Polymarket API expects: `{"orderID": "0x..."}`
#[derive(Debug, Serialize)]
struct CancelOrderRequest {
    /// Order ID to cancel
    #[serde(rename = "orderID")]
    order_id: String,
}

/// Cancel response from Polymarket CLOB API
///
/// Used by all cancel endpoints (single, batch, cancel-all, cancel-market-orders).
/// The `not_canceled` field is a map of order_id -> reason explaining why an order
/// couldn't be canceled.
#[derive(Debug, Deserialize)]
pub struct CancelResponse {
    /// Successfully cancelled order IDs
    pub canceled: Vec<String>,
    /// Map of order_id -> reason for orders that couldn't be canceled
    #[serde(default)]
    pub not_canceled: HashMap<String, String>,
}

/// Neg risk response from /neg-risk endpoint
#[derive(Debug, Deserialize)]
pub struct NegRiskResponse {
    /// Whether the token is a negative risk market
    pub neg_risk: bool,
}

/// Tick size response from /tick-size endpoint
#[derive(Debug, Deserialize)]
pub struct TickSizeResponse {
    /// The tick size for the token (e.g., "0.01", "0.001")
    pub minimum_tick_size: String,
}

/// Fee rate response from /fee-rate endpoint
#[derive(Debug, Deserialize)]
pub struct FeeRateResponse {
    /// The base fee rate in basis points (e.g., 0 for 0%, 100 for 1%)
    pub base_fee: u32,
}

/// Order book level (price/size pair)
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct OrderBookLevel {
    /// Price level
    pub price: String,
    /// Size at this price level
    pub size: String,
}

/// Order book summary response from /book endpoint
///
/// This is the comprehensive response from the Polymarket CLOB `/book` endpoint
/// that contains all market parameters including neg_risk, tick_size, and min_order_size.
///
/// Reference: <https://docs.polymarket.com/api-reference/orderbook/get-order-book-summary>
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct OrderBookSummary {
    /// Market identifier (condition ID)
    pub market: String,
    /// Asset identifier (token ID)
    pub asset_id: String,
    /// Timestamp of the order book snapshot
    pub timestamp: String,
    /// Hash of the order book state
    pub hash: String,
    /// Array of bid levels (buy orders)
    pub bids: Vec<OrderBookLevel>,
    /// Array of ask levels (sell orders)
    pub asks: Vec<OrderBookLevel>,
    /// Minimum order size for this market
    pub min_order_size: String,
    /// Minimum price increment (tick size)
    pub tick_size: String,
    /// Whether negative risk is enabled for this market
    pub neg_risk: bool,
}

impl OrderBookSummary {
    /// Check if the orderbook has any liquidity (bids or asks)
    #[must_use]
    pub fn has_liquidity(&self) -> bool {
        !self.bids.is_empty() || !self.asks.is_empty()
    }

    /// Get the best bid price (highest buy price)
    #[must_use]
    pub fn best_bid(&self) -> Option<&str> {
        self.bids.first().map(|l| l.price.as_str())
    }

    /// Get the best ask price (lowest sell price)
    #[must_use]
    pub fn best_ask(&self) -> Option<&str> {
        self.asks.first().map(|l| l.price.as_str())
    }

    /// Calculate the spread between best bid and best ask
    #[must_use]
    pub fn spread(&self) -> Option<f64> {
        let bid: f64 = self.best_bid()?.parse().ok()?;
        let ask: f64 = self.best_ask()?.parse().ok()?;
        Some(ask - bid)
    }
}

/// CLOB API client
#[derive(Clone)]
pub struct ClobClient {
    config: ClobConfig,
    client: Client,
    signer: PrivateKeySigner,
    rate_limiter: Arc<RateLimiter>,
    /// Stored API credentials (set after creation)
    api_credentials: Option<ApiCredentials>,
    /// Optional explicit address for Builder API auth (when signer ≠ API key owner)
    auth_address: Option<String>,
    /// Optional Builder signer for Integrator authentication
    builder_signer: Option<BuilderSigner>,
}

impl ClobClient {
    /// Create a new CLOB client
    pub fn new(config: ClobConfig, signer: PrivateKeySigner) -> Result<Self> {
        let client = Client::builder()
            .timeout(config.timeout)
            .user_agent(&config.user_agent)
            .gzip(true)
            .build()
            .map_err(|e| PolymarketError::config(format!("Failed to create HTTP client: {e}")))?;

        let quota = Quota::per_second(
            NonZeroU32::new(config.rate_limit_per_second).unwrap_or(NonZeroU32::new(5).unwrap()),
        );
        let rate_limiter = Arc::new(GovRateLimiter::direct(quota));

        Ok(Self {
            config,
            client,
            signer,
            rate_limiter,
            api_credentials: None,
            auth_address: None,
            builder_signer: None,
        })
    }

    /// Create client from environment variables.
    ///
    /// **Deprecated**: Use `ClobClient::new(ClobConfig::default(), signer)` instead.
    #[deprecated(
        since = "0.1.0",
        note = "Use ClobClient::new(ClobConfig::default(), signer) instead"
    )]
    #[allow(deprecated)]
    pub fn from_env(signer: PrivateKeySigner) -> Result<Self> {
        Self::new(ClobConfig::from_env(), signer)
    }

    /// Set API credentials for L2 authentication
    #[must_use]
    pub fn with_api_credentials(mut self, credentials: ApiCredentials) -> Self {
        self.api_credentials = Some(credentials);
        self
    }

    /// Set explicit auth address (for Builder API authentication)
    ///
    /// Use this when the order signer and API credentials owner are different addresses.
    /// This is common when using Builder API credentials.
    #[must_use]
    pub fn with_auth_address(mut self, address: impl Into<String>) -> Self {
        self.auth_address = Some(address.into());
        self
    }

    /// Set Builder API signer for Integrator authentication
    ///
    /// Use this when submitting orders on behalf of users via Builder API.
    /// The Builder credentials authenticate the Integrator, while the order
    /// signature authenticates the user's wallet.
    ///
    /// # Example
    /// ```ignore
    /// let clob_client = ClobClient::from_env(dummy_signer)
    ///     .with_api_credentials(builder_credentials)
    ///     .with_builder_signer(builder_credentials)  // Enables Builder headers
    ///     .with_auth_address(server_wallet_address);
    /// ```
    #[must_use]
    pub fn with_builder_signer(mut self, credentials: ApiCredentials) -> Self {
        let builder_creds = BuilderApiKeyCreds {
            key: credentials.api_key,
            secret: credentials.secret, // Base64 encoded
            passphrase: credentials.passphrase,
        };
        self.builder_signer = Some(BuilderSigner::new(builder_creds));
        self
    }

    /// Get the signer's address
    #[must_use]
    pub fn address(&self) -> String {
        format!("{:?}", self.signer.address())
    }

    /// Get the address to use for L2 authentication.
    ///
    /// Uses explicit `auth_address` if set (for Builder API scenarios where the
    /// order signer and API credentials owner are different), otherwise falls
    /// back to the signer's address.
    ///
    /// This ensures consistent address handling across all L2-authenticated methods.
    fn get_auth_address(&self) -> String {
        if let Some(ref addr) = self.auth_address {
            if addr.starts_with("0x") {
                addr.clone()
            } else {
                format!("0x{}", addr)
            }
        } else {
            format!("{:?}", self.signer.address())
        }
    }

    /// Wait for rate limiter
    async fn wait_for_rate_limit(&self) {
        self.rate_limiter.until_ready().await;
    }

    /// Derive API key (step 1 of credential creation)
    ///
    /// This gets a nonce and derives the API key from the wallet signature.
    #[instrument(skip(self))]
    pub async fn derive_api_key(&self, nonce: Option<U256>) -> Result<DeriveApiKeyResponse> {
        self.wait_for_rate_limit().await;

        let endpoint = "/auth/derive-api-key";
        let url = format!("{}{}", self.config.base_url, endpoint);

        let headers = create_l1_headers(&self.signer, nonce)?;

        debug!(address = %self.address(), "Deriving API key");

        let mut req_builder = self.client.get(&url);
        for (key, value) in &headers {
            req_builder = req_builder.header(*key, value);
        }

        let response = req_builder.send().await?;
        let status = response.status();

        if !status.is_success() {
            let body = response.text().await.unwrap_or_default();
            return Err(PolymarketError::api(status.as_u16(), body));
        }

        let result: DeriveApiKeyResponse = response.json().await.map_err(|e| {
            PolymarketError::parse_with_source(format!("Failed to parse derive response: {e}"), e)
        })?;

        info!(address = %self.address(), "API key derived successfully");

        Ok(result)
    }

    /// Derive API key with pre-computed signature (for Privy ServerWallet)
    ///
    /// This variant accepts a pre-computed EIP-712 signature, useful when using
    /// external signing services like Privy ServerWallet that don't expose private keys.
    ///
    /// # Workflow
    ///
    /// 1. Generate timestamp and nonce
    /// 2. Use `build_clob_auth_typed_data` from auth module to construct typed data
    /// 3. Call Privy ServerWallet API to sign the typed data
    /// 4. Call this method with the signature
    ///
    /// # Arguments
    ///
    /// * `address` - Wallet address (hex string with or without 0x prefix)
    /// * `signature` - EIP-712 signature (hex string with 0x prefix)
    /// * `timestamp` - Unix timestamp string used in signature
    /// * `nonce` - Nonce value used in signature
    ///
    /// # Returns
    ///
    /// Derived API credentials (api_key, secret, passphrase)
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// use polymarket_sdk::auth::{build_clob_auth_typed_data, get_current_unix_time_secs};
    /// use alloy_primitives::{Address, U256};
    ///
    /// // 1. Prepare signature data
    /// let address: Address = "0x1234...".parse()?;
    /// let timestamp = get_current_unix_time_secs().to_string();
    /// let nonce = U256::ZERO;
    ///
    /// // 2. Build typed data for Privy
    /// let typed_data = build_clob_auth_typed_data(address, &timestamp, nonce);
    ///
    /// // 3. Call Privy ServerWallet API (pseudo-code)
    /// let signature = privy_client.sign_typed_data(server_wallet_id, typed_data).await?;
    ///
    /// // 4. Derive API key with signature
    /// let credentials = clob_client
    ///     .derive_api_key_with_signature(&format!("{:?}", address), &signature, &timestamp, nonce)
    ///     .await?;
    /// ```
    #[instrument(skip(self, signature))]
    pub async fn derive_api_key_with_signature(
        &self,
        address: &str,
        signature: &str,
        timestamp: &str,
        nonce: U256,
    ) -> Result<DeriveApiKeyResponse> {
        self.wait_for_rate_limit().await;

        let endpoint = "/auth/derive-api-key";
        let url = format!("{}{}", self.config.base_url, endpoint);

        // Ensure address has 0x prefix
        let address = if address.starts_with("0x") {
            address.to_string()
        } else {
            format!("0x{}", address)
        };

        // Ensure signature has 0x prefix
        let signature = if signature.starts_with("0x") {
            signature.to_string()
        } else {
            format!("0x{}", signature)
        };

        // Build L1 auth headers manually with pre-computed signature
        let headers = HashMap::from([
            ("poly_address", address.clone()),
            ("poly_signature", signature),
            ("poly_timestamp", timestamp.to_string()),
            ("poly_nonce", nonce.to_string()),
        ]);

        debug!(address = %address, "Deriving API key with pre-computed signature");

        let mut req_builder = self.client.get(&url);
        for (key, value) in &headers {
            req_builder = req_builder.header(*key, value);
        }

        let response = req_builder.send().await?;
        let status = response.status();

        if !status.is_success() {
            let body = response.text().await.unwrap_or_default();
            return Err(PolymarketError::api(status.as_u16(), body));
        }

        let result: DeriveApiKeyResponse = response.json().await.map_err(|e| {
            PolymarketError::parse_with_source(format!("Failed to parse derive response: {e}"), e)
        })?;

        info!(address = %address, "API key derived successfully with pre-computed signature");

        Ok(result)
    }

    /// Create API key with pre-computed signature (for server wallet registration)
    ///
    /// This is the first-time registration step that tells Polymarket about this wallet.
    /// After calling this once, you can use derive_api_key_with_signature for subsequent requests.
    #[instrument(skip(self, signature))]
    pub async fn create_api_key_with_signature(
        &self,
        address: &str,
        signature: &str,
        timestamp: &str,
        nonce: U256,
    ) -> Result<ApiKeyResponse> {
        self.wait_for_rate_limit().await;

        let endpoint = "/auth/api-key";
        let url = format!("{}{}", self.config.base_url, endpoint);

        // Ensure address has 0x prefix
        let address = if address.starts_with("0x") {
            address.to_string()
        } else {
            format!("0x{}", address)
        };

        // Ensure signature has 0x prefix
        let signature = if signature.starts_with("0x") {
            signature.to_string()
        } else {
            format!("0x{}", signature)
        };

        // Build L1 auth headers manually with pre-computed signature
        let headers = HashMap::from([
            ("poly_address", address.clone()),
            ("poly_signature", signature),
            ("poly_timestamp", timestamp.to_string()),
            ("poly_nonce", nonce.to_string()),
        ]);

        let body = CreateApiKeyRequest {
            nonce: nonce.to_string(),
        };

        debug!(address = %address, "Creating API key with pre-computed signature (first-time registration)");

        let mut req_builder = self.client.post(&url).json(&body);
        for (key, value) in &headers {
            req_builder = req_builder.header(*key, value);
        }

        let response = req_builder.send().await?;
        let status = response.status();

        if !status.is_success() {
            let body = response.text().await.unwrap_or_default();
            return Err(PolymarketError::api(status.as_u16(), body));
        }

        let result: ApiKeyResponse = response.json().await.map_err(|e| {
            PolymarketError::parse_with_source(format!("Failed to parse create response: {e}"), e)
        })?;

        info!(address = %address, "API key created successfully (wallet registered)");

        Ok(result)
    }

    /// Derive or create API key with pre-computed signature (for Privy ServerWallet)
    ///
    /// This is a convenience method that handles the common case where a wallet
    /// may or may not have been registered with Polymarket CLOB API yet.
    ///
    /// # Workflow
    ///
    /// 1. Try to derive API key (for existing registrations)
    /// 2. If "Could not derive api key" error (wallet not registered):
    ///    - First call create_api_key_with_signature to register the wallet
    ///    - Then retry derive_api_key_with_signature
    /// 3. Return the derived credentials
    ///
    /// # Arguments
    ///
    /// * `address` - Wallet address (hex string with or without 0x prefix)
    /// * `signature` - EIP-712 signature (hex string with 0x prefix)
    /// * `timestamp` - Unix timestamp string used in signature
    /// * `nonce` - Nonce value used in signature
    ///
    /// # Returns
    ///
    /// Derived API credentials (api_key, secret, passphrase)
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// use polymarket_sdk::auth::{build_clob_auth_typed_data, get_current_unix_time_secs};
    /// use alloy_primitives::{Address, U256};
    ///
    /// // Prepare and sign typed data (see derive_api_key_with_signature for details)
    /// let credentials = clob_client
    ///     .derive_or_create_api_key(&address, &signature, &timestamp, nonce)
    ///     .await?;
    /// ```
    #[instrument(skip(self, signature))]
    pub async fn derive_or_create_api_key(
        &self,
        address: &str,
        signature: &str,
        timestamp: &str,
        nonce: U256,
    ) -> Result<DeriveApiKeyResponse> {
        // Try derive first (common case: wallet already registered)
        match self
            .derive_api_key_with_signature(address, signature, timestamp, nonce)
            .await
        {
            Ok(response) => Ok(response),
            Err(e) if e.is_wallet_not_registered() => {
                // Wallet not registered - register it first, then retry derive
                info!(
                    address = %address,
                    "Wallet not registered with CLOB API, registering first"
                );

                // Step 1: Create/register the API key (first-time registration)
                self.create_api_key_with_signature(address, signature, timestamp, nonce)
                    .await?;

                // Step 2: Retry derive (should succeed now)
                info!(address = %address, "Wallet registered, retrying derive");
                self.derive_api_key_with_signature(address, signature, timestamp, nonce)
                    .await
            }
            Err(e) => Err(e),
        }
    }

    /// Create API key (step 2 of credential creation)
    ///
    /// This registers the derived API key with the CLOB.
    #[instrument(skip(self))]
    pub async fn create_api_key(&self, nonce: U256) -> Result<ApiKeyResponse> {
        self.wait_for_rate_limit().await;

        let endpoint = "/auth/api-key";
        let url = format!("{}{}", self.config.base_url, endpoint);

        let headers = create_l1_headers(&self.signer, Some(nonce))?;

        let body = CreateApiKeyRequest {
            nonce: nonce.to_string(),
        };

        debug!(address = %self.address(), "Creating API key");

        let mut req_builder = self.client.post(&url).json(&body);
        for (key, value) in &headers {
            req_builder = req_builder.header(*key, value);
        }

        let response = req_builder.send().await?;
        let status = response.status();

        if !status.is_success() {
            let body = response.text().await.unwrap_or_default();
            return Err(PolymarketError::api(status.as_u16(), body));
        }

        let result: ApiKeyResponse = response.json().await.map_err(|e| {
            PolymarketError::parse_with_source(format!("Failed to parse create response: {e}"), e)
        })?;

        info!(address = %self.address(), "API key created successfully");

        Ok(result)
    }

    /// Create API credentials (complete flow)
    ///
    /// This performs the full API credential creation flow:
    /// 1. Derive API key with L1 signature
    /// 2. Create/register API key
    ///
    /// # Returns
    /// Complete API credentials ready for L2 authentication
    #[instrument(skip(self))]
    pub async fn create_api_credentials(&self) -> Result<ApiCredentials> {
        info!(address = %self.address(), "Creating API credentials");

        // Step 1: Derive API key (ensures the key derivation is set up)
        let _derive_result = self.derive_api_key(None).await?;

        // Step 2: Create API key with nonce 0 (typical for new credentials)
        let create_result = self.create_api_key(U256::ZERO).await?;

        let credentials = ApiCredentials {
            api_key: create_result.api_key,
            secret: create_result.secret,
            passphrase: create_result.passphrase,
        };

        info!(address = %self.address(), "API credentials created successfully");

        Ok(credentials)
    }

    /// Submit an order
    ///
    /// Requires API credentials to be set via `with_api_credentials`.
    ///
    /// # Arguments
    ///
    /// * `order` - The signed order request
    /// * `order_type` - The order type (GTC for limit orders, FOK for market orders, etc.)
    ///
    /// # Order Types
    ///
    /// - `OrderType::GTC` - Good Till Cancelled (limit order)
    /// - `OrderType::FOK` - Fill Or Kill (market order, must fill completely or cancel)
    /// - `OrderType::GTD` - Good Till Date
    /// - `OrderType::FAK` - Fill And Kill (partial fills allowed, unfilled portion cancelled)
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// use polymarket_sdk::types::OrderType;
    ///
    /// // Limit order (GTC)
    /// client.submit_order(&signed_order, OrderType::GTC).await?;
    ///
    /// // Market order (FOK)
    /// client.submit_order(&signed_order, OrderType::FOK).await?;
    /// ```
    #[instrument(skip(self, order))]
    pub async fn submit_order(
        &self,
        order: &SignedOrderRequest,
        order_type: OrderType,
    ) -> Result<OrderResponse> {
        use crate::types::NewOrder;

        self.wait_for_rate_limit().await;

        let api_creds = self.api_credentials.as_ref().ok_or_else(|| {
            PolymarketError::config("API credentials required for order submission")
        })?;

        let endpoint = "/order";
        let url = format!("{}{}", self.config.base_url, endpoint);

        // IMPORTANT: Convert SignedOrderRequest to NewOrder format
        // - Use api_key as owner (NOT wallet address) - matches TypeScript SDK behavior
        // - Wrap order data in nested structure with orderType and deferExec
        let new_order = NewOrder::from_signed_order(order, &api_creds.api_key, order_type, false);

        // CRITICAL FIX: Serialize JSON ONCE and reuse for all operations
        // This ensures L2 HMAC, Builder HMAC, and HTTP body all use identical JSON
        let body_str = serde_json::to_string(&new_order)
            .map_err(|e| PolymarketError::parse(format!("Failed to serialize order: {}", e)))?;

        // CRITICAL FIX: Get timestamp ONCE and reuse for L2 and Builder headers
        // This ensures both headers use the same timestamp, avoiding signature mismatches
        let timestamp = get_current_unix_time_secs();

        // Get the auth address (either explicit or derived from signer)
        let address = if let Some(ref addr) = self.auth_address {
            if addr.starts_with("0x") {
                addr.clone()
            } else {
                format!("0x{}", addr)
            }
        } else {
            format!("{:?}", self.signer.address())
        };

        // 1. Create standard L2 headers (POLY_*) using pre-serialized body string and shared timestamp
        let mut headers = create_l2_headers_with_body_string(
            &address, api_creds, "POST", endpoint, &body_str, timestamp,
        )?;

        // 2. Inject Builder headers (POLY_BUILDER_*) if Builder signer is configured
        // Use the SAME body_str and SAME timestamp for consistency
        if let Some(ref builder) = self.builder_signer {
            info!("Builder signer configured, generating Builder headers");

            let builder_headers = builder
                .create_builder_header_payload(
                    "POST",
                    endpoint,
                    Some(&body_str),
                    Some(timestamp as i64),
                )
                .map_err(|e| PolymarketError::internal(format!("Builder header error: {}", e)))?;

            info!(
                header_count = builder_headers.len(),
                timestamp = timestamp,
                "Builder headers generated with shared timestamp"
            );

            // Merge Builder headers into existing headers
            // Note: We leak the strings to get 'static lifetime for HashMap keys
            for (key, value) in builder_headers {
                let static_key: &'static str = Box::leak(key.into_boxed_str());
                headers.insert(static_key, value);
            }

            info!(token_id = %order.token_id, side = %order.side, "Submitting order with Builder authentication");
        } else {
            warn!("Builder signer NOT configured - order may fail with 401 Unauthorized");
            info!(token_id = %order.token_id, side = %order.side, "Submitting order WITHOUT Builder authentication");
        }

        // Debug: Print the actual JSON being sent (NewOrder format)
        info!(order_json = %body_str, timestamp = timestamp, "Order JSON payload being sent to Polymarket (NewOrder format)");

        // CRITICAL FIX: Use pre-serialized body string instead of re-serializing with .json()
        // This ensures HTTP body matches exactly what was used for HMAC calculation
        let mut req_builder = self
            .client
            .post(&url)
            .header("Content-Type", "application/json")
            .body(body_str.clone());
        for (key, value) in &headers {
            req_builder = req_builder.header(*key, value);
        }

        let response = req_builder.send().await?;
        let status = response.status();

        if !status.is_success() {
            let body = response.text().await.unwrap_or_default();
            return Err(PolymarketError::api(status.as_u16(), body));
        }

        let result: OrderResponse = response.json().await.map_err(|e| {
            PolymarketError::parse_with_source(format!("Failed to parse order response: {e}"), e)
        })?;

        // Check if order submission was successful
        if !result.success {
            return Err(PolymarketError::api(
                400,
                format!(
                    "Order rejected: {} (status: {})",
                    result.error_msg, result.status
                ),
            ));
        }

        info!(
            order_id = %result.order_id,
            status = %result.status,
            success = result.success,
            "Order submitted successfully"
        );

        Ok(result)
    }

    /// Get a single order by its ID
    ///
    /// Retrieves detailed information about an existing order.
    /// This endpoint requires L2 authentication headers.
    ///
    /// Reference: <https://docs.polymarket.com/developers/CLOB/orders/get-order>
    ///
    /// # Arguments
    /// * `order_id` - The order hash/ID to query
    ///
    /// # Returns
    /// * `Ok(Some(OpenOrder))` - Order details if found
    /// * `Ok(None)` - Order not found
    /// * `Err(...)` - API error
    ///
    /// # Example
    /// ```rust,ignore
    /// let order = client.get_order("0xb816482a5187a3d3db49cbaf6fe3ddf24f53e6c712b5a4bf5e01d0ec7b11dabc").await?;
    /// if let Some(order) = order {
    ///     println!("Order status: {}", order.status);
    ///     println!("Price: {}", order.price);
    ///     println!("Size matched: {}", order.size_matched);
    /// }
    /// ```
    #[instrument(skip(self))]
    pub async fn get_order(&self, order_id: &str) -> Result<Option<OpenOrder>> {
        self.wait_for_rate_limit().await;

        let api_creds = self.api_credentials.as_ref().ok_or_else(|| {
            PolymarketError::config("API credentials required for querying order")
        })?;

        let endpoint = format!("/data/order/{}", order_id);
        let url = format!("{}{}", self.config.base_url, endpoint);

        // Use auth_address for L2 authentication (supports Builder API scenarios)
        let address = self.get_auth_address();
        let headers =
            create_l2_headers_with_address::<String>(&address, api_creds, "GET", &endpoint, None)?;

        debug!(order_id = %order_id, "Getting order details");

        let mut req_builder = self.client.get(&url);
        for (key, value) in &headers {
            req_builder = req_builder.header(*key, value);
        }

        let response = req_builder.send().await?;
        let status = response.status();

        // Handle 404 as order not found
        if status.as_u16() == 404 {
            info!(order_id = %order_id, "Order not found (404)");
            return Ok(None);
        }

        if !status.is_success() {
            let body = response.text().await.unwrap_or_default();
            return Err(PolymarketError::api(status.as_u16(), body));
        }

        // Get response body as text first to handle various response formats
        // The API may return HTTP 200 with null, empty object, or error message
        // when the order is not found (similar to official SDK 0.3.x behavior)
        let body = response.text().await.unwrap_or_default();

        // Handle empty response or null
        if body.is_empty() || body == "null" || body == "{}" {
            info!(order_id = %order_id, "Order not found (empty/null response)");
            return Ok(None);
        }

        // Try to parse as JSON Value first to check for error responses
        let json_value: serde_json::Value = serde_json::from_str(&body).map_err(|e| {
            PolymarketError::parse_with_source(
                format!("Failed to parse order response as JSON: {e}"),
                e,
            )
        })?;

        // Check if response contains an error field or indicates not found
        if let Some(obj) = json_value.as_object() {
            // Handle {"error": "..."} responses
            if obj.contains_key("error") {
                let error_msg = obj
                    .get("error")
                    .and_then(|v| v.as_str())
                    .unwrap_or("unknown error");
                // Treat error responses as "not found" if they indicate the order doesn't exist
                if error_msg.to_lowercase().contains("not found")
                    || error_msg.to_lowercase().contains("does not exist")
                {
                    info!(order_id = %order_id, error = %error_msg, "Order not found (error response)");
                    return Ok(None);
                }
                // For other errors, return as API error
                return Err(PolymarketError::api(200, format!("API error: {error_msg}")));
            }

            // Check if the response has required fields for OpenOrder
            // If it's missing essential fields, treat as not found
            if !obj.contains_key("id") && !obj.contains_key("order_id") {
                info!(order_id = %order_id, "Order not found (missing required fields)");
                return Ok(None);
            }
        } else if json_value.is_null() {
            info!(order_id = %order_id, "Order not found (null JSON)");
            return Ok(None);
        }

        // Now try to deserialize as OpenOrder
        let order: OpenOrder = serde_json::from_value(json_value).map_err(|e| {
            PolymarketError::parse_with_source(format!("Failed to parse order response: {e}"), e)
        })?;

        debug!(
            order_id = %order_id,
            status = %order.status,
            price = %order.price,
            "Retrieved order details"
        );

        Ok(Some(order))
    }

    /// Get open orders for the signer
    #[instrument(skip(self))]
    pub async fn get_open_orders(&self) -> Result<Vec<OpenOrder>> {
        self.wait_for_rate_limit().await;

        let api_creds = self.api_credentials.as_ref().ok_or_else(|| {
            PolymarketError::config("API credentials required for querying orders")
        })?;

        // IMPORTANT: Use /data/orders endpoint for GET (not /orders which is for POST)
        let endpoint = "/data/orders";
        let url = format!("{}{}", self.config.base_url, endpoint);

        // Use auth_address for L2 authentication (supports Builder API scenarios)
        let address = self.get_auth_address();
        let headers =
            create_l2_headers_with_address::<String>(&address, api_creds, "GET", endpoint, None)?;

        debug!(address = %self.address(), "Getting open orders");

        let mut req_builder = self.client.get(&url);
        for (key, value) in &headers {
            req_builder = req_builder.header(*key, value);
        }

        let response = req_builder.send().await?;
        let status = response.status();

        if !status.is_success() {
            let body = response.text().await.unwrap_or_default();
            return Err(PolymarketError::api(status.as_u16(), body));
        }

        // Parse as paginated response
        let paginated: PaginatedResponse<OpenOrder> = response.json().await.map_err(|e| {
            PolymarketError::parse_with_source(format!("Failed to parse orders response: {e}"), e)
        })?;

        debug!(count = %paginated.data.len(), "Retrieved open orders");

        Ok(paginated.data)
    }

    /// Cancel a single order by ID
    ///
    /// Sends `DELETE /order` with body `{"orderID": "0x..."}`.
    ///
    /// Reference: <https://docs.polymarket.com/developers/CLOB/orders/cancel-orders#cancel-an-single-order>
    ///
    /// # Arguments
    /// * `order_id` - The order hash/ID to cancel
    ///
    /// # Example
    /// ```rust,ignore
    /// let resp = client.cancel_order("0x38a73eed...").await?;
    /// println!("Canceled: {:?}", resp.canceled);
    /// ```
    #[instrument(skip(self))]
    pub async fn cancel_order(&self, order_id: &str) -> Result<CancelResponse> {
        self.wait_for_rate_limit().await;

        let api_creds = self.api_credentials.as_ref().ok_or_else(|| {
            PolymarketError::config("API credentials required for cancelling order")
        })?;

        let endpoint = "/order";
        let url = format!("{}{}", self.config.base_url, endpoint);

        let body = CancelOrderRequest {
            order_id: order_id.to_string(),
        };

        // Use auth_address for L2 authentication (supports Builder API scenarios)
        // Serialize body once to ensure consistent HMAC calculation
        let address = self.get_auth_address();
        let body_str = serde_json::to_string(&body)
            .map_err(|e| PolymarketError::parse(format!("Failed to serialize: {}", e)))?;
        let timestamp = get_current_unix_time_secs();
        let headers = create_l2_headers_with_body_string(
            &address, api_creds, "DELETE", endpoint, &body_str, timestamp,
        )?;

        debug!(order_id = %order_id, "Cancelling single order");

        let mut req_builder = self
            .client
            .delete(&url)
            .header("Content-Type", "application/json")
            .body(body_str);
        for (key, value) in &headers {
            req_builder = req_builder.header(*key, value);
        }

        let response = req_builder.send().await?;
        let status = response.status();

        if !status.is_success() {
            let body = response.text().await.unwrap_or_default();
            return Err(PolymarketError::api(status.as_u16(), body));
        }

        let result: CancelResponse = response.json().await.map_err(|e| {
            PolymarketError::parse_with_source(format!("Failed to parse cancel response: {e}"), e)
        })?;

        info!(order_id = %order_id, cancelled = ?result.canceled, "Order cancelled");

        Ok(result)
    }

    /// Cancel multiple orders by IDs
    ///
    /// Sends `DELETE /orders` with body `["0x...", "0x..."]` (pure JSON array).
    ///
    /// Reference: <https://docs.polymarket.com/developers/CLOB/orders/cancel-orders#cancel-multiple-orders>
    ///
    /// # Arguments
    /// * `order_ids` - List of order hashes/IDs to cancel
    ///
    /// # Example
    /// ```rust,ignore
    /// let resp = client.cancel_orders(vec![
    ///     "0x38a73eed...".to_string(),
    ///     "0xaaaa...".to_string(),
    /// ]).await?;
    /// println!("Canceled: {:?}", resp.canceled);
    /// ```
    #[instrument(skip(self))]
    pub async fn cancel_orders(&self, order_ids: Vec<String>) -> Result<CancelResponse> {
        self.wait_for_rate_limit().await;

        let api_creds = self.api_credentials.as_ref().ok_or_else(|| {
            PolymarketError::config("API credentials required for cancelling orders")
        })?;

        // NOTE: Batch cancel uses /orders (plural), not /order
        let endpoint = "/orders";
        let url = format!("{}{}", self.config.base_url, endpoint);

        // Polymarket expects a raw JSON array: ["0x...", "0x..."]
        // NOT an object like {"orderIds": [...]}
        let body_str = serde_json::to_string(&order_ids)
            .map_err(|e| PolymarketError::parse(format!("Failed to serialize: {}", e)))?;

        // Use auth_address for L2 authentication (supports Builder API scenarios)
        let address = self.get_auth_address();
        let timestamp = get_current_unix_time_secs();
        let headers = create_l2_headers_with_body_string(
            &address, api_creds, "DELETE", endpoint, &body_str, timestamp,
        )?;

        debug!(count = order_ids.len(), "Cancelling multiple orders");

        let mut req_builder = self
            .client
            .delete(&url)
            .header("Content-Type", "application/json")
            .body(body_str);
        for (key, value) in &headers {
            req_builder = req_builder.header(*key, value);
        }

        let response = req_builder.send().await?;
        let status = response.status();

        if !status.is_success() {
            let body = response.text().await.unwrap_or_default();
            return Err(PolymarketError::api(status.as_u16(), body));
        }

        let result: CancelResponse = response.json().await.map_err(|e| {
            PolymarketError::parse_with_source(format!("Failed to parse cancel response: {e}"), e)
        })?;

        info!(cancelled = ?result.canceled, "Orders cancelled");

        Ok(result)
    }

    /// Cancel all open orders
    ///
    /// Sends `DELETE /cancel-all` with no body.
    ///
    /// Reference: <https://docs.polymarket.com/developers/CLOB/orders/cancel-orders#cancel-all-orders>
    ///
    /// # Example
    /// ```rust,ignore
    /// let resp = client.cancel_all_orders().await?;
    /// println!("Canceled: {:?}", resp.canceled);
    /// ```
    #[instrument(skip(self))]
    pub async fn cancel_all_orders(&self) -> Result<CancelResponse> {
        self.wait_for_rate_limit().await;

        let api_creds = self.api_credentials.as_ref().ok_or_else(|| {
            PolymarketError::config("API credentials required for cancelling orders")
        })?;

        let endpoint = "/cancel-all";
        let url = format!("{}{}", self.config.base_url, endpoint);

        // Use auth_address for L2 authentication (supports Builder API scenarios)
        let address = self.get_auth_address();
        let headers = create_l2_headers_with_address::<String>(
            &address, api_creds, "DELETE", endpoint, None,
        )?;

        debug!(address = %self.address(), "Cancelling all orders");

        let mut req_builder = self.client.delete(&url);
        for (key, value) in &headers {
            req_builder = req_builder.header(*key, value);
        }

        let response = req_builder.send().await?;
        let status = response.status();

        if !status.is_success() {
            let body = response.text().await.unwrap_or_default();
            return Err(PolymarketError::api(status.as_u16(), body));
        }

        let result: CancelResponse = response.json().await.map_err(|e| {
            PolymarketError::parse_with_source(format!("Failed to parse cancel response: {e}"), e)
        })?;

        info!(cancelled = ?result.canceled, "All orders cancelled");

        Ok(result)
    }

    /// Cancel orders for a specific market
    ///
    /// Sends `DELETE /cancel-market-orders` with body `{"market": "...", "asset_id": "..."}`.
    /// At least one of `market` (condition_id) or `asset_id` (token_id) should be provided.
    ///
    /// Reference: <https://docs.polymarket.com/developers/CLOB/orders/cancel-orders#cancel-orders-from-market>
    ///
    /// # Arguments
    /// * `market` - Optional condition ID of the market
    /// * `asset_id` - Optional token/asset ID
    ///
    /// # Example
    /// ```rust,ignore
    /// // Cancel all orders for a specific market
    /// let resp = client.cancel_market_orders(
    ///     Some("0xbd31dc8a..."),
    ///     None,
    /// ).await?;
    ///
    /// // Cancel all orders for a specific asset
    /// let resp = client.cancel_market_orders(
    ///     None,
    ///     Some("52114319501245915516055106046884209969926127482827954674443846427813813222426"),
    /// ).await?;
    /// ```
    #[instrument(skip(self))]
    pub async fn cancel_market_orders(
        &self,
        market: Option<&str>,
        asset_id: Option<&str>,
    ) -> Result<CancelResponse> {
        self.wait_for_rate_limit().await;

        let api_creds = self.api_credentials.as_ref().ok_or_else(|| {
            PolymarketError::config("API credentials required for cancelling market orders")
        })?;

        let endpoint = "/cancel-market-orders";
        let url = format!("{}{}", self.config.base_url, endpoint);

        // Build the body with optional fields
        let mut body_map = serde_json::Map::new();
        if let Some(m) = market {
            body_map.insert(
                "market".to_string(),
                serde_json::Value::String(m.to_string()),
            );
        }
        if let Some(a) = asset_id {
            body_map.insert(
                "asset_id".to_string(),
                serde_json::Value::String(a.to_string()),
            );
        }
        let body_str = serde_json::to_string(&body_map)
            .map_err(|e| PolymarketError::parse(format!("Failed to serialize: {}", e)))?;

        // Use auth_address for L2 authentication (supports Builder API scenarios)
        let address = self.get_auth_address();
        let timestamp = get_current_unix_time_secs();
        let headers = create_l2_headers_with_body_string(
            &address, api_creds, "DELETE", endpoint, &body_str, timestamp,
        )?;

        debug!(market = ?market, asset_id = ?asset_id, "Cancelling market orders");

        let mut req_builder = self
            .client
            .delete(&url)
            .header("Content-Type", "application/json")
            .body(body_str);
        for (key, value) in &headers {
            req_builder = req_builder.header(*key, value);
        }

        let response = req_builder.send().await?;
        let status = response.status();

        if !status.is_success() {
            let body = response.text().await.unwrap_or_default();
            return Err(PolymarketError::api(status.as_u16(), body));
        }

        let result: CancelResponse = response.json().await.map_err(|e| {
            PolymarketError::parse_with_source(format!("Failed to parse cancel response: {e}"), e)
        })?;

        info!(market = ?market, asset_id = ?asset_id, cancelled = ?result.canceled, "Market orders cancelled");

        Ok(result)
    }

    /// Get the order book summary for a token ID
    ///
    /// Queries the Polymarket CLOB `/book` endpoint to retrieve the complete
    /// order book summary including market parameters like `neg_risk`, `tick_size`,
    /// and `min_order_size`, as well as the current bid/ask levels.
    ///
    /// This is the recommended method to use instead of separate calls to
    /// `get_neg_risk`, `get_tick_size`, and `check_orderbook_exists`.
    ///
    /// Reference: <https://docs.polymarket.com/api-reference/orderbook/get-order-book-summary>
    ///
    /// # Arguments
    /// * `token_id` - The token ID (CLOB token / asset ID) to query
    ///
    /// # Returns
    /// * `Ok(Some(OrderBookSummary))` - The order book exists and summary is returned
    /// * `Ok(None)` - The order book does not exist (market closed or invalid token)
    /// * `Err(...)` - API error occurred
    ///
    /// # Example
    /// ```rust,ignore
    /// let summary = client.get_orderbook_summary(token_id).await?;
    /// if let Some(book) = summary {
    ///     println!("neg_risk: {}", book.neg_risk);
    ///     println!("tick_size: {}", book.tick_size);
    ///     println!("min_order_size: {}", book.min_order_size);
    ///     println!("bids: {:?}", book.bids);
    ///     println!("asks: {:?}", book.asks);
    /// } else {
    ///     println!("Orderbook does not exist");
    /// }
    /// ```
    #[instrument(skip(self))]
    pub async fn get_orderbook_summary(&self, token_id: &str) -> Result<Option<OrderBookSummary>> {
        self.wait_for_rate_limit().await;

        let endpoint = "/book";
        let url = format!("{}{}?token_id={}", self.config.base_url, endpoint, token_id);

        debug!(token_id = %token_id, "Fetching orderbook summary");

        let response = self.client.get(&url).send().await?;
        let status = response.status();

        // Get response body
        let body = response.text().await.unwrap_or_default();

        // API returns 200 with {"error": "..."} for non-existent orderbooks
        if body.contains("does not exist") || body.contains("No orderbook") {
            info!(token_id = %token_id, "Orderbook does not exist");
            return Ok(None);
        }

        // Handle 404 as orderbook not found
        if status.as_u16() == 404 {
            info!(token_id = %token_id, "Orderbook not found (404)");
            return Ok(None);
        }

        if !status.is_success() {
            return Err(PolymarketError::api(status.as_u16(), body));
        }

        // Parse the orderbook summary
        let summary: OrderBookSummary = serde_json::from_str(&body).map_err(|e| {
            PolymarketError::parse_with_source(format!("Failed to parse orderbook summary: {e}"), e)
        })?;

        debug!(
            token_id = %token_id,
            neg_risk = %summary.neg_risk,
            tick_size = %summary.tick_size,
            min_order_size = %summary.min_order_size,
            bids_count = %summary.bids.len(),
            asks_count = %summary.asks.len(),
            "Got orderbook summary"
        );

        Ok(Some(summary))
    }

    /// Get the neg_risk status for a token ID
    ///
    /// **Deprecated**: Use [`Self::get_orderbook_summary`] instead, which returns all market
    /// parameters in a single API call.
    ///
    /// Queries the Polymarket CLOB API to determine if a market/token uses
    /// negative risk contracts. This is crucial for signing orders with the
    /// correct exchange contract address.
    ///
    /// # Arguments
    /// * `token_id` - The token ID (condition token) to check
    ///
    /// # Returns
    /// * `true` if the market uses negative risk contracts (use negRiskExchange)
    /// * `false` if the market uses standard contracts (use exchange)
    #[deprecated(
        since = "0.2.0",
        note = "Use get_orderbook_summary() instead, which returns neg_risk, tick_size, and min_order_size in a single API call"
    )]
    #[instrument(skip(self))]
    pub async fn get_neg_risk(&self, token_id: &str) -> Result<bool> {
        self.wait_for_rate_limit().await;

        let endpoint = "/neg-risk";
        let url = format!("{}{}?token_id={}", self.config.base_url, endpoint, token_id);

        debug!(token_id = %token_id, "Querying neg_risk status");

        let response = self.client.get(&url).send().await?;
        let status = response.status();

        if !status.is_success() {
            let body = response.text().await.unwrap_or_default();
            return Err(PolymarketError::api(status.as_u16(), body));
        }

        let result: NegRiskResponse = response.json().await.map_err(|e| {
            PolymarketError::parse_with_source(format!("Failed to parse neg_risk response: {e}"), e)
        })?;

        debug!(token_id = %token_id, neg_risk = %result.neg_risk, "Got neg_risk status");

        Ok(result.neg_risk)
    }

    /// Get the tick size for a token ID
    ///
    /// **Deprecated**: Use [`Self::get_orderbook_summary`] instead, which returns all market
    /// parameters in a single API call.
    ///
    /// Queries the Polymarket CLOB API to get the minimum tick size for
    /// price rounding on a specific market.
    ///
    /// # Arguments
    /// * `token_id` - The token ID (condition token) to check
    ///
    /// # Returns
    /// The tick size as a string (e.g., "0.01", "0.001", "0.0001")
    #[deprecated(
        since = "0.2.0",
        note = "Use get_orderbook_summary() instead, which returns neg_risk, tick_size, and min_order_size in a single API call"
    )]
    #[instrument(skip(self))]
    pub async fn get_tick_size(&self, token_id: &str) -> Result<String> {
        self.wait_for_rate_limit().await;

        let endpoint = "/tick-size";
        let url = format!("{}{}?token_id={}", self.config.base_url, endpoint, token_id);

        debug!(token_id = %token_id, "Querying tick size");

        let response = self.client.get(&url).send().await?;
        let status = response.status();

        if !status.is_success() {
            let body = response.text().await.unwrap_or_default();
            return Err(PolymarketError::api(status.as_u16(), body));
        }

        let result: TickSizeResponse = response.json().await.map_err(|e| {
            PolymarketError::parse_with_source(
                format!("Failed to parse tick_size response: {e}"),
                e,
            )
        })?;

        debug!(token_id = %token_id, tick_size = %result.minimum_tick_size, "Got tick size");

        Ok(result.minimum_tick_size)
    }

    /// Get the fee rate for a token ID
    ///
    /// Queries the Polymarket CLOB API to get the fee rate (in basis points)
    /// for a specific market/token. This is crucial for signing orders with
    /// the correct fee rate that matches what the API expects.
    ///
    /// # Arguments
    /// * `token_id` - The token ID (condition token) to check
    ///
    /// # Returns
    /// The fee rate in basis points (e.g., 0 for 0%, 100 for 1%)
    ///
    /// # Note
    /// Orders MUST use the fee rate returned by this API, otherwise the
    /// EIP-712 signature will not match and the order will be rejected
    /// with "invalid signature".
    #[instrument(skip(self))]
    pub async fn get_fee_rate(&self, token_id: &str) -> Result<u32> {
        self.wait_for_rate_limit().await;

        let endpoint = "/fee-rate";
        let url = format!("{}{}?token_id={}", self.config.base_url, endpoint, token_id);

        debug!(token_id = %token_id, "Querying fee rate");

        let response = self.client.get(&url).send().await?;
        let status = response.status();

        if !status.is_success() {
            let body = response.text().await.unwrap_or_default();
            return Err(PolymarketError::api(status.as_u16(), body));
        }

        let result: FeeRateResponse = response.json().await.map_err(|e| {
            PolymarketError::parse_with_source(format!("Failed to parse fee_rate response: {e}"), e)
        })?;

        debug!(token_id = %token_id, fee_rate_bps = %result.base_fee, "Got fee rate");

        Ok(result.base_fee)
    }

    /// Check if an orderbook exists for a token ID
    ///
    /// **Deprecated**: Use [`Self::get_orderbook_summary`] instead, which returns all market
    /// parameters in a single API call. Check for `Some(...)` vs `None` to determine
    /// if the orderbook exists.
    ///
    /// Queries the Polymarket CLOB `/book` endpoint to verify that an
    /// active orderbook exists for the given token. This should be called
    /// before submitting orders to avoid "orderbook does not exist" errors.
    ///
    /// # Arguments
    /// * `token_id` - The token ID (CLOB token / asset ID) to check
    ///
    /// # Returns
    /// * `true` if the orderbook exists and is active
    /// * `false` if the orderbook does not exist or the market is closed
    ///
    /// # Note
    /// Markets can have valid neg_risk and fee_rate data but no active
    /// orderbook (e.g., resolved or closed markets). Always verify
    /// orderbook existence before submitting orders.
    #[deprecated(
        since = "0.2.0",
        note = "Use get_orderbook_summary() instead. Check for Some(...) vs None to determine if orderbook exists"
    )]
    #[instrument(skip(self))]
    pub async fn check_orderbook_exists(&self, token_id: &str) -> Result<bool> {
        self.wait_for_rate_limit().await;

        let endpoint = "/book";
        let url = format!("{}{}?token_id={}", self.config.base_url, endpoint, token_id);

        debug!(token_id = %token_id, "Checking orderbook existence");

        let response = self.client.get(&url).send().await?;
        let status = response.status();

        // Check response body for error
        let body = response.text().await.unwrap_or_default();

        // API returns 200 with {"error": "..."} for non-existent orderbooks
        if body.contains("does not exist") || body.contains("No orderbook") {
            info!(token_id = %token_id, "Orderbook does not exist");
            return Ok(false);
        }

        if !status.is_success() {
            // Other API errors
            return Err(PolymarketError::api(status.as_u16(), body));
        }

        // If we got here, the orderbook exists
        debug!(token_id = %token_id, "Orderbook exists");
        Ok(true)
    }

    /// Get balance and allowance for specific tokens
    ///
    /// Retrieves the cached balance and allowance for your account.
    /// Use [`Self::update_balance_allowance`] to refresh the cached values first
    /// if you suspect they are stale.
    ///
    /// Reference: <https://docs.polymarket.com/trading/clients/l2#getbalanceallowance>
    ///
    /// # Arguments
    /// * `params` - Asset type and optional token ID to query
    ///
    /// # Example
    /// ```rust,ignore
    /// use polymarket_sdk::types::{BalanceAllowanceParams, AssetType};
    ///
    /// // Query USDC collateral balance
    /// let result = client.get_balance_allowance(
    ///     &BalanceAllowanceParams::collateral()
    /// ).await?;
    /// println!("Balance: {}, Allowance: {}", result.balance, result.allowance);
    ///
    /// // Query conditional token balance
    /// let result = client.get_balance_allowance(
    ///     &BalanceAllowanceParams::conditional("52114319...")
    /// ).await?;
    /// ```
    #[instrument(skip(self))]
    pub async fn get_balance_allowance(
        &self,
        params: &BalanceAllowanceParams,
    ) -> Result<BalanceAllowanceResponse> {
        self.wait_for_rate_limit().await;

        let api_creds = self.api_credentials.as_ref().ok_or_else(|| {
            PolymarketError::config("API credentials required for querying balance allowance")
        })?;

        let endpoint = "/balance-allowance";
        let query_string = params.to_query_string();
        let url = format!("{}{}?{}", self.config.base_url, endpoint, query_string);

        let address = self.get_auth_address();
        let headers =
            create_l2_headers_with_address::<String>(&address, api_creds, "GET", endpoint, None)?;

        debug!(asset_type = %params.asset_type, "Getting balance allowance");

        let mut req_builder = self.client.get(&url);
        for (key, value) in &headers {
            req_builder = req_builder.header(*key, value);
        }

        let response = req_builder.send().await?;
        let status = response.status();

        if !status.is_success() {
            let body = response.text().await.unwrap_or_default();
            return Err(PolymarketError::api(status.as_u16(), body));
        }

        let result: BalanceAllowanceResponse = response.json().await.map_err(|e| {
            PolymarketError::parse_with_source(
                format!("Failed to parse balance allowance response: {e}"),
                e,
            )
        })?;

        debug!(
            balance = %result.balance,
            allowance = %result.allowance,
            "Got balance allowance"
        );

        Ok(result)
    }

    /// Update (refresh) the cached balance and allowance for specific tokens
    ///
    /// Forces the CLOB API to re-read on-chain balance and allowance values.
    /// Call this after on-chain operations (deposits, approvals) to ensure
    /// the API has up-to-date values before placing orders.
    ///
    /// Reference: <https://docs.polymarket.com/trading/clients/l2#updatebalanceallowance>
    ///
    /// # Arguments
    /// * `params` - Asset type and optional token ID to update
    ///
    /// # Example
    /// ```rust,ignore
    /// use polymarket_sdk::types::{BalanceAllowanceParams, AssetType};
    ///
    /// // Refresh USDC collateral balance after a deposit
    /// client.update_balance_allowance(
    ///     &BalanceAllowanceParams::collateral().with_signature_type(2)
    /// ).await?;
    ///
    /// // Now get the updated balance
    /// let result = client.get_balance_allowance(
    ///     &BalanceAllowanceParams::collateral()
    /// ).await?;
    /// ```
    #[instrument(skip(self))]
    pub async fn update_balance_allowance(
        &self,
        params: &BalanceAllowanceParams,
    ) -> Result<()> {
        self.wait_for_rate_limit().await;

        let api_creds = self.api_credentials.as_ref().ok_or_else(|| {
            PolymarketError::config("API credentials required for updating balance allowance")
        })?;

        let endpoint = "/balance-allowance/update";
        let query_string = params.to_query_string();
        let url = format!("{}{}?{}", self.config.base_url, endpoint, query_string);

        let address = self.get_auth_address();
        let headers =
            create_l2_headers_with_address::<String>(&address, api_creds, "GET", endpoint, None)?;

        debug!(asset_type = %params.asset_type, "Updating balance allowance");

        let mut req_builder = self.client.get(&url);
        for (key, value) in &headers {
            req_builder = req_builder.header(*key, value);
        }

        let response = req_builder.send().await?;
        let status = response.status();

        if !status.is_success() {
            let body = response.text().await.unwrap_or_default();
            return Err(PolymarketError::api(status.as_u16(), body));
        }

        info!(asset_type = %params.asset_type, "Balance allowance updated");

        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_clob_config_default() {
        let config = ClobConfig::default();
        // URL uses helper function which may be overridden by env var
        assert_eq!(config.base_url, clob_api_url());
        assert_eq!(config.timeout, Duration::from_secs(30));
        assert_eq!(config.rate_limit_per_second, 5);
    }

    #[test]
    fn test_clob_config_with_base_url() {
        let config = ClobConfig::default().with_base_url("https://custom.example.com");
        assert_eq!(config.base_url, "https://custom.example.com");
    }
}