hypercall_vol_oracle/
lib.rs

1//! Volatility Oracle module for fetching implied volatility data.
2//!
3//! This module provides real-time volatility surface data from Block Scholes
4//! via WebSocket API for use in margin calculations and options pricing.
5//!
6//! # Example
7//!
8//! ```ignore
9//! use hypercall_vol_oracle::{BlockScholesVolOracle, BlockScholesVolOracleConfig};
10//! use std::sync::Arc;
11//!
12//! let config = BlockScholesVolOracleConfig {
13//!     symbols: vec!["BTC".to_string(), "ETH".to_string()],
14//!     ..Default::default()
15//! };
16//!
17//! let oracle = Arc::new(BlockScholesVolOracle::new(config));
18//! let handle = oracle.start_polling();
19//!
20//! // Later, query volatility
21//! if let Some(vol) = oracle.get_vol("BTC", 100000.0, 1735689600).await {
22//!     println!("BTC 100k strike vol: {:.2}%", vol * 100.0);
23//! }
24//! ```
25
26use async_trait::async_trait;
27use std::sync::Arc;
28use tokio::task::JoinHandle;
29
30pub mod blockscholes_oracle;
31pub mod blockscholes_types;
32pub mod databento_oracle;
33pub mod deribit_oracle;
34pub mod derive_oracle;
35pub mod fixed_oracle;
36pub mod polygon_oracle;
37pub mod polymarket_oracle;
38pub mod realized_vol_oracle;
39pub mod risk_oracle;
40pub mod routed_oracle;
41pub mod sticky_moneyness_oracle;
42pub mod vol_surface_cache;
43
44/// Provider runtime trait for polling or streaming live volatility data.
45///
46/// This is intentionally separate from the engine-facing risk-vol lookup trait.
47/// Startup and provider implementations use this for provider lifecycle and
48/// direct surface inspection.
49#[async_trait]
50pub trait PollingVolOracle: Send + Sync {
51    /// Start the WebSocket connection and begin receiving volatility updates.
52    fn start_polling(self: Arc<Self>) -> JoinHandle<()>;
53
54    /// Get the implied volatility for a specific point on the surface.
55    async fn get_vol(&self, symbol: &str, strike: f64, expiry: i64) -> Option<f64>;
56
57    /// Get the ATM volatility for a symbol at a given expiry.
58    async fn get_atm_vol(&self, symbol: &str, expiry: i64) -> Option<f64>;
59
60    /// Check if the oracle is healthy.
61    async fn is_healthy(&self) -> bool;
62
63    /// Get the last update timestamp in milliseconds.
64    async fn last_update_timestamp(&self) -> Option<i64>;
65}
66
67pub use blockscholes_oracle::{
68    BlockScholesVolOracle, BlockScholesVolOracleConfig, DEFAULT_CACHE_TTL_MS,
69};
70pub use blockscholes_types::{
71    BlockScholesMessage, BlockScholesSubscribe, VolSurfacePoint, VolSurfaceUpdateMessage,
72};
73pub use databento_oracle::{DatabentoVolOracle, DatabentoVolOracleConfig};
74pub use deribit_oracle::{DeribitVolOracle, DeribitVolOracleConfig, DEFAULT_DERIBIT_BASE_URL};
75pub use derive_oracle::{DeriveVolOracle, DeriveVolOracleConfig, DEFAULT_DERIVE_BASE_URL};
76pub use fixed_oracle::FixedTestRiskVolOracle;
77pub use polygon_oracle::{
78    PlatformSpotPrices, PolygonUnderlyingConfig, PolygonVolOracle, PolygonVolOracleConfig,
79    DEFAULT_POLYGON_BASE_URL,
80};
81pub use polymarket_oracle::{PolymarketVolOracle, PolymarketVolOracleConfig};
82pub use realized_vol_oracle::{RealizedVolOracle, RealizedVolOracleConfig};
83pub use risk_oracle::{
84    RiskVolOracle, RiskVolOracle as VolOracle, SharedRiskVolOracle, SharedVolOracle,
85    VolLookupError, VolOracleStatus, VolProviderKind, VolSurfaceSnapshot,
86};
87pub use routed_oracle::RoutedVolOracle;
88pub use sticky_moneyness_oracle::{StickyMoneynessVolOracle, StickyMoneynessVolOracleConfig};
89pub use vol_surface_cache::{DeltaCurveExport, DeltaIvExport, VolPoint, VolatilitySurface};
hypercall_vol_oracle/lib.rs

hypercall_vol_oracle/
lib.rs
