nautechsystems/nautilus_trader · error

Binance Futures aggregate trade history is limited to the pa

Error message

Binance Futures aggregate trade history is limited to the past 24 hours

What it means

Thrown by BinanceFuturesHttpClient::request_agg_trades when the requested start or end timestamp is earlier than the client clock's current time minus 24 hours. Binance's futures aggTrades endpoint genuinely only serves the recent window (unlike spot), so the client validates both bounds up front against clock.get_time_ns() and rejects requests that would silently return partial or empty data. Either bound being older than the cutoff fails the whole call, even if the other bound is recent.

Source

Thrown at crates/adapters/binance/src/futures/http/client.rs:2932

        Ok(result)
    }

    /// Requests bounded aggregate public trades for an instrument.
    ///
    /// # Errors
    ///
    /// Returns an error if a supplied time bound is invalid or parsing fails.
    pub async fn request_agg_trades(
        &self,
        instrument_id: InstrumentId,
        start: Option<Timestamp>,
        end: Option<Timestamp>,
        limit: Option<u32>,
    ) -> anyhow::Result<Vec<TradeTick>> {
        let cutoff =
            self.clock.get_time_ns().to_datetime_utc() - jiff::SignedDuration::from_hours(24);
        anyhow::ensure!(
            start.as_ref().is_none_or(|value| value >= &cutoff)
                && end.as_ref().is_none_or(|value| value >= &cutoff),
            "Binance Futures aggregate trade history is limited to the past 24 hours"
        );
        let (symbol, price_precision, size_precision) =
            self.cached_precisions_by_id(instrument_id)?;
        let params = BinanceAggTradesParams {
            symbol,
            from_id: None,
            start_time: start.map(|value| value.as_millisecond()),
            end_time: end.map(|value| value.as_millisecond()),
            limit,
        };
        let trades = self.inner.agg_trades(&params).await?;
        trades
            .iter()
            .map(|trade| {
                let ts_init = parse_millis(trade.time, "Futures aggregate trade time")?;

View on GitHub (pinned to a4b06ed870)

Solutions

1. Clamp both start and end to be >= now - 24h (or pass None) before calling
2. For history older than 24h, use request_binance_bars (klines), which serves deep history, and reconstruct aggregates from bars
3. Double-check timestamp units and timezone — NautilusTrader Timestamps are ns-since-epoch UTC; ensure no ms/s mix-up
4. In tests, align the injected clock with realistic present time before asserting on this API

Example fix

// before
let trades = client.request_agg_trades(inst, Some(start_3_days_ago), None, None).await?;

// after
let cutoff = client.clock.get_time_ns().to_datetime_utc() - jiff::SignedDuration::from_hours(24);
let start = start.max(Timestamp::from_datetime_utc(cutoff));
let trades = client.request_agg_trades(inst, Some(start), None, None).await?;

let cutoff = clock.get_time_ns().to_datetime_utc() - jiff::SignedDuration::from_hours(24);
let start = start.filter(|t| *t >= Timestamp::from_datetime_utc(cutoff));
let end = end.filter(|t| *t >= Timestamp::from_datetime_utc(cutoff));
let trades = client.request_agg_trades(inst, start, end, limit).await?;

Catch the message, clamp both bounds to the 24h cutoff (or None), and retry once; if older data is required, switch to request_binance_bars for klines.

When it happens

Trigger: Requesting aggTrades with a start_ts from days or weeks ago (e.g. for backfill or warm-up of short-horizon signals); passing an end timestamp that predates the cutoff because of unit or timezone confusion; running against a clock set later than real time (test clock) so the cutoff moves forward and a request valid yesterday now fails.

Common situations: Porting spot-market backfill code to futures; strategies requesting 'trades since session start' where the session began >24h ago; a backtest/test clock advanced beyond the data window; millisecond-vs-nanosecond timestamp mix-ups making bounds look ancient.

Related errors

• Invalid venue order ID: {e}
• Cancel algo order failed: code={}, msg={}
• Cancel all orders failed: {}
• Cancel all algo orders failed: {}
• Instrument not found in cache: {symbol}

AI-assisted analysis of nautechsystems/nautilus_trader@a4b06ed870 (2026-08-16). Data as JSON: /api/errors/0c3a8ee1b319f899. Report an issue: GitHub.