defistream-mcp 0.2.0__py3-none-any.whl

defistream_mcp/tools.py

@@ -0,0 +1,727 @@
+"""MCP tool definitions for the DeFiStream API."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+from urllib.parse import parse_qs, urlencode
+
+from .api_client import create_client_with_key, get_client
+from .formatters import (
+    format_aggregate_response,
+    format_events_response,
+    format_link_response,
+    format_local_execution_guide,
+)
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _build_range_params(
+    block_start: int | None,
+    block_end: int | None,
+    since: str | None,
+    until: str | None,
+) -> dict[str, Any]:
+    """Build the block/time range query params, validating mutual exclusivity."""
+    params: dict[str, Any] = {}
+    has_blocks = block_start is not None or block_end is not None
+    has_time = since is not None or until is not None
+
+    if has_blocks and has_time:
+        raise ValueError("Specify either block_start/block_end or since/until, not both.")
+
+    if has_blocks:
+        if block_start is not None:
+            params["block_start"] = block_start
+        if block_end is not None:
+            params["block_end"] = block_end
+    elif has_time:
+        if since is not None:
+            params["since"] = since
+        if until is not None:
+            params["until"] = until
+
+    return params
+
+
+def _build_query(
+    protocol: str,
+    event_type: str,
+    network: str,
+    extra: dict[str, Any],
+    *,
+    aggregate: bool = False,
+    group_by: str = "time",
+    period: str = "1h",
+    verbose: bool = False,
+    with_value: bool = False,
+) -> str:
+    """Build a query path (without base URL) from protocol, event type, and params."""
+    path = f"/{protocol}/events/{event_type}"
+    if aggregate:
+        path += "/aggregate"
+
+    query_params: dict[str, Any] = {"network": network}
+
+    if aggregate:
+        query_params["group_by"] = group_by
+        query_params["period"] = period
+
+    if verbose:
+        query_params["verbose"] = "true"
+
+    if with_value:
+        query_params["with_value"] = "true"
+
+    query_params.update({k: v for k, v in extra.items() if v is not None})
+
+    qs = urlencode(query_params)
+    return f"{path}?{qs}" if qs else path
+
+
+def _parse_query(query: str) -> tuple[str, dict[str, Any]]:
+    """Parse a query path like /erc20/events/transfer?network=eth&token=USDT."""
+    if "?" in query:
+        path, qs = query.split("?", 1)
+        parsed = parse_qs(qs, keep_blank_values=True)
+        params: dict[str, Any] = {
+            k: v[0] if len(v) == 1 else v for k, v in parsed.items()
+        }
+    else:
+        path = query
+        params = {}
+    return path, params
+
+
+# ---------------------------------------------------------------------------
+# Tool registration
+# ---------------------------------------------------------------------------
+
+
+def register_tools(mcp, config):  # noqa: ANN001
+    """Register all DeFiStream tools on the FastMCP instance."""
+
+    # -----------------------------------------------------------------------
+    # Utility tools
+    # -----------------------------------------------------------------------
+
+    @mcp.tool()
+    async def supported_networks(protocol: str) -> str:
+        """Get the list of supported blockchain networks for a protocol.
+
+        Use this to validate that a user's requested network is supported
+        before building a query. Reject requests for unsupported networks.
+
+        Args:
+            protocol: Protocol name (erc20, native_token, aave_v3, uniswap_v3, lido, stader, threshold).
+        """
+        try:
+            client = get_client()
+            data, _ = await client.get_json(f"/{protocol}/networks")
+            return f"Supported networks for {protocol}:\n" + ", ".join(data)
+        except Exception as exc:
+            return f"Error fetching networks for '{protocol}': {exc}"
+
+    @mcp.tool()
+    async def supported_events(protocol: str) -> str:
+        """Get the list of supported event types for a protocol.
+
+        Use this to validate that a user's requested event type is supported
+        before building a query.
+
+        Args:
+            protocol: Protocol name (erc20, native_token, aave_v3, uniswap_v3, lido, stader, threshold).
+        """
+        try:
+            client = get_client()
+            data, _ = await client.get_json(f"/{protocol}/events/types")
+            return f"Supported event types for {protocol}:\n" + ", ".join(data)
+        except Exception as exc:
+            return f"Error fetching event types for '{protocol}': {exc}"
+
+    @mcp.tool()
+    async def base_url() -> str:
+        """Get the DeFiStream API base URL.
+
+        Combine with a query path from any query builder to form the full
+        API URL. Example: base_url + query_path → full URL.
+        """
+        return config.base_url
+
+    @mcp.tool()
+    async def execute_query(
+        query: str,
+        api_key: str,
+        file_format: str = "csv",
+        limit: int = 200,
+    ) -> str:
+        """Execute a query and return results (for small to medium block ranges).
+
+        Requires your DeFiStream API key. Best for queries returning manageable
+        result sets. For very large ranges, use download_query_as_link instead.
+
+        Args:
+            query: Query path from a query builder (e.g. /erc20/events/transfer?network=eth&token=USDT&...).
+            api_key: Your DeFiStream API key (dsk_xxx).
+            file_format: Output format — "json" or "csv" (default "csv").
+            limit: Max rows to return for JSON format (default 200, max 10000).
+        """
+        try:
+            if not api_key:
+                return "Error: api_key is required. Get your key at https://defistream.dev"
+
+            if file_format not in ("json", "csv"):
+                return "Error: file_format must be 'json' or 'csv'."
+
+            path, params = _parse_query(query)
+            params["format"] = file_format
+
+            # Create a client with the user's API key
+            client = create_client_with_key(api_key)
+
+            try:
+                if file_format == "csv":
+                    # For CSV, we get raw text response
+                    resp = await client._http.get(path, params=params)
+                    resp.raise_for_status()
+                    headers = {
+                        k: v
+                        for k, v in resp.headers.items()
+                        if k.lower().startswith("x-ratelimit") or k.lower() == "x-request-cost"
+                    }
+                    csv_text = resp.text
+
+                    # Count lines and potentially truncate
+                    lines = csv_text.strip().split("\n")
+                    effective_limit = min(limit, config.query_row_limit)
+
+                    if len(lines) > effective_limit + 1:  # +1 for header
+                        truncated = lines[: effective_limit + 1]
+                        result = f"Showing {effective_limit} of {len(lines) - 1} rows (truncated).\n\n"
+                        result += "\n".join(truncated)
+                    else:
+                        result = f"{len(lines) - 1} row(s) returned.\n\n"
+                        result += csv_text
+
+                    # Add quota info
+                    remaining = headers.get("x-ratelimit-remaining")
+                    cost = headers.get("x-request-cost")
+                    if remaining or cost:
+                        parts = []
+                        if cost:
+                            parts.append(f"cost={cost} CU")
+                        if remaining:
+                            parts.append(f"remaining={remaining} CU")
+                        result += "\n[Quota: " + ", ".join(parts) + "]"
+
+                    return result
+                else:
+                    # JSON format
+                    body, headers = await client.get_json(path, params)
+
+                    if isinstance(body, dict) and body.get("status") == "error":
+                        return f"API error: {body.get('error', json.dumps(body))}"
+
+                    effective_limit = min(limit, config.query_row_limit)
+
+                    # Aggregate responses have "data" key, event responses have "events"
+                    if "data" in body and "events" not in body:
+                        return format_aggregate_response(body, headers)
+
+                    return format_events_response(body, headers, effective_limit)
+            finally:
+                await client.close()
+        except Exception as exc:
+            return f"Error executing query: {exc}"
+
+    @mcp.tool()
+    async def download_query_as_link(
+        query: str,
+        api_key: str,
+        file_format: str = "csv",
+    ) -> str:
+        """Get a shareable download link for query results.
+
+        Requires your DeFiStream API key. Supports unlimited block ranges.
+        Returns a link that expires in 1 hour - no API key needed to download.
+
+        Args:
+            query: Query path from a query builder.
+            api_key: Your DeFiStream API key (dsk_xxx).
+            file_format: Output format — "csv" or "parquet" (default "csv").
+        """
+        try:
+            if not api_key:
+                return "Error: api_key is required. Get your key at https://defistream.dev"
+
+            if file_format not in ("csv", "parquet"):
+                return "Error: file_format must be 'csv' or 'parquet'."
+
+            path, params = _parse_query(query)
+            params["format"] = file_format
+            params["link"] = "true"
+
+            # Create a client with the user's API key
+            client = create_client_with_key(api_key)
+
+            try:
+                body, headers = await client.get_json(path, params)
+
+                if isinstance(body, dict) and body.get("status") == "error":
+                    return f"API error: {body.get('error', json.dumps(body))}"
+
+                return format_link_response(body, headers)
+            finally:
+                await client.close()
+        except Exception as exc:
+            return f"Error getting download link: {exc}"
+
+    @mcp.tool()
+    def query_local_execution_guide(query: str) -> str:
+        """Get instructions for executing a query locally on your system.
+
+        Use this when you want to run the query from your own environment
+        instead of through the MCP server. Returns examples using curl,
+        Python (requests/aiohttp), JavaScript (fetch), and the Python client library.
+
+        Args:
+            query: Query path from a query builder.
+        """
+        return format_local_execution_guide(query, config.base_url)
+
+    # -----------------------------------------------------------------------
+    # Protocol query builders
+    # -----------------------------------------------------------------------
+
+    @mcp.tool()
+    def erc20_query_builder(
+        event_type: str,
+        network: str,
+        token: str,
+        block_start: int | None = None,
+        block_end: int | None = None,
+        since: str | None = None,
+        until: str | None = None,
+        verbose: bool = False,
+        with_value: bool = False,
+        aggregate: bool = False,
+        group_by: str = "time",
+        period: str = "1h",
+        decimals: int | None = None,
+        sender: str | None = None,
+        receiver: str | None = None,
+        involving: str | None = None,
+        involving_label: str | None = None,
+        involving_category: str | None = None,
+        sender_label: str | None = None,
+        sender_category: str | None = None,
+        receiver_label: str | None = None,
+        receiver_category: str | None = None,
+        min_amount: float | None = None,
+        max_amount: float | None = None,
+    ) -> str:
+        """Build a query for ERC-20 token events (USDT, USDC, WETH, …).
+
+        Returns a query path string. Pass it to execute_query() for JSON
+        results or download_query() for CSV/Parquet files.
+
+        Event types: transfer
+
+        Args:
+            event_type: Event type (e.g. "transfer").
+            network: Network identifier (e.g. "ETH", "ARB", "BASE").
+            token: Token symbol or comma-separated symbols for multi-token queries (e.g. "USDT", "USDT,USDC,DAI"). Multi-token only supports known symbol names, not contract addresses. A single contract address (0x…) is also accepted.
+            block_start: Starting block number.
+            block_end: Ending block number.
+            since: Start time (ISO 8601 or Unix timestamp).
+            until: End time (ISO 8601 or Unix timestamp).
+            verbose: Include all metadata fields (tx_hash, log_index, etc.).
+            with_value: Enrich events with USD value data (adds value_usd column; agg_value_usd on aggregates).
+            aggregate: Set True to build an aggregate query instead of raw events.
+            group_by: Bucket grouping — "time" or "block_number" (aggregate only).
+            period: Bucket size e.g. "1h", "1d", "30m" for time; "1000" for blocks (aggregate only).
+            decimals: Token decimals when using a custom token address instead of symbol.
+            sender: Filter by sender address (comma-separated for multiple).
+            receiver: Filter by receiver address (comma-separated for multiple).
+            involving: Filter by any involved address.
+            involving_label: Filter by entity label substring (e.g. "Binance").
+            involving_category: Filter by address category (e.g. "exchange").
+            sender_label: Filter sender by label.
+            sender_category: Filter sender by category.
+            receiver_label: Filter receiver by label.
+            receiver_category: Filter receiver by category.
+            min_amount: Minimum transfer amount.
+            max_amount: Maximum transfer amount.
+        """
+        extra: dict[str, Any] = {
+            "token": token,
+            "decimals": decimals,
+            "sender": sender,
+            "receiver": receiver,
+            "involving": involving,
+            "involving_label": involving_label,
+            "involving_category": involving_category,
+            "sender_label": sender_label,
+            "sender_category": sender_category,
+            "receiver_label": receiver_label,
+            "receiver_category": receiver_category,
+            "min_amount": min_amount,
+            "max_amount": max_amount,
+        }
+        extra.update(_build_range_params(block_start, block_end, since, until))
+        return _build_query(
+            "erc20", event_type, network, extra,
+            aggregate=aggregate, group_by=group_by, period=period, verbose=verbose,
+            with_value=with_value,
+        )
+
+    @mcp.tool()
+    def native_token_query_builder(
+        event_type: str,
+        network: str,
+        block_start: int | None = None,
+        block_end: int | None = None,
+        since: str | None = None,
+        until: str | None = None,
+        verbose: bool = False,
+        with_value: bool = False,
+        aggregate: bool = False,
+        group_by: str = "time",
+        period: str = "1h",
+        sender: str | None = None,
+        receiver: str | None = None,
+        involving: str | None = None,
+        involving_label: str | None = None,
+        involving_category: str | None = None,
+        sender_label: str | None = None,
+        sender_category: str | None = None,
+        receiver_label: str | None = None,
+        receiver_category: str | None = None,
+        min_amount: float | None = None,
+        max_amount: float | None = None,
+    ) -> str:
+        """Build a query for native blockchain token transfers (ETH, MATIC, BNB, …).
+
+        Returns a query path string. Pass it to execute_query() for JSON
+        results or download_query() for CSV/Parquet files.
+
+        Event types: transfer
+
+        Args:
+            event_type: Event type (e.g. "transfer").
+            network: Network identifier (e.g. "ETH", "ARB", "BASE").
+            block_start: Starting block number.
+            block_end: Ending block number.
+            since: Start time (ISO 8601 or Unix timestamp).
+            until: End time (ISO 8601 or Unix timestamp).
+            verbose: Include all metadata fields (tx_hash, log_index, etc.).
+            with_value: Enrich events with USD value data (adds value_usd column; agg_value_usd on aggregates).
+            aggregate: Set True to build an aggregate query instead of raw events.
+            group_by: Bucket grouping — "time" or "block_number" (aggregate only).
+            period: Bucket size e.g. "1h", "1d", "30m" for time; "1000" for blocks (aggregate only).
+            sender: Filter by sender address (comma-separated for multiple).
+            receiver: Filter by receiver address (comma-separated for multiple).
+            involving: Filter by any involved address.
+            involving_label: Filter by entity label substring (e.g. "Binance").
+            involving_category: Filter by address category (e.g. "exchange").
+            sender_label: Filter sender by label.
+            sender_category: Filter sender by category.
+            receiver_label: Filter receiver by label.
+            receiver_category: Filter receiver by category.
+            min_amount: Minimum transfer amount.
+            max_amount: Maximum transfer amount.
+        """
+        extra: dict[str, Any] = {
+            "sender": sender,
+            "receiver": receiver,
+            "involving": involving,
+            "involving_label": involving_label,
+            "involving_category": involving_category,
+            "sender_label": sender_label,
+            "sender_category": sender_category,
+            "receiver_label": receiver_label,
+            "receiver_category": receiver_category,
+            "min_amount": min_amount,
+            "max_amount": max_amount,
+        }
+        extra.update(_build_range_params(block_start, block_end, since, until))
+        return _build_query(
+            "native_token", event_type, network, extra,
+            aggregate=aggregate, group_by=group_by, period=period, verbose=verbose,
+            with_value=with_value,
+        )
+
+    @mcp.tool()
+    def aave_v3_query_builder(
+        event_type: str,
+        network: str,
+        block_start: int | None = None,
+        block_end: int | None = None,
+        since: str | None = None,
+        until: str | None = None,
+        verbose: bool = False,
+        with_value: bool = False,
+        aggregate: bool = False,
+        group_by: str = "time",
+        period: str = "1h",
+        eth_market_type: str | None = None,
+        involving: str | None = None,
+        involving_label: str | None = None,
+        involving_category: str | None = None,
+    ) -> str:
+        """Build a query for AAVE V3 lending protocol events.
+
+        Returns a query path string. Pass it to execute_query() for JSON
+        results or download_query() for CSV/Parquet files.
+
+        Event types: deposit, withdraw, borrow, repay, flashloan, liquidation
+
+        Args:
+            event_type: Event type (e.g. "deposit", "withdraw", "borrow", "repay", "flashloan", "liquidation").
+            network: Network identifier (e.g. "ETH", "ARB", "BASE").
+            block_start: Starting block number.
+            block_end: Ending block number.
+            since: Start time (ISO 8601 or Unix timestamp).
+            until: End time (ISO 8601 or Unix timestamp).
+            verbose: Include all metadata fields (tx_hash, log_index, etc.).
+            with_value: Enrich events with USD value data (adds value_usd column; agg_value_usd on aggregates).
+            aggregate: Set True to build an aggregate query instead of raw events.
+            group_by: Bucket grouping — "time" or "block_number" (aggregate only).
+            period: Bucket size e.g. "1h", "1d", "30m" for time; "1000" for blocks (aggregate only).
+            eth_market_type: AAVE market type on ETH — "Core", "Prime", or "EtherFi".
+            involving: Filter by any involved address.
+            involving_label: Filter by entity label substring (e.g. "Binance").
+            involving_category: Filter by address category (e.g. "exchange").
+        """
+        extra: dict[str, Any] = {
+            "eth_market_type": eth_market_type,
+            "involving": involving,
+            "involving_label": involving_label,
+            "involving_category": involving_category,
+        }
+        extra.update(_build_range_params(block_start, block_end, since, until))
+        return _build_query(
+            "aave_v3", event_type, network, extra,
+            aggregate=aggregate, group_by=group_by, period=period, verbose=verbose,
+            with_value=with_value,
+        )
+
+    @mcp.tool()
+    def uniswap_v3_query_builder(
+        event_type: str,
+        network: str,
+        symbol0: str,
+        symbol1: str,
+        fee: int,
+        block_start: int | None = None,
+        block_end: int | None = None,
+        since: str | None = None,
+        until: str | None = None,
+        verbose: bool = False,
+        with_value: bool = False,
+        aggregate: bool = False,
+        group_by: str = "time",
+        period: str = "1h",
+        involving: str | None = None,
+        involving_label: str | None = None,
+        involving_category: str | None = None,
+    ) -> str:
+        """Build a query for Uniswap V3 DEX events.
+
+        Returns a query path string. Pass it to execute_query() for JSON
+        results or download_query() for CSV/Parquet files.
+
+        Event types: swap, deposit, withdraw, collect
+
+        Args:
+            event_type: Event type (e.g. "swap", "deposit", "withdraw", "collect").
+            network: Network identifier (e.g. "ETH", "ARB", "BASE").
+            symbol0: First token symbol in the pool (e.g. "WETH") — required.
+            symbol1: Second token symbol in the pool (e.g. "USDC") — required.
+            fee: Pool fee tier (100, 500, 3000, 10000) — required.
+            block_start: Starting block number.
+            block_end: Ending block number.
+            since: Start time (ISO 8601 or Unix timestamp).
+            until: End time (ISO 8601 or Unix timestamp).
+            verbose: Include all metadata fields (tx_hash, log_index, etc.).
+            with_value: Enrich events with USD value data (adds value_usd column; agg_value_usd on aggregates).
+            aggregate: Set True to build an aggregate query instead of raw events.
+            group_by: Bucket grouping — "time" or "block_number" (aggregate only).
+            period: Bucket size e.g. "1h", "1d", "30m" for time; "1000" for blocks (aggregate only).
+            involving: Filter by any involved address.
+            involving_label: Filter by entity label substring (e.g. "Binance").
+            involving_category: Filter by address category (e.g. "exchange").
+        """
+        extra: dict[str, Any] = {
+            "symbol0": symbol0,
+            "symbol1": symbol1,
+            "fee": fee,
+            "involving": involving,
+            "involving_label": involving_label,
+            "involving_category": involving_category,
+        }
+        extra.update(_build_range_params(block_start, block_end, since, until))
+        return _build_query(
+            "uniswap_v3", event_type, network, extra,
+            aggregate=aggregate, group_by=group_by, period=period, verbose=verbose,
+            with_value=with_value,
+        )
+
+    @mcp.tool()
+    def lido_query_builder(
+        event_type: str,
+        network: str,
+        block_start: int | None = None,
+        block_end: int | None = None,
+        since: str | None = None,
+        until: str | None = None,
+        verbose: bool = False,
+        with_value: bool = False,
+        aggregate: bool = False,
+        group_by: str = "time",
+        period: str = "1h",
+        involving: str | None = None,
+        involving_label: str | None = None,
+        involving_category: str | None = None,
+    ) -> str:
+        """Build a query for Lido liquid staking events.
+
+        Returns a query path string. Pass it to execute_query() for JSON
+        results or download_query() for CSV/Parquet files.
+
+        Event types: deposit, withdrawal_request, withdrawal_claimed, l2_deposit, l2_withdrawal_request
+
+        Args:
+            event_type: Event type (e.g. "deposit", "withdrawal_request", "withdrawal_claimed").
+            network: Network identifier (e.g. "ETH", "ARB", "BASE", "OP").
+            block_start: Starting block number.
+            block_end: Ending block number.
+            since: Start time (ISO 8601 or Unix timestamp).
+            until: End time (ISO 8601 or Unix timestamp).
+            verbose: Include all metadata fields (tx_hash, log_index, etc.).
+            with_value: Enrich events with USD value data (adds value_usd column; agg_value_usd on aggregates).
+            aggregate: Set True to build an aggregate query instead of raw events.
+            group_by: Bucket grouping — "time" or "block_number" (aggregate only).
+            period: Bucket size e.g. "1h", "1d", "30m" for time; "1000" for blocks (aggregate only).
+            involving: Filter by any involved address.
+            involving_label: Filter by entity label substring (e.g. "Binance").
+            involving_category: Filter by address category (e.g. "exchange").
+        """
+        extra: dict[str, Any] = {
+            "involving": involving,
+            "involving_label": involving_label,
+            "involving_category": involving_category,
+        }
+        extra.update(_build_range_params(block_start, block_end, since, until))
+        return _build_query(
+            "lido", event_type, network, extra,
+            aggregate=aggregate, group_by=group_by, period=period, verbose=verbose,
+            with_value=with_value,
+        )
+
+    @mcp.tool()
+    def stader_query_builder(
+        event_type: str,
+        network: str,
+        block_start: int | None = None,
+        block_end: int | None = None,
+        since: str | None = None,
+        until: str | None = None,
+        verbose: bool = False,
+        with_value: bool = False,
+        aggregate: bool = False,
+        group_by: str = "time",
+        period: str = "1h",
+        involving: str | None = None,
+        involving_label: str | None = None,
+        involving_category: str | None = None,
+    ) -> str:
+        """Build a query for Stader ETHx staking events.
+
+        Returns a query path string. Pass it to execute_query() for JSON
+        results or download_query() for CSV/Parquet files.
+
+        Args:
+            event_type: Event type.
+            network: Network identifier (e.g. "ETH").
+            block_start: Starting block number.
+            block_end: Ending block number.
+            since: Start time (ISO 8601 or Unix timestamp).
+            until: End time (ISO 8601 or Unix timestamp).
+            verbose: Include all metadata fields (tx_hash, log_index, etc.).
+            with_value: Enrich events with USD value data (adds value_usd column; agg_value_usd on aggregates).
+            aggregate: Set True to build an aggregate query instead of raw events.
+            group_by: Bucket grouping — "time" or "block_number" (aggregate only).
+            period: Bucket size e.g. "1h", "1d", "30m" for time; "1000" for blocks (aggregate only).
+            involving: Filter by any involved address.
+            involving_label: Filter by entity label substring (e.g. "Binance").
+            involving_category: Filter by address category (e.g. "exchange").
+        """
+        extra: dict[str, Any] = {
+            "involving": involving,
+            "involving_label": involving_label,
+            "involving_category": involving_category,
+        }
+        extra.update(_build_range_params(block_start, block_end, since, until))
+        return _build_query(
+            "stader", event_type, network, extra,
+            aggregate=aggregate, group_by=group_by, period=period, verbose=verbose,
+            with_value=with_value,
+        )
+
+    @mcp.tool()
+    def threshold_query_builder(
+        event_type: str,
+        network: str,
+        block_start: int | None = None,
+        block_end: int | None = None,
+        since: str | None = None,
+        until: str | None = None,
+        verbose: bool = False,
+        with_value: bool = False,
+        aggregate: bool = False,
+        group_by: str = "time",
+        period: str = "1h",
+        involving: str | None = None,
+        involving_label: str | None = None,
+        involving_category: str | None = None,
+    ) -> str:
+        """Build a query for Threshold tBTC bridge events.
+
+        Returns a query path string. Pass it to execute_query() for JSON
+        results or download_query() for CSV/Parquet files.
+
+        Args:
+            event_type: Event type.
+            network: Network identifier (e.g. "ETH").
+            block_start: Starting block number.
+            block_end: Ending block number.
+            since: Start time (ISO 8601 or Unix timestamp).
+            until: End time (ISO 8601 or Unix timestamp).
+            verbose: Include all metadata fields (tx_hash, log_index, etc.).
+            with_value: Enrich events with USD value data (adds value_usd column; agg_value_usd on aggregates).
+            aggregate: Set True to build an aggregate query instead of raw events.
+            group_by: Bucket grouping — "time" or "block_number" (aggregate only).
+            period: Bucket size e.g. "1h", "1d", "30m" for time; "1000" for blocks (aggregate only).
+            involving: Filter by any involved address.
+            involving_label: Filter by entity label substring (e.g. "Binance").
+            involving_category: Filter by address category (e.g. "exchange").
+        """
+        extra: dict[str, Any] = {
+            "involving": involving,
+            "involving_label": involving_label,
+            "involving_category": involving_category,
+        }
+        extra.update(_build_range_params(block_start, block_end, since, until))
+        return _build_query(
+            "threshold", event_type, network, extra,
+            aggregate=aggregate, group_by=group_by, period=period, verbose=verbose,
+            with_value=with_value,
+        )