pycgapi

class pycgapi.api.CoinGeckoAPI(api_key: str = None, pro_api: bool = False, retries: int = 5)

Bases: object

A Python wrapper for the CoinGecko API with a focus on ease of use and data integrity.

This class provides methods for accessing the CoinGecko API.

api_key

API key for the CoinGecko API.

Type:: str

pro_api

Flag to use the PRO API.

Type:: bool

base_url

Base URL for the CoinGecko API.

Type:: str

session

A requests Session object for making HTTP requests.

Type:: requests.Session

active_exchanges_list(per_page: int = 100, page: int = 1) → DataFrame

Fetches a list of all active exchanges with trading volumes from the CoinGecko API.

This method queries the CoinGecko API to retrieve a list of all active exchanges with their trading volumes. The data is updated every 60 seconds.

Parameters:

per_page (int, optional) – Total results per page. Valid values are from 1 to 250. Defaults to 100.
page (int, optional) – Page number to paginate through results. Defaults to 1.

Returns:

A DataFrame containing the list of all active exchanges with trading volumes.

Return type:

pd.DataFrame

Raises:

HTTPError – If the HTTP request fails.

Notes

Works with the exchanges endpoint.
Available for public and pro API users.

all_derivatives_exchanges_list() → DataFrame

Fetches a list of all derivative exchanges names and identifiers from the CoinGecko API.

This method queries the CoinGecko API to retrieve a list of all derivative exchanges, including their names and identifiers. The data is updated every 5 minutes.

Returns:: A DataFrame containing the list of all derivative exchanges with their names and identifiers.
Return type:: pd.DataFrame
Raises:: HTTPError – If the HTTP request fails.

Notes

Works with the derivatives/exchanges/list endpoint.
Available for public and pro API users.

all_exchanges_list() → DataFrame

Fetches a list of all supported market IDs and names from the CoinGecko API.

This method queries the CoinGecko API to retrieve a list of all supported markets, including their IDs and names. The data is updated every 5 minutes.

Returns:: A DataFrame containing the list of all supported markets with their IDs and names.
Return type:: pd.DataFrame
Raises:: HTTPError – If the HTTP request fails.

Notes

Works with the exchanges/list endpoint.
Available for public and pro API users.

all_tokens_list(asset_platform_id: str) → DataFrame

Retrieves a full list of tokens for a specific blockchain network supported by Ethereum token list standard.

Parameters:: asset_platform_id (str) – The ID of the blockchain network (e.g., ‘ethereum’, ‘polygon-pos’).
Returns:: A DataFrame containing a comprehensive list of tokens for the specified blockchain network.
Return type:: pd.DataFrame
Raises:: HTTPError – If the HTTP request fails.

Notes

Works with the token_lists/{asset_platform_id}/all endpoint.
Use get_asset_platforms method to retrieve a list of supported blockchain networks.
Available for enterprise API users only.

asset_platforms_list(platform_filter: str = None)

Fetch a list of all asset platforms (blockchain networks) from the CoinGecko API.

Parameters:: platform_filter (str, optional) – Apply relevant filters to results. Valid values: “nft” for platforms with NFT support. Default is None.
Returns:: A DataFrame containing the list of asset platforms.
Return type:: pd.DataFrame
Raises:: HTTPError – If the HTTP request fails.

Notes

The data includes details of various blockchain networks.
If the ‘filter’ is set to “nft”, only platforms that support NFTs are returned.
Works with the asset_platforms endpoint.
Available for public and pro API users.

btc_exchange_rates() → DataFrame

Fetches BTC-to-Currency exchange rates from the CoinGecko API.

This method queries the CoinGecko API to retrieve BTC-to-Currency exchange rates. The data is updated every 60 seconds.

Returns:: A DataFrame containing the BTC-to-Currency exchange rates.
Return type:: pd.DataFrame
Raises:: HTTPError – If the HTTP request fails.

Notes

Works with the exchange_rates endpoint.
Available for public and pro API users.

build_endpoint(endpoint: str) → str

Constructs the complete endpoint URL with API key if required.

Parameters:: endpoint (str) – The specific API endpoint.
Returns:: The complete URL to be used for the API call.
Return type:: str

categories_market_data(order: str = 'market_cap_desc') → DataFrame

Fetches a list of all cryptocurrency categories with market data from the CoinGecko API.

This method queries the CoinGecko API to retrieve a list of all cryptocurrency categories, including their market data. The data is updated every 5 minutes.

Parameters:: order (str, optional) – Ordering of the results. Valid values are ‘market_cap_desc’ (default), ‘market_cap_asc’, ‘name_desc’, ‘name_asc’, ‘market_cap_change_24h_desc’, and ‘market_cap_change_24h_asc’.
Returns:: A DataFrame containing the list of cryptocurrency categories with their market data.
Return type:: pd.DataFrame
Raises:: HTTPError – If the HTTP request fails.

Notes

Works with the coins/categories endpoint.
Available for public and pro API users.

coin_by_contract(platform_id: str, contract_address: str) → dict

Fetch coin information using a specific contract address on a given platform.

Parameters:

platform_id (str) – ID of the asset platform (e.g., ‘ethereum’). Refer to the get_asset_platforms method. Required.
contract_address (str) – The contract address of the token. Required.

Returns:

A dictionary containing the coin information.

Return type:

dict

Raises:

HTTPError – If the HTTP request fails.

Notes

Data is cached and updated every 60 seconds.
This endpoint retrieves current data for a coin based on its contract address.
Works with the coins/{id}/contract/{contract_address} endpoint.
Available for public and pro API users.

