Metadata-Version: 2.3
Name: byteforge-coinmarketcap
Version: 1.0
Summary: Python SDK for the coinmarketcap.com API.
Project-URL: Homepage, https://github.com/jmazzahacks/byteforge-coinmarketcap/
Project-URL: Issues, https://github.com/jmazzahacks/byteforge-coinmarketcap/issues
Author: Jason Byteforgia
License: Apache License
                                       Version 2.0, January 2004
                                    http://www.apache.org/licenses/
                
                TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
                
                1. Definitions.
                
                  "License" shall mean the terms and conditions for use, reproduction,
                  and distribution as defined by Sections 1 through 9 of this document.
                
                  "Licensor" shall mean the copyright owner or entity authorized by
                  the copyright owner that is granting the License.
                
                  "Legal Entity" shall mean the union of the acting entity and all
                  other entities that control, are controlled by, or are under common
                  control with that entity. For the purposes of this definition,
                  "control" means (i) the power, direct or indirect, to cause the
                  direction or management of such entity, whether by contract or
                  otherwise, or (ii) ownership of fifty percent (50%) or more of the
                  outstanding shares, or (iii) beneficial ownership of such entity.
                
                  "You" (or "Your") shall mean an individual or Legal Entity
                  exercising permissions granted by this License.
                
                  "Source" form shall mean the preferred form for making modifications,
                  including but not limited to software source code, documentation
                  source, and configuration files.
                
                  "Object" form shall mean any form resulting from mechanical
                  transformation or translation of a Source form, including but
                  not limited to compiled object code, generated documentation,
                  and conversions to other media types.
                
                  "Work" shall mean the work of authorship, whether in Source or
                  Object form, made available under the License, as indicated by a
                  copyright notice that is included in or attached to the work
                  (an example is provided in the Appendix below).
                
                  "Derivative Works" shall mean any work, whether in Source or Object
                  form, that is based on (or derived from) the Work and for which the
                  editorial revisions, annotations, elaborations, or other modifications
                  represent, as a whole, an original work of authorship. For the purposes
                  of this License, Derivative Works shall not include works that remain
                  separable from, or merely link (or bind by name) to the interfaces of,
                  the Work and Derivative Works thereof.
                
                  "Contribution" shall mean any work of authorship, including
                  the original version of the Work and any modifications or additions
                  to that Work or Derivative Works thereof, that is intentionally
                  submitted to Licensor for inclusion in the Work by the copyright owner
                  or by an individual or Legal Entity authorized to submit on behalf of
                  the copyright owner. For the purposes of this definition, "submitted"
                  means any form of electronic, verbal, or written communication sent
                  to the Licensor or its representatives, including but not limited to
                  communication on electronic mailing lists, source code control systems,
                  and issue tracking systems that are managed by, or on behalf of, the
                  Licensor for the purpose of discussing and improving the Work, but
                  excluding communication that is conspicuously marked or otherwise
                  designated in writing by the copyright owner as "Not a Contribution."
                
                  "Contributor" shall mean Licensor and any individual or Legal Entity
                  on behalf of whom a Contribution has been received by Licensor and
                  subsequently incorporated within the Work.
                
                2. Grant of Copyright License. Subject to the terms and conditions of
                  this License, each Contributor hereby grants to You a perpetual,
                  worldwide, non-exclusive, no-charge, royalty-free, irrevocable
                  copyright license to reproduce, prepare Derivative Works of,
                  publicly display, publicly perform, sublicense, and distribute the
                  Work and such Derivative Works in Source or Object form.
                
                3. Grant of Patent License. Subject to the terms and conditions of
                  this License, each Contributor hereby grants to You a perpetual,
                  worldwide, non-exclusive, no-charge, royalty-free, irrevocable
                  (except as stated in this section) patent license to make, have made,
                  use, offer to sell, sell, import, and otherwise transfer the Work,
                  where such license applies only to those patent claims licensable
                  by such Contributor that are necessarily infringed by their
                  Contribution(s) alone or by combination of their Contribution(s)
                  with the Work to which such Contribution(s) was submitted. If You
                  institute patent litigation against any entity (including a
                  cross-claim or counterclaim in a lawsuit) alleging that the Work
                  or a Contribution incorporated within the Work constitutes direct
                  or contributory patent infringement, then any patent licenses
                  granted to You under this License for that Work shall terminate
                  as of the date such litigation is filed.
                
                4. Redistribution. You may reproduce and distribute copies of the
                  Work or Derivative Works thereof in any medium, with or without
                  modifications, and in Source or Object form, provided that You
                  meet the following conditions:
                
                  (a) You must give any other recipients of the Work or
                      Derivative Works a copy of this License; and
                
                  (b) You must cause any modified files to carry prominent notices
                      stating that You changed the files; and
                
                  (c) You must retain, in the Source form of any Derivative Works
                      that You distribute, all copyright, patent, trademark, and
                      attribution notices from the Source form of the Work,
                      excluding those notices that do not pertain to any part of
                      the Derivative Works; and
                
                  (d) If the Work includes a "NOTICE" text file as part of its
                      distribution, then any Derivative Works that You distribute must
                      include a readable copy of the attribution notices contained
                      within such NOTICE file, excluding those notices that do not
                      pertain to any part of the Derivative Works, in at least one
                      of the following places: within a NOTICE text file distributed
                      as part of the Derivative Works; within the Source form or
                      documentation, if provided along with the Derivative Works; or,
                      within a display generated by the Derivative Works, if and
                      wherever such third-party notices normally appear. The contents
                      of the NOTICE file are for informational purposes only and
                      do not modify the License. You may add Your own attribution
                      notices within Derivative Works that You distribute, alongside
                      or as an addendum to the NOTICE text from the Work, provided
                      that such additional attribution notices cannot be construed
                      as modifying the License.
                
                  You may add Your own copyright statement to Your modifications and
                  may provide additional or different license terms and conditions
                  for use, reproduction, or distribution of Your modifications, or
                  for any such Derivative Works as a whole, provided Your use,
                  reproduction, and distribution of the Work otherwise complies with
                  the conditions stated in this License.
                
                5. Submission of Contributions. Unless You explicitly state otherwise,
                  any Contribution intentionally submitted for inclusion in the Work
                  by You to the Licensor shall be under the terms and conditions of
                  this License, without any additional terms or conditions.
                  Notwithstanding the above, nothing herein shall supersede or modify
                  the terms of any separate license agreement you may have executed
                  with Licensor regarding such Contributions.
                
                6. Trademarks. This License does not grant permission to use the trade
                  names, trademarks, service marks, or product names of the Licensor,
                  except as required for reasonable and customary use in describing the
                  origin of the Work and reproducing the content of the NOTICE file.
                
                7. Disclaimer of Warranty. Unless required by applicable law or
                  agreed to in writing, Licensor provides the Work (and each
                  Contributor provides its Contributions) on an "AS IS" BASIS,
                  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
                  implied, including, without limitation, any warranties or conditions
                  of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
                  PARTICULAR PURPOSE. You are solely responsible for determining the
                  appropriateness of using or redistributing the Work and assume any
                  risks associated with Your exercise of permissions under this License.
                
                8. Limitation of Liability. In no event and under no legal theory,
                  whether in tort (including negligence), contract, or otherwise,
                  unless required by applicable law (such as deliberate and grossly
                  negligent acts) or agreed to in writing, shall any Contributor be
                  liable to You for damages, including any direct, indirect, special,
                  incidental, or consequential damages of any character arising as a
                  result of this License or out of the use or inability to use the
                  Work (including but not limited to damages for loss of goodwill,
                  work stoppage, computer failure or malfunction, or any and all
                  other commercial damages or losses), even if such Contributor
                  has been advised of the possibility of such damages.
                
                9. Accepting Warranty or Additional Liability. While redistributing
                  the Work or Derivative Works thereof, You may choose to offer,
                  and charge a fee for, acceptance of support, warranty, indemnity,
                  or other liability obligations and/or rights consistent with this
                  License. However, in accepting such obligations, You may act only
                  on Your own behalf and on Your sole responsibility, not on behalf
                  of any other Contributor, and only if You agree to indemnify,
                  defend, and hold each Contributor harmless for any liability
                  incurred by, or claims asserted against, such Contributor by reason
                  of your accepting any such warranty or additional liability.
                
                END OF TERMS AND CONDITIONS
                
                APPENDIX: How to apply the Apache License to your work.
                
                  To apply the Apache License to your work, attach the following
                  boilerplate notice, with the fields enclosed by brackets "{}"
                  replaced with your own identifying information. (Don't include
                  the brackets!)  The text should be enclosed in the appropriate
                  comment syntax for the file format. We also recommend that a
                  file or class name and description of purpose be included on the
                  same "printed page" as the copyright notice for easier
                  identification within third-party archives.
                
                Copyright 2014-2017 Martin Simon
                
                Licensed under the Apache License, Version 2.0 (the "License");
                you may not use this file except in compliance with the License.
                You may obtain a copy of the License at
                
                   http://www.apache.org/licenses/LICENSE-2.0
                
                Unless required by applicable law or agreed to in writing, software
                distributed under the License is distributed on an "AS IS" BASIS,
                WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
                See the License for the specific language governing permissions and
                limitations under the License.
