nautilus_polymarket/python/

loader.rs

// -------------------------------------------------------------------------------------------------
//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
//  https://nautechsystems.io
//
//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
//  You may not use this file except in compliance with the License.
//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
// -------------------------------------------------------------------------------------------------

//! Rust-backed Python discovery and historical data facade.

use std::collections::HashMap;

use jiff::Timestamp;
use nautilus_core::{
    datetime::datetime_to_unix_nanos,
    python::{
        IntoPyObjectNautilusExt, params::value_to_pyobject, to_pyruntime_err, to_pyvalue_err,
    },
    time::get_atomic_clock_realtime,
};
use nautilus_model::{
    data::TradeTick,
    instruments::{BinaryOption, InstrumentAny},
};
use nautilus_network::retry::RetryConfig;
use pyo3::{
    conversion::IntoPyObjectExt,
    prelude::*,
    types::{PyDict, PyList},
};
use serde::Serialize;
use serde_json::{Value, json};

use super::extract_string_map;
use crate::{
    http::{
        clob::PolymarketClobPublicClient,
        data_api::PolymarketDataApiHttpClient,
        error::Error as PolymarketHttpError,
        gamma::{PolymarketGammaHttpClient, flatten_event_markets},
        models::{ClobMarketResponse, GammaEvent, GammaMarket},
        parse::{create_instrument_from_def, enrich_market_fee_schedule, parse_gamma_market},
        query::{GetGammaMarketsParams, GetSearchParams},
    },
    providers::{build_gamma_event_params_from_hashmap, build_gamma_params_from_hashmap},
};

#[pyclass(name = "PolymarketDataLoader", skip_from_py_object)]
#[pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.adapters.polymarket")]
#[derive(Clone, Debug)]
pub struct PyPolymarketDataLoader {
    instrument: BinaryOption,
    token_id: String,
    condition_id: String,
    resolution_metadata: Value,
    data_api_client: PolymarketDataApiHttpClient,
}