coin_circulating_supply_history(coin_id: str = 'bitcoin', days: int = 'max', interval: str = 'daily', from_date: str = None, to_date: str = None) → DataFrame

Fetches historical circulating supply data for a coin, either for a specified number of days or within a date range.

Parameters:

coin_id (str) – The ID of the coin (e.g., ‘bitcoin’).
days (int) – Number of days from now for the historical data. Can be up to ‘max’ available days.
interval (str) – Data interval. Valid values include ‘daily’, ‘hourly’, and ‘5-minutely’.
from_date (str, optional) – Start date in ‘mm-dd-yyyy’ format for date range query.
to_date (str, optional) – End date in ‘mm-dd-yyyy’ format for date range query.

Returns:

A DataFrame containing the circulating supply data of the specified coin.

Return type:

pd.DataFrame

Raises:

HTTPError – If the HTTP request fails.

Notes

Works with the coins/{id}/circulating_supply_chart endpoint.
Available for pro and enterprise API users only.

coin_historical_market_data(coin_id: str, vs_currency: str = 'usd', days: Union[int, str] = 'max', interval: str = 'daily', precision: str = 'full', from_date: str = None, to_date: str = None, timezone_str: str = 'UTC') → DataFrame

Get historical market data including price, market cap, and 24h volume for a coin.

This method fetches historical market data for a given cryptocurrency. The data granularity is automatic and varies based on the ‘days’ parameter:

1 day: 5-minute intervals,
2 to 90 days: hourly data,
More than 90 days: daily data at 00:00 UTC.

Parameters:

coin_id (str) – The ID of the coin (e.g., ‘bitcoin’). Refers to coins listed in get_coin_list method.
vs_currency (str, optional) – The target currency of market data (‘usd’, ‘eur’, ‘jpy’, etc.). Refers to supported vs_currencies. Defaults to ‘usd’. Required.
days (Union[int, str], optional) – Data up to a number of days ago or ‘max’ for maximum available data. Default is ‘max’.
interval (str, optional) – Data interval. Possible value: ‘daily’. Default is ‘daily’.
precision (str, optional) – Decimal precision for currency price value. Default is ‘full’.
from_date (str, optional) – From date in ‘mm-dd-yyyy’ format or UNIX Timestamp.
to_date (str, optional) – To date in ‘mm-dd-yyyy’ format or UNIX Timestamp.
timezone_str (str, optional) – Timezone of the dates. Default is ‘UTC’.

Returns:

A DataFrame containing the historical market data of the specified coin.

Return type:

pd.DataFrame

Raises:

HTTPError – If the HTTP request fails.

Notes

Cache expiration times vary: 30 seconds for 1 day, 30 minutes for 2-90 days, and 12 hours for more than 90 days.
The last completed UTC day’s data is available 35 minutes after midnight on the next UTC day (00:35), and the cache always expires at 00:40 UTC.
Works with the coins/{id}/market_chart and coins/{id}/market_chart/range endpoints.
Available for public and pro API users.

coin_historical_on_date(coin_id: str, date: str, localization: str = 'en') → dict

Get historical data (price, market cap, 24hr volume, etc.) for a coin on a specified date.

This method retrieves a snapshot of historical data for a given cryptocurrency at 00:00:00 UTC of the specified date. The last completed UTC day’s data is available 35 minutes after midnight on the next UTC day (00:35).

Parameters:

coin_id (str) – The ID of the coin (e.g., ‘bitcoin’). Refers to coins listed in the get_coins_list method.
date (str) – The date for the historical data snapshot in mm-dd-yyyy format (e.g., ‘12-30-2022’).
localization (str, optional) – The language setting for localization. Default is ‘en’. Set to ‘false’ to exclude localized languages.

Returns:

A dictionary containing the historical data of the specified coin at the given date.

Return type:

dict

Raises:

HTTPError – If the HTTP request fails.

Notes

The returned data includes price, market cap, and 24-hour trading volume.
Data is provided for the specified date at 00:00:00 UTC.
The ‘date’ parameter should now be formatted in mm-dd-yyyy (e.g., 12-30-2022).
Works with the coins/{id}/history endpoint.
Available for public and pro API users.

coin_info(coin_id: str, localization: str = 'true', tickers: bool = True, market_data: bool = True, community_data: bool = True, developer_data: bool = True, sparkline: bool = False) → dict

Get current data (name, price, market, etc.) for a specified coin from CoinGecko.

This method retrieves a wide array of data for a specified cryptocurrency, including name, price, market data, tickers, community and developer data. The data is updated every 60 seconds, ensuring up-to-date information. Twitter, Telegram, and Reddit data is updated daily.

Parameters:

coin_id (str) – The ID of the coin (e.g., ‘bitcoin’). Refers to coins listed in the get_coins_list method.
localization (str, optional) – Include all localized languages in response. Defaults to ‘true’.
tickers (bool, optional) – Include ticker data, limited to 100 items. For more, use the get_coin_tickers method. Defaults to True.
market_data (bool, optional) – Include market data. Defaults to True.
community_data (bool, optional) – Include community data. Defaults to True.
developer_data (bool, optional) – Include developer data. Defaults to True.
sparkline (bool, optional) – Include sparkline data for the last 7 days. Defaults to False.

Returns:

A dictionary containing the data for the coin.

Return type:

dict

Raises:

HTTPError – If the HTTP request fails.

Notes

Ticker data has limitations: ‘is_stale’ is true if not updated for > 8 hours; ‘is_anomaly’ if price is an outlier.
Users are responsible for managing how to display ticker information (e.g., footnote, opacity).
For stale prices, refer to ‘last_updated’ in the price information.
Works with the coins/{id} endpoint.
Available for public and pro API users.

