0
# PyCoingecko
1

2
A comprehensive Python3 wrapper around the CoinGecko API (V3) that provides programmatic access to real-time and historical cryptocurrency market data, pricing information, exchange data, and NFT collection metrics. PyCoingecko supports both the free Public API and paid Pro/Demo API tiers, offering a simple and intuitive interface for accessing CoinGecko's extensive cryptocurrency database.
3

4
## Package Information
5

6
- **Package Name**: pycoingecko
7
- **Language**: Python
8
- **Installation**: `pip install pycoingecko`
9

10
## Core Imports
11

12
```python
13
from pycoingecko import CoinGeckoAPI
14
```
15

16
## Basic Usage
17

18
```python
19
from pycoingecko import CoinGeckoAPI
20

21
# Initialize for free Public API
22
cg = CoinGeckoAPI()
23

24
# Or with demo API key for enhanced rate limits
25
cg = CoinGeckoAPI(demo_api_key='YOUR_DEMO_API_KEY')
26

27
# Or with Pro API key for full Pro API access
28
cg = CoinGeckoAPI(api_key='YOUR_PRO_API_KEY')
29

30
# Get current Bitcoin price in USD
31
price = cg.get_price(ids='bitcoin', vs_currencies='usd')
32
print(price)  # {'bitcoin': {'usd': 43000.00}}
33

34
# Get multiple cryptocurrencies in multiple currencies
35
prices = cg.get_price(
36
    ids=['bitcoin', 'ethereum', 'litecoin'], 
37
    vs_currencies=['usd', 'eur'],
38
    include_market_cap=True,
39
    include_24hr_vol=True
40
)
41

42
# Search for cryptocurrencies
43
results = cg.search(query='ethereum')
44

45
# Get trending cryptocurrencies
46
trending = cg.get_search_trending()
47

48
# Get global cryptocurrency market data
49
global_data = cg.get_global()
50
```
51

52
## Architecture
53

54
PyCoingecko is built around a single `CoinGeckoAPI` class that handles all interactions with the CoinGecko API:
55

56
- **Session Management**: Persistent HTTP session with automatic retry logic and connection pooling
57
- **API Key Handling**: Automatic selection between free Public API, Demo API, and Pro API endpoints based on provided keys
58
- **Parameter Processing**: Automatic conversion of Python lists to comma-separated strings and booleans to lowercase strings
59
- **Error Handling**: Comprehensive HTTP error handling with JSON response parsing
60

61
The library uses a decorator-based approach (`@func_args_preprocessing`) to automatically preprocess function arguments, ensuring seamless conversion between Python data types and API-expected formats.
62

63
## Capabilities
64

65
### Price & Market Data
66

67
Real-time and historical cryptocurrency pricing, market capitalization, trading volume, and market-related statistics for individual coins and tokens.
68

69
```python { .api }
70
def get_price(ids, vs_currencies, **kwargs): ...
71
def get_token_price(id, contract_addresses, vs_currencies, **kwargs): ...
72
def get_supported_vs_currencies(**kwargs): ...
73
def get_coin_top_gainers_losers(vs_currency, **kwargs): ...
74
```
75

76
[Price & Market Data](./price-market.md)
77

78
### Coin Information
79

80
Comprehensive coin data including metadata, tickers, historical information, market charts, OHLC data, and supply metrics.
81

82
```python { .api }
83
def get_coins(**kwargs): ...
84
def get_coins_list(**kwargs): ...
85
def get_coins_list_new(**kwargs): ...
86
def get_coin_by_id(id, **kwargs): ...
87
def get_coin_market_chart_by_id(id, vs_currency, days, **kwargs): ...
88
def get_coin_ohlc_by_id(id, vs_currency, days, **kwargs): ...
89
```
90

91
[Coin Information](./coins.md)
92

93
### Exchanges
94

95
Exchange data including exchange listings, volume information, tickers, historical volume charts, derivatives trading, market indexes, and asset platforms.
96