#[pymethods]
#[pyo3_stub_gen::derive::gen_stub_pymethods]
impl PyPolymarketDataLoader {
    /// Queries one Gamma market by slug.
    #[staticmethod]
    #[pyo3(signature = (slug, base_url_gamma=None, timeout_secs=10))]
    fn query_market_by_slug<'py>(
        py: Python<'py>,
        slug: String,
        base_url_gamma: Option<String>,
        timeout_secs: u64,
    ) -> PyResult<Bound<'py, PyAny>> {
        validate_non_empty("slug", &slug)?;

        pyo3_async_runtimes::tokio::future_into_py(py, async move {
            let client = gamma_client(base_url_gamma, timeout_secs)?;
            let market = request_market_by_slug(&client, &slug).await?;
            Python::attach(|py| serialize_to_py(py, &market))
        })
    }

    /// Queries public CLOB market details by condition ID.
    #[staticmethod]
    #[pyo3(signature = (condition_id, base_url_http=None, timeout_secs=10))]
    fn query_market_details<'py>(
        py: Python<'py>,
        condition_id: String,
        base_url_http: Option<String>,
        timeout_secs: u64,
    ) -> PyResult<Bound<'py, PyAny>> {
        validate_non_empty("condition_id", &condition_id)?;

        pyo3_async_runtimes::tokio::future_into_py(py, async move {
            let client = clob_client(base_url_http, timeout_secs)?;
            let market = client
                .get_market(&condition_id)
                .await
                .map_err(to_pyruntime_err)?;
            Python::attach(|py| serialize_to_py(py, &market))
        })
    }

    /// Queries one Gamma event by slug.
    #[staticmethod]
    #[pyo3(signature = (slug, base_url_gamma=None, timeout_secs=10))]
    fn query_event_by_slug<'py>(
        py: Python<'py>,
        slug: String,
        base_url_gamma: Option<String>,
        timeout_secs: u64,
    ) -> PyResult<Bound<'py, PyAny>> {
        validate_non_empty("slug", &slug)?;

        pyo3_async_runtimes::tokio::future_into_py(py, async move {
            let client = gamma_client(base_url_gamma, timeout_secs)?;
            let event = request_event_by_slug(&client, &slug).await?;
            Python::attach(|py| serialize_to_py(py, &event))
        })
    }

    /// Lists Gamma markets with validated filters and keyset pagination.
    #[staticmethod]
    #[pyo3(signature = (filters=None, base_url_gamma=None, timeout_secs=10))]
    fn query_markets<'py>(
        py: Python<'py>,
        filters: Option<&Bound<'py, PyAny>>,
        base_url_gamma: Option<String>,
        timeout_secs: u64,
    ) -> PyResult<Bound<'py, PyAny>> {
        let filters = extract_filters(filters)?;
        let params = build_gamma_params_from_hashmap(&filters).map_err(to_pyvalue_err)?;

        pyo3_async_runtimes::tokio::future_into_py(py, async move {
            let client = gamma_client(base_url_gamma, timeout_secs)?;
            let markets = client
                .request_markets_by_params(params)
                .await
                .map_err(to_pyruntime_err)?;
            Python::attach(|py| serialize_to_py(py, &markets))
        })
    }

    /// Lists Gamma events with validated filters and keyset pagination.
    #[staticmethod]
    #[pyo3(signature = (filters=None, base_url_gamma=None, timeout_secs=10))]
    fn query_events<'py>(
        py: Python<'py>,
        filters: Option<&Bound<'py, PyAny>>,
        base_url_gamma: Option<String>,
        timeout_secs: u64,
    ) -> PyResult<Bound<'py, PyAny>> {
        let filters = extract_filters(filters)?;
        let params = build_gamma_event_params_from_hashmap(&filters).map_err(to_pyvalue_err)?;

        pyo3_async_runtimes::tokio::future_into_py(py, async move {
            let client = gamma_client(base_url_gamma, timeout_secs)?;
            let events = client
                .request_events_by_params(params)
                .await
                .map_err(to_pyruntime_err)?;
            Python::attach(|py| serialize_to_py(py, &events))
        })
    }

    /// Lists Gamma tags.
    #[staticmethod]
    #[pyo3(signature = (base_url_gamma=None, timeout_secs=10))]
    fn query_tags<'py>(
        py: Python<'py>,
        base_url_gamma: Option<String>,
        timeout_secs: u64,
    ) -> PyResult<Bound<'py, PyAny>> {
        pyo3_async_runtimes::tokio::future_into_py(py, async move {
            let client = gamma_client(base_url_gamma, timeout_secs)?;
            let tags = client.request_tags().await.map_err(to_pyruntime_err)?;
            Python::attach(|py| serialize_to_py(py, &tags))
        })
    }

    /// Searches Gamma markets and events.
    #[staticmethod]
    #[pyo3(signature = (
        query,
        events_status=None,
        events_tag=None,
        sort=None,
        ascending=None,
        limit_per_type=None,
        page=None,
        keep_closed_markets=None,
        base_url_gamma=None,
        timeout_secs=10,
    ))]
    #[expect(clippy::too_many_arguments)]
    fn query_search<'py>(
        py: Python<'py>,
        query: String,
        events_status: Option<String>,
        events_tag: Option<String>,
        sort: Option<String>,
        ascending: Option<bool>,
        limit_per_type: Option<u32>,
        page: Option<u32>,
        keep_closed_markets: Option<bool>,
        base_url_gamma: Option<String>,
        timeout_secs: u64,
    ) -> PyResult<Bound<'py, PyAny>> {
        validate_non_empty("query", &query)?;

        if limit_per_type == Some(0) {
            return Err(to_pyvalue_err("limit_per_type must be greater than zero"));
        }
        let params = GetSearchParams {
            q: Some(query),
            events_status,
            events_tag,
            sort,
            ascending,
            limit_per_type,
            page,
            keep_closed_markets,
        };

        pyo3_async_runtimes::tokio::future_into_py(py, async move {
            let client = gamma_client(base_url_gamma, timeout_secs)?;
            let response = client
                .inner()
                .get_public_search(params)
                .await
                .map_err(to_pyruntime_err)?;
            Python::attach(|py| serialize_to_py(py, &response))
        })
    }

    /// Creates one loader from a Gamma market slug.
    #[staticmethod]
    #[pyo3(signature = (
        slug,
        token_index=0,
        base_url_http=None,
        base_url_gamma=None,
        base_url_data_api=None,
        timeout_secs=10,
    ))]
    fn from_market_slug<'py>(
        py: Python<'py>,
        slug: String,
        token_index: isize,
        base_url_http: Option<String>,
        base_url_gamma: Option<String>,
        base_url_data_api: Option<String>,
        timeout_secs: u64,
    ) -> PyResult<Bound<'py, PyAny>> {
        validate_non_empty("slug", &slug)?;
        validate_token_index(token_index)?;

        pyo3_async_runtimes::tokio::future_into_py(py, async move {
            let gamma = gamma_client(base_url_gamma, timeout_secs)?;
            let clob = clob_client(base_url_http, timeout_secs)?;
            let data_api = data_api_client(base_url_data_api, timeout_secs)?;
            let market = request_market_by_slug(&gamma, &slug).await?;
            let loader =
                build_loader(market, token_index as usize, &gamma, &clob, data_api).await?;
            Python::attach(|py| Py::new(py, loader).map(Py::into_any))
        })
    }

    /// Creates one loader for every market in a Gamma event slug.
    #[staticmethod]
    #[pyo3(signature = (
        slug,
        token_index=0,
        base_url_http=None,
        base_url_gamma=None,
        base_url_data_api=None,
        timeout_secs=10,
    ))]
    fn from_event_slug<'py>(
        py: Python<'py>,
        slug: String,
        token_index: isize,
        base_url_http: Option<String>,
        base_url_gamma: Option<String>,
        base_url_data_api: Option<String>,
        timeout_secs: u64,
    ) -> PyResult<Bound<'py, PyAny>> {
        validate_non_empty("slug", &slug)?;
        validate_token_index(token_index)?;

        pyo3_async_runtimes::tokio::future_into_py(py, async move {
            let gamma = gamma_client(base_url_gamma, timeout_secs)?;
            let clob = clob_client(base_url_http, timeout_secs)?;
            let data_api = data_api_client(base_url_data_api, timeout_secs)?;
            let event = request_event_by_slug(&gamma, &slug).await?;
            if event.markets.is_empty() {
                return Err(to_pyvalue_err(format!(
                    "No markets found in event '{slug}'"
                )));
            }

            let mut loaders = Vec::with_capacity(event.markets.len());
            for market in flatten_event_markets(vec![event]) {
                loaders.push(
                    build_loader(
                        market,
                        token_index as usize,
                        &gamma,
                        &clob,
                        data_api.clone(),
                    )
                    .await?,
                );
            }

            Python::attach(|py| {
                let loaders = loaders
                    .into_iter()
                    .map(|loader| Py::new(py, loader))
                    .collect::<PyResult<Vec<_>>>()?;
                Ok(PyList::new(py, loaders)?.into_py_any_unwrap(py))
            })
        })
    }

    /// Returns the normalized binary option instrument.
    #[getter]
    fn instrument(&self) -> BinaryOption {
        self.instrument.clone()
    }

    /// Returns the selected CLOB token ID.
    #[getter]
    fn token_id(&self) -> &str {
        &self.token_id
    }

    /// Returns the on-chain condition ID.
    #[getter]
    fn condition_id(&self) -> &str {
        &self.condition_id
    }

    /// Returns resolution lifecycle metadata retained separately from `instrument.info`.
    ///
    /// Shared market identity such as `resolutionSource` is also available from
    /// `instrument.info["resolution_source"]`.
    #[getter]
    fn resolution_metadata(&self, py: Python<'_>) -> PyResult<Py<PyAny>> {
        value_to_pyobject(py, &self.resolution_metadata)
    }

    /// Loads historical trades from the Rust Data API client.
    #[pyo3(signature = (start=None, end=None, limit=None))]
    fn load_trades<'py>(
        &self,
        py: Python<'py>,
        start: Option<Timestamp>,
        end: Option<Timestamp>,
        limit: Option<u32>,
    ) -> PyResult<Bound<'py, PyAny>> {
        if let (Some(start), Some(end)) = (start, end)
            && start > end
        {
            return Err(to_pyvalue_err("start must not be later than end"));
        }

        if limit == Some(0) {
            return Err(to_pyvalue_err("limit must be greater than zero"));
        }

        let client = self.data_api_client.clone();
        let instrument = self.instrument.clone();
        let condition_id = self.condition_id.clone();
        let token_id = self.token_id.clone();
        let start = datetime_to_unix_nanos(start);
        let end = datetime_to_unix_nanos(end);

        pyo3_async_runtimes::tokio::future_into_py(py, async move {
            let trades = client
                .request_trade_ticks(
                    instrument.id,
                    &condition_id,
                    &token_id,
                    instrument.price_precision,
                    instrument.size_precision,
                    start,
                    end,
                    limit,
                )
                .await
                .map_err(to_pyruntime_err)?;
            Python::attach(|py| trades_to_py(py, trades))
        })
    }
}