coin_market_tickers(coin_id: str, exchange_ids: str = None, include_exchange_logo: bool = False, page: int = 1, order: str = 'trust_score_desc', depth: bool = False) → DataFrame

Get tickers for a specific coin, paginated to 100 items per page.

This method retrieves ticker information for a specified cryptocurrency, with the data updated every 2 minutes. It includes details such as price, volume, and last trading time.

Parameters:

coin_id (str) – The ID of the coin (e.g., ‘bitcoin’). Refers to coins listed in the get_coins_list method.
exchange_ids (str, optional) – Comma separated cryptocurrency exchange ids (e.g., ‘binance,kraken’).
include_exchange_logo (bool, optional) – Flag to include exchange logo. Defaults to False.
page (int, optional) – Page through results. Default is 1.
order (str, optional) – Sort results by field. Default is “trust_score_desc”.
depth (bool, optional) – Flag to include 2% orderbook depth. Defaults to False.

Returns:

A dictionary containing the tickers for the specified coin.

Return type:

pd.DataFrame

Raises:

HTTPError – If the HTTP request fails.

Notes

Ticker is marked as ‘stale’ if not updated for more than 8 hours and as ‘anomaly’ if price is an outlier.
Users are responsible for managing the display of these information (e.g., footnote, opacity).
Includes last unconverted price, 24h trading volume, converted prices and volumes in BTC, ETH, and USD.
The ‘last_traded_at’ and ‘last_fetch_at’ fields indicate the last time the price changed and the last API call.
Works with the coins/{id}/tickers endpoint.
Available for public and pro API users.

coin_ohlc_data(coin_id: str, vs_currency: str = 'usd', days: Union[int, str] = 'max', precision: str = None)

Fetch the OHLC (Open, High, Low, Close) data for a given coin from the CoinGecko API and return it as a DataFrame.

This method retrieves OHLC data for a specified cryptocurrency. The granularity of the data is automatic and cannot be adjusted for public API users. The granularity varies as follows:

1 to 2 days: 30-minute intervals,
3 to 30 days: 4-hour intervals,
31 days and beyond: 4-day intervals.

For paid plan users, a ‘daily’ candle interval parameter is available.

Parameters:

coin_id (str) – The ID of the coin (e.g., ‘bitcoin’). Refers to coins listed by the get_coins_list method. Required.
vs_currency (str, optional) – The target currency of market data (e.g., ‘usd’, ‘eur’, ‘jpy’, etc.). Default is ‘usd’.
days (Union[int, str], optional) – Data up to a number of days ago (e.g., ‘1’, ‘7’, ‘14’, ‘30’, ‘90’, ‘180’, ‘365’, ‘max’). Default is ‘max’.
precision (str, optional) – Decimal precision for currency price value.

Returns:

A DataFrame containing the OHLC data.

Return type:

DataFrame

Raises:

HTTPError – If the HTTP request fails.

Notes

The ‘daily’ interval is available only for paid plan users for the periods 1/7/14/30/90/180 days.
Data is cached and updated every 30 minutes. The last completed UTC day’s data is available 35 minutes after midnight on the next UTC day (00:35).
Works with the coins/{id}/ohlc endpoint.
Available for public and pro API users.

coin_total_supply_history(coin_id: str, days: int = 30, interval: str = 'daily', from_date: str = None, to_date: str = None) → DataFrame

Fetches historical total supply data for a coin, either for a specified number of days or within a date range.

Parameters:

coin_id (str) – The ID of the coin (e.g., ‘bitcoin’).
days (int) – Number of days from now for the historical data. Can be up to ‘max’ available days.
interval (str) – Data interval. Valid values include ‘daily’, ‘hourly’, and ‘5-minutely’.
from_date (str, optional) – Start date in ‘mm-dd-yyyy’ format for date range query.
to_date (str, optional) – End date in ‘mm-dd-yyyy’ format for date range query.

Returns:

A DataFrame containing the total supply data of the specified coin.

Return type:

pd.DataFrame

Raises:

HTTPError – If the HTTP request fails.

Notes

Works with the coins/{id}/total_supply_chart
Also works with the coins/{coin_id}/total_supply_chart/range endpoints.
Available for pro and enterprise API users only.

coins_list(include_platform: bool = False) → DataFrame

Get a list of all supported coins with their id, name, and symbol from CoinGecko.

Only active coins listed by the CoinGecko team are included. Inactive or deactivated coins are removed from the list. The list is updated every 5 minutes.

Parameters:

include_platform (bool, optional) – Flag to include platform contract addresses (e.g., Ethereum based tokens). Defaults to False. Set to True to include platform information.

Returns:

A DataFrame where each row contains the id, name, and symbol of a coin.: If ‘include_platform’ is True, platform contract addresses are also included.

Return type:

pd.DataFrame

Raises:

HTTPError – If the HTTP request fails.

Notes

Works with the coin/list endpoint.
Available for public and pro API users.

coins_market_data(vs_currency: str = 'usd', ids: str = None, category: str = None, order: str = 'market_cap_desc', per_page: int = 100, page: int = 1, sparkline: bool = False, price_change_percentage: str = None, locale: str = 'en', precision: str = None) → DataFrame

Get a list of all supported coins with market data from CoinGecko.

This method obtains all the coins’ market data including price, market cap, and volume. The data is updated every 45 seconds. When both ‘category’ and ‘ids’ parameters are supplied, ‘category’ takes precedence over ‘ids’.

Parameters:

vs_currency (str, optional) – The target currency of market data (e.g., ‘usd’, ‘eur’, ‘jpy’, etc.). Default is ‘usd’.
ids (str, optional) – Comma-separated cryptocurrency symbols (base). Refer to get_coins_list method.
category (str, optional) – Filter by coin category. Refer to get_coin_categories.
order (str, optional) – Sorting order. Default is “market_cap_desc”. Valid values include ‘market_cap_asc’, ‘market_cap_desc’, ‘volume_asc’, ‘volume_desc’, ‘id_asc’, ‘id_desc’.
per_page (int, optional) – Total results per page. Default is 100. Valid range is 1 to 250.
page (int, optional) – Page through results. Default is 1.
sparkline (bool, optional) – Include sparkline 7 days data. Default is False.
price_change_percentage (str, optional) – Include price change percentage in 1h, 24h, 7d, 14d, 30d, 200d, 1y. Comma-separated values, invalid values will be discarded.
locale (str, optional) – Locale setting for language preferences. Default is ‘en’. Valid values include ‘ar’, ‘bg’, ‘cs’, ‘da’, ‘de’, ‘el’, ‘en’, ‘es’, ‘fi’, ‘fr’, ‘he’, ‘hi’, ‘hr’, ‘hu’, ‘id’, ‘it’, ‘ja’, ‘ko’, ‘lt’, ‘nl’, ‘no’, ‘pl’, ‘pt’, ‘ro’, ‘ru’, ‘sk’, ‘sl’, ‘sv’, ‘th’, ‘tr’, ‘uk’, ‘vi’, ‘zh’, ‘zh-tw’.
precision (str, optional) – Decimal precision for currency price value. Optional. Valid values are 0-18.

Returns:

A DataFrame containing the market data of coins, with columns for each specified field.

Return type:

pd.DataFrame

Raises:

HTTPError – If the HTTP request fails.

Notes

Works with the coins/markets endpoint.
Available for public and pro API users.

companies_holdings(coin_id: str = 'bitcoin') → DataFrame

Fetches data on public companies’ Bitcoin or Ethereum holdings from the CoinGecko API.

This method queries the CoinGecko API to retrieve data about public companies’ holdings of Bitcoin or Ethereum, ordered by total holdings in descending order.

Parameters:: coin_id (str) – The coin identifier (‘bitcoin’ or ‘ethereum’).
Returns:: A DataFrame containing data on public companies’ Bitcoin or Ethereum holdings.
Return type:: pd.DataFrame
Raises:: HTTPError – If the HTTP request fails.

Notes

Works with the companies/public_treasury/{coin_id} endpoint.
Available for public and pro API users.

contract_historical_market_data(platform_id: str, contract_address: str, vs_currency: str = 'usd', days: Union[int, str] = 'max', from_date: str = None, to_date: str = None, precision: str = None, timezone_str: str = 'UTC') → DataFrame

Fetch historical market data (price, market cap, 24h volume) for a token from its contract address.

Parameters:

platform_id (str) – The ID of the platform issuing tokens (e.g., ‘ethereum’).
contract_address (str) – Token’s contract address.
vs_currency (str, optional) – The target currency of market data (e.g., ‘usd’, ‘eur’).
days (Union[int, str], optional) – Data up to a number of days ago (e.g., ‘1’, ‘30’, ‘max’).
from_date (str, optional) – From date in ‘mm-dd-yyyy’ format or UNIX Timestamp. Optional.
to_date (str, optional) – To date in ‘mm-dd-yyyy’ format or UNIX Timestamp. Optional.
precision (str, optional) – Decimal precision for currency price value. Defaults to None.
timezone_str (str, optional) – Timezone of the dates. Default is ‘UTC’.

Returns:

A DataFrame containing historical market data including price, market cap, and 24h volume.

Return type:

pd.DataFrame

Raises:

HTTPError – If the HTTP request fails.

Notes

Works with the coins/{id}/contract/{contract_address}/market_chart endpoint.
Available for public and pro API users.

cryptocurrency_categories_list() → DataFrame

Fetches a list of all cryptocurrency categories from the CoinGecko API.

This method queries the CoinGecko API to retrieve a list of all cryptocurrency categories. The data is updated every 5 minutes.

Returns:: A DataFrame containing the list of cryptocurrency categories.
Return type:: pd.DataFrame
Raises:: HTTPError – If the HTTP request fails.

Notes

Works with the coins/categories/list endpoint.
Available for public and pro API users.

derivatives_exchange_info(exchange_id: str = 'binance_futures', include_tickers: str = None) → DataFrame

Fetches detailed data for a specific derivative exchange from the CoinGecko API.

This method queries the CoinGecko API to retrieve detailed data for a given derivative exchange, including optional tickers’ data. The data is updated every 30 seconds.

Parameters:

exchange_id (str, optional) – The ID of the exchange. Exchange IDs can be obtained from get_derivatives_exchanges_list method. Defaults to ‘binance_futures’.
include_tickers (str, optional) – Option to include tickers data. Valid values are ‘all’, ‘unexpired’, or leave blank to omit tickers data in the response. Defaults to None.

Returns:

A DataFrame containing detailed data for the specified derivative exchange.

Return type:

pd.DataFrame

Raises:

HTTPError – If the HTTP request fails.

Notes

Works with the derivatives/exchanges/{id} endpoint.
Available for public and pro API users.

derivatives_exchanges_list(order: str = None, per_page: int = 100, page: int = 1) → DataFrame

Fetches a list of all derivative exchanges from the CoinGecko API.

This method queries the CoinGecko API to retrieve a list of all derivative exchanges. The data is updated every 60 seconds.

Parameters:

