PyCoingecko

A comprehensive Python3 wrapper around the CoinGecko API (V3) that provides programmatic access to real-time and historical cryptocurrency market data, pricing information, exchange data, and NFT collection metrics. PyCoingecko supports both the free Public API and paid Pro/Demo API tiers, offering a simple and intuitive interface for accessing CoinGecko's extensive cryptocurrency database.

Package Information

• Package Name: pycoingecko
• Language: Python
• Installation: pip install pycoingecko

Core Imports

from pycoingecko import CoinGeckoAPI

Basic Usage

from pycoingecko import CoinGeckoAPI

# Initialize for free Public API
cg = CoinGeckoAPI()

# Or with demo API key for enhanced rate limits
cg = CoinGeckoAPI(demo_api_key='YOUR_DEMO_API_KEY')

# Or with Pro API key for full Pro API access
cg = CoinGeckoAPI(api_key='YOUR_PRO_API_KEY')

# Get current Bitcoin price in USD
price = cg.get_price(ids='bitcoin', vs_currencies='usd')
print(price)  # {'bitcoin': {'usd': 43000.00}}

# Get multiple cryptocurrencies in multiple currencies
prices = cg.get_price(
    ids=['bitcoin', 'ethereum', 'litecoin'], 
    vs_currencies=['usd', 'eur'],
    include_market_cap=True,
    include_24hr_vol=True
)

# Search for cryptocurrencies
results = cg.search(query='ethereum')

# Get trending cryptocurrencies
trending = cg.get_search_trending()

# Get global cryptocurrency market data
global_data = cg.get_global()

Architecture

PyCoingecko is built around a single CoinGeckoAPI class that handles all interactions with the CoinGecko API:

• Session Management: Persistent HTTP session with automatic retry logic and connection pooling
• API Key Handling: Automatic selection between free Public API, Demo API, and Pro API endpoints based on provided keys
• Parameter Processing: Automatic conversion of Python lists to comma-separated strings and booleans to lowercase strings
• Error Handling: Comprehensive HTTP error handling with JSON response parsing

The library uses a decorator-based approach (@func_args_preprocessing) to automatically preprocess function arguments, ensuring seamless conversion between Python data types and API-expected formats.

Capabilities

Price & Market Data

Real-time and historical cryptocurrency pricing, market capitalization, trading volume, and market-related statistics for individual coins and tokens.

def get_price(ids, vs_currencies, **kwargs): ...
def get_token_price(id, contract_addresses, vs_currencies, **kwargs): ...
def get_supported_vs_currencies(**kwargs): ...
def get_coin_top_gainers_losers(vs_currency, **kwargs): ...

Price & Market Data

Coin Information

Comprehensive coin data including metadata, tickers, historical information, market charts, OHLC data, and supply metrics.

def get_coins(**kwargs): ...
def get_coins_list(**kwargs): ...
def get_coins_list_new(**kwargs): ...
def get_coin_by_id(id, **kwargs): ...
def get_coin_market_chart_by_id(id, vs_currency, days, **kwargs): ...
def get_coin_ohlc_by_id(id, vs_currency, days, **kwargs): ...

Coin Information

Exchanges

Exchange data including exchange listings, volume information, tickers, historical volume charts, derivatives trading, market indexes, and asset platforms.

def get_exchanges_list(**kwargs): ...
def get_exchanges_by_id(id, **kwargs): ...
def get_exchanges_tickers_by_id(id, **kwargs): ...
def get_exchanges_volume_chart_by_id(id, days, **kwargs): ...
def get_derivatives(**kwargs): ...
def get_derivatives_exchanges(**kwargs): ...
def get_indexes(**kwargs): ...
def get_indexes_list(**kwargs): ...
def get_asset_platforms(**kwargs): ...
def get_asset_platform_by_id(asset_platform_id, **kwargs): ...

Exchanges

NFTs & Digital Assets

NFT collection data, market information, historical charts, and marketplace tickers for digital collectibles.

def get_nfts_list(**kwargs): ...
def get_nfts_by_id(id, **kwargs): ...
def get_nfts_markets(**kwargs): ...
def get_nfts_market_chart_by_id(id, days, **kwargs): ...

NFTs & Digital Assets

Global Market Data

Cryptocurrency market overview, global statistics, market cap charts, and DeFi-specific metrics.

def get_global(**kwargs): ...
def get_global_decentralized_finance_defi(**kwargs): ...
def get_global_market_cap_chart(days, **kwargs): ...

Global Market Data

Search & Discovery

Search functionality for cryptocurrencies, categories, markets, and trending data discovery.

def search(query, **kwargs): ...
def get_search_trending(**kwargs): ...

Search & Discovery

System & Utilities

API status monitoring, account information, and utility functions for data processing.

def ping(**kwargs): ...
def key(**kwargs): ...  # Pro API only

System & Utilities

API Key Management

PyCoingecko automatically handles different API tiers:

• Free Public API: No API key required, standard rate limits
• Demo API: Uses demo_api_key parameter for enhanced rate limits
• Pro API: Uses api_key parameter for professional-tier access with higher limits

class CoinGeckoAPI:
    def __init__(self, api_key: str = '', retries=5, demo_api_key: str = ''):
        """
        Initialize CoinGecko API client.
        
        Parameters:
        - api_key: Pro API key for professional tier access
        - retries: Number of retry attempts for failed requests (default: 5)
        - demo_api_key: Demo API key for enhanced rate limits on free tier
        """

Error Handling

All API methods may raise the following exceptions:

• requests.exceptions.RequestException: Network-related errors
• requests.exceptions.HTTPError: HTTP status errors (404, 500, etc.)
• ValueError: API response errors with JSON error details
• json.decoder.JSONDecodeError: Response parsing errors

Common Parameters

Most API methods support common optional parameters:

• Lists: Python lists are automatically converted to comma-separated strings
• Booleans: Python booleans are automatically converted to lowercase strings ('true'/'false')
• Pagination: page, per_page parameters where supported
• Localization: localization parameter for multilingual responses
• Additional Options: Method-specific parameters as defined in CoinGecko API documentation

Utility Functions

def func_args_preprocessing(func):
    """Decorator that converts list input arguments to comma-separated strings."""

def arg_preprocessing(arg_v):
    """Return the values of an argument after preprocessing."""

def get_comma_separated_values(values):
    """Return the values as a comma-separated string."""