defistream 1.0.0__tar.gz → 1.0.2__tar.gz

{defistream-1.0.0 → defistream-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: defistream
-Version: 1.0.0
+Version: 1.0.2
 Summary: Python client for the DeFiStream API
 Project-URL: Homepage, https://defistream.dev
 Project-URL: Documentation, https://docs.defistream.dev
@@ -34,7 +34,11 @@ Description-Content-Type: text/markdown
 
 # DeFiStream Python Client
 
-Official Python client for the [DeFiStream API](https://defistream.dev) - access historical DeFi events from 45+ EVM networks.
+Official Python client for the [DeFiStream API](https://defistream.dev).
+
+## Getting an API Key
+
+To use the DeFiStream API, you need to sign up for an account at [defistream.dev](https://defistream.dev) to obtain your API key.
 
 ## Installation
 
@@ -61,44 +65,41 @@ client = DeFiStream()
 client = DeFiStream(api_key="dsk_your_api_key")
 
 # Query ERC20 transfers using builder pattern
-transfers = (
+df = (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
-    .as_dict()
+    .block_range(21000000, 21010000)
+    .as_df()
 )
 
-for transfer in transfers:
-    print(f"{transfer['sender']} -> {transfer['receiver']}: {transfer['amount']}")
+print(df.head())
 ```
 
 ## Features
 
 - **Builder pattern**: Fluent query API with chainable methods
 - **Type-safe**: Full type hints and Pydantic models
-- **Multiple formats**: JSON, CSV, Parquet, pandas DataFrame, polars DataFrame
+- **Multiple formats**: DataFrame (pandas/polars), CSV, Parquet, JSON
 - **Async support**: Native async/await with `AsyncDeFiStream`
-- **All protocols**: AAVE, Uniswap, Lido, ERC20, Native tokens, and more
-- **Verbose mode**: Include all metadata fields (tx_hash, tx_id, log_index, network, name)
+- **All protocols**: ERC20, AAVE, Uniswap, Lido, Stader, Threshold, Native tokens
 
 ## Supported Protocols
 
 | Protocol | Events |
 |----------|--------|
-| ERC20 | `transfers`, `approvals` |
+| ERC20 | `transfers` |
 | Native Token | `transfers` |
-| AAVE V3 | `deposits`, `withdrawals`, `borrows`, `repays`, `liquidations` |
-| Uniswap V3 | `swaps`, `mints`, `burns` |
-| Lido | `deposits`, `withdrawals` |
-| Stader | `deposits`, `withdrawals` |
-| Threshold | `mints`, `burns` |
+| AAVE V3 | `deposits`, `withdrawals`, `borrows`, `repays`, `flashloans`, `liquidations` |
+| Uniswap V3 | `swaps`, `deposits`, `withdrawals`, `collects` |
+| Lido | `deposits`, `withdrawal_requests`, `withdrawals_claimed`, `l2_deposits`, `l2_withdrawal_requests` |
+| Stader | `deposits`, `withdrawal_requests`, `withdrawals` |
+| Threshold | `deposit_requests`, `deposits`, `withdrawal_requests`, `withdrawals` |
 
 ## Usage Examples
 
 ### Builder Pattern
 
-The client uses a fluent builder pattern. The query is only executed when you call a terminal method like `as_dict()`, `as_df()`, or `as_file()`.
+The client uses a fluent builder pattern. The query is only executed when you call a terminal method like `as_df()`, `as_file()`, or `as_dict()`.
 
 ```python
 from defistream import DeFiStream
@@ -108,21 +109,19 @@ client = DeFiStream()
 # Build query step by step
 query = client.erc20.transfers("USDT")
 query = query.network("ETH")
-query = query.start_block(24000000)
-query = query.end_block(24100000)
+query = query.block_range(21000000, 21010000)
 query = query.min_amount(1000)
 
-# Execute and get results
-transfers = query.as_dict()
+# Execute and get DataFrame
+df = query.as_df()
 
 # Or chain everything
-transfers = (
+df = (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
+    .block_range(21000000, 21010000)
     .min_amount(1000)
-    .as_dict()
+    .as_df()
 )
 ```
 
@@ -130,35 +129,21 @@ transfers = (
 
 ```python
 # Get USDT transfers over 10,000 USDT
-transfers = (
+df = (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
+    .block_range(21000000, 21010000)
     .min_amount(10000)
-    .as_dict()
+    .as_df()
 )
 
 # Filter by sender
-transfers = (
+df = (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
+    .block_range(21000000, 21010000)
     .sender("0x28c6c06298d514db089934071355e5743bf21d60")
-    .as_dict()
-)
-
-# Or use aliases: from_address/to_address
-transfers = (
-    client.erc20.transfers()
-    .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
-    .token("USDC")
-    .from_address("0x...")
-    .to_address("0x...")
-    .as_dict()
+    .as_df()
 )
 ```
 
@@ -166,22 +151,20 @@ transfers = (
 
 ```python
 # Get deposits
-deposits = (
+df = (
     client.aave.deposits()
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
-    .as_dict()
+    .block_range(21000000, 21010000)
+    .as_df()
 )
 
-# Get liquidations for a specific user
-liquidations = (
-    client.aave.liquidations()
+# Use a specific market type on ETH (Core, Prime, or EtherFi)
+df = (
+    client.aave.deposits()
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
-    .user("0x...")
-    .as_dict()
+    .block_range(21000000, 21010000)
+    .eth_market_type("Prime")
+    .as_df()
 )
 ```
 
@@ -189,24 +172,22 @@ liquidations = (
 
 ```python
 # Get swaps for WETH/USDC pool with 0.05% fee tier
-swaps = (
+df = (
     client.uniswap.swaps("WETH", "USDC", 500)
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
-    .as_dict()
+    .block_range(21000000, 21010000)
+    .as_df()
 )
 
 # Or build with chain methods
-swaps = (
+df = (
     client.uniswap.swaps()
     .symbol0("WETH")
     .symbol1("USDC")
     .fee(500)
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
-    .as_dict()
+    .block_range(21000000, 21010000)
+    .as_df()
 )
 ```
 
@@ -214,13 +195,12 @@ swaps = (
 
 ```python
 # Get ETH transfers >= 1 ETH
-transfers = (
+df = (
     client.native_token.transfers()
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
+    .block_range(21000000, 21010000)
     .min_amount(1.0)
-    .as_dict()
+    .as_df()
 )
 ```
 
@@ -230,25 +210,21 @@ By default, responses omit metadata fields to reduce payload size. Use `.verbose
 
 ```python
 # Default: compact response (no tx_hash, tx_id, log_index, network, name)
-transfers = (
+df = (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
-    .as_dict()
+    .block_range(21000000, 21010000)
+    .as_df()
 )
-# Returns: [{"block_number": 24000050, "sender": "0x...", "receiver": "0x...", "amount": 1000.0, ...}]
 
 # Verbose: includes all metadata fields
-transfers = (
+df = (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
+    .block_range(21000000, 21010000)
     .verbose()
-    .as_dict()
+    .as_df()
 )
-# Returns: [{"name": "TransferEvent", "network": "ETH", "tx_id": "0x...", "tx_hash": "0x...", "log_index": 5, "block_number": 24000050, ...}]
 ```
 
 ### Return as DataFrame
@@ -258,8 +234,7 @@ transfers = (
 df = (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
+    .block_range(21000000, 21010000)
     .as_df()
 )
 
@@ -267,8 +242,7 @@ df = (
 df = (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
+    .block_range(21000000, 21010000)
     .as_df("polars")
 )
 ```
@@ -278,43 +252,49 @@ df = (
 Format is automatically determined by file extension:
 
 ```python
-# Save as CSV
+# Save as Parquet (recommended for large datasets)
 (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
-    .as_file("transfers.csv")
+    .block_range(21000000, 21100000)
+    .as_file("transfers.parquet")
 )
 
-# Save as Parquet
+# Save as CSV
 (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
-    .as_file("transfers.parquet")
+    .block_range(21000000, 21100000)
+    .as_file("transfers.csv")
 )
 
 # Save as JSON
 (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
+    .block_range(21000000, 21010000)
     .as_file("transfers.json")
 )
+```
 
-# Explicit format (when path has no extension)
-(
+### Return as Dictionary (JSON)
+
+For small queries, you can get results as a list of dictionaries:
+
+```python
+transfers = (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
-    .as_file("transfers", format="csv")
+    .block_range(21000000, 21010000)
+    .as_dict()
 )
+
+for transfer in transfers:
+    print(f"{transfer['sender']} -> {transfer['receiver']}: {transfer['amount']}")
 ```
 
+> **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.
+
 ### Async Usage
 
 ```python
@@ -323,41 +303,17 @@ from defistream import AsyncDeFiStream
 
 async def main():
     async with AsyncDeFiStream() as client:
-        transfers = await (
+        df = await (
             client.erc20.transfers("USDT")
             .network("ETH")
-            .start_block(24000000)
-            .end_block(24100000)
-            .as_dict()
+            .block_range(21000000, 21010000)
+            .as_df()
         )
-        print(f"Found {len(transfers)} transfers")
+        print(f"Found {len(df)} transfers")
 
 asyncio.run(main())
 ```
 
-### Multiple Networks in Parallel
-
-```python
-import asyncio
-from defistream import AsyncDeFiStream
-
-async def fetch_all_networks():
-    async with AsyncDeFiStream() as client:
-        networks = ["ETH", "ARB", "BASE", "OP"]
-        tasks = [
-            client.erc20.transfers("USDC")
-            .network(net)
-            .start_block(24000000)
-            .end_block(24100000)
-            .as_dict()
-            for net in networks
-        ]
-        results = await asyncio.gather(*tasks)
-        return dict(zip(networks, results))
-
-all_transfers = asyncio.run(fetch_all_networks())
-```
-
 ## Configuration
 
 ### Environment Variables
@@ -402,12 +358,11 @@ from defistream.exceptions import (
 client = DeFiStream()
 
 try:
-    transfers = (
+    df = (
         client.erc20.transfers("USDT")
         .network("ETH")
-        .start_block(24000000)
-        .end_block(24100000)
-        .as_dict()
+        .block_range(21000000, 21010000)
+        .as_df()
     )
 except AuthenticationError:
     print("Invalid API key")
@@ -426,12 +381,11 @@ except DeFiStreamError as e:
 Access rate limit and quota information:
 
 ```python
-transfers = (
+df = (
     client.erc20.transfers("USDT")
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
-    .as_dict()
+    .block_range(21000000, 21010000)
+    .as_df()
 )
 
 # Access response metadata
@@ -446,7 +400,7 @@ print(f"Request cost: {client.last_response.request_cost}")
 
 | Method | Description |
 |--------|-------------|
-| `.network(net)` | Set network (ETH, ARB, BASE, OP, etc.) |
+| `.network(net)` | Set network (ETH, ARB, BASE, OP, POLYGON, etc.) |
 | `.start_block(n)` | Set starting block number |
 | `.end_block(n)` | Set ending block number |
 | `.block_range(start, end)` | Set both start and end blocks |
@@ -455,35 +409,30 @@ print(f"Request cost: {client.last_response.request_cost}")
 | `.time_range(start, end)` | Set both start and end times |
 | `.verbose()` | Include all metadata fields |
 
-### Filter Methods
+### Protocol-Specific Parameters
 
 | Method | Protocols | Description |
 |--------|-----------|-------------|
+| `.token(symbol)` | ERC20 | Token symbol (USDT, USDC) or contract address |
+| `.decimals(n)` | ERC20 | Token decimals when using custom address (default: 18) |
 | `.sender(addr)` | ERC20, Native | Filter by sender address |
 | `.receiver(addr)` | ERC20, Native | Filter by receiver address |
-| `.from_address(addr)` | ERC20, Native | Alias for sender |
-| `.to_address(addr)` | ERC20, Native | Alias for receiver |
 | `.min_amount(amt)` | ERC20, Native | Minimum transfer amount |
-| `.token(symbol)` | ERC20 | Token symbol (USDT, USDC, etc.) |
-| `.owner(addr)` | ERC20 Approvals, Lido | Filter by owner |
-| `.spender(addr)` | ERC20 Approvals | Filter by spender |
-| `.user(addr)` | AAVE | Filter by user |
-| `.reserve(addr)` | AAVE | Filter by reserve |
-| `.liquidator(addr)` | AAVE Liquidations | Filter by liquidator |
-| `.symbol0(sym)` | Uniswap | First token symbol |
-| `.symbol1(sym)` | Uniswap | Second token symbol |
-| `.fee(tier)` | Uniswap | Fee tier (100, 500, 3000, 10000) |
-| `.pool(addr)` | Uniswap | Pool address |
+| `.max_amount(amt)` | ERC20, Native | Maximum transfer amount |
+| `.eth_market_type(type)` | AAVE | Market type for ETH: 'Core', 'Prime', 'EtherFi' |
+| `.symbol0(sym)` | Uniswap | First token symbol (required) |
+| `.symbol1(sym)` | Uniswap | Second token symbol (required) |
+| `.fee(tier)` | Uniswap | Fee tier: 100, 500, 3000, 10000 (required) |
 
 ### Terminal Methods
 
 | Method | Description |
 |--------|-------------|
-| `.as_dict()` | Execute and return list of dicts (JSON) |
 | `.as_df()` | Execute and return pandas DataFrame |
 | `.as_df("polars")` | Execute and return polars DataFrame |
 | `.as_file(path)` | Execute and save to file (format from extension) |
 | `.as_file(path, format="csv")` | Execute and save with explicit format |
+| `.as_dict()` | Execute and return list of dicts (JSON, 10K block limit) |
 
 ## License