coinglass-terminal-tools 0.1.0

Python client for the CoinGlass API v4

coinglass

Python client for the CoinGlass API v4. Typed access to futures and spot market data — OHLCV, open interest, funding rates, CVD, liquidations, orderbook depth, positioning, whale activity, and technical indicators.

Features

• 38 API methods across 12 categories (price, OI, funding, volume, liquidations, orderbook, positioning, whale/smart money, indicators, snapshots, global/macro)
• 23 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

pip install -e .

Requires Python 3.10+.

Quick Start

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

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 38 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")
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.

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 for full details on all 39 indicators.

Examples

Script	Description
quickstart.py	Basic usage of the client
funding_scanner.py	Scan for extreme funding rates across all coins
atr_stops.py	Calculate ATR, stop distances, and position sizes
cvd_divergence.py	Detect CVD-price divergences
oi_regime.py	Classify OI + price regime and detect OI divergences
liquidation_monitor.py	Track liquidation spikes and exchange breakdown
orderbook_imbalance.py	Orderbook depth analysis at multiple ranges
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.

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

Documentation

Document	Description
Getting Started	Installation, authentication, symbols, intervals, common parameters
API Reference	All 38 methods with signatures, parameters, and return types
Models	All 23 models with field tables and computed properties
Indicators	All 39 indicators with formulas, parameters, and outputs
Rate Limits	Rate limiting guide with code examples
Error Handling	Exception hierarchy, retry patterns, common errors
Changelog	Version history

Development

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

License

MIT