0
# Coin Information
1

2
Comprehensive coin data including metadata, market information, historical data, technical indicators, and supply metrics. This module provides detailed information about individual cryptocurrencies and their market performance over time.
3

4
## Capabilities
5

6
### Coin Listings and Discovery
7

8
Get comprehensive lists of all supported cryptocurrencies with various filtering and pagination options.
9

10
```python { .api }
11
def get_coins(**kwargs):
12
    """
13
    List all coins with comprehensive data including price, market cap, volume, and metadata.
14
    
15
    Parameters:
16
    - order (str): Sort order ('market_cap_desc', 'gecko_desc', 'gecko_asc', 'market_cap_asc', 'id_asc', 'id_desc')
17
    - per_page (int): Number of results per page (1-250, default: 100)
18
    - page (int): Page number (default: 1)
19
    - localization (bool): Include localized names and descriptions (default: True)
20
    - sparkline (bool): Include 7-day price sparkline data (default: False)
21
    
22
    Returns:
23
    list: List of coin objects with comprehensive market and metadata
24
    """
25

26
def get_coins_list(**kwargs):
27
    """
28
    List all supported coins with ID, name, and symbol only (no pagination required).
29
    
30
    Parameters:
31
    - include_platform (bool): Include platform contract addresses (default: False)
32
    
33
    Returns:
34
    list: List of basic coin information (id, symbol, name, platforms)
35
    """
36

37
def get_coins_list_new(**kwargs):
38
    """
39
    Get the latest 200 coins that recently listed on CoinGecko.
40
    
41
    Returns:
42
    list: List of newly listed coins with basic information
43
    """
44
```
45

46
**Usage Examples:**
47

48
```python
49
# Get top 50 coins by market cap
50
top_coins = cg.get_coins(order='market_cap_desc', per_page=50, page=1)
51

52
# Get basic list of all supported coins
53
all_coins = cg.get_coins_list()
54

55
# Get recently listed coins
56
new_coins = cg.get_coins_list_new()
57
```
58

59
### Market Data
60

61
Get real-time market data for cryptocurrencies including prices, market caps, volumes, and rankings.
62

63
```python { .api }
64
def get_coins_markets(vs_currency, **kwargs):
65
    """
66
    List all supported coins with price, market cap, volume, and market-related data.
67
    
68
    Parameters:
69
    - vs_currency (str): Target currency for market data (e.g., 'usd')
70
    - ids (str or list): Specific coin IDs to retrieve (optional)
71
    - category (str): Filter by category (e.g., 'decentralized_finance_defi')
72
    - order (str): Sort order ('market_cap_desc', 'gecko_desc', 'market_cap_asc', etc.)
73
    - per_page (int): Results per page (1-250, default: 100)
74
    - page (int): Page number (default: 1)
75
    - sparkline (bool): Include 7-day price sparkline (default: False)
76
    - price_change_percentage (str): Include price change percentages ('1h,24h,7d,14d,30d,200d,1y')
77
    
78
    Returns:
79
    list: List of coins with comprehensive market data
80
    """
81
```
82

83
**Usage Example:**
84

85
```python
86
# Get market data for top 100 coins in USD
87
markets = cg.get_coins_markets(
88
    vs_currency='usd',
89
    order='market_cap_desc',
90
    per_page=100,
91
    sparkline=True,
92
    price_change_percentage='1h,24h,7d'
93
)
94
```
95

96
### Individual Coin Data
97

98
Get detailed information about specific cryptocurrencies.
99

100
```python { .api }
101
def get_coin_by_id(id, **kwargs):
102
    """
103
    Get comprehensive data for a specific coin including exchange tickers.
104
    
105
    Parameters:
106
    - id (str): Coin ID (e.g., 'bitcoin')
107
    - localization (bool): Include localized data (default: True)
108
    - tickers (bool): Include ticker data (default: True)
109
    - market_data (bool): Include market data (default: True)
110
    - community_data (bool): Include community data (default: True)
111
    - developer_data (bool): Include developer data (default: True)
112
    - sparkline (bool): Include 7-day price sparkline (default: False)
113
    
114
    Returns:
115
    dict: Comprehensive coin data including description, links, market data, and statistics
116
    """
117

118
def get_coin_ticker_by_id(id, **kwargs):
119
    """
120
    Get coin tickers from exchanges (paginated to 100 items).
121
    
122
    Parameters:
123
    - id (str): Coin ID (e.g., 'bitcoin')
124
    - exchange_ids (str or list): Filter by specific exchange IDs
125
    - include_exchange_logo (bool): Include exchange logos (default: False)
126
    - page (int): Page number (default: 1)
127
    - order (str): Sort order ('trust_score_desc', 'trust_score_asc', 'volume_desc')
128
    - depth (bool): Include 2% order book depth (default: False)
129
    
130
    Returns:
131
    dict: Ticker data with exchange information, trading pairs, and volumes
132
    """
133
```
134

135
**Usage Examples:**
136

