Skip to main content

nautilus_polymarket/python/
loader.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Rust-backed Python discovery and historical data facade.
17
18use std::collections::HashMap;
19
20use indexmap::IndexMap;
21use jiff::Timestamp;
22use nautilus_core::{
23    Params,
24    datetime::datetime_to_unix_nanos,
25    python::{
26        IntoPyObjectNautilusExt, params::value_to_pyobject, to_pyruntime_err, to_pyvalue_err,
27    },
28    time::get_atomic_clock_realtime,
29};
30use nautilus_model::{
31    data::TradeTick,
32    instruments::{BinaryOption, InstrumentAny},
33};
34use nautilus_network::retry::RetryConfig;
35use pyo3::{
36    conversion::IntoPyObjectExt,
37    prelude::*,
38    types::{PyDict, PyList},
39};
40use serde::Serialize;
41use serde_json::{Value, json};
42
43use super::extract_string_map;
44use crate::{
45    common::parse::validate_data_market_version,
46    http::{
47        clob::PolymarketClobPublicClient,
48        data_api::PolymarketDataApiHttpClient,
49        error::Error as PolymarketHttpError,
50        gamma::{PolymarketGammaHttpClient, flatten_event_markets},
51        models::{ClobMarketResponse, GammaEvent, GammaMarket},
52        parse::{create_instrument_from_def, enrich_market_fee_schedule, parse_gamma_market},
53        query::{GetGammaMarketsParams, GetSearchParams},
54    },
55    providers::{build_gamma_event_params_from_hashmap, build_gamma_params_from_hashmap},
56};
57
58#[pyclass(name = "PolymarketDataLoader")]
59#[pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.adapters.polymarket")]
60#[derive(Clone, Debug)]
61pub struct PyPolymarketDataLoader {
62    instrument: BinaryOption,
63    token_id: String,
64    condition_id: String,
65    resolution_metadata: Value,
66    data_api_client: PolymarketDataApiHttpClient,
67}
68
69#[pymethods]
70#[pyo3_stub_gen::derive::gen_stub_pymethods]
71impl PyPolymarketDataLoader {
72    /// Queries one Gamma market by slug.
73    #[staticmethod]
74    #[pyo3(signature = (slug, base_url_gamma=None, timeout_secs=10))]
75    fn query_market_by_slug<'py>(
76        py: Python<'py>,
77        slug: String,
78        base_url_gamma: Option<String>,
79        timeout_secs: u64,
80    ) -> PyResult<Bound<'py, PyAny>> {
81        validate_non_empty("slug", &slug)?;
82
83        pyo3_async_runtimes::tokio::future_into_py(py, async move {
84            let client = gamma_client(base_url_gamma, timeout_secs)?;
85            let market = request_market_by_slug(&client, &slug).await?;
86            Python::attach(|py| serialize_to_py(py, &market))
87        })
88    }
89
90    /// Queries public CLOB market details by condition ID.
91    #[staticmethod]
92    #[pyo3(signature = (condition_id, base_url_http=None, timeout_secs=10))]
93    fn query_market_details<'py>(
94        py: Python<'py>,
95        condition_id: String,
96        base_url_http: Option<String>,
97        timeout_secs: u64,
98    ) -> PyResult<Bound<'py, PyAny>> {
99        validate_non_empty("condition_id", &condition_id)?;
100
101        pyo3_async_runtimes::tokio::future_into_py(py, async move {
102            let client = clob_client(base_url_http, timeout_secs)?;
103            let market = client
104                .get_market(&condition_id)
105                .await
106                .map_err(to_pyruntime_err)?;
107            Python::attach(|py| serialize_to_py(py, &market))
108        })
109    }
110
111    /// Queries one Gamma event by slug.
112    #[staticmethod]
113    #[pyo3(signature = (slug, base_url_gamma=None, timeout_secs=10))]
114    fn query_event_by_slug<'py>(
115        py: Python<'py>,
116        slug: String,
117        base_url_gamma: Option<String>,
118        timeout_secs: u64,
119    ) -> PyResult<Bound<'py, PyAny>> {
120        validate_non_empty("slug", &slug)?;
121
122        pyo3_async_runtimes::tokio::future_into_py(py, async move {
123            let client = gamma_client(base_url_gamma, timeout_secs)?;
124            let event = request_event_by_slug(&client, &slug).await?;
125            Python::attach(|py| serialize_to_py(py, &event))
126        })
127    }
128
129    /// Lists Gamma markets with validated filters and keyset pagination.
130    #[staticmethod]
131    #[pyo3(signature = (filters=None, base_url_gamma=None, timeout_secs=10))]
132    fn query_markets<'py>(
133        py: Python<'py>,
134        filters: Option<&Bound<'py, PyAny>>,
135        base_url_gamma: Option<String>,
136        timeout_secs: u64,
137    ) -> PyResult<Bound<'py, PyAny>> {
138        let filters = extract_filters(filters)?;
139        let params = build_gamma_params_from_hashmap(&filters).map_err(to_pyvalue_err)?;
140
141        pyo3_async_runtimes::tokio::future_into_py(py, async move {
142            let client = gamma_client(base_url_gamma, timeout_secs)?;
143            let markets = client
144                .request_markets_by_params(params)
145                .await
146                .map_err(to_pyruntime_err)?;
147            Python::attach(|py| serialize_to_py(py, &markets))
148        })
149    }
150
151    /// Lists Gamma events with validated filters and keyset pagination.
152    #[staticmethod]
153    #[pyo3(signature = (filters=None, base_url_gamma=None, timeout_secs=10))]
154    fn query_events<'py>(
155        py: Python<'py>,
156        filters: Option<&Bound<'py, PyAny>>,
157        base_url_gamma: Option<String>,
158        timeout_secs: u64,
159    ) -> PyResult<Bound<'py, PyAny>> {
160        let filters = extract_filters(filters)?;
161        let params = build_gamma_event_params_from_hashmap(&filters).map_err(to_pyvalue_err)?;
162
163        pyo3_async_runtimes::tokio::future_into_py(py, async move {
164            let client = gamma_client(base_url_gamma, timeout_secs)?;
165            let events = client
166                .request_events_by_params(params)
167                .await
168                .map_err(to_pyruntime_err)?;
169            Python::attach(|py| serialize_to_py(py, &events))
170        })
171    }
172
173    /// Lists Gamma tags.
174    #[staticmethod]
175    #[pyo3(signature = (base_url_gamma=None, timeout_secs=10))]
176    fn query_tags<'py>(
177        py: Python<'py>,
178        base_url_gamma: Option<String>,
179        timeout_secs: u64,
180    ) -> PyResult<Bound<'py, PyAny>> {
181        pyo3_async_runtimes::tokio::future_into_py(py, async move {
182            let client = gamma_client(base_url_gamma, timeout_secs)?;
183            let tags = client.request_tags().await.map_err(to_pyruntime_err)?;
184            Python::attach(|py| serialize_to_py(py, &tags))
185        })
186    }
187
188    /// Searches Gamma markets and events.
189    #[staticmethod]
190    #[pyo3(signature = (
191        query,
192        events_status=None,
193        events_tag=None,
194        sort=None,
195        ascending=None,
196        limit_per_type=None,
197        page=None,
198        keep_closed_markets=None,
199        base_url_gamma=None,
200        timeout_secs=10,
201    ))]
202    #[expect(clippy::too_many_arguments)]
203    fn query_search<'py>(
204        py: Python<'py>,
205        query: String,
206        events_status: Option<String>,
207        events_tag: Option<String>,
208        sort: Option<String>,
209        ascending: Option<bool>,
210        limit_per_type: Option<u32>,
211        page: Option<u32>,
212        keep_closed_markets: Option<bool>,
213        base_url_gamma: Option<String>,
214        timeout_secs: u64,
215    ) -> PyResult<Bound<'py, PyAny>> {
216        validate_non_empty("query", &query)?;
217
218        if limit_per_type == Some(0) {
219            return Err(to_pyvalue_err("limit_per_type must be greater than zero"));
220        }
221        let params = GetSearchParams {
222            q: Some(query),
223            events_status,
224            events_tag,
225            sort,
226            ascending,
227            limit_per_type,
228            page,
229            keep_closed_markets,
230        };
231
232        pyo3_async_runtimes::tokio::future_into_py(py, async move {
233            let client = gamma_client(base_url_gamma, timeout_secs)?;
234            let response = client
235                .inner()
236                .get_public_search(params)
237                .await
238                .map_err(to_pyruntime_err)?;
239            Python::attach(|py| serialize_to_py(py, &response))
240        })
241    }
242
243    /// Creates one loader from a Gamma market slug.
244    #[staticmethod]
245    #[pyo3(signature = (
246        slug,
247        token_index=0,
248        base_url_http=None,
249        base_url_gamma=None,
250        base_url_data_api=None,
251        timeout_secs=10,
252    ))]
253    fn from_market_slug<'py>(
254        py: Python<'py>,
255        slug: String,
256        token_index: isize,
257        base_url_http: Option<String>,
258        base_url_gamma: Option<String>,
259        base_url_data_api: Option<String>,
260        timeout_secs: u64,
261    ) -> PyResult<Bound<'py, PyAny>> {
262        validate_non_empty("slug", &slug)?;
263        validate_token_index(token_index)?;
264
265        pyo3_async_runtimes::tokio::future_into_py(py, async move {
266            let gamma = gamma_client(base_url_gamma, timeout_secs)?;
267            let clob = clob_client(base_url_http, timeout_secs)?;
268            let data_api = data_api_client(base_url_data_api, timeout_secs)?;
269            let market = request_market_by_slug(&gamma, &slug).await?;
270            let loader =
271                build_loader(market, token_index as usize, &gamma, &clob, data_api).await?;
272            Python::attach(|py| Py::new(py, loader).map(Py::into_any))
273        })
274    }
275
276    /// Creates one loader for every market in a Gamma event slug.
277    #[staticmethod]
278    #[pyo3(signature = (
279        slug,
280        token_index=0,
281        base_url_http=None,
282        base_url_gamma=None,
283        base_url_data_api=None,
284        timeout_secs=10,
285    ))]
286    fn from_event_slug<'py>(
287        py: Python<'py>,
288        slug: String,
289        token_index: isize,
290        base_url_http: Option<String>,
291        base_url_gamma: Option<String>,
292        base_url_data_api: Option<String>,
293        timeout_secs: u64,
294    ) -> PyResult<Bound<'py, PyAny>> {
295        validate_non_empty("slug", &slug)?;
296        validate_token_index(token_index)?;
297
298        pyo3_async_runtimes::tokio::future_into_py(py, async move {
299            let gamma = gamma_client(base_url_gamma, timeout_secs)?;
300            let clob = clob_client(base_url_http, timeout_secs)?;
301            let data_api = data_api_client(base_url_data_api, timeout_secs)?;
302            let event = request_event_by_slug(&gamma, &slug).await?;
303            if event.markets.is_empty() {
304                return Err(to_pyvalue_err(format!(
305                    "No markets found in event '{slug}'"
306                )));
307            }
308
309            let mut loaders = Vec::with_capacity(event.markets.len());
310            for market in flatten_event_markets(vec![event]) {
311                loaders.push(
312                    build_loader(
313                        market,
314                        token_index as usize,
315                        &gamma,
316                        &clob,
317                        data_api.clone(),
318                    )
319                    .await?,
320                );
321            }
322
323            Python::attach(|py| {
324                let loaders = loaders
325                    .into_iter()
326                    .map(|loader| Py::new(py, loader))
327                    .collect::<PyResult<Vec<_>>>()?;
328                Ok(PyList::new(py, loaders)?.into_py_any_unwrap(py))
329            })
330        })
331    }
332
333    /// Returns the normalized binary option instrument.
334    #[getter]
335    fn instrument(&self) -> BinaryOption {
336        self.instrument.clone()
337    }
338
339    /// Returns the selected outcome asset ID.
340    #[getter]
341    fn token_id(&self) -> &str {
342        &self.token_id
343    }
344
345    /// Returns the on-chain condition ID.
346    #[getter]
347    fn condition_id(&self) -> &str {
348        &self.condition_id
349    }
350
351    /// Returns resolution lifecycle metadata retained separately from `instrument.info`.
352    ///
353    /// Shared market identity such as `resolutionSource` is also available from
354    /// `instrument.info["resolution_source"]`.
355    #[getter]
356    fn resolution_metadata(&self, py: Python<'_>) -> PyResult<Py<PyAny>> {
357        value_to_pyobject(py, &self.resolution_metadata)
358    }
359
360    /// Loads historical trades from the Rust Data API client.
361    #[pyo3(signature = (start=None, end=None, limit=None))]
362    fn load_trades<'py>(
363        &self,
364        py: Python<'py>,
365        start: Option<Timestamp>,
366        end: Option<Timestamp>,
367        limit: Option<u32>,
368    ) -> PyResult<Bound<'py, PyAny>> {
369        if let (Some(start), Some(end)) = (start, end)
370            && start > end
371        {
372            return Err(to_pyvalue_err("start must not be later than end"));
373        }
374
375        if limit == Some(0) {
376            return Err(to_pyvalue_err("limit must be greater than zero"));
377        }
378
379        let client = self.data_api_client.clone();
380        let instrument = self.instrument.clone();
381        let condition_id = self.condition_id.clone();
382        let token_id = self.token_id.clone();
383        let start = datetime_to_unix_nanos(start);
384        let end = datetime_to_unix_nanos(end);
385
386        pyo3_async_runtimes::tokio::future_into_py(py, async move {
387            let trades = client
388                .request_trade_ticks(
389                    instrument.id,
390                    &condition_id,
391                    &token_id,
392                    instrument.price_precision,
393                    instrument.size_precision,
394                    start,
395                    end,
396                    limit,
397                )
398                .await
399                .map_err(to_pyruntime_err)?;
400            Python::attach(|py| trades_to_py(py, trades))
401        })
402    }
403}
404
405fn gamma_client(
406    base_url: Option<String>,
407    timeout_secs: u64,
408) -> PyResult<PolymarketGammaHttpClient> {
409    PolymarketGammaHttpClient::new(base_url, timeout_secs, RetryConfig::default())
410        .map_err(to_pyruntime_err)
411}
412
413fn clob_client(
414    base_url: Option<String>,
415    timeout_secs: u64,
416) -> PyResult<PolymarketClobPublicClient> {
417    PolymarketClobPublicClient::new(base_url, timeout_secs).map_err(to_pyruntime_err)
418}
419
420fn data_api_client(
421    base_url: Option<String>,
422    timeout_secs: u64,
423) -> PyResult<PolymarketDataApiHttpClient> {
424    PolymarketDataApiHttpClient::new(base_url, timeout_secs).map_err(to_pyruntime_err)
425}
426
427async fn request_market_by_slug(
428    client: &PolymarketGammaHttpClient,
429    slug: &str,
430) -> PyResult<GammaMarket> {
431    match client.inner().get_gamma_market_by_slug(slug).await {
432        Ok(market) => Ok(market),
433        Err(PolymarketHttpError::Http { status: 404, .. }) => Err(to_pyvalue_err(format!(
434            "Market with slug '{slug}' not found"
435        ))),
436        Err(e) => Err(to_pyruntime_err(e)),
437    }
438}
439
440async fn request_event_by_slug(
441    client: &PolymarketGammaHttpClient,
442    slug: &str,
443) -> PyResult<GammaEvent> {
444    client
445        .inner()
446        .get_gamma_events_by_slug(slug)
447        .await
448        .map_err(to_pyruntime_err)?
449        .into_iter()
450        .next()
451        .ok_or_else(|| to_pyvalue_err(format!("Event with slug '{slug}' not found")))
452}
453
454async fn build_loader(
455    mut market: GammaMarket,
456    token_index: usize,
457    gamma: &PolymarketGammaHttpClient,
458    clob: &PolymarketClobPublicClient,
459    data_api_client: PolymarketDataApiHttpClient,
460) -> PyResult<PyPolymarketDataLoader> {
461    validate_data_market_version(market.version.as_deref()).map_err(to_pyvalue_err)?;
462    if market.condition_id.trim().is_empty() {
463        return Err(to_pyvalue_err("Gamma market has an empty condition ID"));
464    }
465
466    if market.fee_schedule.is_none() {
467        market.fee_schedule = gamma
468            .request_markets_by_params(GetGammaMarketsParams {
469                condition_ids: Some(vec![market.condition_id.clone()]),
470                max_markets: Some(1),
471                ..Default::default()
472            })
473            .await
474            .map_err(to_pyruntime_err)?
475            .into_iter()
476            .find(|candidate| candidate.condition_id == market.condition_id)
477            .and_then(|candidate| candidate.fee_schedule);
478    }
479
480    enrich_market_fee_schedule(&mut market);
481
482    let details = clob
483        .get_market(&market.condition_id)
484        .await
485        .map_err(to_pyruntime_err)?;
486
487    build_loader_from_details(market, &details, token_index, data_api_client)
488}
489
490fn build_loader_from_details(
491    market: GammaMarket,
492    details: &ClobMarketResponse,
493    token_index: usize,
494    data_api_client: PolymarketDataApiHttpClient,
495) -> PyResult<PyPolymarketDataLoader> {
496    validate_data_market_version(market.version.as_deref()).map_err(to_pyvalue_err)?;
497    validate_data_market_version(details.version.as_deref()).map_err(to_pyvalue_err)?;
498    validate_market_details(details, &market.condition_id)?;
499
500    if market.version != details.version {
501        return Err(to_pyvalue_err(
502            "CLOB market protocol does not match Gamma market protocol",
503        ));
504    }
505
506    let defs = parse_gamma_market(&market).map_err(to_pyvalue_err)?;
507
508    let def = defs.get(token_index).ok_or_else(|| {
509        to_pyvalue_err(format!(
510            "Token index {token_index} out of range for market '{}' with {} tokens",
511            market.condition_id,
512            defs.len(),
513        ))
514    })?;
515
516    if defs.len() != details.tokens.len()
517        || defs.iter().any(|def| {
518            !details.tokens.iter().any(|token| {
519                def.token_id.as_str() == token.token_id && def.outcome.as_str() == token.outcome
520            })
521        })
522    {
523        return Err(to_pyvalue_err(
524            "CLOB outcome IDs or labels do not match Gamma market outcomes",
525        ));
526    }
527
528    let mut instrument =
529        match create_instrument_from_def(def, get_atomic_clock_realtime().get_time_ns())
530            .map_err(to_pyvalue_err)?
531        {
532            InstrumentAny::BinaryOption(instrument) => instrument,
533            _ => return Err(to_pyruntime_err("Expected a BinaryOption instrument")),
534        };
535
536    // Fetched snapshots can reveal outcomes that were unknown during the historical period
537    if let Some(info) = instrument.info.as_ref() {
538        let mut info = IndexMap::clone(info);
539        info.shift_remove("gamma_market");
540        info.shift_remove("gamma_event");
541        instrument.info = Some(Params::new(info));
542    }
543
544    let resolution_metadata = resolution_metadata(&market, details);
545    let token_id = def.token_id.to_string();
546    let condition_id = market.condition_id;
547
548    Ok(PyPolymarketDataLoader {
549        instrument,
550        token_id,
551        condition_id,
552        resolution_metadata,
553        data_api_client,
554    })
555}
556
557fn validate_market_details(details: &ClobMarketResponse, condition_id: &str) -> PyResult<()> {
558    if details.condition_id != condition_id {
559        return Err(to_pyvalue_err(format!(
560            "CLOB market condition ID '{}' does not match Gamma condition ID '{condition_id}'",
561            details.condition_id
562        )));
563    }
564
565    if details.tokens.is_empty() {
566        return Err(to_pyvalue_err(format!(
567            "No tokens found for market '{condition_id}'"
568        )));
569    }
570
571    for (index, token) in details.tokens.iter().enumerate() {
572        if token.token_id.trim().is_empty() {
573            return Err(to_pyvalue_err(format!(
574                "CLOB token at index {index} for market '{condition_id}' has an empty token ID"
575            )));
576        }
577
578        if token.outcome.trim().is_empty() {
579            return Err(to_pyvalue_err(format!(
580                "CLOB token at index {index} for market '{condition_id}' has an empty outcome"
581            )));
582        }
583    }
584    Ok(())
585}
586
587fn resolution_metadata(market: &GammaMarket, details: &ClobMarketResponse) -> Value {
588    json!({
589        "gamma_market": market.raw,
590        "gamma_event": market.parent_event.as_ref().map(|event| &event.raw),
591        "closed": details.closed,
592        "closedTime": market.closed_time,
593        "umaResolutionStatus": market.uma_resolution_status,
594        "resolutionStatus": market.resolution_status,
595        "version": market.version,
596        "resolutionSource": market.resolution_source,
597        "tokens": details.tokens,
598    })
599}
600
601fn validate_non_empty(name: &str, value: &str) -> PyResult<()> {
602    if value.trim().is_empty() {
603        Err(to_pyvalue_err(format!("{name} cannot be empty")))
604    } else {
605        Ok(())
606    }
607}
608
609fn validate_token_index(token_index: isize) -> PyResult<()> {
610    if token_index < 0 {
611        Err(to_pyvalue_err(format!(
612            "Token index {token_index} cannot be negative"
613        )))
614    } else {
615        Ok(())
616    }
617}
618
619fn extract_filters(filters: Option<&Bound<'_, PyAny>>) -> PyResult<HashMap<String, String>> {
620    filters
621        .map(extract_string_map)
622        .transpose()
623        .map(Option::unwrap_or_default)
624}
625
626fn serialize_to_py<T: Serialize>(py: Python<'_>, value: &T) -> PyResult<Py<PyAny>> {
627    let encoded = serde_json::to_string(value).map_err(to_pyruntime_err)?;
628    let kwargs = PyDict::new(py);
629    kwargs.set_item(
630        "parse_float",
631        PyModule::import(py, "decimal")?.getattr("Decimal")?,
632    )?;
633    Ok(PyModule::import(py, "json")?
634        .call_method("loads", (encoded,), Some(&kwargs))?
635        .unbind())
636}
637
638fn trades_to_py(py: Python<'_>, trades: Vec<TradeTick>) -> PyResult<Py<PyAny>> {
639    let trades = trades
640        .into_iter()
641        .map(|trade| trade.into_py_any(py))
642        .collect::<PyResult<Vec<_>>>()?;
643    Ok(PyList::new(py, trades)?.into_py_any_unwrap(py))
644}
645
646#[cfg(test)]
647mod tests {
648    use pyo3::exceptions::PyValueError;
649    use rstest::rstest;
650    use serde_json::json;
651
652    use super::*;
653
654    #[rstest]
655    fn test_discovery_python_decimal_precision() {
656        let market: GammaMarket = serde_json::from_str(include_str!(
657            "../../test_data/decimal_precision_market.json"
658        ))
659        .unwrap();
660        Python::initialize();
661        Python::attach(|py| {
662            let output = serialize_to_py(py, &vec![market]).unwrap();
663            let market = output.bind(py).get_item(0).unwrap();
664            let decimal = py.import("decimal").unwrap().getattr("Decimal").unwrap();
665
666            for (field, expected) in [
667                ("bestBid", "0.1234567890123456789012345678"),
668                ("bestAsk", "0.2345678901234567890123456789"),
669                ("liquidityNum", "12345678901.123456"),
670                ("volumeNum", "12345678901.123457"),
671            ] {
672                let actual = market.get_item(field).unwrap();
673                assert!(actual.is_instance(&decimal).unwrap());
674                assert_eq!(actual.str().unwrap().to_str().unwrap(), expected);
675            }
676            let fee = market.get_item("feeSchedule").unwrap();
677            assert_eq!(
678                fee.get_item("exponent")
679                    .unwrap()
680                    .str()
681                    .unwrap()
682                    .to_str()
683                    .unwrap(),
684                "1.234567890123456789012345678"
685            );
686            assert!(
687                fee.get_item("takerOnly")
688                    .unwrap()
689                    .extract::<bool>()
690                    .unwrap()
691            );
692        });
693    }
694
695    #[rstest]
696    fn test_nested_discovery_python_decimal_precision() {
697        let market: GammaMarket = serde_json::from_str(include_str!(
698            "../../test_data/decimal_precision_market.json"
699        ))
700        .unwrap();
701        let mut event: GammaEvent =
702            serde_json::from_str(include_str!("../../test_data/decimal_precision_event.json"))
703                .unwrap();
704        event.markets = vec![market.clone()];
705        let search = crate::http::models::SearchResponse {
706            markets: Some(vec![market]),
707            events: Some(vec![event]),
708        };
709        let clob_raw = include_str!("../../test_data/clob_market_response.json")
710            .replace(
711                "\"max_spread\": 4.5",
712                "\"max_spread\": 0.1234567890123456789012345678",
713            )
714            .replace(
715                "\"price\": 0.715",
716                "\"price\": 0.2345678901234567890123456789",
717            );
718        let clob: ClobMarketResponse = serde_json::from_str(&clob_raw).unwrap();
719        Python::initialize();
720        Python::attach(|py| {
721            let result = serialize_to_py(py, &search).unwrap();
722            let event = result
723                .bind(py)
724                .get_item("events")
725                .unwrap()
726                .get_item(0)
727                .unwrap();
728            let market = event.get_item("markets").unwrap().get_item(0).unwrap();
729            let details = serialize_to_py(py, &clob).unwrap();
730            let decimal = py.import("decimal").unwrap().getattr("Decimal").unwrap();
731            for (actual, expected) in [
732                (event.get_item("volume").unwrap(), "12345678901.123457"),
733                (
734                    market.get_item("bestAsk").unwrap(),
735                    "0.2345678901234567890123456789",
736                ),
737                (
738                    market
739                        .get_item("feeSchedule")
740                        .unwrap()
741                        .get_item("rate")
742                        .unwrap(),
743                    "0.1234567890123456789012345678",
744                ),
745                (
746                    details
747                        .bind(py)
748                        .get_item("rewards")
749                        .unwrap()
750                        .get_item("max_spread")
751                        .unwrap(),
752                    "0.1234567890123456789012345678",
753                ),
754                (
755                    details
756                        .bind(py)
757                        .get_item("tokens")
758                        .unwrap()
759                        .get_item(0)
760                        .unwrap()
761                        .get_item("price")
762                        .unwrap(),
763                    "0.2345678901234567890123456789",
764                ),
765            ] {
766                assert!(actual.is_instance(&decimal).unwrap());
767                assert_eq!(actual.str().unwrap().to_str().unwrap(), expected);
768            }
769            assert_eq!(
770                details
771                    .bind(py)
772                    .get_item("seconds_delay")
773                    .unwrap()
774                    .extract::<i64>()
775                    .unwrap(),
776                1
777            );
778            assert!(market.get_item("closed").unwrap().is_none());
779            assert_eq!(
780                market.get_item("id").unwrap().extract::<String>().unwrap(),
781                "precision-market"
782            );
783        });
784    }
785
786    fn gamma_market() -> GammaMarket {
787        serde_json::from_value(json!({
788            "id": "100001",
789            "conditionId": "0xcondition",
790            "questionID": "0xquestion",
791            "version": "v1",
792            "clobTokenIds": "[\"101\",\"202\"]",
793            "outcomes": "[\"Yes\",\"No\"]",
794            "question": "Will the test pass?",
795            "description": "Test market",
796            "startDate": "2026-01-01T00:00:00Z",
797            "endDate": "2026-12-31T00:00:00Z",
798            "active": false,
799            "closed": true,
800            "closedTime": "2026-06-01T00:00:00Z",
801            "umaResolutionStatus": "resolved",
802            "resolutionSource": "https://example.com/result",
803            "acceptingOrders": false,
804            "enableOrderBook": true,
805            "orderPriceMinTickSize": 0.01,
806            "slug": "test-market",
807            "negRisk": false,
808            "feeSchedule": {
809                "exponent": 2.0,
810                "rate": 0.02,
811                "takerOnly": true,
812                "rebateRate": 0.0
813            },
814            "events": []
815        }))
816        .expect("valid Gamma market")
817    }
818
819    fn gamma_market_with_distinct_crypto_config() -> GammaMarket {
820        let mut value = serde_json::to_value(gamma_market()).expect("serializable Gamma market");
821        value["cryptoMarketConfig"] = json!({
822            "id": "eth-15m-twap-negative-37",
823            "asset": "eth",
824            "duration": "15m",
825            "twapEnabled": true,
826            "twapLookbackSeconds": -37,
827        });
828
829        serde_json::from_value(value).expect("valid distinct crypto market config")
830    }
831
832    fn clob_market() -> ClobMarketResponse {
833        serde_json::from_value(json!({
834            "version": "v1",
835            "condition_id": "0xcondition",
836            "closed": true,
837            "tokens": [
838                {"token_id": "101", "outcome": "Yes", "winner": true},
839                {"token_id": "202", "outcome": "No", "winner": false}
840            ]
841        }))
842        .expect("valid CLOB market")
843    }
844
845    fn data_api() -> PolymarketDataApiHttpClient {
846        PolymarketDataApiHttpClient::new(Some("http://127.0.0.1:1".to_string()), 1)
847            .expect("valid test client")
848    }
849
850    #[rstest]
851    #[case(0, "Yes")]
852    #[case(1, "No")]
853    fn build_loader_retains_parent_event_without_exposing_raw_snapshots(
854        #[case] token_index: usize,
855        #[case] outcome: &str,
856    ) {
857        let events: Vec<GammaEvent> =
858            serde_json::from_str(include_str!("../../test_data/gamma_event.json")).unwrap();
859        let markets = flatten_event_markets(events);
860        assert_eq!(markets.len(), 2);
861
862        for market in markets {
863            let parent = market.parent_event.as_ref().unwrap();
864            let expected_id = parent.id.clone();
865            let expected_event = parent.raw.clone();
866            let expected_market = market.raw.clone();
867            let mut details = clob_market();
868            details.condition_id.clone_from(&market.condition_id);
869            for (token, def) in details
870                .tokens
871                .iter_mut()
872                .zip(parse_gamma_market(&market).unwrap())
873            {
874                token.token_id = def.token_id.to_string();
875                token.outcome = def.outcome.to_string();
876            }
877
878            let loader =
879                build_loader_from_details(market, &details, token_index, data_api()).unwrap();
880            let info = loader.instrument.info.as_ref().unwrap();
881
882            assert_eq!(loader.instrument.event_id.unwrap().as_str(), expected_id);
883            assert_eq!(loader.instrument.outcome.unwrap().as_str(), outcome);
884            assert_eq!(info.get_str("event_id"), Some(expected_id.as_str()));
885            assert!(!info.contains_key("gamma_market"));
886            assert!(!info.contains_key("gamma_event"));
887            assert_eq!(loader.resolution_metadata["gamma_market"], expected_market);
888            assert_eq!(loader.resolution_metadata["gamma_event"], expected_event);
889        }
890    }
891
892    #[rstest]
893    fn build_loader_selects_token_and_retains_resolution_lifecycle_metadata() {
894        let loader = build_loader_from_details(gamma_market(), &clob_market(), 1, data_api())
895            .expect("loader should build");
896        let info = loader.instrument.info.as_ref().expect("instrument info");
897
898        assert_eq!(loader.token_id, "202");
899        assert_eq!(loader.condition_id, "0xcondition");
900        assert_eq!(
901            loader.instrument.outcome.map(|value| value.to_string()),
902            Some("No".to_string())
903        );
904        assert_eq!(loader.resolution_metadata["closed"], true);
905        assert_eq!(loader.resolution_metadata["tokens"][0]["winner"], true);
906        assert_eq!(
907            info.get_str("resolution_source"),
908            Some("https://example.com/result")
909        );
910        assert_eq!(info.get_str("description"), Some("Test market"));
911        assert!(!info.contains_key("gamma_market"));
912        assert_eq!(
913            loader.resolution_metadata["gamma_market"],
914            gamma_market().raw
915        );
916        assert!(!info.contains_key("closed"));
917        assert!(!info.contains_key("closedTime"));
918        assert!(!info.contains_key("umaResolutionStatus"));
919        assert!(!info.contains_key("resolutionSource"));
920        assert!(!info.contains_key("winner"));
921
922        Python::initialize();
923        Python::attach(|py| {
924            let py_loader = Py::new(py, loader).expect("Python loader");
925            assert_eq!(
926                py_loader
927                    .getattr(py, "token_id")
928                    .expect("token ID getter")
929                    .extract::<String>(py)
930                    .expect("token ID string"),
931                "202",
932            );
933            assert_eq!(
934                py_loader
935                    .getattr(py, "condition_id")
936                    .expect("condition ID getter")
937                    .extract::<String>(py)
938                    .expect("condition ID string"),
939                "0xcondition",
940            );
941            let metadata = py_loader
942                .getattr(py, "resolution_metadata")
943                .expect("resolution metadata getter");
944            assert!(
945                metadata
946                    .bind(py)
947                    .get_item("closed")
948                    .expect("closed metadata")
949                    .extract::<bool>()
950                    .expect("closed bool"),
951            );
952        });
953    }
954
955    #[rstest]
956    fn build_loader_preserves_distinct_crypto_config_in_rust_and_python_instrument_info() {
957        let loader = build_loader_from_details(
958            gamma_market_with_distinct_crypto_config(),
959            &clob_market(),
960            0,
961            data_api(),
962        )
963        .expect("loader should build");
964        let info = loader.instrument.info.as_ref().expect("instrument info");
965        let expected = json!({
966            "id": "eth-15m-twap-negative-37",
967            "asset": "eth",
968            "duration": "15m",
969            "twapEnabled": true,
970            "twapLookbackSeconds": -37,
971        });
972
973        assert_eq!(info.get("crypto_market_config"), Some(&expected));
974
975        Python::initialize();
976        Python::attach(|py| {
977            let py_loader = Py::new(py, loader).expect("Python loader");
978            let instrument = py_loader
979                .getattr(py, "instrument")
980                .expect("instrument getter");
981            let info = instrument
982                .getattr(py, "info")
983                .expect("instrument info getter");
984            let config = info
985                .bind(py)
986                .get_item("crypto_market_config")
987                .expect("crypto market config");
988
989            assert_eq!(
990                config
991                    .get_item("id")
992                    .expect("config ID")
993                    .extract::<String>()
994                    .expect("config ID string"),
995                "eth-15m-twap-negative-37",
996            );
997            assert_eq!(
998                config
999                    .get_item("asset")
1000                    .expect("config asset")
1001                    .extract::<String>()
1002                    .expect("config asset string"),
1003                "eth",
1004            );
1005            assert_eq!(
1006                config
1007                    .get_item("duration")
1008                    .expect("config duration")
1009                    .extract::<String>()
1010                    .expect("config duration string"),
1011                "15m",
1012            );
1013            assert!(
1014                config
1015                    .get_item("twapEnabled")
1016                    .expect("TWAP enabled")
1017                    .extract::<bool>()
1018                    .expect("TWAP enabled bool"),
1019            );
1020            assert_eq!(
1021                config
1022                    .get_item("twapLookbackSeconds")
1023                    .expect("TWAP lookback")
1024                    .extract::<i64>()
1025                    .expect("TWAP lookback integer"),
1026                -37,
1027            );
1028        });
1029    }
1030
1031    #[rstest]
1032    #[case(-1, "cannot be negative")]
1033    fn validate_token_index_rejects_negative_values(#[case] index: isize, #[case] message: &str) {
1034        let error = validate_token_index(index).expect_err("index should be rejected");
1035
1036        Python::initialize();
1037        Python::attach(|py| assert!(error.is_instance_of::<PyValueError>(py)));
1038        assert!(error.to_string().contains(message));
1039    }
1040
1041    #[rstest]
1042    #[case(None)]
1043    #[case(Some("unknown"))]
1044    fn build_loader_rejects_unsupported_protocol(
1045        #[case] version: Option<&str>,
1046        #[values(false, true)] clob_unsupported: bool,
1047    ) {
1048        Python::initialize();
1049        let mut market = gamma_market();
1050        let mut details = clob_market();
1051        if clob_unsupported {
1052            details.version = version.map(str::to_string);
1053        } else {
1054            market.version = version.map(str::to_string);
1055        }
1056
1057        let error = build_loader_from_details(market, &details, 0, data_api()).unwrap_err();
1058        assert!(error.to_string().contains(&format!(
1059            "Unsupported Polymarket data protocol {}; expected v1 or v2",
1060            version.unwrap_or("missing"),
1061        )));
1062    }
1063
1064    #[rstest]
1065    #[case("v1")]
1066    #[case("v2")]
1067    fn build_loader_preserves_selected_ids(
1068        #[case] version: &str,
1069        #[values(false, true)] reordered: bool,
1070    ) {
1071        let mut market = gamma_market();
1072        let mut details = clob_market();
1073        market.version = Some(version.into());
1074        details.version = Some(version.into());
1075        market.position_ids = Some(vec!["303".into(), "404".into()]);
1076
1077        if version == "v2" {
1078            details.tokens[0].token_id = "303".into();
1079            details.tokens[1].token_id = "404".into();
1080        }
1081
1082        if reordered {
1083            details.tokens.swap(0, 1);
1084        }
1085
1086        let condition_id = market.condition_id.clone();
1087        let loader = build_loader_from_details(market, &details, 1, data_api()).unwrap();
1088
1089        let expected = if version == "v2" { "404" } else { "202" };
1090        assert_eq!(loader.token_id, expected);
1091        assert_eq!(loader.instrument.raw_symbol.as_str(), expected);
1092        assert_eq!(
1093            loader.instrument.id.to_string(),
1094            format!("{condition_id}-{expected}.POLYMARKET")
1095        );
1096        assert_eq!(
1097            loader
1098                .instrument
1099                .info
1100                .as_ref()
1101                .unwrap()
1102                .get_str("market_version"),
1103            Some(version)
1104        );
1105    }
1106
1107    #[rstest]
1108    #[case::protocol(0)]
1109    #[case::selected_id(1)]
1110    #[case::other_id(2)]
1111    #[case::outcome(3)]
1112    #[case::swapped_labels(4)]
1113    fn build_loader_rejects_conflicting_metadata(
1114        #[case] conflict: usize,
1115        #[values("v1", "v2")] version: &str,
1116    ) {
1117        Python::initialize();
1118        let mut market = gamma_market();
1119        let mut details = clob_market();
1120        market.version = Some(version.into());
1121        details.version = Some(version.into());
1122        market.position_ids = Some(vec!["101".into(), "202".into()]);
1123
1124        match conflict {
1125            0 => details.version = Some(if version == "v1" { "v2" } else { "v1" }.into()),
1126            1 => details.tokens[0].token_id = "303".into(),
1127            2 => details.tokens[1].token_id = "404".into(),
1128            3 => details.tokens[1].outcome = "Other".into(),
1129            4 => {
1130                let outcome = details.tokens[0].outcome.clone();
1131                details.tokens[0].outcome = details.tokens[1].outcome.clone();
1132                details.tokens[1].outcome = outcome;
1133            }
1134            _ => unreachable!(),
1135        }
1136
1137        let error = build_loader_from_details(market, &details, 0, data_api()).unwrap_err();
1138        assert!(
1139            error
1140                .to_string()
1141                .contains("do not match Gamma market outcomes")
1142                || error
1143                    .to_string()
1144                    .contains("does not match Gamma market protocol")
1145        );
1146    }
1147
1148    #[rstest]
1149    fn build_loader_rejects_out_of_range_index() {
1150        Python::initialize();
1151
1152        let error = build_loader_from_details(gamma_market(), &clob_market(), 2, data_api())
1153            .expect_err("index should be rejected");
1154
1155        assert!(error.to_string().contains("Token index 2 out of range"));
1156    }
1157
1158    #[rstest]
1159    fn build_loader_rejects_empty_token_list() {
1160        Python::initialize();
1161
1162        let mut details = clob_market();
1163        details.tokens.clear();
1164
1165        let error = build_loader_from_details(gamma_market(), &details, 0, data_api())
1166            .expect_err("empty tokens should be rejected");
1167
1168        assert!(error.to_string().contains("No tokens found"));
1169    }
1170
1171    #[rstest]
1172    fn build_loader_rejects_transient_empty_token_id(
1173        #[values(0, 1)] token_index: usize,
1174        #[values(0, 1)] clob_index: usize,
1175    ) {
1176        Python::initialize();
1177
1178        let mut details = clob_market();
1179        details.tokens[clob_index].token_id.clear();
1180
1181        let error = build_loader_from_details(gamma_market(), &details, token_index, data_api())
1182            .expect_err("empty token ID should be rejected");
1183
1184        assert!(error.to_string().contains(&format!(
1185            "CLOB token at index {clob_index} for market '{}' has an empty token ID",
1186            details.condition_id,
1187        )));
1188    }
1189
1190    #[rstest]
1191    fn build_loader_rejects_malformed_non_binary_token_payload() {
1192        Python::initialize();
1193
1194        let mut details = clob_market();
1195        details.tokens.truncate(1);
1196
1197        let error = build_loader_from_details(gamma_market(), &details, 0, data_api())
1198            .expect_err("non-binary tokens should be rejected");
1199
1200        assert!(
1201            error
1202                .to_string()
1203                .contains("CLOB outcome IDs or labels do not match Gamma market outcomes")
1204        );
1205    }
1206
1207    #[rstest]
1208    fn build_loader_rejects_mismatched_condition_id() {
1209        Python::initialize();
1210
1211        let mut details = clob_market();
1212        details.condition_id = "0xdifferent".to_string();
1213
1214        let error = build_loader_from_details(gamma_market(), &details, 0, data_api())
1215            .expect_err("condition mismatch should be rejected");
1216
1217        assert!(
1218            error
1219                .to_string()
1220                .contains("does not match Gamma condition ID")
1221        );
1222    }
1223}