Metadata-Version: 2.3
Name: sosovalue-pandas
Version: 0.1.1
Summary: Python client for the SoSoValue API returning pandas DataFrames
Keywords: sosovalue,crypto,etf,bitcoin,pandas,finance
Author: Lucas Jamar
Author-email: Lucas Jamar <lucasjamar@hotmail.com>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: httpx>=0.27
Requires-Dist: pandas>=2.0
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/sigma-quantiphi/sosovalue-pandas
Project-URL: Repository, https://github.com/sigma-quantiphi/sosovalue-pandas
Project-URL: Bug Tracker, https://github.com/sigma-quantiphi/sosovalue-pandas/issues
Description-Content-Type: text/markdown

# sosovalue-pandas

Python client for the [SoSoValue](https://sosovalue.com) API that returns data as pandas DataFrames.

## Installation

```bash
uv add sosovalue-pandas
# or
pip install sosovalue-pandas
```

## Quick start

```python
from sosovalue_pandas import SoSoValueClient

with SoSoValueClient(api_key="your-api-key") as client:
    # ETF inflows for a single type (~300 daily points)
    df = client.get_etf_historical_inflow_chart("us-btc-spot")

    # All supported ETF types in one DataFrame
    df_all = client.get_all_etf_inflows()

    # All listed cryptocurrencies
    df_currencies = client.get_all_listed_currencies()
```

## API reference

### `SoSoValueClient(api_key, base_url, timeout)`

| Method | Description |
|--------|-------------|
| `get_etf_historical_inflow_chart(etf)` | ~300 daily points for one ETF type |
| `get_all_etf_inflows()` | All ETF types concatenated |
| `get_all_listed_currencies()` | All listed cryptocurrencies |

### ETF types

```python
from sosovalue_pandas import ETF_TYPES
# ["us-btc-spot", "us-eth-spot", "us-sol-spot", "us-doge-spot",
#  "us-ltc-spot", "us-link-spot", "us-avax-spot"]
```

### ETF inflow columns

| Column | Type | Description |
|--------|------|-------------|
| `date` | `datetime64` | Trading date |
| `totalNetInflow` | `float` | Daily net inflow (USD) |
| `totalValueTraded` | `float` | Total value traded (USD) |
| `totalNetAssets` | `float` | Total net assets (USD) |
| `cumNetInflow` | `float` | Cumulative net inflow (USD) |
| `etf` | `str` | ETF type identifier |

### Currencies columns

| Column | Type | Description |
|--------|------|-------------|
| `currencyId` | `int` | Unique identifier |
| `fullName` | `str` | Full name (e.g. `"Bitcoin"`) |
| `currencyName` | `str` | Ticker symbol (e.g. `"BTC"`) |

## Error handling

```python
from sosovalue_pandas import SoSoValueClient, SoSoValueError

with SoSoValueClient(api_key="...") as client:
    try:
        df = client.get_etf_historical_inflow_chart("us-btc-spot")
    except SoSoValueError as e:
        print(f"API error: {e}")
```

## API key

Get your API key from [SoSoValue OpenAPI](https://openapi.sosovalue.com).

## License

MIT
