defistream 1.2.0__tar.gz → 1.2.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: defistream
-Version: 1.2.0
+Version: 1.2.1
 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`
@@ -245,6 +246,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:
@@ -507,6 +559,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.2.1}/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`
@@ -211,6 +212,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:
@@ -473,6 +525,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.2.1}/pyproject.toml

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

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

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