Metadata-Version: 2.4
Name: obiko
Version: 1.0.0
Summary: Python SDK for Quant Platform — Bitcoin on-chain analytics from the Arabic Bitcoin Academy
Project-URL: Homepage, https://quant-btcacademy-online.onrender.com
Project-URL: Documentation, https://quant-btcacademy-online.onrender.com/v1/sdk/info
Project-URL: Repository, https://github.com/Obi1Kn/quant-platform
Project-URL: Bug Tracker, https://github.com/Obi1Kn/quant-platform/issues
Project-URL: Get an API key, https://quant-btcacademy-online.onrender.com/pro
Author-email: Obaida Kotainy <hello@btcacademy.online>
License: MIT
License-File: LICENSE
Keywords: analytics,bitcoin,btc,cba,mvrv,nupl,on-chain,quant,research
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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 :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.8
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pandas>=1.5.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.10; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: pandas
Requires-Dist: pandas>=1.5.0; extra == 'pandas'
Description-Content-Type: text/markdown

# Obiko — Python SDK for Quant Platform

[![PyPI version](https://img.shields.io/pypi/v/obiko.svg)](https://pypi.org/project/obiko/)
[![Python](https://img.shields.io/pypi/pyversions/obiko.svg)](https://pypi.org/project/obiko/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

The official Python SDK for [Quant by Bitcoin Academy](https://quant-btcacademy-online.onrender.com) — a research-driven Bitcoin on-chain analytics platform with **pre-registered scientific methodology**.

## What makes Quant different

Quant is the only Bitcoin analytics platform that publishes its hypotheses **before** running the tests. Every indicator goes through a 5-phase protocol with SHA-256 hashed pre-registration, locked thresholds, and out-of-sample validation. We publish refutations as openly as we publish validations.

As of May 2026:
- **22 indicators** with 100% real data sources (no proxies)
- **7 pre-registered research papers** with reproducible methodology
- **1 validated finding** (CBA — 5/5 + 6/6 sanity checks)
- Original methodological contribution: **Phase 0 Protocol**

## Installation

```bash
pip install obiko
```

For DataFrame support:

```bash
pip install obiko[pandas]
```

## Quick start

```python
import obiko

client = obiko.Client(api_key="qnt_pro_xxxxxxxxxxxx")

# Get the validated CBA indicator
cba = client.cba()
print(cba.value, cba.data_date)

# Or fetch any indicator by name
mvrv = client.get_indicator("mvrv_z")
print(mvrv.value)

# Get the full dashboard snapshot
snap = client.dashboard()
print(f"Score: {snap.score}/100  Zone: {snap.zone}  Price: ${snap.price:,.0f}")
```

## API key

API keys are issued to Pro-tier subscribers. [Subscribe at /pro](https://quant-btcacademy-online.onrender.com/pro) to get yours.

You can also set the `OBIKO_API_KEY` environment variable to avoid passing the key in code:

```bash
export OBIKO_API_KEY="qnt_pro_xxxxxxxxxxxx"
```

```python
import obiko
client = obiko.Client()  # reads OBIKO_API_KEY automatically
```

## Working with pandas

Every data-returning method supports `df=True` for direct DataFrame output:

```python
import obiko

client = obiko.Client()

# All current indicators
df = client.indicators(df=True)
print(df.head())
#       indicator   value
# 0        cba       12.5
# 1        map        0.234
# 2        mvrv_z     2.1
# ...

# Full dashboard, flattened
df = client.dashboard(df=True)
print(df.head())
#       section    indicator   value
# 0     top        score       58.3
# 1     top        zone        تراكم ذكي
# ...
```

## Research papers

Pro-tier keys can fetch the underlying data for all 7 pre-registered papers:

```python
papers = client.papers()
for p in papers:
    print(p)
# <Paper ⭐ CBA phase=D outcome=validated>
# <Paper   MAP phase=D outcome=mixed>
# <Paper   PPR phase=D outcome=refuted>
# ...

# Drill into the validated paper
cba = client.paper("cba")
print(cba.verdict)              # 'VALIDATED: CBA U-shape variance pattern holds OOS'
print(cba.thresholds)           # {'P10': 1.9081, 'P90': 20.3353}
print(cba.pre_registration_hash)  # SHA-256 commit hash
```

## Available indicators

```python
print(client.info()["available_indicators"])
```

The SDK currently exposes **31 indicators** across these groups:

- **Price & valuation**: `mayer_multiple`, `ma_200d`, `ma_200w`, `realized_price`, `mvrv_z`, `mvrv_ratio`, `nupl`, `puell_multiple`, `stock_to_flow`
- **Cycle markers**: `pi_cycle_ratio`, `pi_cycle_signal`, `nupl_phase`, `rhodl_ratio`
- **Validated indicators**: `map`, `cba` (with their `_zone` companions)
- **Network health**: `hash_health`, `active_addresses`, `rsi`, `bvol_30d`
- **Premium (Pro tier)**: `hash_ribbons`, `hash_ribbons_buy`, `miner_position_index`, `fear_greed`
- **Composite**: `hybrid_index`, `price`, `zone`

## Error handling

Errors are typed for clean handling:

```python
from obiko import Client, AuthenticationError, RateLimitError, TierError

try:
    client = Client(api_key="qnt_pro_invalid")
    client.cba()
except AuthenticationError:
    print("Bad key — get a new one at /pro")
except TierError as e:
    print(f"Need Pro tier: {e}")
except RateLimitError as e:
    print(f"Slow down — retry after {e.retry_after}s")
```

## Rate limits

| Tier | Requests / minute |
|------|-------------------|
| Pro | 100 |
| Premium | 30 |

The client raises `RateLimitError` (with a `.retry_after` attribute) when limits are exceeded.

## Context manager

Sessions are automatically reused. For explicit cleanup:

```python
with obiko.Client() as client:
    snap = client.dashboard()
    # ... session closed automatically
```

## Versioning

Obiko follows [semantic versioning](https://semver.org/). The current major version is `1.x`.

## Links

- **Platform**: https://quant-btcacademy-online.onrender.com
- **Bitcoin Academy**: https://btcacademy.online
- **Source code**: https://github.com/Obi1Kn/quant-platform
- **API docs**: https://quant-btcacademy-online.onrender.com/v1/sdk/info

## License

MIT — see [LICENSE](LICENSE).

---

Made with conviction in London, UK by [Obaida Kotainy](https://www.linkedin.com/in/kotainy/).