order (str, optional) – Order results using params like ‘name_asc’, ‘name_desc’, ‘open_interest_btc_asc’, ‘open_interest_btc_desc’, ‘trade_volume_24h_btc_asc’, ‘trade_volume_24h_btc_desc’. Defaults to None.
per_page (int, optional) – Total results per page. Defaults to 100.
page (int, optional) – Page number for results pagination. Defaults to 1.

Returns:

A DataFrame containing the list of all derivative exchanges.

Return type:

pd.DataFrame

Raises:

HTTPError – If the HTTP request fails.

Notes

Works with the derivatives/exchanges endpoint.
Available for public and pro API users.

derivatives_market_tickers() → DataFrame

Fetches a list of all derivative tickers from the CoinGecko API.

This method queries the CoinGecko API to retrieve a list of all derivative tickers. Note: ‘open_interest’ and ‘volume_24h’ data are in USD. The data is updated every 30 seconds.

Returns:: A DataFrame containing the list of all derivative tickers.
Return type:: pd.DataFrame
Raises:: HTTPError – If the HTTP request fails.

Notes

Works with the derivatives/tickers endpoint.
Available for public and pro API users.

end_session() → str

Closes the HTTP session.

Returns:: A message indicating the status of the session closure.
Return type:: str

exchange_historical_volume(exchange_id: str = 'gdax', days: Union[int, str] = 30, from_date: str = None, to_date: str = None) → DataFrame

Fetches either rolling or historical volume data (in BTC) for a given exchange.

Parameters:

exchange_id (str, optional) – The ID of the exchange. Defaults to ‘gdax’.
days (Union[int, str], optional) – Number of days for the rolling data. Defaults to 30.
from_date (str, optional) – The start date for historical data in ‘mm-dd-yyyy’ format.
to_date (str, optional) – The end date for historical data in ‘mm-dd-yyyy’ format.

Returns:

A DataFrame containing the volume data of the exchange.

Return type:

pd.DataFrame

Raises:

HTTPError – If the HTTP request fails.
ValueError – If the date range exceeds 31 days.

Notes

Works with the exchanges/{id}/volume_chart endpoint.
Available for public and pro API users.

exchange_market_tickers(exchange_id: str, coin_ids: Optional[str] = None, include_exchange_logo: str = 'false', page: int = 1, depth: str = 'false', order: str = 'trust_score_desc') → DataFrame

Fetches paginated tickers for a specific exchange from the CoinGecko API.

This method queries the CoinGecko API to retrieve tickers for a given exchange, with options to filter by coin IDs, include exchange logos, specify page number, show 2% orderbook depth, and sort the results.

Parameters:

exchange_id (str) – The ID of the exchange (e.g., ‘binance’). Exchange IDs can be obtained from get_exchange_list method.
coin_ids (Optional[str], optional) – Filter tickers by coin IDs. Defaults to None.
include_exchange_logo (str, optional) – Flag to show exchange logo. Valid values: ‘true’, ‘false’. Defaults to ‘false’.
page (int, optional) – Page number to paginate through results. Defaults to 1.
depth (str, optional) – Flag to show 2% orderbook depth. Valid values: ‘true’, ‘false’. Defaults to ‘false’.
order (str, optional) – Sort order of the results. Valid values: ‘trust_score_desc’ (default), ‘trust_score_asc’, ‘volume_desc’.

Returns:

A DataFrame containing the exchange tickers with the specified filters and options.

Return type:

pd.DataFrame

Raises:

HTTPError – If the HTTP request fails.

Notes

‘is_stale’ is true for a ticker not updated for more than 8 hours.
‘is_anomaly’ is true if a ticker’s price is an outlier.
Works with the exchanges/{id}/tickers endpoint.
Available for public and pro API users.

exchange_volume_data(exchange_id: str = 'gdax') → DataFrame

Fetches the volume in BTC and top 100 tickers for a specific exchange from the CoinGecko API.

This method queries the CoinGecko API to retrieve the exchange volume in BTC and information about the top 100 tickers of a given exchange. For derivatives, a different endpoint is suggested.

Parameters:: exchange_id (str) – The ID of the exchange (e.g., ‘binance’). Exchange IDs can be obtained from the get_supported_exchanges endpoint.
Returns:: A dictionary containing the exchange volume in BTC and information about the top 100 tickers.
Return type:: json
Raises:: HTTPError – If the HTTP request fails.

Notes

Ticker object is limited to 100 items. For more tickers, use the get_exchange_tickers method.
‘is_stale’ is true for a ticker not updated from the exchange for more than 8 hours.
‘is_anomaly’ is true if a ticker’s price is an outlier.
The user is responsible for managing the display of these information (e.g., footnotes, different background, etc.).
Works with the exchanges/{id} endpoint.
Available for public and pro API users.

gainers_losers(vs_currency: str = 'usd', duration: str = '24h', top_coins: int = 1000) → Tuple[DataFrame, DataFrame]

Fetches the top 30 coins with the largest price gains and losses for a specific duration.

This method queries the CoinGecko API to retrieve the top 30 coins with the largest price gains and losses by a specific time duration. The data is updated every 5 minutes.

Note: Access to this endpoint requires a paid plan (e.g., Analyst, Lite, Pro, Enterprise).

Parameters:

vs_currency (str, optional) – The target currency for market data. Default is ‘usd’.
duration (str, optional) – The time duration for the price change (e.g., ‘1h’, ‘24h’). Options include: ‘1h’, ‘24h’, ‘7d’, ‘14d’, ‘30d’, ‘60d’, ‘1y’. Default is ‘24h’.
top_coins (int, optional) – The number of top coins to include. Default is 1000.

Returns:

A tuple of DataFrames containing the top gainers and losers.

