Portfolio Tracking

TL;DR

Use /simple/price for real-time portfolio valuation, /coins/{id}/history for cost basis on specific dates, /coins/markets for bulk market data, /coins/{id}/market_chart for historical performance charts, and /simple/supported_vs_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 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 and paste it directly into your AI tool for instant context.

Navigate the API faster with AI

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	Real-time prices with optional market cap, volume, and 24h change	Live portfolio valuation
/simple/token_price/{id}	Token prices by contract address	Tracking ERC-20 and other contract-based tokens
/coins/markets	Bulk market data for multiple coins in a single call	Portfolio dashboard with rankings and sparklines
/coins/{id}/history	Price snapshot on a specific date	Cost basis calculation on purchase dates
/coins/{id}/market_chart	Price, market cap, and volume over a given number of days	Historical performance charts
/coins/../contract/../market_chart	Chart data by token contract address over a given number of days	Performance tracking for tokens by address
/simple/supported_vs_currencies	Full list of supported fiat and crypto currencies	Multi-currency portfolio reporting
/onchain/simple/networks/../token_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.

Real-Time Portfolio Valuation — `/simple/price`

🔗 More endpoint details here 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:

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:

{
  "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 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:

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:

{
  "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 endpoint instead — it returns real-time prices by contract address across any supported network.

Bulk Market Data — `/coins/markets`

🔗 More endpoint details here 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:

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:

{
  "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 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):

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:

{
  "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 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:

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:

{
  "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 endpoint — same data, but queried by contract address instead of coin ID.

Multi-Currency Support — `/simple/supported_vs_currencies`

🔗 More endpoint details here 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:

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:

[
  "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:

Set up currency preference — Query /simple/supported_vs_currencies to populate a currency selector
Import holdings — Use /coins/markets or /simple/price to validate and price initial holdings
Live valuation — Poll /simple/price with all your coin IDs for real-time portfolio value
Calculate cost basis — Use /coins/{id}/history to look up prices on each purchase date
Chart performance — Pull /coins/{id}/market_chart to plot portfolio value over time
Track DeFi tokens — Use /simple/token_price/{id} or the onchain simple price endpoint for contract-based assets

Integrate with CoinGecko MCP Server

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

Getting started

Guides

TL;DR

Navigate the API faster with AI

Endpoint Overview

Real-Time Portfolio Valuation — `/simple/price`

Token Prices by Contract Address — `/simple/token_price/{id}`

Bulk Market Data — `/coins/markets`

Cost Basis Calculation

`/coins/{id}/history`

`/coins/{id}/market_chart`

Multi-Currency Support — `/simple/supported_vs_currencies`

Putting It All Together

Integrate with CoinGecko MCP Server

Getting started

Guides

​TL;DR

Navigate the API faster with AI

​Endpoint Overview

​Real-Time Portfolio Valuation — /simple/price

​Token Prices by Contract Address — /simple/token_price/{id}

​Bulk Market Data — /coins/markets

​Cost Basis Calculation

​/coins/{id}/history

​/coins/{id}/market_chart

​Multi-Currency Support — /simple/supported_vs_currencies

​Putting It All Together

Integrate with CoinGecko MCP Server

TL;DR

Endpoint Overview

Real-Time Portfolio Valuation — `/simple/price`

Token Prices by Contract Address — `/simple/token_price/{id}`

Bulk Market Data — `/coins/markets`

Cost Basis Calculation

`/coins/{id}/history`

`/coins/{id}/market_chart`

Multi-Currency Support — `/simple/supported_vs_currencies`

Putting It All Together