License-File: LICENSE
Keywords: API,BTC,Bitcoin,ETH,Ethereum,LTC,Litecoin,Ripple,XRP,coinmarketcap,cryptocurrency
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Requires-Dist: python-dateutil
Requires-Dist: requests
Requires-Dist: requests-cache
Description-Content-Type: text/markdown

# About This Project

This project is a fork of Martin Simon's 'coinmarketcap' module, which had not been updated for a long while ([original repository](https://github.com/barnumbirr/coinmarketcap)). This version has been extensively reworked to be compatible with the current CoinMarketCap API, diverging significantly from the original source. As a result, it is not backwards compatible, but it brings new capabilities and improvements tailored to the current API's structure and requirements.

This project currently supports the `v1/cryptocurrency/listings/latest` endpoint which is usable by anyone with a a free API key from CoinMarketCap. Obtain your free API key by signing up at [CoinMarketCap API](https://pro.coinmarketcap.com/signup/). 

It also supports the `/v2/cryptocurrency/quotes/historical` endpoint which requires a paid 'Hobbyist' level account or higher.

## Prerequisites

- An API key from [CoinMarketCap Pro](https://pro.coinmarketcap.com/signup/).

## Installation

Install byteforge-coinmarketcap

```bash
pip install byteforge-coinmarketcap
```

## Initialization

First, create an instance of the `Market` class with your API key:

```python
from coinmarketcap import Market
from coinmarketcap import SortOption

API_KEY = 'your_api_key_here'
coinmarketcap = Market(api_key=API_KEY)
```

## General Instructions

This SDK is crafted to fetch market data at specific points in time, offering a comprehensive snapshot of cryptocurrency metrics. Each method returns a list of `TokenState` objects, encapsulating detailed quotes for a cryptocurrency asset corresponding to particular timestamps. The `TokenState` object can include multiple quotes for the asset. For additional information, refer to the usage examples provided. 


## Usage: API listings_latest

Get the top 5 token states by market cap (A TokenState is a snapshot of a token at a certain point of time, for listings_latest, that time will always be "now")

### Simple Usage

```python
token_states = coinmarketcap.listings_latest(sort_by=SortOption.MARKET_CAP, limit=5)

for token in tokens:
    print(token.name, token.symbol, token.quote_map['USD'].price)

# Bitcoin BTC 51121.78037849647
# Ethereum ETH 2912.0337516792188
# Tether USDt USDT 0.9996898483447065
# BNB BNB 369.2725354702457
# Solana SOL 103.68827889524766
```
### The `convert` parameter

The `convert` parameter enhances your ability to receive cryptocurrency quotes in multiple currencies simultaneously. This feature is especially useful for comparing market values across different fiat and cryptocurrencies, allowing up to three currency conversions in a single request.

Here's how you can retrieve the latest listings and obtain quotes in USD and BTC for the top 5 cryptocurrencies by market capitalization:

```python
# Fetch listings with market cap sort, limited to the top 5, converting quotes to USD and BTC
tokens = coinmarketcap.listings_latest(sort_by=SortOption.MARKET_CAP, limit=5, convert=['USD', 'BTC'])

# Iterate through each token to display its name, symbol, and quotes in BTC and USD
for token in tokens:
   btc_price = token.quote_map['BTC'].price
   usd_price = token.quote_map['USD'].price
   print(f"{token.name} ({token.symbol}): {btc_price} BTC | {usd_price} USD")

# Example output:
Bitcoin (BTC): 1 BTC | 67393.03455553834 USD
Ethereum (ETH): 0.052078986669438124 BTC | 3509.760948230864 USD
Tether USDt (USDT): 1.4836675143579e-05 BTC | 0.9998885606405162 USD
Solana (SOL): 0.002940752776384911 BTC | 198.1862534782036 USD
BNB (BNB): 0.008168244957149958 BTC | 550.4828146553089 USD
```

### The `SortOption` parameter

The `SortOption` enum provides various parameters you can use to sort the listings fetched from CoinMarketCap. Below are the available sort options:

- `MARKET_CAP`: Sort by market capitalization.
- `MARKET_CAP_STRICT`: Strict sorting by market capitalization.
- `NAME`: Sort by the name of the token.
- `SYMBOL`: Sort by the symbol of the token.
- `DATE_ADDED`: Sort by the date the token was added to CoinMarketCap.
- `PRICE`: Sort by the price of the token.
- `CIRCULATING_SUPPLY`: Sort by circulating supply.
- `TOTAL_SUPPLY`: Sort by total supply.
- `MAX_SUPPLY`: Sort by maximum supply.
- `NUM_MARKET_PAIRS`: Sort by the number of market pairs.
- `MARKET_CAP_BY_TOTAL_SUPPLY_STRICT`: Strict sorting by market capitalization by total supply.
- `VOLUME_24H`: Sort by 24-hour volume.
- `VOLUME_7D`: Sort by 7-day volume.
- `VOLUME_30D`: Sort by 30-day volume.
- `PERCENT_CHANGE_1H`: Sort by percent change in the last hour.
- `PERCENT_CHANGE_24H`: Sort by percent change in the last 24 hours.
- `PERCENT_CHANGE_7D`: Sort by percent change in the last 7 days.

To use a sort option, simply pass the desired `SortOption` value to the `listings_latest` method's `sort_by` parameter, and use `SortDir` to specificy sort direction:

```python
from coinmarketcap import SortOption, SortDir

# Example: Sort by price in descending order
tokens = coinmarketcap.listings_latest(sort_by=SortOption.PRICE, sort_dir=SortDir.DESC)
```

### The `FilterOptions` parameter

The `FilterOptions` class allows you to filter the listings by various criteria. Below are the fields you can set to apply filters:

- `price_min` and `price_max`: Filter tokens based on their price range.
- `market_cap_min` and `market_cap_max`: Filter tokens based on their market capitalization range.
- `volume_24h_min` and `volume_24h_max`: Filter tokens based on their 24-hour trading volume range.
- `circulating_supply_min` and `circulating_supply_max`: Filter tokens based on their circulating supply range.
- `percent_change_24h_min` and `percent_change_24h_max`: Filter tokens based on their 24-hour percent change range.
- `tags`: Filter tokens that have specified tags.

To use the filter options, create an instance of `FilterOptions` and pass it to the `listings_latest` method's `filters` parameter:

```python
from coinmarketcap import Market, FilterOptions

coinmarketcap = Market(api_key="your_api_key")

# Define your filter criteria
filter_options = FilterOptions(
    price_min=0.01,
    price_max=1.00,
    market_cap_min=1000000,
    volume_24h_min=50000,
    tags=['defi', 'smart-contracts']
)

# Fetch listings with the defined filters
tokens = coinmarketcap.listings_latest(filters=filter_options, limit=10)

for token in tokens:
    print(f"{token.name} - {token.symbol}: ${token.quote_map['USD'].price}")
```

### The `AuxFields` paramater

The `AuxFields` enum allows you to specify additional fields to be included in the response data for each token listing. This can provide more detailed information about each token. Below are the auxiliary fields you can request:

- `NUM_MARKET_PAIRS`: Number of market pairs available for the token.
- `CMC_RANK`: The CoinMarketCap ranking of the token.
- `DATE_ADDED`: The date the token was added to CoinMarketCap.
- `TAGS`: Tags associated with the token.
- `PLATFORM`: The platform on which the token was issued (e.g., Ethereum).
- `MAX_SUPPLY`: The maximum supply of the token.
- `TOTAL_SUPPLY`: The total supply of the token.
- `MARKET_CAP_BY_TOTAL_SUPPLY`: Market cap calculated using the total supply.
- `VOLUME_24H_REPORTED`: Reported 24-hour trading volume.
- `VOLUME_7D`: Trading volume over the last 7 days.
- `VOLUME_7D_REPORTED`: Reported trading volume over the last 7 days.
- `VOLUME_30D`: Trading volume over the last 30 days.
- `VOLUME_30D_REPORTED`: Reported trading volume over the last 30 days.
- `IS_MARKET_CAP_INCLUDED`: Indicates whether the market cap is included in the calculation.

To use these auxiliary fields, pass a list of `AuxFields` to the `listings_latest` method:

```python
from coinmarketcap import Market, SortOption, AuxFields

coinmarketcap = Market(api_key="your_api_key")

# Specify auxiliary fields to include in the response
aux_fields = [
    AuxFields.NUM_MARKET_PAIRS,
    AuxFields.CMC_RANK,
    AuxFields.DATE_ADDED,
    AuxFields.TAGS,
]

tokens = coinmarketcap.listings_latest(
    sort_by=SortOption.MARKET_CAP, 
    aux_fields=aux_fields, 
    limit=5
)

for token in tokens:
    print(f"{token.name} ({token.symbol}) - CMC Rank: {token.cmc_rank}, Market Pairs: {token.num_market_pairs}")
```

## Usage: API quotes_historical


The `quotes_historical` method facilitates fetching historical quotes for a specific cryptocurrency over a given time range. This feature allows for detailed analysis of cryptocurrency value trends over time in different fiat or cryptocurrencies.

This API requires a 'Hobbyist' or higher tier CMC subscription.

### Example Usage

```python
from byteforge_coinmarketcap import Market
from datetime import datetime

market = Market(api_key='your_api_key')

historical_quotes = coinmarketcap.quotes_historical(
    ticker='BTC',
    timestamp_start=1709269200,
    timestamp_end=1710046800,
    interval='daily',
    convert=['USD', 'EUR']
)

for token_state in historical_quotes:
    print(f"{token_state.name} ({token_state.symbol}) - Date: {datetime.fromtimestamp(token_state.timestamp)}")
    for currency, quote in token_state.quote_map.items():
        print(f"  {currency}: {quote.price}")
        
# Example output
# Bitcoin (BTC) - Date: 2024-03-01 19:00:00
#  EUR: 57565.10517077225
#  USD: 62431.65248172238
# Bitcoin (BTC) - Date: 2024-03-02 19:00:00
#  EUR: 57196.216977007156
#  USD: 62031.57852286433
# Bitcoin (BTC) - Date: 2024-03-03 19:00:00
#  EUR: 58233.4060759458
#  USD: 63137.00468154272
# Bitcoin (BTC) - Date: 2024-03-04 19:00:00
#  EUR: 62964.80344823259
#  USD: 68341.05778181224        
```

### Interval Parameter Options

When fetching historical quotes, you can specify the `interval` parameter to determine the granularity of the time series data. There are two types of interval formats you can use:

### Calendar Intervals (UTC Time)
- `hourly`: Retrieves the first quote available at the beginning of each calendar hour.
- `daily`: Retrieves the first quote available at the beginning of each calendar day.
- `weekly`: Retrieves the first quote available at the beginning of each calendar week.
- `monthly`: Retrieves the first quote available at the beginning of each calendar month.
- `yearly`: Retrieves the first quote available at the beginning of each calendar year.

### Relative Time Intervals
- `m`: Retrieves a quote available every "m" minutes. Supported intervals: `5m`, `10m`, `15m`, `30m`, `45m`.
- `h`: Retrieves a quote available every "h" hours. Supported intervals: `1h`, `2h`, `3h`, `4h`, `6h`, `12h`.
- `d`: Retrieves a quote available every "d" days. Supported intervals: `1d`, `2d`, `3d`, `7d`, `14d`, `15d`, `30d`, `60d`, `90d`, `365d`.

Please ensure to select the interval that best matches your data analysis needs.



## License:

```
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

```