Return type:

Tuple[pd.DataFrame, pd.DataFrame]

Raises:

HTTPError – If the HTTP request fails.

Notes

Works with the coins/top_gainers_losers endpoint.
Available for pro and enterprise API users only.

global_crypto_stats() → Tuple

Fetches global cryptocurrency data from the CoinGecko API.

This method queries the CoinGecko API to retrieve global cryptocurrency data, including total volume, total market cap, ongoing ICOs, and other relevant details. The data is updated every 10 minutes.

Returns:: A DataFrame containing global cryptocurrency data.
Return type:: Tuple
Raises:: HTTPError – If the HTTP request fails.

Notes

Works with the global endpoint.
Available for public and pro API users.

global_defi_stats() → DataFrame

Fetches global decentralized finance (DeFi) data from the CoinGecko API.

This method queries the CoinGecko API to retrieve global DeFi data, including market capitalization in USD, Ethereum market capitalization, DeFi to Ethereum ratio, 24-hour trading volume, DeFi dominance, and the top DeFi coin’s name and dominance. The data is updated every 60 minutes.

Returns:: A DataFrame containing global DeFi data.
Return type:: pd.DataFrame
Raises:: HTTPError – If the HTTP request fails.

Notes

Works with the global/decentralized_finance_defi endpoint.
Available for public and pro API users.

historical_global_market_cap(days: Union[int, str] = 'max', vs_currency: str = 'usd') → tuple

Fetches historical global market cap and volume data from the CoinGecko API.

This method queries the CoinGecko API to retrieve historical global market cap and volume data, based on the specified number of days from now.

Parameters:

days (Union[int, str], optional) – Number of days from now for the historical data. Defaults to ‘max’.
vs_currency (str, optional) – The target currency for market data. Defaults to ‘usd’.

Returns:

A tuple of DataFrames containing historical global market cap and volume data.

Return type:

tuple

Raises:

HTTPError – If the HTTP request fails.

Notes

Works with the global/market_cap_chart endpoint.
Available for pro and enterprise API users only.

multiple_coins_historical_data(coin_ids: list, vs_currency: str = 'usd', days: Union[int, str] = 'max', interval: str = 'daily', precision: str = 'full', from_date: str = None, to_date: str = None, timezone_str: str = 'UTC') → dict

Get historical market data for multiple coins and separate the data into different DataFrames.

Parameters:

coin_ids (list) – List of coin IDs (e.g., [‘bitcoin’, ‘ethereum’, ‘tether’]). Refers to coins listed in get_coins_list method. Required.
vs_currency (str, optional) – The target currency of market data (usd, eur, jpy, etc.). Default is ‘usd’.
days (Union[int, str], optional) – Data up to a number of days ago or ‘max’ for maximum available data. Default is ‘max’.
interval (str, optional) – Data interval. Possible value: ‘daily’.
precision (str, optional) – Decimal precision for currency price value. Defaults to ‘full’.
from_date (str, optional) – From date in ‘mm-dd-yyyy’ format or UNIX Timestamp. Default is None.
to_date (str, optional) – To date in ‘mm-dd-yyyy’ format or UNIX Timestamp. Default is None.
timezone_str (str, optional) – Timezone of the dates. Default is ‘UTC’.

Returns:

A dictionary containing DataFrames for prices, market caps, and total volumes. Each DataFrame’s: columns represent different coins.

Return type:

dict

Raises:

HTTPError – If the HTTP request fails.

Notes

Cache expiration times vary: 30 seconds for 1 day, 30 minutes for 2-90 days, and 12 hours for more than 90 days.
The last completed UTC day’s data is available 35 minutes after midnight on the next UTC day (00:35), and the cache always expires at 00:40 UTC.
Works with the coins/{id}/market_chart and coins/{id}/market_chart/range endpoints.
Available for public and pro API users.

multiple_coins_ohlc_data(coin_ids: list, vs_currency: str = 'usd', days: Union[int, str] = 'max', precision: str = None)

Fetch the OHLC (Open, High, Low, Close) data for multiple coins and return separate DataFrames for each.

Note on data granularity for public API users:

1 to 2 days: Data granularity is 30 minutes.
3 to 30 days: Data granularity is 4 hours.
31 days and beyond: Data granularity is 4 days.

For paid plan users, ‘daily’ interval can be used by setting the interval parameter.

Rate Limits:

Cache/Update Frequency: Every 30 minutes.
The last completed UTC day’s data is available 35 minutes after midnight on the next UTC day.

Parameters:

coin_ids (list) – List of coin IDs (e.g., [‘bitcoin’, ‘ethereum’]). Refers to coins listed using get_coins_list method.
vs_currency (str, optional) – The target currency of market data. Default is ‘usd’.
days (Union[int, str], optional) – Data up to number of days ago (e.g., ‘1’, ‘7’, ‘14’, ‘30’, ‘90’, ‘180’, ‘365’, ‘max’). Default is ‘max’.
precision (str, optional) – Precision for currency price value.

Returns:

A dictionary containing DataFrames for Open, High, Low, Close values for each coin.

Return type:

dict

Raises:

HTTPError – If the HTTP request fails.

Notes

The ‘daily’ interval is available only for paid plan users for the periods 1/7/14/30/90/180 days.
Data is cached and updated every 30 minutes. The last completed UTC day’s data is available 35 minutes after midnight on the next UTC day (00:35).
Works with the coins/{id}/ohlc endpoint.
Available for public and pro API users.

new_coins_listed() → DataFrame

Fetches the latest 200 coins recently listed on CoinGecko.