fn gamma_client(
    base_url: Option<String>,
    timeout_secs: u64,
) -> PyResult<PolymarketGammaHttpClient> {
    PolymarketGammaHttpClient::new(base_url, timeout_secs, RetryConfig::default())
        .map_err(to_pyruntime_err)
}

fn clob_client(
    base_url: Option<String>,
    timeout_secs: u64,
) -> PyResult<PolymarketClobPublicClient> {
    PolymarketClobPublicClient::new(base_url, timeout_secs).map_err(to_pyruntime_err)
}

fn data_api_client(
    base_url: Option<String>,
    timeout_secs: u64,
) -> PyResult<PolymarketDataApiHttpClient> {
    PolymarketDataApiHttpClient::new(base_url, timeout_secs).map_err(to_pyruntime_err)
}

async fn request_market_by_slug(
    client: &PolymarketGammaHttpClient,
    slug: &str,
) -> PyResult<GammaMarket> {
    match client.inner().get_gamma_market_by_slug(slug).await {
        Ok(market) => Ok(market),
        Err(PolymarketHttpError::Http { status: 404, .. }) => Err(to_pyvalue_err(format!(
            "Market with slug '{slug}' not found"
        ))),
        Err(e) => Err(to_pyruntime_err(e)),
    }
}

async fn request_event_by_slug(
    client: &PolymarketGammaHttpClient,
    slug: &str,
) -> PyResult<GammaEvent> {
    client
        .inner()
        .get_gamma_events_by_slug(slug)
        .await
        .map_err(to_pyruntime_err)?
        .into_iter()
        .next()
        .ok_or_else(|| to_pyvalue_err(format!("Event with slug '{slug}' not found")))
}

