0
# Price & Market Data
1

2
Real-time and historical cryptocurrency pricing, market capitalization, trading volume, and market-related statistics for individual coins and tokens. This module provides the fundamental price data functionality that forms the core of most cryptocurrency applications.
3

4
## Capabilities
5

6
### Current Price Data
7

8
Get real-time prices for cryptocurrencies in any supported fiat or cryptocurrency denomination.
9

10
```python { .api }
11
def get_price(ids, vs_currencies, **kwargs):
12
    """
13
    Get the current price of any cryptocurrencies in any other supported currencies.
14
    
15
    Parameters:
16
    - ids (str or list): Coin IDs (e.g., 'bitcoin' or ['bitcoin', 'ethereum'])
17
    - vs_currencies (str or list): Target currencies (e.g., 'usd' or ['usd', 'eur'])
18
    - include_market_cap (bool): Include market cap data
19
    - include_24hr_vol (bool): Include 24h volume data
20
    - include_24hr_change (bool): Include 24h price change percentage
21
    - include_last_updated_at (bool): Include last updated timestamp
22
    
23
    Returns:
24
    dict: Price data with coin IDs as keys and currency prices as nested values
25
    """
26
```
27

28
**Usage Examples:**
29

30
```python
31
# Single coin, single currency
32
price = cg.get_price(ids='bitcoin', vs_currencies='usd')
33
# Returns: {'bitcoin': {'usd': 43000.00}}
34

35
# Multiple coins, multiple currencies
36
prices = cg.get_price(
37
    ids=['bitcoin', 'ethereum'], 
38
    vs_currencies=['usd', 'eur']
39
)
40
# Returns: {'bitcoin': {'usd': 43000, 'eur': 37000}, 'ethereum': {'usd': 2500, 'eur': 2150}}
41

42
# With additional market data
43
detailed = cg.get_price(
44
    ids='bitcoin',
45
    vs_currencies='usd',
46
    include_market_cap=True,
47
    include_24hr_vol=True,
48
    include_24hr_change=True
49
)
50
# Returns: {'bitcoin': {'usd': 43000, 'usd_market_cap': 845000000000, 'usd_24h_vol': 15000000000, 'usd_24h_change': 2.5}}
51
```
52

53
### Token Price Data
54

55
Get current prices for tokens by their contract addresses, primarily for Ethereum-based tokens.
56

57
```python { .api }
58
def get_token_price(id, contract_addresses, vs_currencies, **kwargs):
59
    """
60
    Get current prices of tokens by contract addresses.
61
    
62
    Parameters:
63
    - id (str): Platform ID (e.g., 'ethereum')
64
    - contract_addresses (str or list): Token contract addresses
65
    - vs_currencies (str or list): Target currencies for price quotes
66
    - include_market_cap (bool): Include market cap data
67
    - include_24hr_vol (bool): Include 24h volume data
68
    - include_24hr_change (bool): Include 24h price change
69
    - include_last_updated_at (bool): Include last updated timestamp
70
    
71
    Returns:
72
    dict: Token prices keyed by contract address
73
    """
74
```
75

76
**Usage Example:**
77

78
```python
79
# Get USDC token price on Ethereum
80
token_price = cg.get_token_price(
81
    id='ethereum',
82
    contract_addresses='0xa0b86a33e6441c1a0d077d82c79525ba6b14e2a3',
83
    vs_currencies='usd'
84
)
85
```
86

87
### Supported Currencies
88

89
Get the complete list of supported vs_currencies for price queries.
90

91
```python { .api }
92
def get_supported_vs_currencies(**kwargs):
93
    """
94
    Get list of all supported vs_currencies for price endpoints.
95
    
96
    Returns:
97
    list: List of supported currency codes (fiat and crypto)
98
    """
99
```
100

101
**Usage Example:**
102

103
```python
104
currencies = cg.get_supported_vs_currencies()
105
# Returns: ['btc', 'eth', 'ltc', 'bch', 'usd', 'eur', 'jpy', 'gbp', ...]
106
```
107

108
### Top Gainers and Losers
109

110
Identify the best and worst performing cryptocurrencies over the past 24 hours.
111

112
```python { .api }
113
def get_coin_top_gainers_losers(vs_currency, **kwargs):
114
    """
115
    Get top gainers and losers in the cryptocurrency market.
116
    
117
    Parameters:
118
    - vs_currency (str): Currency for price comparison (e.g., 'usd')
119
    - duration (str): Time period ('1h', '24h', '7d', '14d', '30d', '60d', '1y')
120
    - top_coins (str): Scope ('1000', '2000', 'all')
121
    
122
    Returns:
123
    dict: Contains 'top_gainers' and 'top_losers' lists with coin data
124
    """
125
```
126

127
**Usage Example:**
128

129
```python
130
# Get top performers over 24 hours
131
performers = cg.get_coin_top_gainers_losers(vs_currency='usd')
132
top_gainers = performers['top_gainers']
133
top_losers = performers['top_losers']
134
```
135

136
## Parameter Handling
137

138
### List Parameters
139
Python lists are automatically converted to comma-separated strings:
140

141
```python
142
# These are equivalent:
143
cg.get_price(ids=['bitcoin', 'ethereum'], vs_currencies=['usd', 'eur'])
144
cg.get_price(ids='bitcoin,ethereum', vs_currencies='usd,eur')
145
```
146

147
### Boolean Parameters
148
Python booleans are automatically converted to lowercase strings:
149

150
```python
151
# These are equivalent:
152
cg.get_price(ids='bitcoin', vs_currencies='usd', include_market_cap=True)
153
cg.get_price(ids='bitcoin', vs_currencies='usd', include_market_cap='true')
154
```
155

156
## Error Handling
157

158
Price endpoints may raise:
159
- `requests.exceptions.HTTPError`: For invalid coin IDs or currency codes
160
- `ValueError`: For malformed API responses or rate limit exceeded
161
- `requests.exceptions.RequestException`: For network connectivity issues
162

163
## Data Formats
164

165
All price data is returned as nested dictionaries with the following structure:
166

167
```python
168
{
169
    "coin_id": {
170
        "currency_code": price_value,
171
        "currency_code_market_cap": market_cap_value,  # if requested
172
        "currency_code_24h_vol": volume_value,         # if requested
173
        "currency_code_24h_change": change_percentage, # if requested
174
        "last_updated_at": timestamp                   # if requested
175
    }
176
}
177
```
178

179
Timestamps are Unix timestamps in seconds.