# Vaults.fyi Python SDK

Python SDK for the Vaults.fyi V2 API.

## Installation

```bash
pip install vaultsfyi
```

## Quick Start

```python
from vaultsfyi import VaultsSdk

client = VaultsSdk(api_key="your_api_key_here")

# Basic health check
print(client.get_health())

# Fetch detailed vaults with filters
vaults = client.get_detailed_vaults(
    page=0,
    per_page=100,
    allowed_assets=["USDC", "USDT"],
    allowed_networks=["mainnet", "base"],
    min_tvl=1_000_000,
    only_transactional=True,
)

# User portfolio positions
positions = client.get_positions(
    user_address="0x1234...",
    allowed_networks=["mainnet", "base"],
    min_usd_asset_value_threshold=100,
)
```

## Authentication

All endpoints use API key auth via `x-api-key` header.

```python
client = VaultsSdk(api_key="your_api_key_here")
```

## Method Reference

### Health & Metadata

- `get_health()`
- `get_networks(**kwargs)`
- `get_tags(**kwargs)`
- `get_assets(page=None, per_page=None, network=None, **kwargs)`
- `get_vaults(page=None, per_page=None, network=None, asset_symbol=None, only_transactional=None, only_app_featured=None, allow_corrupted=None, **kwargs)`
- `get_curators(**kwargs)`

### Benchmarks

- `get_benchmarks(network, code)`
- `get_historical_benchmarks(network, code, page=None, per_page=None, from_timestamp=None, to_timestamp=None, **kwargs)`

### Detailed Vaults

- `get_detailed_vaults(page=None, per_page=None, allowed_assets=None, disallowed_assets=None, allowed_protocols=None, disallowed_protocols=None, allowed_networks=None, disallowed_networks=None, min_tvl=None, max_tvl=None, min_apy=None, max_apy=None, tags=None, curators=None, only_transactional=None, only_app_featured=None, allow_corrupted=None, allow_vaults_with_warnings=None, sort_by=None, sort_order=None, **kwargs)`
- `get_all_vaults(**kwargs)` *(backward-compatible alias for `get_detailed_vaults`)*
- `get_vault(network, vault_address, **kwargs)`
- `get_vault_apy_breakdown(network, vault_address, **kwargs)`
- `get_vault_tvl_breakdown(network, vault_address, **kwargs)`

### Historical Data

- `get_vault_historical_data(network, vault_address, page=None, per_page=None, apy_interval=None, granularity=None, from_timestamp=None, to_timestamp=None, **kwargs)`
- `get_vault_historical_apy(network, vault_address, page=None, per_page=None, apy_interval=None, granularity=None, from_timestamp=None, to_timestamp=None, **kwargs)`
- `get_vault_historical_tvl(network, vault_address, page=None, per_page=None, apy_interval=None, granularity=None, from_timestamp=None, to_timestamp=None, **kwargs)`
- `get_vault_historical_share_price(network, vault_address, page=None, per_page=None, apy_interval=None, granularity=None, from_timestamp=None, to_timestamp=None, **kwargs)`
- `get_historical_asset_prices(network, asset_address, page=None, per_page=None, granularity=None, from_timestamp=None, to_timestamp=None, **kwargs)`

### Portfolio

- `get_positions(user_address, allowed_assets=None, disallowed_assets=None, allowed_protocols=None, disallowed_protocols=None, allowed_networks=None, disallowed_networks=None, min_tvl=None, max_tvl=None, min_apy=None, max_apy=None, tags=None, curators=None, only_transactional=None, only_app_featured=None, allow_corrupted=None, allow_vaults_with_warnings=None, sort_by=None, sort_order=None, apy_interval=None, min_usd_asset_value_threshold=None, **kwargs)`
- `get_position(user_address, network, vault_address, apy_interval=None, **kwargs)`
- `get_best_vault(user_address, allowed_assets=None, disallowed_assets=None, allowed_protocols=None, disallowed_protocols=None, allowed_networks=None, disallowed_networks=None, min_tvl=None, min_apy=None, only_transactional=None, only_app_featured=None, allow_corrupted=None, allow_vaults_with_warnings=None, apy_interval=None, min_usd_asset_value_threshold=None, **kwargs)`
- `get_deposit_options(user_address, allowed_assets=None, disallowed_assets=None, allowed_protocols=None, disallowed_protocols=None, allowed_networks=None, disallowed_networks=None, min_tvl=None, min_apy=None, only_transactional=None, only_app_featured=None, allow_corrupted=None, allow_vaults_with_warnings=None, apy_interval=None, min_usd_asset_value_threshold=None, always_return_assets=None, max_vaults_per_asset=None, **kwargs)`
- `get_idle_assets(user_address, allowed_assets=None, disallowed_assets=None, allowed_networks=None, disallowed_networks=None, min_usd_asset_value_threshold=None, sort_by=None, sort_direction=None, **kwargs)`
- `get_vault_total_returns(user_address, network, vault_address, **kwargs)`
- `get_vault_holder_events(user_address, network, vault_address, **kwargs)`

### Transactions

- `get_transactions_context(user_address, network, vault_address, **kwargs)`
- `get_actions(action, user_address, network, vault_address, amount=None, asset_address=None, simulate=False, all=None, **kwargs)`

### Rewards

- `get_rewards_context(user_address, **kwargs)`
- `get_rewards_claim(user_address, simulate=None, claim_ids=None, **kwargs)`

## Usage Examples

### Detailed vault filters

```python
vaults = client.get_detailed_vaults(
    allowed_assets=["USDC"],
    allowed_networks=["mainnet", "base"],
    min_tvl=1_000_000,
    min_apy=0.02,
    sort_by="apy",
    sort_order="desc",
    page=0,
    per_page=100,
)
```

### Deposit options

```python
options = client.get_deposit_options(
    user_address="0x1234...",
    allowed_assets=["USDC", "USDT"],
    allowed_networks=["mainnet", "base"],
    min_usd_asset_value_threshold=100,
    always_return_assets=["USDC"],
    max_vaults_per_asset=5,
)
```

### Historical asset prices

```python
prices = client.get_historical_asset_prices(
    network="mainnet",
    asset_address="0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    granularity="1d",
    page=0,
    per_page=100,
)
```

### Transaction actions

```python
actions = client.get_actions(
    action="deposit",
    user_address="0x1234...",
    network="mainnet",
    vault_address="0x5678...",
    asset_address="0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    amount="1000000",
    simulate=False,
)
```

## Error Handling

```python
from vaultsfyi import VaultsSdk, AuthenticationError, HttpResponseError

client = VaultsSdk(api_key="your_api_key_here")

try:
    result = client.get_benchmarks("mainnet", "usd")
except AuthenticationError:
    print("Invalid API key")
except HttpResponseError as e:
    print(f"API error: {e}")
```

## Requirements

- Python 3.8+
- `requests>=2.25.0`

## License

MIT
