1pub mod order_builder;
19pub mod parse;
20
21pub(crate) mod context;
22pub(crate) mod fill_tracker;
23pub(crate) mod pending;
24pub(crate) mod reconciliation;
25pub(crate) mod settlement;
26pub(crate) mod submitter;
27pub(crate) mod types;
28
29mod cancellations;
30mod collateral;
31mod lifecycle;
32mod orders;
33mod reports;
34mod responses;
35
36use std::{
37 cell::RefCell,
38 sync::{Arc, atomic::AtomicBool},
39};
40
41use anyhow::Context;
42use async_trait::async_trait;
43use nautilus_common::{
44 clients::{ExecutionClient, ExecutionReportTask},
45 messages::execution::{
46 BatchCancelOrders, CancelAllOrders, CancelOrder, GenerateFillReports,
47 GenerateOrderStatusReport, GenerateOrderStatusReports, GeneratePositionStatusReports,
48 ModifyOrder, QueryAccount, QueryOrder, SubmitOrder, SubmitOrderList,
49 },
50 msgbus::TypedHandler,
51};
52use nautilus_core::{
53 Params, UnixNanos,
54 collections::AtomicMap,
55 time::{AtomicTime, get_atomic_clock_realtime},
56};
57use nautilus_live::{ExecutionClientCore, ExecutionEventEmitter, SocketControl, task::TaskGroup};
58use nautilus_model::{
59 accounts::AccountAny,
60 enums::{AccountType, LiquiditySide, OmsType, OrderSide},
61 events::{OrderEventAny, PositionEvent},
62 identifiers::{
63 AccountId, ClientId, ClientOrderId, InstrumentId, StrategyId, Venue, VenueOrderId,
64 },
65 instruments::InstrumentAny,
66 orders::{Order, OrderAny},
67 reports::{ExecutionMassStatus, FillReport, OrderStatusReport, PositionStatusReport},
68 types::{AccountBalance, MarginBalance, Money, Price, Quantity},
69};
70use nautilus_network::retry::RetryConfig;
71use parking_lot::Mutex;
72pub(crate) use responses::is_post_only_crossing;
73use rust_decimal::Decimal;
74use ustr::Ustr;
75
76pub(crate) use self::reports::get_pusd_currency;
77use self::{
78 context::OrderContextRegistry,
79 fill_tracker::OrderFillTrackerMap,
80 order_builder::PolymarketOrderBuilder,
81 pending::{PendingCancelTracker, PendingSubmitTracker},
82 settlement::SettlementRegistry,
83 submitter::OrderSubmitter,
84};
85use crate::{
86 common::{consts::POLYMARKET_VENUE, credential::Secrets, enums::PolymarketSignatureType},
87 config::PolymarketExecutionClientConfig,
88 http::{clob::PolymarketClobHttpClient, data_api::PolymarketDataApiHttpClient},
89 signing::eip712::{OrderSigner, parse_address},
90 websocket::{
91 USER_STREAMS_ENDPOINT, client::PolymarketWebSocketClient, dispatch::WsDispatchState,
92 },
93};
94
95#[derive(Debug)]
97pub struct PolymarketExecutionClient {
98 core: ExecutionClientCore,
99 clock: &'static AtomicTime,
100 config: PolymarketExecutionClientConfig,
101 emitter: ExecutionEventEmitter,
102 http_client: PolymarketClobHttpClient,
103 data_api_client: PolymarketDataApiHttpClient,
104 submitter: OrderSubmitter,
105 ws_client: PolymarketWebSocketClient,
106 secrets: Secrets,
107 session_tasks: TaskGroup,
108 pending_tasks: TaskGroup,
109 shutdown_errors: Vec<String>,
110 stopping: Arc<AtomicBool>,
111 heartbeat_healthy: Arc<AtomicBool>,
112 order_event_handler: Option<TypedHandler<OrderEventAny>>,
113 position_event_handler: Option<TypedHandler<PositionEvent>>,
114 fill_observer: Option<TypedHandler<OrderEventAny>>,
115 void_observer: Option<TypedHandler<OrderEventAny>>,
116 decline_observer: Option<TypedHandler<OrderEventAny>>,
117 shared_token_instruments: Arc<AtomicMap<Ustr, InstrumentAny>>,
118 neg_risk_index: Arc<AtomicMap<InstrumentId, bool>>,
119 instruments_pending: RefCell<Option<Vec<InstrumentAny>>>,
120 pending_submits: PendingSubmitTracker,
121 pending_cancels: PendingCancelTracker,
122 order_contexts: Arc<OrderContextRegistry>,
123 collateral_locks: Arc<Mutex<collateral::CollateralLocks>>,
124 fill_tracker: Arc<OrderFillTrackerMap>,
125 settlement: Arc<SettlementRegistry>,
126 ws_dispatch_state: Arc<Mutex<WsDispatchState>>,
127}
128
129impl PolymarketExecutionClient {
130 pub fn new(
137 core: ExecutionClientCore,
138 config: PolymarketExecutionClientConfig,
139 ) -> anyhow::Result<Self> {
140 config.validate()?;
141
142 let proxy_url = config.validated_proxy_url()?;
143 config.validate_signer()?;
144 let secrets = Secrets::resolve(
145 config.private_key.clone(),
146 config.api_key.clone(),
147 config.api_secret.clone(),
148 config.passphrase.clone(),
149 config.funder.clone(),
150 )
151 .context("failed to resolve Polymarket credentials")?;
152
153 let signer_address = secrets.address.clone();
154 let maker_address = resolve_maker_address(
155 config.signature_type,
156 &signer_address,
157 secrets.funder.as_deref(),
158 )?;
159 let http_client = PolymarketClobHttpClient::new_with_proxy(
160 secrets.credential.clone(),
161 signer_address.clone(),
162 config.base_url_http.clone(),
163 config.http_timeout_secs,
164 proxy_url.clone(),
165 )
166 .map_err(|e| anyhow::anyhow!("{e}"))
167 .context("failed to create CLOB HTTP client")?;
168
169 let data_api_client = PolymarketDataApiHttpClient::new_with_proxy(
170 Some(config.data_api_url()),
171 config.http_timeout_secs,
172 proxy_url.clone(),
173 )
174 .map_err(|e| anyhow::anyhow!("{e}"))
175 .context("failed to create Data API HTTP client")?;
176
177 let order_signer = OrderSigner::new(&secrets.private_key)
178 .context("failed to create order signer")?
179 .with_signer_type(config.signer_type);
180
181 let order_builder = Arc::new(PolymarketOrderBuilder::new(
182 order_signer,
183 signer_address,
184 maker_address,
185 config.signature_type,
186 ));
187
188 let retry_config = RetryConfig {
189 max_retries: config.max_retries,
190 initial_delay_ms: config.retry_delay_initial_ms,
191 max_delay_ms: config.retry_delay_max_ms,
192 backoff_factor: 2.0,
193 jitter_ms: 1_000,
194 operation_timeout_ms: Some(config.http_timeout_secs * 1_000),
195 immediate_first: false,
196 max_elapsed_ms: Some(180_000),
197 };
198
199 let settlement = Arc::new(SettlementRegistry::new(core.account_id));
200
201 let submitter = OrderSubmitter::new(
202 http_client.clone(),
203 order_builder,
204 retry_config,
205 settlement.clone(),
206 );
207
208 let ws_client = PolymarketWebSocketClient::new_user_with_proxy(
209 config.base_url_ws.clone(),
210 secrets.credential.clone(),
211 config.transport_backend,
212 proxy_url,
213 );
214
215 let ws_client = ws_client.with_socket_control(SocketControl::new(
216 core.client_id,
217 Some(*POLYMARKET_VENUE),
218 USER_STREAMS_ENDPOINT,
219 ));
220
221 let clock = get_atomic_clock_realtime();
222 let pusd = get_pusd_currency();
223 let emitter = ExecutionEventEmitter::new(
224 clock,
225 core.trader_id,
226 core.account_id,
227 AccountType::Cash,
228 Some(pusd),
229 );
230
231 let session_tasks = TaskGroup::new();
232 let pending_tasks = TaskGroup::new();
233
234 Ok(Self {
235 core,
236 clock,
237 config,
238 emitter,
239 http_client,
240 data_api_client,
241 submitter,
242 ws_client,
243 secrets,
244 session_tasks,
245 pending_tasks,
246 shutdown_errors: Vec::new(),
247 stopping: Arc::new(AtomicBool::new(false)),
248 heartbeat_healthy: Arc::new(AtomicBool::new(true)),
249 order_event_handler: None,
250 position_event_handler: None,
251 fill_observer: None,
252 void_observer: None,
253 decline_observer: None,
254 shared_token_instruments: Arc::new(AtomicMap::new()),
255 neg_risk_index: Arc::new(AtomicMap::new()),
256 instruments_pending: RefCell::new(Some(Vec::new())),
257 pending_submits: PendingSubmitTracker::default(),
258 pending_cancels: PendingCancelTracker::default(),
259 order_contexts: Arc::new(OrderContextRegistry::default()),
260 collateral_locks: Arc::new(Mutex::new(collateral::CollateralLocks::default())),
261 fill_tracker: Arc::new(OrderFillTrackerMap::new()),
262 settlement,
263 ws_dispatch_state: Arc::new(Mutex::new(WsDispatchState::default())),
264 })
265 }
266
267 fn check_not_faulted(&self) -> anyhow::Result<()> {
268 if let Some(reason) = self.settlement.client_fault_reason() {
269 anyhow::bail!("Polymarket execution client is faulted closed until restart: {reason}");
270 }
271
272 Ok(())
273 }
274}
275
276fn resolve_maker_address(
277 signature_type: PolymarketSignatureType,
278 signer_address: &str,
279 funder: Option<&str>,
280) -> anyhow::Result<String> {
281 let maker_address = match signature_type {
282 PolymarketSignatureType::Eoa => funder.unwrap_or(signer_address),
283 PolymarketSignatureType::PolyProxy
284 | PolymarketSignatureType::PolyGnosisSafe
285 | PolymarketSignatureType::Poly1271 => funder.ok_or_else(|| {
286 anyhow::anyhow!(
287 "Polymarket {signature_type:?} signature type requires a funder wallet address",
288 )
289 })?,
290 };
291
292 let maker_address = parse_address(maker_address.trim(), "funder")?;
293 let signer_address = parse_address(signer_address, "signer")?;
294 if signature_type == PolymarketSignatureType::Eoa && maker_address != signer_address {
295 anyhow::bail!(
296 "Polymarket Eoa signature type requires the funder to equal the signing address"
297 );
298 }
299
300 if signature_type != PolymarketSignatureType::Eoa && maker_address == signer_address {
301 anyhow::bail!(
302 "Polymarket {signature_type:?} signature type requires a funder distinct from the signing address",
303 );
304 }
305
306 Ok(format!("{maker_address:#x}"))
307}
308
309#[async_trait(?Send)]
310impl ExecutionClient for PolymarketExecutionClient {
311 fn is_connected(&self) -> bool {
312 self.core.is_connected()
313 && !self.settlement.client_faulted()
314 && (!self.config.heartbeat_enabled
315 || self
316 .heartbeat_healthy
317 .load(std::sync::atomic::Ordering::Acquire))
318 }
319
320 fn client_id(&self) -> ClientId {
321 self.core.client_id
322 }
323
324 fn account_id(&self) -> AccountId {
325 self.core.account_id
326 }
327
328 fn venue(&self) -> Venue {
329 *POLYMARKET_VENUE
330 }
331
332 fn oms_type(&self) -> OmsType {
333 OmsType::Netting
334 }
335
336 fn get_account(&self) -> Option<AccountAny> {
337 self.core.cache().account_owned(&self.core.account_id)
338 }
339
340 fn position_reconciliation_tolerance(&self) -> Decimal {
341 crate::common::consts::POSITION_RECONCILIATION_TOLERANCE
342 }
343
344 fn allows_reconciliation_overfill(&self, order: &OrderAny, report: &FillReport) -> bool {
345 order.order_side() == OrderSide::Buy
346 && report.order_side == OrderSide::Buy
347 && !order.is_quote_quantity()
348 && order
349 .venue_order_ids()
350 .iter()
351 .any(|venue_order_id| **venue_order_id == report.venue_order_id)
352 }
353
354 fn provides_bulk_position_coverage(&self, _instrument_id: InstrumentId) -> bool {
357 false
358 }
359
360 fn generate_account_state(
361 &self,
362 balances: Vec<AccountBalance>,
363 margins: Vec<MarginBalance>,
364 reported: bool,
365 ts_event: UnixNanos,
366 info: Option<Params>,
367 ) -> anyhow::Result<()> {
368 self.emitter
369 .emit_account_state(balances, margins, reported, ts_event, info);
370 Ok(())
371 }
372
373 fn start(&mut self) -> anyhow::Result<()> {
374 self.start_client();
375 Ok(())
376 }
377
378 fn stop(&mut self) -> anyhow::Result<()> {
379 self.stop_client();
380 Ok(())
381 }
382
383 fn reset(&mut self) -> anyhow::Result<()> {
384 self.reset_client();
385 Ok(())
386 }
387
388 fn submit_order(&self, cmd: SubmitOrder) -> anyhow::Result<()> {
389 self.settlement.ensure_submission_allowed()?;
390 self.submit_order_command(&cmd)
391 }
392
393 fn submit_order_list(&self, cmd: SubmitOrderList) -> anyhow::Result<()> {
394 self.settlement.ensure_submission_allowed()?;
395 self.submit_order_list_command(&cmd);
396 Ok(())
397 }
398
399 fn modify_order(&self, cmd: ModifyOrder) -> anyhow::Result<()> {
400 self.check_not_faulted()?;
401
402 if let Err(e) = self.settlement.ensure_submission_allowed() {
403 self.emitter.emit_order_modify_denied_event(
404 cmd.strategy_id,
405 cmd.instrument_id,
406 cmd.client_order_id,
407 cmd.venue_order_id,
408 &e.to_string(),
409 self.clock.get_time_ns(),
410 Some(cmd.command_id),
411 );
412 return Ok(());
413 }
414
415 self.modify_order_command(&cmd);
416 Ok(())
417 }
418
419 fn cancel_order(&self, cmd: CancelOrder) -> anyhow::Result<()> {
420 self.check_not_faulted()?;
421 self.cancel_order_command(&cmd);
422 Ok(())
423 }
424
425 fn cancel_all_orders(&self, cmd: CancelAllOrders) -> anyhow::Result<()> {
426 self.check_not_faulted()?;
427 self.cancel_all_orders_command(&cmd)
428 }
429
430 fn batch_cancel_orders(&self, cmd: BatchCancelOrders) -> anyhow::Result<()> {
431 self.check_not_faulted()?;
432 self.batch_cancel_orders_command(&cmd);
433 Ok(())
434 }
435
436 fn query_account(&self, cmd: QueryAccount) -> anyhow::Result<()> {
437 self.query_account_command(cmd);
438 Ok(())
439 }
440
441 fn query_order(&self, cmd: QueryOrder) -> anyhow::Result<()> {
442 self.query_order_command(&cmd);
443 Ok(())
444 }
445
446 fn retain_unresolved_submissions(&self) -> bool {
447 true
448 }
449
450 fn register_external_order(
451 &self,
452 _client_order_id: ClientOrderId,
453 _venue_order_id: VenueOrderId,
454 _instrument_id: InstrumentId,
455 _strategy_id: StrategyId,
456 _ts_init: UnixNanos,
457 ) {
458 }
459
460 fn on_instrument(&mut self, instrument: InstrumentAny) {
461 if let Some(pending) = self.instruments_pending.get_mut() {
462 pending.push(instrument);
463 } else {
464 self.on_instrument_update(&instrument);
465 }
466 }
467
468 fn calculate_commission(
469 &self,
470 instrument: &InstrumentAny,
471 last_qty: Quantity,
472 last_px: Price,
473 liquidity_side: LiquiditySide,
474 ) -> anyhow::Result<Option<Money>> {
475 self.calculate_commission_impl(instrument, last_qty, last_px, liquidity_side)
476 .map(Some)
477 }
478
479 async fn connect(&mut self) -> anyhow::Result<()> {
480 self.connect_client().await
481 }
482
483 async fn disconnect(&mut self) -> anyhow::Result<()> {
484 self.disconnect_client().await
485 }
486
487 fn generate_order_status_report_task(
488 &self,
489 cmd: &GenerateOrderStatusReport,
490 ) -> Option<ExecutionReportTask<Option<OrderStatusReport>>> {
491 Some(self.order_status_report_task(cmd))
492 }
493
494 fn generate_order_status_reports_task(
495 &self,
496 cmd: &GenerateOrderStatusReports,
497 ) -> Option<ExecutionReportTask<Vec<OrderStatusReport>>> {
498 self.order_status_reports_task(cmd)
499 }
500
501 fn generate_fill_reports_task(
502 &self,
503 cmd: &GenerateFillReports,
504 ) -> Option<ExecutionReportTask<Vec<FillReport>>> {
505 Some(self.fill_reports_task(cmd))
506 }
507
508 fn generate_position_status_reports_task(
509 &self,
510 cmd: &GeneratePositionStatusReports,
511 ) -> Option<ExecutionReportTask<Vec<PositionStatusReport>>> {
512 Some(self.position_status_reports_task(cmd))
513 }
514
515 async fn generate_order_status_report(
516 &self,
517 cmd: &GenerateOrderStatusReport,
518 ) -> anyhow::Result<Option<OrderStatusReport>> {
519 gate_report(
520 || {
521 self.settlement
522 .ensure_order_status_available(cmd.instrument_id, "order status report")
523 },
524 Box::pin(self.generate_order_status_report_impl(cmd)),
525 )
526 .await
527 }
528
529 async fn generate_order_status_reports(
530 &self,
531 cmd: &GenerateOrderStatusReports,
532 ) -> anyhow::Result<Vec<OrderStatusReport>> {
533 gate_report(
534 || {
535 self.settlement
536 .ensure_order_status_available(cmd.instrument_id, "order status reports")
537 },
538 self.generate_order_status_reports_impl(cmd),
539 )
540 .await
541 }
542
543 async fn generate_fill_reports(
544 &self,
545 cmd: GenerateFillReports,
546 ) -> anyhow::Result<Vec<FillReport>> {
547 let (instrument_id, venue_order_id) = (cmd.instrument_id, cmd.venue_order_id);
548 gate_report(
549 || match venue_order_id {
550 Some(venue_order_id) => self
551 .settlement
552 .ensure_order_resolved(&venue_order_id, "fill reports"),
553 None => self
554 .settlement
555 .ensure_resolved(instrument_id, "fill reports"),
556 },
557 Box::pin(self.generate_fill_reports_impl(cmd)),
558 )
559 .await
560 }
561
562 async fn generate_position_status_reports(
563 &self,
564 cmd: &GeneratePositionStatusReports,
565 ) -> anyhow::Result<Vec<PositionStatusReport>> {
566 gate_report(
567 || {
568 self.settlement
569 .ensure_resolved(cmd.instrument_id, "position status reports")
570 },
571 self.generate_position_status_reports_impl(cmd),
572 )
573 .await
574 }
575
576 async fn generate_mass_status(
577 &self,
578 lookback_mins: Option<u64>,
579 ) -> anyhow::Result<Option<ExecutionMassStatus>> {
580 gate_report(
581 || self.settlement.ensure_resolved(None, "mass status"),
582 self.generate_mass_status_impl(lookback_mins),
583 )
584 .await
585 }
586}
587
588async fn gate_report<T>(
591 gate: impl Fn() -> anyhow::Result<()>,
592 report: impl Future<Output = anyhow::Result<T>>,
593) -> anyhow::Result<T> {
594 gate()?;
595 let report = report.await?;
596 gate()?;
597 Ok(report)
598}
599
600#[cfg(test)]
601mod tests {
602 use std::{cell::RefCell, rc::Rc};
603
604 use nautilus_common::{cache::Cache, config::ConfigError};
605 use nautilus_model::{
606 enums::{AccountType, OmsType},
607 identifiers::{TraderId, Venue},
608 };
609 use rstest::rstest;
610
611 use super::*;
612 use crate::config::PolymarketInstrumentProviderConfig;
613
614 #[rstest]
615 #[tokio::test]
616 async fn test_gate_report_rechecks_settlement_after_venue_reads() {
617 let settlement = SettlementRegistry::new(AccountId::from("POLYMARKET-001"));
618
619 let result = gate_report(|| settlement.ensure_resolved(None, "mass status"), async {
620 settlement.quarantine_invalid_trade("trade-quarantined-during-read");
621 Ok(())
622 })
623 .await;
624
625 assert_eq!(
626 result.unwrap_err().to_string(),
627 "cannot generate mass status: Polymarket settlement registry holds 1 record(s) with \
628 unresolved evidence"
629 );
630 }
631
632 #[rstest]
633 #[case(PolymarketSignatureType::PolyProxy)]
634 #[case(PolymarketSignatureType::PolyGnosisSafe)]
635 #[case(PolymarketSignatureType::Poly1271)]
636 fn proxy_signature_types_require_funder(#[case] signature_type: PolymarketSignatureType) {
637 let error = resolve_maker_address(signature_type, "0xsigner", None).unwrap_err();
638
639 assert!(
640 error
641 .to_string()
642 .contains("requires a funder wallet address")
643 );
644 }
645
646 #[rstest]
647 #[case(PolymarketSignatureType::PolyProxy)]
648 #[case(PolymarketSignatureType::PolyGnosisSafe)]
649 #[case(PolymarketSignatureType::Poly1271)]
650 fn proxy_signature_types_require_distinct_funder(
651 #[case] signature_type: PolymarketSignatureType,
652 ) {
653 let error = resolve_maker_address(
654 signature_type,
655 "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
656 Some("0xABCDEFABCDEFABCDEFABCDEFABCDEFABCDEFABCD"),
657 )
658 .unwrap_err();
659
660 assert!(error.to_string().contains("requires a funder distinct"));
661 }
662
663 #[rstest]
664 #[case(None)]
665 #[case(Some("0xABCDEFABCDEFABCDEFABCDEFABCDEFABCDEFABCD"))]
666 fn eoa_uses_configured_funder_or_signer(#[case] funder: Option<&str>) {
667 let maker_address = resolve_maker_address(
668 PolymarketSignatureType::Eoa,
669 "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
670 funder,
671 )
672 .unwrap();
673
674 assert_eq!(maker_address, "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd");
675 }
676
677 #[rstest]
678 fn test_execution_client_rejects_duplicate_config_before_setup() {
679 let core = ExecutionClientCore::new(
680 TraderId::from("TESTER-001"),
681 ClientId::from("POLYMARKET"),
682 Venue::from("POLYMARKET"),
683 OmsType::Netting,
684 AccountId::from("POLYMARKET-001"),
685 AccountType::Cash,
686 None,
687 Rc::new(RefCell::new(Cache::default())),
688 );
689
690 let config = PolymarketExecutionClientConfig {
691 instrument_config: Some(PolymarketInstrumentProviderConfig {
692 series_ids: Some(vec![1, 1]),
693 ..Default::default()
694 }),
695 ..Default::default()
696 };
697
698 let error = PolymarketExecutionClient::new(core, config)
699 .expect_err("duplicate config must fail before credentials or client setup");
700 assert_eq!(
701 error.downcast_ref::<ConfigError>(),
702 Some(&ConfigError::duplicate("series_ids", None))
703 );
704 }
705
706 #[rstest]
707 #[case(
708 PolymarketSignatureType::Eoa,
709 "0x1111111111111111111111111111111111111111",
710 "requires the funder to equal"
711 )]
712 #[case(PolymarketSignatureType::Eoa, "invalid", "Invalid funder address")]
713 #[case(
714 PolymarketSignatureType::PolyProxy,
715 "invalid",
716 "Invalid funder address"
717 )]
718 #[case(
719 PolymarketSignatureType::PolyGnosisSafe,
720 "invalid",
721 "Invalid funder address"
722 )]
723 #[case(PolymarketSignatureType::Poly1271, "invalid", "Invalid funder address")]
724 fn maker_address_rejects_invalid_configuration(
725 #[case] signature_type: PolymarketSignatureType,
726 #[case] funder: &str,
727 #[case] expected: &str,
728 ) {
729 let error = resolve_maker_address(
730 signature_type,
731 "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
732 Some(funder),
733 )
734 .unwrap_err();
735 assert!(error.to_string().contains(expected));
736 }
737}