clob_client_rust/

client.rs

use crate::constants::{END_CURSOR, INITIAL_CURSOR};
use crate::endpoints::{
    ARE_ORDERS_SCORING, CANCEL_ALL, CANCEL_MARKET_ORDERS, CANCEL_ORDER, CANCEL_ORDERS, CLOSED_ONLY,
    CREATE_API_KEY, CREATE_BUILDER_API_KEY, CREATE_READONLY_API_KEY, DELETE_API_KEY,
    DELETE_READONLY_API_KEY, DERIVE_API_KEY, DROP_NOTIFICATIONS, GET_API_KEYS,
    GET_BALANCE_ALLOWANCE, GET_BUILDER_API_KEYS, GET_BUILDER_TRADES, GET_EARNINGS_FOR_USER_FOR_DAY,
    GET_FEE_RATE, GET_LAST_TRADE_PRICE, GET_LAST_TRADES_PRICES, GET_LIQUIDITY_REWARD_PERCENTAGES,
    GET_MARKET, GET_MARKET_TRADES_EVENTS, GET_MARKETS, GET_MIDPOINT, GET_MIDPOINTS, GET_NEG_RISK,
    GET_NOTIFICATIONS, GET_OPEN_ORDERS, GET_ORDER, GET_ORDER_BOOK, GET_ORDER_BOOKS, GET_PRICE,
    GET_PRICES, GET_PRICES_HISTORY, GET_READONLY_API_KEYS, GET_REWARDS_EARNINGS_PERCENTAGES,
    GET_REWARDS_MARKETS, GET_REWARDS_MARKETS_CURRENT, GET_SAMPLING_MARKETS,
    GET_SAMPLING_SIMPLIFIED_MARKETS, GET_SIMPLIFIED_MARKETS, GET_SPREAD, GET_SPREADS,
    GET_TICK_SIZE, GET_TOTAL_EARNINGS_FOR_USER_FOR_DAY, GET_TRADES, IS_ORDER_SCORING,
    POST_HEARTBEAT, POST_ORDER, POST_ORDERS, REVOKE_BUILDER_API_KEY, TIME,
    UPDATE_BALANCE_ALLOWANCE, VALIDATE_READONLY_API_KEY,
};
use crate::errors::ClobError;
// use crate::exchange_consts::ZERO_ADDRESS; // no longer needed; we resolve real exchange addresses dynamically
use crate::http_helpers::RequestOptions;
use crate::order_builder::{BuilderConfig as ObBuilderConfig, OrderBuilder};
use crate::signer_adapter::EthersSigner;
use crate::types::OrderBookSummary;
use crate::types::{ApiKeyCreds, ApiKeyRaw};
use crate::types::{DeleteReadonlyApiKeyRequest, ReadonlyApiKeyResponse};
use crate::types::{HeartbeatResponse, PostOrdersArgs};
use crate::types::{
    Notification, OpenOrder, Order, OrderResponse, OrderType, Reward, SignedOrder, Trade,
    UserMarketOrder, UserOrder,
};
// Removed unused alias import (Signer) after refactor; keep file clean
use serde::Deserialize;
use serde_json::Value;

#[allow(dead_code)]
#[derive(Deserialize)]
struct OkResp {
    ok: bool,
}

#[allow(dead_code)]
#[derive(Deserialize)]
struct SuccessResp {
    success: bool,
}
// Helper enums to accept either a bare array or an object with a `data` field
#[derive(Deserialize)]
#[serde(untagged)]
enum MaybeVec<T> {
    Vec(Vec<T>),
    Data { data: Vec<T> },
}

impl<T> MaybeVec<T> {
    fn into_vec(self) -> Vec<T> {
        match self {
            MaybeVec::Vec(v) => v,
            MaybeVec::Data { data } => data,
        }
    }
}

#[derive(Deserialize)]
#[serde(untagged)]
enum MaybeItem<T> {
    Item(T),
    Data { data: T },
}

impl<T> MaybeItem<T> {
    fn into_item(self) -> T {
        match self {
            MaybeItem::Item(i) => i,
            MaybeItem::Data { data } => data,
        }
    }
}
use dashmap::DashMap;
use rust_decimal::Decimal;
use std::sync::Arc;

/// TypeScript parity payload for cancellation: `{ orderID: string }`.
/// 使用 serde rename 保持 JSON 键与 TS 保持一致。
#[derive(Clone, Debug, serde::Serialize)]
pub struct OrderPayloadParity {
    #[serde(rename = "orderID")]
    pub order_id: String,
}

impl OrderPayloadParity {
    pub fn new(order_id: impl Into<String>) -> Self {
        Self {
            order_id: order_id.into(),
        }
    }
}

pub struct ClobClient {
    pub host: String,
    pub chain_id: i64,
    /// HTTP 客户端实例。
    ///
    /// - 调用方传入 `Some(client)` 时使用该实例（可自定义代理、超时等）。
    /// - 传入 `None` 时使用全局共享默认实例（`http_helpers::default_client()` clone），
    ///   所有未自定义的 ClobClient 共享同一连接池。
    pub http_client: reqwest::Client,
    pub signer: Option<Arc<EthersSigner>>,
    pub creds: Option<ApiKeyCreds>,
    pub use_server_time: bool,
    /// Optional geo block token passed as query parameter `geo_block_token`.
    pub geo_block_token: Option<String>,
    pub tick_sizes: DashMap<String, String>,
    pub neg_risk: DashMap<String, bool>,
    pub fee_rates: DashMap<String, Decimal>,
    /// Optional Builder signer for builder-authenticated flows
    pub builder_signer: Option<builder_signing_sdk_rs::BuilderSigner>,
    /// Optional default builder config for order creation
    pub builder_config: Option<ObBuilderConfig>,
}

impl ClobClient {
    /// Helper to extract L2 credentials or return appropriate error.
    fn require_creds(&self) -> Result<&ApiKeyCreds, ClobError> {
        self.creds.as_ref().ok_or(ClobError::L2AuthNotAvailable)
    }

    /// Helper to extract L1 signer or return appropriate error.
    #[allow(dead_code)]
    fn require_signer(&self) -> Result<&EthersSigner, ClobError> {
        self.signer
            .as_ref()
            .map(|arc| arc.as_ref())
            .ok_or(ClobError::L1AuthUnavailable)
    }
}

/// TypeScript `OrderMarketCancelParams` parity: `{ market?: string, asset_id?: string }`
#[derive(Clone, Debug, serde::Serialize)]
pub struct OrderMarketCancelParams {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub market: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub asset_id: Option<String>,
}

impl ClobClient {
    // --- TypeScript parity alias section --------------------------------------------------
    // These thin wrappers mirror the naming style of the original TypeScript client so that
    // porting example code is mostly a mechanical rename (camelCase). They delegate to the
    // existing snake_case Rust methods. Prefer using the snake_case versions in new Rust code.

