Skip to main content

nautilus_polymarket/
providers.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//! Instrument provider for the Polymarket adapter.
17
18use std::{collections::HashMap, fmt::Debug, sync::Arc};
19
20use ahash::{AHashMap, AHashSet};
21use alloy_primitives::{B256, U256};
22use async_trait::async_trait;
23use nautilus_common::providers::{InstrumentProvider, InstrumentStore};
24use nautilus_model::{
25    identifiers::InstrumentId,
26    instruments::{Instrument, InstrumentAny},
27};
28use rust_decimal::Decimal;
29use ustr::Ustr;
30
31use crate::{
32    common::{
33        consts::{GAMMA_CONDITION_IDS_BATCH_SIZE, POLYMARKET_VENUE},
34        parse::parse_decimal_exact,
35    },
36    config::PolymarketInstrumentProviderConfig,
37    filters::InstrumentFilter,
38    http::{
39        gamma::PolymarketGammaHttpClient,
40        models::GammaTag,
41        query::{GetGammaEventsParams, GetGammaMarketsParams},
42    },
43};
44
45/// Provides Polymarket instruments via the Gamma API.
46///
47/// Wraps [`PolymarketGammaHttpClient`] with an [`InstrumentStore`] and a
48/// token_id index for resolving WebSocket asset IDs to instruments.
49///
50/// Optional [`InstrumentFilter`]s control which instruments are loaded
51/// during `load_all()`. Without filters, all active markets are fetched.
52pub struct PolymarketInstrumentProvider {
53    store: InstrumentStore,
54    http_client: PolymarketGammaHttpClient,
55    token_index: AHashMap<Ustr, InstrumentId>,
56    filters: Vec<Arc<dyn InstrumentFilter>>,
57    config: PolymarketInstrumentProviderConfig,
58}
59
60impl Debug for PolymarketInstrumentProvider {
61    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
62        f.debug_struct(stringify!(PolymarketInstrumentProvider))
63            .field("store", &self.store)
64            .field("http_client", &self.http_client)
65            .field("token_index_len", &self.token_index.len())
66            .field("filters", &self.filters)
67            .field("config", &self.config)
68            .finish()
69    }
70}
71
72impl PolymarketInstrumentProvider {
73    /// Creates a new [`PolymarketInstrumentProvider`] with an empty store and no filters.
74    ///
75    /// # Errors
76    ///
77    /// Returns an error if selections contain duplicates or Gamma filters are invalid.
78    pub fn new(
79        http_client: PolymarketGammaHttpClient,
80        config: Option<PolymarketInstrumentProviderConfig>,
81    ) -> anyhow::Result<Self> {
82        Self::with_filters(http_client, config, Vec::new())
83    }
84
85    /// Creates a new [`PolymarketInstrumentProvider`] with multiple filters.
86    ///
87    /// # Errors
88    ///
89    /// Returns an error if selections contain duplicates or Gamma filters are invalid.
90    pub fn with_filters(
91        http_client: PolymarketGammaHttpClient,
92        config: Option<PolymarketInstrumentProviderConfig>,
93        filters: Vec<Arc<dyn InstrumentFilter>>,
94    ) -> anyhow::Result<Self> {
95        let config = config.unwrap_or_default();
96        config.validate()?;
97
98        Ok(Self {
99            store: InstrumentStore::new(),
100            http_client,
101            token_index: AHashMap::new(),
102            filters,
103            config,
104        })
105    }
106
107    /// Creates a new [`PolymarketInstrumentProvider`] with a single filter.
108    ///
109    /// # Errors
110    ///
111    /// Returns an error if selections contain duplicates or Gamma filters are invalid.
112    pub fn with_filter(
113        http_client: PolymarketGammaHttpClient,
114        config: Option<PolymarketInstrumentProviderConfig>,
115        filter: Arc<dyn InstrumentFilter>,
116    ) -> anyhow::Result<Self> {
117        Self::with_filters(http_client, config, vec![filter])
118    }
119
120    /// Adds an instrument filter for subsequent `load_all()` calls.
121    pub fn add_filter(&mut self, filter: Arc<dyn InstrumentFilter>) {
122        self.filters.push(filter);
123    }
124
125    /// Clears all instrument filters, reverting to bulk load behavior.
126    pub fn clear_filters(&mut self) {
127        self.filters.clear();
128    }
129
130    /// Returns the instrument for the given token ID, if found.
131    #[must_use]
132    pub fn get_by_token_id(&self, token_id: &Ustr) -> Option<&InstrumentAny> {
133        let instrument_id = self.token_index.get(token_id)?;
134        self.store.find(instrument_id)
135    }
136
137    /// Builds a frozen snapshot mapping token IDs to instruments.
138    ///
139    /// Used to provide the WS handler task with a read-only lookup
140    /// table after instruments have been loaded.
141    #[must_use]
142    pub fn build_token_map(&self) -> AHashMap<Ustr, InstrumentAny> {
143        self.token_index
144            .iter()
145            .filter_map(|(token_id, instrument_id)| {
146                self.store
147                    .find(instrument_id)
148                    .map(|inst| (*token_id, inst.clone()))
149            })
150            .collect()
151    }
152
153    /// Loads instruments for the given slugs additively into the store.
154    ///
155    /// Unlike [`Self::load_all`], this does **not** clear existing instruments or
156    /// mark the store as initialized, allowing incremental loading of
157    /// slug-based markets alongside bulk data.
158    ///
159    /// # Errors
160    ///
161    /// Returns an error if the HTTP request or parsing fails.
162    pub async fn load_by_slugs(&mut self, slugs: Vec<String>) -> anyhow::Result<()> {
163        let instruments = self.http_client.request_instruments_by_slugs(slugs).await?;
164        self.add_instruments(instruments);
165
166        Ok(())
167    }
168
169    /// Returns a clone of the configured instrument filters.
170    #[must_use]
171    pub fn filters(&self) -> Vec<Arc<dyn InstrumentFilter>> {
172        self.filters.clone()
173    }
174
175    /// Returns a reference to the underlying HTTP client.
176    #[must_use]
177    pub fn http_client(&self) -> &PolymarketGammaHttpClient {
178        &self.http_client
179    }
180
181    /// Returns the configured provider config.
182    #[must_use]
183    pub fn config(&self) -> &PolymarketInstrumentProviderConfig {
184        &self.config
185    }
186
187    /// Fetches available tags from the Gamma API.
188    pub async fn list_tags(&self) -> anyhow::Result<Vec<GammaTag>> {
189        self.http_client.request_tags().await
190    }
191
192    pub fn add_instruments(&mut self, instruments: Vec<InstrumentAny>) {
193        for inst in &instruments {
194            self.token_index
195                .insert(Ustr::from(inst.raw_symbol().as_str()), inst.id());
196        }
197        self.store.add_bulk(instruments);
198    }
199
200    /// Loads instruments for the given event slugs additively into the store.
201    ///
202    /// Unlike [`Self::load_all`], this does **not** clear existing instruments or
203    /// mark the store as initialized, allowing incremental loading of
204    /// event-scoped markets alongside bulk data.
205    pub async fn load_by_event_slugs(&mut self, slugs: Vec<String>) -> anyhow::Result<()> {
206        let instruments = self
207            .http_client
208            .request_instruments_by_event_slugs(slugs)
209            .await?;
210        self.add_instruments(instruments);
211        Ok(())
212    }
213
214    /// Loads instruments for the given Gamma series IDs additively into the store.
215    ///
216    /// Resolves each series to its active, unresolved events and loads their
217    /// markets. Unlike [`Self::load_all`], this does **not** clear existing
218    /// instruments or mark the store as initialized.
219    pub async fn load_by_series_ids(&mut self, series_ids: Vec<u64>) -> anyhow::Result<()> {
220        let instruments = self
221            .http_client
222            .request_instruments_by_event_params(series_events_params(series_ids))
223            .await?;
224        self.add_instruments(instruments);
225        Ok(())
226    }
227
228    /// Initializes the provider using its configured bootstrap scope.
229    pub async fn initialize(&mut self, reload: bool) -> anyhow::Result<()> {
230        if self.store.is_initialized() && !reload {
231            return Ok(());
232        }
233
234        let should_load_all = has_bootstrap_scope(&self.config, &self.filters);
235        let has_load_ids = self.config.has_load_ids();
236
237        if !should_load_all && !has_load_ids {
238            if self.config.log_warnings {
239                log::warn!(
240                    "No Polymarket instrument bootstrap configured: set instrument_config.load_all, instrument_config.load_ids, instrument_config.filters, instrument_config.event_slugs, instrument_config.market_slugs, instrument_config.event_slug_builder, or instrument_config.series_ids, or register an instrument filter"
241                );
242            }
243            return Ok(());
244        }
245
246        // Registered `InstrumentFilter`s take precedence over the Gamma filter map,
247        // so say when the map is being dropped rather than ignoring it silently.
248        if self.config.log_warnings
249            && !self.filters.is_empty()
250            && self.config.has_nonempty_filters()
251        {
252            log::warn!(
253                "Registered instrument filters take precedence: instrument_config.filters is ignored for this bootstrap"
254            );
255        }
256
257        if should_load_all {
258            self.load_scoped_all().await?;
259        }
260
261        if has_load_ids {
262            // Deliberately not passed `config.filters`: `load_ids` names instruments
263            // explicitly, so intersecting it with the filter map would silently drop
264            // any ID that falls outside those filters. The scopes are additive, and
265            // an explicitly requested instrument is requested unconditionally.
266            let load_ids = self.config.load_ids.clone().unwrap_or_default();
267            self.load_ids(&load_ids, None).await?;
268        }
269
270        // Registered filters take precedence over the `filters` map, so a map paired with an
271        // accept-only filter loads nothing while `should_load_all()` still reports true. Latching
272        // empty would strand the provider against a later `initialize(false)`.
273        let sourced_by_registered_filters = !has_load_ids && !self.filters.is_empty();
274
275        if sourced_by_registered_filters && self.store.count() == 0 {
276            return Ok(());
277        }
278
279        self.store.set_initialized();
280        Ok(())
281    }
282
283    async fn load_scoped_all(&mut self) -> anyhow::Result<()> {
284        let event_slugs = self.config.resolve_event_slugs()?;
285        let market_slugs = self
286            .config
287            .market_slugs
288            .clone()
289            .unwrap_or_default()
290            .into_iter()
291            .filter(|slug| !slug.trim().is_empty())
292            .collect::<Vec<_>>();
293        let series_ids = self.config.series_ids.clone().unwrap_or_default();
294
295        // The clearing bulk load must run before the additive scoped loads.
296        // Explicit scoping never broadens into an unfiltered full-universe fetch,
297        // but every filter-driven query is bounded, so it composes with explicit
298        // scopes instead of being silently dropped. Registered `InstrumentFilter`s
299        // count here just as the Gamma filter map does, otherwise this path would
300        // drop them while `fetch_configured_instruments` keeps them, and the
301        // bootstrap and interval-refresh universes would diverge.
302        //
303        // This deliberately does not go through `load_all`, which marks the store
304        // initialized on completion. The additive scopes below are still
305        // outstanding at this point, and a failure in one of them would otherwise
306        // leave an initialized-but-incomplete store that makes a subsequent
307        // `initialize(false)` short-circuit and skip the missing scopes for good.
308        if !self.config.has_explicit_scope()
309            || self.config.has_nonempty_filters()
310            || !self.filters.is_empty()
311        {
312            let filters = self.config.filters.clone();
313            let instruments = self.fetch_bulk_instruments(filters.as_ref()).await?;
314            self.replace_instruments(instruments);
315        }
316
317        if !series_ids.is_empty() {
318            self.load_by_series_ids(series_ids).await?;
319        }
320
321        if !event_slugs.is_empty() {
322            self.load_by_event_slugs(event_slugs).await?;
323        }
324
325        if !market_slugs.is_empty() {
326            self.load_by_slugs(market_slugs).await?;
327        }
328
329        Ok(())
330    }
331
332    /// Fetches the bulk instrument universe without mutating provider state.
333    ///
334    /// Registered [`InstrumentFilter`]s take precedence; otherwise a non-empty
335    /// Gamma filter map bounds the query, and an absent or empty map falls back
336    /// to the full universe.
337    async fn fetch_bulk_instruments(
338        &self,
339        filters: Option<&HashMap<String, String>>,
340    ) -> anyhow::Result<Vec<InstrumentAny>> {
341        if !self.filters.is_empty() {
342            return fetch_instruments(&self.http_client, &self.filters).await;
343        }
344
345        match filters {
346            Some(map) if !map.is_empty() => {
347                let params = build_gamma_params_from_hashmap(map)?;
348                self.http_client.request_instruments_by_params(params).await
349            }
350            _ => self.http_client.request_instruments().await,
351        }
352    }
353
354    /// Replaces the store contents, leaving the initialized flag untouched.
355    ///
356    /// Callers that complete a full bootstrap are responsible for marking the
357    /// store initialized once every scope has succeeded.
358    fn replace_instruments(&mut self, instruments: Vec<InstrumentAny>) {
359        self.store.clear();
360        self.token_index.clear();
361        self.add_instruments(instruments);
362    }
363}
364
365/// Fetches instruments from the Gamma API, respecting any configured filters.
366pub async fn fetch_instruments(
367    http_client: &PolymarketGammaHttpClient,
368    filters: &[Arc<dyn InstrumentFilter>],
369) -> anyhow::Result<Vec<InstrumentAny>> {
370    if filters.is_empty() {
371        return http_client.request_instruments().await;
372    }
373
374    let mut instruments = Vec::new();
375
376    for filter in filters {
377        if let Some(slugs) = filter.market_slugs()
378            && !slugs.is_empty()
379        {
380            let result = http_client.request_instruments_by_slugs(slugs).await?;
381            instruments.extend(result);
382        }
383
384        if let Some(event_slugs) = filter.event_slugs()
385            && !event_slugs.is_empty()
386        {
387            let result = http_client
388                .request_instruments_by_event_slugs(event_slugs)
389                .await?;
390            instruments.extend(result);
391        }
392
393        if let Some(params) = filter.query_params() {
394            let result = http_client.request_instruments_by_params(params).await?;
395            instruments.extend(result);
396        }
397
398        if let Some(event_queries) = filter.event_queries() {
399            for (event_slug, params) in event_queries {
400                let result = http_client
401                    .request_instruments_by_event_query(&event_slug, params)
402                    .await?;
403                instruments.extend(result);
404            }
405        }
406
407        if let Some(params) = filter.event_params() {
408            let result = http_client
409                .request_instruments_by_event_params(params)
410                .await?;
411            instruments.extend(result);
412        }
413
414        if let Some(params) = filter.search_params() {
415            let result = http_client.request_instruments_by_search(params).await?;
416            instruments.extend(result);
417        }
418    }
419
420    let mut seen = AHashSet::new();
421    instruments.retain(|inst| seen.insert(inst.id()));
422    instruments.retain(|inst| filters.iter().all(|f| f.accept(inst)));
423
424    Ok(instruments)
425}
426
427/// Fetches instruments using the configured provider bootstrap scope without
428/// mutating any provider state.
429pub async fn fetch_configured_instruments(
430    http_client: &PolymarketGammaHttpClient,
431    config: &PolymarketInstrumentProviderConfig,
432    filters: &[Arc<dyn InstrumentFilter>],
433) -> anyhow::Result<Vec<InstrumentAny>> {
434    config.validate()?;
435
436    let mut instruments = Vec::new();
437
438    if has_bootstrap_scope(config, filters) {
439        let has_explicit_scope = config.has_explicit_scope();
440        let event_slugs = config.resolve_event_slugs()?;
441
442        let market_slugs = config
443            .market_slugs
444            .clone()
445            .unwrap_or_default()
446            .into_iter()
447            .filter(|slug| !slug.trim().is_empty())
448            .collect::<Vec<_>>();
449
450        let series_ids = config.series_ids.clone().unwrap_or_default();
451
452        // Explicit scoping never broadens into an unfiltered full-universe
453        // fetch, but every filter-driven query is bounded, so it composes with
454        // explicit series and slug scopes instead of being silently dropped.
455        // This mirrors `load_scoped_all`, which the interval refresh and
456        // `request_instruments` paths must stay consistent with.
457        if !filters.is_empty() {
458            instruments.extend(fetch_instruments(http_client, filters).await?);
459        } else if let Some(map) = config.filters.as_ref().filter(|map| !map.is_empty()) {
460            let params = build_gamma_params_from_hashmap(map)?;
461            instruments.extend(http_client.request_instruments_by_params(params).await?);
462        } else if !has_explicit_scope {
463            instruments.extend(http_client.request_instruments().await?);
464        }
465
466        if !series_ids.is_empty() {
467            instruments.extend(
468                http_client
469                    .request_instruments_by_event_params(series_events_params(series_ids))
470                    .await?,
471            );
472        }
473
474        if !event_slugs.is_empty() {
475            instruments.extend(
476                http_client
477                    .request_instruments_by_event_slugs(event_slugs)
478                    .await?,
479            );
480        }
481
482        if !market_slugs.is_empty() {
483            instruments.extend(
484                http_client
485                    .request_instruments_by_slugs(market_slugs)
486                    .await?,
487            );
488        }
489    }
490
491    if config.has_load_ids() {
492        // Queried by condition ID alone. Merging `config.filters` in here would
493        // intersect an explicit scope with a filter scope, so an ID outside those
494        // filters would never load despite being named directly. Mirrors the
495        // `load_ids` call in `initialize`.
496        let condition_ids = config
497            .load_ids
498            .clone()
499            .unwrap_or_default()
500            .into_iter()
501            .map(|id| validated_condition_id(&id))
502            .collect::<anyhow::Result<AHashSet<_>>>()?
503            .into_iter()
504            .collect::<Vec<_>>();
505
506        for chunk in condition_ids.chunks(GAMMA_CONDITION_IDS_BATCH_SIZE) {
507            let params = GetGammaMarketsParams {
508                condition_ids: Some(chunk.to_vec()),
509                ..Default::default()
510            };
511            instruments.extend(http_client.request_instruments_by_params(params).await?);
512        }
513    }
514
515    // Deduplicated but NOT filtered by `accept` here. `fetch_instruments` already
516    // applies acceptance to the results of filter-driven queries, which is the only
517    // place it belongs: applying it again across the whole collection would let a
518    // registered filter reject series, slug, and ID instruments that the provider's
519    // `load_scoped_all` adds unconditionally, so a refresh would silently drop
520    // instruments the bootstrap had loaded.
521    let mut seen = AHashSet::new();
522    instruments.retain(|inst| seen.insert(inst.id()));
523    Ok(instruments)
524}
525
526// Registered filters live on the provider, not the config, so the config predicate alone cannot
527// see them. Source methods are deliberately not evaluated: they are documented as re-evaluated
528// each load cycle, so probing here would consume a batch the fetch then misses.
529fn has_bootstrap_scope(
530    config: &PolymarketInstrumentProviderConfig,
531    filters: &[Arc<dyn InstrumentFilter>],
532) -> bool {
533    config.should_load_all() || !filters.is_empty()
534}
535
536/// Builds the Gamma events query that resolves series IDs to their active,
537/// unresolved events.
538fn series_events_params(series_ids: Vec<u64>) -> GetGammaEventsParams {
539    GetGammaEventsParams {
540        series_id: Some(series_ids),
541        active: Some(true),
542        closed: Some(false),
543        ..Default::default()
544    }
545}
546
547/// Extracts the condition ID from an instrument symbol.
548///
549/// Polymarket instrument symbols follow the pattern `{condition_id}-{token_id}`.
550/// The condition_id is a hex string (e.g. `0xabc123...`) and the token_id is a
551/// large decimal number. This extracts the condition_id by splitting at the last `-`.
552pub fn extract_condition_id(instrument_id: &InstrumentId) -> anyhow::Result<String> {
553    let symbol = instrument_id.symbol.as_str();
554    symbol
555        .rfind('-')
556        .map(|idx| symbol[..idx].to_string())
557        .ok_or_else(|| {
558            anyhow::anyhow!("Cannot extract condition_id from symbol '{symbol}': no '-' separator")
559        })
560}
561
562pub(crate) fn validated_condition_id(instrument_id: &InstrumentId) -> anyhow::Result<String> {
563    let parts = instrument_id.symbol.as_str().rsplit_once('-');
564    anyhow::ensure!(
565        instrument_id.venue == *POLYMARKET_VENUE
566            && parts.is_some_and(|(condition_id, token_id)| {
567                condition_id.starts_with("0x")
568                    && condition_id.parse::<B256>().is_ok()
569                    && !token_id.is_empty()
570                    && token_id.bytes().all(|byte| byte.is_ascii_digit())
571                    && token_id.parse::<U256>().is_ok()
572            }),
573        "Invalid Polymarket instrument ID {instrument_id}; expected <0x-prefixed 32-byte condition ID>-<decimal uint256 token ID>.POLYMARKET"
574    );
575    extract_condition_id(instrument_id)
576}
577
578/// Extracts the token ID from an instrument symbol.
579///
580/// Polymarket instrument symbols follow the pattern `{condition_id}-{token_id}`. This extracts the
581/// token_id by splitting at the last `-`.
582pub(crate) fn extract_token_id(instrument_id: &InstrumentId) -> anyhow::Result<String> {
583    let symbol = instrument_id.symbol.as_str();
584    symbol
585        .rsplit_once('-')
586        .map(|(_, token_id)| token_id.to_string())
587        .ok_or_else(|| {
588            anyhow::anyhow!("Cannot extract token_id from symbol '{symbol}': no '-' separator")
589        })
590}
591
592/// Builds validated market keyset parameters from string key/value filters.
593///
594/// # Errors
595///
596/// Returns an error if keys are unknown, values are malformed, or filter combinations are invalid.
597pub fn build_gamma_params_from_hashmap(
598    map: &HashMap<String, String>,
599) -> anyhow::Result<GetGammaMarketsParams> {
600    for key in map.keys() {
601        match key.as_str() {
602            "is_active"
603            | "active"
604            | "closed"
605            | "archived"
606            | "id"
607            | "limit"
608            | "offset"
609            | "order"
610            | "ascending"
611            | "slug"
612            | "clob_token_ids"
613            | "condition_ids"
614            | "question_ids"
615            | "market_maker_address"
616            | "liquidity_num_min"
617            | "liquidity_num_max"
618            | "volume_num_min"
619            | "volume_num_max"
620            | "start_date_min"
621            | "start_date_max"
622            | "end_date_min"
623            | "end_date_max"
624            | "tag_id"
625            | "related_tags"
626            | "tag_match"
627            | "decimalized"
628            | "cyom"
629            | "rfq_enabled"
630            | "uma_resolution_status"
631            | "game_id"
632            | "sports_market_types"
633            | "include_tag"
634            | "locale"
635            | "max_markets" => {}
636            _ => anyhow::bail!("Unknown Gamma market filter key '{key}'"),
637        }
638    }
639
640    let mut params = GetGammaMarketsParams::default();
641
642    if map
643        .get("is_active")
644        .map(|value| parse_gamma_filter_bool("market", "is_active", value))
645        .transpose()?
646        .unwrap_or(false)
647    {
648        params.active = Some(true);
649        params.archived = Some(false);
650        params.closed = Some(false);
651    }
652
653    if let Some(v) = map.get("active") {
654        params.active = Some(parse_gamma_filter_bool("market", "active", v)?);
655    }
656
657    if let Some(v) = map.get("closed") {
658        params.closed = Some(parse_gamma_filter_bool("market", "closed", v)?);
659    }
660
661    if let Some(v) = map.get("archived") {
662        params.archived = Some(parse_gamma_filter_bool("market", "archived", v)?);
663    }
664
665    if let Some(v) = map.get("id") {
666        params.id = Some(parse_gamma_numeric_filter_list("market", "id", v)?);
667    }
668
669    if let Some(v) = map.get("slug") {
670        params.slug = Some(parse_gamma_filter_list("market", "slug", v)?);
671    }
672
673    if let Some(v) = map.get("tag_id") {
674        params.tag_id = Some(parse_gamma_numeric_filter_list("market", "tag_id", v)?);
675    }
676
677    if let Some(v) = map.get("condition_ids") {
678        params.condition_ids = Some(parse_gamma_filter_list("market", "condition_ids", v)?);
679    }
680
681    if let Some(v) = map.get("clob_token_ids") {
682        params.clob_token_ids = Some(parse_gamma_filter_list("market", "clob_token_ids", v)?);
683    }
684
685    if let Some(v) = map.get("question_ids") {
686        params.question_ids = Some(parse_gamma_filter_list("market", "question_ids", v)?);
687    }
688
689    if let Some(v) = map.get("market_maker_address") {
690        params.market_maker_address = Some(parse_gamma_filter_list(
691            "market",
692            "market_maker_address",
693            v,
694        )?);
695    }
696
697    if let Some(v) = map.get("liquidity_num_min") {
698        params.liquidity_num_min = Some(parse_gamma_filter_decimal(
699            "market",
700            "liquidity_num_min",
701            v,
702        )?);
703    }
704
705    if let Some(v) = map.get("liquidity_num_max") {
706        params.liquidity_num_max = Some(parse_gamma_filter_decimal(
707            "market",
708            "liquidity_num_max",
709            v,
710        )?);
711    }
712
713    if let Some(v) = map.get("volume_num_min") {
714        params.volume_num_min = Some(parse_gamma_filter_decimal("market", "volume_num_min", v)?);
715    }
716
717    if let Some(v) = map.get("volume_num_max") {
718        params.volume_num_max = Some(parse_gamma_filter_decimal("market", "volume_num_max", v)?);
719    }
720
721    if let Some(v) = map.get("order") {
722        params.order = Some(parse_gamma_filter_string("market", "order", v)?);
723    }
724
725    if let Some(v) = map.get("ascending") {
726        params.ascending = Some(parse_gamma_filter_bool("market", "ascending", v)?);
727    }
728
729    if let Some(v) = map.get("limit") {
730        params.limit = Some(parse_gamma_filter_u32("market", "limit", v)?.min(100));
731    }
732
733    if let Some(v) = map.get("offset") {
734        params.offset = Some(parse_gamma_filter_u32("market", "offset", v)?);
735    }
736
737    if let Some(v) = map.get("start_date_min") {
738        params.start_date_min = Some(parse_gamma_filter_string("market", "start_date_min", v)?);
739    }
740
741    if let Some(v) = map.get("start_date_max") {
742        params.start_date_max = Some(parse_gamma_filter_string("market", "start_date_max", v)?);
743    }
744
745    if let Some(v) = map.get("end_date_min") {
746        params.end_date_min = Some(parse_gamma_filter_string("market", "end_date_min", v)?);
747    }
748
749    if let Some(v) = map.get("end_date_max") {
750        params.end_date_max = Some(parse_gamma_filter_string("market", "end_date_max", v)?);
751    }
752
753    if let Some(v) = map.get("related_tags") {
754        params.related_tags = Some(parse_gamma_filter_bool("market", "related_tags", v)?);
755    }
756
757    if let Some(v) = map.get("tag_match") {
758        params.tag_match = Some(parse_gamma_filter_string("market", "tag_match", v)?);
759    }
760
761    if let Some(v) = map.get("decimalized") {
762        params.decimalized = Some(parse_gamma_filter_bool("market", "decimalized", v)?);
763    }
764
765    if let Some(v) = map.get("cyom") {
766        params.cyom = Some(parse_gamma_filter_bool("market", "cyom", v)?);
767    }
768
769    if let Some(v) = map.get("rfq_enabled") {
770        params.rfq_enabled = Some(parse_gamma_filter_bool("market", "rfq_enabled", v)?);
771    }
772
773    if let Some(v) = map.get("uma_resolution_status") {
774        params.uma_resolution_status = Some(parse_gamma_filter_string(
775            "market",
776            "uma_resolution_status",
777            v,
778        )?);
779    }
780
781    if let Some(v) = map.get("game_id") {
782        params.game_id = Some(parse_gamma_filter_string("market", "game_id", v)?);
783    }
784
785    if let Some(v) = map.get("sports_market_types") {
786        params.sports_market_types =
787            Some(parse_gamma_filter_list("market", "sports_market_types", v)?);
788    }
789
790    if let Some(v) = map.get("include_tag") {
791        params.include_tag = Some(parse_gamma_filter_bool("market", "include_tag", v)?);
792    }
793
794    if let Some(v) = map.get("locale") {
795        params.locale = Some(parse_gamma_filter_string("market", "locale", v)?);
796    }
797
798    if let Some(v) = map.get("max_markets") {
799        params.max_markets = Some(parse_gamma_filter_u32("market", "max_markets", v)?);
800    }
801
802    params.validate_keyset().map_err(|e| anyhow::anyhow!(e))?;
803    Ok(params)
804}
805
806/// Builds validated event keyset parameters from string key/value filters.
807///
808/// # Errors
809///
810/// Returns an error if keys are unknown, values are malformed, or filter combinations are invalid.
811pub fn build_gamma_event_params_from_hashmap(
812    map: &HashMap<String, String>,
813) -> anyhow::Result<GetGammaEventsParams> {
814    for key in map.keys() {
815        match key.as_str() {
816            "is_active" | "active" | "closed" | "archived" | "id" | "slug" | "live"
817            | "featured" | "cyom" | "title_search" | "liquidity_min" | "liquidity_max"
818            | "volume_min" | "volume_max" | "start_date_min" | "start_date_max"
819            | "end_date_min" | "end_date_max" | "start_time_min" | "start_time_max" | "tag_id"
820            | "tag_slug" | "exclude_tag_id" | "related_tags" | "tag_match" | "series_id"
821            | "game_id" | "event_date" | "event_week" | "featured_order" | "recurrence"
822            | "created_by" | "parent_event_id" | "include_children" | "partner_slug"
823            | "include_chat" | "include_template" | "include_best_lines" | "locale" | "order"
824            | "ascending" | "limit" | "offset" | "max_events" => {}
825            _ => anyhow::bail!("Unknown Gamma event filter key '{key}'"),
826        }
827    }
828
829    let mut params = GetGammaEventsParams::default();
830
831    if map
832        .get("is_active")
833        .map(|value| parse_gamma_filter_bool("event", "is_active", value))
834        .transpose()?
835        .unwrap_or(false)
836    {
837        params.active = Some(true);
838        params.archived = Some(false);
839        params.closed = Some(false);
840    }
841
842    macro_rules! set_bool {
843        ($field:ident) => {
844            if let Some(value) = map.get(stringify!($field)) {
845                params.$field = Some(parse_gamma_filter_bool("event", stringify!($field), value)?);
846            }
847        };
848    }
849    macro_rules! set_string {
850        ($field:ident) => {
851            if let Some(value) = map.get(stringify!($field)) {
852                params.$field = Some(parse_gamma_filter_string(
853                    "event",
854                    stringify!($field),
855                    value,
856                )?);
857            }
858        };
859    }
860    macro_rules! set_decimal {
861        ($field:ident) => {
862            if let Some(value) = map.get(stringify!($field)) {
863                params.$field = Some(parse_gamma_filter_decimal(
864                    "event",
865                    stringify!($field),
866                    value,
867                )?);
868            }
869        };
870    }
871    macro_rules! set_u32 {
872        ($field:ident) => {
873            if let Some(value) = map.get(stringify!($field)) {
874                params.$field = Some(parse_gamma_filter_u32("event", stringify!($field), value)?);
875            }
876        };
877    }
878    macro_rules! set_u64 {
879        ($field:ident) => {
880            if let Some(value) = map.get(stringify!($field)) {
881                params.$field = Some(parse_gamma_filter_u64("event", stringify!($field), value)?);
882            }
883        };
884    }
885    macro_rules! set_strings {
886        ($field:ident) => {
887            if let Some(value) = map.get(stringify!($field)) {
888                params.$field = Some(parse_gamma_filter_list("event", stringify!($field), value)?);
889            }
890        };
891    }
892    macro_rules! set_u64s {
893        ($field:ident) => {
894            if let Some(value) = map.get(stringify!($field)) {
895                params.$field = Some(parse_gamma_numeric_filter_list(
896                    "event",
897                    stringify!($field),
898                    value,
899                )?);
900            }
901        };
902    }
903
904    set_bool!(active);
905    set_bool!(closed);
906    set_bool!(archived);
907    set_bool!(live);
908    set_bool!(featured);
909    set_bool!(cyom);
910    set_bool!(related_tags);
911    set_bool!(featured_order);
912    set_bool!(include_children);
913    set_bool!(include_chat);
914    set_bool!(include_template);
915    set_bool!(include_best_lines);
916    set_bool!(ascending);
917    set_strings!(slug);
918    set_strings!(created_by);
919    set_u64s!(id);
920    set_u64s!(tag_id);
921    set_u64s!(exclude_tag_id);
922    set_u64s!(series_id);
923    set_u64s!(game_id);
924    set_string!(title_search);
925    set_string!(start_date_min);
926    set_string!(start_date_max);
927    set_string!(end_date_min);
928    set_string!(end_date_max);
929    set_string!(start_time_min);
930    set_string!(start_time_max);
931    set_string!(tag_slug);
932    set_string!(tag_match);
933    set_string!(event_date);
934    set_string!(recurrence);
935    set_string!(partner_slug);
936    set_string!(locale);
937    set_string!(order);
938    set_decimal!(liquidity_min);
939    set_decimal!(liquidity_max);
940    set_decimal!(volume_min);
941    set_decimal!(volume_max);
942    set_u32!(event_week);
943    set_u32!(limit);
944    set_u32!(offset);
945    set_u32!(max_events);
946    set_u64!(parent_event_id);
947
948    params.validate_keyset().map_err(anyhow::Error::msg)?;
949    Ok(params)
950}
951
952fn parse_gamma_filter_bool(scope: &str, key: &str, value: &str) -> anyhow::Result<bool> {
953    if value.eq_ignore_ascii_case("true") {
954        Ok(true)
955    } else if value.eq_ignore_ascii_case("false") {
956        Ok(false)
957    } else {
958        anyhow::bail!("Gamma {scope} filter '{key}' must be true or false, was '{value}'")
959    }
960}
961
962fn parse_gamma_filter_u32(scope: &str, key: &str, value: &str) -> anyhow::Result<u32> {
963    value.parse::<u32>().map_err(|e| {
964        anyhow::anyhow!("Gamma {scope} filter '{key}' must be an unsigned integer: {e}")
965    })
966}
967
968fn parse_gamma_filter_u64(scope: &str, key: &str, value: &str) -> anyhow::Result<u64> {
969    value.parse::<u64>().map_err(|e| {
970        anyhow::anyhow!("Gamma {scope} filter '{key}' must be an unsigned integer: {e}")
971    })
972}
973
974fn parse_gamma_filter_decimal(scope: &str, key: &str, value: &str) -> anyhow::Result<Decimal> {
975    parse_decimal_exact(value)
976        .map_err(|e| anyhow::anyhow!("Gamma {scope} filter '{key}' must be a decimal number: {e}"))
977}
978
979fn parse_gamma_filter_list(scope: &str, key: &str, value: &str) -> anyhow::Result<Vec<String>> {
980    let values = value
981        .split(',')
982        .map(str::trim)
983        .map(str::to_string)
984        .collect::<Vec<_>>();
985
986    if values.is_empty() || values.iter().any(String::is_empty) {
987        anyhow::bail!("Gamma {scope} filter '{key}' must contain non-empty comma-separated values")
988    }
989
990    Ok(values)
991}
992
993fn parse_gamma_numeric_filter_list(
994    scope: &str,
995    key: &str,
996    value: &str,
997) -> anyhow::Result<Vec<u64>> {
998    parse_gamma_filter_list(scope, key, value)?
999        .into_iter()
1000        .map(|item| {
1001            item.parse::<u64>().map_err(|e| {
1002                anyhow::anyhow!(
1003                    "Gamma {scope} filter '{key}' values must be unsigned integers: {e}"
1004                )
1005            })
1006        })
1007        .collect()
1008}
1009
1010fn parse_gamma_filter_string(scope: &str, key: &str, value: &str) -> anyhow::Result<String> {
1011    if value.trim().is_empty() {
1012        anyhow::bail!("Gamma {scope} filter '{key}' cannot be empty")
1013    }
1014    Ok(value.to_string())
1015}
1016
1017/// Resolves a tag slug to a tag ID by querying the Gamma tags endpoint.
1018pub async fn resolve_tag_slug(
1019    client: &PolymarketGammaHttpClient,
1020    slug: &str,
1021) -> anyhow::Result<u64> {
1022    let tags = client.request_tags().await?;
1023    let tag_id = tags
1024        .iter()
1025        .find(|t| t.slug.as_deref() == Some(slug))
1026        .map(|t| t.id.as_str())
1027        .ok_or_else(|| anyhow::anyhow!("Tag slug '{slug}' not found"))?;
1028    tag_id
1029        .parse::<u64>()
1030        .map_err(|e| anyhow::anyhow!("Tag slug '{slug}' returned invalid ID '{tag_id}': {e}"))
1031}
1032
1033#[async_trait(?Send)]
1034impl InstrumentProvider for PolymarketInstrumentProvider {
1035    fn store(&self) -> &InstrumentStore {
1036        &self.store
1037    }
1038
1039    fn store_mut(&mut self) -> &mut InstrumentStore {
1040        &mut self.store
1041    }
1042
1043    async fn load_all(&mut self, filters: Option<&HashMap<String, String>>) -> anyhow::Result<()> {
1044        let instruments = self.fetch_bulk_instruments(filters).await?;
1045        self.replace_instruments(instruments);
1046        self.store.set_initialized();
1047
1048        Ok(())
1049    }
1050
1051    async fn load_ids(
1052        &mut self,
1053        instrument_ids: &[InstrumentId],
1054        filters: Option<&HashMap<String, String>>,
1055    ) -> anyhow::Result<()> {
1056        for instrument_id in instrument_ids {
1057            validated_condition_id(instrument_id)?;
1058        }
1059
1060        let missing: Vec<_> = instrument_ids
1061            .iter()
1062            .filter(|id| !self.store.contains(id))
1063            .collect();
1064
1065        if missing.is_empty() {
1066            return Ok(());
1067        }
1068
1069        // Extract unique condition IDs from instrument symbols
1070        // Symbol format: "{condition_id}-{token_id}"
1071        let mut condition_ids: Vec<String> = missing
1072            .iter()
1073            .map(|id| extract_condition_id(id))
1074            .collect::<anyhow::Result<_>>()?;
1075        condition_ids.sort();
1076        condition_ids.dedup();
1077
1078        if condition_ids.is_empty() {
1079            return Ok(());
1080        }
1081
1082        let base_params = filters
1083            .map(build_gamma_params_from_hashmap)
1084            .transpose()?
1085            .unwrap_or_default();
1086
1087        for chunk in condition_ids.chunks(GAMMA_CONDITION_IDS_BATCH_SIZE) {
1088            let params = GetGammaMarketsParams {
1089                condition_ids: Some(chunk.to_vec()),
1090                ..base_params.clone()
1091            };
1092            let instruments = self
1093                .http_client
1094                .request_instruments_by_params(params)
1095                .await?;
1096            self.add_instruments(instruments);
1097        }
1098
1099        Ok(())
1100    }
1101
1102    async fn load(
1103        &mut self,
1104        instrument_id: &InstrumentId,
1105        filters: Option<&HashMap<String, String>>,
1106    ) -> anyhow::Result<()> {
1107        if self.store.contains(instrument_id) {
1108            return Ok(());
1109        }
1110
1111        // Try direct fetch via condition_id extracted from symbol
1112        if let Ok(cid) = extract_condition_id(instrument_id) {
1113            let params = GetGammaMarketsParams {
1114                condition_ids: Some(vec![cid]),
1115                ..Default::default()
1116            };
1117
1118            if let Ok(instruments) = self.http_client.request_instruments_by_params(params).await {
1119                self.add_instruments(instruments);
1120
1121                if self.store.contains(instrument_id) {
1122                    return Ok(());
1123                }
1124            }
1125        }
1126
1127        // Fallback: full load_all if not initialized. A provider with an explicit
1128        // scope is excluded: `load_all` would broaden it into the full-universe
1129        // fetch that scoping exists to avoid, and would also clear the partially
1130        // loaded store and mark it initialized, making a later `initialize(false)`
1131        // skip the scopes it still owes after a failed bootstrap.
1132        if !self.store.is_initialized() && !self.config.has_explicit_scope() {
1133            self.load_all(filters).await?;
1134        }
1135
1136        if self.store.contains(instrument_id) {
1137            Ok(())
1138        } else {
1139            anyhow::bail!("Instrument {instrument_id} not found on Polymarket")
1140        }
1141    }
1142}
1143
1144#[cfg(test)]
1145mod tests {
1146    use nautilus_common::config::ConfigError;
1147    use nautilus_network::retry::RetryConfig;
1148    use rstest::rstest;
1149
1150    use super::*;
1151    use crate::{config::PolymarketUpDownEventSlugConfig, filters::MarketSlugFilter};
1152
1153    #[rstest]
1154    #[case("0xcondition-0xtoken", Some("0xtoken"))]
1155    #[case("0xcondition-with-dash-0xtoken", Some("0xtoken"))]
1156    #[case("0xcondition", None)]
1157    fn extracts_token_id_from_instrument_symbol(
1158        #[case] symbol: &str,
1159        #[case] expected: Option<&str>,
1160    ) {
1161        let instrument_id = InstrumentId::from(format!("{symbol}.POLYMARKET").as_str());
1162        assert_eq!(extract_token_id(&instrument_id).ok().as_deref(), expected,);
1163    }
1164
1165    #[rstest]
1166    #[case::plain(0)]
1167    #[case::multiple_filters(1)]
1168    #[case::single_filter(2)]
1169    fn test_constructor_rejects_invalid_config(
1170        #[case] constructor: u8,
1171        #[values(false, true)] builder: bool,
1172    ) {
1173        let http_client = PolymarketGammaHttpClient::new(
1174            Some("http://127.0.0.1:1".to_string()),
1175            1,
1176            RetryConfig::default(),
1177        )
1178        .unwrap();
1179
1180        let mut config = PolymarketInstrumentProviderConfig {
1181            series_ids: Some(vec![10684, 10684]),
1182            ..Default::default()
1183        };
1184
1185        let expected = if builder {
1186            config.series_ids = None;
1187            config.event_slug_builder = Some(PolymarketUpDownEventSlugConfig {
1188                interval_mins: 0,
1189                ..Default::default()
1190            });
1191
1192            ConfigError::range(
1193                "event_slug_builder.interval_mins",
1194                "must be positive and fit in seconds",
1195            )
1196        } else {
1197            ConfigError::duplicate("series_ids", None)
1198        };
1199
1200        let filter = Arc::new(MarketSlugFilter::from_slugs(vec!["market".to_string()]));
1201
1202        let result = match constructor {
1203            0 => PolymarketInstrumentProvider::new(http_client, Some(config)),
1204            1 => {
1205                PolymarketInstrumentProvider::with_filters(http_client, Some(config), vec![filter])
1206            }
1207            2 => PolymarketInstrumentProvider::with_filter(http_client, Some(config), filter),
1208            _ => unreachable!(),
1209        };
1210
1211        let error = result.unwrap_err();
1212
1213        assert_eq!(error.downcast_ref::<ConfigError>(), Some(&expected));
1214    }
1215}