This method queries the CoinGecko API to retrieve the latest 200 coins that were recently listed on CoinGecko.com, along with their IDs, symbols, names, and activation times. The data is updated every 30 seconds.

Note: Access to this endpoint requires a paid plan (e.g., Analyst, Lite, Pro, Enterprise).

Returns:: A DataFrame containing the latest 200 coins listed on CoinGecko.
Return type:: pd.DataFrame
Raises:: HTTPError – If the HTTP request fails.

Notes

Works with the coins/listed/new endpoint.
Available for pro and enterprise API users only.

nft_collection_info(nft_id: str = None, asset_platform_id: str = None, contract_address: str = None) → DataFrame

Fetches current data for a specific NFT collection from the CoinGecko API.

This method queries the CoinGecko API to retrieve current data for a given NFT collection, identified either by its ID or by its asset platform ID and contract address. The data is updated every 60 seconds.

Parameters:

nft_id (str, optional) – The ID of the NFT collection. Can be obtained from get_supported_nfts method.
asset_platform_id (str, optional) – The ID of the platform issuing tokens. See the asset_platforms endpoint for options.
contract_address (str, optional) – The contract address of the NFT collection. Can be obtained from get_supported_nfts method.

Returns:

A DataFrame containing current data for the specified NFT collection.

Return type:

pd.DataFrame

Raises:

ValueError – If neither nft_id nor both asset_platform_id and contract_address are provided.
HTTPError – If the HTTP request fails.

Notes

Works with the nfts/{id} and nfts/{asset_platform_id}/contract/{contract_address}.
Available for public and pro API users.

Raises:: ValueError – If neither nft_id nor both asset_platform_id and contract_address are provided.

nft_collections_info(nft_ids: list = None, asset_platform_id: str = None, contract_addresses: list = None) → DataFrame

Fetches current data for multiple NFT collections from the CoinGecko API.

This method queries the CoinGecko API to retrieve current data for multiple NFT collections, identified either by a list of their IDs or by a combination of an asset platform ID and a list of contract addresses. The data is updated every 60 seconds.

Parameters:

nft_ids (list, optional) – A list of NFT collection IDs.
asset_platform_id (str, optional) – The ID of the platform issuing tokens. See the asset_platforms endpoint.
contract_addresses (list, optional) – A list of contract addresses of NFT collections.

Returns:

A DataFrame containing current data for the specified NFT collections.

Return type:

pd.DataFrame

Raises:

HTTPError – If the HTTP request fails.
ValueError – If neither nft_ids nor both asset_platform_id and contract_addresses are provided.

Notes

Works with the nfts/{id} endpoint.
Also works with nfts/{asset_platform_id}/contract/{contract_address} endpoint.
Available for public and pro API users.

Raises:: ValueError – If neither nft_ids nor both asset_platform_id and contract_addresses are provided.

nft_historical_data(nft_id: str = None, asset_platform_id: str = None, contract_address: str = None, days: Union[int, str] = 'max') → DataFrame

Fetches historical market data of a specific NFT collection from the CoinGecko API using either the NFT ID or the asset platform ID and contract address.

Parameters:

nft_id (str, optional) – The ID of the NFT collection. Defaults to None.
asset_platform_id (str, optional) – The ID of the asset platform (e.g., ‘ethereum’). Defaults to None.
contract_address (str, optional) – The contract address of the NFT collection. Defaults to None.
days (Union[int, str]) – Number of days from now for the historical data. Defaults to ‘max’.

Returns:

A DataFrame containing historical market data for the specified NFT collection.

Return type:

pd.DataFrame

Raises:

ValueError – If neither nft_id nor both asset_platform_id and contract_address are provided.
HTTPError – If the HTTP request fails.

Notes

Works with the nfts/{id}/market_chart and
nfts/{asset_platform_id}/contract/{contract_address}/market_chart endpoints.
Available for pro and enterprise API users only.

nft_market_data(asset_platform_id: str = None, order: str = None, per_page: int = 100, page: int = 1) → DataFrame

Fetches a list of supported NFTs with market data from the CoinGecko API.

This method queries the CoinGecko API to retrieve a list of all supported NFTs, including floor price, market cap, volume, and other market-related data. The data is updated every 5 minutes.

Note: Access to this endpoint requires a paid plan (e.g., Analyst, Lite, Pro, Enterprise).

Parameters:

asset_platform_id (str, optional) – The id of the platform issuing tokens. Defaults to None.
order (str, optional) – Order results using parameters like ‘h24_volume_native_desc’. Defaults to None.
per_page (int, optional) – Total results per page. Defaults to 100.
page (int, optional) – Page number to paginate through results. Defaults to 1.

Returns:

A DataFrame containing the list of supported NFTs with market data.

Return type:

pd.DataFrame

Raises:

HTTPError – If the HTTP request fails.

Notes

Works with the nfts/markets endpoint.
Available for pro and enterprise API users only.

nft_market_tickers(nft_id: str) → DataFrame

Fetches the latest floor price and 24h volume of an NFT collection on each NFT marketplace.

This method queries the CoinGecko API to retrieve the latest floor price and 24-hour volume data for a specific NFT collection, as listed on various NFT marketplaces.

Note: Access to this endpoint requires a paid plan (e.g., Analyst, Lite, Pro, Enterprise).

Parameters:: nft_id (str) – The ID of the NFT collection.
Returns:: A DataFrame containing the floor price and 24h volume data of the NFT collection on different marketplaces.
Return type:: pd.DataFrame
Raises:: HTTPError – If the HTTP request fails.

Notes

Works with the nfts/{id}/tickers endpoint.
Available for pro and enterprise API users only.