    /// TS parity alias for `get_markets` (camelCase). Prefer `get_markets` in Rust.
    #[allow(non_snake_case)]
    pub async fn getMarkets(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::Market>, ClobError> {
        self.get_markets(params).await
    }

    /// TS parity alias for `getMarket` -> `get_market`.
    #[allow(non_snake_case)]
    pub async fn getMarket(
        &self,
        market_id: &str,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<crate::types::Market, ClobError> {
        self.get_market(market_id, params).await
    }

    #[allow(non_snake_case)]
    pub async fn getOrderBook(&self, token_id: &str) -> Result<OrderBookSummary, ClobError> {
        self.get_order_book(token_id).await
    }

    #[allow(non_snake_case)]
    pub async fn getTickSize(&self, token_id: &str) -> Result<String, ClobError> {
        self.get_tick_size(token_id).await
    }

    #[allow(non_snake_case)]
    pub async fn getNegRisk(&self, token_id: &str) -> Result<bool, ClobError> {
        self.get_neg_risk(token_id).await
    }

    #[allow(non_snake_case)]
    pub async fn getFeeRate(&self, token_id: &str) -> Result<Decimal, ClobError> {
        self.get_fee_rate(token_id).await
    }

    #[allow(non_snake_case)]
    pub async fn getOpenOrders(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<SignedOrder>, ClobError> {
        self.get_open_orders(params).await
    }

    #[allow(non_snake_case)]
    pub async fn getOrder(&self, order_id: &str) -> Result<OpenOrder, ClobError> {
        self.get_order(order_id).await
    }

    #[allow(non_snake_case)]
    pub async fn postSignedOrder(
        &self,
        signed_order: &SignedOrder,
    ) -> Result<OrderResponse, ClobError> {
        self.post_signed_order(signed_order, OrderType::GTC, false, None)
            .await
    }

    #[allow(non_snake_case)]
    pub async fn postOrders(
        &self,
        orders: Vec<PostOrdersArgs>,
        defer_exec: bool,
        default_post_only: bool,
    ) -> Result<Vec<Order>, ClobError> {
        self.post_orders(orders, defer_exec, default_post_only)
            .await
    }

    #[allow(non_snake_case)]
    pub async fn createOrder(
        &self,
        user_order: UserOrder,
        options_tick: Option<&str>,
    ) -> Result<SignedOrder, ClobError> {
        self.create_order(user_order, options_tick).await
    }

    #[allow(non_snake_case)]
    pub async fn createMarketOrder(
        &self,
        user_market_order: UserMarketOrder,
        options_tick: Option<&str>,
    ) -> Result<SignedOrder, ClobError> {
        self.create_market_order(user_market_order, options_tick)
            .await
    }

    #[allow(non_snake_case)]
    pub async fn createAndPostOrder(
        &self,
        user_order: UserOrder,
        options_tick: Option<&str>,
        order_type: Option<OrderType>,
        defer_exec: bool,
        post_only: bool,
    ) -> Result<OrderResponse, ClobError> {
        self.create_and_post_order(
            user_order,
            options_tick,
            order_type,
            defer_exec,
            Some(post_only),
        )
        .await
    }

    #[allow(non_snake_case)]
    pub async fn createAndPostMarketOrder(
        &self,
        user_market_order: UserMarketOrder,
        options_tick: Option<&str>,
        order_type: Option<OrderType>,
        defer_exec: bool,
    ) -> Result<OrderResponse, ClobError> {
        self.create_and_post_market_order(user_market_order, options_tick, order_type, defer_exec)
            .await
    }

    /// TypeScript parity: `cancelOrder({ orderID })` 发送 DELETE /orders 携带 JSON body。
    #[allow(non_snake_case)]
    pub async fn cancelOrder(&self, payload: OrderPayloadParity) -> Result<Value, ClobError> {
        self.cancel_order_payload_raw(payload).await
    }

    #[allow(non_snake_case)]
    pub async fn cancelOrders(&self, order_ids: Vec<String>) -> Result<Vec<Order>, ClobError> {
        self.cancel_orders(order_ids).await
    }

    #[allow(non_snake_case)]
    pub async fn cancelAll(&self) -> Result<Vec<Order>, ClobError> {
        self.cancel_all().await
    }

    #[allow(non_snake_case)]
    pub async fn cancelMarketOrders(
        &self,
        payload: OrderMarketCancelParams,
    ) -> Result<Vec<Order>, ClobError> {
        self.cancel_market_orders(payload).await
    }

    #[allow(non_snake_case)]
    pub async fn isOrderScoring(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<crate::types::OrderScoring, ClobError> {
        self.is_order_scoring(params).await
    }

    #[allow(non_snake_case)]
    pub async fn areOrdersScoring(
        &self,
        order_ids: Option<Vec<String>>,
    ) -> Result<crate::types::OrdersScoring, ClobError> {
        self.are_orders_scoring(order_ids).await
    }

    #[allow(non_snake_case)]
    pub async fn getTrades(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
        only_first_page: bool,
        next_cursor: Option<String>,
    ) -> Result<Vec<Value>, ClobError> {
        self.get_trades(params, only_first_page, next_cursor).await
    }

    #[allow(non_snake_case)]
    pub async fn getTradesTyped(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
        only_first_page: bool,
        next_cursor: Option<String>,
    ) -> Result<Vec<Trade>, ClobError> {
        self.get_trades_typed(params, only_first_page, next_cursor)
            .await
    }

    #[allow(non_snake_case)]
    pub async fn getNotifications(&self) -> Result<Vec<Notification>, ClobError> {
        self.get_notifications().await
    }

    #[allow(non_snake_case)]
    pub async fn dropNotifications(&self, ids: Option<&Vec<String>>) -> Result<(), ClobError> {
        self.drop_notifications(ids).await
    }

    #[allow(non_snake_case)]
    pub async fn getBalanceAllowance(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<crate::types::BalanceAllowanceResponse, ClobError> {
        self.get_balance_allowance(params).await
    }

    #[allow(non_snake_case)]
    pub async fn updateBalanceAllowance(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<(), ClobError> {
        self.update_balance_allowance(params).await
    }

    #[allow(non_snake_case)]
    pub async fn getTime(&self) -> Result<u64, ClobError> {
        self.get_server_time().await
    }

    // API keys (L2)
    #[allow(non_snake_case)]
    pub async fn getApiKeys(&self) -> Result<Vec<crate::types::ApiKeyCreds>, ClobError> {
        self.get_api_keys().await
    }
    #[allow(non_snake_case)]
    pub async fn deleteApiKey(&self) -> Result<(), ClobError> {
        self.delete_api_key().await
    }
    #[allow(non_snake_case)]
    pub async fn getClosedOnlyMode(&self) -> Result<crate::types::BanStatus, ClobError> {
        self.get_closed_only_mode().await
    }

    // L1-derived API keys
    #[allow(non_snake_case)]
    pub async fn createApiKey(&self, nonce: Option<u64>) -> Result<ApiKeyCreds, ClobError> {
        self.create_api_key(nonce).await
    }
    #[allow(non_snake_case)]
    pub async fn deriveApiKey(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<ApiKeyCreds, ClobError> {
        self.derive_api_key(params).await
    }

    // Builder API keys
    #[allow(non_snake_case)]
    pub async fn createBuilderApiKey(&self) -> Result<ApiKeyCreds, ClobError> {
        self.create_builder_api_key().await
    }
    #[allow(non_snake_case)]
    pub async fn getBuilderApiKeys(&self) -> Result<Vec<ApiKeyCreds>, ClobError> {
        self.get_builder_api_keys().await
    }
    #[allow(non_snake_case)]
    pub async fn revokeBuilderApiKey(&self) -> Result<(), ClobError> {
        self.revoke_builder_api_key().await
    }

    // Markets/prices aliases
    #[allow(non_snake_case)]
    pub async fn getSimplifiedMarkets(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::Market>, ClobError> {
        self.get_simplified_markets(params).await
    }
    #[allow(non_snake_case)]
    pub async fn getSamplingMarkets(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::Market>, ClobError> {
        self.get_sampling_markets(params).await
    }
    #[allow(non_snake_case)]
    pub async fn getSamplingSimplifiedMarkets(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::Market>, ClobError> {
        self.get_sampling_simplified_markets(params).await
    }
    #[allow(non_snake_case)]
    pub async fn getOrderBooks(
        &self,
        params: &[crate::types::BookParams],
    ) -> Result<Vec<crate::types::OrderBookSummary>, ClobError> {
        self.get_order_books(params).await
    }
    #[allow(non_snake_case)]
    pub async fn getMidpoint(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<crate::types::MidpointResponse, ClobError> {
        self.get_midpoint(params).await
    }
    #[allow(non_snake_case)]
    pub async fn getMidpoints(
        &self,
        params: &[crate::types::BookParams],
    ) -> Result<serde_json::Value, ClobError> {
        self.get_midpoints(params).await
    }
    #[allow(non_snake_case)]
    pub async fn getPrices(
        &self,
        params: &[crate::types::BookParams],
    ) -> Result<serde_json::Value, ClobError> {
        self.get_prices(params).await
    }
    #[allow(non_snake_case)]
    pub async fn getSpreads(
        &self,
        params: &[crate::types::BookParams],
    ) -> Result<serde_json::Value, ClobError> {
        self.get_spreads(params).await
    }
    #[allow(non_snake_case)]
    pub async fn getLastTradesPrices(
        &self,
        params: &[crate::types::BookParams],
    ) -> Result<serde_json::Value, ClobError> {
        self.get_last_trades_prices(params).await
    }
    #[allow(non_snake_case)]
    pub async fn getPricesHistory(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::MarketPrice>, ClobError> {
        self.get_prices_history(params).await
    }
    #[allow(non_snake_case)]
    pub async fn getMarketTradesEvents(
        &self,
        market_id: &str,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::Trade>, ClobError> {
        self.get_market_trades_events(market_id, params).await
    }

    // Builder trades
    #[allow(non_snake_case)]
    pub async fn getBuilderTrades(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::BuilderTrade>, ClobError> {
        self.get_builder_trades(params).await
    }

    // Rewards
    #[allow(non_snake_case)]
    pub async fn getEarningsForUserForDay(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::Reward>, ClobError> {
        self.get_earnings_for_user_for_day(params).await
    }
    #[allow(non_snake_case)]
    pub async fn getEarningsForUserForDayTyped(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::Reward>, ClobError> {
        self.get_rewards_user_for_day_typed(params).await
    }
    #[allow(non_snake_case)]
    pub async fn getTotalEarningsForUserForDay(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::Reward>, ClobError> {
        self.get_total_earnings_for_user_for_day(params).await
    }
    #[allow(non_snake_case)]
    pub async fn getLiquidityRewardPercentages(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<std::collections::HashMap<String, f64>, ClobError> {
        self.get_liquidity_reward_percentages(params).await
    }
    #[allow(non_snake_case)]
    pub async fn getRewardsMarketsCurrent(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::RewardsMarket>, ClobError> {
        self.get_rewards_markets_current(params).await
    }
    #[allow(non_snake_case)]
    pub async fn getRewardsEarningsPercentages(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::Reward>, ClobError> {
        self.get_rewards_earnings_percentages(params).await
    }
    // --------------------------------------------------------------------------------------
    /// 创建 ClobClient。
    ///
    /// `http_client`:
    /// - `None` — 使用全局共享默认连接池（所有传 None 的实例共享同一个池，与原有行为一致）
    /// - `Some(client)` — 使用调用方自定义的 `reqwest::Client`（可配置代理、独立连接池等）
    pub fn new(
        host: &str,
        chain_id: i64,
        signer: Option<Arc<EthersSigner>>,
        creds: Option<ApiKeyCreds>,
        use_server_time: bool,
        http_client: Option<reqwest::Client>,
    ) -> Self {
        Self {
            host: if let Some(stripped) = host.strip_suffix('/') {
                stripped.to_string()
            } else {
                host.to_string()
            },
            chain_id,
            http_client: http_client
                .unwrap_or_else(|| crate::http_helpers::default_client().clone()),
            signer,
            creds,
            use_server_time,
            geo_block_token: None,
            tick_sizes: DashMap::new(),
            neg_risk: DashMap::new(),
            fee_rates: DashMap::new(),
            builder_signer: None,
            builder_config: None,
        }
    }

    pub fn with_geo_block_token(mut self, token: String) -> Self {
        self.geo_block_token = Some(token);
        self
    }

    pub fn set_geo_block_token(&mut self, token: Option<String>) {
        self.geo_block_token = token;
    }

    fn attach_geo_request_options<B>(
        &self,
        options: Option<RequestOptions<B>>,
    ) -> Option<RequestOptions<B>> {
        let tok = match self
            .geo_block_token
            .as_ref()
            .filter(|t| !t.trim().is_empty())
        {
            Some(t) => t.clone(),
            None => return options,
        };

        let mut opts = options.unwrap_or(RequestOptions {
            headers: None,
            data: None,
            params: None,
        });

        let params = opts
            .params
            .get_or_insert_with(std::collections::HashMap::new);
        // TS 合并顺序：{ ...options.params, geo_block_token: this.geoBlockToken }
        // => client token 覆盖 caller 的同名字段。
        params.insert("geo_block_token".to_string(), tok);
        Some(opts)
    }

    async fn http_get(
        &self,
        endpoint: &str,
        options: Option<RequestOptions<serde_json::Value>>,
    ) -> Result<serde_json::Value, ClobError> {
        crate::http_helpers::get(
            &self.http_client,
            endpoint,
            self.attach_geo_request_options(options),
        )
        .await
    }

    async fn http_post(
        &self,
        endpoint: &str,
        options: Option<RequestOptions<serde_json::Value>>,
    ) -> Result<serde_json::Value, ClobError> {
        crate::http_helpers::post(
            &self.http_client,
            endpoint,
            self.attach_geo_request_options(options),
        )
        .await
    }

    async fn http_get_typed<R>(
        &self,
        endpoint: &str,
        options: Option<RequestOptions<serde_json::Value>>,
    ) -> Result<R, ClobError>
    where
        R: serde::de::DeserializeOwned,
    {
        crate::http_helpers::get_typed(
            &self.http_client,
            endpoint,
            self.attach_geo_request_options(options),
        )
        .await
    }

    async fn http_post_typed<R, B>(
        &self,
        endpoint: &str,
        options: Option<RequestOptions<B>>,
    ) -> Result<R, ClobError>
    where
        R: serde::de::DeserializeOwned,
        B: serde::Serialize,
    {
        crate::http_helpers::post_typed(
            &self.http_client,
            endpoint,
            self.attach_geo_request_options(options),
        )
        .await
    }

    async fn http_del_typed<R, B>(
        &self,
        endpoint: &str,
        options: Option<RequestOptions<B>>,
    ) -> Result<R, ClobError>
    where
        R: serde::de::DeserializeOwned,
        B: serde::Serialize,
    {
        crate::http_helpers::del_typed(
            &self.http_client,
            endpoint,
            self.attach_geo_request_options(options),
        )
        .await
    }

    /// Configure Builder API signer (builder auth). Secret must be base64 encoded.
    pub fn with_builder_signer(
        mut self,
        key: String,
        secret_b64: String,
        passphrase: String,
    ) -> Self {
        let creds = builder_signing_sdk_rs::BuilderApiKeyCreds {
            key,
            secret: secret_b64,
            passphrase,
        };
        self.builder_signer = Some(builder_signing_sdk_rs::BuilderSigner::new(creds));
        self
    }

    /// Set a default builder config for order creation (tick size, neg risk, signature type, funder).
    pub fn with_builder_config(mut self, cfg: ObBuilderConfig) -> Self {
        self.builder_config = Some(cfg);
        self
    }

    /// RFQ entrypoint.
    ///
    /// 使用方式：`client.rfq().get_rfq_quotes(...)`。
    ///
    /// 注意：RFQ 的 accept/approve 需要在本地创建并签名订单，因此会对 `self` 持有可变借用。
    pub fn rfq(&self) -> crate::rfq_client::RfqClient<'_> {
        crate::rfq_client::RfqClient::new(self)
    }

    pub async fn get_order_book(&self, token_id: &str) -> Result<OrderBookSummary, ClobError> {
        let endpoint = format!("{}{}", self.host, GET_ORDER_BOOK);
        let mut params = std::collections::HashMap::new();
        params.insert("token_id".to_string(), token_id.to_string());
        let opts = RequestOptions {
            headers: None,
            data: None,
            params: Some(params),
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        let obs: OrderBookSummary =
            serde_json::from_value(val).map_err(|e| ClobError::Other(e.to_string()))?;
        Ok(obs)
    }

    pub async fn get_tick_size(&self, token_id: &str) -> Result<String, ClobError> {
        if let Some(v) = self.tick_sizes.get(token_id) {
            return Ok(v.value().clone());
        }
        let endpoint = format!("{}{}", self.host, GET_TICK_SIZE);
        let mut params = std::collections::HashMap::new();
        params.insert("token_id".to_string(), token_id.to_string());
        let opts = RequestOptions {
            headers: None,
            data: None,
            params: Some(params),
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        let tick_val = val
            .get("minimum_tick_size")
            .ok_or(ClobError::Other("invalid tick response".to_string()))?;
        let tick = match tick_val {
            serde_json::Value::String(s) => s.clone(),
            serde_json::Value::Number(n) => n.to_string(),
            _ => return Err(ClobError::Other("invalid tick response".to_string())),
        };
        self.tick_sizes.insert(token_id.to_string(), tick.clone());
        Ok(tick)
    }

    pub async fn get_neg_risk(&self, token_id: &str) -> Result<bool, ClobError> {
        if let Some(v) = self.neg_risk.get(token_id) {
            return Ok(*v.value());
        }
        let endpoint = format!("{}{}", self.host, GET_NEG_RISK);
        let mut params = std::collections::HashMap::new();
        params.insert("token_id".to_string(), token_id.to_string());
        let opts = RequestOptions {
            headers: None,
            data: None,
            params: Some(params),
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        let rr = val
            .get("neg_risk")
            .and_then(|v| v.as_bool())
            .ok_or(ClobError::Other("invalid neg risk response".to_string()))?;
        self.neg_risk.insert(token_id.to_string(), rr);
        Ok(rr)
    }

    pub async fn get_fee_rate(&self, token_id: &str) -> Result<Decimal, ClobError> {
        if let Some(v) = self.fee_rates.get(token_id) {
            return Ok(*v.value());
        }
        let endpoint = format!("{}{}", self.host, GET_FEE_RATE);
        let mut params = std::collections::HashMap::new();
        params.insert("token_id".to_string(), token_id.to_string());
        let opts = RequestOptions {
            headers: None,
            data: None,
            params: Some(params),
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        // String round-trip: 避免 from_f64_retain 精度灰尘 (e.g. 0.1 → 0.100000000000000005...)
        let fee_str = val
            .get("base_fee")
            .map(|v| match v {
                serde_json::Value::Number(n) => n.to_string(),
                serde_json::Value::String(s) => s.clone(),
                _ => String::new(),
            })
            .filter(|s| !s.is_empty())
            .ok_or(ClobError::Other("invalid fee response".to_string()))?;
        let fee: Decimal = fee_str
            .parse()
            .map_err(|e| ClobError::Other(format!("fee rate parse error: {}", e)))?;
        self.fee_rates.insert(token_id.to_string(), fee);
        Ok(fee)
    }

    /// Convenience method that accepts a typed `SignedOrder` and posts it to the
    /// API. Delegates to `post_signed_order` which performs serialization,
    /// header creation and response parsing. Uses default orderType=GTC.
    pub async fn post_order(&self, signed_order: &SignedOrder) -> Result<OrderResponse, ClobError> {
        // Delegate to the typed helper with default GTC order type
        self.post_signed_order(signed_order, OrderType::GTC, false, None)
            .await
    }

    pub async fn get_api_keys(&self) -> Result<Vec<crate::types::ApiKeyCreds>, ClobError> {
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();
        let endpoint = format!("{}{}", self.host, GET_API_KEYS);
        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "GET",
            GET_API_KEYS,
            None,
            ts,
        )
        .await?;
        let resp: crate::types::ApiKeysResponse = self
            .http_get_typed(
                &endpoint,
                Some(RequestOptions::<Value> {
                    headers: Some(headers),
                    data: None,
                    params: None,
                }),
            )
            .await?;
        Ok(resp.api_keys)
    }

    /// Creates a new readonly API key for the current (L2 authenticated) user.
    ///
    /// TS parity: `createReadonlyApiKey(): Promise<{ apiKey: string }>`
    pub async fn create_readonly_api_key(&self) -> Result<ReadonlyApiKeyResponse, ClobError> {
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();

        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "POST",
            CREATE_READONLY_API_KEY,
            None,
            ts,
        )
        .await?;

        let endpoint = format!("{}{}", self.host, CREATE_READONLY_API_KEY);
        let resp: ReadonlyApiKeyResponse = self
            .http_post_typed(
                &endpoint,
                Some(RequestOptions::<Value> {
                    headers: Some(headers),
                    data: None,
                    params: None,
                }),
            )
            .await?;
        Ok(resp)
    }

    /// Lists readonly API keys for the current (L2 authenticated) user.
    ///
    /// TS parity: `getReadonlyApiKeys(): Promise<string[]>`
    pub async fn get_readonly_api_keys(&self) -> Result<Vec<String>, ClobError> {
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();

        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "GET",
            GET_READONLY_API_KEYS,
            None,
            ts,
        )
        .await?;

        let endpoint = format!("{}{}", self.host, GET_READONLY_API_KEYS);
        let resp: Vec<String> = self
            .http_get_typed(
                &endpoint,
                Some(RequestOptions::<Value> {
                    headers: Some(headers),
                    data: None,
                    params: None,
                }),
            )
            .await?;
        Ok(resp)
    }

    /// Deletes a readonly API key for the current (L2 authenticated) user.
    ///
    /// TS parity: `deleteReadonlyApiKey(key: string): Promise<boolean>`
    pub async fn delete_readonly_api_key(&self, key: &str) -> Result<bool, ClobError> {
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();

        let payload = DeleteReadonlyApiKeyRequest {
            key: key.to_string(),
        };
        let body_str =
            serde_json::to_string(&payload).map_err(|e| ClobError::Other(e.to_string()))?;

        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "DELETE",
            DELETE_READONLY_API_KEY,
            Some(&body_str),
            ts,
        )
        .await?;

        let endpoint = format!("{}{}", self.host, DELETE_READONLY_API_KEY);
        let resp: bool = self
            .http_del_typed(
                &endpoint,
                Some(RequestOptions {
                    headers: Some(headers),
                    data: Some(payload),
                    params: None,
                }),
            )
            .await?;
        Ok(resp)
    }

    /// Validates a readonly API key for a given address.
    ///
    /// TS parity: `validateReadonlyApiKey(address: string, key: string): Promise<string>`
    ///
    /// Note: This endpoint is treated as public (no L1/L2 auth headers).
    pub async fn validate_readonly_api_key(
        &self,
        address: &str,
        key: &str,
    ) -> Result<String, ClobError> {
        let endpoint = format!("{}{}", self.host, VALIDATE_READONLY_API_KEY);
        let mut params = std::collections::HashMap::new();
        params.insert("address".to_string(), address.to_string());
        params.insert("key".to_string(), key.to_string());
        let val = self
            .http_get(
                &endpoint,
                Some(RequestOptions::<Value> {
                    headers: None,
                    data: None,
                    params: Some(params),
                }),
            )
            .await?;

        if let Some(s) = val.as_str() {
            return Ok(s.to_string());
        }
        if let Some(s) = val
            .get("result")
            .and_then(|v| v.as_str())
            .or_else(|| val.get("address").and_then(|v| v.as_str()))
        {
            return Ok(s.to_string());
        }
        Ok(val.to_string())
    }

    // --- TypeScript parity aliases (camelCase) -----------------------------------------
    #[allow(non_snake_case)]
    pub async fn createReadonlyApiKey(&self) -> Result<ReadonlyApiKeyResponse, ClobError> {
        self.create_readonly_api_key().await
    }

    #[allow(non_snake_case)]
    pub async fn getReadonlyApiKeys(&self) -> Result<Vec<String>, ClobError> {
        self.get_readonly_api_keys().await
    }

    #[allow(non_snake_case)]
    pub async fn deleteReadonlyApiKey(&self, key: &str) -> Result<bool, ClobError> {
        self.delete_readonly_api_key(key).await
    }

    #[allow(non_snake_case)]
    pub async fn validateReadonlyApiKey(
        &self,
        address: &str,
        key: &str,
    ) -> Result<String, ClobError> {
        self.validate_readonly_api_key(address, key).await
    }

    pub async fn get_closed_only_mode(&self) -> Result<crate::types::BanStatus, ClobError> {
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();
        let endpoint = format!("{}{}", self.host, CLOSED_ONLY);
        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "GET",
            CLOSED_ONLY,
            None,
            ts,
        )
        .await?;
        let resp: crate::types::BanStatus = self
            .http_get_typed(
                &endpoint,
                Some(RequestOptions::<Value> {
                    headers: Some(headers),
                    data: None,
                    params: None,
                }),
            )
            .await?;
        Ok(resp)
    }

    pub async fn delete_api_key(&self) -> Result<(), ClobError> {
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();
        let endpoint = format!("{}{}", self.host, DELETE_API_KEY);
        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "DELETE",
            DELETE_API_KEY,
            None,
            ts,
        )
        .await?;
        let _val: () = self
            .http_del_typed::<(), Value>(
                &endpoint,
                Some(RequestOptions::<Value> {
                    headers: Some(headers),
                    data: None,
                    params: None,
                }),
            )
            .await?;
        Ok(())
    }

    pub async fn get_trades(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
        only_first_page: bool,
        next_cursor: Option<String>,
    ) -> Result<Vec<Value>, ClobError> {
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();
        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "GET",
            GET_TRADES,
            None,
            ts,
        )
        .await?;
        let mut results: Vec<Value> = vec![];
        let endpoint = format!("{}{}", self.host, GET_TRADES);
        let mut cursor = next_cursor.unwrap_or_else(|| INITIAL_CURSOR.to_string());
        while cursor != END_CURSOR {
            if only_first_page && cursor != INITIAL_CURSOR {
                break;
            }
            let mut p = params.clone().unwrap_or_default();
            p.insert("next_cursor".to_string(), cursor.clone());
            let val = self
                .http_get(
                    &endpoint,
                    Some(RequestOptions {
                        headers: Some(headers.clone()),
                        data: None,
                        params: Some(p),
                    }),
                )
                .await?;
            let data = val
                .get("data")
                .and_then(|v| v.as_array())
                .cloned()
                .unwrap_or_default();
            for item in data {
                results.push(item);
            }
            cursor = val
                .get("next_cursor")
                .and_then(|v| v.as_str())
                .unwrap_or(END_CURSOR)
                .to_string();
        }
        Ok(results)
    }

    /// Typed variant of get_trades that deserializes each trade into `Trade`.
    pub async fn get_trades_typed(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
        only_first_page: bool,
        next_cursor: Option<String>,
    ) -> Result<Vec<Trade>, ClobError> {
        let vals = self
            .get_trades(params, only_first_page, next_cursor)
            .await?;
        let mut trades: Vec<Trade> = Vec::new();
        for v in vals {
            let t: Trade =
                serde_json::from_value(v).map_err(|e| ClobError::Other(e.to_string()))?;
            trades.push(t);
        }
        Ok(trades)
    }

    pub async fn get_notifications(&self) -> Result<Vec<Notification>, ClobError> {
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();
        let endpoint = format!("{}{}", self.host, GET_NOTIFICATIONS);
        let mut params = std::collections::HashMap::new();
        params.insert("signature_type".to_string(), "EOA".to_string());
        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "GET",
            GET_NOTIFICATIONS,
            None,
            ts,
        )
        .await?;
        let resp: MaybeVec<Notification> = self
            .http_get_typed(
                &endpoint,
                Some(RequestOptions::<Value> {
                    headers: Some(headers),
                    data: None,
                    params: Some(params),
                }),
            )
            .await?;
        Ok(resp.into_vec())
    }

    /// Typed variant of get_notifications that deserializes notifications into `Notification`.
    pub async fn get_notifications_typed(&self) -> Result<Vec<Notification>, ClobError> {
        // Kept for compatibility: delegate to get_notifications
        self.get_notifications().await
    }

    pub async fn drop_notifications(&self, ids: Option<&Vec<String>>) -> Result<(), ClobError> {
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();
        let endpoint = format!("{}{}", self.host, DROP_NOTIFICATIONS);
        let params = crate::http_helpers::parse_drop_notification_params(ids);
        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "DELETE",
            DROP_NOTIFICATIONS,
            None,
            ts,
        )
        .await?;
        let _raw: SuccessResp = self
            .http_del_typed(
                &endpoint,
                Some(RequestOptions::<Value> {
                    headers: Some(headers),
                    data: None,
                    params: Some(params),
                }),
            )
            .await?;
        Ok(())
    }

    pub async fn get_balance_allowance(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<crate::types::BalanceAllowanceResponse, ClobError> {
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();
        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "GET",
            GET_BALANCE_ALLOWANCE,
            None,
            ts,
        )
        .await?;
        let endpoint = format!("{}{}", self.host, GET_BALANCE_ALLOWANCE);
        let resp: crate::types::BalanceAllowanceResponse = self
            .http_get_typed(
                &endpoint,
                Some(RequestOptions::<Value> {
                    headers: Some(headers),
                    data: None,
                    params,
                }),
            )
            .await?;
        Ok(resp)
    }

    pub async fn update_balance_allowance(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<(), ClobError> {
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();
        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "GET",
            UPDATE_BALANCE_ALLOWANCE,
            None,
            ts,
        )
        .await?;
        // API returns no useful body for update; call and ignore body
        let endpoint = format!("{}{}", self.host, UPDATE_BALANCE_ALLOWANCE);
        let _resp: OkResp = self
            .http_get_typed(
                &endpoint,
                Some(RequestOptions::<Value> {
                    headers: Some(headers),
                    data: None,
                    params,
                }),
            )
            .await?;
        Ok(())
    }

    /// Typed helper to fetch user rewards for a day (deserializes into `Reward`).
    /// This endpoint may be public or require params depending on server; we accept optional query params.
    pub async fn get_rewards_user_for_day_typed(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<Reward>, ClobError> {
        let endpoint = format!("{}{}", self.host, GET_EARNINGS_FOR_USER_FOR_DAY);
        let val = self
            .http_get(
                &endpoint,
                Some(RequestOptions {
                    headers: None,
                    data: None,
                    params,
                }),
            )
            .await?;

        let arr = if let Some(a) = val.get("data").and_then(|v| v.as_array()) {
            a.clone()
        } else if val.is_array() {
            val.as_array().cloned().unwrap_or_default()
        } else {
            Vec::new()
        };
        let mut out: Vec<Reward> = Vec::new();
        for v in arr {
            let r: Reward =
                serde_json::from_value(v).map_err(|e| ClobError::Other(e.to_string()))?;
            out.push(r);
        }
        Ok(out)
    }

    pub async fn create_order(
        &self,
        user_order: UserOrder,
        options_tick: Option<&str>,
    ) -> Result<SignedOrder, ClobError> {
        // L1 auth required
        self.can_l1_auth()?;
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();
        let ob = if let Some(cfg) = &self.builder_config {
            OrderBuilder::with_config(signer_ref, self.chain_id, cfg)
        } else {
            OrderBuilder::new(signer_ref, self.chain_id, None, None)
        };
        // 动态解析合约地址：根据 chainId 与 neg_risk(token) 选择标准或 negRisk 交易所
        let exchange_addr = self.resolve_exchange_address(&user_order.token_id);
        let signed = ob
            .build_order(&exchange_addr, &user_order, options_tick.unwrap_or("0.01"))
            .await?;
        Ok(signed)
    }

    pub async fn create_market_order(
        &self,
        user_market_order: UserMarketOrder,
        options_tick: Option<&str>,
    ) -> Result<SignedOrder, ClobError> {
        self.can_l1_auth()?;
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();
        let ob = if let Some(cfg) = &self.builder_config {
            OrderBuilder::with_config(signer_ref, self.chain_id, cfg)
        } else {
            OrderBuilder::new(signer_ref, self.chain_id, None, None)
        };
        let exchange_addr = self.resolve_exchange_address(&user_market_order.token_id);
        let signed = ob
            .build_market_order(
                &exchange_addr,
                &user_market_order,
                options_tick.unwrap_or("0.01"),
            )
            .await?;
        Ok(signed)
    }

    /// 依据链 ID 与 builder_config.neg_risk 选择 verifyingContract 地址。
    /// 注意：当前实现不主动查询 token neg_risk，只使用调用方传入的配置；如需自动检测可在上层先调用 get_neg_risk 并写入 builder_config。
    fn resolve_exchange_address(&self, _token_id: &str) -> String {
        let neg = self
            .builder_config
            .as_ref()
            .and_then(|c| c.neg_risk)
            .unwrap_or(false);
        match (self.chain_id, neg) {
            (137, false) => "0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E".to_string(),
            (137, true) => "0xC5d563A36AE78145C45a50134d48A1215220f80a".to_string(),
            (80002, false) => "0xdFE02Eb6733538f8Ea35D585af8DE5958AD99E40".to_string(),
            (80002, true) => "0xC5d563A36AE78145C45a50134d48A1215220f80a".to_string(),
            (_other, _) => "0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E".to_string(),
        }
    }

    // removed unused builder-auth helpers; builder headers are injected inline where needed

    /// Post multiple orders to the API (v5.2.0 signature)
    ///
    /// This method matches the TypeScript SDK's `postOrders` signature.
    /// It supports PostOrdersArgs which includes post_only support.
    ///
    /// # Arguments
    /// * `orders` - Vector of PostOrdersArgs containing signed orders with their options
    /// * `defer_exec` - Whether to defer execution (default: false)
    /// * `default_post_only` - Default post_only value if not specified per-order (default: false)
    ///
    /// # Returns
    /// * Vector of Order responses
    pub async fn post_orders(
        &self,
        orders: Vec<PostOrdersArgs>,
        defer_exec: bool,
        default_post_only: bool,
    ) -> Result<Vec<Order>, ClobError> {
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();

        // IMPORTANT: Use API key as owner
        let owner = self.require_creds()?.key.clone();

        // Convert orders to NewOrder format with post_only support
        let new_orders: Vec<crate::types::NewOrder> = orders
            .into_iter()
            .map(|arg| {
                let post_only = arg.post_only.or(Some(default_post_only));
                crate::utilities::order_to_json(
                    &arg.order,
                    &owner,
                    arg.order_type,
                    defer_exec,
                    post_only,
                )
            })
            .collect::<Result<Vec<_>, _>>()?;

        let body_str =
            serde_json::to_string(&new_orders).map_err(|e| ClobError::Other(e.to_string()))?;
        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let mut headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "POST",
            POST_ORDERS,
            Some(&body_str),
            ts,
        )
        .await?;
        if let Some(b) = &self.builder_signer {
            let b_payload = b
                .create_builder_header_payload("POST", POST_ORDERS, Some(&body_str), None)
                .map_err(|e| ClobError::Other(format!("builder header error: {}", e)))?;
            headers = crate::headers::inject_builder_headers(headers, &b_payload);
        }
        let endpoint = format!("{}{}", self.host, POST_ORDERS);
        let raw: MaybeVec<Order> = self
            .http_post_typed(
                &endpoint,
                Some(RequestOptions {
                    headers: Some(headers),
                    data: Some(new_orders),
                    params: None,
                }),
            )
            .await?;
        Ok(raw.into_vec())
    }

    /// Helper: post a single SignedOrder (typed) to the API. Wraps SignedOrder in NewOrder
    /// with orderType and performs L2-authenticated POST to POST_ORDER endpoint.
    ///
    /// # Arguments
    /// * `signed_order` - The signed order to post
    /// * `order_type` - Type of order (GTC, FOK, GTD, FAK)
    /// * `defer_exec` - Whether to defer execution
    /// * `post_only` - If true, order will be rejected if it would immediately match (v5.2.0).
    ///   Only supported for GTC and GTD orders.
    pub async fn post_signed_order(
        &self,
        signed_order: &SignedOrder,
        order_type: OrderType,
        defer_exec: bool,
        post_only: Option<bool>,
    ) -> Result<OrderResponse, ClobError> {
        // build headers and post, then parse into Order
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();

        // IMPORTANT: Use API key as owner, NOT wallet address
        // This matches TypeScript SDK behavior: orderToJson(order, this.creds?.key || "", ...)
        let owner = self.require_creds()?.key.clone();

        // Convert SignedOrder to NewOrder format
        let new_order = crate::utilities::order_to_json(
            signed_order,
            &owner,
            order_type,
            defer_exec,
            post_only,
        )?;

        let body_str =
            serde_json::to_string(&new_order).map_err(|e| ClobError::Other(e.to_string()))?;
        // 使用服务器时间保证与服务器 HMAC 计算节奏一致
        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let mut headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "POST",
            POST_ORDER,
            Some(&body_str),
            ts,
        )
        .await?;
        // Inject builder headers if builder auth configured
        if let Some(b) = &self.builder_signer {
            let b_payload = b
                .create_builder_header_payload("POST", POST_ORDER, Some(&body_str), None)
                .map_err(|e| ClobError::Other(format!("builder header error: {}", e)))?;
            headers = crate::headers::inject_builder_headers(headers, &b_payload);
        }
        let endpoint = format!("{}{}", self.host, POST_ORDER);
        let opts = RequestOptions {
            headers: Some(headers),
            data: Some(new_order),
            params: None,
        };
        let res: MaybeItem<OrderResponse> = self.http_post_typed(&endpoint, Some(opts)).await?;
        Ok(res.into_item())
    }

    /// Typed variant of posting a signed order: posts the signed order and attempts to
    /// deserialize the response into an `OrderResponse` (or into the `data` field if present).
    pub async fn post_signed_order_typed(
        &self,
        signed_order: &SignedOrder,
        order_type: OrderType,
        defer_exec: bool,
        post_only: Option<bool>,
    ) -> Result<OrderResponse, ClobError> {
        self.post_signed_order(signed_order, order_type, defer_exec, post_only)
            .await
    }

    /// Convenience: create (build & sign) then immediately post a limit order.
    /// orderType defaults to GTC (Good Till Cancelled).
    /// Matches TypeScript SDK signature: createAndPostOrder(userOrder, options, orderType, deferExec, postOnly)
    pub async fn create_and_post_order(
        &self,
        user_order: UserOrder,
        options_tick: Option<&str>,
        order_type: Option<OrderType>,
        defer_exec: bool,
        post_only: Option<bool>,
    ) -> Result<OrderResponse, ClobError> {
        // 避免在创建阶段发起额外 HTTP: 优先使用调用方提供的 tick 或 builder_config 中的 tick，否则使用默认值
        let tick = if let Some(t) = options_tick {
            t.to_string()
        } else if let Some(cfg_tick) = self
            .builder_config
            .as_ref()
            .and_then(|c| c.tick_size.as_ref())
        {
            cfg_tick.clone()
        } else {
            "0.01".to_string()
        };
        let signed = self.create_order(user_order, Some(&tick)).await?;
        let order_type = order_type.unwrap_or(OrderType::GTC);
        self.post_signed_order(&signed, order_type, defer_exec, post_only)
            .await
    }

    /// Convenience: create (build & sign) then immediately post a market order.
    /// orderType defaults to FOK (Fill Or Kill).
    /// Matches TypeScript SDK signature: createAndPostMarketOrder(userMarketOrder, options, orderType, deferExec)
    pub async fn create_and_post_market_order(
        &self,
        user_market_order: UserMarketOrder,
        options_tick: Option<&str>,
        order_type: Option<OrderType>,
        defer_exec: bool,
    ) -> Result<OrderResponse, ClobError> {
        // 避免在创建阶段发起额外 HTTP: 同上
        let tick = if let Some(t) = options_tick {
            t.to_string()
        } else if let Some(cfg_tick) = self
            .builder_config
            .as_ref()
            .and_then(|c| c.tick_size.as_ref())
        {
            cfg_tick.clone()
        } else {
            "0.01".to_string()
        };
        let signed = self
            .create_market_order(user_market_order, Some(&tick))
            .await?;
        let order_type = order_type.unwrap_or(OrderType::FOK);
        self.post_signed_order(&signed, order_type, defer_exec, None)
            .await
    }

    // 已移除内部 tick size 解析逻辑（resolve_tick/get_tick_size_uncached）以避免隐式网络请求；保留显式 get_tick_size API。
    /// Helper: accept typed SignedOrder list and post them to POST_ORDERS endpoint.
    pub async fn post_orders_typed(
        &self,
        orders: Vec<SignedOrder>,
        _defer_exec: bool,
    ) -> Result<Value, ClobError> {
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();
        let body_str =
            serde_json::to_string(&orders).map_err(|e| ClobError::Other(e.to_string()))?;
        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "POST",
            POST_ORDERS,
            Some(&body_str),
            ts,
        )
        .await?;
        let headers = if let Some(b) = &self.builder_signer {
            let b_payload = b
                .create_builder_header_payload("POST", POST_ORDERS, Some(&body_str), None)
                .map_err(|e| ClobError::Other(format!("builder header error: {}", e)))?;
            crate::headers::inject_builder_headers(headers, &b_payload)
        } else {
            headers
        };
        let endpoint = format!("{}{}", self.host, POST_ORDERS);
        let res: Value = self
            .http_post_typed(
                &endpoint,
                Some(RequestOptions {
                    headers: Some(headers),
                    data: Some(orders),
                    params: None,
                }),
            )
            .await?;
        Ok(res)
    }

    /// Post typed orders and return parsed `Vec<Order>` from the response.
    /// This wraps the existing `post_orders_typed` which returns a raw JSON Value
    /// and attempts to parse either a top-level array or `data` field into `Vec<Order>`.
    pub async fn post_orders_typed_parsed(
        &self,
        orders: Vec<SignedOrder>,
        _defer_exec: bool,
    ) -> Result<Vec<Order>, ClobError> {
        // Build body and headers similarly to post_orders_typed, but use the typed http helper
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();
        let body_str =
            serde_json::to_string(&orders).map_err(|e| ClobError::Other(e.to_string()))?;
        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "POST",
            POST_ORDERS,
            Some(&body_str),
            ts,
        )
        .await?;
        let headers = if let Some(b) = &self.builder_signer {
            let b_payload = b
                .create_builder_header_payload("POST", POST_ORDERS, Some(&body_str), None)
                .map_err(|e| ClobError::Other(format!("builder header error: {}", e)))?;
            crate::headers::inject_builder_headers(headers, &b_payload)
        } else {
            headers
        };
        let endpoint = format!("{}{}", self.host, POST_ORDERS);
        let raw: MaybeVec<Order> = self
            .http_post_typed(
                &endpoint,
                Some(RequestOptions {
                    headers: Some(headers),
                    data: Some(orders),
                    params: None,
                }),
            )
            .await?;
        Ok(raw.into_vec())
    }

    pub async fn cancel_all(&self) -> Result<Vec<Order>, ClobError> {
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();
        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let mut headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "DELETE",
            CANCEL_ALL,
            None,
            ts,
        )
        .await?;
        if let Some(b) = &self.builder_signer {
            let b_payload = b
                .create_builder_header_payload("DELETE", CANCEL_ALL, None, None)
                .map_err(|e| ClobError::Other(format!("builder header error: {}", e)))?;
            headers = crate::headers::inject_builder_headers(headers, &b_payload);
        }
        let endpoint = format!("{}{}", self.host, CANCEL_ALL);
        let raw: MaybeVec<Order> = self
            .http_del_typed(
                &endpoint,
                Some(RequestOptions::<Value> {
                    headers: Some(headers),
                    data: None,
                    params: None,
                }),
            )
            .await?;
        Ok(raw.into_vec())
    }

    pub async fn cancel_market_orders(
        &self,
        payload: OrderMarketCancelParams,
    ) -> Result<Vec<Order>, ClobError> {
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();
        let body_str =
            serde_json::to_string(&payload).map_err(|e| ClobError::Other(e.to_string()))?;
        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let mut headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "DELETE",
            CANCEL_MARKET_ORDERS,
            Some(&body_str),
            ts,
        )
        .await?;
        if let Some(b) = &self.builder_signer {
            let b_payload = b
                .create_builder_header_payload(
                    "DELETE",
                    CANCEL_MARKET_ORDERS,
                    Some(&body_str),
                    None,
                )
                .map_err(|e| ClobError::Other(format!("builder header error: {}", e)))?;
            headers = crate::headers::inject_builder_headers(headers, &b_payload);
        }
        let endpoint = format!("{}{}", self.host, CANCEL_MARKET_ORDERS);
        // Serialize payload to generic Value for request data
        let body_val =
            serde_json::to_value(&payload).map_err(|e| ClobError::Other(e.to_string()))?;
        let raw: MaybeVec<Order> = self
            .http_del_typed(
                &endpoint,
                Some(RequestOptions::<Value> {
                    headers: Some(headers),
                    data: Some(body_val),
                    params: None,
                }),
            )
            .await?;
        Ok(raw.into_vec())
    }

    pub async fn is_order_scoring(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<crate::types::OrderScoring, ClobError> {
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();
        let mut headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "GET",
            IS_ORDER_SCORING,
            None,
            if self.use_server_time {
                Some(self.get_server_time().await?)
            } else {
                None
            },
        )
        .await?;
        if let Some(b) = &self.builder_signer {
            let b_payload = b
                .create_builder_header_payload("GET", IS_ORDER_SCORING, None, None)
                .map_err(|e| ClobError::Other(format!("builder header error: {}", e)))?;
            headers = crate::headers::inject_builder_headers(headers, &b_payload);
        }
        let endpoint = format!("{}{}", self.host, IS_ORDER_SCORING);
        let resp: crate::types::OrderScoring = self
            .http_get_typed(
                &endpoint,
                Some(RequestOptions::<Value> {
                    headers: Some(headers),
                    data: None,
                    params,
                }),
            )
            .await?;
        Ok(resp)
    }

    pub async fn are_orders_scoring(
        &self,
        order_ids: Option<Vec<String>>,
    ) -> Result<crate::types::OrdersScoring, ClobError> {
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();
        let body_str =
            serde_json::to_string(&order_ids).map_err(|e| ClobError::Other(e.to_string()))?;
        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let mut headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "POST",
            ARE_ORDERS_SCORING,
            Some(&body_str),
            ts,
        )
        .await?;
        if let Some(b) = &self.builder_signer {
            let b_payload = b
                .create_builder_header_payload("POST", ARE_ORDERS_SCORING, Some(&body_str), None)
                .map_err(|e| ClobError::Other(format!("builder header error: {}", e)))?;
            headers = crate::headers::inject_builder_headers(headers, &b_payload);
        }
        // Serialize optional ids to JSON Value (null or array)
        let body_json =
            serde_json::to_value(&order_ids).map_err(|e| ClobError::Other(e.to_string()))?;
        let endpoint = format!("{}{}", self.host, ARE_ORDERS_SCORING);
        let resp: crate::types::OrdersScoring = self
            .http_post_typed(
                &endpoint,
                Some(RequestOptions::<Value> {
                    headers: Some(headers),
                    data: Some(body_json),
                    params: None,
                }),
            )
            .await?;
        Ok(resp)
    }

    /// Parity version using JSON body `{ orderID }` instead of query param.
    pub async fn cancel_order_payload(
        &self,
        payload: OrderPayloadParity,
    ) -> Result<Order, ClobError> {
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let creds = self.require_creds()?;
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();
        let body_str =
            serde_json::to_string(&payload).map_err(|e| ClobError::Other(e.to_string()))?;
        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let mut headers = crate::headers::create_l2_headers(
            signer_ref,
            creds,
            "DELETE",
            CANCEL_ORDER,
            Some(&body_str),
            ts,
        )
        .await?;
        if let Some(b) = &self.builder_signer {
            let b_payload = b
                .create_builder_header_payload("DELETE", CANCEL_ORDER, Some(&body_str), None)
                .map_err(|e| ClobError::Other(format!("builder header error: {}", e)))?;
            headers = crate::headers::inject_builder_headers(headers, &b_payload);
        }
        let endpoint = format!("{}{}", self.host, CANCEL_ORDER);
        // Serialize body as generic Value for RequestOptions
        let body_val =
            serde_json::to_value(&payload).map_err(|e| ClobError::Other(e.to_string()))?;
        let opts: RequestOptions<Value> = RequestOptions::<Value> {
            headers: Some(headers),
            data: Some(body_val),
            params: None,
        };
        let raw: MaybeItem<Order> = self.http_del_typed(&endpoint, Some(opts)).await?;
        Ok(raw.into_item())
    }

    /// Raw JSON variant: return the API response as `serde_json::Value` (parity with TS `any`).
    pub async fn cancel_order_payload_raw(
        &self,
        payload: OrderPayloadParity,
    ) -> Result<Value, ClobError> {
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let creds = self.require_creds()?;
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();
        let body_str =
            serde_json::to_string(&payload).map_err(|e| ClobError::Other(e.to_string()))?;
        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let mut headers = crate::headers::create_l2_headers(
            signer_ref,
            creds,
            "DELETE",
            CANCEL_ORDER,
            Some(&body_str),
            ts,
        )
        .await?;
        if let Some(b) = &self.builder_signer {
            let b_payload = b
                .create_builder_header_payload("DELETE", CANCEL_ORDER, Some(&body_str), None)
                .map_err(|e| ClobError::Other(format!("builder header error: {}", e)))?;
            headers = crate::headers::inject_builder_headers(headers, &b_payload);
        }
        let endpoint = format!("{}{}", self.host, CANCEL_ORDER);
        let body_val =
            serde_json::to_value(&payload).map_err(|e| ClobError::Other(e.to_string()))?;
        let opts: RequestOptions<Value> = RequestOptions::<Value> {
            headers: Some(headers),
            data: Some(body_val),
            params: None,
        };
        let raw: MaybeItem<Value> = self.http_del_typed(&endpoint, Some(opts)).await?;
        Ok(raw.into_item())
    }

    pub async fn cancel_orders(&self, order_ids: Vec<String>) -> Result<Vec<Order>, ClobError> {
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let creds = self.require_creds()?;
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();
        let body_str =
            serde_json::to_string(&order_ids).map_err(|e| ClobError::Other(e.to_string()))?;
        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let mut headers = crate::headers::create_l2_headers(
            signer_ref,
            creds,
            "DELETE",
            CANCEL_ORDERS,
            Some(&body_str),
            ts,
        )
        .await?;
        if let Some(b) = &self.builder_signer {
            let b_payload = b
                .create_builder_header_payload("DELETE", CANCEL_ORDERS, Some(&body_str), None)
                .map_err(|e| ClobError::Other(format!("builder header error: {}", e)))?;
            headers = crate::headers::inject_builder_headers(headers, &b_payload);
        }
        let endpoint = format!("{}{}", self.host, CANCEL_ORDERS);
        let opts = RequestOptions {
            headers: Some(headers),
            data: Some(order_ids.clone()),
            params: None,
        };
        let raw: MaybeVec<Order> = self.http_del_typed(&endpoint, Some(opts)).await?;
        Ok(raw.into_vec())
    }

    pub async fn get_order(&self, order_id: &str) -> Result<OpenOrder, ClobError> {
        // 与 TypeScript SDK 保持一致：执行带 L2 鉴权的调用
        self.get_order_typed(order_id).await
    }

    /// Typed variant: try to deserialize an order response into `OpenOrder`.
    pub async fn get_order_typed(&self, order_id: &str) -> Result<OpenOrder, ClobError> {
        // TS SDK 行为：必须 L2 鉴权（canL2Auth + createL2Headers），useServerTime 时使用服务器时间戳参与 HMAC
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();

        // requestPath 需要包含具体 /orders/{id}，与 TS 保持完全一致
        let request_path = format!("{}{}", GET_ORDER, order_id);
        let endpoint = format!("{}{}", self.host, request_path);

        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let mut headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "GET",
            &request_path,
            None,
            ts,
        )
        .await?;

        if let Some(b) = &self.builder_signer {
            let b_payload = b
                .create_builder_header_payload("GET", &request_path, None, None)
                .map_err(|e| ClobError::Other(format!("builder header error: {}", e)))?;
            headers = crate::headers::inject_builder_headers(headers, &b_payload);
        }

        let opts = RequestOptions {
            headers: Some(headers),
            data: None,
            params: None,
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        // API may return object or { data: object }
        if val.is_object() && val.get("id").is_some() {
            let o: OpenOrder =
                serde_json::from_value(val).map_err(|e| ClobError::Other(e.to_string()))?;
            Ok(o)
        } else if let Some(d) = val.get("data") {
            let o: OpenOrder =
                serde_json::from_value(d.clone()).map_err(|e| ClobError::Other(e.to_string()))?;
            Ok(o)
        } else {
            Err(ClobError::Other(format!(
                "unexpected order response shape: {}",
                val
            )))
        }
    }

    pub async fn get_open_orders(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<SignedOrder>, ClobError> {
        // Delegate to typed variant
        self.get_open_orders_typed(params).await
    }

    /// Typed variant: try to deserialize open orders `data` into Vec<SignedOrder>`.
    pub async fn get_open_orders_typed(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<SignedOrder>, ClobError> {
        // TS SDK 行为：getOpenOrders 需要 L2 鉴权
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();

        let endpoint = format!("{}{}", self.host, GET_OPEN_ORDERS);
        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let mut headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "GET",
            GET_OPEN_ORDERS,
            None,
            ts,
        )
        .await?;

        if let Some(b) = &self.builder_signer {
            let b_payload = b
                .create_builder_header_payload("GET", GET_OPEN_ORDERS, None, None)
                .map_err(|e| ClobError::Other(format!("builder header error: {}", e)))?;
            headers = crate::headers::inject_builder_headers(headers, &b_payload);
        }

        let query = params.unwrap_or_default();
        let opts = RequestOptions {
            headers: Some(headers),
            data: None,
            params: if query.is_empty() { None } else { Some(query) },
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        // API might return { data: [...] } or an array directly
        let arr = if val.is_array() {
            val
        } else if let Some(d) = val.get("data") {
            d.clone()
        } else {
            return Err(ClobError::Other(
                "unexpected open orders response shape".to_string(),
            ));
        };
        let orders: Vec<SignedOrder> =
            serde_json::from_value(arr).map_err(|e| ClobError::Other(e.to_string()))?;
        Ok(orders)
    }

    pub async fn get_markets(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::Market>, ClobError> {
        let endpoint = format!("{}{}", self.host, GET_MARKETS);
        let opts = RequestOptions {
            headers: None,
            data: None,
            params,
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        // API may return an array or an object containing `data: [...]`
        let arr = if val.is_array() {
            val
        } else if let Some(d) = val.get("data") {
            d.clone()
        } else {
            return Err(ClobError::Other(
                "unexpected markets response shape".to_string(),
            ));
        };
        let markets: Vec<crate::types::Market> =
            serde_json::from_value(arr).map_err(|e| ClobError::Other(e.to_string()))?;
        Ok(markets)
    }

    pub async fn get_market(
        &self,
        market_id: &str,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<crate::types::Market, ClobError> {
        let endpoint = format!("{}{}{}", self.host, GET_MARKET, market_id);
        let opts = RequestOptions {
            headers: None,
            data: None,
            params,
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        // /markets/{id} returns a single Market object directly
        let m: crate::types::Market =
            serde_json::from_value(val).map_err(|e| ClobError::Other(e.to_string()))?;
        Ok(m)
    }

    pub async fn get_simplified_markets(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::Market>, ClobError> {
        let endpoint = format!("{}{}", self.host, GET_SIMPLIFIED_MARKETS);
        let opts = RequestOptions {
            headers: None,
            data: None,
            params,
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        let arr = if val.is_array() {
            val
        } else if let Some(d) = val.get("data") {
            d.clone()
        } else {
            return Err(ClobError::Other(
                "unexpected simplified markets response shape".to_string(),
            ));
        };
        let markets: Vec<crate::types::Market> =
            serde_json::from_value(arr).map_err(|e| ClobError::Other(e.to_string()))?;
        Ok(markets)
    }

    pub async fn get_sampling_markets(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::Market>, ClobError> {
        let endpoint = format!("{}{}", self.host, GET_SAMPLING_MARKETS);
        let opts = RequestOptions {
            headers: None,
            data: None,
            params,
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        let arr = if val.is_array() {
            val
        } else if let Some(d) = val.get("data") {
            d.clone()
        } else {
            return Err(ClobError::Other(
                "unexpected sampling markets response shape".to_string(),
            ));
        };
        let markets: Vec<crate::types::Market> =
            serde_json::from_value(arr).map_err(|e| ClobError::Other(e.to_string()))?;
        Ok(markets)
    }

    pub async fn get_server_time(&self) -> Result<u64, ClobError> {
        let endpoint = format!("{}{}", self.host, TIME);
        let val = self.http_get(&endpoint, None).await?;
        // Expect number or object with `time`
        if val.is_number() {
            Ok(val
                .as_u64()
                .ok_or(ClobError::Other("invalid time value".to_string()))?)
        } else if val.get("time").is_some() {
            Ok(val
                .get("time")
                .and_then(|v| v.as_u64())
                .ok_or(ClobError::Other("invalid time value".to_string()))?)
        } else {
            Err(ClobError::Other(
                "unexpected server time response".to_string(),
            ))
        }
    }

    fn can_l1_auth(&self) -> Result<(), ClobError> {
        if self.signer.is_none() {
            return Err(ClobError::Other("L1 auth required".to_string()));
        }
        Ok(())
    }

    pub async fn create_api_key(&self, nonce: Option<u64>) -> Result<ApiKeyCreds, ClobError> {
        self.can_l1_auth()?;
        let signer_arc = self.signer.as_ref().ok_or(ClobError::L1AuthUnavailable)?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();
        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let headers =
            crate::headers::create_l1_headers(signer_ref, self.chain_id as i32, nonce, ts).await?;
        let endpoint = format!("{}{}", self.host, CREATE_API_KEY);
        let opts = RequestOptions {
            headers: Some(headers),
            data: None,
            params: None,
        };
        let val = self.http_post(&endpoint, Some(opts)).await?;
        // Deserialize into ApiKeyRaw then to ApiKeyCreds
        let api_raw: ApiKeyRaw =
            serde_json::from_value(val).map_err(|e| ClobError::Other(e.to_string()))?;
        let api_key = ApiKeyCreds {
            key: api_raw.api_key,
            secret: api_raw.secret,
            passphrase: api_raw.passphrase,
        };
        Ok(api_key)
    }

    // Additional endpoints ported from TypeScript client
    pub async fn derive_api_key(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<ApiKeyCreds, ClobError> {
        self.can_l1_auth()?;
        let signer_arc = self.signer.as_ref().ok_or(ClobError::L1AuthUnavailable)?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();
        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let headers =
            crate::headers::create_l1_headers(signer_ref, self.chain_id as i32, None, ts).await?;
        let endpoint = format!("{}{}", self.host, DERIVE_API_KEY);
        let opts = RequestOptions {
            headers: Some(headers),
            data: None,
            params,
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        // Deserialize ApiKeyRaw then map to ApiKeyCreds
        let api_raw: ApiKeyRaw =
            serde_json::from_value(val).map_err(|e| ClobError::Other(e.to_string()))?;
        let api_key = ApiKeyCreds {
            key: api_raw.api_key,
            secret: api_raw.secret,
            passphrase: api_raw.passphrase,
        };
        Ok(api_key)
    }

    pub async fn create_builder_api_key(&self) -> Result<crate::types::ApiKeyCreds, ClobError> {
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();
        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "POST",
            CREATE_BUILDER_API_KEY,
            None,
            ts,
        )
        .await?;
        let endpoint = format!("{}{}", self.host, CREATE_BUILDER_API_KEY);
        let resp: crate::types::ApiKeyCreds = self
            .http_post_typed(
                &endpoint,
                Some(RequestOptions::<Value> {
                    headers: Some(headers),
                    data: None,
                    params: None,
                }),
            )
            .await?;
        Ok(resp)
    }

    pub async fn get_builder_api_keys(&self) -> Result<Vec<crate::types::ApiKeyCreds>, ClobError> {
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();
        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "GET",
            GET_BUILDER_API_KEYS,
            None,
            ts,
        )
        .await?;
        let endpoint = format!("{}{}", self.host, GET_BUILDER_API_KEYS);
        let resp: Vec<crate::types::ApiKeyCreds> = self
            .http_get_typed(
                &endpoint,
                Some(RequestOptions::<Value> {
                    headers: Some(headers),
                    data: None,
                    params: None,
                }),
            )
            .await?;
        Ok(resp)
    }

    pub async fn revoke_builder_api_key(&self) -> Result<(), ClobError> {
        if self.builder_signer.is_none() {
            return Err(ClobError::Other("Builder signer required".to_string()));
        }
        let b_signer = self
            .builder_signer
            .as_ref()
            .ok_or(ClobError::BuilderAuthNotAvailable)?;
        let headers_map = b_signer
            .create_builder_header_payload("DELETE", REVOKE_BUILDER_API_KEY, None, None)
            .map_err(|e| ClobError::Other(format!("builder header error: {}", e)))?;

        let mut headers = crate::headers::Headers::new();
        for (k, v) in headers_map {
            headers.insert(k, v);
        }

        let endpoint = format!("{}{}", self.host, REVOKE_BUILDER_API_KEY);
        let _val: () = self
            .http_del_typed::<(), Value>(
                &endpoint,
                Some(RequestOptions::<Value> {
                    headers: Some(headers),
                    data: None,
                    params: None,
                }),
            )
            .await?;
        Ok(())
    }

    pub async fn get_sampling_simplified_markets(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::Market>, ClobError> {
        let endpoint = format!("{}{}", self.host, GET_SAMPLING_SIMPLIFIED_MARKETS);
        let opts = RequestOptions {
            headers: None,
            data: None,
            params,
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        let arr = if val.is_object() && val.get("data").is_some() {
            val.get("data").cloned().unwrap_or_default()
        } else if val.is_array() {
            val
        } else {
            return Err(ClobError::Other(
                "unexpected sampling simplified markets response shape".to_string(),
            ));
        };
        let markets: Vec<crate::types::Market> =
            serde_json::from_value(arr).map_err(|e| ClobError::Other(e.to_string()))?;
        Ok(markets)
    }

    /// POST `/books` with `[{"token_id":"..."}]` → array of OrderBookSummary
    pub async fn get_order_books(
        &self,
        params: &[crate::types::BookParams],
    ) -> Result<Vec<crate::types::OrderBookSummary>, ClobError> {
        let endpoint = format!("{}{}", self.host, GET_ORDER_BOOKS);
        let body = serde_json::to_value(params).map_err(|e| ClobError::Other(e.to_string()))?;
        let opts = RequestOptions {
            headers: None,
            data: Some(body),
            params: None,
        };
        let val = self.http_post(&endpoint, Some(opts)).await?;
        let arr = if val.is_array() {
            val
        } else if let Some(d) = val.get("data") {
            d.clone()
        } else {
            return Err(ClobError::Other(
                "unexpected order books response shape".to_string(),
            ));
        };
        let books: Vec<crate::types::OrderBookSummary> =
            serde_json::from_value(arr).map_err(|e| ClobError::Other(e.to_string()))?;
        Ok(books)
    }

    /// GET `/midpoint?token_id=...` → `{"mid": "0.77"}`
    pub async fn get_midpoint(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<crate::types::MidpointResponse, ClobError> {
        let endpoint = format!("{}{}", self.host, GET_MIDPOINT);
        let opts = RequestOptions {
            headers: None,
            data: None,
            params,
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        let resp: crate::types::MidpointResponse =
            serde_json::from_value(val).map_err(|e| ClobError::Other(e.to_string()))?;
        Ok(resp)
    }

    /// POST `/midpoints` with `[{"token_id":"..."}]` → `{"TOKEN_ID": "0.77"}`
    pub async fn get_midpoints(
        &self,
        params: &[crate::types::BookParams],
    ) -> Result<serde_json::Value, ClobError> {
        let endpoint = format!("{}{}", self.host, GET_MIDPOINTS);
        let body = serde_json::to_value(params).map_err(|e| ClobError::Other(e.to_string()))?;
        let opts = RequestOptions {
            headers: None,
            data: Some(body),
            params: None,
        };
        self.http_post(&endpoint, Some(opts)).await
    }

    /// GET `/price?token_id=...&side=BUY` → `{"price": "0.76"}`
    pub async fn get_price(
        &self,
        token_id: &str,
        side: &str,
    ) -> Result<crate::types::PriceResponse, ClobError> {
        let endpoint = format!("{}{}", self.host, GET_PRICE);
        let mut qp = std::collections::HashMap::new();
        qp.insert("token_id".to_string(), token_id.to_string());
        qp.insert("side".to_string(), side.to_string());
        let opts = RequestOptions {
            headers: None,
            data: None,
            params: Some(qp),
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        let resp: crate::types::PriceResponse =
            serde_json::from_value(val).map_err(|e| ClobError::Other(e.to_string()))?;
        Ok(resp)
    }

    /// POST `/prices` with `[{"token_id":"...","side":"BUY"}]` → `{"TOKEN_ID": {"BUY": "0.76"}}`
    pub async fn get_prices(
        &self,
        params: &[crate::types::BookParams],
    ) -> Result<serde_json::Value, ClobError> {
        let endpoint = format!("{}{}", self.host, GET_PRICES);
        let body = serde_json::to_value(params).map_err(|e| ClobError::Other(e.to_string()))?;
        let opts = RequestOptions {
            headers: None,
            data: Some(body),
            params: None,
        };
        self.http_post(&endpoint, Some(opts)).await
    }

    /// GET `/spread?token_id=...` → `{"spread": "0.02"}`
    pub async fn get_spread(
        &self,
        token_id: &str,
    ) -> Result<crate::types::SpreadResponse, ClobError> {
        let endpoint = format!("{}{}", self.host, GET_SPREAD);
        let mut qp = std::collections::HashMap::new();
        qp.insert("token_id".to_string(), token_id.to_string());
        let opts = RequestOptions {
            headers: None,
            data: None,
            params: Some(qp),
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        let resp: crate::types::SpreadResponse =
            serde_json::from_value(val).map_err(|e| ClobError::Other(e.to_string()))?;
        Ok(resp)
    }

    /// POST `/spreads` with `[{"token_id":"..."}]` → `{"TOKEN_ID": "0.02"}`
    pub async fn get_spreads(
        &self,
        params: &[crate::types::BookParams],
    ) -> Result<serde_json::Value, ClobError> {
        let endpoint = format!("{}{}", self.host, GET_SPREADS);
        let body = serde_json::to_value(params).map_err(|e| ClobError::Other(e.to_string()))?;
        let opts = RequestOptions {
            headers: None,
            data: Some(body),
            params: None,
        };
        self.http_post(&endpoint, Some(opts)).await
    }

    /// GET `/last-trade-price?token_id=...` → `{"price": "0.8", "side": "BUY"}`
    pub async fn get_last_trade_price(
        &self,
        token_id: &str,
    ) -> Result<crate::types::LastTradePriceResponse, ClobError> {
        let endpoint = format!("{}{}", self.host, GET_LAST_TRADE_PRICE);
        let mut qp = std::collections::HashMap::new();
        qp.insert("token_id".to_string(), token_id.to_string());
        let opts = RequestOptions {
            headers: None,
            data: None,
            params: Some(qp),
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        let resp: crate::types::LastTradePriceResponse =
            serde_json::from_value(val).map_err(|e| ClobError::Other(e.to_string()))?;
        Ok(resp)
    }

    /// POST `/last-trades-prices` with `[{"token_id":"..."}]` → `[{"price":"0.8","side":"BUY","token_id":"..."}]`
    pub async fn get_last_trades_prices(
        &self,
        params: &[crate::types::BookParams],
    ) -> Result<serde_json::Value, ClobError> {
        let endpoint = format!("{}{}", self.host, GET_LAST_TRADES_PRICES);
        let body = serde_json::to_value(params).map_err(|e| ClobError::Other(e.to_string()))?;
        let opts = RequestOptions {
            headers: None,
            data: Some(body),
            params: None,
        };
        self.http_post(&endpoint, Some(opts)).await
    }

    /// GET `/prices-history?market=TOKEN_ID&interval=...&fidelity=...` → `{"history": [{t, p}]}`
    pub async fn get_prices_history(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::MarketPrice>, ClobError> {
        let endpoint = format!("{}{}", self.host, GET_PRICES_HISTORY);
        let opts = RequestOptions {
            headers: None,
            data: None,
            params,
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        // API returns {"history": [{t, p}, ...]}
        if let Some(history) = val.get("history") {
            let prices: Vec<crate::types::MarketPrice> = serde_json::from_value(history.clone())
                .map_err(|e| ClobError::Other(e.to_string()))?;
            Ok(prices)
        } else if val.is_array() {
            // Fallback: bare array
            let prices: Vec<crate::types::MarketPrice> =
                serde_json::from_value(val).map_err(|e| ClobError::Other(e.to_string()))?;
            Ok(prices)
        } else {
            Err(ClobError::Other(
                "unexpected prices history response shape".to_string(),
            ))
        }
    }

    pub async fn get_market_trades_events(
        &self,
        market_id: &str,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::Trade>, ClobError> {
        let endpoint = format!("{}{}{}", self.host, GET_MARKET_TRADES_EVENTS, market_id);
        let opts = RequestOptions {
            headers: None,
            data: None,
            params,
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        let arr = if val.is_array() {
            val
        } else if let Some(d) = val.get("data") {
            d.clone()
        } else {
            return Err(ClobError::Other(
                "unexpected market trades events response shape".to_string(),
            ));
        };
        let trades: Vec<crate::types::Trade> =
            serde_json::from_value(arr).map_err(|e| ClobError::Other(e.to_string()))?;
        Ok(trades)
    }

    // Rewards endpoints
    pub async fn get_earnings_for_user_for_day(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::Reward>, ClobError> {
        let endpoint = format!("{}{}", self.host, GET_EARNINGS_FOR_USER_FOR_DAY);
        let opts = RequestOptions {
            headers: None,
            data: None,
            params,
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        let arr = if val.is_array() {
            val
        } else if let Some(d) = val.get("data") {
            d.clone()
        } else {
            return Err(ClobError::Other(
                "unexpected earnings response shape".to_string(),
            ));
        };
        let rewards: Vec<crate::types::Reward> =
            serde_json::from_value(arr).map_err(|e| ClobError::Other(e.to_string()))?;
        Ok(rewards)
    }

    pub async fn get_total_earnings_for_user_for_day(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::Reward>, ClobError> {
        let endpoint = format!("{}{}", self.host, GET_TOTAL_EARNINGS_FOR_USER_FOR_DAY);
        let opts = RequestOptions {
            headers: None,
            data: None,
            params,
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        let arr = if val.is_array() {
            val
        } else if let Some(d) = val.get("data") {
            d.clone()
        } else {
            return Err(ClobError::Other(
                "unexpected total earnings response shape".to_string(),
            ));
        };
        let rewards: Vec<crate::types::Reward> =
            serde_json::from_value(arr).map_err(|e| ClobError::Other(e.to_string()))?;
        Ok(rewards)
    }

    /// Typed wrapper for total earnings for user for day. Attempts to parse an array of Reward.
    pub async fn get_total_earnings_for_user_for_day_typed(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::Reward>, ClobError> {
        let val = self.get_total_earnings_for_user_for_day(params).await?;
        Ok(val)
    }

    pub async fn get_liquidity_reward_percentages(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<std::collections::HashMap<String, f64>, ClobError> {
        let endpoint = format!("{}{}", self.host, GET_LIQUIDITY_REWARD_PERCENTAGES);
        let opts = RequestOptions {
            headers: None,
            data: None,
            params,
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        // Accept object or { data: object }
        let obj = if val.is_object() {
            val
        } else if let Some(d) = val.get("data") {
            d.clone()
        } else {
            return Err(ClobError::Other(
                "unexpected liquidity percentages response shape".to_string(),
            ));
        };
        let map: std::collections::HashMap<String, f64> =
            serde_json::from_value(obj).map_err(|e| ClobError::Other(e.to_string()))?;
        Ok(map)
    }

    /// Typed wrapper for liquidity reward percentages. Attempts to parse into a map of market -> percentage.
    pub async fn get_liquidity_reward_percentages_typed(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<std::collections::HashMap<String, f64>, ClobError> {
        let val = self.get_liquidity_reward_percentages(params).await?;
        Ok(val)
    }

    pub async fn get_rewards_markets_current(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::RewardsMarket>, ClobError> {
        let endpoint = format!("{}{}", self.host, GET_REWARDS_MARKETS_CURRENT);
        let opts = RequestOptions {
            headers: None,
            data: None,
            params,
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        let arr = if val.is_array() {
            val
        } else if let Some(d) = val.get("data") {
            d.clone()
        } else {
            return Err(ClobError::Other(
                "unexpected rewards markets response shape".to_string(),
            ));
        };
        let rewards: Vec<crate::types::RewardsMarket> =
            serde_json::from_value(arr).map_err(|e| ClobError::Other(e.to_string()))?;
        Ok(rewards)
    }

    pub async fn get_rewards_markets(
        &self,
        market_id: &str,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::Reward>, ClobError> {
        let endpoint = format!("{}{}{}", self.host, GET_REWARDS_MARKETS, market_id);
        let opts = RequestOptions {
            headers: None,
            data: None,
            params,
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        let arr = if val.is_array() {
            val
        } else if let Some(d) = val.get("data") {
            d.clone()
        } else {
            return Err(ClobError::Other(
                "unexpected rewards markets response shape".to_string(),
            ));
        };
        let rewards: Vec<crate::types::Reward> =
            serde_json::from_value(arr).map_err(|e| ClobError::Other(e.to_string()))?;
        Ok(rewards)
    }

    /// Typed wrapper for get_rewards_markets (per-market rewards). Returns Vec<Reward>.
    pub async fn get_rewards_markets_typed(
        &self,
        market_id: &str,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::Reward>, ClobError> {
        let val = self.get_rewards_markets(market_id, params).await?;
        Ok(val)
    }

    pub async fn get_rewards_earnings_percentages(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::Reward>, ClobError> {
        let endpoint = format!("{}{}", self.host, GET_REWARDS_EARNINGS_PERCENTAGES);
        let opts = RequestOptions {
            headers: None,
            data: None,
            params,
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        let arr = if val.is_array() {
            val
        } else if let Some(d) = val.get("data") {
            d.clone()
        } else {
            return Err(ClobError::Other(
                "unexpected rewards earnings percentages response shape".to_string(),
            ));
        };
        let rewards: Vec<crate::types::Reward> =
            serde_json::from_value(arr).map_err(|e| ClobError::Other(e.to_string()))?;
        Ok(rewards)
    }

    /// Typed wrapper for rewards earnings percentages. Returns Vec<Reward> or object parsed into map.
    pub async fn get_rewards_earnings_percentages_typed(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::Reward>, ClobError> {
        let val = self.get_rewards_earnings_percentages(params).await?;
        Ok(val)
    }

    pub async fn get_builder_trades(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::BuilderTrade>, ClobError> {
        if self.builder_signer.is_none() {
            return Err(ClobError::Other("Builder signer required".to_string()));
        }
        let b_signer = self
            .builder_signer
            .as_ref()
            .ok_or(ClobError::BuilderAuthNotAvailable)?;
        let headers_map = b_signer
            .create_builder_header_payload("GET", GET_BUILDER_TRADES, None, None)
            .map_err(|e| ClobError::Other(format!("builder header error: {}", e)))?;

        // Convert HashMap<String, String> to Headers
        let mut headers = crate::headers::Headers::new();
        for (k, v) in headers_map {
            headers.insert(k, v);
        }

        let endpoint = format!("{}{}", self.host, GET_BUILDER_TRADES);
        let opts = RequestOptions {
            headers: Some(headers),
            data: None,
            params,
        };
        let val = self.http_get(&endpoint, Some(opts)).await?;
        let arr = if val.is_array() {
            val
        } else if let Some(d) = val.get("data") {
            d.clone()
        } else {
            return Err(ClobError::Other(
                "unexpected builder trades response shape".to_string(),
            ));
        };
        let trades: Vec<crate::types::BuilderTrade> =
            serde_json::from_value(arr).map_err(|e| ClobError::Other(e.to_string()))?;
        Ok(trades)
    }

    /// Typed variant for builder trades (kept for compatibility)
    pub async fn get_builder_trades_typed(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::BuilderTrade>, ClobError> {
        self.get_builder_trades(params).await
    }

    /// Typed wrapper for get_earnings_for_user_for_day -> Vec<Reward>
    pub async fn get_earnings_for_user_for_day_typed(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::Reward>, ClobError> {
        let val = self.get_earnings_for_user_for_day(params).await?;
        Ok(val)
    }

    /// Typed wrapper for current rewards markets
    pub async fn get_rewards_markets_current_typed(
        &self,
        params: Option<std::collections::HashMap<String, String>>,
    ) -> Result<Vec<crate::types::RewardsMarket>, ClobError> {
        let val = self.get_rewards_markets_current(params).await?;
        Ok(val)
    }

    /// Post a heartbeat to keep the session alive (added in v5.2.0)
    ///
    /// Heartbeats must be sent within 10 seconds of each other. If a heartbeat is not
    /// received within 10 seconds, all orders will be cancelled.
    ///
    /// Use heartbeat_id=None for the first heartbeat, then chain subsequent heartbeats
    /// using the returned heartbeat_id.
    ///
    /// # Arguments
    /// * `heartbeat_id` - Optional heartbeat ID from a previous heartbeat to chain them
    ///
    /// # Returns
    /// * `HeartbeatResponse` containing the heartbeat_id to use for the next heartbeat
    pub async fn post_heartbeat(
        &self,
        heartbeat_id: Option<&str>,
    ) -> Result<HeartbeatResponse, ClobError> {
        if self.creds.is_none() {
            return Err(ClobError::Other("L2 creds required".to_string()));
        }
        let signer_arc = self
            .signer
            .as_ref()
            .ok_or(ClobError::Other("L1 signer required".to_string()))?;
        let signer_ref: &EthersSigner = signer_arc.as_ref();

        // Build request body — field name must be snake_case "heartbeat_id"
        // to match Polymarket API (see py-clob-client reference implementation).
        let body = serde_json::json!({ "heartbeat_id": heartbeat_id });
        let body_str = serde_json::to_string(&body).map_err(|e| ClobError::Other(e.to_string()))?;

        let ts = if self.use_server_time {
            Some(self.get_server_time().await?)
        } else {
            None
        };
        let headers = crate::headers::create_l2_headers(
            signer_ref,
            self.require_creds()?,
            "POST",
            POST_HEARTBEAT,
            Some(&body_str),
            ts,
        )
        .await?;

        let endpoint = format!("{}{}", self.host, POST_HEARTBEAT);
        let resp: HeartbeatResponse = self
            .http_post_typed(
                &endpoint,
                Some(RequestOptions {
                    headers: Some(headers),
                    data: Some(body),
                    params: None,
                }),
            )
            .await?;
        Ok(resp)
    }
}