defistream 1.0.6__py3-none-any.whl → 1.2.0__py3-none-any.whl

defistream/__init__.py

@@ -29,9 +29,14 @@ from .exceptions import (
     ServerError,
     ValidationError,
 )
-from .query import AsyncQueryBuilder, QueryBuilder
+from .query import (
+    AggregateQueryBuilder,
+    AsyncAggregateQueryBuilder,
+    AsyncQueryBuilder,
+    QueryBuilder,
+)
 
-__version__ = "1.0.6"
+__version__ = "1.2.0"
 
 __all__ = [
     # Clients
@@ -40,6 +45,8 @@ __all__ = [
     # Query builders
     "QueryBuilder",
     "AsyncQueryBuilder",
+    "AggregateQueryBuilder",
+    "AsyncAggregateQueryBuilder",
     # Exceptions
     "DeFiStreamError",
     "AuthenticationError",

defistream/client.py

@@ -126,6 +126,7 @@ class BaseClient:
         response: httpx.Response,
         as_dataframe: Literal["pandas", "polars"] | None = None,
         output_file: str | None = None,
+        response_key: str = "events",
     ) -> list[dict[str, Any]] | Any:
         """Process response and optionally convert to DataFrame or save to file."""
         self.last_response = self._parse_response_metadata(response.headers)
@@ -184,7 +185,7 @@ class BaseClient:
         if data.get("status") == "error":
             raise DeFiStreamError(data.get("error", "Unknown error"))
 
-        events = data.get("events", [])
+        events = data.get(response_key, [])
 
         if as_dataframe == "pandas":
             import pandas as pd
@@ -269,6 +270,7 @@ class DeFiStream(BaseClient):
         params: dict[str, Any] | None = None,
         as_dataframe: Literal["pandas", "polars"] | None = None,
         output_file: str | None = None,
+        response_key: str = "events",
     ) -> list[dict[str, Any]] | Any:
         """Make HTTP request."""
         if params is None:
@@ -281,7 +283,7 @@ class DeFiStream(BaseClient):
                 params["format"] = "csv"
 
         response = self._client.request(method, path, params=params)
-        return self._process_response(response, as_dataframe, output_file)
+        return self._process_response(response, as_dataframe, output_file, response_key)
 
     def decoders(self) -> list[str]:
         """Get list of available decoders."""
@@ -289,8 +291,24 @@ class DeFiStream(BaseClient):
         if response.status_code >= 400:
             self._handle_error_response(response)
         data = response.json()
+        if isinstance(data, list):
+            return data
         return data.get("decoders", [])
 
