kraken_api_client/rate_limit/
mod.rs

1//! Rate limiting for Kraken API.
2//!
3//! Kraken has strict rate limits that vary by endpoint type and verification tier.
4//! This module provides automatic rate limiting to prevent API bans.
5//!
6//! ## Rate Limit Categories
7//!
8//! - **Public endpoints**: Limited by IP address (sliding window)
9//! - **Private endpoints**: Limited by API key, varies by verification tier (token bucket)
10//! - **Trading endpoints**: Additional penalties for order placement/cancellation
11//!
12//! ## Example
13//!
14//! ```rust,ignore
15//! use kraken_api_client::spot::rest::SpotRestClient;
16//! use kraken_api_client::rate_limit::{RateLimitedClient, RateLimitConfig};
17//! use kraken_api_client::types::VerificationTier;
18//!
19//! // Wrap a client with automatic rate limiting
20//! let client = SpotRestClient::new();
21//! let rate_limited = RateLimitedClient::new(client, RateLimitConfig {
22//!     tier: VerificationTier::Intermediate,
23//!     enabled: true,
24//! });
25//!
26//! // All requests are automatically rate limited
27//! let time = rate_limited.get_server_time().await?;
28//! ```
29//!
30//! ## Low-Level Rate Limiters
31//!
32//! You can also use the rate limiters directly for custom logic:
33//!
34//! ```rust
35//! use kraken_api_client::rate_limit::{TtlCache, KeyedRateLimiter, TradingRateLimiter};
36//! use std::time::Duration;
37//!
38//! // Track orders for rate limit penalty calculation
39//! let mut order_cache: TtlCache<String, i64> = TtlCache::new(Duration::from_secs(300));
40//!
41//! // Per-pair rate limiting for order book requests
42//! let mut pair_limiter: KeyedRateLimiter<String> = KeyedRateLimiter::new(Duration::from_secs(1), 5);
43//!
44//! // Trading rate limiter with order lifetime penalties
45//! let mut trading_limiter = TradingRateLimiter::new(20, 1.0);
46//! ```
47
48mod client;
49mod keyed;
50mod trading;
51mod ttl_cache;
52
53pub use client::RateLimitedClient;
54pub use keyed::{KeyedRateLimiter, SlidingWindow};
55pub use trading::{OrderTrackingInfo, PerPairTradingLimiter, TradingRateLimiter};
56pub use ttl_cache::TtlCache;
57
58use crate::types::VerificationTier;
59
60/// Rate limiter configuration.
61#[derive(Debug, Clone)]
62pub struct RateLimitConfig {
63    /// Verification tier (affects rate limits).
64    pub tier: VerificationTier,
65    /// Whether to enable rate limiting.
66    pub enabled: bool,
67}
68
69impl Default for RateLimitConfig {
70    fn default() -> Self {
71        Self {
72            tier: VerificationTier::Starter,
73            enabled: true,
74        }
75    }
76}
77
78/// Rate limit constants by verification tier.
79pub mod limits {
80    /// Starter tier limits.
81    pub mod starter {
82        /// Maximum API counter value.
83        pub const MAX_COUNTER: u32 = 15;
84        /// Counter decay rate per second.
85        pub const DECAY_RATE: f64 = 0.33;
86    }
87
88    /// Intermediate tier limits.
89    pub mod intermediate {
90        /// Maximum API counter value.
91        pub const MAX_COUNTER: u32 = 20;
92        /// Counter decay rate per second.
93        pub const DECAY_RATE: f64 = 0.5;
94    }
95
96    /// Pro tier limits.
97    pub mod pro {
98        /// Maximum API counter value.
99        pub const MAX_COUNTER: u32 = 20;
100        /// Counter decay rate per second.
101        pub const DECAY_RATE: f64 = 1.0;
102    }
103
104    /// Trading rate limit constants.
105    pub mod trading {
106        /// Maximum orders per second.
107        pub const MAX_ORDERS_PER_SECOND: u32 = 60;
108        /// Penalty for orders under 5 seconds old when cancelled.
109        pub const CANCEL_PENALTY_UNDER_5S: u32 = 8;
110        /// Penalty for orders 5-10 seconds old when cancelled.
111        pub const CANCEL_PENALTY_5_TO_10S: u32 = 6;
112        /// Penalty for orders 10-15 seconds old when cancelled.
113        pub const CANCEL_PENALTY_10_TO_15S: u32 = 5;
114        /// Penalty for orders 15-45 seconds old when cancelled.
115        pub const CANCEL_PENALTY_15_TO_45S: u32 = 4;
116        /// Penalty for orders 45-90 seconds old when cancelled.
117        pub const CANCEL_PENALTY_45_TO_90S: u32 = 2;
118        /// Penalty for orders over 90 seconds old when cancelled.
119        pub const CANCEL_PENALTY_OVER_90S: u32 = 0;
120    }
121}
kraken_api_client/rate_limit/mod.rs

kraken_api_client/rate_limit/
mod.rs
