defistream 1.0.6__tar.gz → 1.1.0__tar.gz

defistream-1.1.0/.claude/settings.local.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git log:*)",
+      "Bash(python -m pytest:*)",
+      "Bash(python3 -m pytest:*)",
+      "Bash(git add:*)",
+      "Bash(git commit -m \"$\\(cat <<''EOF''\nAdd label/category filters and multi-value support to query builders\n\nAdd involving, involving_label, involving_category, sender_label,\nsender_category, receiver_label, receiver_category methods to both\nQueryBuilder and AsyncQueryBuilder. Update sender/receiver/from_address/\nto_address to accept varargs for multi-value filtering. Add SQL safety\nvalidation for label/category params and mutual exclusivity enforcement\nbetween involving* and sender*/receiver* filter slots.\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(python3 -m build:*)",
+      "Bash(python3:*)",
+      "Bash(pip3 install:*)",
+      "Bash(/home/mvp/Running/Horatio_Chain_Scan/DeFiStream/python-client/.venv/bin/pip install:*)",
+      "Bash(/home/mvp/Running/Horatio_Chain_Scan/DeFiStream/python-client/.venv/bin/python:*)"
+    ]
+  }
+}

{defistream-1.0.6 → defistream-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: defistream
-Version: 1.0.6
+Version: 1.1.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:
@@ -423,6 +464,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:** Comma-separated values are accepted (e.g., `"Binance,Coinbase"`).
+
+**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.0.6 → defistream-1.1.0}/README.md

@@ -170,6 +170,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:
@@ -389,6 +430,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:** Comma-separated values are accepted (e.g., `"Binance,Coinbase"`).
+
+**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.0.6 → defistream-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "defistream"
-version = "1.0.6"
+version = "1.1.0"
 description = "Python client for the DeFiStream API"
 readme = "README.md"
 license = "MIT"

{defistream-1.0.6 → defistream-1.1.0}/src/defistream/__init__.py

@@ -31,7 +31,7 @@ from .exceptions import (
 )
 from .query import AsyncQueryBuilder, QueryBuilder
 
-__version__ = "1.0.6"
+__version__ = "1.1.0"
 
 __all__ = [
     # Clients

{defistream-1.0.6 → defistream-1.1.0}/src/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, *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, *addresses: str) -> "QueryBuilder":
+        """Filter by sender address (alias for sender). Accepts multiple addresses."""
+        return self.sender(*addresses)
+
+    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 receiver(self, address: str) -> "QueryBuilder":
-        """Filter by receiver address (ERC20, Native Token)."""
-        return self._copy_with(receiver=address)
+    def sender_label(self, *labels: str) -> "QueryBuilder":
+        """Filter sender by label (ERC20, Native Token)."""
+        return self._copy_with(sender_label=_normalize_multi(*labels))
 
-    def from_address(self, address: str) -> "QueryBuilder":
-        """Filter by sender address (alias for sender)."""
-        return self.sender(address)
+    def sender_category(self, *categories: str) -> "QueryBuilder":
+        """Filter sender by category (ERC20, Native Token)."""
+        return self._copy_with(sender_category=_normalize_multi(*categories))
 
-    def to_address(self, address: str) -> "QueryBuilder":
-        """Filter by receiver address (alias for receiver)."""
-        return self.receiver(address)
+    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
@@ -294,21 +398,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, *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, *addresses: str) -> "AsyncQueryBuilder":
+        """Filter by sender address (alias for sender). Accepts multiple addresses."""
+        return self.sender(*addresses)
+
+    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 receiver(self, address: str) -> "AsyncQueryBuilder":
-        """Filter by receiver address (ERC20, Native Token)."""
-        return self._copy_with(receiver=address)
+    def sender_category(self, *categories: str) -> "AsyncQueryBuilder":
+        """Filter sender by category (ERC20, Native Token)."""
+        return self._copy_with(sender_category=_normalize_multi(*categories))
 
