Qubx 1.1.3.dev10__tar.gz → 1.1.3.dev12__tar.gz

{qubx-1.1.3.dev10 → qubx-1.1.3.dev12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Qubx
-Version: 1.1.3.dev10
+Version: 1.1.3.dev12
 Summary: Qubx - Quantitative Trading Framework
 Project-URL: homepage, https://xlydian.com
 Project-URL: repository, https://github.com/xLydianSoftware/Qubx

{qubx-1.1.3.dev10 → qubx-1.1.3.dev12}/src/qubx/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.1.3.dev10'
-__version_tuple__ = version_tuple = (1, 1, 3, 'dev10')
+__version__ = version = '1.1.3.dev12'
+__version_tuple__ = version_tuple = (1, 1, 3, 'dev12')
 
 __commit_id__ = commit_id = None

{qubx-1.1.3.dev10 → qubx-1.1.3.dev12}/src/qubx/connectors/ccxt/connection_manager.py

@@ -12,7 +12,16 @@ from asyncio.exceptions import CancelledError
 from collections import defaultdict
 from typing import Awaitable, Callable
 
-from ccxt import BadSymbol, ExchangeClosedByUser, ExchangeError, ExchangeNotAvailable, NetworkError, UnsubscribeError
+from ccxt import (
+    BadSymbol,
+    DDoSProtection,
+    ExchangeClosedByUser,
+    ExchangeError,
+    ExchangeNotAvailable,
+    NetworkError,
+    RateLimitExceeded,
+    UnsubscribeError,
+)
 from ccxt.async_support.base.ws.client import Client as _WsClient
 from ccxt.pro import Exchange
 
@@ -145,6 +154,18 @@ class ConnectionManager:
                 )
                 await asyncio.sleep(1)
                 continue
