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

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.

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.

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

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 offers various API plans tailored to different user needs. Below is a summary table of the key features of each plan:

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.

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  

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

api.status_check()

api.simple_prices(coin_ids)

api.supported_currencies()

api.coins_list()

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

api.coin_info(coin_id='bitcoin')

api.coin_market_tickers(coin_id='bitcoin')

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

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

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')

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

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

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

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

api.asset_platforms_list()

api.cryptocurrency_categories_list()

api.categories_market_data()

api.active_exchanges_list()

api.all_exchanges_list()

api.exchange_volume_data(exchange_id='binance')

api.exchange_market_tickers(exchange_id='binance')

api.exchange_historical_volume(exchange_id='binance')

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

api.derivatives_market_tickers()

api.derivatives_exchanges_list()

api.derivatives_exchange_info(exchange_id='binance_futures')

api.all_derivatives_exchanges_list()

api.nfts_supported()

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

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

api.btc_exchange_rates()

api.search_coingecko(query='bitcoin')

api.trending_searches()

api.global_crypto_stats()

api.global_defi_stats()

api.companies_holdings(coin_id='bitcoin')

api.new_coins_listed()

api.gainers_losers()

api.historical_global_market_cap()

api.nft_market_data()

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

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

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

api.coin_circulating_supply_history(coin_id='bitcoin')

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

api.coin_total_supply_history(coin_id='bitcoin')

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

api.all_tokens_list(asset_platform_id='ethereum')

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

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.

• Add asynchronous functionality to improve performance.

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

Notable changes can be found in the Change Log.

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

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