Reference

pymarketcap.core

class pymarketcap.core.Pymarketcap

Synchronous class for retrieve data from https://coinmarketcap.com.

Parameters:
  • timeout (int, optional) – Set timeout value for requests. As default 20.
  • debug – (bool, optional): Show low level data in get requests. As default, False.
  • proxy_addr (bytes, optional) – Proxy to use with Pymarketcap. As default, b"".

Coinmarketcap API

listings()

List all criptocurrencies with their ids, names, symbol and website slug.

Returns (dict):
Coinmarketcap API raw response.
stats()

Get global cryptocurrencies statistics.

Parameters:convert (str, optional) – return 24h volume, and market cap in terms of another currency. See ticker_badges property to get valid values. As default "USD".
Returns (dict):
Global markets statistics on a raw response.
ticker()

Get currencies with other aditional data. Only returns 100 currencies in each request. Use pymarketcap.Pymarketcap.ticker_all() method for retrieve all currencies navegation through API pagination.

Parameters:
  • currency (str, optional) – Specify a currency to return data, that can be a name, symbol, id or website_slug fields from pymarketcap.core.Pymarketcap.cryptocurrencies property. If you dont specify a currency, returns data for all in coinmarketcap. As default, None.
  • convert (str, optional) – Allows to convert prices, 24h volumes and market capitalizations in terms of one of badges returned by ticker_badges property. As default, "USD".
Returns (dict):
Data from all currencies or a currency from coinmarketcap.
cryptocurrencies

Return all cryptocurrencies listed at coinmarketcap. This is the cached version of public API listings method but without low level fields like "data" and "metadata".

ticker_badges

Badges in which you can convert prices in ticker() method.

Web scraper

currency()

Get currency metadata like total markets capitalization, websites, source code link, if mineable…

Parameters:
  • curr (str) – Currency to get metadata. Can be a name, symbol, id or website_slug fields from pymarketcap.core.Pymarketcap.cryptocurrencies.
  • convert (str, optional) – Currency to convert response fields total_markets_cap, total_markets_volume_24h and price between USD and BTC. As default "USD".
Returns (dict):
Aditional general metadata not supported by other methods.
exchange()

Obtain data from a exchange passed as argument. See pymarketcap.core.Pymarketcap.cryptoexchanges property for obtain all posibles values.

Parameters:
Returns (dict):
Data from a exchange. Fields: "currency", "pair", "name", "volume_24h" (total), "price", "percent_volume", "updated". "slug", "website_slug", "id", "volume", "markets".
exchanges()

Get all exchanges in coinmarketcap ranked by volumes along with other metadata.

Parameters:convert (str, optional) – Convert volumes and prices between USD and BTC. As default "USD".
Returns (list):
Exchanges with markets and other data included.
cryptoexchanges

Returns all exchanges listed at coinmarketcap, as dictionaries with "name", "id" and "website_slug" keys.

historical()

Get historical data for a currency.

Parameters:
  • curr (str) – Currency to scrap historical data. Can be a name, "symbol", id or website_slug fields from pymarketcap.core.Pymarketcap.cryptocurrencies.
  • start (date, optional) – Time to start scraping periods as datetime.datetime type. As default datetime.datetime(2008, 8, 18)().
  • end (date, optional) – Time to end scraping periods as datetime.datetime type. As default datetime.datetime.now().
  • revert (bool, optional) – If False, return first date first, in chronological order, otherwise returns reversed list of periods. As default False.
Returns (list):
Historical dayly OHLC for a currency.
markets()

Get available coinmarketcap markets data for a currency.

Parameters:
  • curr (str) – Currency to get market data. Can be a name, "symbol", id or website_slug fields from pymarketcap.core.Pymarketcap.cryptocurrencies.
  • convert (str, optional) – Currency to convert response fields volume_24h and price between USD and BTC. As default "USD".
Returns (list):
Markets on wich provided currency is currently tradeable.
ranks()

Returns gainers and losers for 1 hour, 24 hours and 7 days.

Returns (dict):
A dictionary with 2 keys (gainers and losers) whose values are the periods "1h", "24h" and "7d".
recently()

Get recently added currencies along with other metadata.

Parameters:convert (str, optional) – Convert market_caps, prices, volumes and percent_changes between USD and BTC. As default "USD".
Returns (list):
Recently added currencies data.
tokens()

Get data from platforms tokens

Parameters:convert (str, optional) – Convert "market_cap", "price" and "volume_24h" values between USD and BTC. As default "USD".
Returns (list):
Platforms tokens data.

