deribit_websocket/
lib.rs

1//! # Deribit WebSocket Client
2//!
3//! A high-performance, production-ready WebSocket client for the Deribit cryptocurrency derivatives exchange.
4//! This crate provides comprehensive real-time market data streaming, trading operations, and account management
5//! through Deribit's WebSocket API v2.
6//!
7//! ## Features
8//!
9//! - 🔌 **WebSocket Connection Management** - Robust connection handling with automatic reconnection and heartbeat
10//! - 📡 **JSON-RPC Protocol** - Complete JSON-RPC 2.0 implementation for Deribit API
11//! - 📊 **Real-time Market Data** - Live ticker, order book, trades, and chart data streaming
12//! - 📈 **Advanced Subscriptions** - Chart data aggregation and user position change notifications
13//! - 💰 **Mass Quote System** - High-performance mass quoting with MMP (Market Maker Protection) groups
14//! - 🔐 **Authentication** - Secure API key and signature-based authentication
15//! - 🛡️ **Error Handling** - Comprehensive error types with detailed recovery mechanisms
16//! - ⚡ **Async/Await** - Full async support with tokio runtime for high concurrency
17//! - 🔄 **Callback System** - Flexible message processing with primary and error callbacks
18//! - 📋 **Subscription Management** - Intelligent subscription tracking and channel management
19//! - 🧪 **Testing Support** - Complete test coverage with working examples
20//!
21//! ## Supported Subscription Channels
22//!
23//! ### Market Data Channels
24//! - `ticker.{instrument}` - Real-time ticker updates
25//! - `book.{instrument}.{group}` - Order book snapshots and updates
26//! - `trades.{instrument}` - Live trade executions
27//! - `chart.trades.{instrument}.{resolution}` - Aggregated chart data for technical analysis
28//!
29//! ### User Data Channels (Requires Authentication)
30//! - `user.orders` - Order status updates and fills
31//! - `user.trades` - User trade executions
32//! - `user.changes.{instrument}.{interval}` - Position and portfolio changes
33//!
34//! ## Protocol Support
35//!
36//! | Feature | Status | Description |
37//! |---------|--------|-------------|
38//! | JSON-RPC over WebSocket | ✅ Full Support | Complete JSON-RPC 2.0 implementation |
39//! | Market Data Subscriptions | ✅ Full Support | All public channels supported |
40//! | User Data Subscriptions | ✅ Full Support | Private channels with authentication |
41//! | Chart Data Streaming | ✅ Full Support | Real-time OHLCV data aggregation |
42//! | Authentication | ✅ API Key + Signature | Secure credential-based auth |
43//! | Connection Management | ✅ Auto-reconnect | Robust connection handling |
44//! | Error Recovery | ✅ Comprehensive | Detailed error types and handling |
45//!
46//! ## Quick Start
47//!
48//! ```rust,no_run
49//! use deribit_websocket::prelude::*;
50//!
51//! #[tokio::main]
52//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
53//!     // Initialize crypto provider for TLS connections
54//!     rustls::crypto::aws_lc_rs::default_provider()
55//!         .install_default()
56//!         .map_err(|_| "Failed to install crypto provider")?;
57//!
58//!     // Create client for testnet
59//!     let config = WebSocketConfig::default();
60//!     let mut client = DeribitWebSocketClient::new(&config)?;
61//!
62//!     // Set up message processing
63//!     client.set_message_handler(
64//!         |message| {
65//!             tracing::info!("Received: {}", message);
66//!             Ok(())
67//!         },
68//!         |message, error| {
69//!             tracing::error!("Error processing {}: {}", message, error);
70//!         }
71//!     );
72//!
73//!     // Connect and subscribe
74//!     client.connect().await?;
75//!     client.subscribe(vec!["ticker.BTC-PERPETUAL".to_string()]).await?;
76//!
77//!     // Start processing messages
78//!     client.start_message_processing_loop().await?;
79//!     Ok(())
80//! }
81//! ```
82//!
83//! ## Advanced Usage
84//!
85//! The client supports advanced subscription patterns for professional trading applications:
86//!
87//! ### Chart Data Streaming
88//! ```rust,no_run
89//! # use deribit_websocket::prelude::*;
90//! # #[tokio::main]
91//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
92//! # let config = WebSocketConfig::default();
93//! # let client = DeribitWebSocketClient::new(&config)?;
94//! // Subscribe to 1-minute chart data for BTC perpetual
95//! client.subscribe(vec!["chart.trades.BTC-PERPETUAL.1".to_string()]).await?;
96//! # Ok(())
97//! # }
98//! ```
99//!
100//! ### Position Change Monitoring
101//! ```rust,no_run
102//! # use deribit_websocket::prelude::*;
103//! # #[tokio::main]
104//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
105//! # let config = WebSocketConfig::default();
106//! # let client = DeribitWebSocketClient::new(&config)?;
107//! // Monitor real-time position changes (requires authentication)
108//! client.authenticate("client_id", "client_secret").await?;
109//! client.subscribe(vec!["user.changes.BTC-PERPETUAL.raw".to_string()]).await?;
110//! # Ok(())
111//! # }
112//! ```
113//!
114//! ### Mass Quote System
115//! ```rust,no_run
116//! # use deribit_websocket::prelude::*;
117//! # #[tokio::main]
118//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
119//! # let config = WebSocketConfig::default();
120//! # let mut client = DeribitWebSocketClient::new(&config)?;
121//! # client.connect().await?;
122//! # client.authenticate("client_id", "client_secret").await?;
123//! // Set up MMP group for mass quoting
124//! let mmp_config = MmpGroupConfig::new(
125//!     "btc_market_making".to_string(),
126//!     10.0,  // quantity_limit
127//!     5.0,   // delta_limit  
128//!     1000,  // interval (ms)
129//!     5000,  // frozen_time (ms)
130//! )?;
131//! client.set_mmp_config(mmp_config).await?;
132//!
133//! // Create and place mass quotes
134//! let quotes = vec![
135//!     Quote::buy("BTC-PERPETUAL".to_string(), 0.1, 45000.0),
136//!     Quote::sell("BTC-PERPETUAL".to_string(), 0.1, 55000.0),
137//! ];
138//! let request = MassQuoteRequest::new("btc_market_making".to_string(), quotes);
139//! let response = client.mass_quote(request).await?;
140//! # Ok(())
141//! # }
142//! ```
143//!
144//! ## Examples
145//!
146//! The crate includes comprehensive examples demonstrating:
147//! - **`basic_client.rs`** - Basic connection, subscription, and message handling
148//! - **`callback_example.rs`** - Advanced callback system with error handling
149//! - **`advanced_subscriptions.rs`** - Chart data and position change subscriptions
150//! - **`mass_quote_basic.rs`** - Basic mass quoting with MMP group setup
151//! - **`mass_quote_advanced.rs`** - Advanced mass quoting with multiple MMP groups and monitoring
152//! - **`mass_quote_options.rs`** - Options-specific mass quoting with delta management
153//!
154//! ## Architecture
155//!
156//! The client is built with a modular architecture:
157//! - **Connection Layer** - Low-level WebSocket connection management
158//! - **Session Layer** - Protocol-aware session handling with authentication
159//! - **Message Layer** - JSON-RPC request/response and notification handling
160//! - **Subscription Layer** - Channel management and subscription tracking
161//! - **Callback Layer** - Flexible message processing with error recovery
162
163#![warn(missing_docs)]
164#![deny(unsafe_code)]
165
166pub mod callback;
167pub mod client;
168pub mod config;
169pub mod connection;
170pub mod constants;
171pub mod error;
172pub mod message;
173pub mod model;
174/// Prelude module with commonly used types
175pub mod prelude;
176pub mod session;
177pub mod subscriptions;
178
179// Re-export common types from deribit-base
180pub use deribit_base;
deribit_websocket/lib.rs

deribit_websocket/
lib.rs