+            except (RateLimitExceeded, DDoSProtection) as e:
+                # Rate limit hit — report to rate limiter if available and backoff
+                logger.warning(
+                    f"<yellow>{self._exchange_id}</yellow> Rate limited in {stream_name}: {e}"
+                )
+                if hasattr(self, "_exchange_manager") and self._exchange_manager.rate_limiter:
+                    self._exchange_manager.rate_limiter.report_limit_hit(
+                        pool_name="ccxt_rest", reason=f"{e.__class__.__name__}: {e}"
+                    )
+                await asyncio.sleep(min(2 ** (n_retry + 1), 60))
+                n_retry += 1
+                continue
             except (NetworkError, ExchangeError, ExchangeNotAvailable) as e:
                 # Network/exchange errors - retry after short delay
                 logger.error(

{qubx-1.1.3.dev10 → qubx-1.1.3.dev12}/src/qubx/connectors/ccxt/exchange_manager.py

@@ -254,6 +254,45 @@ class ExchangeManager:
     # === Exchange Property Access ===
     # Explicit property to access underlying CCXT exchange
 
+    # === Rate Limiting ===
+
+    def attach_rate_limiter(self, rate_limiter) -> None:
+        """Attach an ExchangeRateLimiter to this exchange manager.
+
+        Disables CCXT's built-in rate limiting and replaces the throttle
+        method with our rate limiter. Survives exchange recreation.
+
+        Args:
+            rate_limiter: ExchangeRateLimiter instance
+        """
+        self._rate_limiter = rate_limiter
+        self._apply_rate_limiter_to_exchange(self._exchange)
+        self.register_recreation_callback(lambda: self._apply_rate_limiter_to_exchange(self._exchange))
+        logger.info(f"Rate limiter attached to {self._exchange_name}")
+
+    def _apply_rate_limiter_to_exchange(self, exchange: cxp.Exchange) -> None:
+        """Disable CCXT's built-in rate limiter and install our throttle override."""
+        rate_limiter = getattr(self, "_rate_limiter", None)
+        if rate_limiter is None:
+            return
+
+        exchange.enableRateLimit = False
+
+        # Override the throttle method to use our rate limiter
+        # CCXT calls self.throttle(cost) in fetch2() before every REST request
+        # cost comes from calculateRateLimiterCost() which uses per-endpoint weights
+        async def _rate_limit_throttle(cost=None):
+            if cost is None:
+                cost = 1.0
+            await rate_limiter.acquire("ccxt_rest", weight_override=float(cost))
+
+        exchange.throttle = _rate_limit_throttle
+
+    @property
+    def rate_limiter(self):
+        """Access the attached rate limiter (if any)."""
+        return getattr(self, "_rate_limiter", None)
+
     @property
     def exchange(self) -> cxp.Exchange:
         """Access to the underlying CCXT exchange instance.

{qubx-1.1.3.dev10 → qubx-1.1.3.dev12}/src/qubx/connectors/ccxt/factory.py

@@ -129,6 +129,11 @@ def get_ccxt_exchange_manager(
         check_interval_seconds=check_interval_seconds,
     )
 
+    # Attach rate limiter if provided in kwargs
+    rate_limiter = kwargs.pop("rate_limiter", None)
+    if rate_limiter is not None:
+        manager.attach_rate_limiter(rate_limiter)
+
     _exchange_manager_cache[cache_key] = manager
     return manager
 

qubx-1.1.3.dev12/src/qubx/connectors/ccxt/rate_limits.py

@@ -0,0 +1,277 @@
+"""
+CCXT exchange rate limit configurations.
+
+Provides default rate limit configs per exchange, differentiated by market type
+(spot vs futures). Also includes response header parsers for syncing modeled
+state with exchange-reported usage.
+
+References:
+- Binance: https://binance-docs.github.io/apidocs/spot/en/#limits
+- Binance Futures: https://binance-docs.github.io/apidocs/futures/en/#limits
+- OKX: https://www.okx.com/docs-v5/en/#overview-rate-limit
+- Kraken: https://docs.kraken.com/api/docs/guides/rate-limits
+- Bybit: https://bybit-exchange.github.io/docs/v5/rate-limit
+"""
+
+from qubx.rate_limiting import EndpointCosts, ExchangeRateLimitConfig, PoolConfig
+
+
+def create_ccxt_rate_limit_config(exchange_name: str, ccxt_exchange=None) -> ExchangeRateLimitConfig:
+    """Create rate limit config for a CCXT exchange.
+
+    Handles exchange.market_type differentiation (spot vs futures).
+
+    Args:
+        exchange_name: Exchange name (e.g., "binance", "binance.um", "kraken")
+        ccxt_exchange: Optional CCXT exchange instance for auto-detection
+    """
+    name = exchange_name.lower()
+    base = name.split(".")[0]
+
+    if base in ("binance", "binanceusdm", "binancecoinm"):
+        return _binance_config(name)
+    elif base == "okx":
+        return _okx_config()
+    elif base == "bybit":
+        return _bybit_config()
+    elif base in ("kraken", "krakenfutures"):
+        return _kraken_config(name)
+    else:
+        return _default_config(exchange_name, ccxt_exchange)
+
+
+# === Binance ===
+
+
+def _binance_config(exchange_name: str) -> ExchangeRateLimitConfig:
+    """Binance rate limits differentiated by market type.
+
+    Spot:
+    - IP weight: 6000/min (recently increased from 1200)
+    - UID weight: 180,000/min
+    - Orders: 10/sec, 200,000/day per account
+
+    USDM Futures (binance.um):
+    - IP weight: 2400/min
+    - Orders: 300/10sec per account
+
+    COIN-M Futures (binance.cm):
+    - IP weight: 6000/min
+    - Orders: 300/10sec per account
+
+    Headers: X-MBX-USED-WEIGHT-1M, X-MBX-ORDER-COUNT-1S, X-MBX-ORDER-COUNT-1D
+    """
+    if exchange_name in ("binance.um", "binanceusdm"):
+        # USDM Futures
+        return ExchangeRateLimitConfig(
+            pools={
+                "ccxt_rest": PoolConfig("ccxt_rest", "ip", 2400, 40.0, cooldown=30.0),
+                "orders": PoolConfig("orders", "account", 300, 30.0, cooldown=10.0),
+            },
+            endpoint_map={"ccxt_rest": EndpointCosts([("ccxt_rest", 1)])},
+            default_costs=EndpointCosts([("ccxt_rest", 1)]),
+        )
+    elif exchange_name in ("binance.cm", "binancecoinm"):
+        # COIN-M Futures
+        return ExchangeRateLimitConfig(
+            pools={
+                "ccxt_rest": PoolConfig("ccxt_rest", "ip", 6000, 100.0, cooldown=30.0),
+                "orders": PoolConfig("orders", "account", 300, 30.0, cooldown=10.0),
+            },
+            endpoint_map={"ccxt_rest": EndpointCosts([("ccxt_rest", 1)])},
+            default_costs=EndpointCosts([("ccxt_rest", 1)]),
+        )
+    else:
+        # Spot
+        return ExchangeRateLimitConfig(
+            pools={
+                "ccxt_rest": PoolConfig("ccxt_rest", "ip", 6000, 100.0, cooldown=30.0),
+                "orders": PoolConfig("orders", "account", 10, 10.0, cooldown=10.0),
+            },
+            endpoint_map={"ccxt_rest": EndpointCosts([("ccxt_rest", 1)])},
+            default_costs=EndpointCosts([("ccxt_rest", 1)]),
+        )
+
+
+# === OKX ===
+
+
+def _okx_config() -> ExchangeRateLimitConfig:
+    """OKX rate limits (unified across spot/futures).
+
+    - REST: varies heavily by endpoint (2-60 req/2sec per endpoint)
+    - Trade endpoints: 60/2sec per account
+    - Market data: 20/2sec per IP
+
+    Headers: x-ratelimit-remaining, x-ratelimit-limit, x-ratelimit-reset
+    """
+    return ExchangeRateLimitConfig(
+        pools={
+            "ccxt_rest": PoolConfig("ccxt_rest", "ip", 20, 10.0, cooldown=15.0),
+            "orders": PoolConfig("orders", "account", 60, 30.0, cooldown=10.0),
+        },
+        endpoint_map={"ccxt_rest": EndpointCosts([("ccxt_rest", 1)])},
+        default_costs=EndpointCosts([("ccxt_rest", 1)]),
+    )
+
+
+# === Bybit ===
+
+
+def _bybit_config() -> ExchangeRateLimitConfig:
+    """Bybit rate limits (unified v5 API).
+
+    - REST: 10 req/sec per endpoint per IP (varies by endpoint)
+    - Orders: 10/sec per account
+    - Rate limit info in response body: rate_limit_status, rate_limit_reset_ms
+    """
+    return ExchangeRateLimitConfig(
+        pools={
+            "ccxt_rest": PoolConfig("ccxt_rest", "ip", 120, 24.0, cooldown=15.0),
+            "orders": PoolConfig("orders", "account", 10, 10.0, cooldown=10.0),
+        },
+        endpoint_map={"ccxt_rest": EndpointCosts([("ccxt_rest", 1)])},
+        default_costs=EndpointCosts([("ccxt_rest", 1)]),
+    )
+
+
+# === Kraken ===
+
+
+def _kraken_config(exchange_name: str) -> ExchangeRateLimitConfig:
+    """Kraken rate limits.
+
+    Kraken Spot uses a unique "call counter" system:
+    - Each API call adds to a counter (1-6 depending on endpoint)
+    - Counter decays at a fixed rate based on verification level
+    - Intermediate verified: max counter 20, decay 0.33/sec
+    - Pro verified: max counter 20, decay 1.0/sec
+
+    Per-endpoint costs from CCXT:
+    - Public: 1.0-1.2 per call
+    - Private: 0-6 per call (orders=0, balance=3, ledgers=6)
+    - Orders: cost 0 (separate matching engine limit)
+
+    Kraken Futures:
+    - Simple: ~1.67 req/sec (600ms rateLimit)
+    - No per-endpoint weights documented
+
+    Matching engine (order) limits (separate from REST):
+    - Spot: based on tier, typically 60/min for intermediate
+    - Futures: separate per-instrument limits
+    """
+    if exchange_name in ("krakenfutures",):
+        return ExchangeRateLimitConfig(
+            pools={
+                "ccxt_rest": PoolConfig("ccxt_rest", "ip", 10, 1.67, cooldown=15.0),
+            },
+            endpoint_map={"ccxt_rest": EndpointCosts([("ccxt_rest", 1)])},
+            default_costs=EndpointCosts([("ccxt_rest", 1)]),
+        )
+
+    # Kraken Spot — counter-decay system maps to token bucket:
+    # capacity=20 (max counter), refill=0.33/sec (intermediate) or 1.0/sec (pro)
+    # Using intermediate as default — can be overridden via config
+    return ExchangeRateLimitConfig(
+        pools={
+            # Main REST counter (per IP, decays at 0.33/sec for intermediate tier)
+            "ccxt_rest": PoolConfig("ccxt_rest", "ip", 20, 0.33, cooldown=30.0),
+            # Order matching engine (separate limit per account)
+            "orders": PoolConfig("orders", "account", 60, 1.0, cooldown=15.0),
+        },
+        endpoint_map={
+            # CCXT defines per-endpoint costs for Kraken — these are the weights
+            # that get passed through CCXT's calculateRateLimiterCost → our throttle override.
+            # Key costs: Balance=3, ClosedOrders=3, TradesHistory=6, Ledgers=6
+            # Orders have cost=0 in the REST counter (separate matching engine limit)
+            "ccxt_rest": EndpointCosts([("ccxt_rest", 1)]),
+        },
+        default_costs=EndpointCosts([("ccxt_rest", 1)]),
+    )
+
+
+# === Default ===
+
+
+def _default_config(exchange_name: str, ccxt_exchange=None) -> ExchangeRateLimitConfig:
+    """Default conservative config for unknown exchanges.
+
+    Derives from CCXT's rateLimit property if exchange instance provided.
+    """
+    rate_limit_ms = 50  # default: 20 req/sec
+    if ccxt_exchange and hasattr(ccxt_exchange, "rateLimit"):
+        rate_limit_ms = ccxt_exchange.rateLimit or 50
+
+    rps = 1000.0 / rate_limit_ms
+    capacity = rps * 60  # 1 minute capacity
+
+    return ExchangeRateLimitConfig(
+        pools={
+            "ccxt_rest": PoolConfig("ccxt_rest", "ip", capacity, rps, cooldown=15.0),
+        },
+        endpoint_map={"ccxt_rest": EndpointCosts([("ccxt_rest", 1)])},
+        default_costs=EndpointCosts([("ccxt_rest", 1)]),
+    )
+
+
+# === Response Header Parsers ===
+
+
+def parse_binance_headers(headers: dict, rate_limiter) -> None:
+    """Parse Binance rate limit headers and sync with rate limiter.
+
+    Binance returns:
+    - X-MBX-USED-WEIGHT-1M: weight used in current 1-minute window
+    - X-MBX-ORDER-COUNT-1S: orders placed in current 1-second window
+    - X-MBX-ORDER-COUNT-1D: orders placed in current day
+    """
+    if rate_limiter is None:
+        return
+
+    # Try both casing conventions (CCXT normalizes to lowercase)
+    used_weight = headers.get("x-mbx-used-weight-1m") or headers.get("X-MBX-USED-WEIGHT-1M")
+    if used_weight:
+        try:
+            rate_limiter.sync_from_exchange("ccxt_rest", used=int(used_weight))
+        except Exception:
+            pass
+
+    order_count = headers.get("x-mbx-order-count-1s") or headers.get("X-MBX-ORDER-COUNT-1S")
+    if order_count and "orders" in rate_limiter.config.pools:
+        try:
+            rate_limiter.sync_from_exchange("orders", used=int(order_count))
+        except Exception:
+            pass
+
+
+def parse_okx_headers(headers: dict, rate_limiter) -> None:
+    """Parse OKX rate limit headers and sync with rate limiter.
+
+    OKX returns:
+    - x-ratelimit-remaining: remaining requests for this endpoint
+    - x-ratelimit-limit: total limit for this endpoint
+    - x-ratelimit-reset: timestamp when limit resets (ms)
+    """
+    if rate_limiter is None:
+        return
+
+    remaining = headers.get("x-ratelimit-remaining") or headers.get("X-RateLimit-Remaining")
+    if remaining:
+        try:
+            rate_limiter.sync_from_exchange("ccxt_rest", remaining=float(remaining))
+        except Exception:
+            pass
+
+
+HEADER_PARSERS = {
+    "binance": parse_binance_headers,
+    "binanceusdm": parse_binance_headers,
+    "binancecoinm": parse_binance_headers,
+    "okx": parse_okx_headers,
+}
+
+
+def get_header_parser(exchange_name: str):
+    """Get the response header parser for an exchange."""
+    name = exchange_name.lower().split(".")[0]
+    return HEADER_PARSERS.get(name)

{qubx-1.1.3.dev10 → qubx-1.1.3.dev12}/src/qubx/core/context.py

@@ -159,6 +159,9 @@ class StrategyContext(IStrategyContext):
         data_throttler: "InstrumentThrottler | None" = None,
         state_persistence: IStatePersistence | None = None,
         state_snapshot_interval: str | None = None,
+        rate_limit_backend: Any | None = None,
+        rate_limiting_config: Any | None = None,
+        event_loop: "asyncio.AbstractEventLoop | None" = None,
     ) -> None:
         self.account = account
         self.strategy = self.__instantiate_strategy(strategy, config)
@@ -190,6 +193,9 @@ class StrategyContext(IStrategyContext):
         self.health = self._health_monitor
         self._state_persistence = state_persistence or DummyStatePersistence()
         self._state_snapshot_interval = state_snapshot_interval
+        self._rate_limit_backend = rate_limit_backend
+        self._rate_limiting_config = rate_limiting_config
+        self.event_loop = event_loop
 
         # Initialize shutdown handling
         self._stop_lock = Lock()
@@ -308,6 +314,16 @@ class StrategyContext(IStrategyContext):
         # Configure periodic state snapshot persistence
         self._processing_manager.configure_state_snapshot(self._state_snapshot_interval)
 
+        # Collect rate limiters from data providers
+        for dp in self._data_providers:
+            rl = dp.rate_limiter
+            if rl is not None:
+                self.rate_limiters[rl.exchange] = rl
+
+        # Configure periodic rate limit metric emission
+        _rl_metrics_interval = self._rate_limiting_config.metrics_interval if self._rate_limiting_config else None
+        self._processing_manager.configure_rate_limit_metrics(_rl_metrics_interval)
+
         if self.is_simulation and isinstance(self.account, CompositeAccountProcessor):
             # Auto-assign simulation transfer manager
             from qubx.backtester.transfers import SimulationTransferManager
@@ -573,6 +589,22 @@ class StrategyContext(IStrategyContext):
     def persistence(self) -> IStatePersistence:
         return self._state_persistence
 
+    @property
+    def rate_limiters(self) -> dict:
+        """Registry of ExchangeRateLimiter instances by exchange name.
+
+        Connectors register their rate limiters here at startup.
+        Used by the processing mixin for periodic metric emission.
+        """
+        if not hasattr(self, "_rate_limiters"):
+            self._rate_limiters: dict = {}
+        return self._rate_limiters
+
+    @property
+    def rate_limit_backend(self):
+        """Rate limit storage backend (InMemoryBackend or RedisBackend)."""
+        return self._rate_limit_backend
+
     # IAccountViewer delegation
 
     # capital information

{qubx-1.1.3.dev10 → qubx-1.1.3.dev12}/src/qubx/core/interfaces.py

@@ -831,6 +831,11 @@ class IDataProvider:
         """
         raise NotImplementedError("exchange() is not implemented")
 
+    @property
+    def rate_limiter(self):
+        """Return the ExchangeRateLimiter for this provider, if any."""
+        return None
+
     def is_connected(self) -> bool:
         """
         Check if the data provider is currently connected to the exchange.

{qubx-1.1.3.dev10 → qubx-1.1.3.dev12}/src/qubx/core/mixins/processing.py

@@ -293,6 +293,47 @@ class ProcessingManager(IProcessingManager):
                 self._scheduler.schedule_event(cron_schedule, "state_snapshot")
                 logger.info(f"State snapshot enabled with interval: {interval}")
 
+    def configure_rate_limit_metrics(self, interval: str | None) -> None:
+        """
+        Configure periodic rate limit metric emission.
+
+        Emits pool utilization, gate state, hit counts etc. for all registered
+        rate limiters via ctx.emitter.emit(). Only active in live mode.
+
+        Args:
+            interval: Emission interval (e.g., "60s", "1m"). None to disable.
+        """
+        self._scheduler.unschedule_event("rate_limit_metrics")
+
+        if interval is not None and not self._is_simulation:
+            cron_schedule = interval_to_cron(interval)
+            self._scheduler.schedule_event(cron_schedule, "rate_limit_metrics")
+            self._custom_scheduled_methods["rate_limit_metrics"] = self._emit_rate_limit_metrics
+            logger.info(f"Rate limit metrics emission enabled with interval: {interval}")
+
+    def _emit_rate_limit_metrics(self, ctx) -> None:
+        """Emit rate limit metrics for all registered rate limiters."""
+        import asyncio
+        import concurrent.futures
+
+        if ctx.emitter is None or ctx.event_loop is None:
+            return
+
+        for exchange_name, rate_limiter in ctx.rate_limiters.items():
+            try:
+                future = asyncio.run_coroutine_threadsafe(rate_limiter.collect_metrics(), ctx.event_loop)
+                metrics = future.result(timeout=5)
+                self._do_emit_metrics(ctx, metrics)
+            except concurrent.futures.TimeoutError:
+                logger.warning(f"Rate limit metrics collection timed out for {exchange_name}")
+            except Exception as e:
+                logger.error(f"Failed to collect rate limit metrics for {exchange_name}: {e}")
+
+    @staticmethod
+    def _do_emit_metrics(ctx, metrics: list[dict]) -> None:
+        for m in metrics:
+            ctx.emitter.emit(m["name"], m["value"], m["tags"])
+
     def process_data(self, instrument: Instrument, d_type: str, data: Any, is_historical: bool) -> bool:
         should_stop = self.__process_data(instrument, d_type, data, is_historical)
         if not is_historical:

qubx-1.1.3.dev12/src/qubx/rate_limiting/__init__.py

@@ -0,0 +1,32 @@
+"""
+Exchange-aware rate limiting engine.
+
+Provides a shared, multi-pool rate limiting system that connectors use
+to comply with exchange API limits. Supports per-IP and per-account scoping,
+gate mechanism for cooldowns, and optional Redis backend for cross-bot coordination.
+
+Usage:
+    >>> from qubx.rate_limiting import ExchangeRateLimiter, ExchangeRateLimitConfig, PoolConfig, EndpointCosts
+    >>>
+    >>> config = ExchangeRateLimitConfig(
+    ...     pools={"rest": PoolConfig("rest", "ip", 1200, 20.0)},
+    ...     endpoint_map={"fetch_ohlcv": EndpointCosts([("rest", 5)])},
+    ...     default_costs=EndpointCosts([("rest", 1)]),
+    ... )
+    >>> limiter = ExchangeRateLimiter("binance", config)
+    >>> await limiter.acquire("fetch_ohlcv")
+"""
+
+from qubx.rate_limiting.backend import IRateLimitBackend, InMemoryBackend
+from qubx.rate_limiting.config import EndpointCosts, ExchangeRateLimitConfig, PoolConfig
+from qubx.rate_limiting.engine import ExchangeRateLimiter, RateLimitGateTimeout
+
+__all__ = [
+    "EndpointCosts",
+    "ExchangeRateLimitConfig",
+    "ExchangeRateLimiter",
+    "IRateLimitBackend",
+    "InMemoryBackend",
+    "PoolConfig",
+    "RateLimitGateTimeout",
+]

qubx-1.1.3.dev12/src/qubx/rate_limiting/backend.py

@@ -0,0 +1,83 @@
+"""
+Rate limit storage backends.
+
+Provides the interface and in-memory implementation for token bucket state.
+Redis backend can be added later for cross-bot coordination.
+"""
+
+import time
+from abc import ABC, abstractmethod
+
+from qubx.utils.rate_limiter import TokenBucketRateLimiter
+
+
+class IRateLimitBackend(ABC):
+    """Interface for rate limit token storage.
+
+    Backends manage token bucket state — either in-process (InMemoryBackend)
+    or distributed (RedisBackend for cross-bot coordination).
+    """
+
+    @abstractmethod
+    async def acquire(self, key: str, weight: float, capacity: float, refill_rate: float) -> float:
+        """Acquire tokens from a bucket. Blocks until available.
+
+        Args:
+            key: Unique bucket identifier (e.g., "ratelimit:binance:rest:ip_1.2.3.4")
+            weight: Tokens to consume
+            capacity: Bucket capacity (used to create bucket on first access)
+            refill_rate: Tokens per second (used to create bucket on first access)
+
+        Returns:
+            Time spent waiting in seconds (0.0 if immediate)
+        """
+
+    @abstractmethod
+    async def get_remaining(self, key: str) -> float | None:
+        """Get remaining tokens for a key (non-blocking).
+
+        Returns:
+            Token count, or None if key doesn't exist
+        """
+
+    @abstractmethod
+    async def set_remaining(self, key: str, remaining: float) -> None:
+        """Force-set remaining tokens (for syncing with exchange-reported state).
+
+        Used when exchange headers/responses tell us the actual remaining budget,
+        correcting any drift in our model.
+        """
+
+
+class InMemoryBackend(IRateLimitBackend):
+    """In-process token bucket backend.
+
+    Each key gets its own TokenBucketRateLimiter instance.
+    Suitable for single-bot usage without cross-bot coordination.
+    """
+
+    def __init__(self):
+        self._limiters: dict[str, TokenBucketRateLimiter] = {}
+
+    def _get_or_create(self, key: str, capacity: float, refill_rate: float) -> TokenBucketRateLimiter:
+        if key not in self._limiters:
+            self._limiters[key] = TokenBucketRateLimiter(capacity, refill_rate, name=key)
+        return self._limiters[key]
+
+    async def acquire(self, key: str, weight: float, capacity: float, refill_rate: float) -> float:
+        limiter = self._get_or_create(key, capacity, refill_rate)
+        start = time.monotonic()
+        await limiter.acquire(weight)
+        return time.monotonic() - start
+
+    async def get_remaining(self, key: str) -> float | None:
+        limiter = self._limiters.get(key)
+        if limiter is None:
+            return None
+        return limiter.get_available_tokens()
+
+    async def set_remaining(self, key: str, remaining: float) -> None:
+        limiter = self._limiters.get(key)
+        if limiter is not None:
+            limiter._tokens = remaining
+            limiter._last_refill = time.monotonic()