97
```python { .api }
98
def get_exchanges_list(**kwargs): ...
99
def get_exchanges_by_id(id, **kwargs): ...
100
def get_exchanges_tickers_by_id(id, **kwargs): ...
101
def get_exchanges_volume_chart_by_id(id, days, **kwargs): ...
102
def get_derivatives(**kwargs): ...
103
def get_derivatives_exchanges(**kwargs): ...
104
def get_indexes(**kwargs): ...
105
def get_indexes_list(**kwargs): ...
106
def get_asset_platforms(**kwargs): ...
107
def get_asset_platform_by_id(asset_platform_id, **kwargs): ...
108
```
109

110
[Exchanges](./exchanges.md)
111

112
### NFTs & Digital Assets
113

114
NFT collection data, market information, historical charts, and marketplace tickers for digital collectibles.
115

116
```python { .api }
117
def get_nfts_list(**kwargs): ...
118
def get_nfts_by_id(id, **kwargs): ...
119
def get_nfts_markets(**kwargs): ...
120
def get_nfts_market_chart_by_id(id, days, **kwargs): ...
121
```
122

123
[NFTs & Digital Assets](./nfts.md)
124

125
### Global Market Data
126

127
Cryptocurrency market overview, global statistics, market cap charts, and DeFi-specific metrics.
128

129
```python { .api }
130
def get_global(**kwargs): ...
131
def get_global_decentralized_finance_defi(**kwargs): ...
132
def get_global_market_cap_chart(days, **kwargs): ...
133
```
134

135
[Global Market Data](./global.md)
136

137
### Search & Discovery
138

139
Search functionality for cryptocurrencies, categories, markets, and trending data discovery.
140

141
```python { .api }
142
def search(query, **kwargs): ...
143
def get_search_trending(**kwargs): ...
144
```
145

146
[Search & Discovery](./search.md)
147

148
### System & Utilities
149

150
API status monitoring, account information, and utility functions for data processing.
151

152
```python { .api }
153
def ping(**kwargs): ...
154
def key(**kwargs): ...  # Pro API only
155
```
156

157
[System & Utilities](./system-utils.md)
158

159
## API Key Management
160

161
PyCoingecko automatically handles different API tiers:
162

163
- **Free Public API**: No API key required, standard rate limits
164
- **Demo API**: Uses `demo_api_key` parameter for enhanced rate limits
165
- **Pro API**: Uses `api_key` parameter for professional-tier access with higher limits
166

167
```python { .api }
168
class CoinGeckoAPI:
169
    def __init__(self, api_key: str = '', retries=5, demo_api_key: str = ''):
170
        """
171
        Initialize CoinGecko API client.
172
        
173
        Parameters:
174
        - api_key: Pro API key for professional tier access
175
        - retries: Number of retry attempts for failed requests (default: 5)
176
        - demo_api_key: Demo API key for enhanced rate limits on free tier
177
        """
178
```
179

180
## Error Handling
181

182
All API methods may raise the following exceptions:
183

184
- `requests.exceptions.RequestException`: Network-related errors
185
- `requests.exceptions.HTTPError`: HTTP status errors (404, 500, etc.)
186
- `ValueError`: API response errors with JSON error details
187
- `json.decoder.JSONDecodeError`: Response parsing errors
188

189
## Common Parameters
190

191
Most API methods support common optional parameters:
192

193
- **Lists**: Python lists are automatically converted to comma-separated strings
194
- **Booleans**: Python booleans are automatically converted to lowercase strings ('true'/'false')
195
- **Pagination**: `page`, `per_page` parameters where supported
196
- **Localization**: `localization` parameter for multilingual responses
197
- **Additional Options**: Method-specific parameters as defined in CoinGecko API documentation
198

199
## Utility Functions
200

201
```python { .api }
202
def func_args_preprocessing(func):
203
    """Decorator that converts list input arguments to comma-separated strings."""
204

205
def arg_preprocessing(arg_v):
206
    """Return the values of an argument after preprocessing."""
207

208
def get_comma_separated_values(values):
209
    """Return the values as a comma-separated string."""
210
```