> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coingecko.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Portfolio Tracking
> Build portfolio trackers with real-time prices, historical snapshots for cost basis, and multi-currency support across 35M+ coins from CoinGecko API.
### TL;DR
Use [/simple/price](/reference/simple-price) for real-time portfolio valuation, [/coins/\{id}/history](/reference/coins-id-history) for cost basis on specific dates, [/coins/markets](/reference/coins-markets) for bulk market data, [/coins/\{id}/market\_chart](/reference/coins-id-market-chart) for historical performance charts, and [/simple/supported\_vs\_currencies](/reference/simple-supported-currencies) to power multi-currency reporting.
**Portfolio tracking** starts with accurate, up-to-date pricing — whether you're building a **personal dashboard**, a **multi-wallet aggregator**, or a **tax reporting tool** that needs **historical cost basis** calculations.
This guide walks you through the CoinGecko API endpoints that matter most for portfolio tracking workflows, and ties them together into a [complete workflow](#putting-it-all-together) at the end:
* **Real-time prices and market cap** to value your holdings across 35M+ coins
* **Historical snapshots** to calculate cost basis and unrealized gains over time
* **Multi-currency support** across fiat and crypto pairs for global reporting
Estimated reading time: **8 minutes**
**Want to get started even faster?**
Copy the contents of this page from [portfolio-tracking.md](https://docs.coingecko.com/docs/portfolio-tracking.md) and paste it directly into your AI tool for instant context.
Install the CoinGecko SKILL to give your AI coding agent built-in knowledge of every endpoint, parameter, and workflow. Setup takes less than 3 minutes.
***
## Endpoint Overview
| Endpoint | What It Gives You | Best For |
| ------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------ |
| [/simple/price](/reference/simple-price) | Real-time prices with optional market cap, volume, and 24h change | Live portfolio valuation |
| [/simple/token\_price/\{id}](/reference/simple-token-price) | Token prices by contract address | Tracking ERC-20 and other contract-based tokens |
| [/coins/markets](/reference/coins-markets) | Bulk market data for multiple coins in a single call | Portfolio dashboard with rankings and sparklines |
| [/coins/\{id}/history](/reference/coins-id-history) | Price snapshot on a specific date | Cost basis calculation on purchase dates |
| [/coins/\{id}/market\_chart](/reference/coins-id-market-chart) | Price, market cap, and volume over a given number of days | Historical performance charts |
| [/coins/../contract/../market\_chart](/reference/contract-address-market-chart) | Chart data by token contract address over a given number of days | Performance tracking for tokens by address |
| [/simple/supported\_vs\_currencies](/reference/simple-supported-currencies) | Full list of supported fiat and crypto currencies | Multi-currency portfolio reporting |
| [/onchain/simple/networks/../token\_price/..](/reference/onchain-simple-price) | Onchain token prices across any supported network | Tracking DEX tokens not listed on CoinGecko |
Replace `YOUR_API_KEY` in the examples below with your actual CoinGecko API key.
Don't have one yet? [Get your API key here](https://www.coingecko.com/en/api/pricing).
***
## Real-Time Portfolio Valuation — `/simple/price`
*🔗 More endpoint details [here](/reference/simple-price)*
The fastest way to value your holdings. Query multiple coins in a single request and get prices alongside market cap and 24h changes — everything you need for a live portfolio view.
**Example request:**
```bash cURL theme={null}
curl -X GET "https://pro-api.coingecko.com/api/v3/simple/price?ids=bitcoin,ethereum,solana,cardano&vs_currencies=usd,eur,btc&include_market_cap=true&include_24hr_change=true" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
**Key parameters:**
| Parameter | Why It Matters |
| --------------------- | ------------------------------------------------------------------------- |
| `ids` / `symbols` | Query by CoinGecko ID or ticker symbol — batch multiple coins in one call |
| `vs_currencies` | Get prices in multiple currencies simultaneously (e.g., `usd,eur,btc`) |
| `include_market_cap` | Display market cap alongside each holding |
| `include_24hr_change` | Show daily gain/loss percentage per asset |
| `precision` | Control decimal precision for display formatting |
**Response highlights:**
```json JSON theme={null}
{
"bitcoin": {
"usd": 67432.51,
"eur": 62145.30,
"btc": 1,
"usd_market_cap": 1326789012345,
"usd_24h_change": 2.34567
},
"ethereum": {
"usd": 3456.78,
"eur": 3185.42,
"btc": 0.05123,
"usd_market_cap": 415678901234,
"usd_24h_change": 1.23456
}
}
```
Multiply each price by your holding quantity to get the current value per asset. Sum them up for your total portfolio value.
***
## Token Prices by Contract Address — `/simple/token_price/{id}`
*🔗 More endpoint details [here](/reference/simple-token-price)*
When your portfolio includes ERC-20 tokens or other contract-based assets, you can look up prices directly by contract address — no need to know the CoinGecko ID.
**Example request:**
```bash cURL theme={null}
curl -X GET "https://pro-api.coingecko.com/api/v3/simple/token_price/ethereum?contract_addresses=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48,0x6b175474e89094c44da98b954eedeac495271d0f&vs_currencies=usd&include_market_cap=true&include_24hr_change=true" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
**Key parameters:**
| Parameter | Why It Matters |
| -------------------- | -------------------------------------------------------------- |
| `id` (path) | The asset platform (e.g., `ethereum`, `polygon-pos`, `solana`) |
| `contract_addresses` | Comma-separated token contract addresses |
| `vs_currencies` | Target currencies for pricing |
| `include_market_cap` | Useful for weighting tokens in your portfolio |
**Response highlights:**
```json JSON theme={null}
{
"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": {
"usd": 1.0,
"usd_market_cap": 32456789012,
"usd_24h_change": 0.012
},
"0x6b175474e89094c44da98b954eedeac495271d0f": {
"usd": 1.0,
"usd_market_cap": 5234567890,
"usd_24h_change": -0.005
}
}
```
For onchain tokens not listed on CoinGecko, use the [Onchain Simple Price](/reference/onchain-simple-price) endpoint instead — it returns real-time prices by contract address across any supported network.
***
## Bulk Market Data — `/coins/markets`
*🔗 More endpoint details [here](/reference/coins-markets)*
When you need more than just prices — market cap rankings, 24h highs/lows, sparkline charts, and multi-timeframe price changes — this endpoint delivers everything in one call for up to 250 coins per page.
**Example request:**
```bash cURL theme={null}
curl -X GET "https://pro-api.coingecko.com/api/v3/coins/markets?vs_currency=usd&ids=bitcoin,ethereum,solana,cardano,polkadot&sparkline=true&price_change_percentage=1h,24h,7d,30d" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
**Key parameters:**
| Parameter | Why It Matters |
| ------------------------- | ---------------------------------------------------------------------- |
| `ids` | Filter to only your portfolio coins — avoids fetching unnecessary data |
| `sparkline` | Includes 7-day sparkline data for inline mini-charts |
| `price_change_percentage` | Include `1h,24h,7d,30d` for multi-timeframe performance at a glance |
| `per_page` | Up to 250 results per page — reduces the number of calls needed |
**Response highlights:**
```json JSON theme={null}
{
"id": "bitcoin",
"symbol": "btc",
"name": "Bitcoin",
"image": "https://assets.coingecko.com/coins/images/1/large/bitcoin.png",
"current_price": 67432.51,
"market_cap": 1326789012345,
"market_cap_rank": 1,
"high_24h": 68100.00,
"low_24h": 65800.00,
"price_change_percentage_24h_in_currency": 2.34,
"price_change_percentage_7d_in_currency": 5.67,
"price_change_percentage_30d_in_currency": 12.45,
"sparkline_in_7d": {
"price": [64200.12, 64580.45, ...]
}
}
```
This is ideal for building a portfolio dashboard — you get everything needed for a rich table view including coin images, rankings, and sparkline charts.
***
## Cost Basis Calculation
### `/coins/{id}/history`
*🔗 More endpoint details [here](/reference/coins-id-history)*
Returns a price snapshot for a specific date — exactly what you need to calculate cost basis on the date you purchased an asset.
**Example request** (Bitcoin price on January 15, 2024):
```bash cURL theme={null}
curl -X GET "https://pro-api.coingecko.com/api/v3/coins/bitcoin/history?date=15-01-2024" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
**Key parameters:**
| Parameter | Why It Matters |
| -------------- | ------------------------------------------ |
| `date` | The historical date in `dd-mm-yyyy` format |
| `localization` | Set to `false` to reduce response size |
**Response highlights:**
```json JSON theme={null}
{
"id": "bitcoin",
"symbol": "btc",
"name": "Bitcoin",
"market_data": {
"current_price": {
"usd": 42856.23,
"eur": 39456.78,
"btc": 1.0
},
"market_cap": {
"usd": 840123456789
},
"total_volume": {
"usd": 18234567890
}
}
}
```
The `date` parameter uses `dd-mm-yyyy` format (not ISO format).
For example, January 15, 2024 is `15-01-2024`.
### `/coins/{id}/market_chart`
*🔗 More endpoint details [here](/reference/coins-id-market-chart)*
When you need continuous historical data — for example, to chart your portfolio's value over time or calculate time-weighted returns. Just pass a `days` parameter and get the full latest data directly, similar to CoinGecko's web charts.
**Example request:**
```bash cURL theme={null}
curl -X GET "https://pro-api.coingecko.com/api/v3/coins/ethereum/market_chart?vs_currency=usd&days=365&interval=daily" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
**Key parameters:**
| Parameter | Why It Matters |
| ------------- | ------------------------------------------------------------------------------------- |
| `days` | Lookback window: `1`, `7`, `14`, `30`, `90`, `180`, `365`, or `max` |
| `vs_currency` | Target currency for the historical data |
| `interval` | Use `daily` for consistent day-level data points, or leave empty for auto granularity |
**Response highlights:**
```json JSON theme={null}
{
"prices": [
[1704067200000, 2282.51],
[1704153600000, 2356.78]
],
"market_caps": [
[1704067200000, 274256789012],
[1704153600000, 283156789012]
],
"total_volumes": [
[1704067200000, 8234567890],
[1704153600000, 9123456789]
]
}
```
For tokens tracked by contract address, use the [/coins/../contract/../market\_chart](/reference/contract-address-market-chart) endpoint — same data, but queried by contract address instead of coin ID.
***
## Multi-Currency Support — `/simple/supported_vs_currencies`
*🔗 More endpoint details [here](/reference/simple-supported-currencies)*
Returns the full list of supported fiat and crypto currencies you can use as the `vs_currencies` parameter across all pricing endpoints. Essential for building currency selectors in your portfolio UI.
**Example request:**
```bash cURL theme={null}
curl -X GET "https://pro-api.coingecko.com/api/v3/simple/supported_vs_currencies" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
**Response highlights:**
```json JSON theme={null}
[
"btc", "eth", "usd", "eur", "jpy", "gbp", "aud", "cad",
"chf", "cny", "hkd", "krw", "sgd", "twd", "inr", "myr",
"idr", "php", "thb", "vnd", "sar", "aed", ...
]
```
Use this list to let users choose their preferred display currency, then pass it as `vs_currencies` to `/simple/price` or `vs_currency` to `/coins/markets`.
***
## Putting It All Together
Here's how these endpoints fit into a typical portfolio tracking workflow:
1. **Set up currency preference** — Query `/simple/supported_vs_currencies` to populate a currency selector
2. **Import holdings** — Use `/coins/markets` or `/simple/price` to validate and price initial holdings
3. **Live valuation** — Poll `/simple/price` with all your coin IDs for real-time portfolio value
4. **Calculate cost basis** — Use `/coins/{id}/history` to look up prices on each purchase date
5. **Chart performance** — Pull `/coins/{id}/market_chart` to plot portfolio value over time
6. **Track DeFi tokens** — Use `/simple/token_price/{id}` or the onchain simple price endpoint for contract-based assets
Connect your AI agent directly to CoinGecko's API using our MCP server — enabling real-time crypto data queries from tools like Claude Desktop, Cursor, and more.
***
Have feedback or need help? Reach out to `eason.lim@coingecko[dot]com`
Built with [Mintlify](https://mintlify.com).