coinglass-terminal-tools 0.2.0
Python client for the CoinGlass API v4
Requires Python: >=3.10

# coinglass

Python client for the [CoinGlass API v4](https://coinglass.com/). Typed access to futures and spot market data — OHLCV, open interest, funding rates, CVD, liquidations, orderbook depth, positioning, whale activity, and technical indicators.

## Features

- **40 API methods** across 13 categories (price, OI, funding, volume, liquidations, orderbook, positioning, whale/smart money, indicators, snapshots, options, global/macro)
- **25 typed models** — immutable Pydantic objects with computed properties
- **39 local indicators** — 8 primitives, 13 Tier 1, 14 Tier 2, 5 crypto-specific composites (no external TA libraries)
- **Built-in rate limiting** — 80 req/min with 0.75s delay, automatic sleep
- **Type-safe enums** for intervals, time ranges, units, and plan validation

## Install

```bash
pip install coinglass-terminal-tools
```

Requires Python 3.10+. The import name is `coinglass`:

```python
from coinglass import CoinGlass
```

## Quick Start

```python
from coinglass import CoinGlass

with CoinGlass() as cg:  # reads COINGLASS_API_KEY env var
    candles = cg.get_ohlcv("BTCUSDT", "4h", limit=100)
    for c in candles[-3:]:
        print(f"Close: ${c.close:,.2f}  Volume: ${c.volume:,.0f}")
```

## Async Usage

```python
import asyncio
from coinglass import AsyncCoinGlass

async def main():
    async with AsyncCoinGlass() as cg:  # reads COINGLASS_API_KEY env var
        candles = await cg.get_ohlcv("BTCUSDT", "4h", limit=100)
        for c in candles[-3:]:
            print(f"Close: ${c.close:,.2f}  Volume: ${c.volume:,.0f}")

asyncio.run(main())
```

Same 40 methods as the sync client, just `await`-able. Supports `async with` or manual `await cg.aclose()`.

## What's Available

| Category | Methods | Example |
|----------|---------|---------|
| Discovery | 5 | `get_supported_coins()` |
| Price | 2 | `get_ohlcv("BTCUSDT", "4h")` |
| Open Interest | 2 | `get_open_interest_aggregated("BTC", "4h")` |
| Funding Rates | 4 | `get_funding_rate_by_exchange("BTC")` |
| Volume & CVD | 5 | `get_cvd("BTC", "4h")` |
| Liquidations | 3 | `get_liquidations_aggregated("BTC", "1h")` |
| Orderbook | 3 | `get_orderbook_aggregated("BTC", "4h")` |
| Positioning | 3 | `get_global_long_short_ratio("BTCUSDT", "4h")` |
| Whale / Smart Money | 2 | `get_whale_index("BTCUSDT", "4h")` |
| Technical Indicators | 5 | `get_rsi("BTCUSDT", "4h")` |
| Snapshots | 1 | `get_pairs_markets("BTC")` |
| Options | 2 | `get_options_info("BTC")` |
| Global / Macro | 3 | `get_coinbase_premium("4h")` |

> Funding rates are returned as **percentages**: `0.01` means `0.01%`, not `1%`.

## Indicators

The `coinglass.indicators` subpackage provides 39 technical indicators built on the library's models — no external TA libraries needed. Tier 1/2 operate on `list[OHLCVCandle]`. Tier 3 composites combine CoinGlass-unique data (funding, liquidations, whale index, L/S ratios) for crypto-specific analysis.

```python
from coinglass import CoinGlass
from coinglass.indicators import calculate_supertrend

with CoinGlass() as cg:
    candles = cg.get_ohlcv("BTCUSDT", "4h", limit=200)
    st = calculate_supertrend(candles)
    print(f"Supertrend: {st[-1].value:.2f}, direction: {'UP' if st[-1].direction == 1 else 'DOWN'}")
```

See [docs/indicators.md](docs/indicators.md) for full details on all 39 indicators.

## Examples

| Script | Description |
|--------|-------------|
| [`quickstart.py`](examples/quickstart.py) | Basic usage of the client |
| [`funding_scanner.py`](examples/funding_scanner.py) | Scan for extreme funding rates across all coins |
| [`atr_stops.py`](examples/atr_stops.py) | Calculate ATR, stop distances, and position sizes |
| [`cvd_divergence.py`](examples/cvd_divergence.py) | Detect CVD-price divergences |
| [`oi_regime.py`](examples/oi_regime.py) | Classify OI + price regime and detect OI divergences |
| [`liquidation_monitor.py`](examples/liquidation_monitor.py) | Track liquidation spikes and exchange breakdown |
| [`orderbook_imbalance.py`](examples/orderbook_imbalance.py) | Orderbook depth analysis at multiple ranges |
| [`multi_timeframe.py`](examples/multi_timeframe.py) | Compare RSI and OI across 1h/4h/1d timeframes |

Each example is fully self-contained — copy any script to your project and it just works.

```bash
export COINGLASS_API_KEY="your-key"
python examples/quickstart.py
```

## Documentation

| Document | Description |
|----------|-------------|
| [Getting Started](docs/getting-started.md) | Installation, authentication, symbols, intervals, common parameters |
| [API Reference](docs/api-reference.md) | All 40 methods with signatures, parameters, and return types |
| [Models](docs/models.md) | All 25 models with field tables and computed properties |
| [Indicators](docs/indicators.md) | All 39 indicators with formulas, parameters, and outputs |
| [Rate Limits](docs/rate-limits.md) | Rate limiting guide with code examples |
| [Error Handling](docs/error-handling.md) | Exception hierarchy, retry patterns, common errors |
| [Changelog](docs/changelog.md) | Version history |

## Development

```bash
pip install -e ".[dev]"
pytest tests/ -v
ruff check src/
```

## License

MIT