137
```python
138
# Get comprehensive Bitcoin data
139
bitcoin = cg.get_coin_by_id(id='bitcoin', sparkline=True)
140

141
# Get Bitcoin tickers from exchanges
142
tickers = cg.get_coin_ticker_by_id(id='bitcoin', order='volume_desc')
143
```
144

145
### Historical Data
146

147
Access historical price, market cap, and volume data for cryptocurrencies.
148

149
```python { .api }
150
def get_coin_history_by_id(id, date, **kwargs):
151
    """
152
    Get historical data for a coin at a specific date.
153
    
154
    Parameters:
155
    - id (str): Coin ID (e.g., 'bitcoin')
156
    - date (str): Date in dd-mm-yyyy format (e.g., '30-12-2017')
157
    - localization (bool): Include localized data (default: True)
158
    
159
    Returns:
160
    dict: Historical coin data for the specified date
161
    """
162

163
def get_coin_market_chart_by_id(id, vs_currency, days, **kwargs):
164
    """
165
    Get historical market data including price, market cap, and 24h volume.
166
    
167
    Parameters:
168
    - id (str): Coin ID (e.g., 'bitcoin')
169
    - vs_currency (str): Target currency (e.g., 'usd')
170
    - days (str or int): Data range ('1', '7', '14', '30', '90', '180', '365', 'max')
171
    - interval (str): Data interval ('minutely', 'hourly', 'daily')
172
    
173
    Returns:
174
    dict: Contains 'prices', 'market_caps', and 'total_volumes' arrays with [timestamp, value] pairs
175
    """
176

177
def get_coin_market_chart_range_by_id(id, vs_currency, from_timestamp, to_timestamp, **kwargs):
178
    """
179
    Get historical market data within a specific timestamp range.
180
    
181
    Parameters:
182
    - id (str): Coin ID (e.g., 'bitcoin')
183
    - vs_currency (str): Target currency (e.g., 'usd')
184
    - from_timestamp (int): Start timestamp (Unix seconds)
185
    - to_timestamp (int): End timestamp (Unix seconds)
186
    
187
    Returns:
188
    dict: Market data arrays for the specified time range
189
    """
190
```
191

192
**Usage Examples:**
193

194
```python
195
# Get Bitcoin data from December 30, 2017
196
historical = cg.get_coin_history_by_id(id='bitcoin', date='30-12-2017')
197

198
# Get Bitcoin price chart for last 30 days
199
chart = cg.get_coin_market_chart_by_id(id='bitcoin', vs_currency='usd', days=30)
200

201
# Get Bitcoin data for specific time range
202
range_data = cg.get_coin_market_chart_range_by_id(
203
    id='bitcoin',
204
    vs_currency='usd',
205
    from_timestamp=1609459200,  # Jan 1, 2021
206
    to_timestamp=1640995200     # Jan 1, 2022
207
)
208
```
209

210
### OHLC Data
211

212
Get Open, High, Low, Close (OHLC) candlestick data for technical analysis.
213

214
```python { .api }
215
def get_coin_ohlc_by_id(id, vs_currency, days, **kwargs):
216
    """
217
    Get OHLC (candlestick) data for a coin.
218
    
219
    Parameters:
220
    - id (str): Coin ID (e.g., 'bitcoin')
221
    - vs_currency (str): Target currency (e.g., 'usd')
222
    - days (str or int): Data range ('1', '7', '14', '30', '90', '180', '365')
223
    
224
    Returns:
225
    list: Array of [timestamp, open, high, low, close] arrays
226
    """
227

228
def get_coin_ohlc_by_id_range(id, vs_currency, from_timestamp, to_timestamp, interval, **kwargs):
229
    """
230
    Get OHLC data within a specific timestamp range.
231
    
232
    Parameters:
233
    - id (str): Coin ID (e.g., 'bitcoin')
234
    - vs_currency (str): Target currency (e.g., 'usd')
235
    - from_timestamp (int): Start timestamp (Unix seconds)
236
    - to_timestamp (int): End timestamp (Unix seconds)
237
    - interval (str): Data interval ('4h', '1d', '3d', '1w')
238
    
239
    Returns:
240
    list: OHLC data arrays for the specified range
241
    """
242
```
243

244
**Usage Examples:**
245

246
```python
247
# Get Bitcoin OHLC data for last 7 days
248
ohlc = cg.get_coin_ohlc_by_id(id='bitcoin', vs_currency='usd', days=7)
249

250
# Get Bitcoin OHLC data for specific range with daily intervals
251
ohlc_range = cg.get_coin_ohlc_by_id_range(
252
    id='bitcoin',
253
    vs_currency='usd',
254
    from_timestamp=1640995200,
255
    to_timestamp=1672531200,
256
    interval='1d'
257
)
258
```
259

260
### Supply Charts
261

262
Access circulating and total supply data over time.
263