Graphs API

Note

The graphs methods can be called also as cmc.graphs.currency(), cmc.graphs.global_cap() and cmc.graphs.dominance(), being cmc a instance of Pymarketcap or AyncPymarketcap classes.

_currency()

Get graphs data of a currency.

Parameters:
  • curr (str) – Currency to retrieve graphs data.
  • start (datetime, optional) – Time to start retrieving graphs data in datetime type. As default None.
  • end (datetime, optional) – Time to end retrieving graphs data in datetime type. As default None.
  • use_auto_timeframe (bool, optional) – Use auto time frames same as fronted API. As default False
Returns (dict):
Dict info with next keys: "market_cap_by_available_supply", "price_btc", "price_usd", "volume_usd": and "price_platform". For each value, a list of lists where each one has two values [<datetime>, <value>]
_global_cap()

Get global market capitalization graphs, including or excluding Bitcoin.

Parameters:
  • bitcoin (bool, optional) – Indicates if Bitcoin will be includedin global market capitalization graph. As default True.
  • start (int, optional) – Time to start retrieving graphs data in datetime. As default None.
  • end (optional, datetime) – Time to start retrieving graphs data in datetime. As default None.
  • use_auto_timeframe (bool, optional) – Use auto time frames same as fronted API. As default False
Returns (dict):
Whose values are lists of lists with timestamp and values, a data structure with the keys: "volume_usd" and "market_cap_by_available_supply".
_dominance()

Get currencies dominance percentage graph

Parameters:
  • start (int, optional) – Time to start retrieving graphs data in datetime. As default None.
  • end (optional, datetime) – Time to start retrieving graphs data in datetime. As default None.
  • use_auto_timeframe (bool, optional) – Use auto time frames same as fronted API. As default False
Returns (dict):
Altcoins and dominance percentage values with timestamps.

Utils

convert()

Convert prices between currencies. Provide a value, the currency of the value and the currency to convert it and get the value in currency converted rate. For see all available currencies to convert see currencies_to_convert property.

Parameters:
  • value (int/float) – Value to convert betweeen two currencies.
  • currency_in (str) – Currency in which is expressed the value passed.
  • currency_out (str) – Currency to convert.
Returns (float):
Value expressed in currency_out parameter provided.

Download a currency image logo providing their size.

Parameters:
  • curr (str) – Currency name, id, website_slug or symbol to download.
  • size (int, optional) – Size in pixels. Valid sizes are: [16, 32, 64, 128, 200]. As default 128.
  • filename (str, optional) – Filename for store the logo. Doesn’t include the extension (will be “.png”). As default None.
Returns (str):
Filename of downloaded file if all was correct.

Download a exchange logo passing his name or id or website slug as first parameter and optionally a filename without extension.

Parameters:
  • exc (str) – Exchange name, id or website slug to download.
  • size (int) – Size in pixels. Valid values are: [16, 32, 64, 128, 200].
  • filename (str, optional) – Filename for store the logo, without include file extension (will be “.png”). As default None.
Returns (str):
Filename of downloaded file if all was correct.

pymarketcap.pymasyncore

class pymarketcap.pymasyncore.AsyncPymarketcap(queue_size=10, progress_bar=True, consumers=10, timeout=15, logger=<Logger /pymarketcap/pymasyncore.py (WARNING)>, debug=False, sync=<pymarketcap.core.Pymarketcap object>, **kwargs)

Bases: aiohttp.client.ClientSession

Asynchronous scraper for coinmarketcap.com

Parameters:
  • queue_size (int) – Number of maximum simultanenous get requests performing together in methods involving several requests. As default 10.
  • progress_bar (bool) – Select True or False if you want to show a progress bar in methods that involve processing of several requests (requires tqdm module). As default, True.
  • consumers (int) – Number of consumers resolving HTTP requests from an internal asyncio.Queue. As default, 10.
  • timeout (int/float, optional) – Limit max time waiting for a response. As default, 15.
  • logger (logging.logger) – As default is a logger with a StreamHandler.
  • debug (bool, optional) – If True, the logger level will be setted as DEBUG. As default False.
  • sync (object, optional) – Synchronous version instance of pymarketcap. As default pymarketcap.core.Pymarketcap
  • **kwargs – arguments that corresponds to the aiohttp.client.ClientSession parent class.

Note

All scraper methods described in Pymarketcap object and almost all the properties also exists in AsyncPymarketcap.

every_currency(currencies=None, convert='USD', consumers=None)

Return general data from every currency in coinmarketcap passing a list of currencies as first parameter. As default returns data for all currencies.