async fn build_loader(
    mut market: GammaMarket,
    token_index: usize,
    gamma: &PolymarketGammaHttpClient,
    clob: &PolymarketClobPublicClient,
    data_api_client: PolymarketDataApiHttpClient,
) -> PyResult<PyPolymarketDataLoader> {
    if market.condition_id.trim().is_empty() {
        return Err(to_pyvalue_err("Gamma market has an empty condition ID"));
    }

    if market.fee_schedule.is_none() {
        market.fee_schedule = gamma
            .request_markets_by_params(GetGammaMarketsParams {
                condition_ids: Some(vec![market.condition_id.clone()]),
                max_markets: Some(1),
                ..Default::default()
            })
            .await
            .map_err(to_pyruntime_err)?
            .into_iter()
            .find(|candidate| candidate.condition_id == market.condition_id)
            .and_then(|candidate| candidate.fee_schedule);
    }

    enrich_market_fee_schedule(&mut market);

    let details = clob
        .get_market(&market.condition_id)
        .await
        .map_err(to_pyruntime_err)?;

    if let Some(schedule) = market.fee_schedule.as_mut()
        && schedule.rate.is_zero()
        && !schedule.rebate_rate.is_zero()
        && let Some(token) = details.tokens.get(token_index)
    {
        match clob.get_fee_rate(&token.token_id).await {
            Ok(response) => {
                let rate = response.to_rate();
                if rate >= rust_decimal::Decimal::ZERO {
                    schedule.rate = rate;
                }
            }
            Err(e) => {
                log::warn!(
                    "CLOB fee-rate fallback failed for market {}: {e}",
                    market.id
                );
            }
        }
    }

    build_loader_from_details(market, &details, token_index, data_api_client)
}

fn build_loader_from_details(
    mut market: GammaMarket,
    details: &ClobMarketResponse,
    token_index: usize,
    data_api_client: PolymarketDataApiHttpClient,
) -> PyResult<PyPolymarketDataLoader> {
    validate_market_details(details, &market.condition_id, token_index)?;

    market.clob_token_ids = serde_json::to_string(
        &details
            .tokens
            .iter()
            .map(|token| token.token_id.as_str())
            .collect::<Vec<_>>(),
    )
    .map_err(to_pyruntime_err)?;
    market.outcomes = serde_json::to_string(
        &details
            .tokens
            .iter()
            .map(|token| token.outcome.as_str())
            .collect::<Vec<_>>(),
    )
    .map_err(to_pyruntime_err)?;

    let def = parse_gamma_market(&market)
        .map_err(to_pyvalue_err)?
        .into_iter()
        .nth(token_index)
        .ok_or_else(|| to_pyvalue_err("Selected token has no instrument definition"))?;

    let mut instrument =
        match create_instrument_from_def(&def, get_atomic_clock_realtime().get_time_ns())
            .map_err(to_pyvalue_err)?
        {
            InstrumentAny::BinaryOption(instrument) => instrument,
            _ => return Err(to_pyruntime_err("Expected a BinaryOption instrument")),
        };

    // Fetched snapshots can reveal outcomes that were unknown during the historical period
    if let Some(info) = instrument.info.as_mut() {
        info.shift_remove("gamma_market");
        info.shift_remove("gamma_event");
    }

    let resolution_metadata = resolution_metadata(&market, details);
    let token_id = details.tokens[token_index].token_id.clone();
    let condition_id = market.condition_id;

    Ok(PyPolymarketDataLoader {
        instrument,
        token_id,
        condition_id,
        resolution_metadata,
        data_api_client,
    })
}

