defistream 1.0.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

defistream/__init__.py

@@ -1,19 +1,22 @@
 """
 DeFiStream Python Client
 
-Official Python client for the DeFiStream API - access historical
-DeFi events from 45+ EVM networks.
+Official Python client for the DeFiStream API.
 
 Example:
     >>> from defistream import DeFiStream
     >>> client = DeFiStream(api_key="dsk_...")
     >>>
-    >>> # Builder pattern
-    >>> query = client.erc20.transfers("USDT").network("ETH").start_block(24000000).end_block(24100000)
-    >>> transfers = query.as_dict()
+    >>> # Builder pattern - returns pandas DataFrame
+    >>> df = (
+    ...     client.erc20.transfers("USDT")
+    ...     .network("ETH")
+    ...     .block_range(21000000, 21010000)
+    ...     .as_df()
+    ... )
     >>>
     >>> # Save to file
-    >>> query.to_csv_file("transfers.csv")
+    >>> query.as_file("transfers.parquet")
 """
 
 from .client import AsyncDeFiStream, DeFiStream
@@ -32,20 +35,17 @@ from .models import (
     AAVELiquidationEvent,
     AAVERepayEvent,
     AAVEWithdrawEvent,
-    ERC20ApprovalEvent,
     ERC20TransferEvent,
     EventBase,
     LidoDepositEvent,
     LidoWithdrawEvent,
     NativeTransferEvent,
     ResponseMetadata,
-    UniswapBurnEvent,
-    UniswapMintEvent,
     UniswapSwapEvent,
 )
 from .query import AsyncQueryBuilder, QueryBuilder
 