-    def from_address(self, address: str) -> "AsyncQueryBuilder":
-        """Filter by sender address (alias for sender)."""
-        return self.sender(address)
+    def receiver_label(self, *labels: str) -> "AsyncQueryBuilder":
+        """Filter receiver by label (ERC20, Native Token)."""
+        return self._copy_with(receiver_label=_normalize_multi(*labels))
 
-    def to_address(self, address: str) -> "AsyncQueryBuilder":
-        """Filter by receiver address (alias for receiver)."""
-        return self.receiver(address)
+    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 +482,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

{defistream-1.0.6 → defistream-1.1.0}/tests/test_client.py

@@ -400,3 +400,335 @@ class TestAsyncTerminalMethods:
         client = AsyncDeFiStream(api_key="dsk_test")
         query = client.erc20.transfers()
         assert hasattr(query, "as_file")
+
+
+class TestLabelCategoryMethods:
+    """Test label and category filter methods."""
+
+    def test_involving_sets_param(self):
+        """involving() should set involving param."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().involving("0xA")
+        assert query._params["involving"] == "0xA"
+
+    def test_involving_label_sets_param(self):
+        """involving_label() should set involving_label param."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().involving_label("Binance")
+        assert query._params["involving_label"] == "Binance"
+
+    def test_involving_category_sets_param(self):
+        """involving_category() should set involving_category param."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().involving_category("CEX")
+        assert query._params["involving_category"] == "CEX"
+
+    def test_sender_label_sets_param(self):
+        """sender_label() should set sender_label param."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().sender_label("Binance")
+        assert query._params["sender_label"] == "Binance"
+
+    def test_sender_category_sets_param(self):
+        """sender_category() should set sender_category param."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().sender_category("CEX")
+        assert query._params["sender_category"] == "CEX"
+
+    def test_receiver_label_sets_param(self):
+        """receiver_label() should set receiver_label param."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().receiver_label("Coinbase")
+        assert query._params["receiver_label"] == "Coinbase"
+
+    def test_receiver_category_sets_param(self):
+        """receiver_category() should set receiver_category param."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().receiver_category("DEX")
+        assert query._params["receiver_category"] == "DEX"
+
+    def test_label_chaining(self):
+        """Label methods should chain with other methods."""
+        client = DeFiStream(api_key="dsk_test")
+        query = (
+            client.erc20.transfers("USDT")
+            .network("ETH")
+            .sender_label("Binance")
+            .block_range(21000000, 21010000)
+        )
+        assert query._params["sender_label"] == "Binance"
+        assert query._params["network"] == "ETH"
+        assert query._params["block_start"] == 21000000
+
+    def test_label_immutability(self):
+        """Label methods should return new instances (immutability)."""
+        client = DeFiStream(api_key="dsk_test")
+        query1 = client.erc20.transfers()
+        query2 = query1.sender_label("Binance")
+        assert query1 is not query2
+        assert "sender_label" not in query1._params
+        assert query2._params["sender_label"] == "Binance"
+
+    def test_sender_and_receiver_labels_together(self):
+        """sender_label and receiver_label should work together."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().sender_label("Binance").receiver_label("Coinbase")
+        params = query._build_params()
+        assert params["sender_label"] == "Binance"
+        assert params["receiver_label"] == "Coinbase"
+
+
+class TestMultiValueSupport:
+    """Test multi-value support for address and label/category filters."""
+
+    def test_sender_varargs_join(self):
+        """sender() with multiple args should join with comma."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().sender("0xA", "0xB", "0xC")
+        assert query._params["sender"] == "0xA,0xB,0xC"
+
+    def test_receiver_varargs_join(self):
+        """receiver() with multiple args should join with comma."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().receiver("0xA", "0xB")
+        assert query._params["receiver"] == "0xA,0xB"
+
+    def test_from_address_varargs_join(self):
+        """from_address() with multiple args should join with comma."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().from_address("0xA", "0xB")
+        assert query._params["sender"] == "0xA,0xB"
+
+    def test_to_address_varargs_join(self):
+        """to_address() with multiple args should join with comma."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().to_address("0xA", "0xB")
+        assert query._params["receiver"] == "0xA,0xB"
+
+    def test_involving_varargs_join(self):
+        """involving() with multiple args should join with comma."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().involving("0xA", "0xB")
+        assert query._params["involving"] == "0xA,0xB"
+
+    def test_involving_label_varargs_join(self):
+        """involving_label() with multiple args should join with comma."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().involving_label("Binance", "Coinbase")
+        assert query._params["involving_label"] == "Binance,Coinbase"
+
+    def test_involving_category_varargs_join(self):
+        """involving_category() with multiple args should join with comma."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().involving_category("CEX", "DEX")
+        assert query._params["involving_category"] == "CEX,DEX"
+
+    def test_sender_label_varargs_join(self):
+        """sender_label() with multiple args should join with comma."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().sender_label("Binance", "Coinbase")
+        assert query._params["sender_label"] == "Binance,Coinbase"
+
+    def test_pre_joined_string_passthrough(self):
+        """A single pre-joined string should pass through unchanged."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().sender("0xA,0xB,0xC")
+        assert query._params["sender"] == "0xA,0xB,0xC"
+
+    def test_single_string_backward_compat(self):
+        """Single string arg should still work (backward compatibility)."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().sender("0xA")
+        assert query._params["sender"] == "0xA"
+
+    def test_sender_no_args_raises(self):
+        """sender() with no args should raise ValueError."""
+        client = DeFiStream(api_key="dsk_test")
+        with pytest.raises(ValueError, match="At least one value is required"):
+            client.erc20.transfers().sender()
+
+    def test_involving_label_no_args_raises(self):
+        """involving_label() with no args should raise ValueError."""
+        client = DeFiStream(api_key="dsk_test")
+        with pytest.raises(ValueError, match="At least one value is required"):
+            client.erc20.transfers().involving_label()
+
+
+class TestMutualExclusivity:
+    """Test mutual exclusivity validation between filter slots."""
+
+    def test_involving_vs_involving_label_raises(self):
+        """involving + involving_label should raise ValidationError."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().involving("0xA").involving_label("Binance")
+        with pytest.raises(ValidationError, match="Cannot combine"):
+            query._build_params()
+
+    def test_involving_vs_involving_category_raises(self):
+        """involving + involving_category should raise ValidationError."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().involving("0xA").involving_category("CEX")
+        with pytest.raises(ValidationError, match="Cannot combine"):
+            query._build_params()
+
+    def test_involving_label_vs_involving_category_raises(self):
+        """involving_label + involving_category should raise ValidationError."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().involving_label("Binance").involving_category("CEX")
+        with pytest.raises(ValidationError, match="Cannot combine"):
+            query._build_params()
+
+    def test_sender_vs_sender_label_raises(self):
+        """sender + sender_label should raise ValidationError."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().sender("0xA").sender_label("Binance")
+        with pytest.raises(ValidationError, match="Cannot combine"):
+            query._build_params()
+
+    def test_sender_vs_sender_category_raises(self):
+        """sender + sender_category should raise ValidationError."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().sender("0xA").sender_category("CEX")
+        with pytest.raises(ValidationError, match="Cannot combine"):
+            query._build_params()
+
+    def test_receiver_vs_receiver_label_raises(self):
+        """receiver + receiver_label should raise ValidationError."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().receiver("0xA").receiver_label("Coinbase")
+        with pytest.raises(ValidationError, match="Cannot combine"):
+            query._build_params()
+
+    def test_receiver_vs_receiver_category_raises(self):
+        """receiver + receiver_category should raise ValidationError."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().receiver("0xA").receiver_category("CEX")
+        with pytest.raises(ValidationError, match="Cannot combine"):
+            query._build_params()
+
+    def test_involving_with_sender_raises(self):
+        """involving + sender should raise ValidationError (cross-slot)."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().involving("0xA").sender("0xB")
+        with pytest.raises(ValidationError, match="Cannot combine"):
+            query._build_params()
+
+    def test_involving_label_with_receiver_label_raises(self):
+        """involving_label + receiver_label should raise ValidationError (cross-slot)."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().involving_label("Binance").receiver_label("Coinbase")
+        with pytest.raises(ValidationError, match="Cannot combine"):
+            query._build_params()
+
+    def test_involving_category_with_sender_category_raises(self):
+        """involving_category + sender_category should raise ValidationError (cross-slot)."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().involving_category("CEX").sender_category("DEX")
+        with pytest.raises(ValidationError, match="Cannot combine"):
+            query._build_params()
+
+    def test_sender_and_receiver_valid(self):
+        """sender + receiver should be valid (different slots, no involving)."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().sender("0xA").receiver("0xB")
+        params = query._build_params()
+        assert params["sender"] == "0xA"
+        assert params["receiver"] == "0xB"
+
+    def test_sender_label_and_receiver_category_valid(self):
+        """sender_label + receiver_category should be valid."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().sender_label("Binance").receiver_category("DEX")
+        params = query._build_params()
+        assert params["sender_label"] == "Binance"
+        assert params["receiver_category"] == "DEX"
+
+
+class TestSQLSafetyValidation:
+    """Test SQL safety validation for label/category params."""
+
+    def test_single_quote_in_label_raises(self):
+        """Label with single quote should raise ValidationError."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().involving_label("Binance'; DROP TABLE--")
+        with pytest.raises(ValidationError, match="unsafe characters"):
+            query._build_params()
+
+    def test_backslash_in_label_raises(self):
+        """Label with backslash should raise ValidationError."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().sender_label("Binance\\x00")
+        with pytest.raises(ValidationError, match="unsafe characters"):
+            query._build_params()
+
+    def test_single_quote_in_category_raises(self):
+        """Category with single quote should raise ValidationError."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().receiver_category("CEX'")
+        with pytest.raises(ValidationError, match="unsafe characters"):
+            query._build_params()
+
+    def test_backslash_in_category_raises(self):
+        """Category with backslash should raise ValidationError."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().involving_category("CEX\\")
+        with pytest.raises(ValidationError, match="unsafe characters"):
+            query._build_params()
+
+    def test_clean_label_passes(self):
+        """Clean label values should pass validation."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().involving_label("Binance 14")
+        params = query._build_params()
+        assert params["involving_label"] == "Binance 14"
+
+    def test_address_params_not_checked(self):
+        """Address params (sender, receiver) should not be SQL-checked."""
+        client = DeFiStream(api_key="dsk_test")
+        # Addresses can contain any characters — only label/category is checked
+        query = client.erc20.transfers().sender("0x'abc")
+        params = query._build_params()
+        assert params["sender"] == "0x'abc"
+
+
+class TestAsyncLabelCategoryMethods:
+    """Test label/category methods on AsyncQueryBuilder."""
+
+    def test_async_involving_label(self):
+        """Async involving_label should set param."""
+        client = AsyncDeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().involving_label("Binance")
+        assert isinstance(query, AsyncQueryBuilder)
+        assert query._params["involving_label"] == "Binance"
+
+    def test_async_sender_multi_value(self):
+        """Async sender with multiple args should join."""
+        client = AsyncDeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().sender("0xA", "0xB")
+        assert query._params["sender"] == "0xA,0xB"
+
+    def test_async_mutual_exclusivity(self):
+        """Async builder should enforce mutual exclusivity."""
+        client = AsyncDeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().involving("0xA").sender("0xB")
+        with pytest.raises(ValidationError, match="Cannot combine"):
+            query._build_params()
+
+    def test_async_sql_safety(self):
+        """Async builder should enforce SQL safety."""
+        client = AsyncDeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().sender_label("test'injection")
+        with pytest.raises(ValidationError, match="unsafe characters"):
+            query._build_params()
+
+    def test_async_label_chaining(self):
+        """Async label methods should chain correctly."""
+        client = AsyncDeFiStream(api_key="dsk_test")
+        query = (
+            client.erc20.transfers("USDT")
+            .network("ETH")
+            .sender_label("Binance", "Coinbase")
+            .receiver_category("DEX")
+        )
+        assert query._params["sender_label"] == "Binance,Coinbase"
+        assert query._params["receiver_category"] == "DEX"