fn validate_market_details(
    details: &ClobMarketResponse,
    condition_id: &str,
    token_index: usize,
) -> PyResult<()> {
    if details.condition_id != condition_id {
        return Err(to_pyvalue_err(format!(
            "CLOB market condition ID '{}' does not match Gamma condition ID '{condition_id}'",
            details.condition_id
        )));
    }

    if details.tokens.is_empty() {
        return Err(to_pyvalue_err(format!(
            "No tokens found for market '{condition_id}'"
        )));
    }

    if token_index >= details.tokens.len() {
        return Err(to_pyvalue_err(format!(
            "Token index {token_index} out of range for market '{condition_id}' with {} tokens",
            details.tokens.len()
        )));
    }

    if details.tokens[token_index].token_id.trim().is_empty() {
        return Err(to_pyvalue_err(format!(
            "Token index {token_index} for market '{condition_id}' has an empty token ID"
        )));
    }

    if details.tokens[token_index].outcome.trim().is_empty() {
        return Err(to_pyvalue_err(format!(
            "Token index {token_index} for market '{condition_id}' has an empty outcome"
        )));
    }
    Ok(())
}

fn resolution_metadata(market: &GammaMarket, details: &ClobMarketResponse) -> Value {
    json!({
        "gamma_market": market.raw,
        "gamma_event": market.parent_event.as_ref().map(|event| &event.raw),
        "closed": details.closed,
        "closedTime": market.closed_time,
        "umaResolutionStatus": market.uma_resolution_status,
        "resolutionSource": market.resolution_source,
        "tokens": details.tokens,
    })
}

fn validate_non_empty(name: &str, value: &str) -> PyResult<()> {
    if value.trim().is_empty() {
        Err(to_pyvalue_err(format!("{name} cannot be empty")))
    } else {
        Ok(())
    }
}

fn validate_token_index(token_index: isize) -> PyResult<()> {
    if token_index < 0 {
        Err(to_pyvalue_err(format!(
            "Token index {token_index} cannot be negative"
        )))
    } else {
        Ok(())
    }
}

fn extract_filters(filters: Option<&Bound<'_, PyAny>>) -> PyResult<HashMap<String, String>> {
    filters
        .map(extract_string_map)
        .transpose()
        .map(Option::unwrap_or_default)
}

fn serialize_to_py<T: Serialize>(py: Python<'_>, value: &T) -> PyResult<Py<PyAny>> {
    let encoded = serde_json::to_string(value).map_err(to_pyruntime_err)?;
    let kwargs = PyDict::new(py);
    kwargs.set_item(
        "parse_float",
        PyModule::import(py, "decimal")?.getattr("Decimal")?,
    )?;
    Ok(PyModule::import(py, "json")?
        .call_method("loads", (encoded,), Some(&kwargs))?
        .unbind())
}

fn trades_to_py(py: Python<'_>, trades: Vec<TradeTick>) -> PyResult<Py<PyAny>> {
    let trades = trades
        .into_iter()
        .map(|trade| trade.into_py_any(py))
        .collect::<PyResult<Vec<_>>>()?;
    Ok(PyList::new(py, trades)?.into_py_any_unwrap(py))
}

#[cfg(test)]
mod tests {
    use std::sync::{
        Arc,
        atomic::{AtomicUsize, Ordering},
    };

    use pyo3::exceptions::PyValueError;
    use rstest::rstest;
    use serde_json::json;

    use super::*;

    #[rstest]
    fn test_discovery_python_decimal_precision() {
        let market: GammaMarket = serde_json::from_str(include_str!(
            "../../test_data/decimal_precision_market.json"
        ))
        .unwrap();
        Python::initialize();
        Python::attach(|py| {
            let output = serialize_to_py(py, &vec![market]).unwrap();
            let market = output.bind(py).get_item(0).unwrap();
            let decimal = py.import("decimal").unwrap().getattr("Decimal").unwrap();

            for (field, expected) in [
                ("bestBid", "0.1234567890123456789012345678"),
                ("bestAsk", "0.2345678901234567890123456789"),
                ("liquidityNum", "12345678901.123456"),
                ("volumeNum", "12345678901.123457"),
            ] {
                let actual = market.get_item(field).unwrap();
                assert!(actual.is_instance(&decimal).unwrap());
                assert_eq!(actual.str().unwrap().to_str().unwrap(), expected);
            }
            let fee = market.get_item("feeSchedule").unwrap();
            assert_eq!(
                fee.get_item("exponent")
                    .unwrap()
                    .str()
                    .unwrap()
                    .to_str()
                    .unwrap(),
                "1.234567890123456789012345678"
            );
            assert!(
                fee.get_item("takerOnly")
                    .unwrap()
                    .extract::<bool>()
                    .unwrap()
            );
        });
    }