+    def aggregate_schema(self, protocol: str) -> dict[str, Any]:
+        """Get the aggregate schema for a protocol.
+
+        Args:
+            protocol: Protocol name (e.g. ``"erc20"``, ``"aave"``).
+
+        Returns:
+            Schema dictionary describing available aggregate fields.
+        """
+        response = self._client.get(f"/{protocol}/aggregate_schema")
+        if response.status_code >= 400:
+            self._handle_error_response(response)
+        return response.json()
+
 
 class AsyncDeFiStream(BaseClient):
     """
@@ -357,6 +375,7 @@ class AsyncDeFiStream(BaseClient):
         params: dict[str, Any] | None = None,
         as_dataframe: Literal["pandas", "polars"] | None = None,
         output_file: str | None = None,
+        response_key: str = "events",
     ) -> list[dict[str, Any]] | Any:
         """Make async HTTP request."""
         if params is None:
@@ -369,7 +388,7 @@ class AsyncDeFiStream(BaseClient):
                 params["format"] = "csv"
 
         response = await self._client.request(method, path, params=params)
-        return self._process_response(response, as_dataframe, output_file)
+        return self._process_response(response, as_dataframe, output_file, response_key)
 
     async def decoders(self) -> list[str]:
         """Get list of available decoders."""
@@ -377,4 +396,20 @@ class AsyncDeFiStream(BaseClient):
         if response.status_code >= 400:
             self._handle_error_response(response)
         data = response.json()
+        if isinstance(data, list):
+            return data
         return data.get("decoders", [])
+
+    async def aggregate_schema(self, protocol: str) -> dict[str, Any]:
+        """Get the aggregate schema for a protocol.
+
+        Args:
+            protocol: Protocol name (e.g. ``"erc20"``, ``"aave"``).
+
+        Returns:
+            Schema dictionary describing available aggregate fields.
+        """
+        response = await self._client.get(f"/{protocol}/aggregate_schema")
+        if response.status_code >= 400:
+            self._handle_error_response(response)
+        return response.json()

defistream/query.py

@@ -4,10 +4,84 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
 
+from .exceptions import ValidationError
+
 if TYPE_CHECKING:
     from .client import BaseClient
 
 
+# Label/category parameter names that need SQL safety checks
+_LABEL_CATEGORY_PARAMS = frozenset({
+    "involving_label", "involving_category",
+    "sender_label", "sender_category",
+    "receiver_label", "receiver_category",
+})
+
+# Mutual exclusivity groups: within each slot, only one key is allowed
+_INVOLVING_SLOT = ("involving", "involving_label", "involving_category")
+_SENDER_SLOT = ("sender", "sender_label", "sender_category")
+_RECEIVER_SLOT = ("receiver", "receiver_label", "receiver_category")
+
+
+def _normalize_multi(*args: str) -> str:
+    """Join varargs into a comma-separated string.
+
+    Accepts one or more strings. If a single pre-joined string is passed
+    (e.g. "a,b") it passes through unchanged.
+
+    Raises:
+        ValueError: If no arguments are provided.
+    """
+    if not args:
+        raise ValueError("At least one value is required")
+    return ",".join(args)
+
+
+def _validate_sql_safety(params: dict[str, Any]) -> None:
+    """Reject label/category values containing quotes or backslashes.
+
+    Raises:
+        ValidationError: If any label/category value contains ' or \\.
+    """
+    for key in _LABEL_CATEGORY_PARAMS:
+        value = params.get(key)
+        if value is not None and isinstance(value, str):
+            if "'" in value or "\\" in value:
+                raise ValidationError(
+                    f"Parameter '{key}' contains unsafe characters (single quote or backslash)"
+                )
+
+
+def _validate_mutual_exclusivity(params: dict[str, Any]) -> None:
+    """Enforce mutual exclusivity between filter slots.
+
+    Within each slot (involving, sender, receiver) only one key is allowed.
+    Cross-slot: involving* cannot combine with sender* or receiver*.
+
+    Raises:
+        ValidationError: If conflicting parameters are present.
+    """
+    def _check_slot(slot: tuple[str, ...], slot_name: str) -> str | None:
+        present = [k for k in slot if k in params]
+        if len(present) > 1:
+            raise ValidationError(
+                f"Cannot combine {present[0]} with {present[1]} — "
+                f"pick one {slot_name} filter"
+            )
+        return present[0] if present else None
+
+    involving_key = _check_slot(_INVOLVING_SLOT, "involving")
+    sender_key = _check_slot(_SENDER_SLOT, "sender")
+    receiver_key = _check_slot(_RECEIVER_SLOT, "receiver")
+
+    if involving_key and (sender_key or receiver_key):
+        other = sender_key or receiver_key
+        raise ValidationError(
+            f"Cannot combine {involving_key} with {other} — "
+            f"use involving* or sender*/receiver*, not both"
+        )
+
+
 class QueryBuilder:
     """
     Builder for constructing and executing DeFiStream API queries.
@@ -78,21 +152,49 @@ class QueryBuilder:
         return self._copy_with(since=start, until=end)
 
     # ERC20 and Native Token filters
-    def sender(self, address: str) -> "QueryBuilder":
-        """Filter by sender address (ERC20, Native Token)."""
-        return self._copy_with(sender=address)
+    def sender(self, *addresses: str) -> "QueryBuilder":
+        """Filter by sender address (ERC20, Native Token). Accepts multiple addresses."""
+        return self._copy_with(sender=_normalize_multi(*addresses))
 
-    def receiver(self, address: str) -> "QueryBuilder":
-        """Filter by receiver address (ERC20, Native Token)."""
-        return self._copy_with(receiver=address)
+    def receiver(self, *addresses: str) -> "QueryBuilder":
+        """Filter by receiver address (ERC20, Native Token). Accepts multiple addresses."""
+        return self._copy_with(receiver=_normalize_multi(*addresses))
 
-    def from_address(self, address: str) -> "QueryBuilder":
-        """Filter by sender address (alias for sender)."""
-        return self.sender(address)
+    def from_address(self, *addresses: str) -> "QueryBuilder":
+        """Filter by sender address (alias for sender). Accepts multiple addresses."""
+        return self.sender(*addresses)
 