Parameters:
  • currencies (list, optional) – Iterator with all the currencies that you want to retrieve. As default None (pymarketcap.Pymarketcap.coins() will be used in that case).
  • convert (str, optional) – Convert prices in response between “USD” and BTC. As default "USD".
  • consumers (int, optional) – Number of consumers processing the requests simultaneously. As default None (see pymarketcap.AsyncPymarketcap.consumers).

Returns (list): Data for all currencies.

every_markets(currencies=None, convert='USD', consumers=None)

Returns markets data from every currency in coinmarketcap passing a list of currencies as first parameter. As default returns data for all currencies.

Parameters:
  • currencies (list, optional) – Iterator with all the currencies that you want to retrieve. As default None (pymarketcap.Pymarketcap.coins() will be used in that case).
  • convert (str, optional) – Convert prices in response between “USD” and BTC. As default "USD".
  • consumers (int, optional) – Number of consumers processing the requests simultaneously. As default None (see pymarketcap.AsyncPymarketcap.consumers).
Returns (async iterator):
Data for all currencies.
every_historical(currencies=None, start=datetime.datetime(2008, 8, 18, 0, 0), end=datetime.datetime(2018, 10, 29, 21, 13, 30, 336755), revert=False, consumers=None)

Returns historical data from every currency in coinmarketcap passing a list of currencies as first parameter. As default returns data for all currencies.

Parameters:
  • currencies (list, optional) – Iterator with all the currencies that you want to retrieve. As default None (pymarketcap.Pymarketcap.coins() will be used in that case).
  • start (date, optional) – Time to start scraping periods as datetime.datetime type. As default datetime(2008, 8, 18).
  • end (date, optional) – Time to end scraping periods as datetime.datetime type. As default datetime.now().
  • revert (bool, optional) – If False, return first date first, in chronological order, otherwise returns reversed list of periods. As default False.
  • consumers (int, optional) – Number of consumers processing the requests simultaneously. As default None (see pymarketcap.AsyncPymarketcap.consumers).
Returns (async iterator):
Historical data for all currencies.
every_exchange(exchanges=None, convert='USD', consumers=None)

Returns general data from every exchange in coinmarketcap passing a list of exchanges as first parameter. As default returns data for all exchanges.

Parameters:
  • exchanges (list, optional) – Iterator with all the exchanges that you want to retrieve. As default None (pymarketcap.Pymarketcap.exchange_slugs() will be used in that case).
  • convert (str, optional) – Convert market_caps, prices, volumes and percent_changes between USD and BTC. As default "USD".
  • consumers (int, optional) – Number of consumers processing the requests simultaneously. As default None (see pymarketcap.AsyncPymarketcap.consumers).
Returns (async iterator):
General data from all exchanges.

Note

The next method can be called also as graphs.every_currency().

_every_currency(currencies=None, start=None, end=None, use_auto_timeframe=False, consumers=None)

Returns graphs data from every currency in coinmarketcap passing a list of currencies as first parameter. As default returns graphs data for all currencies.

Parameters:
  • currencies (list, optional) – Iterator with all the currencies that you want to retrieve. As default None (pymarketcap.Pymarketcap.coins() will be used in that case).
  • start (datetime, optional) – Time to start retrieving graphs data in datetime. As default None.
  • end (datetime, optional) – Time to end retrieving graphs data in datetime. As default None.
  • use_auto_timeframe (bool, optional) – Use auto time frames same as fronted API. As default False
  • consumers (int, optional) – Number of consumers processing the requests simultaneously. As default None (see pymarketcap.AsyncPymarketcap.consumers).

Returns (async iterator): Graphs data from all currencies.

pymarketcap.errors

Pymarketcap errors module.

exception pymarketcap.errors.CoinmarketcapError

Bases: Exception

Coinmarketcap base classs errors.

exception pymarketcap.errors.CoinmarketcapHTTPError

Bases: pymarketcap.errors.CoinmarketcapError

Exception for catch HTTPErrors.

exception pymarketcap.errors.CoinmarketcapHTTPError404

Bases: pymarketcap.errors.CoinmarketcapError

Exception for catch 404 HTTP error codes.

exception pymarketcap.errors.CoinmarketcapHTTPError408

Bases: pymarketcap.errors.CoinmarketcapError

Exception for catch request timeout HTTP errors.

exception pymarketcap.errors.CoinmarketcapTooManyRequestsError

Bases: pymarketcap.errors.CoinmarketcapHTTPError

Exception for catch 429 HTTP error codes.