-__version__ = "0.1.0"
+__version__ = "1.0.1"
 
 __all__ = [
     # Clients
@@ -66,7 +66,6 @@ __all__ = [
     "EventBase",
     "ResponseMetadata",
     "ERC20TransferEvent",
-    "ERC20ApprovalEvent",
     "NativeTransferEvent",
     "AAVEDepositEvent",
     "AAVEWithdrawEvent",
@@ -74,8 +73,6 @@ __all__ = [
     "AAVERepayEvent",
     "AAVELiquidationEvent",
     "UniswapSwapEvent",
-    "UniswapMintEvent",
-    "UniswapBurnEvent",
     "LidoDepositEvent",
     "LidoWithdrawEvent",
 ]

defistream/protocols.py

@@ -21,34 +21,25 @@ class ERC20Protocol:
         Start a query for ERC20 transfer events.
 
         Args:
-            token: Optional token symbol (USDT, USDC, WETH, etc.)
+            token: Token symbol (USDT, USDC, WETH, etc.) or contract address
 
         Returns:
             QueryBuilder for chaining filters
 
         Example:
-            query = client.erc20.transfers("USDT").network("ETH").start_block(24000000).end_block(24100000)
-            df = query.as_pandas()
+            df = (
+                client.erc20.transfers("USDT")
+                .network("ETH")
+                .block_range(21000000, 21010000)
+                .as_df()
+            )
         """
         params = {"token": token} if token else {}
         return QueryBuilder(self._client, "/erc20/events/transfer", params)
 
-    def approvals(self, token: str | None = None) -> QueryBuilder:
-        """
-        Start a query for ERC20 approval events.
-
-        Args:
-            token: Optional token symbol
-
-        Returns:
-            QueryBuilder for chaining filters
-        """
-        params = {"token": token} if token else {}
-        return QueryBuilder(self._client, "/erc20/events/approval", params)
-
 
 class NativeTokenProtocol:
-    """Native token (ETH, MATIC, BNB, etc.) events with builder pattern."""
+    """Native token (ETH, MATIC, etc.) events with builder pattern."""
 
     def __init__(self, client: "BaseClient"):
         self._client = client
@@ -61,8 +52,13 @@ class NativeTokenProtocol:
             QueryBuilder for chaining filters
 
         Example:
-            query = client.native_token.transfers().network("ETH").start_block(24000000).end_block(24100000)
-            transfers = query.min_amount(1.0).as_dict()
+            df = (
+                client.native_token.transfers()
+                .network("ETH")
+                .block_range(21000000, 21010000)
+                .min_amount(1.0)
+                .as_df()
+            )
         """
         return QueryBuilder(self._client, "/native_token/events/transfer")
 
@@ -89,6 +85,10 @@ class AAVEProtocol:
         """Start a query for AAVE repay events."""
         return QueryBuilder(self._client, "/aave/events/repay")
 
+    def flashloans(self) -> QueryBuilder:
+        """Start a query for AAVE flash loan events."""
+        return QueryBuilder(self._client, "/aave/events/flashloan")
+
     def liquidations(self) -> QueryBuilder:
         """Start a query for AAVE liquidation events."""
         return QueryBuilder(self._client, "/aave/events/liquidation")
@@ -110,16 +110,20 @@ class UniswapProtocol:
         Start a query for Uniswap V3 swap events.
 
         Args:
-            symbol0: Optional first token symbol (e.g., WETH)
-            symbol1: Optional second token symbol (e.g., USDC)
-            fee: Optional fee tier (100, 500, 3000, 10000)
+            symbol0: First token symbol (e.g., WETH)
+            symbol1: Second token symbol (e.g., USDC)
+            fee: Fee tier (100, 500, 3000, 10000)
 
         Returns:
             QueryBuilder for chaining filters
 
         Example:
-            query = client.uniswap.swaps("WETH", "USDC", 500).network("ETH").start_block(24000000).end_block(24100000)
-            df = query.as_pandas()
+            df = (
+                client.uniswap.swaps("WETH", "USDC", 500)
+                .network("ETH")
+                .block_range(21000000, 21010000)
+                .as_df()
+            )
         """
         params: dict[str, Any] = {}
         if symbol0:
@@ -130,13 +134,13 @@ class UniswapProtocol:
             params["fee"] = fee
         return QueryBuilder(self._client, "/uniswap/events/swap", params)
 
-    def mints(
+    def deposits(
         self,
         symbol0: str | None = None,
         symbol1: str | None = None,
         fee: int | None = None,
     ) -> QueryBuilder:
-        """Start a query for Uniswap V3 mint (add liquidity) events."""
+        """Start a query for Uniswap V3 deposit (add liquidity) events."""
         params: dict[str, Any] = {}
         if symbol0:
             params["symbol0"] = symbol0
@@ -144,15 +148,15 @@ class UniswapProtocol:
             params["symbol1"] = symbol1
         if fee:
             params["fee"] = fee
-        return QueryBuilder(self._client, "/uniswap/events/mint", params)
+        return QueryBuilder(self._client, "/uniswap/events/deposit", params)
 
-    def burns(
+    def withdrawals(
         self,
         symbol0: str | None = None,
         symbol1: str | None = None,
         fee: int | None = None,
     ) -> QueryBuilder:
-        """Start a query for Uniswap V3 burn (remove liquidity) events."""
+        """Start a query for Uniswap V3 withdrawal (remove liquidity) events."""
         params: dict[str, Any] = {}
         if symbol0:
             params["symbol0"] = symbol0
@@ -160,7 +164,23 @@ class UniswapProtocol:
             params["symbol1"] = symbol1
         if fee:
             params["fee"] = fee
-        return QueryBuilder(self._client, "/uniswap/events/burn", params)
+        return QueryBuilder(self._client, "/uniswap/events/withdraw", params)
+
+    def collects(
+        self,
+        symbol0: str | None = None,
+        symbol1: str | None = None,
+        fee: int | None = None,
+    ) -> QueryBuilder:
+        """Start a query for Uniswap V3 collect (fee collection) events."""
+        params: dict[str, Any] = {}
+        if symbol0:
+            params["symbol0"] = symbol0
+        if symbol1:
+            params["symbol1"] = symbol1
+        if fee:
+            params["fee"] = fee
+        return QueryBuilder(self._client, "/uniswap/events/collect", params)
 
 
 class LidoProtocol:
@@ -169,17 +189,31 @@ class LidoProtocol:
     def __init__(self, client: "BaseClient"):
         self._client = client
 
+    # L1 ETH events
     def deposits(self) -> QueryBuilder:
-        """Start a query for Lido stETH deposit events."""
+        """Start a query for Lido stETH deposit events (ETH L1 only)."""
         return QueryBuilder(self._client, "/lido/events/deposit")
 
-    def withdrawals(self) -> QueryBuilder:
-        """Start a query for Lido withdrawal events."""
-        return QueryBuilder(self._client, "/lido/events/withdraw")
+    def withdrawal_requests(self) -> QueryBuilder:
+        """Start a query for Lido withdrawal request events (ETH L1 only)."""
+        return QueryBuilder(self._client, "/lido/events/withdrawal_request")
+
+    def withdrawals_claimed(self) -> QueryBuilder:
+        """Start a query for Lido claimed withdrawal events (ETH L1 only)."""
+        return QueryBuilder(self._client, "/lido/events/withdrawal_claimed")
+
+    # L2 events
+    def l2_deposits(self) -> QueryBuilder:
+        """Start a query for Lido L2 deposit events (L2 networks only)."""
+        return QueryBuilder(self._client, "/lido/events/l2_deposit")
+
+    def l2_withdrawal_requests(self) -> QueryBuilder:
+        """Start a query for Lido L2 withdrawal request events (L2 networks only)."""
+        return QueryBuilder(self._client, "/lido/events/l2_withdrawal_request")
 
 
 class StaderProtocol:
-    """Stader EthX staking events with builder pattern."""
+    """Stader ETHx staking events with builder pattern (ETH only)."""
 
     def __init__(self, client: "BaseClient"):
         self._client = client
@@ -188,24 +222,36 @@ class StaderProtocol:
         """Start a query for Stader deposit events."""
         return QueryBuilder(self._client, "/stader/events/deposit")
 
+    def withdrawal_requests(self) -> QueryBuilder:
+        """Start a query for Stader withdrawal request events."""
+        return QueryBuilder(self._client, "/stader/events/withdrawal_request")
+
     def withdrawals(self) -> QueryBuilder:
         """Start a query for Stader withdrawal events."""
-        return QueryBuilder(self._client, "/stader/events/withdraw")
+        return QueryBuilder(self._client, "/stader/events/withdrawal")
 
 
 class ThresholdProtocol:
-    """Threshold tBTC events with builder pattern."""
+    """Threshold tBTC events with builder pattern (ETH only)."""
 
     def __init__(self, client: "BaseClient"):
         self._client = client
 
-    def mints(self) -> QueryBuilder:
-        """Start a query for tBTC mint events."""
-        return QueryBuilder(self._client, "/threshold/events/mint")
+    def deposit_requests(self) -> QueryBuilder:
+        """Start a query for tBTC deposit request (reveal) events."""
+        return QueryBuilder(self._client, "/threshold/events/deposit_request")
 
-    def burns(self) -> QueryBuilder:
-        """Start a query for tBTC burn/redeem events."""
-        return QueryBuilder(self._client, "/threshold/events/burn")
+    def deposits(self) -> QueryBuilder:
+        """Start a query for tBTC deposit (mint) events."""
+        return QueryBuilder(self._client, "/threshold/events/deposit")
+
+    def withdrawal_requests(self) -> QueryBuilder:
+        """Start a query for tBTC withdrawal request events."""
+        return QueryBuilder(self._client, "/threshold/events/withdrawal_request")
+
+    def withdrawals(self) -> QueryBuilder:
+        """Start a query for tBTC withdrawal (unmint) events."""
+        return QueryBuilder(self._client, "/threshold/events/withdrawal")
 
 
 # Async protocol implementations
@@ -220,11 +266,6 @@ class AsyncERC20Protocol:
         params = {"token": token} if token else {}
         return AsyncQueryBuilder(self._client, "/erc20/events/transfer", params)
 
-    def approvals(self, token: str | None = None) -> AsyncQueryBuilder:
-        """Start a query for ERC20 approval events."""
-        params = {"token": token} if token else {}
-        return AsyncQueryBuilder(self._client, "/erc20/events/approval", params)
-
 
 class AsyncNativeTokenProtocol:
     """Async native token events with builder pattern."""
@@ -259,6 +300,10 @@ class AsyncAAVEProtocol:
         """Start a query for AAVE repay events."""
         return AsyncQueryBuilder(self._client, "/aave/events/repay")
 
+    def flashloans(self) -> AsyncQueryBuilder:
+        """Start a query for AAVE flash loan events."""
+        return AsyncQueryBuilder(self._client, "/aave/events/flashloan")
+
     def liquidations(self) -> AsyncQueryBuilder:
         """Start a query for AAVE liquidation events."""
         return AsyncQueryBuilder(self._client, "/aave/events/liquidation")
@@ -286,13 +331,29 @@ class AsyncUniswapProtocol:
             params["fee"] = fee
         return AsyncQueryBuilder(self._client, "/uniswap/events/swap", params)
 
-    def mints(
+    def deposits(
+        self,
+        symbol0: str | None = None,
+        symbol1: str | None = None,
+        fee: int | None = None,
+    ) -> AsyncQueryBuilder:
+        """Start a query for Uniswap V3 deposit events."""
+        params: dict[str, Any] = {}
+        if symbol0:
+            params["symbol0"] = symbol0
+        if symbol1:
+            params["symbol1"] = symbol1
+        if fee:
+            params["fee"] = fee
+        return AsyncQueryBuilder(self._client, "/uniswap/events/deposit", params)
+
+    def withdrawals(
         self,
         symbol0: str | None = None,
         symbol1: str | None = None,
         fee: int | None = None,
     ) -> AsyncQueryBuilder:
-        """Start a query for Uniswap V3 mint events."""
+        """Start a query for Uniswap V3 withdrawal events."""
         params: dict[str, Any] = {}
         if symbol0:
             params["symbol0"] = symbol0
@@ -300,15 +361,15 @@ class AsyncUniswapProtocol:
             params["symbol1"] = symbol1
         if fee:
             params["fee"] = fee
-        return AsyncQueryBuilder(self._client, "/uniswap/events/mint", params)
+        return AsyncQueryBuilder(self._client, "/uniswap/events/withdraw", params)
 
-    def burns(
+    def collects(
         self,
         symbol0: str | None = None,
         symbol1: str | None = None,
         fee: int | None = None,
     ) -> AsyncQueryBuilder:
-        """Start a query for Uniswap V3 burn events."""
+        """Start a query for Uniswap V3 collect events."""
         params: dict[str, Any] = {}
         if symbol0:
             params["symbol0"] = symbol0
@@ -316,7 +377,7 @@ class AsyncUniswapProtocol:
             params["symbol1"] = symbol1
         if fee:
             params["fee"] = fee
-        return AsyncQueryBuilder(self._client, "/uniswap/events/burn", params)
+        return AsyncQueryBuilder(self._client, "/uniswap/events/collect", params)
 
 
 class AsyncLidoProtocol:
@@ -326,12 +387,24 @@ class AsyncLidoProtocol:
         self._client = client
 
     def deposits(self) -> AsyncQueryBuilder:
-        """Start a query for Lido deposit events."""
+        """Start a query for Lido deposit events (ETH L1 only)."""
         return AsyncQueryBuilder(self._client, "/lido/events/deposit")
 
-    def withdrawals(self) -> AsyncQueryBuilder:
-        """Start a query for Lido withdrawal events."""
-        return AsyncQueryBuilder(self._client, "/lido/events/withdraw")
+    def withdrawal_requests(self) -> AsyncQueryBuilder:
+        """Start a query for Lido withdrawal request events (ETH L1 only)."""
+        return AsyncQueryBuilder(self._client, "/lido/events/withdrawal_request")
+
+    def withdrawals_claimed(self) -> AsyncQueryBuilder:
+        """Start a query for Lido claimed withdrawal events (ETH L1 only)."""
+        return AsyncQueryBuilder(self._client, "/lido/events/withdrawal_claimed")
+
+    def l2_deposits(self) -> AsyncQueryBuilder:
+        """Start a query for Lido L2 deposit events."""
+        return AsyncQueryBuilder(self._client, "/lido/events/l2_deposit")
+
+    def l2_withdrawal_requests(self) -> AsyncQueryBuilder:
+        """Start a query for Lido L2 withdrawal request events."""
+        return AsyncQueryBuilder(self._client, "/lido/events/l2_withdrawal_request")
 
 
 class AsyncStaderProtocol:
@@ -344,9 +417,13 @@ class AsyncStaderProtocol:
         """Start a query for Stader deposit events."""
         return AsyncQueryBuilder(self._client, "/stader/events/deposit")
 
+    def withdrawal_requests(self) -> AsyncQueryBuilder:
+        """Start a query for Stader withdrawal request events."""
+        return AsyncQueryBuilder(self._client, "/stader/events/withdrawal_request")
+
     def withdrawals(self) -> AsyncQueryBuilder:
         """Start a query for Stader withdrawal events."""
-        return AsyncQueryBuilder(self._client, "/stader/events/withdraw")
+        return AsyncQueryBuilder(self._client, "/stader/events/withdrawal")
 
 
 class AsyncThresholdProtocol:
@@ -355,10 +432,18 @@ class AsyncThresholdProtocol:
     def __init__(self, client: "BaseClient"):
         self._client = client
 
-    def mints(self) -> AsyncQueryBuilder:
-        """Start a query for tBTC mint events."""
-        return AsyncQueryBuilder(self._client, "/threshold/events/mint")
+    def deposit_requests(self) -> AsyncQueryBuilder:
+        """Start a query for tBTC deposit request events."""
+        return AsyncQueryBuilder(self._client, "/threshold/events/deposit_request")
 
-    def burns(self) -> AsyncQueryBuilder:
-        """Start a query for tBTC burn events."""
-        return AsyncQueryBuilder(self._client, "/threshold/events/burn")
+    def deposits(self) -> AsyncQueryBuilder:
+        """Start a query for tBTC deposit events."""
+        return AsyncQueryBuilder(self._client, "/threshold/events/deposit")
+
+    def withdrawal_requests(self) -> AsyncQueryBuilder:
+        """Start a query for tBTC withdrawal request events."""
+        return AsyncQueryBuilder(self._client, "/threshold/events/withdrawal_request")
+
+    def withdrawals(self) -> AsyncQueryBuilder:
+        """Start a query for tBTC withdrawal events."""
+        return AsyncQueryBuilder(self._client, "/threshold/events/withdrawal")

{defistream-1.0.0.dist-info → defistream-1.0.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: defistream
-Version: 1.0.0
+Version: 1.0.1
 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 = (
+df = (
     client.aave.liquidations()
     .network("ETH")
-    .start_block(24000000)
-    .end_block(24100000)
+    .block_range(21000000, 21010000)
     .user("0x...")
-    .as_dict()
+    .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 |
@@ -465,8 +419,6 @@ print(f"Request cost: {client.last_response.request_cost}")
 | `.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 |
@@ -479,11 +431,11 @@ print(f"Request cost: {client.last_response.request_cost}")
 
 | 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
 

{defistream-1.0.0.dist-info → defistream-1.0.1.dist-info}/RECORD

@@ -1,11 +1,11 @@
-defistream/__init__.py,sha256=nXlmtbfyy4VrbZ8PRFzUW49R6DukTRZIxeeph_9k6UY,1827
+defistream/__init__.py,sha256=h2xO5tLBCKGkCzw0DTG6g6aDSBZs2qd4oaKnCRLlJR8,1680
 defistream/client.py,sha256=Ku8ouDbM6Mx4lVmqvBwNvNt-h2FkvqauPMSjKyPkjU4,12717
 defistream/exceptions.py,sha256=_GxZQ18_YvXFtmNHeddWV8fHPIllHgFeP7fP0CmHF1k,1492
 defistream/models.py,sha256=JiG4IUq19HIANz9MHQCkaE6onGNyNzXcbdJmosrHsw0,3812
-defistream/protocols.py,sha256=b9zX0RUaw9mwZA-rPCPfpRisN5X-mdwmXSoTPYS-ius,11811
+defistream/protocols.py,sha256=5_bYd46lDy-mK6LZ8sTGW0Z2IVH4g0cQ5rBbbOXsw0U,15368
 defistream/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 defistream/query.py,sha256=73vu8uXBdiFqGKoU0nDHDQ8emLnt1HVJMmvrl--Hzmg,17791
-defistream-1.0.0.dist-info/METADATA,sha256=m6_u2yhrLNNHnm8HthaDx0pYpGtENY-CO7bz-qQeh94,12079
-defistream-1.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-defistream-1.0.0.dist-info/licenses/LICENSE,sha256=72DWAof8dMePfFQmfaswClW5d-sE6k7p-7VpuSKLmU4,1067
-defistream-1.0.0.dist-info/RECORD,,
+defistream-1.0.1.dist-info/METADATA,sha256=2yl5LrW4c3sEHzORotGKqmn5FG50oicXUCgttApTn2M,10947
+defistream-1.0.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+defistream-1.0.1.dist-info/licenses/LICENSE,sha256=72DWAof8dMePfFQmfaswClW5d-sE6k7p-7VpuSKLmU4,1067
+defistream-1.0.1.dist-info/RECORD,,