    #[rstest]
    fn test_nested_discovery_python_decimal_precision() {
        let market: GammaMarket = serde_json::from_str(include_str!(
            "../../test_data/decimal_precision_market.json"
        ))
        .unwrap();
        let mut event: GammaEvent =
            serde_json::from_str(include_str!("../../test_data/decimal_precision_event.json"))
                .unwrap();
        event.markets = vec![market.clone()];
        let search = crate::http::models::SearchResponse {
            markets: Some(vec![market]),
            events: Some(vec![event]),
        };
        let clob_raw = include_str!("../../test_data/clob_market_response.json")
            .replace(
                "\"max_spread\": 4.5",
                "\"max_spread\": 0.1234567890123456789012345678",
            )
            .replace(
                "\"price\": 0.715",
                "\"price\": 0.2345678901234567890123456789",
            );
        let clob: ClobMarketResponse = serde_json::from_str(&clob_raw).unwrap();
        Python::initialize();
        Python::attach(|py| {
            let result = serialize_to_py(py, &search).unwrap();
            let event = result
                .bind(py)
                .get_item("events")
                .unwrap()
                .get_item(0)
                .unwrap();
            let market = event.get_item("markets").unwrap().get_item(0).unwrap();
            let details = serialize_to_py(py, &clob).unwrap();
            let decimal = py.import("decimal").unwrap().getattr("Decimal").unwrap();
            for (actual, expected) in [
                (event.get_item("volume").unwrap(), "12345678901.123457"),
                (
                    market.get_item("bestAsk").unwrap(),
                    "0.2345678901234567890123456789",
                ),
                (
                    market
                        .get_item("feeSchedule")
                        .unwrap()
                        .get_item("rate")
                        .unwrap(),
                    "0.1234567890123456789012345678",
                ),
                (
                    details
                        .bind(py)
                        .get_item("rewards")
                        .unwrap()
                        .get_item("max_spread")
                        .unwrap(),
                    "0.1234567890123456789012345678",
                ),
                (
                    details
                        .bind(py)
                        .get_item("tokens")
                        .unwrap()
                        .get_item(0)
                        .unwrap()
                        .get_item("price")
                        .unwrap(),
                    "0.2345678901234567890123456789",
                ),
            ] {
                assert!(actual.is_instance(&decimal).unwrap());
                assert_eq!(actual.str().unwrap().to_str().unwrap(), expected);
            }
            assert_eq!(
                details
                    .bind(py)
                    .get_item("seconds_delay")
                    .unwrap()
                    .extract::<i64>()
                    .unwrap(),
                1
            );
            assert!(market.get_item("closed").unwrap().is_none());
            assert_eq!(
                market.get_item("id").unwrap().extract::<String>().unwrap(),
                "precision-market"
            );
        });
    }

    fn gamma_market() -> GammaMarket {
        serde_json::from_value(json!({
            "id": "100001",
            "conditionId": "0xcondition",
            "questionID": "0xquestion",
            "clobTokenIds": "[]",
            "outcomes": "[]",
            "question": "Will the test pass?",
            "description": "Test market",
            "startDate": "2026-01-01T00:00:00Z",
            "endDate": "2026-12-31T00:00:00Z",
            "active": false,
            "closed": true,
            "closedTime": "2026-06-01T00:00:00Z",
            "umaResolutionStatus": "resolved",
            "resolutionSource": "https://example.com/result",
            "acceptingOrders": false,
            "enableOrderBook": true,
            "orderPriceMinTickSize": 0.01,
            "slug": "test-market",
            "negRisk": false,
            "feeSchedule": {
                "exponent": 2.0,
                "rate": 0.02,
                "takerOnly": true,
                "rebateRate": 0.0
            },
            "events": []
        }))
        .expect("valid Gamma market")
    }

    fn gamma_market_with_distinct_crypto_config() -> GammaMarket {
        let mut value = serde_json::to_value(gamma_market()).expect("serializable Gamma market");
        value["cryptoMarketConfig"] = json!({
            "id": "eth-15m-twap-negative-37",
            "asset": "eth",
            "duration": "15m",
            "twapEnabled": true,
            "twapLookbackSeconds": -37,
        });

        serde_json::from_value(value).expect("valid distinct crypto market config")
    }

    fn clob_market() -> ClobMarketResponse {
        serde_json::from_value(json!({
            "condition_id": "0xcondition",
            "closed": true,
            "tokens": [
                {"token_id": "yes-token", "outcome": "Yes", "winner": true},
                {"token_id": "no-token", "outcome": "No", "winner": false}
            ]
        }))
        .expect("valid CLOB market")
    }

    fn data_api() -> PolymarketDataApiHttpClient {
        PolymarketDataApiHttpClient::new(Some("http://127.0.0.1:1".to_string()), 1)
            .expect("valid test client")
    }

