openapi: 3.1.0
info:
title: CoinGecko Crypto Market Data Asset Platforms Coins API
description: The CoinGecko Crypto Market Data API provides comprehensive and reliable cryptocurrency price and market data through RESTful JSON endpoints. It offers over 70 endpoints covering real-time and historical prices, trading volumes, market capitalization, OHLCV data, exchange information, NFT metrics, derivatives data, and public treasury holdings for over 18,000 coins. The Demo API plan provides free access with 30 calls per minute to a subset of 30 publicly accessible endpoints.
version: 3.0.1
contact:
name: CoinGecko Support
url: https://support.coingecko.com
termsOfService: https://www.coingecko.com/en/terms
servers:
- url: https://api.coingecko.com/api/v3
description: CoinGecko Demo API Server
security:
- demoApiKeyHeader: []
- demoApiKeyQuery: []
tags:
- name: Coins
description: Comprehensive coin data including current prices, market data, historical data, tickers, and OHLCV charts.
paths:
/coins/list:
get:
operationId: getCoinsList
summary: List all supported coins
description: Get the complete list of all supported coins with their IDs, symbols, and names. Use this endpoint to obtain coin IDs for use in other endpoints. This list is cached and updated periodically.
tags:
- Coins
parameters:
- name: include_platform
in: query
description: Include platform contract addresses in the response (e.g., Ethereum, Solana contract addresses)
schema:
type: boolean
default: false
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CoinListItem'
/coins/markets:
get:
operationId: getCoinsMarkets
summary: List coins with market data
description: Get a paginated list of all supported coins with price, market cap, volume, and other market-related data. Results are ordered by market cap rank by default.
tags:
- Coins
parameters:
- name: vs_currency
in: query
required: true
description: The target currency of market data (e.g., usd, eur, btc)
schema:
type: string
- name: ids
in: query
description: Comma-separated list of coin IDs to filter results
schema:
type: string
- name: category
in: query
description: Filter by coin category
schema:
type: string
- name: order
in: query
description: Sort order for results
schema:
type: string
enum:
- market_cap_asc
- market_cap_desc
- volume_asc
- volume_desc
- id_asc
- id_desc
default: market_cap_desc
- name: per_page
in: query
description: Number of results per page (1-250)
schema:
type: integer
minimum: 1
maximum: 250
default: 100
- name: page
in: query
description: Page number for pagination
schema:
type: integer
minimum: 1
default: 1
- name: sparkline
in: query
description: Include sparkline 7-day price data
schema:
type: boolean
default: false
- name: price_change_percentage
in: query
description: Comma-separated list of price change percentage timeframes (1h, 24h, 7d, 14d, 30d, 200d, 1y)
schema:
type: string
- name: locale
in: query
description: Language locale for descriptions
schema:
type: string
default: en
- name: precision
in: query
description: Decimal precision for currency price values
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CoinMarket'
'400':
description: Bad request - invalid parameters
'401':
description: Unauthorized - invalid or missing API key
/coins/{id}:
get:
operationId: getCoinById
summary: Get coin data by ID
description: Get comprehensive data for a specific coin including current price, market data, community data, developer data, and more. This is the most detailed single-coin endpoint.
tags:
- Coins
parameters:
- $ref: '#/components/parameters/coinId'
- name: localization
in: query
description: Include all localized language descriptions
schema:
type: boolean
default: true
- name: tickers
in: query
description: Include exchange tickers data
schema:
type: boolean
default: true
- name: market_data
in: query
description: Include market data
schema:
type: boolean
default: true
- name: community_data
in: query
description: Include community data
schema:
type: boolean
default: true
- name: developer_data
in: query
description: Include developer data
schema:
type: boolean
default: true
- name: sparkline
in: query
description: Include sparkline 7-day price data
schema:
type: boolean
default: false
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/CoinData'
'404':
description: Coin not found
/coins/{id}/tickers:
get:
operationId: getCoinTickers
summary: Get coin tickers
description: Get trading pair tickers for a specific coin across all exchanges. Results include price, volume, spread, and trust score information.
tags:
- Coins
parameters:
- $ref: '#/components/parameters/coinId'
- name: exchange_ids
in: query
description: Filter tickers by exchange IDs (comma-separated)
schema:
type: string
- name: include_exchange_logo
in: query
description: Include exchange logo URL in the response
schema:
type: boolean
default: false
- name: page
in: query
description: Page number for pagination
schema:
type: integer
minimum: 1
default: 1
- name: order
in: query
description: Sort order for tickers
schema:
type: string
enum:
- trust_score_desc
- trust_score_asc
- volume_desc
- volume_asc
default: trust_score_desc
- name: depth
in: query
description: Include order book depth (2% cost to move)
schema:
type: boolean
default: false
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Coin name
tickers:
type: array
items:
$ref: '#/components/schemas/Ticker'
'404':
description: Coin not found
/coins/{id}/history:
get:
operationId: getCoinHistory
summary: Get historical coin data
description: Get historical data for a specific coin at a given date. Includes price, market cap, 24h volume, and community and developer data.
tags:
- Coins
parameters:
- $ref: '#/components/parameters/coinId'
- name: date
in: query
required: true
description: The date of data snapshot in dd-mm-yyyy format
schema:
type: string
pattern: ^\d{2}-\d{2}-\d{4}$
- name: localization
in: query
description: Include all localized language descriptions
schema:
type: boolean
default: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/CoinData'
'404':
description: Coin not found
/coins/{id}/market_chart:
get:
operationId: getCoinMarketChart
summary: Get coin market chart data
description: Get historical market data including price, market cap, and 24h volume for a specific coin over a time range. Data granularity is automatic based on the number of days requested.
tags:
- Coins
parameters:
- $ref: '#/components/parameters/coinId'
- name: vs_currency
in: query
required: true
description: The target currency for market data
schema:
type: string
- name: days
in: query
required: true
description: Number of days of historical data (1, 7, 14, 30, 90, 180, 365, or max for all available data)
schema:
type: string
- name: interval
in: query
description: Data interval (daily). Leave empty for automatic granularity.
schema:
type: string
enum:
- daily
- name: precision
in: query
description: Decimal precision for currency price values
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/MarketChart'
'404':
description: Coin not found
/coins/{id}/market_chart/range:
get:
operationId: getCoinMarketChartRange
summary: Get coin market chart data within date range
description: Get historical market data including price, market cap, and 24h volume for a specific coin within a custom date range specified by UNIX timestamps.
tags:
- Coins
parameters:
- $ref: '#/components/parameters/coinId'
- name: vs_currency
in: query
required: true
description: The target currency for market data
schema:
type: string
- name: from
in: query
required: true
description: Start date as UNIX timestamp
schema:
type: number
- name: to
in: query
required: true
description: End date as UNIX timestamp
schema:
type: number
- name: precision
in: query
description: Decimal precision for currency price values
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/MarketChart'
'404':
description: Coin not found
/coins/{id}/ohlc:
get:
operationId: getCoinOHLC
summary: Get coin OHLC chart data
description: Get OHLC (Open, High, Low, Close) candlestick data for a specific coin. Data granularity is automatic based on the number of days requested. 1-2 days returns 30-minute candles, 3-30 days returns 4-hour candles, and 31+ days returns daily candles.
tags:
- Coins
parameters:
- $ref: '#/components/parameters/coinId'
- name: vs_currency
in: query
required: true
description: The target currency for OHLC data
schema:
type: string
- name: days
in: query
required: true
description: Number of days of historical data (1, 7, 14, 30, 90, 180, 365)
schema:
type: string
- name: precision
in: query
description: Decimal precision for currency price values
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
type: array
description: OHLC data point as array of [timestamp, open, high, low, close]
items:
type: number
minItems: 5
maxItems: 5
'404':
description: Coin not found
/coins/list/new:
get:
operationId: getNewlyAddedCoins
summary: Get recently added coins
description: Get the list of the latest 200 coins that have been recently added to CoinGecko. This endpoint is exclusive to paid plan subscribers.
tags:
- Coins
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
description: CoinGecko coin identifier
symbol:
type: string
description: Coin ticker symbol
name:
type: string
description: Coin display name
activated_at:
type: integer
description: UNIX timestamp when the coin was added
'401':
description: Unauthorized - invalid or missing Pro API key
'403':
description: Forbidden - endpoint not available on current plan
/coins/top_gainers_losers:
get:
operationId: getTopGainersLosers
summary: Get top gainers and losers
description: Get the top 30 coins with the largest price gain and the top 30 coins with the largest price loss over a specified time duration. This endpoint is exclusive to paid plan subscribers.
tags:
- Coins
parameters:
- name: vs_currency
in: query
required: true
description: The target currency for price data (e.g., usd)
schema:
type: string
default: usd
- name: duration
in: query
description: Time duration for price change calculation
schema:
type: string
enum:
- 1h
- 24h
- 7d
- 14d
- 30d
- 60d
- 1y
default: 24h
- name: top_coins
in: query
description: Filter by top N coins by market cap (e.g., 300 to only consider the top 300 coins)
schema:
type: string
enum:
- '300'
- '500'
- '1000'
- all
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
top_gainers:
type: array
description: Top coins by price increase
items:
$ref: '#/components/schemas/GainerLoser'
top_losers:
type: array
description: Top coins by price decrease
items:
$ref: '#/components/schemas/GainerLoser'
'401':
description: Unauthorized - invalid or missing Pro API key
'403':
description: Forbidden - endpoint not available on current plan
/coins/{id}/circulating_supply_chart:
get:
operationId: getCoinCirculatingSupplyChart
summary: Get coin circulating supply chart
description: Get historical circulating supply chart data for a specific coin. This endpoint is exclusive to paid plan subscribers.
tags:
- Coins
parameters:
- name: id
in: path
required: true
description: The CoinGecko coin ID
schema:
type: string
- name: days
in: query
required: true
description: Number of days of historical data
schema:
type: string
- name: interval
in: query
description: Data interval (daily)
schema:
type: string
enum:
- daily
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
type: array
description: Data point as [timestamp, circulating_supply]
items:
type: number
minItems: 2
maxItems: 2
'401':
description: Unauthorized - invalid or missing Pro API key
'404':
description: Coin not found
/coins/{id}/circulating_supply_chart/range:
get:
operationId: getCoinCirculatingSupplyChartRange
summary: Get coin circulating supply chart within date range
description: Get historical circulating supply chart data for a specific coin within a custom date range specified by UNIX timestamps. This endpoint is exclusive to paid plan subscribers.
tags:
- Coins
parameters:
- name: id
in: path
required: true
description: The CoinGecko coin ID
schema:
type: string
- name: from
in: query
required: true
description: Start date as UNIX timestamp
schema:
type: number
- name: to
in: query
required: true
description: End date as UNIX timestamp
schema:
type: number
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
type: array
description: Data point as [timestamp, circulating_supply]
items:
type: number
minItems: 2
maxItems: 2
'401':
description: Unauthorized - invalid or missing Pro API key
'404':
description: Coin not found
/coins/{id}/total_supply_chart:
get:
operationId: getCoinTotalSupplyChart
summary: Get coin total supply chart
description: Get historical total supply chart data for a specific coin. This endpoint is exclusive to paid plan subscribers.
tags:
- Coins
parameters:
- name: id
in: path
required: true
description: The CoinGecko coin ID
schema:
type: string
- name: days
in: query
required: true
description: Number of days of historical data
schema:
type: string
- name: interval
in: query
description: Data interval (daily)
schema:
type: string
enum:
- daily
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
type: array
description: Data point as [timestamp, total_supply]
items:
type: number
minItems: 2
maxItems: 2
'401':
description: Unauthorized - invalid or missing Pro API key
'404':
description: Coin not found
/coins/{id}/total_supply_chart/range:
get:
operationId: getCoinTotalSupplyChartRange
summary: Get coin total supply chart within date range
description: Get historical total supply chart data for a specific coin within a custom date range specified by UNIX timestamps. This endpoint is exclusive to paid plan subscribers.
tags:
- Coins
parameters:
- name: id
in: path
required: true
description: The CoinGecko coin ID
schema:
type: string
- name: from
in: query
required: true
description: Start date as UNIX timestamp
schema:
type: number
- name: to
in: query
required: true
description: End date as UNIX timestamp
schema:
type: number
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
type: array
description: Data point as [timestamp, total_supply]
items:
type: number
minItems: 2
maxItems: 2
'401':
description: Unauthorized - invalid or missing Pro API key
'404':
description: Coin not found
components:
schemas:
CoinListItem:
type: object
properties:
id:
type: string
description: CoinGecko coin identifier
symbol:
type: string
description: Coin ticker symbol
name:
type: string
description: Coin display name
platforms:
type: object
description: Contract addresses on various platforms
additionalProperties:
type: string
CoinMarket:
type: object
properties:
id:
type: string
description: CoinGecko coin identifier
symbol:
type: string
description: Coin ticker symbol
name:
type: string
description: Coin display name
image:
type: string
format: uri
description: Coin logo image URL
current_price:
type: number
description: Current price in the target currency
market_cap:
type: number
description: Market capitalization in the target currency
market_cap_rank:
type: integer
description: Market cap ranking position
fully_diluted_valuation:
type: number
description: Fully diluted valuation in the target currency
total_volume:
type: number
description: 24-hour trading volume in the target currency
high_24h:
type: number
description: 24-hour price high in the target currency
low_24h:
type: number
description: 24-hour price low in the target currency
price_change_24h:
type: number
description: 24-hour price change amount
price_change_percentage_24h:
type: number
description: 24-hour price change percentage
market_cap_change_24h:
type: number
description: 24-hour market cap change amount
market_cap_change_percentage_24h:
type: number
description: 24-hour market cap change percentage
circulating_supply:
type: number
description: Current circulating supply
total_supply:
type: number
description: Total supply
max_supply:
type: number
description: Maximum supply (null if unlimited)
ath:
type: number
description: All-time high price
ath_change_percentage:
type: number
description: Percentage change from all-time high
ath_date:
type: string
format: date-time
description: Date of all-time high
atl:
type: number
description: All-time low price
atl_change_percentage:
type: number
description: Percentage change from all-time low
atl_date:
type: string
format: date-time
description: Date of all-time low
last_updated:
type: string
format: date-time
description: Timestamp of last data update
GainerLoser:
type: object
properties:
id:
type: string
description: CoinGecko coin identifier
symbol:
type: string
description: Coin ticker symbol
name:
type: string
description: Coin display name
image:
type: string
format: uri
description: Coin logo URL
market_cap_rank:
type: integer
description: Market cap ranking
usd:
type: number
description: Current price in USD
usd_24h_vol:
type: number
description: 24-hour trading volume in USD
usd_24h_change:
type: number
description: 24-hour price change percentage
Ticker:
type: object
properties:
base:
type: string
description: Base currency ticker
target:
type: string
description: Target currency ticker
market:
type: object
properties:
name:
type: string
description: Exchange name
identifier:
type: string
description: Exchange identifier
has_trading_incentive:
type: boolean
description: Whether the exchange has trading incentives
last:
type: number
description: Last traded price
volume:
type: number
description: Trading volume
converted_last:
type: object
description: Last price converted to BTC, ETH, and USD
additionalProperties:
type: number
converted_volume:
type: object
description: Volume converted to BTC, ETH, and USD
additionalProperties:
type: number
trust_score:
type: string
description: Trust score color (green, yellow, red)
bid_ask_spread_percentage:
type: number
description: Bid-ask spread percentage
timestamp:
type: string
format: date-time
description: Ticker data timestamp
last_traded_at:
type: string
format: date-time
description: Last trade timestamp
last_fetch_at:
type: string
format: date-time
description: Last data fetch timestamp
is_anomaly:
type: boolean
description: Whether the ticker is flagged as anomalous
is_stale:
type: boolean
description: Whether the ticker data is stale
trade_url:
type: string
format: uri
description: URL to trade this pair
coin_id:
type: string
description: CoinGecko coin ID of base currency
target_coin_id:
type: string
description: CoinGecko coin ID of target currency
MarketChart:
type: object
properties:
prices:
type: array
description: Price data points as [timestamp, price] arrays
items:
type: array
items:
type: number
minItems: 2
maxItems: 2
market_caps:
type: array
description: Market cap data points as [timestamp, market_cap] arrays
items:
type: array
items:
type: number
minItems: 2
maxItems: 2
total_volumes:
type: array
description: Volume data points as [timestamp, volume] arrays
items:
type: array
items:
type: number
minItems: 2
maxItems: 2
MarketData:
type: object
properties:
current_price:
type: object
description: Current price in various currencies
additionalProperties:
type: number
total_value_locked:
type: number
description: Total value locked (for DeFi tokens)
market_cap:
type: object
description: Market cap in various currencies
additionalProperties:
type: number
total_volume:
type: object
description: 24h volume in various currencies
additionalProperties:
type: number
high_24h:
type: object
description: 24-hour high in various currencies
additionalProperties:
type: number
low_24h:
type: object
description: 24-hour low in various currencies
additionalProperties:
type: number
price_change_24h:
type: number
description: 24-hour price change
price_change_percentage_24h:
type: number
description: 24-hour price change percentage
market_cap_change_24h:
type: number
description: 24-hour market cap change
market_cap_change_percentage_24h:
type: number
description: 24-hour market cap change percentage
circulating_supply:
type: number
description: Current circulating supply
total_supply:
type: number
description: Total supply
max_supply:
type: number
description: Maximum supply
CoinData:
type: object
properties:
id:
type: string
description: CoinGecko coin identifier
symbol:
type: string
description: Coin ticker symbol
name:
type: string
description: Coin display name
asset_platform_id:
type: string
description: Asset platform identifier if token
platforms:
type: object
description: Contract addresses on various platforms
additionalProperties:
type: string
block_time_in_minutes:
type: integer
description: Average block time in minutes
hashing_algorithm:
type: string
description: Mining or hashing algorithm
categories:
type: array
items:
type: string
description: Categories the coin belongs to
description:
type: object
description: Localized descriptions
additionalProperties:
type: string
links:
type: object
description: Related links (homepage, blockchain sites, forums, etc.)
image:
type: object
description: Coin logo images at various sizes
properties:
thumb:
type: string
format: uri
small:
type: string
format: uri
large:
type: string
format: uri
genesis_date:
type: string
format: date
description: Date the coin was created
market_cap_rank:
type: integer
description: Market cap ranking position
market_data:
$ref: '#/components/schemas/MarketData'
last_updated:
type: string
format: date-time
description: Timestamp of last data update
parameters:
coinId:
name: id
in: path
required: true
description: The CoinGecko coin ID (e.g., bitcoin, ethereum)
schema:
type: string
securitySchemes:
demoApiKeyHeader:
type: apiKey
in: header
name: x-cg-demo-api-key
description: CoinGecko Demo API key passed via request header. Obtain a free key from the CoinGecko developer dashboard.
demoApiKeyQuery:
type: apiKey
in: query
name: x_cg_demo_api_key
description: CoinGecko Demo API key passed via query string parameter.
externalDocs:
description: CoinGecko API Documentation
url: https://docs.coingecko.com