defistream 1.2.0__tar.gz → 1.3.0__tar.gz

{defistream-1.2.0 → defistream-1.3.0}/.claude/settings.local.json

@@ -17,7 +17,18 @@
       "Bash(git push:*)",
       "Bash(git subtree push:*)",
       "Bash(.venv/bin/python -m pytest:*)",
-      "Bash(.venv/bin/python:*)"
+      "Bash(.venv/bin/python:*)",
+      "Bash(git status:*)",
+      "Bash(grep:*)",
+      "Bash(git commit -m \"$\\(cat <<''EOF''\nAccept case-insensitive network names in events server\n\nNormalize the network query parameter to uppercase at the entry point\nin both _fetch_events_dataframe and _handle_parquet_request so that\neth, Eth, and ETH are all accepted. Add tests for core and API gateway.\nUpdate API docs to note case-insensitivity.\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(git commit:*)",
+      "Bash(curl:*)",
+      "Bash(tree:*)",
+      "Bash(python -m build:*)"
     ]
-  }
+  },
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": [
+    "defistream"
+  ]
 }

{defistream-1.2.0 → defistream-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: defistream
-Version: 1.2.0
+Version: 1.3.0
 Summary: Python client for the DeFiStream API
 Project-URL: Homepage, https://defistream.dev
 Project-URL: Documentation, https://docs.defistream.dev
@@ -78,6 +78,7 @@ print(df.head())
 ## Features
 
 - **Builder pattern**: Fluent query API with chainable methods
+- **Aggregate queries**: Bucket events into time or block intervals with summary statistics
 - **Type-safe**: Full type hints and Pydantic models
 - **Multiple formats**: DataFrame (pandas/polars), CSV, Parquet, JSON
 - **Async support**: Native async/await with `AsyncDeFiStream`
@@ -137,6 +138,23 @@ df = (
     .as_df()
 )
 
+# Query multiple tokens at once (known symbols only, not contract addresses)
+df = (
+    client.erc20.transfers("USDT", "USDC", "DAI")
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .as_df()
+)
+
+# Or set multiple tokens via chain method
+df = (
+    client.erc20.transfers()
+    .token("USDT", "USDC")
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .as_df()
+)
+
 # Filter by sender
 df = (
     client.erc20.transfers("USDT")
@@ -245,6 +263,57 @@ df = (
 )
 ```
 
+### Aggregate Queries
+
+Use `.aggregate()` to bucket raw events into time or block intervals with summary statistics. All existing filters work before `.aggregate()` is called.
+
+```python
+# Aggregate USDT transfers into 2-hour buckets
+df = (
+    client.erc20.transfers("USDT")
+    .network("ETH")
+    .block_range(21000000, 21100000)
+    .aggregate(group_by="time", period="2h")
+    .as_df()
+)
+
+# Aggregate by block intervals
+df = (
+    client.erc20.transfers("USDT")
+    .network("ETH")
+    .block_range(21000000, 21100000)
+    .aggregate(group_by="block", period="100b")
+    .as_df()
+)
+
+# Combine with filters — large transfers from exchanges, bucketed hourly
+df = (
+    client.erc20.transfers("USDT")
+    .network("ETH")
+    .block_range(21000000, 21100000)
+    .sender_category("exchange")
+    .min_amount(10000)
+    .aggregate(group_by="time", period="1h")
+    .as_df()
+)
+
+# Aggregate Uniswap swaps
+df = (
+    client.uniswap.swaps("WETH", "USDC", 500)
+    .network("ETH")
+    .block_range(21000000, 21100000)
+    .aggregate(group_by="time", period="1h")
+    .as_df()
+)
+```
+
+You can also discover what aggregate fields are available for a protocol:
+
+```python
+schema = client.aggregate_schema("erc20")
+print(schema)
+```
+
 ### Verbose Mode
 
 By default, responses omit metadata fields to reduce payload size. Use `.verbose()` to include all fields:
@@ -477,7 +546,7 @@ print(f"Request cost: {client.last_response.request_cost}")
 
 | Method | Protocols | Description |
 |--------|-----------|-------------|
-| `.token(symbol)` | ERC20 | Token symbol (USDT, USDC) or contract address (required) |
+| `.token(*symbols)` | ERC20 | Token symbol(s) (USDT, USDC) or contract address. Accepts multiple known symbols for multi-token queries (multi-value). |
 | `.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) |
@@ -507,6 +576,13 @@ Filter events by entity names or categories using the labels database. Available
 
 **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.
 
+### Aggregate Methods
+
+| Method | Description |
+|--------|-------------|
+| `.aggregate(group_by, period)` | Transition to aggregate query. `group_by`: `"time"` or `"block"`. `period`: bucket size (e.g. `"1h"`, `"100b"`). Returns an `AggregateQueryBuilder` that supports all the same terminal and filter methods. |
+| `client.aggregate_schema(protocol)` | Get available aggregate fields for a protocol (e.g. `"erc20"`, `"aave"`). |
+
 ### Terminal Methods
 
 | Method | Description |

{defistream-1.2.0 → defistream-1.3.0}/README.md

@@ -44,6 +44,7 @@ print(df.head())
 ## Features
 
 - **Builder pattern**: Fluent query API with chainable methods
+- **Aggregate queries**: Bucket events into time or block intervals with summary statistics
 - **Type-safe**: Full type hints and Pydantic models
 - **Multiple formats**: DataFrame (pandas/polars), CSV, Parquet, JSON
 - **Async support**: Native async/await with `AsyncDeFiStream`
@@ -103,6 +104,23 @@ df = (
     .as_df()
 )
 
+# Query multiple tokens at once (known symbols only, not contract addresses)
+df = (
+    client.erc20.transfers("USDT", "USDC", "DAI")
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .as_df()
+)
+
+# Or set multiple tokens via chain method
+df = (
+    client.erc20.transfers()
+    .token("USDT", "USDC")
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .as_df()
+)
+
 # Filter by sender
 df = (
     client.erc20.transfers("USDT")
@@ -211,6 +229,57 @@ df = (
 )
 ```
 
+### Aggregate Queries
+
+Use `.aggregate()` to bucket raw events into time or block intervals with summary statistics. All existing filters work before `.aggregate()` is called.
+
+```python
+# Aggregate USDT transfers into 2-hour buckets
+df = (
+    client.erc20.transfers("USDT")
+    .network("ETH")
+    .block_range(21000000, 21100000)
+    .aggregate(group_by="time", period="2h")
+    .as_df()
+)
+
+# Aggregate by block intervals
+df = (
+    client.erc20.transfers("USDT")
+    .network("ETH")
+    .block_range(21000000, 21100000)
+    .aggregate(group_by="block", period="100b")
+    .as_df()
+)
+
+# Combine with filters — large transfers from exchanges, bucketed hourly
+df = (
+    client.erc20.transfers("USDT")
+    .network("ETH")
+    .block_range(21000000, 21100000)
+    .sender_category("exchange")
+    .min_amount(10000)
+    .aggregate(group_by="time", period="1h")
+    .as_df()
+)
+
+# Aggregate Uniswap swaps
+df = (
+    client.uniswap.swaps("WETH", "USDC", 500)
+    .network("ETH")
+    .block_range(21000000, 21100000)
+    .aggregate(group_by="time", period="1h")
+    .as_df()
+)
+```
+
+You can also discover what aggregate fields are available for a protocol:
+
+```python
+schema = client.aggregate_schema("erc20")
+print(schema)
+```
+
 ### Verbose Mode
 
 By default, responses omit metadata fields to reduce payload size. Use `.verbose()` to include all fields:
@@ -443,7 +512,7 @@ print(f"Request cost: {client.last_response.request_cost}")
 
 | Method | Protocols | Description |
 |--------|-----------|-------------|
-| `.token(symbol)` | ERC20 | Token symbol (USDT, USDC) or contract address (required) |
+| `.token(*symbols)` | ERC20 | Token symbol(s) (USDT, USDC) or contract address. Accepts multiple known symbols for multi-token queries (multi-value). |
 | `.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) |
@@ -473,6 +542,13 @@ Filter events by entity names or categories using the labels database. Available
 
 **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.
 
+### Aggregate Methods
+
+| Method | Description |
+|--------|-------------|
+| `.aggregate(group_by, period)` | Transition to aggregate query. `group_by`: `"time"` or `"block"`. `period`: bucket size (e.g. `"1h"`, `"100b"`). Returns an `AggregateQueryBuilder` that supports all the same terminal and filter methods. |
+| `client.aggregate_schema(protocol)` | Get available aggregate fields for a protocol (e.g. `"erc20"`, `"aave"`). |
+
 ### Terminal Methods
 
 | Method | Description |

{defistream-1.2.0 → defistream-1.3.0}/pyproject.toml

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

{defistream-1.2.0 → defistream-1.3.0}/src/defistream/__init__.py

@@ -36,7 +36,7 @@ from .query import (
     QueryBuilder,
 )
 
-__version__ = "1.2.0"
+__version__ = "1.3.0"
 
 __all__ = [
     # Clients

{defistream-1.2.0 → defistream-1.3.0}/src/defistream/protocols.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
 
-from .query import QueryBuilder, AsyncQueryBuilder
+from .query import QueryBuilder, AsyncQueryBuilder, _normalize_multi
 
 if TYPE_CHECKING:
     from .client import BaseClient
@@ -16,25 +16,37 @@ class ERC20Protocol:
     def __init__(self, client: "BaseClient"):
         self._client = client
 
-    def transfers(self, token: str | None = None) -> QueryBuilder:
+    def transfers(self, *tokens: str) -> QueryBuilder:
         """
         Start a query for ERC20 transfer events.
 
         Args:
-            token: Token symbol (USDT, USDC, WETH, etc.) or contract address
+            *tokens: One or more token symbols (USDT, USDC, DAI, etc.) or a
+                single contract address. Multiple tokens are joined as
+                comma-separated symbols (multi-token queries only support
+                known symbol names, not contract addresses).
 
         Returns:
             QueryBuilder for chaining filters
 
         Example:
+            # Single token
             df = (
                 client.erc20.transfers("USDT")
                 .network("ETH")
                 .block_range(21000000, 21010000)
                 .as_df()
             )
+
+            # Multiple tokens
+            df = (
+                client.erc20.transfers("USDT", "USDC", "DAI")
+                .network("ETH")
+                .block_range(21000000, 21010000)
+                .as_df()
+            )
         """
-        params = {"token": token} if token else {}
+        params = {"token": _normalize_multi(*tokens)} if tokens else {}
         return QueryBuilder(self._client, "/erc20/events/transfer", params)
 
 
@@ -261,9 +273,16 @@ class AsyncERC20Protocol:
     def __init__(self, client: "BaseClient"):
         self._client = client
 
-    def transfers(self, token: str | None = None) -> AsyncQueryBuilder:
-        """Start a query for ERC20 transfer events."""
-        params = {"token": token} if token else {}
+    def transfers(self, *tokens: str) -> AsyncQueryBuilder:
+        """Start a query for ERC20 transfer events.
+
+        Args:
+            *tokens: One or more token symbols (USDT, USDC, DAI, etc.) or a
+                single contract address. Multiple tokens are joined as
+                comma-separated symbols (multi-token queries only support
+                known symbol names, not contract addresses).
+        """
+        params = {"token": _normalize_multi(*tokens)} if tokens else {}
         return AsyncQueryBuilder(self._client, "/erc20/events/transfer", params)
 
 

{defistream-1.2.0 → defistream-1.3.0}/src/defistream/query.py

@@ -205,9 +205,9 @@ class QueryBuilder:
         return self._copy_with(max_amount=amount)
 
     # ERC20 specific
-    def token(self, symbol: str) -> "QueryBuilder":
-        """Set token symbol or address (ERC20)."""
-        return self._copy_with(token=symbol)
+    def token(self, *symbols: str) -> "QueryBuilder":
+        """Set token symbol(s) or address (ERC20). Accepts multiple known symbols for multi-token queries."""
+        return self._copy_with(token=_normalize_multi(*symbols))
 
     # AAVE specific
     def eth_market_type(self, market_type: str) -> "QueryBuilder":
@@ -545,9 +545,9 @@ class AsyncQueryBuilder:
         return self._copy_with(max_amount=amount)
 
     # ERC20 specific
-    def token(self, symbol: str) -> "AsyncQueryBuilder":
-        """Set token symbol or address (ERC20)."""
-        return self._copy_with(token=symbol)
+    def token(self, *symbols: str) -> "AsyncQueryBuilder":
+        """Set token symbol(s) or address (ERC20). Accepts multiple known symbols for multi-token queries."""
+        return self._copy_with(token=_normalize_multi(*symbols))
 
     # AAVE specific
     def eth_market_type(self, market_type: str) -> "AsyncQueryBuilder":

{defistream-1.2.0 → defistream-1.3.0}/tests/test_client.py

@@ -253,6 +253,96 @@ class TestBuilderPattern:
         assert query._params["since"] == "2024-01-01"
         assert query._params["until"] == "2024-01-31"
 
+class TestMultiTokenSupport:
+    """Test multi-token support for ERC20 transfers."""
+
+    def test_transfers_single_token(self):
+        """transfers('USDT') should set token param."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers("USDT")
+        assert query._params["token"] == "USDT"
+
+    def test_transfers_multiple_tokens(self):
+        """transfers('USDT', 'USDC', 'DAI') should join with comma."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers("USDT", "USDC", "DAI")
+        assert query._params["token"] == "USDT,USDC,DAI"
+
+    def test_transfers_two_tokens(self):
+        """transfers('USDT', 'USDC') should join with comma."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers("USDT", "USDC")
+        assert query._params["token"] == "USDT,USDC"
+
+    def test_transfers_no_token(self):
+        """transfers() with no args should have no token param."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers()
+        assert "token" not in query._params
+
+    def test_transfers_pre_joined_string(self):
+        """transfers('USDT,USDC') with pre-joined string should pass through."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers("USDT,USDC")
+        assert query._params["token"] == "USDT,USDC"
+
+    def test_token_chain_multiple(self):
+        """.token('USDT', 'USDC') should join with comma."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().token("USDT", "USDC")
+        assert query._params["token"] == "USDT,USDC"
+
+    def test_token_chain_single(self):
+        """.token('USDT') should set single token."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().token("USDT")
+        assert query._params["token"] == "USDT"
+
+    def test_token_chain_no_args_raises(self):
+        """.token() 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().token()
+
+    def test_multi_token_with_chaining(self):
+        """Multi-token should work with other builder methods."""
+        client = DeFiStream(api_key="dsk_test")
+        query = (
+            client.erc20.transfers("USDT", "USDC", "DAI")
+            .network("ETH")
+            .block_range(21000000, 21010000)
+        )
+        assert query._params["token"] == "USDT,USDC,DAI"
+        assert query._params["network"] == "ETH"
+        assert query._params["block_start"] == 21000000
+
+    def test_async_transfers_multiple_tokens(self):
+        """Async transfers should support multi-token."""
+        client = AsyncDeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers("USDT", "USDC")
+        assert isinstance(query, AsyncQueryBuilder)
+        assert query._params["token"] == "USDT,USDC"
+
+    def test_async_token_chain_multiple(self):
+        """Async .token() should support multi-token."""
+        client = AsyncDeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers().token("USDT", "USDC", "DAI")
+        assert query._params["token"] == "USDT,USDC,DAI"
+
+    def test_contract_address_still_works(self):
+        """Single contract address should still work."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers("0xdAC17F958D2ee523a2206206994597C13D831ec7")
+        assert query._params["token"] == "0xdAC17F958D2ee523a2206206994597C13D831ec7"
+
+    def test_multi_token_aggregate(self):
+        """Multi-token should carry through to aggregate queries."""
+        client = DeFiStream(api_key="dsk_test")
+        query = client.erc20.transfers("USDT", "USDC").network("ETH").aggregate()
+        assert query._params["token"] == "USDT,USDC"
+        assert isinstance(query, AggregateQueryBuilder)
+
+
 class TestAsyncBuilderPattern:
     """Test async builder pattern."""