    #[rstest]
    #[case(0, "Yes")]
    #[case(1, "No")]
    fn build_loader_retains_parent_event_without_exposing_raw_snapshots(
        #[case] token_index: usize,
        #[case] outcome: &str,
    ) {
        let events: Vec<GammaEvent> =
            serde_json::from_str(include_str!("../../test_data/gamma_event.json")).unwrap();
        let markets = flatten_event_markets(events);
        assert_eq!(markets.len(), 2);

        for market in markets {
            let parent = market.parent_event.as_ref().unwrap();
            let expected_id = parent.id.clone();
            let expected_event = parent.raw.clone();
            let expected_market = market.raw.clone();
            let mut details = clob_market();
            details.condition_id.clone_from(&market.condition_id);
            let loader =
                build_loader_from_details(market, &details, token_index, data_api()).unwrap();
            let info = loader.instrument.info.as_ref().unwrap();

            assert_eq!(loader.instrument.event_id.unwrap().as_str(), expected_id);
            assert_eq!(loader.instrument.outcome.unwrap().as_str(), outcome);
            assert_eq!(info.get_str("event_id"), Some(expected_id.as_str()));
            assert!(!info.contains_key("gamma_market"));
            assert!(!info.contains_key("gamma_event"));
            assert_eq!(loader.resolution_metadata["gamma_market"], expected_market);
            assert_eq!(loader.resolution_metadata["gamma_event"], expected_event);
        }
    }

    #[rstest]
    fn build_loader_selects_token_and_retains_resolution_lifecycle_metadata() {
        let loader = build_loader_from_details(gamma_market(), &clob_market(), 1, data_api())
            .expect("loader should build");
        let info = loader.instrument.info.as_ref().expect("instrument info");

        assert_eq!(loader.token_id, "no-token");
        assert_eq!(loader.condition_id, "0xcondition");
        assert_eq!(
            loader.instrument.outcome.map(|value| value.to_string()),
            Some("No".to_string())
        );
        assert_eq!(loader.instrument.taker_fee.to_string(), "0.02");
        assert_eq!(loader.resolution_metadata["closed"], true);
        assert_eq!(loader.resolution_metadata["tokens"][0]["winner"], true);
        assert_eq!(
            info.get_str("resolution_source"),
            Some("https://example.com/result")
        );
        assert_eq!(info.get_str("description"), Some("Test market"));
        assert!(!info.contains_key("gamma_market"));
        assert_eq!(
            loader.resolution_metadata["gamma_market"],
            gamma_market().raw
        );
        assert!(!info.contains_key("closed"));
        assert!(!info.contains_key("closedTime"));
        assert!(!info.contains_key("umaResolutionStatus"));
        assert!(!info.contains_key("resolutionSource"));
        assert!(!info.contains_key("winner"));

        Python::initialize();
        Python::attach(|py| {
            let py_loader = Py::new(py, loader).expect("Python loader");
            assert_eq!(
                py_loader
                    .getattr(py, "token_id")
                    .expect("token ID getter")
                    .extract::<String>(py)
                    .expect("token ID string"),
                "no-token",
            );
            assert_eq!(
                py_loader
                    .getattr(py, "condition_id")
                    .expect("condition ID getter")
                    .extract::<String>(py)
                    .expect("condition ID string"),
                "0xcondition",
            );
            let metadata = py_loader
                .getattr(py, "resolution_metadata")
                .expect("resolution metadata getter");
            assert!(
                metadata
                    .bind(py)
                    .get_item("closed")
                    .expect("closed metadata")
                    .extract::<bool>()
                    .expect("closed bool"),
            );
        });
    }

    #[rstest]
    fn build_loader_preserves_distinct_crypto_config_in_rust_and_python_instrument_info() {
        let loader = build_loader_from_details(
            gamma_market_with_distinct_crypto_config(),
            &clob_market(),
            0,
            data_api(),
        )
        .expect("loader should build");
        let info = loader.instrument.info.as_ref().expect("instrument info");
        let expected = json!({
            "id": "eth-15m-twap-negative-37",
            "asset": "eth",
            "duration": "15m",
            "twapEnabled": true,
            "twapLookbackSeconds": -37,
        });

        assert_eq!(info.get("crypto_market_config"), Some(&expected));

        Python::initialize();
        Python::attach(|py| {
            let py_loader = Py::new(py, loader).expect("Python loader");
            let instrument = py_loader
                .getattr(py, "instrument")
                .expect("instrument getter");
            let info = instrument
                .getattr(py, "info")
                .expect("instrument info getter");
            let config = info
                .bind(py)
                .get_item("crypto_market_config")
                .expect("crypto market config");

            assert_eq!(
                config
                    .get_item("id")
                    .expect("config ID")
                    .extract::<String>()
                    .expect("config ID string"),
                "eth-15m-twap-negative-37",
            );
            assert_eq!(
                config
                    .get_item("asset")
                    .expect("config asset")
                    .extract::<String>()
                    .expect("config asset string"),
                "eth",
            );
            assert_eq!(
                config
                    .get_item("duration")
                    .expect("config duration")
                    .extract::<String>()
                    .expect("config duration string"),
                "15m",
            );
            assert!(
                config
                    .get_item("twapEnabled")
                    .expect("TWAP enabled")
                    .extract::<bool>()
                    .expect("TWAP enabled bool"),
            );
            assert_eq!(
                config
                    .get_item("twapLookbackSeconds")
                    .expect("TWAP lookback")
                    .extract::<i64>()
                    .expect("TWAP lookback integer"),
                -37,
            );
        });
    }