-    def to_address(self, address: str) -> "QueryBuilder":
-        """Filter by receiver address (alias for receiver)."""
-        return self.receiver(address)
+    def to_address(self, *addresses: str) -> "QueryBuilder":
+        """Filter by receiver address (alias for receiver). Accepts multiple addresses."""
+        return self.receiver(*addresses)
+
+    def involving(self, *addresses: str) -> "QueryBuilder":
+        """Filter by any involved address (all protocols). Accepts multiple addresses."""
+        return self._copy_with(involving=_normalize_multi(*addresses))
+
+    def involving_label(self, *labels: str) -> "QueryBuilder":
+        """Filter by label on any involved address (all protocols)."""
+        return self._copy_with(involving_label=_normalize_multi(*labels))
+
+    def involving_category(self, *categories: str) -> "QueryBuilder":
+        """Filter by category on any involved address (all protocols)."""
+        return self._copy_with(involving_category=_normalize_multi(*categories))
+
+    def sender_label(self, *labels: str) -> "QueryBuilder":
+        """Filter sender by label (ERC20, Native Token)."""
+        return self._copy_with(sender_label=_normalize_multi(*labels))
+
+    def sender_category(self, *categories: str) -> "QueryBuilder":
+        """Filter sender by category (ERC20, Native Token)."""
+        return self._copy_with(sender_category=_normalize_multi(*categories))
+
+    def receiver_label(self, *labels: str) -> "QueryBuilder":
+        """Filter receiver by label (ERC20, Native Token)."""
+        return self._copy_with(receiver_label=_normalize_multi(*labels))
+
+    def receiver_category(self, *categories: str) -> "QueryBuilder":
+        """Filter receiver by category (ERC20, Native Token)."""
+        return self._copy_with(receiver_category=_normalize_multi(*categories))
 
     def min_amount(self, amount: float) -> "QueryBuilder":
         """Filter by minimum amount (ERC20, Native Token)."""
@@ -134,6 +236,8 @@ class QueryBuilder:
     def _build_params(self) -> dict[str, Any]:
         """Build the final query parameters."""
         params = self._params.copy()
+        _validate_sql_safety(params)
+        _validate_mutual_exclusivity(params)
         if self._verbose:
             params["verbose"] = "true"
         return params
@@ -221,10 +325,104 @@ class QueryBuilder:
             params["format"] = format
             self._client._request("GET", self._endpoint, params=params, output_file=path)
 
+    # Aggregate transition
+    def aggregate(self, group_by: str = "time", period: str = "1h") -> "AggregateQueryBuilder":
+        """Transition to an aggregate query.
+
+        Appends ``/aggregate`` to the endpoint and includes ``group_by`` and
+        ``period`` as query parameters.
+
+        Args:
+            group_by: Aggregation axis — ``"time"`` or ``"block"``.
+            period: Bucket size, e.g. ``"1h"``, ``"100b"``.
+
+        Returns:
+            An :class:`AggregateQueryBuilder` that inherits all current filters.
+        """
+        builder = AggregateQueryBuilder(
+            self._client,
+            self._endpoint.rstrip("/") + "/aggregate",
+            self._params.copy(),
+        )
+        builder._verbose = self._verbose
+        builder._params["group_by"] = group_by
+        builder._params["period"] = period
+        return builder
+
     def __repr__(self) -> str:
         return f"QueryBuilder(endpoint={self._endpoint!r}, params={self._params!r}, verbose={self._verbose})"
 
 
