defistream 1.0.6__py3-none-any.whl

defistream-1.0.6.dist-info/METADATA

@@ -0,0 +1,438 @@
+Metadata-Version: 2.4
+Name: defistream
+Version: 1.0.6
+Summary: Python client for the DeFiStream API
+Project-URL: Homepage, https://defistream.dev
+Project-URL: Documentation, https://docs.defistream.dev
+Project-URL: Repository, https://github.com/Eren-Nevin/DeFiStream_PythonClient
+Author-email: DeFiStream <support@defistream.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,blockchain,crypto,defi,ethereum,web3
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: pyarrow>=14.0.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0.0; extra == 'dev'
+Provides-Extra: polars
+Requires-Dist: polars>=0.20.0; extra == 'polars'
+Description-Content-Type: text/markdown
+
+# DeFiStream Python Client
+
+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
+
+```bash
+pip install defistream
+```
+
+This includes pandas and pyarrow by default for DataFrame support.
+
+With polars support (in addition to pandas):
+```bash
+pip install defistream[polars]
+```
+
+## Quick Start
+
+```python
+from defistream import DeFiStream
+
+# Initialize client (reads DEFISTREAM_API_KEY from environment if not provided)
+client = DeFiStream()
+
+# Or with explicit API key
+client = DeFiStream(api_key="dsk_your_api_key")
+
+# Query ERC20 transfers using builder pattern
+df = (
+    client.erc20.transfers("USDT")
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .as_df()
+)
+
+print(df.head())
+```
+
+## Features
+
+- **Builder pattern**: Fluent query API with chainable methods
+- **Type-safe**: Full type hints and Pydantic models
+- **Multiple formats**: DataFrame (pandas/polars), CSV, Parquet, JSON
+- **Async support**: Native async/await with `AsyncDeFiStream`
+- **All protocols**: ERC20, AAVE, Uniswap, Lido, Stader, Threshold, Native tokens
+
+## Supported Protocols
+
+| Protocol | Events |
+|----------|--------|
+| ERC20 | `transfers` |
+| Native Token | `transfers` |
+| 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_df()`, `as_file()`, or `as_dict()`.
+
+```python
+from defistream import DeFiStream
+
+client = DeFiStream()
+
+# Build query step by step
+query = client.erc20.transfers("USDT")
+query = query.network("ETH")
+query = query.block_range(21000000, 21010000)
+query = query.min_amount(1000)
+
+# Execute and get DataFrame
+df = query.as_df()
+
+# Or chain everything
+df = (
+    client.erc20.transfers("USDT")
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .min_amount(1000)
+    .as_df()
+)
+```
+
+### ERC20 Transfers
+
+```python
+# Get USDT transfers over 10,000 USDT
+df = (
+    client.erc20.transfers("USDT")
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .min_amount(10000)
+    .as_df()
+)
+
+# Filter by sender
+df = (
+    client.erc20.transfers("USDT")
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .sender("0x28c6c06298d514db089934071355e5743bf21d60")
+    .as_df()
+)
+```
+
+### AAVE Events
+
+```python
+# Get deposits
+df = (
+    client.aave.deposits()
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .as_df()
+)
+
+# Use a specific market type on ETH (Core, Prime, or EtherFi)
+df = (
+    client.aave.deposits()
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .eth_market_type("Prime")
+    .as_df()
+)
+```
+
+### Uniswap Swaps
+
+```python
+# Get swaps for WETH/USDC pool with 0.05% fee tier
+df = (
+    client.uniswap.swaps("WETH", "USDC", 500)
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .as_df()
+)
+
+# Or build with chain methods
+df = (
+    client.uniswap.swaps()
+    .symbol0("WETH")
+    .symbol1("USDC")
+    .fee(500)
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .as_df()
+)
+```
+
+### Native Token Transfers
+
+```python
+# Get ETH transfers >= 1 ETH
+df = (
+    client.native_token.transfers()
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .min_amount(1.0)
+    .as_df()
+)
+```
+
+### Verbose Mode
+
+By default, responses omit metadata fields to reduce payload size. Use `.verbose()` to include all fields:
+
+```python
+# Default: compact response (no tx_hash, tx_id, log_index, network, name)
+df = (
+    client.erc20.transfers("USDT")
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .as_df()
+)
+
+# Verbose: includes all metadata fields
+df = (
+    client.erc20.transfers("USDT")
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .verbose()
+    .as_df()
+)
+```
+
+### Return as DataFrame
+
+```python
+# As pandas DataFrame (default)
+df = (
+    client.erc20.transfers("USDT")
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .as_df()
+)
+
+# As polars DataFrame
+df = (
+    client.erc20.transfers("USDT")
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .as_df("polars")
+)
+```
+
+### Save to File
+
+Format is automatically determined by file extension:
+
+```python
+# Save as Parquet (recommended for large datasets)
+(
+    client.erc20.transfers("USDT")
+    .network("ETH")
+    .block_range(21000000, 21100000)
+    .as_file("transfers.parquet")
+)
+
+# Save as CSV
+(
+    client.erc20.transfers("USDT")
+    .network("ETH")
+    .block_range(21000000, 21100000)
+    .as_file("transfers.csv")
+)
+
+# Save as JSON
+(
+    client.erc20.transfers("USDT")
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .as_file("transfers.json")
+)
+```
+
+### Return as Dictionary (JSON)
+
+For small queries, you can get results as a list of dictionaries:
+
+```python
+transfers = (
+    client.erc20.transfers("USDT")
+    .network("ETH")
+    .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
+import asyncio
+from defistream import AsyncDeFiStream
+
+async def main():
+    async with AsyncDeFiStream() as client:
+        df = await (
+            client.erc20.transfers("USDT")
+            .network("ETH")
+            .block_range(21000000, 21010000)
+            .as_df()
+        )
+        print(f"Found {len(df)} transfers")
+
+asyncio.run(main())
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+export DEFISTREAM_API_KEY=dsk_your_api_key
+export DEFISTREAM_BASE_URL=https://api.defistream.dev/v1  # optional
+```
+
+```python
+from defistream import DeFiStream
+
+# API key from environment
+client = DeFiStream()
+
+# Or explicit
+client = DeFiStream(api_key="dsk_...", base_url="https://api.defistream.dev/v1")
+```
+
+### Timeout and Retries
+
+```python
+client = DeFiStream(
+    api_key="dsk_...",
+    timeout=60.0,  # seconds
+    max_retries=3
+)
+```
+
+## Error Handling
+
+```python
+from defistream import DeFiStream
+from defistream.exceptions import (
+    DeFiStreamError,
+    AuthenticationError,
+    QuotaExceededError,
+    RateLimitError,
+    ValidationError
+)
+
+client = DeFiStream()
+
+try:
+    df = (
+        client.erc20.transfers("USDT")
+        .network("ETH")
+        .block_range(21000000, 21010000)
+        .as_df()
+    )
+except AuthenticationError:
+    print("Invalid API key")
+except QuotaExceededError as e:
+    print(f"Quota exceeded. Remaining: {e.remaining}")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after: {e.retry_after}s")
+except ValidationError as e:
+    print(f"Invalid request: {e.message}")
+except DeFiStreamError as e:
+    print(f"API error: {e}")
+```
+
+## Response Headers
+
+Access rate limit and quota information:
+
+```python
+df = (
+    client.erc20.transfers("USDT")
+    .network("ETH")
+    .block_range(21000000, 21010000)
+    .as_df()
+)
+
+# Access response metadata
+print(f"Rate limit: {client.last_response.rate_limit}")
+print(f"Remaining quota: {client.last_response.quota_remaining}")
+print(f"Request cost: {client.last_response.request_cost}")
+```
+
+## Builder Methods Reference
+
+### Common Methods (all protocols)
+
+| Method | Description |
+|--------|-------------|
+| `.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 |
+| `.start_time(ts)` | Set starting time (ISO format or Unix timestamp) |
+| `.end_time(ts)` | Set ending time (ISO format or Unix timestamp) |
+| `.time_range(start, end)` | Set both start and end times |
+| `.verbose()` | Include all metadata fields |
+
+### Protocol-Specific Parameters
+
+| Method | Protocols | Description |
+|--------|-----------|-------------|
+| `.token(symbol)` | ERC20 | Token symbol (USDT, USDC) or contract address (required) |
+| `.sender(addr)` | ERC20, Native | Filter by sender address |
+| `.receiver(addr)` | ERC20, Native | Filter by receiver address |
+| `.min_amount(amt)` | ERC20, Native | Minimum transfer amount |
+| `.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_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
+
+MIT License

defistream-1.0.6.dist-info/RECORD

@@ -0,0 +1,11 @@
+defistream/__init__.py,sha256=duUlI1d-H7mP16D6dd0zbCslu45ARItE_pwQ5N7o05M,1089
+defistream/client.py,sha256=Ku8ouDbM6Mx4lVmqvBwNvNt-h2FkvqauPMSjKyPkjU4,12717
+defistream/exceptions.py,sha256=_GxZQ18_YvXFtmNHeddWV8fHPIllHgFeP7fP0CmHF1k,1492
+defistream/models.py,sha256=Zw3DHAISxB6pivKybNzyHXR5IcRwvTZl23DHbjfyKwM,622
+defistream/protocols.py,sha256=5_bYd46lDy-mK6LZ8sTGW0Z2IVH4g0cQ5rBbbOXsw0U,15368
+defistream/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+defistream/query.py,sha256=sNn_0OzNDlsp4N74Grumsb08R5OFPPoppPok3vh8Y6Q,16775
+defistream-1.0.6.dist-info/METADATA,sha256=2VBBk9BJNGQiGOyya3YCTB23rFTbes0UjNhma-4R4ig,10877
+defistream-1.0.6.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+defistream-1.0.6.dist-info/licenses/LICENSE,sha256=72DWAof8dMePfFQmfaswClW5d-sE6k7p-7VpuSKLmU4,1067
+defistream-1.0.6.dist-info/RECORD,,

defistream-1.0.6.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

defistream-1.0.6.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeFiStream
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.