Table of Contents

1. Overview
2. Features
3. Installation
4. API Key
5. Quick Start
6. Usage Examples
7. Available Methods
   • ping
   • simple
   • coins
   • contract
   • asset_platforms
   • categories
   • exchanges
   • derivatives
   • nfts (beta)
   • exchange_rates
   • search
   • trending
   • global
   • companies (beta)
   • paid plan (exclusive)
   • enterprise plan (exclusive)
8. Running on Docker
9. Testing
10. Roadmap
11. Contributing
12. Change Log
13. License
14. Contact

Overview

pycgapi is an unofficial Python wrapper for the CoinGecko API (V3). It's designed to process API endpoint responses into easy-to-use pandas DataFrames wherever possible. From simple price checks to complex historical data analysis, pycgapi facilitates seamless integration with the CoinGecko API. For more information on the official CoinGecko API, please refer to the official documentation.

Features

pycgapi provides a user-friendly and efficient way to interact with the CoinGecko API. It simplifies the process of retrieving cryptocurrency data, offering the following features:

1. Simplified Endpoints: Access to CoinGecko's extensive cryptocurrency data through easy-to-use Python methods.
2. Comprehensive Data Access: Fetch latest prices, market caps, trading volumes, historical data, and more for over thousands of cryptocurrencies.
3. Enhanced Functionality for Pro Users: Special endpoints for Pro API users, including faster data updates and access to exclusive data sets.
4. Multi-Category Support: Access to various categories, including coins, exchanges, derivatives, decentralized finance (DeFi), and non-fungible tokens (NFTs).
5. Historical Data Retrieval: Obtain historical market data with customizable granularity, providing valuable insights into cryptocurrency trends and movements.
6. Global Cryptocurrency Statistics: Overview of global cryptocurrency statistics, including market caps, trading volumes, and dominance percentages.
7. Rate Limit Management: Handles API rate limits efficiently, ensuring seamless data retrieval without hitting rate limits.
8. Error Handling and Reporting: Comprehensive error handling to report and manage API request issues effectively.
9. Real-time Data Updates: Offers real-time updates on cryptocurrency prices and market changes, crucial for timely analysis and decision-making.
10. Easy Integration: Designed for easy integration into financial analysis tools, trading bots, and cryptocurrency applications.

pycgapi is ideal for cryptocurrency enthusiasts, financial analysts, data scientists, and developers seeking a robust and comprehensive solution for accessing CoinGecko's extensive cryptocurrency data.

Installation

To install pycgapi, simply run:

pip install pycgapi

Or, clone from GitHub and install:

git clone https://github.com/nathanramoscfa/pycgapi.git
cd pycgapi
python setup.py install

API Key

You do not need an API key to use the Public API. You will need an API key to use the Pro API. To obtain an API key, please visit the CoinGecko API page and follow the instructions. This package comes bundled with keyring to save and retrieve your API key securely without having to hardcode it. To save your API key, simply run the following code in a Python console or Jupyter Notebook:

import keyring
keyring.set_password('coingecko', 'api_key', 'MY_API_KEY')  # replace MY_API_KEY with your API key
print(keyring.get_password('coingecko', 'api_key'))

Output:

'MY_API_KEY'

CoinGecko API Plans and Rate Limits

CoinGecko offers various API plans tailored to different user needs. Below is a summary table of the key features of each plan:

Plan	Monthly Price	Annual Price (Monthly)	Rate Limit/Min	Call Credits (Monthly
Demo	Free	Free	10-30	10K
Analyst	$129	$103	500	500K
Lite	$499	$399	500	2M
Pro	$999	$799	1000	5M
Enterprise	Custom Pricing	Custom Pricing	Custom	Custom

Quick Start

To initialize the pycgapi client, simply run the following code based on your API plan:

Demo API:

import keyring
from pycgapi import CoinGeckoAPI
api_key = keyring.get_password('coingecko', 'api_key')  # gets your API key
api = CoinGeckoAPI(api_key, pro_api=False)  # set pro_api=False for demo API

Paid Plan API:

import keyring
from pycgapi import CoinGeckoAPI
api_key = keyring.get_password('coingecko', 'api_key')  # gets your API key
api = CoinGeckoAPI(api_key, pro_api=True)  # set pro_api=True for paid API

Ping the CoinGecko API server:

api.status_check()

Output:

API Server Status: {'gecko_says': '(V3) To the Moon!'}

The output above confirms a successful connection to the CoinGecko API server.

Usage Examples

For detailed examples of all endpoints, see the examples directory. Here are a few examples of pycgapi:

Get a list of all supported coins:

coins = api.coins_list()
coins.head()

Output:

                    symbol                 name
id                                             
01coin                 zoc               01coin
0chain                 zcn                  Zus
0-knowledge-network    0kn  0 Knowledge Network
0-mee                  ome                O-MEE
0vix-protocol          vix        0VIX Protocol

Get a list of all supported coins with price, volume, and market-related data:

coins = api.coins_market_data()[['symbol', 'name', 'current_price', 'market_cap', 'total_volume']]
print(coins.head())

Output:

            symbol      name  current_price    market_cap  total_volume
id                                                                     
bitcoin        btc   Bitcoin      43410.000  850590460912   29791306848
ethereum       eth  Ethereum       2223.840  267274033503   18135533011
tether        usdt    Tether          1.002   92977544355   51440182305
binancecoin    bnb       BNB        311.890   48011725773    1578466144
solana         sol    Solana         96.810   41708642386    3237650635

Get a list of supported fiat-currencies:

supported_vs_currencies = api.supported_currencies()
print('Available Vs. Currencies: {}'.format(sorted(supported_vs_currencies)))

Output:

Available Vs. Currencies: ['aed', 'ars', 'aud', 'bch', 'bdt', 'bhd', 'bits', 'bmd', 'bnb', 'brl', 'btc', 'cad', 'chf', 
'clp', 'cny', 'czk', 'dkk', 'dot', 'eos', 'eth', 'eur', 'gbp', 'gel', 'hkd', 'huf', 'idr', 'ils', 'inr', 'jpy', 'krw', 
'kwd', 'link', 'lkr', 'ltc', 'mmk', 'mxn', 'myr', 'ngn', 'nok', 'nzd', 'php', 'pkr', 'pln', 'rub', 'sar', 'sats', 'sek', 
'sgd', 'thb', 'try', 'twd', 'uah', 'usd', 'vef', 'vnd', 'xag', 'xau', 'xdr', 'xlm', 'xrp', 'yfi', 'zar']

Get the current price of a list of cryptocurrencies:

coin_ids = ['bitcoin', 'ethereum', 'tether', 'binancecoin', 'solana']
price = api.get_simple_prices(coin_ids)
price

Output:

                     usd
binancecoin    320.25000
bitcoin      43201.00000
ethereum      2239.91000
solana         101.26000
tether           0.99994

Get the historical market data for a list of cryptocurrencies:

coin_ids = ['bitcoin', 'ethereum', 'tether', 'binancecoin', 'solana']
coins_historical_data = api.multiple_coins_historical_data(coin_ids)
print('Available Keys: {}'.format(sorted(coins_historical_data.keys())))
coins_historical_data['price'].head()

Output:

100%|██████████| 5/5 [00:01<00:00,  2.68it/s]
Available Keys: ['market_cap', 'price', 'total_volume']

                               bitcoin    ethereum    tether  binancecoin  \
timestamp                                                                   
2020-04-11 00:00:00+00:00  6864.694257  157.740158  1.001752    13.718826   
2020-04-12 00:00:00+00:00  6878.781213  158.327878  1.001414    13.826759   
2020-04-13 00:00:00+00:00  6913.158787  158.863826  0.996086    14.265117   
2020-04-14 00:00:00+00:00  6857.538538  156.701359  0.998972    15.045573   
2020-04-15 00:00:00+00:00  6860.178536  158.267151  1.000622    15.582721   

                             solana  
timestamp                            
2020-04-11 00:00:00+00:00  0.957606  
2020-04-12 00:00:00+00:00  0.784711  
2020-04-13 00:00:00+00:00  0.875994  
2020-04-14 00:00:00+00:00  0.786712  
2020-04-15 00:00:00+00:00  0.666673  

Available Methods

pycgapi offers a wide range of methods for accessing cryptocurrency data. For a complete list of available methods, please refer to the documentation.

ping

• /ping - Check API server status.

api.status_check()

simple

• /simple/price - Get the current price of any cryptocurrencies in any other supported currencies that you need.

api.simple_prices(coin_ids)

• /simple/supported_vs_currencies - Get list of supported_vs_currencies.

api.supported_currencies()

coins

• /coins/list - List all supported coins id, name and symbol (no pagination required).

api.coins_list()

• /coins/markets - List all supported coins price, market cap, volume, and market related data.

api.coins_market_data()
api.top_coins_market_data(top_n=10)

• /coins/{id} - Get current data (name, price, market, ... including exchange tickers) for a coin.

api.coin_info(coin_id='bitcoin')

• /coins/{id}/tickers - Get coin tickers (paginated to 100 items).

api.coin_market_tickers(coin_id='bitcoin')

• /coins/{id}/history - Get historical data (name, price, market, stats) at a given date for a coin.

api.coin_historical_on_date(coin_id='bitcoin', date='12-31-2023')

• /coins/{id}/market_chart - Get historical market data include price, market cap, and 24h volume (granularity auto).

api.coin_historical_market_data(coin_id='bitcoin')
api.multiple_coins_historical_data(coin_ids=['bitcoin', 'ethereum', 'tether', 'binancecoin', 'solana'])

• /coins/{id}/market_chart/range - Get historical market data include price, market cap, and 24h volume within a range of timestamp (granularity auto).

api.coin_historical_market_data(coin_id='bitcoin', from_date='12-31-2022', to_date='12-31-2023')
api.multiple_coins_historical_data(coin_ids=['bitcoin', 'ethereum', 'tether'], from_date='12-31-2022',
                                   to_date='12-31-2023')

• /coins/{id}/ohlc - Get coin's OHLC (candlestick) data.

api.coin_ohlc_data(coin_id='bitcoin')
api.multiple_coins_ohlc_data(coin_ids=['bitcoin', 'ethereum', 'tether', 'binancecoin', 'solana'])

contract

• /coins/{id}/contract/{contract_address} - Get coin info from contract address.

api.coin_by_contract(platform_id='ethereum', contract_address='0x5a98fcbea516cf06857215779fd812ca3bef1b32')

• /coins/{id}/contract/{contract_address}/market_chart - Get historical market data include price, market cap, and 24h volume (granularity auto).

api.contract_historical_market_data(platform_id='ethereum',
                                    contract_address='0x5a98fcbea516cf06857215779fd812ca3bef1b32')

• /coins/{id}/contract/{contract_address}/market_chart/range - Get historical market data include price, market cap, and 24h volume within a range of timestamp (granularity auto).

api.contract_historical_market_data(platform_id='ethereum',
                                    contract_address='0x5a98fcbea516cf06857215779fd812ca3bef1b32',
                                    from_date='12-31-2022', to_date='12-31-2023')

asset_platforms

• /asset_platforms - List all asset platforms (Blockchain networks).

api.asset_platforms_list()

categories

• /coins/categories/list - List all categories.

api.cryptocurrency_categories_list()

• /coins/categories - List all categories with market data.

api.categories_market_data()

exchanges

• /exchanges - List all exchanges.

api.active_exchanges_list()

• /exchanges/list - List all exchanges name and identifier.

api.all_exchanges_list()

• /exchanges/{id} - Get exchange volume in BTC and top 100 tickers for a specific exchange.

api.exchange_volume_data(exchange_id='binance')

• /exchanges/{id}/tickers - Get paginated tickers for a specific exchange (paginated, 100 tickers per page).

api.exchange_market_tickers(exchange_id='binance')

• /exchanges/{id}/volume_chart - Get volume_chart data for a specific exchange.

api.exchange_historical_volume(exchange_id='binance')

• /exchanges/{id}/volume_chart/range - Get volume_chart data for a specific exchange within a range of timestamp.

api.exchange_historical_volume(exchange_id='binance', from_date='12-31-2022', to_date='12-31-2023')

derivatives

• /derivatives - List all derivative tickers.

api.derivatives_market_tickers()

• /derivatives/exchanges - List all derivative exchanges.

api.derivatives_exchanges_list()

• /derivatives/exchanges/{id} - Get detailed data for a specific derivatives exchange.

api.derivatives_exchange_info(exchange_id='binance_futures')

• /derivatives/exchanges/list - List all derivatives exchanges name and identifiers.

api.all_derivatives_exchanges_list()

nfts (beta)

• /nfts/list - Get list of all supported NFT ids.

api.nfts_supported()

• /nfts/{id} - Get current data for a specific NFT collection.

api.nft_collection_info(nft_id='bored-ape-yacht-club')
api.nft_collections_info(nft_ids=['cryptopunks', 'bored-ape-yacht-club'])

• nfts/{asset_platform_id}/contract/{contract_address} - Get current data for a specific NFT contract address.

api.nft_collection_info(asset_platform_id='ethereum', contract_address='0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d')

exchange_rates

• /exchange_rates - Get BTC-to-Currency exchange rates.

api.btc_exchange_rates()

search

• /search - Search for coins, categories, and markets listed on CoinGecko.

api.search_coingecko(query='bitcoin')

trending

• /search/trending - Get trending search coins (Top-7) on CoinGecko in the last 24 hours.

api.trending_searches()

global

• /global - Get cryptocurrency global data.

api.global_crypto_stats()

• /global/decentralized_finance_defi - Get cryptocurrency global decentralized finance(defi) data.

api.global_defi_stats()

companies (beta)

• /companies/public_treasury/{coin_id} - Get public companies that hold this coin as part of their treasury.

api.companies_holdings(coin_id='bitcoin')

paid plan (exclusive)

• /coins/list/new - Get the latest 200 coins recented listed on CoinGecko.

api.new_coins_listed()

• /coins/top_gainers_losers - Get the top 30 gainers and losers for a specific duration.

api.gainers_losers()

• /global/market_cap_chart - Get historical global market cap and volume data.

api.historical_global_market_cap()

• /nfts/markets - Get list of supported NFTs with market data.

api.nft_market_data()

• /nfts/{id}/market_chart - Get historical market data of a specific NFT collection by id.

api.get_nft_collection_historical_market_data(nft_id='bored-ape-yacht-club')

• /nfts/{asset_platform_id}/contract/{contract_address}/market_chart - Get historical market data of a specific NFT collection by contract address.

api.nft_historical_data(
   asset_platform_id='ethereum', 
   contract_address='0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d'
)

• /nfts/{id}/tickers - Get the latest floor price and 24h volume of an NFT collection on each NFT marketplace.

api.nft_market_tickers(nft_id='bored-ape-yacht-club')

enterprise plan (exclusive)

• /coins/{id}/circulating_supply_chart - Get historical circulating supply data for a coin.

api.coin_circulating_supply_history(coin_id='bitcoin')

• /coins/{id}/circulating_supply_chart/range - Get historical circulating supply data for a coin within a date range.

api.coin_circulating_supply_history(coin_id='bitcoin', from_date='12-31-2022', to_date='12-31-2023')

• /coins/{id}/total_supply_chart - Get historical total supply data for a coin.

api.coin_total_supply_history(coin_id='bitcoin')

• /coins/{id}/total_supply_chart/range - Get historical total supply data for a coin within a date range.

api.coin_total_supply_history(coin_id='bitcoin', from_date='12-31-2022', to_date='12-31-2023')

• /token_lists/{asset_platform_id}/all.json - Get list of tokens for a specific blockchain network supported by Ethereum token list standard.

api.all_tokens_list(asset_platform_id='ethereum')

Running on Docker

You can run pycgapi inside a Docker container. Below are the steps to build and run the Docker image:

1. Build the Docker Image:

   First, navigate to the root directory of the project in the command prompt and build the Docker image using the following command:

   docker build --no-cache -t pycgapi .

2. Running the Docker Container:

   Once the Docker image is built, you can run the Docker container using the following command:

   docker run -it pycgapi

Testing

To run the test suite with coverage analysis, navigate to the root directory of the project and use the following command:

coverage run -m unittest discover -s tests

This command uses coverage to run all tests in the tests directory and collect coverage data as specified in the .coveragerc file. After running the tests, you can generate a report to see the coverage percentage with:

coverage report

Or, to generate an HTML report showing line-by-line coverage:

coverage html

This will create a new directory named htmlcov. Open the index.html file in this directory with a web browser to view the detailed coverage report.

Roadmap

• Add asynchronous functionality to improve performance.

Contributing

Contributions are welcome! Please feel free to submit pull requests, report bugs, or suggest new features.

Change Log

Notable changes can be found in the Change Log.

License

pycgapi is released under the MIT License. See LICENSE file for more details.

Contact

Find me on LinkedIn or schedule a meeting with me on Calendly.