    #[rstest]
    #[case(-1, "cannot be negative")]
    fn validate_token_index_rejects_negative_values(#[case] index: isize, #[case] message: &str) {
        let error = validate_token_index(index).expect_err("index should be rejected");

        Python::initialize();
        Python::attach(|py| assert!(error.is_instance_of::<PyValueError>(py)));
        assert!(error.to_string().contains(message));
    }

    #[rstest]
    fn build_loader_rejects_out_of_range_index() {
        Python::initialize();

        let error = build_loader_from_details(gamma_market(), &clob_market(), 2, data_api())
            .expect_err("index should be rejected");

        assert!(error.to_string().contains("Token index 2 out of range"));
    }

    #[rstest]
    fn build_loader_rejects_empty_token_list() {
        Python::initialize();

        let mut details = clob_market();
        details.tokens.clear();

        let error = build_loader_from_details(gamma_market(), &details, 0, data_api())
            .expect_err("empty tokens should be rejected");

        assert!(error.to_string().contains("No tokens found"));
    }

    #[rstest]
    fn build_loader_rejects_transient_empty_token_id() {
        Python::initialize();

        let mut details = clob_market();
        details.tokens[0].token_id.clear();

        let error = build_loader_from_details(gamma_market(), &details, 0, data_api())
            .expect_err("empty token ID should be rejected");

        assert!(error.to_string().contains("has an empty token ID"));
    }

    #[rstest]
    fn build_loader_rejects_malformed_non_binary_token_payload() {
        Python::initialize();

        let mut details = clob_market();
        details.tokens.truncate(1);

        let error = build_loader_from_details(gamma_market(), &details, 0, data_api())
            .expect_err("non-binary tokens should be rejected");

        assert!(error.to_string().contains("Expected 2 token IDs"));
    }

    #[rstest]
    fn build_loader_rejects_mismatched_condition_id() {
        Python::initialize();

        let mut details = clob_market();
        details.condition_id = "0xdifferent".to_string();

        let error = build_loader_from_details(gamma_market(), &details, 0, data_api())
            .expect_err("condition mismatch should be rejected");

        assert!(
            error
                .to_string()
                .contains("does not match Gamma condition ID")
        );
    }

    #[tokio::test]
    async fn build_loader_recovers_zero_taker_rate_from_clob_fee_rate() {
        Python::initialize();

        let calls = Arc::new(AtomicUsize::new(0));
        let asserted = Arc::clone(&calls);
        let details = serde_json::to_string(&clob_market()).unwrap();

        let router = axum::Router::new()
            .route(
                "/markets/0xcondition",
                axum::routing::get(move || {
                    let details = details.clone();

                    async move { details }
                }),
            )
            .route(
                "/fee-rate",
                axum::routing::get(move || {
                    let calls = Arc::clone(&calls);

                    async move {
                        calls.fetch_add(1, Ordering::SeqCst);
                        r#"{"base_fee":700}"#.to_string()
                    }
                }),
            );

        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let address = listener.local_addr().unwrap();
        let server = tokio::spawn(async move { axum::serve(listener, router).await.unwrap() });

        let mut market = gamma_market();
        market.fees_enabled = Some(true);
        market.fee_type = Some("crypto_fees".to_string());
        market.fee_schedule = Some(crate::http::models::FeeSchedule {
            exponent: rust_decimal::Decimal::ONE,
            rate: rust_decimal::Decimal::ZERO,
            taker_only: true,
            rebate_rate: rust_decimal::Decimal::ZERO,
        });

        let gamma = PolymarketGammaHttpClient::new(
            Some("http://127.0.0.1:1".to_string()),
            1,
            RetryConfig::default(),
        )
        .expect("valid test client");
        let clob = PolymarketClobPublicClient::new(Some(format!("http://{address}")), 5).unwrap();

        let loader = build_loader(market, 0, &gamma, &clob, data_api())
            .await
            .expect("loader should build");
        server.abort();

        assert_eq!(asserted.load(Ordering::SeqCst), 1);
        assert_eq!(loader.token_id, "yes-token");

        let info = loader.instrument.info.as_ref().unwrap();
        let schedule: crate::http::models::FeeSchedule =
            serde_json::from_value(info.get("fee_schedule").unwrap().clone()).unwrap();
        assert_eq!(schedule.rate, rust_decimal::Decimal::new(7, 2));
        assert_eq!(schedule.rebate_rate, rust_decimal::Decimal::new(2, 1));
    }
}