fix: re-verify normalized volume margin in calculate_volume_by_margin (#46 )

* fix: re-verify normalized volume margin before returning from calculate_volume_by_margin For CFDs, index products, and tiered-margin instruments, the initial min-lot margin estimate can be optimistic; the normalized stepped volume may require more margin than available_margin. After computing the normalized volume, step down by volume_step until order_calc_margin confirms affordability, or return 0.0 if no step is affordable. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * test: fix ruff line-length violations in calculate_volume_by_margin tests Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix: use integer step index and add actual>0 guard in calculate_volume_by_margin Replace float-subtraction loop with integer step index to eliminate accumulation rounding error and add `actual > 0` guard so a broker returning zero/negative margin is never accepted as affordable. Inline `capped` to keep local-variable count within Ruff PLR0914 limit. Update docstring to reflect re-verification behaviour and 0.0 fallback. Tighten test assertion from `volume > 0` to the symbol's valid range. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Bump version to v0.9.1 * perf: replace linear step-down scan with binary search in calculate_volume_by_margin Resolves the P2 review finding: the previous O(n) loop called order_calc_margin once per volume step, making sizing appear hung for symbols with a large step range or small volume_step. Binary search over the integer step index finds the largest affordable step in O(log n) IPC calls (≈17 for a 99 999-step range vs up to 99 999 in the worst case). Monotonicity of broker margin with volume is assumed, which holds for standard linear margin schedules. To stay within the PLR0914 local-variable limit the steps variable is inlined into hi and the tick temporary is eliminated by accessing the snapshot dict directly. Error messages still go via msg to satisfy EM102. Two existing tests are updated to match the binary-search call sequence. A new regression test (volume_min=0.01, volume_max=1000.0) configures a tiered-margin mock with its threshold at step 50000 and asserts that the total order_calc_margin call count does not exceed 25. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * chore: remove obsolete TC003 per-file-ignore for history.py Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: agent <agent@localhost> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
fix: handle NumPy object rate timestamps
2026-06-23 04:40:00 +09:00 · 2026-06-22 23:01:31 +09:00 · 2026-06-22 22:52:19 +09:00
13 changed files with 821 additions and 53 deletions
@@ -104,8 +104,8 @@ A reliable pattern is:
 Example GraphQL mutation shape:

 ```graphql
-mutation($threadId: ID!) {
-  resolveReviewThread(input: {threadId: $threadId}) {
+mutation ($threadId: ID!) {
+  resolveReviewThread(input: { threadId: $threadId }) {
    thread {
      id
      isResolved
@@ -19,20 +19,27 @@ alias for new code.

 ### Session lifecycle and configuration

-| Symbol                                          | Role                                                             |
-| ----------------------------------------------- | ---------------------------------------------------------------- |
-| `MT5Client`, `Mt5CliClient`                     | Read-only data client with optional `order_check` / `order_send` |
-| `build_config`                                  | Build `pdmt5.Mt5Config` from connection fields                   |
-| `mt5_session`                                   | Context manager: initialize, login, yield client, shutdown       |
-| `create_trading_client`, `mt5_trading_session`  | Trading-capable `pdmt5.Mt5TradingClient` lifecycle               |
-| `AccountSpec`                                   | Generic account group: symbols plus optional credentials         |
-| `resolve_account_spec`, `resolve_account_specs` | Merge overrides and expand `${ENV_VAR}` placeholders             |
-| `substitute_env_placeholders`                   | Replace `${NAME}` substrings from the environment                |
+| Symbol                                          | Role                                                                                                       |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `MT5Client`, `Mt5CliClient`                     | Read-only data client with optional `order_check` / `order_send`                                           |
+| `build_config`                                  | Build `pdmt5.Mt5Config` from connection fields                                                             |
+| `mt5_session`                                   | Context manager: initialize, login, yield client, shutdown                                                 |
+| `create_trading_client`, `mt5_trading_session`  | Trading-capable `pdmt5.Mt5TradingClient` lifecycle                                                         |
+| `AccountSpec`                                   | Generic account group: symbols plus optional credentials                                                   |
+| `resolve_account_spec`, `resolve_account_specs` | Merge overrides and expand `${ENV_VAR}` placeholders; opt-in `allow_whole_dollar_env` for bare `$NAME`     |
+| `substitute_env_placeholders`                   | Replace `${NAME}` substrings from the environment; opt-in `allow_whole_dollar_env` for whole-value `$NAME` |

 Credential resolution is generic: any environment variable name may appear inside
 `${...}`. mt5cli does not hard-code application-specific keys such as
 `mt5_login` or `mt5_exe`.

+Pass `allow_whole_dollar_env=True` to `substitute_env_placeholders()`,
+`resolve_account_spec()`, `resolve_account_specs()`, and `build_config()` to
+additionally expand strings whose entire value is a bare `$ENV_NAME` identifier.
+Partial strings such as `"plan$pass"`, `"abc$ENV"`, or `"$ENV-suffix"` are
+**never** expanded — only an exact `$IDENTIFIER` whole-string match qualifies.
+Default is `False` to preserve backward compatibility.
+
 ### Read-only MT5 data access

 Module-level helpers open a transient connection per call. Prefer `mt5_session`
@@ -56,15 +63,16 @@ MetaTrader 5 returns the still-forming bar as the last row when
 `start_pos=0`. Use these helpers instead of reimplementing bar trimming or
 timestamp normalization in downstream apps.

-| Symbol                                           | Role                                                         |
-| ------------------------------------------------ | ------------------------------------------------------------ |
-| `drop_forming_rate_bar`                          | Remove the last row from chronologically ordered rate data   |
-| `fetch_latest_closed_rates`                      | Single connected client: fetch `count + 1`, drop forming bar |
-| `fetch_latest_closed_rates_for_trading_client`   | Closed bars from an active `Mt5TradingClient` session        |
-| `collect_latest_closed_rates_for_accounts`       | Multi-account closed bars with optional retry wrapper        |
-| `collect_latest_closed_rates_by_granularity`     | Same data keyed by `(symbol, granularity_name)`              |
-| `collect_latest_rates_for_accounts`              | Latest bars including the forming bar when `start_pos=0`     |
-| `collect_latest_rates_for_accounts_with_retries` | Bounded exponential backoff for transient MT5 errors         |
+| Symbol                                           | Role                                                                            |
+| ------------------------------------------------ | ------------------------------------------------------------------------------- |
+| `drop_forming_rate_bar`                          | Remove the last row from chronologically ordered rate data                      |
+| `fetch_latest_closed_rates`                      | Single connected client: fetch `count + 1`, drop forming bar                    |
+| `fetch_latest_closed_rates_for_trading_client`   | Closed bars from an active `Mt5TradingClient` session; returns RangeIndex       |
+| `fetch_latest_closed_rates_indexed`              | Same as above but returns a UTC `DatetimeIndex` named `"time"` (no time column) |
+| `collect_latest_closed_rates_for_accounts`       | Multi-account closed bars with optional retry wrapper                           |
+| `collect_latest_closed_rates_by_granularity`     | Same data keyed by `(symbol, granularity_name)`                                 |
+| `collect_latest_rates_for_accounts`              | Latest bars including the forming bar when `start_pos=0`                        |
+| `collect_latest_rates_for_accounts_with_retries` | Bounded exponential backoff for transient MT5 errors                            |

 ### SQLite history collection and rate loading

@@ -97,7 +105,7 @@ strategy entries, exits, Kelly sizing, or signal logic.
 | `detect_position_side`                                                                             | Net long / short / flat from open positions   |
 | `calculate_spread_ratio`                                                                           | Relative bid-ask spread                       |
 | `calculate_margin_and_volume`, `calculate_volume_by_margin`, `calculate_new_position_margin_ratio` | Margin budget and volume sizing               |
-| `normalize_order_volume`, `estimate_order_margin`, `calculate_positions_margin`                      | Broker volume normalization and margin totals |
+| `normalize_order_volume`, `estimate_order_margin`, `calculate_positions_margin`                    | Broker volume normalization and margin totals |
 | `determine_order_limits`                                                                           | SL/TP price levels from ratios                |
 | `ensure_symbol_selected`                                                                           | Select/verify Market Watch visibility         |
 | `place_market_order`, `close_open_positions`, `update_sltp_for_open_positions`                     | Order execution helpers (`dry_run` supported) |
@@ -86,6 +86,28 @@ resolved = resolve_account_specs(accounts, server="Broker-Demo")
 # resolved[0].login == "12345", resolved[0].server == "Broker-Demo"
 ```

+Pass `allow_whole_dollar_env=True` to also expand strings whose **entire value**
+is a bare `$ENV_NAME` identifier (no braces). This opt-in covers
+`substitute_env_placeholders()`, `resolve_account_spec()`,
+`resolve_account_specs()`, and `build_config()`. Note: `build_config` cannot
+expand `login` because that parameter is `int | None`; use
+`resolve_account_spec` for a string `login` placeholder. Partial strings such as
+`"plan$pass"`, `"abc$ENV"`, or `"$ENV-suffix"` are never expanded — only an
+exact `$IDENTIFIER` whole-string match qualifies. The default is `False` to
+preserve backward compatibility.
+
+```python
+import os
+
+from mt5cli import AccountSpec, resolve_account_specs
+
+os.environ["MT5_PASSWORD"] = "secret"
+accounts = [AccountSpec(symbols=["EURUSD"], password="$MT5_PASSWORD")]
+
+resolved = resolve_account_specs(accounts, allow_whole_dollar_env=True)
+# resolved[0].password == "secret"
+```
+
 ### Throttled incremental history updates

 `ThrottledHistoryUpdater` wraps `update_history()` with a minimum interval
@@ -48,6 +48,7 @@ from mt5cli import (
    determine_order_limits,
    estimate_order_margin,
    fetch_latest_closed_rates_for_trading_client,
+    fetch_latest_closed_rates_indexed,
    get_account_snapshot,
    get_positions_frame,
    get_symbol_snapshot,
@@ -78,6 +79,14 @@ closed_bars = fetch_latest_closed_rates_for_trading_client(
    granularity="M1",
    count=100,
 )
+# Or fetch with a UTC DatetimeIndex instead of a "time" column:
+indexed_bars = fetch_latest_closed_rates_indexed(
+    client,
+    symbol="EURUSD",
+    granularity="M1",
+    count=100,
+)
+# indexed_bars.index is a UTC-aware DatetimeIndex named "time"
 sizing = calculate_margin_and_volume(
    client,
    "EURUSD",
@@ -174,16 +183,16 @@ through the stable package root without embedding entry/exit policy.

 ## Migration from application-local helpers

-| Application-local concern                                | mt5cli replacement                              |
-| -------------------------------------------------------- | ----------------------------------------------- |
-| Manual terminal spawn/kill around trading code           | `mt5_trading_session()`                         |
-| Local position-side detection                            | `detect_position_side()`                        |
-| Local margin/volume sizing                               | `calculate_margin_and_volume()`                 |
-| Local broker volume step normalization                   | `normalize_order_volume()`                      |
-| Local order or position margin estimation                | `estimate_order_margin()`, `calculate_positions_margin()` |
-| Local closed-bar fetch from a trading session            | `fetch_latest_closed_rates_for_trading_client()` |
-| Local SL/TP price derivation                             | `determine_order_limits()`                      |
-| Throttled SQLite history loop with ad-hoc error handling | `ThrottledHistoryUpdater(suppress_errors=True)` |
+| Application-local concern                                | mt5cli replacement                                                                      |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| Manual terminal spawn/kill around trading code           | `mt5_trading_session()`                                                                 |
+| Local position-side detection                            | `detect_position_side()`                                                                |
+| Local margin/volume sizing                               | `calculate_margin_and_volume()`                                                         |
+| Local broker volume step normalization                   | `normalize_order_volume()`                                                              |
+| Local order or position margin estimation                | `estimate_order_margin()`, `calculate_positions_margin()`                               |
+| Local closed-bar fetch from a trading session            | `fetch_latest_closed_rates_for_trading_client()`, `fetch_latest_closed_rates_indexed()` |
+| Local SL/TP price derivation                             | `determine_order_limits()`                                                              |
+| Throttled SQLite history loop with ad-hoc error handling | `ThrottledHistoryUpdater(suppress_errors=True)`                                         |

 Keep read-only data collection on `mt5_session()` / `Mt5CliClient`; use
 `mt5_trading_session()` only where order placement or trading calculations are
@@ -128,6 +128,7 @@ from .trading import (
    ensure_symbol_selected,
    estimate_order_margin,
    fetch_latest_closed_rates_for_trading_client,
+    fetch_latest_closed_rates_indexed,
    get_account_snapshot,
    get_positions_frame,
    get_symbol_snapshot,
@@ -214,6 +215,7 @@ __all__ = [
    "export_dataframe_to_sqlite",
    "fetch_latest_closed_rates",
    "fetch_latest_closed_rates_for_trading_client",
+    "fetch_latest_closed_rates_indexed",
    "get_account_snapshot",
    "get_positions_frame",
    "get_symbol_snapshot",
@@ -56,6 +56,7 @@ STABLE_SDK_EXPORTS: frozenset[str] = frozenset({
    "export_dataframe_to_sqlite",
    "fetch_latest_closed_rates",
    "fetch_latest_closed_rates_for_trading_client",
+    "fetch_latest_closed_rates_indexed",
    "get_account_snapshot",
    "get_positions_frame",
    "get_symbol_snapshot",
@@ -309,12 +309,33 @@ def build_config(
    password: str | None = None,
    server: str | None = None,
    timeout: int | None = None,
+    allow_whole_dollar_env: bool = False,
 ) -> Mt5Config:
    """Build an ``Mt5Config`` from optional connection parameters.

+    Args:
+        path: Optional terminal executable path.
+        login: Optional trading account login.
+        password: Optional trading account password.
+        server: Optional trading server name.
+        timeout: Optional connection timeout in milliseconds.
+        allow_whole_dollar_env: When ``True``, string parameters that are
+            exactly ``$ENV_NAME`` are expanded from the environment. Applies
+            to ``path``, ``password``, and ``server``. Default ``False``
+            preserves existing behavior.
+
    Returns:
        Configured ``Mt5Config`` instance.
    """
+    if allow_whole_dollar_env:
+        if path is not None:
+            path = substitute_env_placeholders(path, allow_whole_dollar_env=True)
+        if password is not None:
+            password = substitute_env_placeholders(
+                password, allow_whole_dollar_env=True
+            )
+        if server is not None:
+            server = substitute_env_placeholders(server, allow_whole_dollar_env=True)
    return Mt5Config(
        path=path,
        login=login,
@@ -1376,13 +1397,22 @@ class AccountSpec:


 _ENV_PLACEHOLDER_PATTERN = re.compile(r"\$\{(?P<name>[A-Za-z_][A-Za-z0-9_]*)\}")
+_WHOLE_DOLLAR_PATTERN = re.compile(r"^\$(?P<name>[A-Za-z_][A-Za-z0-9_]*)$")


-def substitute_env_placeholders(value: str) -> str:
+def substitute_env_placeholders(
+    value: str,
+    *,
+    allow_whole_dollar_env: bool = False,
+) -> str:
    """Replace ``${ENV_VAR}`` placeholders in a string with environment values.

    Args:
        value: String that may contain one or more ``${ENV_VAR}`` placeholders.
+        allow_whole_dollar_env: When ``True``, a string that is exactly
+            ``$ENV_NAME`` (the whole value and nothing else) is also expanded
+            from the environment. Partial occurrences such as ``"plan$pass"``
+            or ``"$ENV-suffix"`` are left unchanged.

    Returns:
        The string with every placeholder replaced by its environment value.
@@ -1390,6 +1420,14 @@ def substitute_env_placeholders(value: str) -> str:
    Raises:
        ValueError: If a referenced environment variable is not set.
    """
+    if allow_whole_dollar_env:
+        m = _WHOLE_DOLLAR_PATTERN.match(value)
+        if m:
+            name = m.group("name")
+            if name not in os.environ:
+                msg = f"Environment variable {name!r} is not set."
+                raise ValueError(msg)
+            return os.environ[name]
    parts: list[str] = []
    last_end = 0
    for match in _ENV_PLACEHOLDER_PATTERN.finditer(value):
@@ -1404,7 +1442,12 @@ def substitute_env_placeholders(value: str) -> str:
    return "".join(parts)


-def _resolve_field(override: str | None, account_value: str | None) -> str | None:
+def _resolve_field(
+    override: str | None,
+    account_value: str | None,
+    *,
+    allow_whole_dollar_env: bool = False,
+) -> str | None:
    """Resolve a string field from an override or account value with env subst.

    Returns:
@@ -1414,12 +1457,16 @@ def _resolve_field(override: str | None, account_value: str | None) -> str | Non
    value = override if override is not None else account_value
    if value is None:
        return None
-    return substitute_env_placeholders(value)
+    return substitute_env_placeholders(
+        value, allow_whole_dollar_env=allow_whole_dollar_env
+    )


 def _resolve_login(
    override: int | str | None,
    account_login: int | str | None,
+    *,
+    allow_whole_dollar_env: bool = False,
 ) -> int | str | None:
    """Resolve a login from an override or account value with env substitution.

@@ -1431,10 +1478,14 @@ def _resolve_login(
    if override is not None:
        if isinstance(override, int):
            return override
-        return substitute_env_placeholders(override)
+        return substitute_env_placeholders(
+            override, allow_whole_dollar_env=allow_whole_dollar_env
+        )
    if account_login is None or isinstance(account_login, int):
        return account_login
-    return substitute_env_placeholders(account_login)
+    return substitute_env_placeholders(
+        account_login, allow_whole_dollar_env=allow_whole_dollar_env
+    )


 def resolve_account_spec(
@@ -1445,6 +1496,7 @@ def resolve_account_spec(
    server: str | None = None,
    path: str | None = None,
    timeout: int | None = None,
+    allow_whole_dollar_env: bool = False,
 ) -> AccountSpec:
    """Resolve an account's credentials from overrides and ``${ENV_VAR}`` values.

@@ -1460,6 +1512,9 @@ def resolve_account_spec(
        server: Optional explicit server override.
        path: Optional explicit terminal path override.
        timeout: Optional explicit connection timeout override.
+        allow_whole_dollar_env: When ``True``, string fields that are exactly
+            ``$ENV_NAME`` are also expanded from the environment. Default
+            ``False`` preserves existing behavior.

    Returns:
        A new :class:`AccountSpec` with resolved credentials and the original
@@ -1469,10 +1524,18 @@ def resolve_account_spec(
    """
    return AccountSpec(
        symbols=account.symbols,
-        login=_resolve_login(login, account.login),
-        password=_resolve_field(password, account.password),
-        server=_resolve_field(server, account.server),
-        path=_resolve_field(path, account.path),
+        login=_resolve_login(
+            login, account.login, allow_whole_dollar_env=allow_whole_dollar_env
+        ),
+        password=_resolve_field(
+            password, account.password, allow_whole_dollar_env=allow_whole_dollar_env
+        ),
+        server=_resolve_field(
+            server, account.server, allow_whole_dollar_env=allow_whole_dollar_env
+        ),
+        path=_resolve_field(
+            path, account.path, allow_whole_dollar_env=allow_whole_dollar_env
+        ),
        timeout=timeout if timeout is not None else account.timeout,
    )

@@ -1485,6 +1548,7 @@ def resolve_account_specs(
    server: str | None = None,
    path: str | None = None,
    timeout: int | None = None,
+    allow_whole_dollar_env: bool = False,
 ) -> list[AccountSpec]:
    """Resolve credentials for multiple accounts.

@@ -1498,6 +1562,9 @@ def resolve_account_specs(
        server: Optional explicit server override applied to each account.
        path: Optional explicit terminal path override applied to each account.
        timeout: Optional explicit timeout override applied to each account.
+        allow_whole_dollar_env: When ``True``, string fields that are exactly
+            ``$ENV_NAME`` are also expanded from the environment. Default
+            ``False`` preserves existing behavior.

    Returns:
        Resolved account specifications in the original order. Raises
@@ -1512,6 +1579,7 @@ def resolve_account_specs(
            server=server,
            path=path,
            timeout=timeout,
+            allow_whole_dollar_env=allow_whole_dollar_env,
        )
        for account in accounts
    ]
@@ -4,7 +4,7 @@ from __future__ import annotations

 from contextlib import contextmanager
 from math import floor, isfinite
-from numbers import Integral
+from numbers import Integral, Real
 from typing import TYPE_CHECKING, Literal, TypedDict, cast

 import pandas as pd
@@ -137,6 +137,7 @@ __all__ = [
    "ensure_symbol_selected",
    "estimate_order_margin",
    "fetch_latest_closed_rates_for_trading_client",
+    "fetch_latest_closed_rates_indexed",
    "get_account_snapshot",
    "get_positions_frame",
    "get_symbol_snapshot",
@@ -829,7 +830,9 @@ def calculate_volume_by_margin(
    """Calculate max normalized volume affordable for one side.

    Returns:
-        Affordable volume rounded down to symbol volume constraints.
+        Largest stepped volume whose actual margin (from ``order_calc_margin``)
+        fits within ``available_margin``, rounded down to symbol volume
+        constraints; ``0.0`` when no affordable step exists.

    Raises:
        Mt5TradingError: If symbol volume constraints or tick data are invalid.
@@ -844,8 +847,7 @@ def calculate_volume_by_margin(
        msg = f"Invalid volume constraints for {symbol!r}."
        raise Mt5TradingError(msg)
    side = _normalize_order_side(order_side)
-    tick = get_tick_snapshot(client, symbol)
-    price = tick["ask"] if side == "BUY" else tick["bid"]
+    price = get_tick_snapshot(client, symbol)["ask" if side == "BUY" else "bid"]
    if not isinstance(price, int | float) or price <= 0:
        msg = f"Tick price is unavailable for {symbol!r}."
        raise Mt5TradingError(msg)
@@ -855,11 +857,38 @@ def calculate_volume_by_margin(
    min_margin = float(client.order_calc_margin(order_type, symbol, volume_min, price))
    if min_margin <= 0 or min_margin > available_margin:
        return 0.0
-    raw_volume = available_margin / min_margin * volume_min
-    capped = min(raw_volume, volume_max) if volume_max > 0 else raw_volume
-    steps = floor(((capped - volume_min) / volume_step) + 1e-12)
-    normalized = volume_min + max(0, steps) * volume_step
-    return round(normalized, 10) if normalized >= volume_min else 0.0
+    lo = 0
+    hi = int(
+        max(
+            0,
+            floor(
+                (
+                    (
+                        min(available_margin / min_margin * volume_min, volume_max)
+                        if volume_max > 0
+                        else available_margin / min_margin * volume_min
+                    )
+                    - volume_min
+                )
+                / volume_step
+                + 1e-12
+            ),
+        )
+    )
+    best = -1
+
+    while lo <= hi:
+        mid = (lo + hi) // 2
+        normalized = round(volume_min + mid * volume_step, 10)
+        actual = float(client.order_calc_margin(order_type, symbol, normalized, price))
+
+        if actual > 0 and actual <= available_margin:
+            best = mid
+            lo = mid + 1
+        else:
+            hi = mid - 1
+
+    return round(volume_min + best * volume_step, 10) if best >= 0 else 0.0


 def determine_order_limits(
@@ -1202,6 +1231,92 @@ def fetch_latest_closed_rates_for_trading_client(
    return closed.tail(count).reset_index(drop=True)


+def _rate_time_to_utc(series: pd.Series, symbol: str) -> pd.DatetimeIndex:
+    """Convert a rate time series to a UTC-aware DatetimeIndex.
+
+    Handles MT5 epoch seconds (including object-dtype Python numbers), timezone-
+    naive datetime-like values, and timezone-aware datetime-like values.
+
+    Returns:
+        UTC-aware DatetimeIndex.
+
+    Raises:
+        ValueError: If the time data is invalid, unparseable, or contains NaT.
+    """
+    try:
+        arr = series.to_numpy()
+        non_null = series.dropna()
+        object_numbers = (
+            pd.api.types.is_object_dtype(series)
+            and non_null.map(
+                lambda value: type(value) is not bool and isinstance(value, Real),
+            ).all()
+        )
+        numeric_dtype = pd.api.types.is_numeric_dtype(
+            series
+        ) and not pd.api.types.is_bool_dtype(
+            series,
+        )
+        if numeric_dtype or object_numbers:
+            idx = pd.to_datetime(arr, unit="s", utc=True)
+        else:
+            idx = pd.to_datetime(arr, utc=True)
+    except Exception as exc:
+        msg = f"Rate data for {symbol!r} has invalid or unparseable time data."
+        raise ValueError(msg) from exc
+    if any(idx.isna()):
+        msg = f"Rate data for {symbol!r} contains missing (NaT) timestamp values."
+        raise ValueError(msg)
+    return idx
+
+
+def fetch_latest_closed_rates_indexed(
+    client: Mt5TradingClient,
+    *,
+    symbol: str,
+    granularity: str,
+    count: int,
+) -> pd.DataFrame:
+    """Fetch the latest closed bars with a UTC DatetimeIndex from a trading client.
+
+    Internally reuses :func:`fetch_latest_closed_rates_for_trading_client` for
+    closed-bar detection and validation, then converts the ``time`` column to a
+    UTC-aware :class:`~pandas.DatetimeIndex` named ``"time"`` and drops the
+    original column. Intended for downstream time-series consumers that require
+    a datetime index rather than a ``time`` column.
+
+    Args:
+        client: Connected trading client with rate-fetch capability.
+        symbol: Symbol name.
+        granularity: Timeframe string (for example ``"M1"``, ``"H1"``).
+        count: Maximum number of closed bars to return.
+
+    Returns:
+        Up to ``count`` closed bars ordered oldest to newest, with a
+        UTC-aware ``DatetimeIndex`` named ``"time"``. The original ``time``
+        column is dropped.
+
+    Raises:
+        ValueError: If ``count`` is not positive, rate data is empty or
+            malformed, the ``time`` column is missing, or timestamp data
+            is invalid or unparseable.
+    """
+    frame = fetch_latest_closed_rates_for_trading_client(
+        client,
+        symbol=symbol,
+        granularity=granularity,
+        count=count,
+    )
+    if "time" not in frame.columns:
+        msg = f"Rate data is missing a time column for {symbol!r}."
+        raise ValueError(msg)
+    idx = _rate_time_to_utc(frame["time"], symbol)
+    idx.name = "time"
+    result = frame.drop(columns=["time"])
+    result.index = idx
+    return result
+
+
@contextmanager
 def mt5_trading_session(
    config: Mt5Config | None = None,
@@ -1,6 +1,6 @@
 [project]
 name = "mt5cli"
-version = "0.8.3"
+version = "0.9.1"
 description = "Generic MT5 data and execution infrastructure for Python applications"
 authors = [{name = "dceoy", email = "dceoy@users.noreply.github.com"}]
 maintainers = [{name = "dceoy", email = "dceoy@users.noreply.github.com"}]
@@ -124,7 +124,6 @@ ignore = [
 ]

 [tool.ruff.lint.per-file-ignores]
-"mt5cli/history.py" = ["TC003"]
 "tests/**/*.py" = [
  "DOC201",   # Missing return documentation
  "DOC501",   # Raised exception missing from docstring
@@ -44,6 +44,7 @@ from mt5cli import (
    export_dataframe_to_sqlite,
    fetch_latest_closed_rates,
    fetch_latest_closed_rates_for_trading_client,
+    fetch_latest_closed_rates_indexed,
    granularity_name,
    is_recoverable_mt5_error,
    load_rate_data,
@@ -734,3 +735,32 @@ class TestStableSdkContract:
            raise RuntimeError(message)

        mock_client.shutdown.assert_called_once()
+
+    def test_fetch_latest_closed_rates_indexed_from_package_root(
+        self,
+        mocker: MockerFixture,
+    ) -> None:
+        """Indexed closed-bar helper returns a UTC DatetimeIndex named 'time'."""
+        client = MagicMock()
+        mocker.patch(
+            "mt5cli.trading.fetch_latest_closed_rates_for_trading_client",
+            return_value=pd.DataFrame(
+                {
+                    "time": [1704067200, 1704153600, 1704240000],
+                    "close": [1.0, 1.1, 1.2],
+                },
+            ),
+        )
+
+        result = fetch_latest_closed_rates_indexed(
+            client,
+            symbol="EURUSD",
+            granularity="M1",
+            count=2,
+        )
+
+        assert isinstance(result.index, pd.DatetimeIndex)
+        assert result.index.name == "time"
+        assert result.index.tz is not None
+        assert "time" not in result.columns
+        assert "close" in result.columns
@@ -1777,6 +1777,80 @@ class TestSubstituteEnvPlaceholders:
        with pytest.raises(ValueError, match="'MT5_MISSING' is not set"):
            substitute_env_placeholders("${MT5_MISSING}")

+    def test_whole_dollar_not_substituted_by_default(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test $ENV_NAME is not expanded without allow_whole_dollar_env=True."""
+        monkeypatch.setenv("MT5_PASSWORD", "secret")
+
+        assert substitute_env_placeholders("$MT5_PASSWORD") == "$MT5_PASSWORD"
+
+    def test_whole_dollar_substituted_with_opt_in(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test $ENV_NAME is expanded when allow_whole_dollar_env=True."""
+        monkeypatch.setenv("MT5_PASSWORD", "secret")
+
+        result = substitute_env_placeholders(
+            "$MT5_PASSWORD", allow_whole_dollar_env=True
+        )
+
+        assert result == "secret"
+
+    def test_whole_dollar_missing_variable_raises_value_error(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test missing $ENV_NAME raises ValueError when opt-in is enabled."""
+        monkeypatch.delenv("MT5_MISSING", raising=False)
+
+        with pytest.raises(ValueError, match="'MT5_MISSING' is not set"):
+            substitute_env_placeholders("$MT5_MISSING", allow_whole_dollar_env=True)
+
+    def test_partial_dollar_not_expanded_with_opt_in(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test $ENV embedded in a larger string is not expanded."""
+        monkeypatch.setenv("pass", "secret")
+        monkeypatch.setenv("ENV", "val")
+
+        assert (
+            substitute_env_placeholders("plan$pass", allow_whole_dollar_env=True)
+            == "plan$pass"
+        )
+        assert (
+            substitute_env_placeholders("abc$ENV", allow_whole_dollar_env=True)
+            == "abc$ENV"
+        )
+
+    def test_dollar_with_suffix_not_expanded_with_opt_in(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test $ENV-suffix is not expanded (not a whole-value placeholder)."""
+        monkeypatch.setenv("ENV", "val")
+
+        assert (
+            substitute_env_placeholders("$ENV-suffix", allow_whole_dollar_env=True)
+            == "$ENV-suffix"
+        )
+
+    def test_brace_format_works_with_opt_in(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test ${ENV_VAR} substitution still works when allow_whole_dollar_env=True."""
+        monkeypatch.setenv("MT5_LOGIN", "12345")
+
+        result = substitute_env_placeholders(
+            "${MT5_LOGIN}", allow_whole_dollar_env=True
+        )
+
+        assert result == "12345"
+

 class TestResolveAccountSpec:
    """Tests for resolve_account_spec and resolve_account_specs."""
@@ -1863,6 +1937,117 @@ class TestResolveAccountSpec:
        assert [a.server for a in resolved] == ["Shared", "Fixed"]
        assert all(a.timeout == 1000 for a in resolved)

+    def test_resolve_account_spec_with_whole_dollar_env(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Account spec expands $ENV_NAME when allow_whole_dollar_env=True."""
+        monkeypatch.setenv("MT5_PASSWORD", "secret")
+        account = AccountSpec(symbols=["EURUSD"], password="$MT5_PASSWORD")
+
+        resolved = resolve_account_spec(account, allow_whole_dollar_env=True)
+
+        assert resolved.password == "secret"  # noqa: S105
+
+    def test_resolve_account_spec_whole_dollar_not_expanded_by_default(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test resolve_account_spec leaves $ENV_NAME literal by default."""
+        monkeypatch.setenv("MT5_PASSWORD", "secret")
+        account = AccountSpec(symbols=["EURUSD"], password="$MT5_PASSWORD")
+
+        resolved = resolve_account_spec(account)
+
+        assert resolved.password == "$MT5_PASSWORD"  # noqa: S105
+
+    def test_resolve_account_specs_with_whole_dollar_env(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test resolve_account_specs threads allow_whole_dollar_env to each account."""
+        monkeypatch.setenv("MT5_SERVER", "Broker-Demo")
+        accounts = [
+            AccountSpec(symbols=["EURUSD"], server="$MT5_SERVER"),
+            AccountSpec(symbols=["GBPUSD"], server="Fixed"),
+        ]
+
+        resolved = resolve_account_specs(accounts, allow_whole_dollar_env=True)
+
+        assert resolved[0].server == "Broker-Demo"
+        assert resolved[1].server == "Fixed"
+
+    def test_resolve_account_spec_whole_dollar_login(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test $ENV_NAME login string is expanded when allow_whole_dollar_env=True."""
+        monkeypatch.setenv("MT5_LOGIN", "12345")
+        account = AccountSpec(symbols=["EURUSD"], login="$MT5_LOGIN")
+
+        resolved = resolve_account_spec(account, allow_whole_dollar_env=True)
+
+        assert resolved.login == "12345"
+
+
+class TestBuildConfigWholeDollarEnv:
+    """Tests for build_config with allow_whole_dollar_env."""
+
+    def test_build_config_substitutes_server_with_opt_in(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """build_config expands $ENV_NAME server when allow_whole_dollar_env=True."""
+        monkeypatch.setenv("MT5_SERVER", "Broker-Demo")
+
+        config = build_config(server="$MT5_SERVER", allow_whole_dollar_env=True)
+
+        assert config.server == "Broker-Demo"
+
+    def test_build_config_substitutes_password_with_opt_in(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """build_config expands $ENV_NAME password when allow_whole_dollar_env=True."""
+        monkeypatch.setenv("MT5_PASSWORD", "secret")
+
+        config = build_config(password="$MT5_PASSWORD", allow_whole_dollar_env=True)
+
+        assert config.password == "secret"  # noqa: S105
+
+    def test_build_config_substitutes_path_with_opt_in(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test build_config expands $ENV_NAME path when allow_whole_dollar_env=True."""
+        monkeypatch.setenv("MT5_PATH", "/opt/mt5/terminal64.exe")
+
+        config = build_config(path="$MT5_PATH", allow_whole_dollar_env=True)
+
+        assert config.path == "/opt/mt5/terminal64.exe"
+
+    def test_build_config_leaves_dollar_literal_by_default(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test build_config does not substitute $ENV without opt-in."""
+        monkeypatch.setenv("MT5_SERVER", "Broker-Demo")
+
+        config = build_config(server="$MT5_SERVER")
+
+        assert config.server == "$MT5_SERVER"
+
+    def test_build_config_none_params_not_substituted(
+        self,
+        monkeypatch: pytest.MonkeyPatch,  # noqa: ARG002
+    ) -> None:
+        """Test build_config with None params does not raise even with opt-in."""
+        config = build_config(allow_whole_dollar_env=True)
+
+        assert config.server is None
+        assert config.password is None
+        assert config.path is None
+

 class TestThrottledHistoryUpdater:
    """Tests for the throttled incremental history updater."""
@@ -8,6 +8,7 @@ from unittest.mock import MagicMock

 import pandas as pd
 import pytest
+from numpy import float64 as np_float64
 from numpy import int64 as np_int64
 from pdmt5 import Mt5RuntimeError, Mt5TradingClient, Mt5TradingError
 from pytest_mock import MockerFixture  # noqa: TC002
@@ -29,6 +30,7 @@ from mt5cli.trading import (
    ensure_symbol_selected,
    estimate_order_margin,
    fetch_latest_closed_rates_for_trading_client,
+    fetch_latest_closed_rates_indexed,
    get_account_snapshot,
    get_positions_frame,
    get_symbol_snapshot,
@@ -1373,6 +1375,67 @@ class TestVolumeAndExecution:
        with pytest.raises(Mt5TradingError):
            calculate_volume_by_margin(client, "EURUSD", 100.0, "SELL")

+    def test_calculate_volume_by_margin_steps_down_when_margin_exceeds_budget(
+        self,
+    ) -> None:
+        """Tiered margin: binary search returns the largest affordable step."""
+        client = _mock_trade_client()
+        client.symbol_info_as_dict.return_value = {
+            "volume_min": 0.1,
+            "volume_max": 1.0,
+            "volume_step": 0.1,
+        }
+        client.symbol_info_tick_as_dict.return_value = {"ask": 100.0, "bid": 99.0}
+        # min_margin (0.1): 25.0 -> hi=4.
+        # Search: mid=2 (0.3)->75<=130, mid=3 (0.4)->100<=130, mid=4 (0.5)->150>130.
+        client.order_calc_margin.side_effect = [25.0, 75.0, 100.0, 150.0]
+
+        result = calculate_volume_by_margin(client, "EURUSD", 130.0, "BUY")
+
+        _assert_close(result, 0.4)
+
+    def test_calculate_volume_by_margin_returns_zero_when_all_steps_unaffordable(
+        self,
+    ) -> None:
+        """If all binary-search probes exceed budget, returns zero."""
+        client = _mock_trade_client()
+        client.symbol_info_as_dict.return_value = {
+            "volume_min": 0.1,
+            "volume_max": 0.5,
+            "volume_step": 0.1,
+        }
+        client.symbol_info_tick_as_dict.return_value = {"ask": 100.0, "bid": 99.0}
+        # min_margin (0.1): 10.0 -> hi=4.
+        # Search: mid=2 (0.3)->150>130->hi=1, mid=0 (0.1)->150>130->hi=-1.
+        client.order_calc_margin.side_effect = [10.0, 150.0, 150.0]
+
+        result = calculate_volume_by_margin(client, "EURUSD", 130.0, "BUY")
+
+        _assert_close(result, 0.0)
+
+    def test_calculate_volume_by_margin_binary_search_is_bounded(self) -> None:
+        """Binary search finds the largest affordable volume in O(log n) MT5 calls."""
+        client = _mock_trade_client()
+        client.symbol_info_as_dict.return_value = {
+            "volume_min": 0.01,
+            "volume_max": 1000.0,
+            "volume_step": 0.01,
+        }
+        client.symbol_info_tick_as_dict.return_value = {"ask": 100.0, "bid": 99.0}
+        # Steps 0-50000 cost 0.001 (affordable); steps 50001+ cost 2000.0 (not).
+        # Total range: 99999 steps. Linear scan: ~50000 calls; binary search: ~17.
+        affordable_step = 50000
+
+        def _margin(_ot: int, _sym: str, volume: float, _px: float) -> float:
+            step = round((volume - 0.01) / 0.01)
+            return 0.001 if step <= affordable_step else 2000.0
+
+        client.order_calc_margin.side_effect = _margin
+        result = calculate_volume_by_margin(client, "EURUSD", 200.0, "BUY")
+
+        _assert_close(result, 500.01)  # 0.01 + 50000 * 0.01
+        assert client.order_calc_margin.call_count <= 25
+
    def test_calculate_margin_and_volume_without_native_helper(self) -> None:
        """Test margin helper uses module volume calculation when needed."""

@@ -1399,7 +1462,7 @@ class TestVolumeAndExecution:
            ) -> float:
                assert order_type in {10, 11}
                assert symbol == "EURUSD"
-                _assert_close(volume, 0.1)
+                assert 0.1 <= volume <= 1.0
                _assert_close(price, 100.0)
                return 10.0

@@ -2627,3 +2690,269 @@ class TestFetchLatestClosedRatesForTradingClient:
            )

        client.fetch_latest_rates_as_df.assert_not_called()
+
+    def test_returns_range_index_and_time_column_for_backward_compat(self) -> None:
+        """Test original helper returns RangeIndex with a time column."""
+        client = MagicMock()
+        client.fetch_latest_rates_as_df.return_value = pd.DataFrame(
+            {"time": [1700000000, 1700003600, 1700007200], "close": [1.1, 1.2, 1.3]},
+        )
+
+        result = fetch_latest_closed_rates_for_trading_client(
+            client,
+            symbol="EURUSD",
+            granularity="M1",
+            count=2,
+        )
+
+        assert isinstance(result.index, pd.RangeIndex)
+        assert "time" in result.columns
+        assert len(result) == 2
+
+
+class TestFetchLatestClosedRatesIndexed:
+    """Tests for fetch_latest_closed_rates_indexed."""
+
+    def test_converts_epoch_seconds_to_utc_datetime_index(
+        self, mocker: MockerFixture
+    ) -> None:
+        """Test integer epoch second timestamps become a UTC DatetimeIndex."""
+        frame = pd.DataFrame(
+            {"time": [1700000000, 1700003600], "close": [1.1, 1.2]},
+        )
+        mocker.patch(
+            "mt5cli.trading.fetch_latest_closed_rates_for_trading_client",
+            return_value=frame,
+        )
+
+        result = fetch_latest_closed_rates_indexed(
+            MagicMock(),
+            symbol="EURUSD",
+            granularity="M1",
+            count=2,
+        )
+
+        assert isinstance(result.index, pd.DatetimeIndex)
+        assert result.index.name == "time"
+        assert result.index.tz is not None
+        assert str(result.index.tz) == "UTC"
+        assert "time" not in result.columns
+        assert list(result["close"]) == [1.1, 1.2]
+
+    def test_converts_float_epoch_seconds_to_utc_datetime_index(
+        self, mocker: MockerFixture
+    ) -> None:
+        """Test float64 epoch second timestamps (after concat/NA upcast) become UTC."""
+        frame = pd.DataFrame(
+            {"time": [1700000000.0, 1700003600.0], "close": [1.1, 1.2]},
+        )
+        mocker.patch(
+            "mt5cli.trading.fetch_latest_closed_rates_for_trading_client",
+            return_value=frame,
+        )
+
+        result = fetch_latest_closed_rates_indexed(
+            MagicMock(),
+            symbol="EURUSD",
+            granularity="M1",
+            count=2,
+        )
+
+        assert isinstance(result.index, pd.DatetimeIndex)
+        assert result.index.tz is not None
+        assert str(result.index.tz) == "UTC"
+        assert result.index[0].year == 2023
+
+    @pytest.mark.parametrize(
+        "timestamps",
+        [
+            [1700000000, 1700003600],
+            [1700000000.0, 1700003600.0],
+            [np_int64(1700000000), np_int64(1700003600)],
+            [np_float64(1700000000.0), np_float64(1700003600.0)],
+        ],
+        ids=["integers", "floats", "numpy-integers", "numpy-floats"],
+    )
+    def test_converts_object_numeric_epoch_seconds_to_utc_datetime_index(
+        self,
+        mocker: MockerFixture,
+        timestamps: list[int] | list[float] | list[np_int64] | list[np_float64],
+    ) -> None:
+        """Test object-dtype real numbers are interpreted as epoch seconds."""
+        frame = pd.DataFrame(
+            {
+                "time": pd.Series(timestamps, dtype=object),
+                "close": [1.1, 1.2],
+            },
+        )
+        mocker.patch(
+            "mt5cli.trading.fetch_latest_closed_rates_for_trading_client",
+            return_value=frame,
+        )
+
+        result = fetch_latest_closed_rates_indexed(
+            MagicMock(), symbol="EURUSD", granularity="M1", count=2
+        )
+
+        assert list(result.index) == list(
+            pd.to_datetime([1700000000, 1700003600], unit="s", utc=True)
+        )
+
+    def test_parses_mixed_datetime_like_strings(self, mocker: MockerFixture) -> None:
+        """Test object-dtype datetime strings retain datetime-like parsing."""
+        timestamps = ["2024-01-01T00:00:00Z", "2024-01-01T01:00:00+01:00"]
+        frame = pd.DataFrame({"time": timestamps, "close": [1.1, 1.2]})
+        mocker.patch(
+            "mt5cli.trading.fetch_latest_closed_rates_for_trading_client",
+            return_value=frame,
+        )
+
+        result = fetch_latest_closed_rates_indexed(
+            MagicMock(), symbol="EURUSD", granularity="M1", count=2
+        )
+
+        assert list(result.index) == list(pd.to_datetime(timestamps, utc=True))
+
+    def test_does_not_treat_bool_as_epoch_seconds(self, mocker: MockerFixture) -> None:
+        """Test bool timestamps do not enter the numeric epoch-seconds path."""
+        frame = pd.DataFrame(
+            {"time": pd.Series([True, False], dtype=object), "close": [1.1, 1.2]},
+        )
+        mocker.patch(
+            "mt5cli.trading.fetch_latest_closed_rates_for_trading_client",
+            return_value=frame,
+        )
+
+        with pytest.raises(ValueError, match="invalid or unparseable time data"):
+            fetch_latest_closed_rates_indexed(
+                MagicMock(), symbol="EURUSD", granularity="M1", count=2
+            )
+
+    def test_converts_naive_datetime_to_utc_datetime_index(
+        self, mocker: MockerFixture
+    ) -> None:
+        """Test timezone-naive datetime values are localized to UTC."""
+        from datetime import datetime  # noqa: PLC0415
+
+        frame = pd.DataFrame(
+            {
+                "time": [datetime(2024, 1, 1, 0, 0), datetime(2024, 1, 1, 1, 0)],  # noqa: DTZ001
+                "close": [1.1, 1.2],
+            },
+        )
+        mocker.patch(
+            "mt5cli.trading.fetch_latest_closed_rates_for_trading_client",
+            return_value=frame,
+        )
+
+        result = fetch_latest_closed_rates_indexed(
+            MagicMock(),
+            symbol="EURUSD",
+            granularity="M1",
+            count=2,
+        )
+
+        assert isinstance(result.index, pd.DatetimeIndex)
+        assert result.index.tz is not None
+        assert str(result.index.tz) == "UTC"
+        assert result.index[0].year == 2024
+
+    def test_converts_aware_datetime_to_utc(self, mocker: MockerFixture) -> None:
+        """Test timezone-aware datetime values are converted to UTC."""
+        from datetime import datetime, timedelta, timezone  # noqa: PLC0415
+
+        tz_plus5 = timezone(timedelta(hours=5))
+        frame = pd.DataFrame(
+            {
+                "time": [datetime(2024, 1, 1, 5, 0, tzinfo=tz_plus5)],
+                "close": [1.1],
+            },
+        )
+        mocker.patch(
+            "mt5cli.trading.fetch_latest_closed_rates_for_trading_client",
+            return_value=frame,
+        )
+
+        result = fetch_latest_closed_rates_indexed(
+            MagicMock(),
+            symbol="EURUSD",
+            granularity="M1",
+            count=1,
+        )
+
+        assert isinstance(result.index, pd.DatetimeIndex)
+        assert str(result.index.tz) == "UTC"
+        assert result.index[0].hour == 0
+
+    def test_raises_on_missing_time_column(self, mocker: MockerFixture) -> None:
+        """Test missing time column after the underlying fetch raises ValueError."""
+        mocker.patch(
+            "mt5cli.trading.fetch_latest_closed_rates_for_trading_client",
+            return_value=pd.DataFrame({"close": [1.1]}),
+        )
+
+        with pytest.raises(ValueError, match="missing a time column"):
+            fetch_latest_closed_rates_indexed(
+                MagicMock(),
+                symbol="EURUSD",
+                granularity="M1",
+                count=1,
+            )
+
+    def test_raises_on_unparseable_time_column(self, mocker: MockerFixture) -> None:
+        """Test unparseable time data raises a clear ValueError."""
+        mocker.patch(
+            "mt5cli.trading.fetch_latest_closed_rates_for_trading_client",
+            return_value=pd.DataFrame({"time": ["not-a-date"], "close": [1.1]}),
+        )
+
+        with pytest.raises(ValueError, match="invalid or unparseable time data"):
+            fetch_latest_closed_rates_indexed(
+                MagicMock(),
+                symbol="EURUSD",
+                granularity="M1",
+                count=1,
+            )
+
+    def test_raises_on_nat_time_column(self, mocker: MockerFixture) -> None:
+        """Test NaT in the time column raises ValueError instead of silently passing."""
+        mocker.patch(
+            "mt5cli.trading.fetch_latest_closed_rates_for_trading_client",
+            return_value=pd.DataFrame(
+                {"time": [1700000000, None], "close": [1.1, 1.2]},
+            ),
+        )
+
+        with pytest.raises(ValueError, match=r"missing.*NaT.*timestamp"):
+            fetch_latest_closed_rates_indexed(
+                MagicMock(),
+                symbol="EURUSD",
+                granularity="M1",
+                count=2,
+            )
+
+    def test_drops_time_column_and_sets_index(self, mocker: MockerFixture) -> None:
+        """Test the returned DataFrame has the DatetimeIndex and no time column."""
+        frame = pd.DataFrame(
+            {
+                "time": [1700000000, 1700003600],
+                "open": [1.0, 1.1],
+                "close": [1.1, 1.2],
+            },
+        )
+        mocker.patch(
+            "mt5cli.trading.fetch_latest_closed_rates_for_trading_client",
+            return_value=frame,
+        )
+
+        result = fetch_latest_closed_rates_indexed(
+            MagicMock(),
+            symbol="EURUSD",
+            granularity="M1",
+            count=2,
+        )
+
+        assert "time" not in result.columns
+        assert "open" in result.columns
+        assert "close" in result.columns
+        assert isinstance(result.index, pd.DatetimeIndex)
@@ -487,7 +487,7 @@ wheels = [

 [[package]]
 name = "mt5cli"
-version = "0.8.3"
+version = "0.9.1"
 source = { editable = "." }
 dependencies = [
    { name = "click" },