pycgapi 0.1.4

Description:

pycgapi 0.1.4

Table of Contents

Overview
Features
Installation
API Key
Quick Start
Usage Examples
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)


Running on Docker
Testing
Roadmap
Contributing
Change Log
License
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:

Simplified Endpoints: Access to CoinGecko's extensive cryptocurrency data through easy-to-use Python methods.
Comprehensive Data Access: Fetch latest prices, market caps, trading volumes, historical data, and more for over
thousands of cryptocurrencies.
Enhanced Functionality for Pro Users: Special endpoints for Pro API users, including faster data updates and
access to exclusive data sets.
Multi-Category Support: Access to various categories, including coins, exchanges, derivatives,
decentralized finance (DeFi), and non-fungible tokens (NFTs).
Historical Data Retrieval: Obtain historical market data with customizable granularity, providing valuable
insights into cryptocurrency trends and movements.
Global Cryptocurrency Statistics: Overview of global cryptocurrency statistics, including market caps, trading
volumes, and dominance percentages.
Rate Limit Management: Handles API rate limits efficiently, ensuring seamless data retrieval without hitting
rate limits.
Error Handling and Reporting: Comprehensive error handling to report and manage API request issues effectively.
Real-time Data Updates: Offers real-time updates on cryptocurrency prices and market changes, crucial for timely
analysis and decision-making.
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 (Beta)
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 (Beta) API:
from pycgapi import CoinGeckoAPI
api = CoinGeckoAPI() # no API key required for public 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) # must provide api_key and set pro_api=True

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


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

api.coin_market_tickers(coin_id='bitoin')


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

api.coin_historical_on_date(coin_id='bitoin', 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='bitoin')
api.multiple_coins_historical_data(coin_ids=['bitoin', '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='bitoin', from_date='12-31-2022', to_date='12-31-2023')
api.multiple_coins_historical_data(coin_ids=['bitoin', '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='bitoin')
api.multiple_coins_ohlc_data(coin_ids=['bitoin', '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:


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 .



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.