tessl/pypi-pycoingecko

Python3 wrapper around the CoinGecko API (V3) enabling access to cryptocurrency market data, prices, exchanges, and NFT information.

—

Pending

Overview

Eval results

Files

Price & Market Data

Name: tessl/pypi-pycoingecko
Author: tessl

Real-time and historical cryptocurrency pricing, market capitalization, trading volume, and market-related statistics for individual coins and tokens. This module provides the fundamental price data functionality that forms the core of most cryptocurrency applications.

Capabilities

Current Price Data

Get real-time prices for cryptocurrencies in any supported fiat or cryptocurrency denomination.

def get_price(ids, vs_currencies, **kwargs):
    """
    Get the current price of any cryptocurrencies in any other supported currencies.
    
    Parameters:
    - ids (str or list): Coin IDs (e.g., 'bitcoin' or ['bitcoin', 'ethereum'])
    - vs_currencies (str or list): Target currencies (e.g., 'usd' or ['usd', 'eur'])
    - include_market_cap (bool): Include market cap data
    - include_24hr_vol (bool): Include 24h volume data
    - include_24hr_change (bool): Include 24h price change percentage
    - include_last_updated_at (bool): Include last updated timestamp
    
    Returns:
    dict: Price data with coin IDs as keys and currency prices as nested values
    """

Usage Examples:

# Single coin, single currency
price = cg.get_price(ids='bitcoin', vs_currencies='usd')
# Returns: {'bitcoin': {'usd': 43000.00}}

# Multiple coins, multiple currencies
prices = cg.get_price(
    ids=['bitcoin', 'ethereum'], 
    vs_currencies=['usd', 'eur']
)
# Returns: {'bitcoin': {'usd': 43000, 'eur': 37000}, 'ethereum': {'usd': 2500, 'eur': 2150}}

# With additional market data
detailed = cg.get_price(
    ids='bitcoin',
    vs_currencies='usd',
    include_market_cap=True,
    include_24hr_vol=True,
    include_24hr_change=True
)
# Returns: {'bitcoin': {'usd': 43000, 'usd_market_cap': 845000000000, 'usd_24h_vol': 15000000000, 'usd_24h_change': 2.5}}

Token Price Data

Get current prices for tokens by their contract addresses, primarily for Ethereum-based tokens.

def get_token_price(id, contract_addresses, vs_currencies, **kwargs):
    """
    Get current prices of tokens by contract addresses.
    
    Parameters:
    - id (str): Platform ID (e.g., 'ethereum')
    - contract_addresses (str or list): Token contract addresses
    - vs_currencies (str or list): Target currencies for price quotes
    - include_market_cap (bool): Include market cap data
    - include_24hr_vol (bool): Include 24h volume data
    - include_24hr_change (bool): Include 24h price change
    - include_last_updated_at (bool): Include last updated timestamp
    
    Returns:
    dict: Token prices keyed by contract address
    """

Usage Example:

# Get USDC token price on Ethereum
token_price = cg.get_token_price(
    id='ethereum',
    contract_addresses='0xa0b86a33e6441c1a0d077d82c79525ba6b14e2a3',
    vs_currencies='usd'
)

Supported Currencies

Get the complete list of supported vs_currencies for price queries.

def get_supported_vs_currencies(**kwargs):
    """
    Get list of all supported vs_currencies for price endpoints.
    
    Returns:
    list: List of supported currency codes (fiat and crypto)
    """

Usage Example:

currencies = cg.get_supported_vs_currencies()
# Returns: ['btc', 'eth', 'ltc', 'bch', 'usd', 'eur', 'jpy', 'gbp', ...]

Top Gainers and Losers

Identify the best and worst performing cryptocurrencies over the past 24 hours.

def get_coin_top_gainers_losers(vs_currency, **kwargs):
    """
    Get top gainers and losers in the cryptocurrency market.
    
    Parameters:
    - vs_currency (str): Currency for price comparison (e.g., 'usd')
    - duration (str): Time period ('1h', '24h', '7d', '14d', '30d', '60d', '1y')
    - top_coins (str): Scope ('1000', '2000', 'all')
    
    Returns:
    dict: Contains 'top_gainers' and 'top_losers' lists with coin data
    """

Usage Example:

# Get top performers over 24 hours
performers = cg.get_coin_top_gainers_losers(vs_currency='usd')
top_gainers = performers['top_gainers']
top_losers = performers['top_losers']

Parameter Handling

List Parameters

Python lists are automatically converted to comma-separated strings:

# These are equivalent:
cg.get_price(ids=['bitcoin', 'ethereum'], vs_currencies=['usd', 'eur'])
cg.get_price(ids='bitcoin,ethereum', vs_currencies='usd,eur')

Boolean Parameters

Python booleans are automatically converted to lowercase strings:

# These are equivalent:
cg.get_price(ids='bitcoin', vs_currencies='usd', include_market_cap=True)
cg.get_price(ids='bitcoin', vs_currencies='usd', include_market_cap='true')

Error Handling

Price endpoints may raise:

requests.exceptions.HTTPError: For invalid coin IDs or currency codes
ValueError: For malformed API responses or rate limit exceeded
requests.exceptions.RequestException: For network connectivity issues

Data Formats

All price data is returned as nested dictionaries with the following structure:

{
    "coin_id": {
        "currency_code": price_value,
        "currency_code_market_cap": market_cap_value,  # if requested
        "currency_code_24h_vol": volume_value,         # if requested
        "currency_code_24h_change": change_percentage, # if requested
        "last_updated_at": timestamp                   # if requested
    }
}

Timestamps are Unix timestamps in seconds.

Install with Tessl CLI