Skip to main content

nautilus_polymarket/http/
gamma.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//! Provides the HTTP client for the Polymarket Gamma API.
17//!
18//! Gamma keyset constraints honored by the paginators and `load_ids` chunker:
19//!
20//! - `/markets/keyset` accepts at most 100 items per page.
21//! - `/events/keyset` accepts at most 500 items per page.
22//! - Keyset endpoints reject `offset`; the paginators apply a requested initial
23//!   offset locally for compatibility.
24//! - Missing `next_cursor` ends pagination; a full final page can still include one.
25//! - `condition_ids=` accepts at most 100 IDs per request, so `load_ids` for
26//!   larger sets chunks the request and unions the responses. `condition_ids`
27//!   lookups stop at one market per distinct ID, since a redundant cursor request
28//!   can exceed Gamma's URI limit (HTTP 414).
29
30use std::{collections::HashMap, future::Future, result::Result as StdResult, sync::Arc};
31
32use ahash::{AHashMap, AHashSet};
33use jiff::Timestamp;
34use nautilus_common::live::dst;
35use nautilus_core::{
36    UnixNanos,
37    time::{AtomicTime, get_atomic_clock_realtime},
38};
39use nautilus_model::instruments::InstrumentAny;
40use nautilus_network::{
41    http::{
42        HttpClient, HttpClientError, HttpResponse, Method, create_standard_nautilus_headers,
43        parse_retry_after,
44    },
45    retry::{RetryConfig, RetryError, RetryManager},
46    websocket::proxy::ProxyUrl,
47};
48use parking_lot::Mutex;
49use rust_decimal::Decimal;
50use serde::{Deserialize, Serialize, de::DeserializeOwned};
51use serde_json::{Value, value::RawValue};
52
53use crate::{
54    common::{consts::MARKET_VERSION_V2, parse::validate_data_market_version, urls::gamma_api_url},
55    filters::set_market_closed,
56    http::{
57        error::{Error, Result, decode_response},
58        models::{GammaEvent, GammaMarket, GammaTag, SearchResponse},
59        pagination::{Completion, CursorProtocol, FetchOutcome, Paginator, WindowedCollect},
60        parse::{
61            create_instrument_from_def, enrich_market_fee_schedule,
62            parse_gamma_market_with_event_cache,
63        },
64        query::{GetGammaEventsParams, GetGammaMarketsParams, GetSearchParams},
65        rate_limits::{HEADER_RETRY_AFTER, POLYMARKET_GAMMA_REST_QUOTA},
66    },
67};
68
69const GAMMA_MARKETS_KEYSET_PAGE_LIMIT: u32 = 100;
70const GAMMA_EVENTS_KEYSET_PAGE_LIMIT: u32 = 500;
71
72#[derive(Clone, Copy, Debug, Eq, PartialEq)]
73enum GammaStop {
74    CallerCapped,
75}
76
77/// Provides a raw HTTP client for the Polymarket Gamma API.
78///
79/// Handles HTTP transport for fetching market data from the public Gamma API.
80/// Retries transient failures per request. No authentication is required.
81/// Uses three retries with exponential backoff and a 180-second total budget.
82/// The configured HTTP timeout bounds each attempt.
83#[derive(Debug, Clone)]
84pub struct PolymarketGammaRawHttpClient {
85    client: HttpClient,
86    base_url: String,
87    retry_manager: Arc<RetryManager<Error>>,
88}
89
90impl PolymarketGammaRawHttpClient {
91    /// Creates a new [`PolymarketGammaRawHttpClient`].
92    ///
93    /// # Errors
94    ///
95    /// Returns an error if the HTTP client cannot be created.
96    pub fn new(base_url: Option<String>, timeout_secs: u64) -> StdResult<Self, HttpClientError> {
97        Self::new_with_proxy(base_url, timeout_secs, None)
98    }
99
100    /// Creates a new raw client with an optional validated proxy URL.
101    ///
102    /// # Errors
103    ///
104    /// Returns an error if the HTTP client cannot be created.
105    pub fn new_with_proxy(
106        base_url: Option<String>,
107        timeout_secs: u64,
108        proxy_url: Option<ProxyUrl>,
109    ) -> StdResult<Self, HttpClientError> {
110        Ok(Self {
111            client: HttpClient::builder()
112                .headers(Self::default_headers())
113                .header_keys(vec![HEADER_RETRY_AFTER.to_string()])
114                .default_quota(*POLYMARKET_GAMMA_REST_QUOTA)
115                .timeout_secs(timeout_secs)
116                .maybe_proxy_url(proxy_url.map(|url| url.expose().to_string()))
117                .build()?,
118            base_url: base_url
119                .unwrap_or_else(|| gamma_api_url().to_string())
120                .trim_end_matches('/')
121                .to_string(),
122            retry_manager: Arc::new(RetryManager::new(RetryConfig {
123                jitter_ms: 1_000,
124                operation_timeout_ms: None,
125                max_elapsed_ms: Some(180_000),
126                ..RetryConfig::default()
127            })),
128        })
129    }
130
131    fn default_headers() -> HashMap<String, String> {
132        let mut headers: HashMap<String, String> =
133            create_standard_nautilus_headers().into_iter().collect();
134        headers.insert("Content-Type".to_string(), "application/json".to_string());
135        headers
136    }
137
138    fn url(&self, path: &str) -> String {
139        format!("{}{path}", self.base_url)
140    }
141
142    async fn send_get<P: Serialize, T: DeserializeOwned>(
143        &self,
144        path: &str,
145        params: Option<&P>,
146    ) -> Result<T> {
147        self.send_request(path, || {
148            let url = self.url(path);
149            self.client
150                .request_with_params(Method::GET, url, params, None, None, None, None)
151        })
152        .await
153    }
154
155    async fn send_get_query_map<T: DeserializeOwned>(
156        &self,
157        path: &str,
158        params: Option<&HashMap<String, Vec<String>>>,
159    ) -> Result<T> {
160        self.send_request(path, || {
161            let url = self.url(path);
162            self.client
163                .request(Method::GET, url, params, None, None, None, None)
164        })
165        .await
166    }
167
168    async fn send_request<T, F, Fut>(&self, path: &str, mut request: F) -> Result<T>
169    where
170        T: DeserializeOwned,
171        F: FnMut() -> Fut,
172        Fut: Future<Output = StdResult<HttpResponse, HttpClientError>>,
173    {
174        let retry_after = Mutex::new(None);
175
176        // Bound the layout of retry futures nested in instrument discovery
177        Box::pin(
178            self.retry_manager
179                .invocation(
180                    path,
181                    || {
182                        let response = request();
183                        async {
184                            *retry_after.lock() = None;
185                            let response = response.await.map_err(Error::from_http_client)?;
186                            *retry_after.lock() = response
187                                .headers
188                                .get(HEADER_RETRY_AFTER)
189                                .and_then(|value| parse_retry_after(value, Timestamp::now()))
190                                .filter(|delay| {
191                                    dst::time::Instant::now().checked_add(*delay).is_some()
192                                });
193                            decode_response(&response)
194                        }
195                    },
196                    Error::is_retryable,
197                    |e| match e {
198                        RetryError::OperationTimeout { .. } => Error::Timeout,
199                        RetryError::InvalidConfiguration { message } => Error::bad_request(message),
200                        e => Error::transport(e.to_string()),
201                    },
202                )
203                .retry_delay(&|_| *retry_after.lock())
204                .execute(),
205        )
206        .await
207    }
208
209    /// Fetches markets from the Gamma API.
210    ///
211    /// Handles both bare array and `{"data": [...]}` response schemas.
212    pub async fn get_gamma_markets(
213        &self,
214        params: GetGammaMarketsParams,
215    ) -> Result<Vec<GammaMarket>> {
216        let query_params = gamma_markets_query_params(params)?;
217        let raw: Box<RawValue> = self
218            .send_get_query_map("/markets", Some(&query_params))
219            .await?;
220        parse_gamma_markets_response(&raw)
221    }
222
223    async fn get_gamma_markets_keyset(
224        &self,
225        mut params: GetGammaMarketsParams,
226        after_cursor: Option<&str>,
227    ) -> Result<GammaMarketsKeysetResponse> {
228        params.validate_keyset().map_err(Error::decode)?;
229        params.offset = None;
230        let mut query_params = gamma_markets_query_params(params)?;
231        if let Some(after_cursor) = after_cursor {
232            query_params.insert("after_cursor".to_string(), vec![after_cursor.to_string()]);
233        }
234        self.send_get_query_map("/markets/keyset", Some(&query_params))
235            .await
236    }
237
238    /// Fetches a single market by ID from the Gamma API.
239    pub async fn get_gamma_market(&self, market_id: &str) -> Result<GammaMarket> {
240        let path = format!("/markets/{market_id}");
241        self.send_get::<(), _>(&path, None::<&()>).await
242    }
243
244    /// Fetches a market from the Gamma API `GET /markets/slug/{slug}`.
245    pub async fn get_gamma_market_by_slug(&self, slug: &str) -> Result<GammaMarket> {
246        let path = format!("/markets/slug/{slug}");
247        self.send_get::<(), _>(&path, None::<&()>).await
248    }
249
250    /// Fetches events from the Gamma API `GET /events?slug=`.
251    pub async fn get_gamma_events_by_slug(&self, slug: &str) -> Result<Vec<GammaEvent>> {
252        #[derive(Serialize)]
253        struct EventSlugParams<'a> {
254            slug: &'a str,
255        }
256        let params = EventSlugParams { slug };
257        self.send_get("/events", Some(&params)).await
258    }
259
260    /// Fetches events from the Gamma API `GET /events` with full query params.
261    pub async fn get_gamma_events(&self, params: GetGammaEventsParams) -> Result<Vec<GammaEvent>> {
262        let query_params = gamma_events_query_params(params)?;
263        self.send_get_query_map("/events", Some(&query_params))
264            .await
265    }
266
267    async fn get_gamma_events_keyset(
268        &self,
269        mut params: GetGammaEventsParams,
270        after_cursor: Option<&str>,
271    ) -> Result<GammaEventsKeysetResponse> {
272        params.validate_keyset().map_err(Error::decode)?;
273        params.offset = None;
274        let mut query_params = gamma_events_query_params(params)?;
275        if let Some(after_cursor) = after_cursor {
276            query_params.insert("after_cursor".to_string(), vec![after_cursor.to_string()]);
277        }
278        self.send_get_query_map("/events/keyset", Some(&query_params))
279            .await
280    }
281
282    /// Fetches available tags from the Gamma API `GET /tags`.
283    pub async fn get_gamma_tags(&self) -> Result<Vec<GammaTag>> {
284        self.send_get::<(), _>("/tags", None::<&()>).await
285    }
286
287    /// Searches the Gamma API via `GET /public-search`.
288    pub async fn get_public_search(&self, params: GetSearchParams) -> Result<SearchResponse> {
289        self.send_get("/public-search", Some(&params)).await
290    }
291}
292
293#[derive(Debug, Deserialize)]
294struct GammaMarketsKeysetResponse {
295    markets: Vec<GammaMarket>,
296    next_cursor: Option<String>,
297}
298
299#[derive(Debug, Deserialize)]
300struct GammaEventsKeysetResponse {
301    events: Vec<GammaEvent>,
302    next_cursor: Option<String>,
303}
304
305fn gamma_markets_query_params(
306    params: GetGammaMarketsParams,
307) -> Result<HashMap<String, Vec<String>>> {
308    let mut scalar_params = params;
309    let id = scalar_params.id.take();
310    let slug = scalar_params.slug.take();
311    let clob_token_ids = scalar_params.clob_token_ids.take();
312    let condition_ids = scalar_params.condition_ids.take();
313    let question_ids = scalar_params.question_ids.take();
314    let market_maker_address = scalar_params.market_maker_address.take();
315    let tag_id = scalar_params.tag_id.take();
316    let sports_market_types = scalar_params.sports_market_types.take();
317    let value = serde_json::to_value(&scalar_params).map_err(Error::Serde)?;
318    let fields = value
319        .as_object()
320        .ok_or_else(|| Error::decode("Gamma markets params must encode to an object"))?;
321    let mut params = HashMap::with_capacity(fields.len());
322
323    for (key, value) in fields {
324        if let Some(value) = gamma_query_value(value)? {
325            params.insert(key.clone(), vec![value]);
326        }
327    }
328
329    insert_repeated_param(&mut params, "id", id);
330    insert_repeated_param(&mut params, "slug", slug);
331    insert_repeated_param(&mut params, "clob_token_ids", clob_token_ids);
332    insert_repeated_param(&mut params, "condition_ids", condition_ids);
333    insert_repeated_param(&mut params, "question_ids", question_ids);
334    insert_repeated_param(&mut params, "market_maker_address", market_maker_address);
335    insert_repeated_param(&mut params, "tag_id", tag_id);
336    insert_repeated_param(&mut params, "sports_market_types", sports_market_types);
337
338    Ok(params)
339}
340
341fn gamma_events_query_params(params: GetGammaEventsParams) -> Result<HashMap<String, Vec<String>>> {
342    let mut scalar_params = params;
343    let id = scalar_params.id.take();
344    let slug = scalar_params.slug.take();
345    let tag_id = scalar_params.tag_id.take();
346    let exclude_tag_id = scalar_params.exclude_tag_id.take();
347    let series_id = scalar_params.series_id.take();
348    let game_id = scalar_params.game_id.take();
349    let created_by = scalar_params.created_by.take();
350    let value = serde_json::to_value(&scalar_params).map_err(Error::Serde)?;
351    let fields = value
352        .as_object()
353        .ok_or_else(|| Error::decode("Gamma events params must encode to an object"))?;
354    let mut params = HashMap::with_capacity(fields.len());
355
356    for (key, value) in fields {
357        if let Some(value) = gamma_query_value(value)? {
358            params.insert(key.clone(), vec![value]);
359        }
360    }
361
362    insert_repeated_param(&mut params, "id", id);
363    insert_repeated_param(&mut params, "slug", slug);
364    insert_repeated_param(&mut params, "tag_id", tag_id);
365    insert_repeated_param(&mut params, "exclude_tag_id", exclude_tag_id);
366    insert_repeated_param(&mut params, "series_id", series_id);
367    insert_repeated_param(&mut params, "game_id", game_id);
368    insert_repeated_param(&mut params, "created_by", created_by);
369
370    Ok(params)
371}
372
373fn insert_repeated_param<T: ToString>(
374    params: &mut HashMap<String, Vec<String>>,
375    key: &str,
376    values: Option<Vec<T>>,
377) {
378    let Some(values) = values else {
379        return;
380    };
381
382    params.insert(
383        key.to_string(),
384        values
385            .into_iter()
386            .map(|value| value.to_string().trim().to_string())
387            .collect(),
388    );
389}
390
391fn gamma_query_value(value: &Value) -> Result<Option<String>> {
392    match value {
393        Value::Null => Ok(None),
394        Value::String(value) => Ok(Some(value.clone())),
395        Value::Bool(value) => Ok(Some(value.to_string())),
396        Value::Number(value) => Ok(Some(value.to_string())),
397        other => Err(Error::decode(format!(
398            "Unsupported Gamma query value: {other}"
399        ))),
400    }
401}
402
403fn parse_markets_to_instruments(markets: &[GammaMarket], ts_init: UnixNanos) -> Vec<InstrumentAny> {
404    let (instruments, _transient) = parse_markets_with_transient(markets, ts_init);
405    instruments
406}
407
408// Returns parsed instruments alongside condition IDs of markets still in the
409// CLOB hydration window (missing or empty selected outcome IDs), so callers
410// can retry rather than treating them as terminal.
411//
412// This is the single funnel through which live instruments reach the client caches, so Gamma's
413// `closed` state is recorded here rather than in `create_instrument_from_def`. Historical loader
414// instruments share that constructor and must not carry terminal state in `info`; they expose it
415// through `resolution_metadata` instead.
416pub(crate) fn parse_markets_with_transient(
417    markets: &[GammaMarket],
418    ts_init: UnixNanos,
419) -> (Vec<InstrumentAny>, Vec<String>) {
420    let mut instruments = Vec::new();
421    let mut transient = Vec::new();
422
423    // Parents outlive this batch; pointer keys keep distinct discovery snapshots separate
424    let mut event_metadata = AHashMap::new();
425
426    for market in markets {
427        if let Err(e) = validate_data_market_version(market.version.as_deref()) {
428            log::warn!("Skipping Gamma market {}: {e}", market.condition_id);
429            continue;
430        }
431
432        if is_transient_market(market) {
433            transient.push(market.condition_id.clone());
434            continue;
435        }
436
437        match parse_gamma_market_with_event_cache(market, &mut event_metadata) {
438            Ok(defs) => {
439                for def in defs {
440                    match create_instrument_from_def(&def, ts_init) {
441                        Ok(InstrumentAny::BinaryOption(mut binary)) => {
442                            set_market_closed(&mut binary, def.closed);
443                            instruments.push(InstrumentAny::BinaryOption(binary));
444                        }
445                        Ok(other) => instruments.push(other),
446                        Err(e) => log::warn!("Failed to create instrument: {e}"),
447                    }
448                }
449            }
450            Err(e) => log::warn!("Failed to parse gamma market: {e}"),
451        }
452    }
453
454    if !transient.is_empty() {
455        log::debug!(
456            "{} market(s) without usable outcome IDs deferred as transient (CLOB hydration)",
457            transient.len(),
458        );
459    }
460    (instruments, transient)
461}
462
463fn is_transient_market(market: &GammaMarket) -> bool {
464    if market.version.as_deref() == Some(MARKET_VERSION_V2) {
465        market
466            .position_ids
467            .as_ref()
468            .is_none_or(|ids| ids.is_empty() || ids.iter().any(String::is_empty))
469    } else {
470        is_transient_clob_token_ids(&market.clob_token_ids)
471    }
472}
473
474// Treats bare empty string, encoded empty array, and arrays with empty entries
475// as transient. Unparsable payloads fall through to `parse_gamma_market` so
476// real schema errors still surface.
477fn is_transient_clob_token_ids(raw: &str) -> bool {
478    if raw.is_empty() {
479        return true;
480    }
481
482    match serde_json::from_str::<Vec<String>>(raw) {
483        Ok(ids) => ids.is_empty() || ids.iter().any(|t| t.is_empty()),
484        Err(_) => false,
485    }
486}
487
488pub(crate) fn flatten_event_markets(events: Vec<GammaEvent>) -> Vec<GammaMarket> {
489    events
490        .into_iter()
491        .flat_map(|mut event| {
492            let markets = std::mem::take(&mut event.markets);
493            let event = Arc::new(event);
494
495            markets.into_iter().map(move |mut market| {
496                if market.game_id.is_none() {
497                    market.game_id.clone_from(&event.game_id);
498                }
499
500                market.parent_event = Some(event.clone());
501                market
502            })
503        })
504        .collect()
505}
506
507/// Provides a domain HTTP client for Polymarket instrument fetching.
508///
509/// Wraps [`PolymarketGammaRawHttpClient`] with instrument parsing: fetch from
510/// the Gamma API and parse into Nautilus types. Stateless with respect to
511/// instrument storage; caching is handled by the instrument provider.
512#[derive(Debug, Clone)]
513pub struct PolymarketGammaHttpClient {
514    inner: Arc<PolymarketGammaRawHttpClient>,
515    clock: &'static AtomicTime,
516    retry_manager: Arc<RetryManager<Error>>,
517}
518
519impl PolymarketGammaHttpClient {
520    /// Creates a new [`PolymarketGammaHttpClient`].
521    ///
522    /// `retry_config` controls indexing-lag retries, independently of HTTP retries.
523    /// `retry_config.operation_timeout_ms` is ignored; `timeout_secs` bounds each HTTP attempt.
524    ///
525    /// # Errors
526    ///
527    /// Returns an error if the underlying HTTP client cannot be created.
528    pub fn new(
529        gamma_base_url: Option<String>,
530        timeout_secs: u64,
531        retry_config: RetryConfig,
532    ) -> StdResult<Self, HttpClientError> {
533        Self::new_with_proxy(gamma_base_url, timeout_secs, retry_config, None)
534    }
535
536    /// Creates a new domain client with an optional validated proxy URL.
537    ///
538    /// `retry_config` controls indexing-lag retries, independently of HTTP retries.
539    /// `retry_config.operation_timeout_ms` is ignored; `timeout_secs` bounds each HTTP attempt.
540    ///
541    /// # Errors
542    ///
543    /// Returns an error if the underlying HTTP client cannot be created.
544    pub fn new_with_proxy(
545        gamma_base_url: Option<String>,
546        timeout_secs: u64,
547        mut retry_config: RetryConfig,
548        proxy_url: Option<ProxyUrl>,
549    ) -> StdResult<Self, HttpClientError> {
550        // HTTP attempts own their timeouts; indexing retries include HTTP backoff
551        retry_config.operation_timeout_ms = None;
552
553        Ok(Self {
554            inner: Arc::new(PolymarketGammaRawHttpClient::new_with_proxy(
555                gamma_base_url,
556                timeout_secs,
557                proxy_url,
558            )?),
559            clock: get_atomic_clock_realtime(),
560            retry_manager: Arc::new(RetryManager::new(retry_config)),
561        })
562    }
563
564    pub(crate) fn retry_manager(&self) -> &RetryManager<Error> {
565        &self.retry_manager
566    }
567
568    /// Fetches markets from the Gamma API with the given base params, paginating automatically.
569    async fn fetch_gamma_markets_paginated(
570        &self,
571        base_params: GetGammaMarketsParams,
572    ) -> anyhow::Result<Vec<GammaMarket>> {
573        let page_size = base_params
574            .limit
575            .unwrap_or(GAMMA_MARKETS_KEYSET_PAGE_LIMIT)
576            .min(GAMMA_MARKETS_KEYSET_PAGE_LIMIT);
577        let protocol = CursorProtocol::gamma("Gamma market");
578
579        let reducer = WindowedCollect::new(
580            base_params.offset.unwrap_or(0) as usize,
581            gamma_markets_maximum(&base_params),
582            GammaStop::CallerCapped,
583        );
584        let paginator = Paginator::new("Gamma market", protocol, reducer);
585        let completed = paginator
586            .run(
587                |position| {
588                    let after_cursor = position.map(|cursor| cursor.as_ref().to_string());
589                    let params = GetGammaMarketsParams {
590                        limit: Some(page_size),
591                        offset: None,
592                        ..base_params.clone()
593                    };
594                    async move {
595                        let response = self
596                            .inner
597                            .get_gamma_markets_keyset(params, after_cursor.as_deref())
598                            .await?;
599                        Ok::<_, anyhow::Error>(FetchOutcome {
600                            rows: response.markets,
601                            wire: response.next_cursor,
602                        })
603                    }
604                },
605                anyhow::Error::new,
606            )
607            .await?;
608
609        match completed.completion {
610            Completion::WireExhausted | Completion::Stopped(GammaStop::CallerCapped) => {
611                Ok(completed.output)
612            }
613        }
614    }
615
616    /// Fetches all active markets from the Gamma API, paginating automatically.
617    async fn fetch_all_gamma_markets(&self) -> anyhow::Result<Vec<GammaMarket>> {
618        self.fetch_gamma_markets_paginated(GetGammaMarketsParams {
619            active: Some(true),
620            closed: Some(false),
621            ..Default::default()
622        })
623        .await
624    }
625
626    /// Fetches instruments from the Gamma API and returns Nautilus domain types.
627    ///
628    /// # Errors
629    ///
630    /// Returns an error if the HTTP request or parsing fails.
631    pub async fn request_instruments(&self) -> anyhow::Result<Vec<InstrumentAny>> {
632        let mut markets = self.fetch_all_gamma_markets().await?;
633        enrich_markets(&mut markets);
634        let ts_init = self.clock.get_time_ns();
635        let instruments = parse_markets_to_instruments(&markets, ts_init);
636        log::debug!("Parsed {} instruments from Gamma API", instruments.len());
637        Ok(instruments)
638    }
639
640    /// Fetches instruments for the given slugs concurrently.
641    ///
642    /// Each slug is queried individually via the Gamma API. Missing or
643    /// unparsable slugs are logged and skipped.
644    ///
645    /// # Errors
646    ///
647    /// Returns an error if all slug requests fail. Individual slug failures
648    /// are warned and skipped when at least one slug succeeds.
649    pub async fn request_instruments_by_slugs(
650        &self,
651        slugs: Vec<String>,
652    ) -> anyhow::Result<Vec<InstrumentAny>> {
653        let ts_init = self.clock.get_time_ns();
654
655        let futures = slugs.into_iter().map(|slug| {
656            let inner = Arc::clone(&self.inner);
657            async move {
658                let params = GetGammaMarketsParams {
659                    slug: Some(vec![slug.clone()]),
660                    ..Default::default()
661                };
662
663                match inner.get_gamma_markets(params).await {
664                    Ok(markets) => Some((slug, markets)),
665                    Err(e) => {
666                        log::warn!("Failed to fetch slug '{slug}': {e}");
667                        None
668                    }
669                }
670            }
671        });
672
673        let results = futures_util::future::join_all(futures).await;
674
675        let total_slugs = results.len();
676        let succeeded = results.iter().filter(|r| r.is_some()).count();
677        let mut instruments = Vec::new();
678
679        for result in results.into_iter().flatten() {
680            let (slug, mut markets) = result;
681            if markets.is_empty() {
682                log::debug!("No markets found for slug '{slug}'");
683                continue;
684            }
685
686            enrich_markets(&mut markets);
687            instruments.extend(parse_markets_to_instruments(&markets, ts_init));
688        }
689
690        if succeeded == 0 && total_slugs > 0 {
691            anyhow::bail!("All {total_slugs} slug requests failed");
692        }
693
694        log::debug!("Parsed {} instruments from slug queries", instruments.len());
695        Ok(instruments)
696    }
697
698    /// Fetches instruments for the given slugs with retry on empty results.
699    ///
700    /// Uses exponential backoff for indexing lag. Each HTTP request independently
701    /// retries transient failures, without retrying exhausted HTTP errors at the batch level.
702    pub async fn request_instruments_by_slugs_with_retry(
703        &self,
704        slugs: Vec<String>,
705    ) -> anyhow::Result<Vec<InstrumentAny>> {
706        let inner = Arc::clone(&self.inner);
707        let ts_init = self.clock.get_time_ns();
708
709        let mut markets: Vec<GammaMarket> = self
710            .retry_manager
711            .invocation(
712                "gamma_fetch_by_slugs",
713                || {
714                    let inner = Arc::clone(&inner);
715                    let slugs = slugs.clone();
716                    async move {
717                        let futures = slugs.into_iter().map(|slug| {
718                            let inner = Arc::clone(&inner);
719                            async move {
720                                let params = GetGammaMarketsParams {
721                                    slug: Some(vec![slug.clone()]),
722                                    ..Default::default()
723                                };
724                                inner
725                                    .get_gamma_markets(params)
726                                    .await
727                                    .map(|markets| (slug, markets))
728                            }
729                        });
730
731                        let results: Vec<_> = futures_util::future::join_all(futures)
732                            .await
733                            .into_iter()
734                            .collect::<StdResult<Vec<_>, _>>()?;
735
736                        let markets: Vec<GammaMarket> = results
737                            .into_iter()
738                            .flat_map(|(_, markets)| markets)
739                            .collect();
740
741                        if parse_markets_to_instruments(&markets, ts_init).is_empty()
742                            && (markets.is_empty()
743                                || markets.iter().any(|market| {
744                                    validate_data_market_version(market.version.as_deref()).is_ok()
745                                }))
746                        {
747                            return Err(Error::exchange(
748                                "Gamma returned no instruments (indexing lag)",
749                            ));
750                        }
751
752                        Ok(markets)
753                    }
754                },
755                |e| matches!(e, Error::Exchange(_)),
756                |e| Error::transport(e.to_string()),
757            )
758            .execute()
759            .await
760            .map_err(|e| anyhow::anyhow!("{e}"))?;
761
762        enrich_markets(&mut markets);
763        Ok(parse_markets_to_instruments(&markets, ts_init))
764    }
765
766    /// Fetches instruments from event slugs concurrently.
767    ///
768    /// Each slug queries `GET /events?slug=`, extracts the markets array from
769    /// the first matching event, and parses each market into instruments.
770    pub async fn request_instruments_by_event_slugs(
771        &self,
772        event_slugs: Vec<String>,
773    ) -> anyhow::Result<Vec<InstrumentAny>> {
774        let ts_init = self.clock.get_time_ns();
775
776        let futures = event_slugs.into_iter().map(|slug| {
777            let inner = Arc::clone(&self.inner);
778            async move {
779                match inner.get_gamma_events_by_slug(&slug).await {
780                    Ok(events) => Some((slug, events)),
781                    Err(e) => {
782                        log::warn!("Failed to fetch event slug '{slug}': {e}");
783                        None
784                    }
785                }
786            }
787        });
788
789        let results = futures_util::future::join_all(futures).await;
790
791        let total = results.len();
792        let succeeded = results.iter().filter(|r| r.is_some()).count();
793        let mut instruments = Vec::new();
794
795        for result in results.into_iter().flatten() {
796            let (slug, events) = result;
797            let mut markets = flatten_event_markets(events);
798            if markets.is_empty() {
799                log::warn!("No markets found in event slug '{slug}'");
800                continue;
801            }
802
803            enrich_markets(&mut markets);
804            instruments.extend(parse_markets_to_instruments(&markets, ts_init));
805        }
806
807        if succeeded == 0 && total > 0 {
808            anyhow::bail!("All {total} event slug requests failed");
809        }
810
811        log::debug!(
812            "Parsed {} instruments from event slug queries",
813            instruments.len()
814        );
815        Ok(instruments)
816    }
817
818    /// Fetches instruments using arbitrary Gamma API query params with auto-pagination.
819    pub async fn request_instruments_by_params(
820        &self,
821        base_params: GetGammaMarketsParams,
822    ) -> anyhow::Result<Vec<InstrumentAny>> {
823        let mut markets = self.fetch_gamma_markets_paginated(base_params).await?;
824        enrich_markets(&mut markets);
825        let ts_init = self.clock.get_time_ns();
826        let instruments = parse_markets_to_instruments(&markets, ts_init);
827        log::debug!("Parsed {} instruments from params query", instruments.len());
828        Ok(instruments)
829    }
830
831    /// Fetches supported instruments and condition IDs awaiting outcome IDs.
832    ///
833    /// Market protocols `v1` and `v2` enter the transient list. Unlike
834    /// [`Self::request_instruments_by_params`], this method errors when every returned
835    /// market uses an unsupported protocol.
836    ///
837    /// # Errors
838    ///
839    /// Returns an error if the request fails or every returned market is unsupported.
840    pub async fn request_instruments_by_params_with_transient(
841        &self,
842        base_params: GetGammaMarketsParams,
843    ) -> anyhow::Result<(Vec<InstrumentAny>, Vec<String>)> {
844        let mut markets = self.fetch_gamma_markets_paginated(base_params).await?;
845        if !markets.is_empty()
846            && markets
847                .iter()
848                .all(|market| validate_data_market_version(market.version.as_deref()).is_err())
849        {
850            validate_data_market_version(markets[0].version.as_deref())?;
851        }
852
853        enrich_markets(&mut markets);
854        let ts_init = self.clock.get_time_ns();
855        let (instruments, transient) = parse_markets_with_transient(&markets, ts_init);
856        log::debug!(
857            "Parsed {} instruments and {} transient condition_id(s) from params query",
858            instruments.len(),
859            transient.len(),
860        );
861        Ok((instruments, transient))
862    }
863
864    /// Fetches raw Gamma markets using arbitrary query params with auto-pagination.
865    pub async fn request_markets_by_params(
866        &self,
867        base_params: GetGammaMarketsParams,
868    ) -> anyhow::Result<Vec<GammaMarket>> {
869        self.fetch_gamma_markets_paginated(base_params).await
870    }
871
872    /// Fetches instruments from an event's embedded markets with client-side sorting and limiting.
873    ///
874    /// Only these `GetGammaMarketsParams` fields are supported:
875    /// - `order`: `"liquidity"`, `"volume"`, `"volume24hr"`, `"competitive"`,
876    ///   `"spread"`, `"best_bid"`, `"one_day_price_change"`, or `"volume_1wk"`.
877    /// - `ascending`: sort direction (default: descending); unused without `order`.
878    /// - `max_markets`: truncate after sorting; without `order`, retain event order.
879    ///
880    /// # Errors
881    ///
882    /// Returns an error if:
883    /// - A parameter or order field is unsupported, rejected before fetching.
884    /// - The event request fails.
885    pub async fn request_instruments_by_event_query(
886        &self,
887        event_slug: &str,
888        params: GetGammaMarketsParams,
889    ) -> anyhow::Result<Vec<InstrumentAny>> {
890        let unsupported = GetGammaMarketsParams {
891            order: None,
892            ascending: None,
893            max_markets: None,
894            ..params.clone()
895        };
896
897        let unsupported = serde_json::to_value(unsupported)?;
898        if let Some(field) = unsupported
899            .as_object()
900            .and_then(|fields| fields.keys().next())
901        {
902            anyhow::bail!("Unsupported event query parameter '{field}'");
903        }
904
905        let compare: Option<fn(&GammaMarket, &GammaMarket) -> std::cmp::Ordering> =
906            if let Some(order_field) = params.order.as_deref() {
907                Some(match order_field {
908                    "liquidity" => |a, b| {
909                        a.liquidity_num
910                            .unwrap_or(Decimal::ZERO)
911                            .cmp(&b.liquidity_num.unwrap_or(Decimal::ZERO))
912                    },
913                    "volume" => |a, b| {
914                        a.volume_num
915                            .unwrap_or(Decimal::ZERO)
916                            .cmp(&b.volume_num.unwrap_or(Decimal::ZERO))
917                    },
918                    "volume24hr" => |a, b| {
919                        a.volume_24hr
920                            .unwrap_or(Decimal::ZERO)
921                            .cmp(&b.volume_24hr.unwrap_or(Decimal::ZERO))
922                    },
923                    "competitive" => |a, b| {
924                        a.competitive
925                            .unwrap_or(0.0)
926                            .partial_cmp(&b.competitive.unwrap_or(0.0))
927                            .unwrap_or(std::cmp::Ordering::Equal)
928                    },
929                    "spread" => |a, b| {
930                        a.spread
931                            .unwrap_or(Decimal::MAX)
932                            .cmp(&b.spread.unwrap_or(Decimal::MAX))
933                    },
934                    "best_bid" => |a, b| {
935                        a.best_bid
936                            .unwrap_or(Decimal::ZERO)
937                            .cmp(&b.best_bid.unwrap_or(Decimal::ZERO))
938                    },
939                    "one_day_price_change" => |a, b| {
940                        a.one_day_price_change
941                            .unwrap_or(Decimal::ZERO)
942                            .cmp(&b.one_day_price_change.unwrap_or(Decimal::ZERO))
943                    },
944                    "volume_1wk" => |a, b| {
945                        a.volume_1wk
946                            .unwrap_or(Decimal::ZERO)
947                            .cmp(&b.volume_1wk.unwrap_or(Decimal::ZERO))
948                    },
949                    _ => anyhow::bail!("Unsupported event query order field '{order_field}'"),
950                })
951            } else {
952                None
953            };
954
955        let events = self.inner.get_gamma_events_by_slug(event_slug).await?;
956        let mut markets = flatten_event_markets(events);
957
958        if markets.is_empty() {
959            log::warn!("No markets found in event slug '{event_slug}'");
960            return Ok(Vec::new());
961        }
962
963        log::debug!("Event '{event_slug}' returned {} markets", markets.len());
964
965        if let Some(compare) = compare {
966            let ascending = params.ascending.unwrap_or(false);
967            markets.sort_by(|a, b| {
968                let cmp = compare(a, b);
969                if ascending { cmp } else { cmp.reverse() }
970            });
971        }
972
973        if let Some(cap) = params.max_markets {
974            markets.truncate(cap as usize);
975        }
976
977        enrich_markets(&mut markets);
978        let ts_init = self.clock.get_time_ns();
979        let instruments = parse_markets_to_instruments(&markets, ts_init);
980        log::debug!(
981            "Parsed {} instruments from event query '{event_slug}'",
982            instruments.len()
983        );
984        Ok(instruments)
985    }
986
987    /// Fetches events from the Gamma API with the given base params, paginating automatically.
988    async fn fetch_gamma_events_paginated(
989        &self,
990        base_params: GetGammaEventsParams,
991    ) -> anyhow::Result<Vec<GammaEvent>> {
992        let page_size = base_params
993            .limit
994            .unwrap_or(GAMMA_EVENTS_KEYSET_PAGE_LIMIT)
995            .min(GAMMA_EVENTS_KEYSET_PAGE_LIMIT);
996        let protocol = CursorProtocol::gamma("Gamma event");
997
998        let reducer = WindowedCollect::new(
999            base_params.offset.unwrap_or(0) as usize,
1000            base_params.max_events.map(|value| value as usize),
1001            GammaStop::CallerCapped,
1002        );
1003        let paginator = Paginator::new("Gamma event", protocol, reducer);
1004        let completed = paginator
1005            .run(
1006                |position| {
1007                    let after_cursor = position.map(|cursor| cursor.as_ref().to_string());
1008                    let params = GetGammaEventsParams {
1009                        limit: Some(page_size),
1010                        offset: None,
1011                        ..base_params.clone()
1012                    };
1013                    async move {
1014                        let response = self
1015                            .inner
1016                            .get_gamma_events_keyset(params, after_cursor.as_deref())
1017                            .await?;
1018                        Ok::<_, anyhow::Error>(FetchOutcome {
1019                            rows: response.events,
1020                            wire: response.next_cursor,
1021                        })
1022                    }
1023                },
1024                anyhow::Error::new,
1025            )
1026            .await?;
1027
1028        match completed.completion {
1029            Completion::WireExhausted | Completion::Stopped(GammaStop::CallerCapped) => {
1030                Ok(completed.output)
1031            }
1032        }
1033    }
1034
1035    /// Fetches instruments from events matching full query params (paginated).
1036    pub async fn request_instruments_by_event_params(
1037        &self,
1038        params: GetGammaEventsParams,
1039    ) -> anyhow::Result<Vec<InstrumentAny>> {
1040        let events = self.fetch_gamma_events_paginated(params).await?;
1041        let ts_init = self.clock.get_time_ns();
1042        let total_events = events.len();
1043        let mut markets = flatten_event_markets(events);
1044        let total_markets = markets.len();
1045        enrich_markets(&mut markets);
1046        let instruments = parse_markets_to_instruments(&markets, ts_init);
1047        log::debug!(
1048            "Parsed {} instruments from {total_events} events ({total_markets} markets)",
1049            instruments.len(),
1050        );
1051        Ok(instruments)
1052    }
1053
1054    /// Fetches raw Gamma events using arbitrary query params with auto-pagination.
1055    pub async fn request_events_by_params(
1056        &self,
1057        params: GetGammaEventsParams,
1058    ) -> anyhow::Result<Vec<GammaEvent>> {
1059        self.fetch_gamma_events_paginated(params).await
1060    }
1061
1062    /// Searches for instruments via the Gamma public search endpoint.
1063    pub async fn request_instruments_by_search(
1064        &self,
1065        params: GetSearchParams,
1066    ) -> anyhow::Result<Vec<InstrumentAny>> {
1067        let response = self.inner.get_public_search(params).await?;
1068        let ts_init = self.clock.get_time_ns();
1069
1070        let mut instruments = Vec::new();
1071
1072        if let Some(markets) = response.markets {
1073            let mut markets = markets;
1074            enrich_markets(&mut markets);
1075            instruments.extend(parse_markets_to_instruments(&markets, ts_init));
1076        }
1077
1078        if let Some(events) = &response.events {
1079            let mut event_markets = flatten_event_markets(events.clone());
1080            enrich_markets(&mut event_markets);
1081            instruments.extend(parse_markets_to_instruments(&event_markets, ts_init));
1082        }
1083
1084        log::debug!("Parsed {} instruments from search query", instruments.len());
1085        Ok(instruments)
1086    }
1087
1088    /// Fetches available tags from the Gamma API.
1089    pub async fn request_tags(&self) -> anyhow::Result<Vec<GammaTag>> {
1090        Ok(self.inner.get_gamma_tags().await?)
1091    }
1092
1093    /// Returns a reference to the underlying raw HTTP client.
1094    #[must_use]
1095    pub fn inner(&self) -> &Arc<PolymarketGammaRawHttpClient> {
1096        &self.inner
1097    }
1098}
1099
1100fn gamma_markets_maximum(params: &GetGammaMarketsParams) -> Option<usize> {
1101    let caller_maximum = params.max_markets.map(|value| value as usize);
1102
1103    let condition_maximum = params.condition_ids.as_ref().map(|ids| {
1104        let distinct = ids
1105            .iter()
1106            .map(|id| id.trim())
1107            .collect::<AHashSet<_>>()
1108            .len();
1109        distinct.saturating_sub(params.offset.unwrap_or(0) as usize)
1110    });
1111
1112    match (caller_maximum, condition_maximum) {
1113        (Some(caller), Some(conditions)) => Some(caller.min(conditions)),
1114        (caller, conditions) => caller.or(conditions),
1115    }
1116}
1117
1118fn enrich_markets(markets: &mut [GammaMarket]) {
1119    for market in markets {
1120        enrich_market_fee_schedule(market);
1121    }
1122}
1123
1124fn parse_gamma_markets_response(raw: &RawValue) -> Result<Vec<GammaMarket>> {
1125    #[derive(Deserialize)]
1126    struct MarketsEnvelope {
1127        data: Vec<GammaMarket>,
1128    }
1129
1130    if raw.get().starts_with('[') {
1131        return serde_json::from_str(raw.get()).map_err(Error::Serde);
1132    }
1133    serde_json::from_str::<MarketsEnvelope>(raw.get())
1134        .map(|envelope| envelope.data)
1135        .map_err(Error::Serde)
1136}
1137
1138#[cfg(test)]
1139mod tests {
1140    use std::{
1141        sync::atomic::{AtomicUsize, Ordering},
1142        time::Duration,
1143    };
1144
1145    use nautilus_common::cache::Cache;
1146    use nautilus_model::instruments::Instrument;
1147    use rstest::rstest;
1148    use rust_decimal_macros::dec;
1149    use serde_json::from_str;
1150
1151    use super::*;
1152    use crate::{
1153        http::{
1154            clob::PolymarketClobPublicClient, data_api::PolymarketDataApiHttpClient,
1155            parse::parse_gamma_market,
1156        },
1157        resolve::build_strict_resolved_market,
1158    };
1159
1160    #[rstest]
1161    #[tokio::test(start_paused = true)]
1162    async fn test_http_policy_is_independent_of_indexing_policy() {
1163        let client = PolymarketGammaHttpClient::new(
1164            None,
1165            90,
1166            RetryConfig {
1167                max_retries: 0,
1168                operation_timeout_ms: Some(30_000),
1169                immediate_first: true,
1170                max_elapsed_ms: Some(300_000),
1171                ..RetryConfig::default()
1172            },
1173        )
1174        .unwrap();
1175        let attempts = AtomicUsize::new(0);
1176        let started = tokio::time::Instant::now();
1177        let tags: Vec<GammaTag> = client
1178            .inner
1179            .send_request("/tags", || {
1180                let attempt = attempts.fetch_add(1, Ordering::Relaxed);
1181                async move {
1182                    if attempt == 0 {
1183                        return Err(HttpClientError::TransportError("reset".to_string()));
1184                    }
1185
1186                    tokio::time::sleep(Duration::from_secs(65)).await;
1187                    Ok(HttpResponse {
1188                        status: 200_u16.try_into().unwrap(),
1189                        headers: HashMap::new(),
1190                        body: "[]".into(),
1191                    })
1192                }
1193            })
1194            .await
1195            .unwrap();
1196
1197        assert!(tags.is_empty());
1198        assert_eq!(attempts.load(Ordering::Relaxed), 2);
1199        assert!(started.elapsed() >= Duration::from_secs(66));
1200    }
1201
1202    fn load_fee_market(filename: &str) -> GammaMarket {
1203        let path = format!("test_data/{filename}");
1204        let content = std::fs::read_to_string(path).unwrap();
1205        serde_json::from_str(&content).unwrap()
1206    }
1207
1208    #[rstest]
1209    #[ignore = "read-only mainnet market-data validation"]
1210    #[tokio::test]
1211    async fn test_live_market_protocol_data() {
1212        let gamma = PolymarketGammaHttpClient::new(None, 20, RetryConfig::default()).unwrap();
1213        let clob = PolymarketClobPublicClient::new(None, 20).unwrap();
1214        let data = PolymarketDataApiHttpClient::new(None, 20).unwrap();
1215
1216        for (id, version) in [(5931597, "v2"), (1557558, "v1")] {
1217            let markets = gamma
1218                .request_markets_by_params(GetGammaMarketsParams {
1219                    id: Some(vec![id]),
1220                    closed: Some(true),
1221                    max_markets: Some(1),
1222                    ..Default::default()
1223                })
1224                .await
1225                .unwrap();
1226
1227            assert_eq!(markets.len(), 1);
1228            assert_eq!(markets[0].id, id.to_string());
1229            assert_eq!(markets[0].version.as_deref(), Some(version));
1230
1231            if version == "v2" {
1232                assert_eq!(markets[0].resolution_status.as_deref(), Some("resolved"));
1233                let resolved = build_strict_resolved_market(&markets[0]).expect("strict V2 payout");
1234                assert_eq!(resolved.condition_id, markets[0].condition_id);
1235                assert_eq!(resolved.winning_asset_id, resolved.asset_ids[0]);
1236                assert_eq!(resolved.winning_outcome, resolved.outcomes[0]);
1237                eprintln!("Validated V2 finality and exact binary payout for market {id}");
1238            }
1239
1240            let definitions = parse_gamma_market(&markets[0]).unwrap();
1241            let instruments = parse_markets_to_instruments(&markets, 1.into());
1242            assert_eq!(instruments.len(), 2);
1243            let details = clob.get_market(&markets[0].condition_id).await.unwrap();
1244            assert_eq!(details.version.as_deref(), Some(version));
1245            assert_eq!(details.condition_id, markets[0].condition_id);
1246            assert_eq!(details.tokens.len(), definitions.len());
1247
1248            for definition in &definitions {
1249                assert!(details.tokens.iter().any(|token| {
1250                    definition.token_id.as_str() == token.token_id
1251                        && definition.outcome.as_str() == token.outcome
1252                }));
1253            }
1254
1255            let trades = data
1256                .request_trade_ticks(
1257                    instruments[0].id(),
1258                    &markets[0].condition_id,
1259                    definitions[0].token_id.as_str(),
1260                    definitions[0].price_precision,
1261                    6,
1262                    None,
1263                    None,
1264                    Some(1),
1265                )
1266                .await
1267                .unwrap();
1268            eprintln!(
1269                "Validated {version} market {id}: 2 instruments, matching Gamma/CLOB identity, {} historical trades",
1270                trades.len()
1271            );
1272        }
1273    }
1274
1275    #[rstest]
1276    #[case(Some("v1"), true)]
1277    #[case(Some("v2"), true)]
1278    #[case(None, false)]
1279    #[case(Some("v3"), false)]
1280    #[case(Some("V1"), false)]
1281    fn test_market_protocol_controls_discovery(
1282        #[case] version: Option<&str>,
1283        #[case] supported: bool,
1284        #[values("gamma_market_protocol_v1.json", "gamma_market_protocol_v2.json")] fixture: &str,
1285        #[values(false, true)] empty_ids: bool,
1286    ) {
1287        let mut market = load_fee_market(fixture);
1288        market.version = version.map(str::to_string);
1289        market.position_ids = Some(from_str(&market.clob_token_ids).unwrap());
1290        if empty_ids {
1291            market.clob_token_ids = "[]".into();
1292            market.position_ids = Some(Vec::new());
1293        }
1294
1295        let condition_id = market.condition_id.clone();
1296        let (instruments, transient) = parse_markets_with_transient(&[market.clone()], 1.into());
1297        assert_eq!(
1298            instruments.len(),
1299            if supported && !empty_ids { 2 } else { 0 }
1300        );
1301        assert_eq!(
1302            transient,
1303            if supported && empty_ids {
1304                vec![condition_id]
1305            } else {
1306                vec![]
1307            }
1308        );
1309
1310        if supported && !empty_ids {
1311            for instrument in instruments {
1312                let InstrumentAny::BinaryOption(binary) = instrument else {
1313                    panic!("expected binary option")
1314                };
1315
1316                assert_eq!(
1317                    binary.info.as_ref().unwrap().get_str("market_version"),
1318                    version
1319                );
1320            }
1321        } else if !supported {
1322            let error = parse_gamma_market(&market).unwrap_err();
1323            assert_eq!(
1324                error.to_string(),
1325                format!(
1326                    "Unsupported Polymarket data protocol {}; expected v1 or v2",
1327                    version.unwrap_or("missing"),
1328                )
1329            );
1330        }
1331    }
1332
1333    #[rstest]
1334    fn test_live_instrument_funnel_retains_gamma_metadata() {
1335        let raw = include_str!("../../test_data/gamma_market_metadata.json");
1336        let market: GammaMarket = serde_json::from_str(raw).unwrap();
1337        let expected = raw.trim();
1338        let (instruments, transient) = parse_markets_with_transient(&[market], 1.into());
1339        assert_eq!(instruments.len(), 2);
1340        assert_eq!(transient, Vec::<String>::new());
1341
1342        for instrument in instruments {
1343            let InstrumentAny::BinaryOption(binary) = instrument else {
1344                unreachable!()
1345            };
1346
1347            assert_eq!(binary.event_id.map(|id| id.as_str()), Some("event-456"));
1348            let info = binary.info.unwrap();
1349            assert_eq!(info.get_str("gamma_market"), Some(expected));
1350            assert_eq!(info.get_bool("closed"), Some(false));
1351        }
1352    }
1353
1354    #[rstest]
1355    fn test_event_discovery_retains_parent_metadata() {
1356        let raw = include_str!("../../test_data/gamma_event.json");
1357        let events: Vec<GammaEvent> = serde_json::from_str(raw).unwrap();
1358        let expected: Vec<Value> = serde_json::from_str(raw).unwrap();
1359        let markets = flatten_event_markets(events);
1360        assert_eq!(markets.len(), 2);
1361
1362        for market in &markets {
1363            let parent = market.parent_event.as_ref().unwrap();
1364            let expected_event = expected
1365                .iter()
1366                .find(|event| event["id"] == parent.id)
1367                .unwrap();
1368            let expected_market = expected_event["markets"]
1369                .as_array()
1370                .unwrap()
1371                .iter()
1372                .find(|raw| raw["id"] == market.id)
1373                .unwrap();
1374            assert_eq!(
1375                serde_json::from_str::<Value>(&parent.raw).unwrap(),
1376                *expected_event
1377            );
1378            assert_eq!(
1379                serde_json::from_str::<Value>(&market.raw).unwrap(),
1380                *expected_market
1381            );
1382            let defs = parse_gamma_market(market).unwrap();
1383            for def in defs {
1384                assert_eq!(def.event_id.unwrap().as_str(), parent.id);
1385                assert_eq!(
1386                    def.gamma_event.as_ref().unwrap().as_str(),
1387                    Some(parent.raw.as_str())
1388                );
1389                assert_eq!(def.gamma_market, market.raw);
1390                let instrument = create_instrument_from_def(&def, 1.into()).unwrap();
1391
1392                let InstrumentAny::BinaryOption(binary) = instrument else {
1393                    unreachable!()
1394                };
1395
1396                let info = binary.info.unwrap();
1397                assert_eq!(binary.event_id.unwrap().as_str(), parent.id);
1398                assert_eq!(info.get_str("gamma_event"), Some(parent.raw.as_str()));
1399                assert_eq!(info.get_str("gamma_market"), Some(market.raw.as_str()));
1400            }
1401        }
1402    }
1403
1404    #[rstest]
1405    #[case(1)]
1406    #[case(8)]
1407    #[case(32)]
1408    fn test_event_metadata_shares_storage_across_instruments_and_clones(
1409        #[case] market_count: usize,
1410    ) {
1411        let mut events: Vec<GammaEvent> =
1412            serde_json::from_str(include_str!("../../test_data/gamma_event.json")).unwrap();
1413        let mut event = events.remove(0);
1414        let market = event.markets[0].clone();
1415        event.markets = (0..market_count)
1416            .map(|index| {
1417                let mut market = market.clone();
1418                market.id = format!("market-{index}");
1419                market.condition_id = format!("condition-{index}");
1420                market.clob_token_ids = serde_json::to_string(&[
1421                    format!("{}", 2 * index + 1),
1422                    format!("{}", 2 * index + 2),
1423                ])
1424                .unwrap();
1425                market
1426            })
1427            .collect();
1428
1429        let expected = event.raw.clone();
1430        let markets = flatten_event_markets(vec![event]);
1431        let (instruments, transient) = parse_markets_with_transient(&markets, 1.into());
1432        let event = instruments[0].info().unwrap().get("gamma_event").unwrap();
1433        let mut pointers = std::collections::HashSet::new();
1434        let mut cache = Cache::default();
1435
1436        assert_eq!(instruments.len(), 2 * market_count);
1437        assert_eq!(transient, Vec::<String>::new());
1438        assert_eq!(event.as_str(), Some(expected.as_str()));
1439
1440        for instrument in &instruments {
1441            cache.add_instrument(instrument.clone()).unwrap();
1442            let cloned = cache.instrument(&instrument.id()).unwrap().clone();
1443            for instrument in [instrument, &cloned] {
1444                let info = instrument.info().unwrap();
1445                let value = info.get("gamma_event").unwrap();
1446                pointers.insert(value.as_str().unwrap().as_ptr());
1447                assert!(std::ptr::eq(value, event));
1448                assert_eq!(info.get_bool("closed"), Some(false));
1449            }
1450        }
1451
1452        assert_eq!(pointers.len(), 1);
1453    }
1454
1455    #[rstest]
1456    fn test_event_metadata_keeps_distinct_snapshots_with_the_same_id() {
1457        let mut events: Vec<GammaEvent> =
1458            serde_json::from_str(include_str!("../../test_data/gamma_event.json")).unwrap();
1459        let event = events.remove(0);
1460        let mut updated = event.clone();
1461        let mut value: Value = serde_json::from_str(&updated.raw).unwrap();
1462        value["snapshot"] = Value::String("updated".to_string());
1463        updated.raw = serde_json::to_string(&value).unwrap();
1464        let original_raw = event.raw.clone();
1465        let updated_raw = updated.raw.clone();
1466        let markets_per_event = event.markets.len();
1467        let markets = flatten_event_markets(vec![event, updated]);
1468        let (instruments, transient) = parse_markets_with_transient(&markets, 1.into());
1469        let snapshots = instruments
1470            .chunks(2 * markets_per_event)
1471            .collect::<Vec<_>>();
1472
1473        assert_eq!(transient, Vec::<String>::new());
1474        assert_eq!(snapshots.len(), 2);
1475
1476        for (snapshot, expected) in snapshots.iter().zip([original_raw, updated_raw]) {
1477            let event = snapshot[0].info().unwrap().get("gamma_event").unwrap();
1478            assert_eq!(event.as_str(), Some(expected.as_str()));
1479
1480            for instrument in *snapshot {
1481                assert!(std::ptr::eq(
1482                    instrument.info().unwrap().get("gamma_event").unwrap(),
1483                    event
1484                ));
1485            }
1486        }
1487
1488        assert!(!std::ptr::eq(
1489            snapshots[0][0].info().unwrap().get("gamma_event").unwrap(),
1490            snapshots[1][0].info().unwrap().get("gamma_event").unwrap()
1491        ));
1492    }
1493
1494    #[rstest]
1495    #[case(false)]
1496    #[case(true)]
1497    fn test_markets_response_preserves_decimal_precision(#[case] enveloped: bool) {
1498        let market = include_str!("../../test_data/decimal_precision_market.json");
1499        let array = format!("[{market}]");
1500        let raw = if enveloped {
1501            format!("{{\"data\":{array}}}")
1502        } else {
1503            array
1504        };
1505        let markets =
1506            parse_gamma_markets_response(&serde_json::from_str::<Box<RawValue>>(&raw).unwrap())
1507                .unwrap();
1508        assert_eq!(markets.len(), 1);
1509        assert_eq!(
1510            markets[0].best_bid,
1511            Some(dec!(0.1234567890123456789012345678))
1512        );
1513        assert_eq!(markets[0].volume_num, Some(dec!(12345678901.123457)));
1514        assert_eq!(
1515            markets[0].fee_schedule.as_ref().unwrap().rate,
1516            dec!(0.1234567890123456789012345678)
1517        );
1518    }
1519}