Skip to main content

nautilus_polymarket/data/
mod.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//! Live market data client implementation for the Polymarket adapter.
17
18mod auto_load;
19mod dispatch;
20mod effective_deltas;
21mod instruments;
22mod lifecycle;
23mod requests;
24mod runtime;
25mod subscriptions;
26
27#[cfg(test)]
28mod test_logging;
29
30use std::{
31    future::Future,
32    sync::{
33        Arc,
34        atomic::{AtomicBool, Ordering},
35    },
36    time::Duration,
37};
38
39use dashmap::DashMap;
40use nautilus_common::{
41    cache::InstrumentLookupError,
42    clients::{DataClient, execute_instrument_subscriptions},
43    live::{dst::time::Instant, runner::get_data_event_sender, sender::EventSender},
44    messages::{
45        DataEvent,
46        data::{
47            RequestBookSnapshot, RequestCustomData, RequestInstrument, RequestInstruments,
48            RequestTrades, SubscribeBookDeltas, SubscribeBookDepth, SubscribeCustomData,
49            SubscribeInstrument, SubscribeInstrumentClose, SubscribeInstrumentStatus,
50            SubscribeInstruments, SubscribeQuotes, SubscribeTrades, UnsubscribeBookDeltas,
51            UnsubscribeCustomData, UnsubscribeInstrument, UnsubscribeInstrumentClose,
52            UnsubscribeInstrumentStatus, UnsubscribeQuotes, UnsubscribeTrades,
53        },
54    },
55    msgbus::TypedHandler,
56};
57use nautilus_core::{
58    AtomicMap,
59    time::{AtomicTime, get_atomic_clock_realtime},
60};
61use nautilus_live::{
62    SocketControl, SocketControlFactory,
63    task::{TaskGroup, TaskSpawner},
64};
65use nautilus_model::{
66    enums::BookType,
67    events::PositionEvent,
68    identifiers::{ClientId, InstrumentId, Venue},
69    instruments::{Instrument, InstrumentAny},
70};
71use nautilus_network::websocket::proxy::ProxyUrl;
72use parking_lot::Mutex;
73use tokio_util::sync::CancellationToken;
74use ustr::Ustr;
75
76pub(crate) use self::subscriptions::DataSubscriptions;
77use self::{
78    instruments::InstrumentUpdateState,
79    requests::{
80        request_book_snapshot, request_data, request_instrument, request_instruments,
81        request_trades,
82    },
83    runtime::is_instrument_expired_and_not_reported_open,
84    subscriptions::{SubscriptionKind, resolve_token_id_from},
85};
86use crate::{
87    book::{BookSequenceOutcome, recovery::start_recovery},
88    common::{
89        consts::{MARKET_VERSION_KEY, POLYMARKET_VENUE},
90        credential::Credential,
91        parse::validate_data_market_version,
92    },
93    config::PolymarketDataClientConfig,
94    filters::InstrumentFilter,
95    http::{
96        clob::PolymarketClobPublicClient, data_api::PolymarketDataApiHttpClient,
97        gamma::PolymarketGammaHttpClient,
98    },
99    polybolt::{PolymarketPolyBoltFeed, is_supported_polybolt_data_type},
100    providers::PolymarketInstrumentProvider,
101    resolve::{PendingResolution, ResolveContext, ResolveWatchlist, StrictResolvedMarket},
102    websocket::{POLYBOLT_STREAMS_ENDPOINT, pool::PolymarketMarketConnectionPool},
103};
104
105const NEW_MARKET_FETCH_MAX_CONCURRENCY_CAP: usize = 64;
106pub(super) const NEW_MARKET_EMPTY_RECHECK_MAX_ATTEMPTS: usize = 1;
107pub(super) const NEW_MARKET_EMPTY_RECHECK_DELAY: Duration = Duration::from_millis(500);
108
109/// Polymarket data client for live market data streaming.
110///
111/// Integrates with the Nautilus DataEngine to provide:
112/// - Real-time order book snapshots and deltas via WebSocket
113/// - Quote ticks synthesized from book data
114/// - Trade ticks from last trade price messages
115/// - Automatic instrument discovery from the Gamma API
116#[derive(Debug)]
117pub struct PolymarketDataClient {
118    clock: &'static AtomicTime,
119    client_id: ClientId,
120    config: PolymarketDataClientConfig,
121    provider: PolymarketInstrumentProvider,
122    clob_public_client: PolymarketClobPublicClient,
123    data_api_client: PolymarketDataApiHttpClient,
124    ws_client: PolymarketMarketConnectionPool,
125    is_connected: AtomicBool,
126    cancellation_token: CancellationToken,
127    tasks: TaskGroup,
128    data_sender: EventSender<DataEvent>,
129    instruments: Arc<AtomicMap<InstrumentId, InstrumentAny>>,
130    subscriptions: DataSubscriptions,
131    instrument_update_state: Arc<Mutex<InstrumentUpdateState>>,
132    resolve_poll_watchlist: Arc<ResolveWatchlist>,
133    resolve_watch_apply_mutex: Arc<Mutex<()>>,
134    pending_resolutions: Arc<DashMap<String, PendingResolution>>,
135    deferred_resolutions: Arc<AtomicMap<InstrumentId, StrictResolvedMarket>>,
136    new_market_inflight_keys: Arc<DashMap<String, ()>>,
137    new_market_fetch_semaphore: Arc<tokio::sync::Semaphore>,
138    auto_load_scheduled: Arc<AtomicBool>,
139    position_event_handler: Option<TypedHandler<PositionEvent>>,
140    polybolt_feed: PolymarketPolyBoltFeed,
141    polybolt_socket_control: Option<SocketControl>,
142    polybolt_credential: Option<Credential>,
143    proxy_url: Option<ProxyUrl>,
144    reset_pending: bool,
145    shutdown_errors: Vec<String>,
146}
147
148impl PolymarketDataClient {
149    /// Creates a new [`PolymarketDataClient`].
150    ///
151    /// # Errors
152    ///
153    /// Returns an error if the configuration is invalid.
154    pub fn new(
155        client_id: ClientId,
156        config: PolymarketDataClientConfig,
157        gamma_client: PolymarketGammaHttpClient,
158        clob_public_client: PolymarketClobPublicClient,
159        data_api_client: PolymarketDataApiHttpClient,
160        ws_client: PolymarketMarketConnectionPool,
161    ) -> anyhow::Result<Self> {
162        Self::new_with_proxy(
163            client_id,
164            config,
165            gamma_client,
166            clob_public_client,
167            data_api_client,
168            ws_client,
169            None,
170        )
171    }
172
173    /// Creates a new data client with an optional validated proxy URL.
174    ///
175    /// # Errors
176    ///
177    /// Returns an error if the configuration is invalid.
178    pub fn new_with_proxy(
179        client_id: ClientId,
180        mut config: PolymarketDataClientConfig,
181        gamma_client: PolymarketGammaHttpClient,
182        clob_public_client: PolymarketClobPublicClient,
183        data_api_client: PolymarketDataApiHttpClient,
184        ws_client: PolymarketMarketConnectionPool,
185        proxy_url: Option<ProxyUrl>,
186    ) -> anyhow::Result<Self> {
187        config.validate()?;
188        let polybolt_credential = config.polybolt_credential()?;
189
190        let clock = get_atomic_clock_realtime();
191        let data_sender = get_data_event_sender();
192        let socket_factory = SocketControlFactory::new(client_id, Some(*POLYMARKET_VENUE));
193        let ws_client = ws_client
194            .with_connect_timeout(config.ws_timeout_secs)
195            .with_socket_factory(socket_factory.clone());
196        let polybolt_socket_control = Some(socket_factory.control(POLYBOLT_STREAMS_ENDPOINT));
197        let provider =
198            PolymarketInstrumentProvider::new(gamma_client, config.instrument_config.clone())?;
199        let configured_fetch_max_concurrency = config.new_market_fetch_max_concurrency;
200        let fetch_max_concurrency =
201            clamp_new_market_fetch_max_concurrency(configured_fetch_max_concurrency);
202
203        if configured_fetch_max_concurrency == 0 {
204            log::warn!(
205                "PolymarketDataClientConfig.new_market_fetch_max_concurrency=0 is invalid, clamping to 1"
206            );
207        } else if configured_fetch_max_concurrency > NEW_MARKET_FETCH_MAX_CONCURRENCY_CAP {
208            log::warn!(
209                "PolymarketDataClientConfig.new_market_fetch_max_concurrency={configured_fetch_max_concurrency} exceeds cap {NEW_MARKET_FETCH_MAX_CONCURRENCY_CAP}, clamping",
210            );
211        }
212        config.new_market_fetch_max_concurrency = fetch_max_concurrency;
213
214        let polybolt_url = config.reference_prices_url();
215        let polybolt_transport_backend = config.transport_backend;
216        let ws_timeout_secs = config.ws_timeout_secs;
217        let polybolt_data_sender = data_sender.clone();
218
219        let tasks = TaskGroup::new();
220        let cancellation_token = tasks.cancellation_token();
221
222        let instruments = Arc::new(AtomicMap::new());
223        let resolve_poll_watchlist = Arc::new(ResolveWatchlist::default());
224        let resolve_watch_apply_mutex = Arc::new(Mutex::new(()));
225        let deferred_resolutions = Arc::new(AtomicMap::new());
226
227        let subscriptions = DataSubscriptions::new(
228            instruments.clone(),
229            resolve_poll_watchlist.clone(),
230            deferred_resolutions.clone(),
231            resolve_watch_apply_mutex.clone(),
232            ws_client.handle(),
233            config.subscribe_new_markets,
234        );
235
236        Ok(Self {
237            clock,
238            client_id,
239            config,
240            provider,
241            clob_public_client,
242            data_api_client,
243            ws_client,
244            is_connected: AtomicBool::new(false),
245            cancellation_token,
246            tasks,
247            data_sender,
248            instruments,
249            subscriptions,
250            instrument_update_state: Arc::new(Mutex::new(InstrumentUpdateState::default())),
251            resolve_poll_watchlist,
252            resolve_watch_apply_mutex,
253            pending_resolutions: Arc::new(DashMap::new()),
254            deferred_resolutions,
255            new_market_inflight_keys: Arc::new(DashMap::new()),
256            new_market_fetch_semaphore: Arc::new(tokio::sync::Semaphore::new(
257                fetch_max_concurrency,
258            )),
259            auto_load_scheduled: Arc::new(AtomicBool::new(false)),
260            position_event_handler: None,
261            polybolt_feed: PolymarketPolyBoltFeed::new_with_proxy_and_socket_control(
262                polybolt_url,
263                polybolt_transport_backend,
264                clock,
265                polybolt_data_sender,
266                proxy_url.clone(),
267                polybolt_socket_control.clone(),
268                polybolt_credential.clone(),
269                ws_timeout_secs,
270            ),
271            polybolt_socket_control,
272            polybolt_credential,
273            proxy_url,
274            reset_pending: false,
275            shutdown_errors: Vec::new(),
276        })
277    }
278
279    /// Returns a reference to the client configuration.
280    #[must_use]
281    pub fn config(&self) -> &PolymarketDataClientConfig {
282        &self.config
283    }
284
285    /// Returns the venue for this data client.
286    #[must_use]
287    pub fn venue(&self) -> Venue {
288        *POLYMARKET_VENUE
289    }
290
291    /// Returns a reference to the instrument provider.
292    #[must_use]
293    pub fn provider(&self) -> &PolymarketInstrumentProvider {
294        &self.provider
295    }
296
297    #[cfg(test)]
298    pub(crate) fn clob_public_client(&self) -> &PolymarketClobPublicClient {
299        &self.clob_public_client
300    }
301
302    #[cfg(test)]
303    pub(crate) fn data_api_client(&self) -> &PolymarketDataApiHttpClient {
304        &self.data_api_client
305    }
306
307    #[cfg(test)]
308    pub(crate) fn ws_client(&self) -> &PolymarketMarketConnectionPool {
309        &self.ws_client
310    }
311
312    #[cfg(test)]
313    pub(crate) fn polybolt_feed(&self) -> &PolymarketPolyBoltFeed {
314        &self.polybolt_feed
315    }
316
317    /// Adds an instrument filter on the underlying provider.
318    pub fn add_instrument_filter(&mut self, filter: Arc<dyn InstrumentFilter>) {
319        self.provider.add_filter(filter);
320    }
321
322    /// Returns `true` when the client is connected.
323    #[must_use]
324    pub fn is_connected(&self) -> bool {
325        self.is_connected.load(Ordering::Relaxed)
326    }
327
328    fn resolve_token_id(&self, instrument_id: InstrumentId) -> anyhow::Result<String> {
329        resolve_token_id_from(&self.instruments, instrument_id)
330    }
331
332    fn resolution_context(&self) -> ResolveContext {
333        ResolveContext {
334            subscriptions: self.subscriptions.clone(),
335            clock: self.clock,
336            data_sender: self.data_sender.clone(),
337            instruments: self.instruments.clone(),
338            watchlist: self.resolve_poll_watchlist.clone(),
339            apply_mutex: self.resolve_watch_apply_mutex.clone(),
340            pending_resolutions: self.pending_resolutions.clone(),
341            deferred_resolutions: self.deferred_resolutions.clone(),
342            cancellation_token: self.cancellation_token.clone(),
343        }
344    }
345
346    fn ensure_live_subscription_allowed(&self, instrument_id: InstrumentId) -> anyhow::Result<()> {
347        let now_ns = self.clock.get_time_ns();
348        let loaded = self.instruments.load();
349        let Some(instrument) = loaded.get(&instrument_id) else {
350            return Ok(());
351        };
352
353        validate_data_market_version(
354            instrument
355                .info()
356                .and_then(|info| info.get_str(MARKET_VERSION_KEY)),
357        )?;
358
359        if is_instrument_expired_and_not_reported_open(instrument, now_ns) {
360            anyhow::bail!(
361                "Instrument {instrument_id} is expired and no longer available for live subscription"
362            );
363        }
364
365        Ok(())
366    }
367
368    fn ensure_market_data_request_allowed(
369        &self,
370        instrument_id: InstrumentId,
371    ) -> anyhow::Result<InstrumentAny> {
372        let loaded = self.instruments.load();
373        let instrument = loaded
374            .get(&instrument_id)
375            .ok_or_else(|| InstrumentLookupError::not_found(instrument_id))?
376            .clone();
377
378        validate_data_market_version(
379            instrument
380                .info()
381                .and_then(|info| info.get_str(MARKET_VERSION_KEY)),
382        )?;
383
384        if is_instrument_expired_and_not_reported_open(&instrument, self.clock.get_time_ns()) {
385            anyhow::bail!(
386                "Instrument {instrument_id} is expired and no longer available for market data requests"
387            );
388        }
389
390        Ok(instrument)
391    }
392
393    fn subscribe_resolution(
394        &self,
395        instrument_id: InstrumentId,
396        kind: SubscriptionKind,
397    ) -> anyhow::Result<()> {
398        // Expiration bounds recovery; it does not disqualify metadata needed for settlement
399        let loaded = self.instruments.load();
400        let cached = loaded.get(&instrument_id);
401        if let Some(instrument) = cached {
402            validate_data_market_version(
403                instrument
404                    .info()
405                    .and_then(|info| info.get_str(MARKET_VERSION_KEY)),
406            )?;
407        }
408
409        let cached = cached.is_some();
410
411        if !cached && !self.config.auto_load_missing_instruments {
412            anyhow::bail!(
413                "Instrument {instrument_id} not found, and `auto_load_missing_instruments` is disabled"
414            );
415        }
416
417        if !self
418            .subscriptions
419            .add_resolution_subscription_intent(instrument_id, kind)
420        {
421            return Ok(());
422        }
423
424        if !cached {
425            self.queue_pending_load(instrument_id);
426            return Ok(());
427        }
428
429        self.sync_ws_subscription(instrument_id);
430        Ok(())
431    }
432
433    // Spawns an async task that reconciles the WS subscription for
434    // `instrument_id`. The task holds `ws_sub_mutex` across the wire send so
435    // concurrent subscribe/unsubscribe calls deliver commands to the WS handler
436    // in a consistent order with the final `active_*_subs` state.
437    fn sync_ws_subscription(&self, instrument_id: InstrumentId) {
438        if let Ok(token_id) = self.resolve_token_id(instrument_id) {
439            self.sync_ws_subscription_for_token(instrument_id, token_id);
440        }
441    }
442
443    fn sync_ws_subscription_for_token(&self, instrument_id: InstrumentId, token_id_str: String) {
444        let subscriptions = self.subscriptions.clone();
445        let future = async move {
446            subscriptions.reconcile(instrument_id, token_id_str).await;
447        };
448
449        if let Err(e) = self.tasks.spawn(future) {
450            log::debug!("Skipping Polymarket data task after shutdown began: {e}");
451        }
452    }
453
454    // The venue ignores a duplicate subscribe, so a token another subscription already holds
455    // sends no `book` for this one; a recovery cycle requests it instead.
456    fn sync_book_subscription(&self, instrument_id: InstrumentId) {
457        let Ok(token_id) = self.resolve_token_id(instrument_id) else {
458            return;
459        };
460
461        let spawner = match self.tasks.spawner() {
462            Ok(spawner) => spawner,
463            Err(e) => {
464                log::debug!("Skipping Polymarket data task after shutdown began: {e}");
465                return;
466            }
467        };
468
469        // Read on arrival so a subscription still queued behind the subscription lock does not
470        // look open; its `book` reaches this one.
471        let was_open = self
472            .subscriptions
473            .ws_open_tokens
474            .contains(&Ustr::from(token_id.as_str()));
475        let subscriptions = self.subscriptions.clone();
476        let snapshot_timeout = Duration::from_secs(self.config.book_snapshot_timeout_secs);
477
478        // The sync waits out any subscribe write in flight, so recovery cycles an owned token
479        let future = async move {
480            subscriptions
481                .reconcile(instrument_id, token_id.clone())
482                .await;
483
484            if was_open
485                && subscriptions.book_sync.request_snapshot_if_subscribed(
486                    &subscriptions.active_delta_subs,
487                    instrument_id,
488                    Instant::now(),
489                ) == BookSequenceOutcome::Recover
490            {
491                log::debug!("Requesting a book snapshot for {instrument_id} on an open token");
492                start_recovery(
493                    instrument_id,
494                    Some(token_id),
495                    &subscriptions.active_delta_subs,
496                    &subscriptions.book_sync,
497                    &subscriptions.ws_client,
498                    snapshot_timeout,
499                    &spawner,
500                );
501            } else if !was_open {
502                subscriptions.monitor_book_snapshot(instrument_id, snapshot_timeout, &spawner);
503            }
504        };
505
506        if let Err(e) = self.tasks.spawn(future) {
507            log::debug!("Skipping Polymarket data task after shutdown began: {e}");
508        }
509    }
510}
511
512#[async_trait::async_trait(?Send)]
513impl DataClient for PolymarketDataClient {
514    fn client_id(&self) -> ClientId {
515        self.client_id
516    }
517
518    fn venue(&self) -> Option<Venue> {
519        Some(*POLYMARKET_VENUE)
520    }
521
522    fn start(&mut self) -> anyhow::Result<()> {
523        self.start_client();
524        Ok(())
525    }
526
527    fn stop(&mut self) -> anyhow::Result<()> {
528        self.stop_client();
529        Ok(())
530    }
531
532    fn reset(&mut self) -> anyhow::Result<()> {
533        self.reset_client();
534        Ok(())
535    }
536
537    fn dispose(&mut self) -> anyhow::Result<()> {
538        self.stop()
539    }
540
541    async fn connect(&mut self) -> anyhow::Result<()> {
542        self.connect_client().await
543    }
544
545    async fn disconnect(&mut self) -> anyhow::Result<()> {
546        self.disconnect_client().await
547    }
548
549    fn is_connected(&self) -> bool {
550        self.is_connected.load(Ordering::Relaxed)
551    }
552
553    fn is_disconnected(&self) -> bool {
554        !self.is_connected()
555    }
556
557    fn request_data(&self, request: RequestCustomData) -> anyhow::Result<()> {
558        request_data(self, request);
559        Ok(())
560    }
561
562    fn request_instruments(&self, request: RequestInstruments) -> anyhow::Result<()> {
563        request_instruments(self, request);
564        Ok(())
565    }
566
567    fn request_instrument(&self, request: RequestInstrument) -> anyhow::Result<()> {
568        request_instrument(self, request)
569    }
570
571    fn request_book_snapshot(&self, request: RequestBookSnapshot) -> anyhow::Result<()> {
572        request_book_snapshot(self, request)
573    }
574
575    fn request_trades(&self, request: RequestTrades) -> anyhow::Result<()> {
576        request_trades(self, request)
577    }
578
579    fn subscribe_instruments(&mut self, _cmd: SubscribeInstruments) -> anyhow::Result<()> {
580        log::debug!("subscribe_instruments: subscribed individually via data subscription methods");
581        Ok(())
582    }
583
584    fn subscribe_instrument(&mut self, cmd: SubscribeInstrument) -> anyhow::Result<()> {
585        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
586            log::debug!(
587                "Subscribed to instrument definition updates for {instrument_id}; shared instrument sources remain active"
588            );
589
590            Ok(())
591        })
592    }
593
594    fn unsubscribe_instrument(&mut self, cmd: &UnsubscribeInstrument) -> anyhow::Result<()> {
595        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
596            log::debug!(
597                "Unsubscribed from instrument {instrument_id}; shared instrument sources remain active"
598            );
599            Ok(())
600        })
601    }
602
603    fn subscribe(&mut self, cmd: SubscribeCustomData) -> anyhow::Result<()> {
604        if !is_supported_polybolt_data_type(&cmd.data_type) {
605            log::debug!(
606                "Ignoring unsupported Polymarket custom data subscription: {}",
607                cmd.data_type
608            );
609            return Ok(());
610        }
611
612        log::debug!(
613            "Tracking Polymarket PolyBolt custom data subscription: {}",
614            cmd.data_type
615        );
616        let changed = self.polybolt_feed.track_subscribe(cmd.data_type)?;
617        if !changed {
618            return Ok(());
619        }
620
621        if !self.is_connected() {
622            return Ok(());
623        }
624
625        self.polybolt_feed
626            .request_reconcile(crate::polybolt::ReconcileReason::DesiredChanged);
627
628        Ok(())
629    }
630
631    fn subscribe_book_deltas(&mut self, cmd: SubscribeBookDeltas) -> anyhow::Result<()> {
632        if cmd.book_type != BookType::L2_MBP {
633            anyhow::bail!(
634                "Polymarket only supports L2_MBP order book deltas, received {:?}",
635                cmd.book_type
636            );
637        }
638
639        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
640            self.ensure_live_subscription_allowed(instrument_id)?;
641            let cached = self.instruments.load().contains_key(&instrument_id);
642
643            if !cached && !self.config.auto_load_missing_instruments {
644                anyhow::bail!(
645                    "Instrument {instrument_id} not found, and `auto_load_missing_instruments` is disabled"
646                );
647            }
648
649            // Mark intent before routing so unsubscribe can race-safely clear it.
650            if !self
651                .subscriptions
652                .add_delta_subscription_intent(instrument_id, self.config.compute_effective_deltas)
653            {
654                return Ok(());
655            }
656
657            if !cached {
658                self.queue_pending_load(instrument_id);
659                return Ok(());
660            }
661
662            self.sync_book_subscription(instrument_id);
663            Ok(())
664        })
665    }
666
667    fn subscribe_book_depth(&mut self, _cmd: SubscribeBookDepth) -> anyhow::Result<()> {
668        anyhow::bail!(
669            "Polymarket does not support OrderBookDepth subscriptions; use managed L2_MBP order book deltas"
670        )
671    }
672
673    fn subscribe_quotes(&mut self, cmd: SubscribeQuotes) -> anyhow::Result<()> {
674        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
675            self.ensure_live_subscription_allowed(instrument_id)?;
676            let cached = self.instruments.load().contains_key(&instrument_id);
677
678            if !cached && !self.config.auto_load_missing_instruments {
679                anyhow::bail!(
680                    "Instrument {instrument_id} not found, and `auto_load_missing_instruments` is disabled"
681                );
682            }
683
684            if !self
685                .subscriptions
686                .add_live_subscription_intent(instrument_id, SubscriptionKind::Quotes)
687            {
688                return Ok(());
689            }
690
691            if !cached {
692                self.queue_pending_load(instrument_id);
693                return Ok(());
694            }
695
696            self.sync_ws_subscription(instrument_id);
697            Ok(())
698        })
699    }
700
701    fn subscribe_trades(&mut self, cmd: SubscribeTrades) -> anyhow::Result<()> {
702        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
703            self.ensure_live_subscription_allowed(instrument_id)?;
704            let cached = self.instruments.load().contains_key(&instrument_id);
705
706            if !cached && !self.config.auto_load_missing_instruments {
707                anyhow::bail!(
708                    "Instrument {instrument_id} not found, and `auto_load_missing_instruments` is disabled"
709                );
710            }
711
712            if !self
713                .subscriptions
714                .add_live_subscription_intent(instrument_id, SubscriptionKind::Trades)
715            {
716                return Ok(());
717            }
718
719            if !cached {
720                self.queue_pending_load(instrument_id);
721                return Ok(());
722            }
723
724            self.sync_ws_subscription(instrument_id);
725            Ok(())
726        })
727    }
728
729    fn subscribe_instrument_status(
730        &mut self,
731        cmd: SubscribeInstrumentStatus,
732    ) -> anyhow::Result<()> {
733        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
734            self.subscribe_resolution(instrument_id, SubscriptionKind::Status)
735        })
736    }
737
738    fn subscribe_instrument_close(&mut self, cmd: SubscribeInstrumentClose) -> anyhow::Result<()> {
739        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
740            self.subscribe_resolution(instrument_id, SubscriptionKind::Close)
741        })
742    }
743
744    fn unsubscribe_book_deltas(&mut self, cmd: &UnsubscribeBookDeltas) -> anyhow::Result<()> {
745        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
746            let token_id = self
747                .subscriptions
748                .unsubscribe(instrument_id, SubscriptionKind::Deltas);
749            if let Some(token_id) = token_id {
750                self.sync_ws_subscription_for_token(instrument_id, token_id);
751            }
752
753            Ok(())
754        })
755    }
756
757    fn unsubscribe_quotes(&mut self, cmd: &UnsubscribeQuotes) -> anyhow::Result<()> {
758        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
759            let token_id = self
760                .subscriptions
761                .unsubscribe(instrument_id, SubscriptionKind::Quotes);
762            if let Some(token_id) = token_id {
763                self.sync_ws_subscription_for_token(instrument_id, token_id);
764            }
765
766            Ok(())
767        })
768    }
769
770    fn unsubscribe_trades(&mut self, cmd: &UnsubscribeTrades) -> anyhow::Result<()> {
771        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
772            let token_id = self
773                .subscriptions
774                .unsubscribe(instrument_id, SubscriptionKind::Trades);
775            if let Some(token_id) = token_id {
776                self.sync_ws_subscription_for_token(instrument_id, token_id);
777            }
778
779            Ok(())
780        })
781    }
782
783    fn unsubscribe_instrument_status(
784        &mut self,
785        cmd: &UnsubscribeInstrumentStatus,
786    ) -> anyhow::Result<()> {
787        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
788            let token_id = self
789                .subscriptions
790                .unsubscribe(instrument_id, SubscriptionKind::Status);
791            if let Some(token_id) = token_id {
792                self.sync_ws_subscription_for_token(instrument_id, token_id);
793            }
794
795            Ok(())
796        })
797    }
798
799    fn unsubscribe_instrument_close(
800        &mut self,
801        cmd: &UnsubscribeInstrumentClose,
802    ) -> anyhow::Result<()> {
803        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
804            let token_id = self
805                .subscriptions
806                .unsubscribe(instrument_id, SubscriptionKind::Close);
807            if let Some(token_id) = token_id {
808                self.sync_ws_subscription_for_token(instrument_id, token_id);
809            }
810
811            Ok(())
812        })
813    }
814
815    fn unsubscribe(&mut self, cmd: &UnsubscribeCustomData) -> anyhow::Result<()> {
816        if !is_supported_polybolt_data_type(&cmd.data_type) {
817            log::debug!(
818                "Ignoring unsupported Polymarket custom data unsubscription: {}",
819                cmd.data_type
820            );
821            return Ok(());
822        }
823
824        log::debug!(
825            "Tracking Polymarket PolyBolt custom data unsubscription: {}",
826            cmd.data_type
827        );
828        let changed = self.polybolt_feed.track_unsubscribe(&cmd.data_type)?;
829        if !changed {
830            return Ok(());
831        }
832
833        if !self.is_connected() {
834            return Ok(());
835        }
836
837        self.polybolt_feed
838            .request_reconcile(crate::polybolt::ReconcileReason::DesiredChanged);
839
840        Ok(())
841    }
842}
843
844fn clamp_new_market_fetch_max_concurrency(value: usize) -> usize {
845    value.clamp(1, NEW_MARKET_FETCH_MAX_CONCURRENCY_CAP)
846}
847
848pub(super) fn spawn_task<F>(tasks: &TaskSpawner, future: F)
849where
850    F: Future<Output = ()> + Send + 'static,
851{
852    if let Err(e) = tasks.spawn(future) {
853        log::debug!("Skipping Polymarket data task after shutdown began: {e}");
854    }
855}