264
```python { .api }
265
def get_coin_circulating_supply_chart(id, days, **kwargs):
266
    """
267
    Get coin's circulating supply chart over time.
268
    
269
    Parameters:
270
    - id (str): Coin ID (e.g., 'bitcoin')
271
    - days (str or int): Data range ('1', '7', '14', '30', '90', '180', '365', 'max')
272
    
273
    Returns:
274
    dict: Contains 'circulating_supply' array with [timestamp, supply] pairs
275
    """
276

277
def get_coin_circulating_supply_chart_range(id, from_timestamp, to_timestamp, **kwargs):
278
    """
279
    Get circulating supply chart within a timestamp range.
280
    
281
    Parameters:
282
    - id (str): Coin ID (e.g., 'bitcoin')
283
    - from_timestamp (int): Start timestamp (Unix seconds)
284
    - to_timestamp (int): End timestamp (Unix seconds)
285
    
286
    Returns:
287
    dict: Circulating supply data for the specified range
288
    """
289

290
def get_coin_total_supply_chart(id, days, **kwargs):
291
    """
292
    Get coin's total supply chart over time.
293
    
294
    Parameters:
295
    - id (str): Coin ID (e.g., 'bitcoin')
296
    - days (str or int): Data range ('1', '7', '14', '30', '90', '180', '365', 'max')
297
    
298
    Returns:
299
    dict: Contains 'total_supply' array with [timestamp, supply] pairs
300
    """
301

302
def get_coin_total_supply_chart_range(id, from_timestamp, to_timestamp, **kwargs):
303
    """
304
    Get total supply chart within a timestamp range.
305
    
306
    Parameters:
307
    - id (str): Coin ID (e.g., 'bitcoin')
308
    - from_timestamp (int): Start timestamp (Unix seconds)
309
    - to_timestamp (int): End timestamp (Unix seconds)
310
    
311
    Returns:
312
    dict: Total supply data for the specified range
313
    """
314
```
315

316
### Contract Address Queries
317

318
Get coin information and market data using smart contract addresses.
319

320
```python { .api }
321
def get_coin_info_from_contract_address_by_id(id, contract_address, **kwargs):
322
    """
323
    Get coin information from its contract address.
324
    
325
    Parameters:
326
    - id (str): Platform ID (e.g., 'ethereum', 'binance-smart-chain')
327
    - contract_address (str): Token contract address
328
    
329
    Returns:
330
    dict: Coin information including ID, symbol, name, and basic market data
331
    """
332

333
def get_coin_market_chart_from_contract_address_by_id(id, contract_address, vs_currency, days, **kwargs):
334
    """
335
    Get historical market data using contract address.
336
    
337
    Parameters:
338
    - id (str): Platform ID (e.g., 'ethereum')
339
    - contract_address (str): Token contract address
340
    - vs_currency (str): Target currency (e.g., 'usd')
341
    - days (str or int): Data range ('1', '7', '14', '30', '90', '180', '365', 'max')
342
    
343
    Returns:
344
    dict: Market chart data arrays (prices, market_caps, total_volumes)
345
    """
346

347
def get_coin_market_chart_range_from_contract_address_by_id(id, contract_address, vs_currency, from_timestamp, to_timestamp, **kwargs):
348
    """
349
    Get market data range using contract address.
350
    
351
    Parameters:
352
    - id (str): Platform ID (e.g., 'ethereum')
353
    - contract_address (str): Token contract address
354
    - vs_currency (str): Target currency (e.g., 'usd')
355
    - from_timestamp (int): Start timestamp (Unix seconds)
356
    - to_timestamp (int): End timestamp (Unix seconds)
357
    
358
    Returns:
359
    dict: Market data for the specified time range
360
    """
361
```
362

363
**Usage Examples:**
364

365
```python
366
# Get USDC info by contract address
367
usdc_info = cg.get_coin_info_from_contract_address_by_id(
368
    id='ethereum',
369
    contract_address='0xa0b86a33e6441c1a0d077d82c79525ba6b14e2a3'
370
)
371

372
# Get USDC price chart by contract address
373
usdc_chart = cg.get_coin_market_chart_from_contract_address_by_id(
374
    id='ethereum',
375
    contract_address='0xa0b86a33e6441c1a0d077d82c79525ba6b14e2a3',
376
    vs_currency='usd',
377
    days=30
378
)
379
```
380

381
## Data Structures
382

383
### Chart Data Format
384
Historical data endpoints return arrays with timestamp-value pairs:
385

386
```python
387
{
388
    "prices": [[timestamp1, price1], [timestamp2, price2], ...],
389
    "market_caps": [[timestamp1, cap1], [timestamp2, cap2], ...],
390
    "total_volumes": [[timestamp1, vol1], [timestamp2, vol2], ...]
391
}
392
```
393

394
### OHLC Data Format
395
OHLC endpoints return arrays of candlestick data:
396

397
```python
398
[
399
    [timestamp, open, high, low, close],
400
    [timestamp, open, high, low, close],
401
    ...
402
]
403
```
404

405
All timestamps are Unix timestamps in milliseconds. Price and volume values are numeric.