nfts_supported(order: str = 'market_cap_usd_desc', asset_platform_id: str = None, per_page: int = 100, page: int = 1) → DataFrame

Fetches a list of all supported NFT ids from the CoinGecko API, paginated by 100 items per page.

This method queries the CoinGecko API to retrieve a list of all NFT ids, with options for ordering, specifying the asset platform, and paginating the results. The data is updated every 5 minutes.

Parameters:

order (str, optional) – Order results by specific fields. Valid values include h24_volume_native_asc/desc, floor_price_native_asc/desc, market_cap_native_asc/desc, market_cap_usd_asc/desc. Defaults to None.
asset_platform_id (str, optional) – The id of the platform issuing tokens. See asset_platforms endpoint for list of options. Defaults to None.
per_page (int, optional) – Total results per page, valid values from 1 to 250. Defaults to 100.
page (int, optional) – Page number for results pagination. Defaults to 1.

Returns:

A DataFrame containing the list of all NFTs with their ids, contract addresses, names, etc.

Return type:

pd.DataFrame

Raises:

HTTPError – If the HTTP request fails.

Notes

Works with the nfts/list endpoint.
Available for public and pro API users.

search_coingecko(query: str) → dict

Searches for coins, categories, and markets on CoinGecko.

This method queries the CoinGecko API to search for coins, categories, and markets listed on CoinGecko, ordered by largest Market Cap first. The data is updated every 15 minutes.

Parameters:: query (str) – The search string.
Returns:: A dictionary containing the search results as DataFrames.
Return type:: dict
Raises:: HTTPError – If the HTTP request fails.

Notes

Works with the search endpoint.
Available for public and pro API users.

simple_prices(coin_ids: list = None, vs_currencies: list = 'usd', include_market_cap: bool = False, include_24hr_vol: bool = False, include_24hr_change: bool = False, include_last_updated_at: bool = False, precision: str = None, platform_id: str = None, contract_addresses: list = None) → DataFrame

Get the current prices of specified cryptocurrencies in the desired currencies.

This method fetches current prices from the CoinGecko API for cryptocurrencies by either coin_ids or with platform_id and contract_addresses specified. Specifying platform_id and contract_addresses queries prices using their contract addresses on a specified platform. Otherwise, a list of coin_ids must be specified.

Parameters:

coin_ids (str or list) – A single coin ID or list of coin IDs for cryptocurrencies (e.g., ‘bitcoin’ or [‘bitcoin’, ‘ethereum’]). Refers to coins listed using the get_coin_list method.
vs_currencies (str or list, optional) – A single target currency or list of target currencies for price conversion (e.g., ‘usd’ or [‘usd’, ‘eur’]). Refers to supported vs_currencies. Defaults to ‘usd’.
include_market_cap (bool, optional) – Include market cap in the response. Defaults to False.
include_24hr_vol (bool, optional) – Include 24-hour volume. Defaults to False.
include_24hr_change (bool, optional) – Include 24-hour price change. Defaults to False.
include_last_updated_at (bool, optional) – Include the last updated timestamp of the price. Defaults to False.
precision (str, optional) – Specify decimal precision for currency price value, ranging from 0 to 18. Defaults to full precision.
platform_id (str, optional) – ID of the platform issuing tokens (e.g., ‘ethereum’). See asset_platforms endpoint for options. Required for querying token prices.
contract_addresses (list, optional) – Contract addresses of tokens, comma-separated. Required for querying token prices.

Returns:

A DataFrame containing the current prices and additional requested data.

Return type:

pd.DataFrame

Raises:

HTTPError – If the HTTP request fails.

Notes

The method returns the global average price aggregated across all active exchanges.
It does not return the price of a specific network; cross-check on CoinGecko.com for network-specific prices.
Data is cached and updated every 60 seconds (30 seconds for Pro API users).
The ‘include_24hr_change=true’ parameter can be used to check if the 24-hour change returns a ‘null’ value.
Prices are returned in the specified vs_currencies.
The method supports both cryptocurrencies and token prices via contract addresses.
Works with the simple/price endpoint.
Available for public and pro API users.

status_check() → dict

Check API server status

Returns:: API server status
Return type:: dict

supported_currencies() → list

Fetch the list of supported vs_currencies (versus currencies) from the CoinGecko API.

This method queries the CoinGecko API to retrieve a list of all supported currencies against which cryptocurrency prices can be compared.

Returns:: A list of supported versus currencies.
Return type:: list
Raises:: HTTPError – If the HTTP request fails.

Notes

The data is updated every 60 seconds.
Works with the simple/supported_vs_currencies endpoint.
Available for public and pro API users.

top_coins_market_data(top_n: int = 250) → DataFrame

Fetch market data for the top N cryptocurrencies by market cap.

This method paginates through the CoinGecko API to retrieve the market data for the specified number of top cryptocurrencies.

Parameters:: top_n (int, optional) – The number of top cryptocurrencies to fetch. Default is 250.
Returns:: A DataFrame containing the market data of the top N cryptocurrencies.
Return type:: pd.DataFrame
Raises:: HTTPError – If the HTTP request fails.

Notes

Works with the coins/markets endpoint.
Available for public and pro API users.

trending_searches() → DataFrame

Fetches the top-7 trending search coins on CoinGecko in the last 24 hours.

This method queries the CoinGecko API to retrieve the top-7 trending coins as searched by users in the last 24 hours, ordered by most popular first. The data is updated every 10 minutes.

Returns:: A DataFrame containing the list of top-7 trending coins, ordered by most popular first.
Return type:: pd.DataFrame
Raises:: HTTPError – If the HTTP request fails.

Notes

Works with the search/trending endpoint.
Available for public and pro API users.