+class AggregateQueryBuilder(QueryBuilder):
+    """Builder for aggregate (bucketed) queries.
+
+    Returned by :pymeth:`QueryBuilder.aggregate`. Overrides terminal methods
+    so that JSON responses extract from the ``"data"`` key instead of
+    ``"events"``.
+    """
+
+    def _copy_with(self, **updates: Any) -> "AggregateQueryBuilder":
+        """Create a copy preserving aggregate builder type."""
+        new_builder = AggregateQueryBuilder(self._client, self._endpoint, self._params.copy())
+        new_builder._verbose = self._verbose
+        for key, value in updates.items():
+            if key == "verbose":
+                new_builder._verbose = value
+            elif value is not None:
+                new_builder._params[key] = value
+        return new_builder
+
+    # Terminal methods — extract from "data" key
+    def as_dict(self) -> list[dict[str, Any]]:
+        """Execute aggregate query and return results as list of dictionaries."""
+        params = self._build_params()
+        return self._client._request(
+            "GET", self._endpoint, params=params, response_key="data",
+        )
+
+    def as_df(self, library: str = "pandas") -> Any:
+        """Execute aggregate query and return results as DataFrame."""
+        if library not in ("pandas", "polars"):
+            raise ValueError(f"library must be 'pandas' or 'polars', got '{library}'")
+        params = self._build_params()
+        params["format"] = "parquet"
+        return self._client._request(
+            "GET", self._endpoint, params=params, as_dataframe=library,
+        )
+
+    def as_file(self, path: str, format: str | None = None) -> None:
+        """Execute aggregate query and save results to file."""
+        if format is None:
+            if path.endswith(".csv"):
+                format = "csv"
+            elif path.endswith(".parquet"):
+                format = "parquet"
+            elif path.endswith(".json"):
+                format = "json"
+            else:
+                raise ValueError(
+                    f"Cannot determine format from path '{path}'. "
+                    "Use a file extension (.csv, .parquet, .json) or specify format explicitly."
+                )
+
+        if format not in ("csv", "parquet", "json"):
+            raise ValueError(f"format must be 'csv', 'parquet', or 'json', got '{format}'")
+
+        params = self._build_params()
+
+        if format == "json":
+            import json as _json
+            results = self.as_dict()
+            with open(path, "w") as f:
+                _json.dump(results, f, indent=2)
+        else:
+            params["format"] = format
+            self._client._request("GET", self._endpoint, params=params, output_file=path)
+
+    def __repr__(self) -> str:
+        return f"AggregateQueryBuilder(endpoint={self._endpoint!r}, params={self._params!r}, verbose={self._verbose})"
+
+
 class AsyncQueryBuilder:
     """
     Async builder for constructing and executing DeFiStream API queries.
@@ -294,21 +492,49 @@ class AsyncQueryBuilder:
         return self._copy_with(since=start, until=end)
 
     # ERC20 and Native Token filters
-    def sender(self, address: str) -> "AsyncQueryBuilder":
-        """Filter by sender address (ERC20, Native Token)."""
-        return self._copy_with(sender=address)
+    def sender(self, *addresses: str) -> "AsyncQueryBuilder":
+        """Filter by sender address (ERC20, Native Token). Accepts multiple addresses."""
+        return self._copy_with(sender=_normalize_multi(*addresses))
 
-    def receiver(self, address: str) -> "AsyncQueryBuilder":
-        """Filter by receiver address (ERC20, Native Token)."""
-        return self._copy_with(receiver=address)
+    def receiver(self, *addresses: str) -> "AsyncQueryBuilder":
+        """Filter by receiver address (ERC20, Native Token). Accepts multiple addresses."""
+        return self._copy_with(receiver=_normalize_multi(*addresses))
 
-    def from_address(self, address: str) -> "AsyncQueryBuilder":
-        """Filter by sender address (alias for sender)."""
-        return self.sender(address)
+    def from_address(self, *addresses: str) -> "AsyncQueryBuilder":
+        """Filter by sender address (alias for sender). Accepts multiple addresses."""
+        return self.sender(*addresses)
 
-    def to_address(self, address: str) -> "AsyncQueryBuilder":
-        """Filter by receiver address (alias for receiver)."""
-        return self.receiver(address)
+    def to_address(self, *addresses: str) -> "AsyncQueryBuilder":
+        """Filter by receiver address (alias for receiver). Accepts multiple addresses."""
+        return self.receiver(*addresses)
+
+    def involving(self, *addresses: str) -> "AsyncQueryBuilder":
+        """Filter by any involved address (all protocols). Accepts multiple addresses."""
+        return self._copy_with(involving=_normalize_multi(*addresses))
+
+    def involving_label(self, *labels: str) -> "AsyncQueryBuilder":
+        """Filter by label on any involved address (all protocols)."""
+        return self._copy_with(involving_label=_normalize_multi(*labels))
+
+    def involving_category(self, *categories: str) -> "AsyncQueryBuilder":
+        """Filter by category on any involved address (all protocols)."""
+        return self._copy_with(involving_category=_normalize_multi(*categories))
+
+    def sender_label(self, *labels: str) -> "AsyncQueryBuilder":
+        """Filter sender by label (ERC20, Native Token)."""
+        return self._copy_with(sender_label=_normalize_multi(*labels))
+
+    def sender_category(self, *categories: str) -> "AsyncQueryBuilder":
+        """Filter sender by category (ERC20, Native Token)."""
+        return self._copy_with(sender_category=_normalize_multi(*categories))
+
+    def receiver_label(self, *labels: str) -> "AsyncQueryBuilder":
+        """Filter receiver by label (ERC20, Native Token)."""
+        return self._copy_with(receiver_label=_normalize_multi(*labels))
+
+    def receiver_category(self, *categories: str) -> "AsyncQueryBuilder":
+        """Filter receiver by category (ERC20, Native Token)."""
+        return self._copy_with(receiver_category=_normalize_multi(*categories))
 
     def min_amount(self, amount: float) -> "AsyncQueryBuilder":
         """Filter by minimum amount (ERC20, Native Token)."""
@@ -350,6 +576,8 @@ class AsyncQueryBuilder:
     def _build_params(self) -> dict[str, Any]:
         """Build the final query parameters."""
         params = self._params.copy()
+        _validate_sql_safety(params)
+        _validate_mutual_exclusivity(params)
         if self._verbose:
             params["verbose"] = "true"
         return params
@@ -437,5 +665,99 @@ class AsyncQueryBuilder:
             params["format"] = format
             await self._client._request("GET", self._endpoint, params=params, output_file=path)
 
+    # Aggregate transition
+    def aggregate(self, group_by: str = "time", period: str = "1h") -> "AsyncAggregateQueryBuilder":
+        """Transition to an async aggregate query.
+
+        Appends ``/aggregate`` to the endpoint and includes ``group_by`` and
+        ``period`` as query parameters.
+
+        Args:
+            group_by: Aggregation axis — ``"time"`` or ``"block"``.
+            period: Bucket size, e.g. ``"1h"``, ``"100b"``.
+
+        Returns:
+            An :class:`AsyncAggregateQueryBuilder` that inherits all current filters.
+        """
+        builder = AsyncAggregateQueryBuilder(
+            self._client,
+            self._endpoint.rstrip("/") + "/aggregate",
+            self._params.copy(),
+        )
+        builder._verbose = self._verbose
+        builder._params["group_by"] = group_by
+        builder._params["period"] = period
+        return builder
+
     def __repr__(self) -> str:
         return f"AsyncQueryBuilder(endpoint={self._endpoint!r}, params={self._params!r}, verbose={self._verbose})"
+
+
+class AsyncAggregateQueryBuilder(AsyncQueryBuilder):
+    """Async builder for aggregate (bucketed) queries.
+
+    Returned by :pymeth:`AsyncQueryBuilder.aggregate`. Overrides terminal
+    methods so that JSON responses extract from the ``"data"`` key instead of
+    ``"events"``.
+    """
+
+    def _copy_with(self, **updates: Any) -> "AsyncAggregateQueryBuilder":
+        """Create a copy preserving async aggregate builder type."""
+        new_builder = AsyncAggregateQueryBuilder(self._client, self._endpoint, self._params.copy())
+        new_builder._verbose = self._verbose
+        for key, value in updates.items():
+            if key == "verbose":
+                new_builder._verbose = value
+            elif value is not None:
+                new_builder._params[key] = value
+        return new_builder
+
+    # Terminal methods — extract from "data" key
+    async def as_dict(self) -> list[dict[str, Any]]:
+        """Execute aggregate query and return results as list of dictionaries."""
+        params = self._build_params()
+        return await self._client._request(
+            "GET", self._endpoint, params=params, response_key="data",
+        )
+
+    async def as_df(self, library: str = "pandas") -> Any:
+        """Execute aggregate query and return results as DataFrame."""
+        if library not in ("pandas", "polars"):
+            raise ValueError(f"library must be 'pandas' or 'polars', got '{library}'")
+        params = self._build_params()
+        params["format"] = "parquet"
+        return await self._client._request(
+            "GET", self._endpoint, params=params, as_dataframe=library,
+        )
+
+    async def as_file(self, path: str, format: str | None = None) -> None:
+        """Execute aggregate query and save results to file."""
+        if format is None:
+            if path.endswith(".csv"):
+                format = "csv"
+            elif path.endswith(".parquet"):
+                format = "parquet"
+            elif path.endswith(".json"):
+                format = "json"
+            else:
+                raise ValueError(
+                    f"Cannot determine format from path '{path}'. "
+                    "Use a file extension (.csv, .parquet, .json) or specify format explicitly."
+                )
+
+        if format not in ("csv", "parquet", "json"):
+            raise ValueError(f"format must be 'csv', 'parquet', or 'json', got '{format}'")
+
+        params = self._build_params()
+
+        if format == "json":
+            import json as _json
+            results = await self.as_dict()
+            with open(path, "w") as f:
+                _json.dump(results, f, indent=2)
+        else:
+            params["format"] = format
+            await self._client._request("GET", self._endpoint, params=params, output_file=path)
+
+    def __repr__(self) -> str:
+        return f"AsyncAggregateQueryBuilder(endpoint={self._endpoint!r}, params={self._params!r}, verbose={self._verbose})"

{defistream-1.0.6.dist-info → defistream-1.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: defistream
-Version: 1.0.6
+Version: 1.2.0
 Summary: Python client for the DeFiStream API
 Project-URL: Homepage, https://defistream.dev
 Project-URL: Documentation, https://docs.defistream.dev
@@ -204,6 +204,47 @@ df = (
 )
 ```
 
+### Label & Category Filters
+
+```python
+# Get USDT transfers involving Binance wallets
+df = (
+    client.erc20.transfers("USDT")
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .involving_label("Binance")
+    .as_df()
+)
+
+# Get USDT transfers FROM exchanges TO DeFi protocols
+df = (
+    client.erc20.transfers("USDT")
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .sender_category("exchange")
+    .receiver_category("defi")
+    .as_df()
+)
+
+# Get AAVE deposits involving exchange addresses
+df = (
+    client.aave.deposits()
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .involving_category("exchange")
+    .as_df()
+)
+
+# Get native ETH transfers FROM Binance or Coinbase (multi-value)
+df = (
+    client.native_token.transfers()
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .sender_label("Binance,Coinbase")
+    .as_df()
+)
+```
+
 ### Verbose Mode
 
 By default, responses omit metadata fields to reduce payload size. Use `.verbose()` to include all fields:
@@ -295,6 +336,21 @@ for transfer in transfers:
 
 > **Note:** `as_dict()` and `as_file("*.json")` use JSON format which has a **10,000 block limit**. For larger block ranges, use `as_df()` or `as_file()` with `.parquet` or `.csv` extensions, which support up to 1,000,000 blocks.
 
+### Context Manager
+
+Both sync and async clients support context managers to automatically close connections:
+
+```python
+# Sync
+with DeFiStream() as client:
+    df = (
+        client.erc20.transfers("USDT")
+        .network("ETH")
+        .block_range(21000000, 21010000)
+        .as_df()
+    )
+```
+
 ### Async Usage
 
 ```python
@@ -314,6 +370,14 @@ async def main():
 asyncio.run(main())
 ```
 
+### List Available Decoders
+
+```python
+client = DeFiStream()
+decoders = client.decoders()
+print(decoders)  # ['native_token', 'erc20', 'aave', 'uniswap', 'lido', 'stader', 'threshold']
+```
+
 ## Configuration
 
 ### Environment Variables
@@ -414,8 +478,11 @@ print(f"Request cost: {client.last_response.request_cost}")
 | Method | Protocols | Description |
 |--------|-----------|-------------|
 | `.token(symbol)` | ERC20 | Token symbol (USDT, USDC) or contract address (required) |
-| `.sender(addr)` | ERC20, Native | Filter by sender address |
-| `.receiver(addr)` | ERC20, Native | Filter by receiver address |
+| `.sender(*addrs)` | ERC20, Native | Filter by sender address (multi-value) |
+| `.receiver(*addrs)` | ERC20, Native | Filter by receiver address (multi-value) |
+| `.involving(*addrs)` | All | Filter by any involved address (multi-value) |
+| `.from_address(*addrs)` | ERC20, Native | Alias for `.sender()` |
+| `.to_address(*addrs)` | ERC20, Native | Alias for `.receiver()` |
 | `.min_amount(amt)` | ERC20, Native | Minimum transfer amount |
 | `.max_amount(amt)` | ERC20, Native | Maximum transfer amount |
 | `.eth_market_type(type)` | AAVE | Market type for ETH: 'Core', 'Prime', 'EtherFi' |
@@ -423,6 +490,23 @@ print(f"Request cost: {client.last_response.request_cost}")
 | `.symbol1(sym)` | Uniswap | Second token symbol (required) |
 | `.fee(tier)` | Uniswap | Fee tier: 100, 500, 3000, 10000 (required) |
 
+### Address Label & Category Filters
+
+Filter events by entity names or categories using the labels database. Available on all protocols.
+
+| Method | Protocols | Description |
+|--------|-----------|-------------|
+| `.involving_label(label)` | All | Filter where any involved address matches a label substring (e.g., "Binance") |
+| `.involving_category(cat)` | All | Filter where any involved address matches a category (e.g., "exchange") |
+| `.sender_label(label)` | ERC20, Native | Filter sender by label substring |
+| `.sender_category(cat)` | ERC20, Native | Filter sender by category |
+| `.receiver_label(label)` | ERC20, Native | Filter receiver by label substring |
+| `.receiver_category(cat)` | ERC20, Native | Filter receiver by category |
+
+**Multi-value support:** Pass multiple values as separate arguments (e.g., `.sender_label("Binance", "Coinbase")`) or as a comma-separated string (e.g., `.sender_label("Binance,Coinbase")`). Both forms are equivalent.
+
+**Mutual exclusivity:** Within each slot (involving/sender/receiver), only one of address/label/category can be set. `involving*` filters cannot be combined with `sender*`/`receiver*` filters.
+
 ### Terminal Methods
 
 | Method | Description |

defistream-1.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+defistream/__init__.py,sha256=j9vKDoqInjyvxau2lDb1eBfr0ZWKVouhBNBbgzXbgpg,1224
+defistream/client.py,sha256=OZsaa7kgDxWCS37geoTGlp-IFaO3Kn8bm1ghNE9tqB4,13973
+defistream/exceptions.py,sha256=_GxZQ18_YvXFtmNHeddWV8fHPIllHgFeP7fP0CmHF1k,1492
+defistream/models.py,sha256=Zw3DHAISxB6pivKybNzyHXR5IcRwvTZl23DHbjfyKwM,622
+defistream/protocols.py,sha256=5_bYd46lDy-mK6LZ8sTGW0Z2IVH4g0cQ5rBbbOXsw0U,15368
+defistream/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+defistream/query.py,sha256=Pr-zwUCBcjBUkqa1CFzVJmsnZ4DpV29c0_9p1VtfGak,30433
+defistream-1.2.0.dist-info/METADATA,sha256=7rNfboEYqF87-3RKkUlOzMRsKRKEns0H1lmeesEJwsM,13657
+defistream-1.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+defistream-1.2.0.dist-info/licenses/LICENSE,sha256=72DWAof8dMePfFQmfaswClW5d-sE6k7p-7VpuSKLmU4,1067
+defistream-1.2.0.dist-info/RECORD,,

defistream-1.0.6.dist-info/RECORD

@@ -1,11 +0,0 @@
-defistream/__init__.py,sha256=duUlI1d-H7mP16D6dd0zbCslu45ARItE_pwQ5N7o05M,1089
-defistream/client.py,sha256=Ku8ouDbM6Mx4lVmqvBwNvNt-h2FkvqauPMSjKyPkjU4,12717
-defistream/exceptions.py,sha256=_GxZQ18_YvXFtmNHeddWV8fHPIllHgFeP7fP0CmHF1k,1492
-defistream/models.py,sha256=Zw3DHAISxB6pivKybNzyHXR5IcRwvTZl23DHbjfyKwM,622
-defistream/protocols.py,sha256=5_bYd46lDy-mK6LZ8sTGW0Z2IVH4g0cQ5rBbbOXsw0U,15368
-defistream/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-defistream/query.py,sha256=sNn_0OzNDlsp4N74Grumsb08R5OFPPoppPok3vh8Y6Q,16775
-defistream-1.0.6.dist-info/METADATA,sha256=2VBBk9BJNGQiGOyya3YCTB23rFTbes0UjNhma-4R4ig,10877
-defistream-1.0.6.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-defistream-1.0.6.dist-info/licenses/LICENSE,sha256=72DWAof8dMePfFQmfaswClW5d-sE6k7p-7VpuSKLmU4,1067
-defistream-1.0.6.dist-info/RECORD,,