* To filter results based on the coin's category, use the `category` param (refer to [`/coins/categories/list`](https://docs.coingecko.com/v3.0.1/reference/coins-categories-list) for available categories).
v3.0.1/reference/api-reference/coingecko-demo.json get /coins/{id}/contract/{contract_address}/market_chart/range
This endpoint allows you to **get the historical chart data within certain time range in UNIX along with price, market cap and 24hr volume based on asset platform and particular token contract address**
* You may obtain the asset platform and contract address via several ways:
* refers to respective coin page and find 'contract address'.
* You may leave the interval params as empty for automatic granularity:
* 1 day from current time = **5-minutely** data
* 1 day from any time (except current time) = **hourly** data
* 2 - 90 days from any time = **hourly** data
* above 90 days from any time = **daily** data (00:00 UTC)
* Cache / Update Frequency:\
Based on days range (all the API plans)
* 1 day = 30 seconds cache
* 2 -90 days = 30 minutes cache
* 90 days = 12 hours cache
* The last completed UTC day (00:00) is available 35 minutes after midnight on the next UTC day (00:35). The cache will always expire at 00:40 UTC.
* Access to historical data via the Public API (Demo plan) is **restricted to the past 365 days** only. To access the complete range of historical data, please subscribe to one of our [paid plans](https://www.coingecko.com/en/api/pricing) to obtain a Pro-API key.
* You can retrieve pools or tokens of a specific category with this endpoint: [Pools by Category ID](https://docs.coingecko.com/reference/pools-category).
* GeckoTerminal categories are different from [CoinGecko categories](https://docs.coingecko.com/reference/coins-categories-list).
v3.0.1/reference/api-reference/onchain-demo.json get /search/pools
This endpoint allows you to **search for pools on a network**
* You may use this endpoint to search for query such as pool contract address, token contract address or token symbol. The endpoint will return matching pools as response.
* You may include values such as `page` to specify which page of responses you would like to show.
</Tip>
* If the token's market cap is not verified by the team, the API response will return `null` for its market cap value, even though it has a displayed value on GeckoTerminal, which might not be accurate as it often matches the Fully Diluted Valuation (FDV).
* Attributes specified in the `include` param will be returned under the top-level "included" key.
* This endpoint returns up to 20 pools per page. Use the `page` param to navigate more results.
*`page`: Pagination beyond 10 pages is available for [Paid Plan](https://www.coingecko.com/en/api/pricing) subscribers (Analyst plan or above).
| `c` | `channel_type` | string | Indicates the type of channel subscribed to. | G1 |
| `n` | `network_id` | string | Identifier of the blockchain network. Check full list of IDs [here](https://api.geckoterminal.com/api/v2/networks?page=1). | `eth` |
| `ta` | `token_address` | string | Contract address of the token on the blockchain. | `0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2` |
| `p` | `usd_price` | float | Current token price in USD. | 3639.78228844745 |
| `pp` | `usd_price_24h_change_percentage` | float | Percentage change in token price over the last 24 hours. | 3.566 |
| `t` | `last_updated_at` | integer | Timestamp of the last data update in UNIX time. | 1709542750 |
**Tips**: The Websocket payload will use the value `null` when specific data is unavailable. Ensure your application is capable of handling null values for fields that may not always have data.
## 1. Establish Connection to Websocket
<CodeGroup>
</CodeGroup>
## 2. Subscribe to a specific channel - OnchainSimpleTokenPrice
<CodeGroup>
</CodeGroup>
<CodeGroup>
</CodeGroup>
## 3. Stream OnchainSimpleTokenPrice data
<CodeGroup>
</CodeGroup>
<CodeGroup>
</CodeGroup>
<CodeGroup>
</CodeGroup>
The output keys will be in random order.
### Un-subscribe to stop streaming OnchainSimpleTokenPrice data
**Input Example:** Unsubscribe for 1 specific token data:
<CodeGroup>
</CodeGroup>
<CodeGroup>
</CodeGroup>
**Input Example:** Unsubscribe from OnchainSimpleTokenPrice channel and all token data:
<CodeGroup>
</CodeGroup>
<CodeGroup>
</CodeGroup>
**Examples:**
Example 1 (unknown):
```unknown
</CodeGroup>
## 2. Subscribe to a specific channel - OnchainSimpleTokenPrice
**Input Example:**
<CodeGroup>
```
Example 2 (unknown):
```unknown
</CodeGroup>
**Output Example**:
<CodeGroup>
```
Example 3 (unknown):
```unknown
</CodeGroup>
## 3. Stream OnchainSimpleTokenPrice data
**Input Example:**
<CodeGroup>
```
Example 4 (unknown):
```unknown
</CodeGroup>
**Output Example**:
<CodeGroup>
```
---
## OnchainOHLCV
**URL:** llms-txt#onchainohlcv
**Contents:**
- Data Payload
- 1. Establish Connection to Websocket
- 2. Subscribe to a specific channel - OnchainOHLCV
- 3. Stream OnchainOHLCV data
- Tips:
- Un-subscribe to stop streaming OnchainOHLCV data
Subscribe to receive real-time OHLCV updates for pools, as seen on GeckoTerminal.com
This Websocket channel allows you to subscribe to real-time OHLCV updates of a pool.
* Lookup by Network + Pool Address
* It will return **O**pen, **H**igh, **L**ow, **C**lose price and **V**olume data the specified pool.
**Update Frequency**: as fast as 1s, for actively traded pools.
**Tips**: use this Rest API endpoint [Top Pools by Token Address](https://docs.coingecko.com/reference/top-pools-contract-address#/) to obtain contract address of the most liquid pool.
* You may stream the pool ohlcv data based on `base` or `quote` token of a pool.
* Please note that your subscription quota is based on the number of **unique data streams** you request. Each unique combination of an interval and token for a given pool is considered a **distinct subscription** and will count towards your max subscription limit.
| `ch` | `channel_type` | string | Indicates the type of channel subscribed to. | G3 |
| `n` | `network_id` | string | Identifier of the blockchain network. Check full list of IDs [here](https://api.geckoterminal.com/api/v2/networks?page=1). | eth |
| `pa` | `pool_address` | string | Contract address of the pool. | `0x88e6a0c2dd6fcb..3f5640` |
**Tips**: The Websocket payload will use the value `null` when specific data is unavailable. Ensure your application is capable of handling null values for fields that may not always have data.
## 1. Establish Connection to Websocket
<CodeGroup>
</CodeGroup>
## 2. Subscribe to a specific channel - OnchainOHLCV
<CodeGroup>
</CodeGroup>
<CodeGroup>
</CodeGroup>
## 3. Stream OnchainOHLCV data
**Input Example:** (1 minute interval and base token of a pool)
v3.0.1/reference/api-reference/coingecko-demo.json get /coins/{id}/history
This endpoint allows you to **query the historical data (price, market cap, 24hrs volume, ...) at a given date for a coin based on a particular coin ID**
* You may obtain the coin ID (API ID) via several ways:
* refers to respective coin page and find 'API ID'.
* refers to Google Sheets [here](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
</Tip>
* The data returned is at `00:00:00 UTC`.
* The last completed UTC day (00:00) is available 35 minutes after midnight on the next UTC day (00:35).
* Access to historical data via the Public API (Demo plan) is **restricted to the past 365 days** only. To access the complete range of historical data, please subscribe to one of our [paid plans](https://www.coingecko.com/en/api/pricing) to obtain a Pro-API key.
v3.0.1/reference/api-reference/coingecko-demo.json get /coins/{id}/contract/{contract_address}/market_chart
This endpoint allows you to **get the historical chart data including time in UNIX, price, market cap and 24hr volume based on asset platform and particular token contract address**
* You may obtain the asset platform and contract address via several ways:
* refers to respective coin page and find 'contract address'.
* You may leave the interval as empty for automatic granularity:
* 1 day from current time = **5-minutely** data
* 2 - 90 days from current time = **hourly** data
* above 90 days from current time = **daily** data (00:00 UTC)
* Cache / Update Frequency:
* Every 5 minutes for all the API plans.
* The last completed UTC day (00:00) is available 35 minutes after midnight on the next UTC day (00:35). The cache will always expire at 00:40 UTC.
* Access to historical data via the Public API (Demo plan) is **restricted to the past 365 days** only. To access the complete range of historical data, please subscribe to one of our [paid plans](https://www.coingecko.com/en/api/pricing) to obtain a Pro-API key.
MCP Server for Crypto Price & Market Data. MCP (Model Context Protocol) is an open standard that allows Large Language Model (LLM) and other AI agents to securely and intelligently interact with external data sources and tools.
**CoinGecko MCP Server is currently in Beta.** We're constantly improving, and your feedback is crucial. Please share any thoughts or suggestions via [this feedback form](https://docs.google.com/forms/d/e/1FAIpQLSf06DOBauiZ8XS6NwWXUUwhFluH7jKHOAa3y4VsrkyGbLKyfA/viewform).
* If you would like to query token information such as socials, websites, description and etc. You can go to this endpoint [`/networks/{network}/tokens/{address}/info`](https://docs.coingecko.com/v3.0.1/reference/token-info-contract-address) instead.
* If the token's market cap is not verified by the team, the API response will return `null` for its market cap value, even though it has a displayed value on GeckoTerminal, which might not be accurate as it often matches the Fully Diluted Valuation (FDV).
* Market Cap can be verified by and sourced from CoinGecko, and the number may be higher than FDV as it may include Market Cap of tokens issued on other blockchain network.
* Attributes specified in the `include` param will be returned under the top-level "included" key.
* Set `include_composition=true` to surface the balance and liquidity value of the pool's base and quote tokens. (requires `include=top_pools`)
* For tokens on a bonding curve (i.e. non-graduated tokens from launchpads), the response will include a `launchpad_details` object containing their graduation status and details.
v3.0.1/reference/api-reference/onchain-demo.json get /networks/{network}/pools/{pool_address}/info
This endpoint allows you to **query pool metadata (base and quote token details, image, socials, websites, description, contract address, etc.) based on a provided pool contract address on a network**
* If you would like to query pool data such as price, transactions, volume and etc. You can go to this endpoint [`/networks/{network}/pools/{address}`](https://docs.coingecko.com/v3.0.1/reference/pool-address) instead.
* Learn more about GT score [here](https://support.coingecko.com/hc/en-us/articles/38381394237593-What-is-GT-Score-How-is-GT-Score-calculated).
* Metadata (image, websites, description, socials) may be sourced on-chain and is not vetted by the CoinGecko team. If you wish to get metadata reviewed by CoinGecko team, you may use the following endpoints:
*`holders` data is currently in Beta, with ongoing improvements to data quality, coverage, and update frequency.
* Supported chains include: Solana, EVM (Ethereum, Polygon, BNB, Arbitrum, Optimism, Base), Sui, TON, and Ronin.
*`distribution_percentage` coverage:
* Solana: `top_10`, `11_20`, `21_40`, `rest`
* Other chains: `top_10`, `11_30`, `31_50`, `rest`
* For tokens on a bonding curve (i.e. non-graduated tokens from launchpads), the response will include a `launchpad_details` object containing their graduation status and details.
- Designed to make your life easier: Common Benefits of Our SDKs
The official CoinGecko Typescript and Python SDK are now available for all developers! These SDKs dramatically streamline your integration process, enabling you to build powerful crypto applications faster and more reliably than ever before, regardless of your preferred language.
### Designed to make your life easier: Common Benefits of Our SDKs
* **Official Support**: Both SDKs are maintained by the CoinGecko team, ensuring up-to-date features, reliable access, and dedicated support.
* **Reduced Boilerplate**: Say goodbye to manual request construction and parsing. Our SDKs handle the complexities, allowing you to focus on your application logic.
* **Faster Development**: Build and iterate quicker with intuitive methods, clear documentation, and pre-built functionalities tailored for each language.
* **Seamless Integration**: Effortlessly incorporate CoinGecko data into your existing Python or TypeScript projects.
v3.0.1/reference/api-reference/coingecko-demo.json get /coins/{id}/market_chart
This endpoint allows you to **get the historical chart data of a coin including time in UNIX, price, market cap and 24hr volume based on particular coin ID**
* You may obtain the coin ID (API ID) via several ways:
* refers to respective coin page and find 'API ID'.
* refers to google sheets [here](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
* You may use tools like [epoch converter ](https://www.epochconverter.com) to convert human readable date to UNIX timestamp.
</Tip>
* You may leave the interval as empty for automatic granularity:
* 1 day from current time = **5-minutely** data
* 2 - 90 days from current time = **hourly** data
* above 90 days from current time = **daily** data (00:00 UTC)
* Cache / Update Frequency:
* Every 30 seconds for all the API plans (for last data point).
* The last completed UTC day (00:00) data is now available **10 minutes after midnight** on the next UTC day (00:10).
* Access to historical data via the Public API (Demo plan) is **restricted to the past 365 days** only. To access the complete range of historical data, please subscribe to one of our [paid plans](https://www.coingecko.com/en/api/pricing) to obtain a Pro-API key.
* refers to Google Sheets [here](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
* You can retrieve specific coins using their unique `ids`, `names`, or `symbols`.
* You may flag to include more data such as market cap, 24hr volume, 24hr change, last updated time etc.
* To verify if a price is stale, you may flag `include_last_updated_at=true` in your request to obtain the latest updated time. Alternatively, you may flag `include_24hr_change=true` to determine if it returns a `null` value.
</Tip>
* You may cross-check the price on [CoinGecko](https://www.coingecko.com) and learn more about our price methodology [here](https://www.coingecko.com/en/methodology).
* When multiple lookup params are provided, the following priority order is applied: `ids` (highest) > `names` > `symbols` (lowest).
* When searching by `name`, you need to URL-encode any spaces (e.g. "Binance Coin" becomes "Binance%20Coin").
* The `include_tokens=all` param is exclusively for use with the `symbols` lookup and is limited to maximum of 50 symbols per request.
* Wildcard searches are not supported for lookup params (`ids`, `names`, `symbols`).
* Cache/Update Frequency: every 60 seconds for Public API.
* Every 20 seconds for [Pro-API](https://www.coingecko.com/en/api/pricing) (Analyst, Lite, Pro, Enterprise).
v3.0.1/reference/api-reference/onchain-demo.json get /networks/{network}/pools/{address}
This endpoint allows you to **query the specific pool based on the provided network and pool address**
* Address not found in GeckoTerminal will be ignored.
* If the token's market cap is not verified by the team, the API response will return `null` for its market cap value, even though it has a displayed value on GeckoTerminal, which might not be accurate as it often matches the Fully Diluted Valuation (FDV).
* Market Cap can be verified by and sourced from CoinGecko, and the number may be higher than FDV as it may include Market Cap of tokens issued on other blockchain network.
* Attributes specified in the `include` param will be returned under the top-level "included" key.
*`locked_liquidity_percentage` will be updated on daily basis.
* Set `include_composition=true` to surface the balance and liquidity value of the pool's base and quote tokens.
* Pools on a bonding curve (e.g. non-graduated pools from launchpads) will return `launchpad_details` object with their graduation status and migration details.
v3.0.1/reference/api-reference/coingecko-demo.json get /coins/{id}/contract/{contract_address}
This endpoint allows you to **query all the metadata (image, websites, socials, description, contract address, etc.) and market data (price, ATH, exchange tickers, etc.) of a coin from the CoinGecko coin page based on an asset platform and a particular token contract address**
* Please note that the `twitter_followers` data field will no longer be supported by our API starting on May 15, 2025. Please refer to [changelog](https://docs.coingecko.com/changelog#upcoming-change-notice%3A-removal-of-twitter-followers-data) for more details.
v3.0.1/reference/api-reference/coingecko-demo.json get /coins/{id}
This endpoint allows you to **query all the metadata (image, websites, socials, description, contract address, etc.) and market data (price, ATH, exchange tickers, etc.) of a coin from the CoinGecko coin page based on a particular coin ID**
* You may obtain the coin `id` (API ID) via several ways:
* refers to respective coin page and find "API ID".
* Tickers are limited to 100 items, to get more tickers, please go to [/coins/{id}/tickers](https://docs.coingecko.com/v3.0.1/reference/coins-id-tickers).
* Coin descriptions may include newline characters represented as `\r\n` (escape sequences), which may require processing for proper formatting.
* When `dex_pair_format=symbol`, the DEX pair `base` and `target` are displayed in symbol format (e.g. `WETH`, `USDC`) instead of as contract addresses.
* Cache/Update Frequency:
* Every 60 seconds for all the API plans.
* Community data for Telegram will be updated on weekly basis (Reddit & Twitter community data are no longer supported).
* The provided endpoint URL includes parameters such as `ids=bitcoin` and `vs_currencies=usd`, indicating that the intention to retrieve the current price of Bitcoin in US Dollars.
**How to obtain Coin ID aka API ID?** There are 3 options:
* View the full list of coins with API ID, symbol and name using this [Google Sheet](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
* Look for the "API ID“ by visiting the info section of a coin page on CoinGecko:
Other than using Coin ID, you may also query price & market data of a coin using contract address, using [/simple/token\_price/\{id](https://docs.coingecko.com/reference/simple-token-price)} endpoint as example:
* Look for the "Contract“ by visiting the info section of a coin page on CoinGecko.
* Not all coins will have a contract address listed on the CoinGecko site.
* If an address is not shown on the CoinGecko page, you will not be able to query the coin by its contract address via the API.
* The contract addresses are curated by the CoinGecko team, if you find out any missing contract address, feel free to [share](https://support.coingecko.com/hc/en-us/requests/new) with us to review.
* [Block Explorer (Etherscan)](https://etherscan.io/token/0x1f9840a85d5af5bf1d1762f925bdaddc4201f984)
## Specify target currency to return
In the 2 examples above, both queries for Coin ID and Contract Address contain `vs_currencies=usd`. Most of the CoinGecko API endpoints will require you to specify the currency.
CoinGecko API data supports all major fiat currencies and some famous crypto currencies like the following:
| Type | Currency | vs\_currencies (Param value) |
For full list of supported currencies, please go to [/simple/supported\_vs\_currencies](https://docs.coingecko.com/reference/simple-supported-currencies) endpoint
There are 4 parameters values applied for this endpoint:
*`vs_currency`: `usd`
*`order`: `market_cap_desc` — The endpoint response will be sorted in descending order, from the coins with the largest market cap to those with the smallest.
*`per_page`: `100` — The results of coins per page are set at 100 in this case (maximum is 250).
*`page`: `1` — The page number of the results is determined by the parameter `per_page`. In the case of `per_page=100` and `page=2`, the responses will include coins ranked 101 to 200 on CoinGecko, sorted by market cap, as per the specified endpoint.
**Examples:**
Example 1 (unknown):
```unknown
</CodeGroup>
* View the full list of coins with API ID, symbol and name using this [Google Sheet](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
* Look for the "API ID“ by visiting the info section of a coin page on CoinGecko:
Other than using Coin ID, you may also query price & market data of a coin using contract address, using [/simple/token\_price/\{id](https://docs.coingecko.com/reference/simple-token-price)} endpoint as example:
| Get Full List with IDs | [/coins/list](https://docs.coingecko.com/reference/coins-list) | [/nfts/list](https://docs.coingecko.com/reference/nfts-list) | [/exchanges/list](https://docs.coingecko.com/reference/exchanges-list) | [/derivatives/exchanges/list](https://docs.coingecko.com/reference/derivatives-exchanges-list) |
| Get latest market data | [/coins/\{id}](https://docs.coingecko.com/reference/coins-id) | [/nfts/\{id}](https://docs.coingecko.com/reference/nfts-id) | [/exchanges/\{id}](https://docs.coingecko.com/reference/exchanges-id) | [/derivatives/exchanges/\{id}](https://docs.coingecko.com/reference/derivatives-exchanges-id) |
| Get Historical Data | [/coins/\{id}/market\_chart](https://docs.coingecko.com/reference/coins-id-market-chart) | [/nfts/\{id}/market\_chart](https://docs.coingecko.com/reference/nfts-id-market-chart) | [/exchanges/\{id}/volume\_chart](https://docs.coingecko.com/reference/exchanges-id-volume-chart) | [/exchanges/\{id}/volume\_chart](https://docs.coingecko.com/reference/exchanges-id-volume-chart) |
* You may flag to include more data such as market cap, 24hr volume, 24hr change, last updated time etc.
</Tip>
* The endpoint returns the global average price of the coin that is aggregated across all active exchanges on CoinGecko.
* You may cross-check the price on [CoinGecko](https://www.coingecko.com) and learn more about our price methodology [here](https://www.coingecko.com/en/methodology).
* Cache/Update Frequency: every 60 seconds for Public API.
* Every 20 seconds for [Pro-API](https://www.coingecko.com/en/api/pricing) (Analyst, Lite, Pro, Enterprise).
</Note>
---
## CoinGecko SDK (Beta)
**URL:** llms-txt#coingecko-sdk-(beta)
Source: https://docs.coingecko.com/docs/sdk
Official CoinGecko Typescript and Python SDKs — Crypto Price & Market Data API
* Exclusive for all Paid Plan Subscribers (Analyst, Lite, Pro and Enterprise).
</Note>
---
## 💡 Example Prompts
**URL:** llms-txt#💡-example-prompts
**Contents:**
- Simple Queries
- Advanced Queries
- Creative and Fun Ideas
Tap into the full potential of CoinGecko data — use these prompts to kickstart your next AI build.
> * What is the current price of Bitcoin in USD?
> * What is the market cap of Ethereum?
> * What are the top 3 trending coins on CoinGecko right now?
> * What are the top AI coins on GeckoTerminal now?
> * What is the floor price of the Pudgy Penguins NFT collection?
> * Show me the current top 10 cryptocurrencies by market cap. Include their price, 24h change, and total volume. Display this in an interactive table.
CoinGecko API: Stream Real-Time Crypto Data with WebSockets
## Access Real-Time Crypto Data Instantly with CoinGecko WebSockets
In the fast-paced world of cryptocurrency, speed matters. Our official CoinGecko WebSocket API provides a dedicated, persistent connection for real-time data streaming, ensuring you receive critical market updates the moment they happen.
Move beyond traditional polling and embrace the power of instant data delivery for your trading bots, dashboards, and analytical applications.
<Tip>
CoinGecko Websocket (Beta) is now available for [paid plan ](https://www.coingecko.com/en/api/pricing)customers (Analyst plan & above)!
* For Analyst, Lite, Pro, and Pro+ self-serve customers, you will be eligible to access the following features, and stream real-time data by utilising your monthly API plan credits:
* Max connections: 10 concurrent socket connections
* Max subscriptions: 100 token or pool data subscription per channel, per socket
* Channel Access: all 4 channels
* Credit charge: 0.1 credit per response returned, deducting from monthly API plan credits
We will gradually improve the Websocket and expand the feature limits. Please share your feedback and suggestion via this [survey form](https://forms.gle/gNE1Txc9FCV55s7ZA), or email soonaik\@coingecko\[dot]com
</Tip>
* For existing **Enterprise plan** clients who wish to unlock higher limits (max connections, max subscriptions, and lower credit charge), please contact your Customer Success Manager.
| [OnchainSimpleTokenPrice](https://docs.coingecko.com/websocket/onchainsimpletokenprice) | G1 | Subscribe to receive real-time price updates for tokens, as seen on GeckoTerminal.com |
| [CGSimplePrice](https://docs.coingecko.com/websocket/cgsimpleprice) | C1 | Subscribe to receive real-time price updates for tokens, as seen on CoinGecko.com |
| [OnchainTrade](https://docs.coingecko.com/websocket/wss-onchain-trade) | G2 | Subscribe to receive real-time transaction updates for pools, as seen on GeckoTerminal.com |
| [OnchainOHLCV](https://docs.coingecko.com/websocket/wssonchainohlcv/) | G3 | Subscribe to receive real-time OHLCV (Open, High, Low, Close, Volume) for pools, as seen on GeckoTerminal.com |
* **Real-Time Data**: Once subscribed, you will start receiving real-time data updates based on your subscriptions. The received data will be in JSON format and will contain the relevant information for the subscribed event.
* **Close Connection:** When you're done receiving updates or want to close the WebSocket connection, you can gracefully close the connection.
* **Security Considerations:** Ensure that you keep your Pro-API key secure and do not expose it publicly in your code or any public repositories.
</Note>
### Connection Handling
To provide you with the most reliable and efficient experience, please be aware of the following regarding our WebSocket connections:
* To ensure your connection remains active and healthy, we send a **"ping" signal every 10 seconds**.
* If we **do not receive a "pong" response from your client within 20 seconds** of sending a ping, we will automatically disconnect the connection.
* **Action Required (Client-Side)**: Your WebSocket client must be configured to respond to our ping messages with a pong. Most WebSocket libraries handle this automatically, but please verify your implementation to ensure it's sending pong responses. This is critical for maintaining your connection.
* **Purpose**: From time to time, we will perform system reboots or deploy new versions of our service to implement updates, bug fixes, and improvements. These actions require a graceful restart of our servers.
* **Impact**: During these periods, your active WebSocket connections might be temporarily disconnected.
* **Action Required (Client-Side)**: It is essential that your application is designed to automatically attempt to re-establish the WebSocket connection if it detects a disconnection. Implementing an exponential backoff strategy for reconnection attempts is highly recommended to avoid overwhelming our servers during a widespread disconnection event.
**Tips**: use this Rest API endpoint [Top Pools by Token Address](https://docs.coingecko.com/reference/top-pools-contract-address) to obtain contract address of the most liquid pool.
| `ch` | `channel_type` | string | Indicates the type of channel subscribed to. | G2 |
| `n` | `network_id` | string | Identifier of the blockchain network. Check full list of IDs [here](https://api.geckoterminal.com/api/v2/networks?page=1). | eth |
| `pa` | `pool_address` | string | Contract address of the pool. | `0x88e6a0c2dd6fcb..3f5640` |
| `vo` | `volume_in_usd` | float | The transaction value in USD. | 1000 |
| `pc` | `price_in_token_currency` | float | Current token price in target token currency | 3639.78228844745 |
| `pu` | `price_in_usd` | float | Current token price in USD | 3.566 |
| `t` | `last_updated_at` | integer | Timestamp of the last data update in UNIX time. | 1752072129000 |
**Tips**: The Websocket payload will use the value `null` when specific data is unavailable. Ensure your application is capable of handling null values for fields that may not always have data.
## 1. Establish Connection to Websocket
<CodeGroup>
</CodeGroup>
## 2. Subscribe to a specific channel - OnchainTrade
<CodeGroup>
</CodeGroup>
<CodeGroup>
</CodeGroup>
## 3. Stream OnchainTrade data
<CodeGroup>
</CodeGroup>
<CodeGroup>
</CodeGroup>
<CodeGroup>
</CodeGroup>
The output keys will be in random order.
### Un-subscribe to stop streaming OnchainTrade data
**Input Example:** Unsubscribe for 1 specific pool data:
<CodeGroup>
</CodeGroup>
<CodeGroup>
</CodeGroup>
**Input Example:** Unsubscribe from OnchainTrade channel and all pools data:
<CodeGroup>
</CodeGroup>
<CodeGroup>
</CodeGroup>
**Examples:**
Example 1 (unknown):
```unknown
</CodeGroup>
## 2. Subscribe to a specific channel - OnchainTrade
**Input Example:**
<CodeGroup>
```
Example 2 (unknown):
```unknown
</CodeGroup>
**Output Example**:
<CodeGroup>
```
Example 3 (unknown):
```unknown
</CodeGroup>
## 3. Stream OnchainTrade data
**Input Example:**
<CodeGroup>
```
Example 4 (unknown):
```unknown
</CodeGroup>
**Output Example**:
<CodeGroup>
```
---
## 💼 Historical Token Holders Chart by Token Address
* For historical chart data with better granularity, you may consider using [/coins/\{id}/market\_chart](https://docs.coingecko.com/v3.0.1/reference/coins-id-market-chart) endpoint.
* The timestamp displayed in the payload (response) indicates the end (or close) time of the OHLC data.
* Data granularity (candle's body) is automatic:
* 1 - 2 days: 30 minutes
* 3 - 30 days: 4 hours
* 31 days and beyond: 4 days
* Cache / Update Frequency:
* Every 15 minutes for all the API plans.
* The last completed UTC day (00:00) is available 35 minutes after midnight on the next UTC day (00:35).
* Access to historical data via the Public API (Demo plan) is **restricted to the past 365 days** only. To access the complete range of historical data, please subscribe to one of our [paid plans](https://www.coingecko.com/en/api/pricing) to obtain a Pro-API key.
</Note>
---
## 🐍 CoinGecko Python SDK
**URL:** llms-txt#🐍-coingecko-python-sdk
**Contents:**
- Install via `pip`
- Resources
Built to seamlessly integrate with the Python ecosystem, enabling fast and intuitive access to CoinGecko's API.
* **Pythonic Simplicity**: Leverage idiomatic Python to interact with the API effortlessly—ideal for data analysis, prototyping, or production use.
* **Streamlined Development**: Clean and consistent interface designed to accelerate workflows and reduce boilerplate in your Python projects.
v3.0.1/reference/api-reference/onchain-demo.json get /networks/{network}/new_pools
This endpoint allows you to **query all the latest pools based on provided network**
* You may include values such as `page` to specify which page of responses you would like to show.
</Tip>
* This endpoint includes the newly created pools in the past 48 hours.
* If the token's market cap is not verified by the team, the API response will return `null` for its market cap value, even though it has a displayed value on GeckoTerminal, which might not be accurate as it often matches the Fully Diluted Valuation (FDV).
* Attributes specified in the `include` param will be returned under the top-level "included" key.
* This endpoint returns up to 20 pools per page. Use the `page` param to navigate more results.
*`page`: Pagination beyond 10 pages is available for [Paid Plan](https://www.coingecko.com/en/api/pricing) subscribers (Analyst plan or above).
v3.0.1/reference/api-reference/onchain-demo.json get /networks/new_pools
This endpoint allows you to **query all the latest pools across all networks on GeckoTerminal**
* You may include values such as `page` to specify which page of responses you would like to show.
</Tip>
* If the token's market cap is not verified by the team, the API response will return `null` for its market cap value, even though it has a displayed value on GeckoTerminal, which might not be accurate as it often matches the Fully Diluted Valuation (FDV).
* Attributes specified in the `include` param will be returned under the top-level "included" key.
* This endpoint returns up to 20 pools per page. Use the `page` param to navigate more results.
*`page`: Pagination beyond 10 pages is available for [Paid Plan](https://www.coingecko.com/en/api/pricing) subscribers (Analyst plan or above).
v3.0.1/reference/api-reference/onchain-demo.json get /networks/{network}/pools/{pool_address}/ohlcv/{timeframe}
This endpoint allows you to **get the OHLCV chart (Open, High, Low, Close, Volume) of a pool based on the provided pool address on a network**
* You may use this endpoint to query the historical price and volume of a token.
* You may select the timeframe with its respective aggregate to get the intended OHLCV data (e.g. `minute?aggregate=15` for 15 minutes OHLCV).
</Tip>
* This endpoint uses epoch/unix format for its timestamp. Example: `1708850449`.
* [Paid plan](https://www.coingecko.com/en/api/pricing) subscribers (Analyst plan & above) can access data from **September 2021 to the present**, depending on when the pool started tracking on GeckoTerminal.
* If no earlier data is available, an empty response will be returned.
* Each API call can only retrieve data for a **maximum range of 6 months**. To fetch older data, use the `before_timestamp` parameter to query in multiple requests.
* Pools with more than 2 tokens are not yet supported for this endpoint.
* Each OHLCV array (under "ohlcv\_list") consists of 6 elements in the following order:
* Timestamp: The epoch/unix timestamp representing the start of the time interval.
* Open: The opening price of the asset at the beginning of the interval.
* High: The highest price reached during the interval.
* Low: The lowest price reached during the interval.
* Close: The price of the asset at the end of the interval.
* Volume: The total trading volume of the asset during the interval.
* **Skipped Intervals**: To ensure concise and relevant data, specific timeframe intervals (e.g. minutely) with no recorded swaps are **excluded** from the response.
* Higher granularity timeframes (e.g. 1 minute) are more likely to skip intervals due to periods of inactivity, while lower granularity timeframes (e.g. daily) are less affected.
* For `include_empty_intervals` param:
* When `false` (default): Only intervals with trade data are returned.
* When `true`: All requested intervals are returned, those with no trade data are populated as follows:
* OHLC (Open, High, Low, Close) are all set to the Close price of the previous interval.
* *O = H = L = C = previous Close*
* Volume (V) is set to 0, reflecting no trade activity.
reference/api-reference/onchain-pro.json get /pools/trending_search
This endpoint allows you to **query all the trending search pools across all networks on GeckoTerminal**
* If the token's market cap is not verified by the team, the API response will return `null` for its market cap value, even though it has a displayed value on GeckoTerminal, which might not be accurate as it often matches the Fully Diluted Valuation (FDV).
* Attributes specified in the `include` param will be returned under the top-level "included" key.
* Cache/Update frequency: every 60 seconds.
* 💼 Exclusive for [Paid Plan](https://www.coingecko.com/en/api/pricing) subscribers (Analyst plan or above).
* This endpoint can be used to query other coin's metadata like: links, categories, contract address, community, description in different languages and many more.
* Coin descriptions may include newline characters represented as `\r\n` (escape sequences), which may require processing for proper formatting.
* Use [Token Info by Token Address](https://docs.coingecko.com/reference/token-info-contract-address) endpoint to get metadata of tokens listed on GeckoTerminal.com.
* For CoinGecko [categories](https://www.coingecko.com/en/categories), use [/coins/markets](https://docs.coingecko.com/reference/coins-markets) endpoint by supplying specific category.
* For GeckoTerminal [categories](https://www.geckoterminal.com/category), use [Pools by Category ID](https://docs.coingecko.com/reference/pools-category) endpoint by supplying specific category.
* Use [/coins/id](https://docs.coingecko.com/reference/coins-id) or [/coins/markets](https://docs.coingecko.com/reference/coins-markets) endpoints by flagging `sparkline = true`.
* If you wish to the obtain the URL slug of a specific CoinGecko Coin Page, e.g. `www.coingecko.com/en/coins/{web_slug}` you may use [/coin/id](https://docs.coingecko.com/reference/coins-id) endpoint and obtain the **`{web_slug}`** value.
* Active: use [/coins/list](https://docs.coingecko.com/reference/coins-list) endpoint, only active coins will be shown by default. You may also flag **`status=inactive`** to get a list of inactive coins.
* Price Stale: use [/simple/price](https://docs.coingecko.com/reference/simple-price) endpoint, flag `include_last_updated_at=true` to check latest update time.
* Current exchange rate: use [/exchange\_rates](https://docs.coingecko.com/reference/exchange-rates) endpoint.
* Historical exchange rate: use [/coins/id/history](https://docs.coingecko.com/reference/coins-id-history) or [/coins/id/market\_chart](https://docs.coingecko.com/reference/coins-id-market-chart) endpoints.
* [/search](https://docs.coingecko.com/reference/search-data) endpoint allows you to search for coins, categories, exchanges (markets), and NFTs listed on CoinGecko.com. You may query by name or symbol.
* [/search-pools](https://docs.coingecko.com/reference/search-pools) endpoint allows you to search for pools listed on GeckoTerminal.com. You may query by pool contract address, token contract address, or token symbol.
## 19. Get List of Blockchain Networks supported on CoinGecko and GeckoTerminal.
CoinGecko and GeckoTerminal support different sets of blockchain networks. You can use the following endpoints to find the list of supported networks and their respective IDs:
You may use the [/asset-platforms-list](https://docs.coingecko.com/reference/asset-platforms-list) endpoint to obtain the native coin ID of all networks (asset platforms) listed on [www.coingecko.com](http://www.coingecko.com.).
There are multiple onchain endpoints that provide the liquidity data (`reserve_in_usd`) of a pool, for example: [Specific Pool Data by Pool Address](https://docs.coingecko.com/reference/pool-address). You may also get liquidity data (`total_reserve_in_usd`) of a token, using endpoints like: [Token Data by Token Address](https://docs.coingecko.com/reference/token-data-contract-address).
Note: `reserve_in_usd` (pool) represents the total liquidity of all tokens within a specific pool, whereas `total_reserve_in_usd` (token) refers to the total liquidity portion attributable to a specific token across all available pools.
## 22. Get list of onchain DEX pools based on specific criteria
* Use [/pools/megafilter](https://docs.coingecko.com/reference/pools-megafilter) to retrieve data for onchain DEX pools that match a given set of filters.
* Custom filtering: Combine multiple params — like liquidity thresholds, FDV ranges, 24-hour volume, and more — to extract the precise datasets you need.
* Risk and Quality checks: Apply fraud filters to weed out risky projects.
* For more details on examples and available filters, refer to:
* [Trending Search List](https://docs.coingecko.com/reference/trending-search/) — Trending Coins, NFTs, Categories on CoinGecko.com, based on user searches.
* [Trending Search Pools](https://docs.coingecko.com/reference/trending-search-pools/) — Trending Pools and Tokens on GeckoTerminal.com, based on user searches.
* [Top Gainers & Losers](https://docs.coingecko.com/reference/coins-top-gainers-losers) on CoinGecko.com, by specific time duration.
* [Trending Pools List](https://docs.coingecko.com/reference/trending-pools-list) and [Trending Pools by Network](https://docs.coingecko.com/reference/trending-pools-network) on GeckoTerminal.com, by specific time duration.
* By using [Token Info by Token Address](https://docs.coingecko.com/reference/token-info-contract-address) endpoint, you can obtain the following security related data:
* Use [megafilter](https://docs.coingecko.com/reference/pools-megafilter) endpoint to retrieve latest launchpad data, by flagging `sort=pool_created_at_desc`. Learn more on [changelog](https://docs.coingecko.com/changelog#now-supported%3A-launchpad-data-pump-fun-%26-more-%2C-granular-ohlcv%2C-and-honeypot-info).
With WebSocket, you can now stream ultra-low latency, real-time prices, trades, and OHLCV chart data. <br />
Subscribe to our [paid API plan](https://www.coingecko.com/en/api/pricing) (Analyst plan & above) to access WebSocket and REST API data delivery methods.
* Use [/coins/id](https://docs.coingecko.com/reference/coins-id) or [/coins/markets](https://docs.coingecko.com/reference/coins-markets) endpoints by flagging `sparkline = true`.
* If you wish to the obtain the URL slug of a specific CoinGecko Coin Page, e.g. `www.coingecko.com/en/coins/{web_slug}` you may use [/coin/id](https://docs.coingecko.com/reference/coins-id) endpoint and obtain the **`{web_slug}`** value.
* Active: use [/coins/list](https://docs.coingecko.com/reference/coins-list) endpoint, only active coins will be shown by default. You may also flag **`status=inactive`** to get a list of inactive coins.
* Price Stale: use [/simple/price](https://docs.coingecko.com/reference/simple-price) endpoint, flag `include_last_updated_at=true` to check latest update time.
* Current exchange rate: use [/exchange\_rates](https://docs.coingecko.com/reference/exchange-rates) endpoint.
* Historical exchange rate: use [/coins/id/history](https://docs.coingecko.com/reference/coins-id-history) or [/coins/id/market\_chart](https://docs.coingecko.com/reference/coins-id-market-chart) endpoints.
* [/search](https://docs.coingecko.com/reference/search-data) endpoint allows you to search for coins, categories, exchanges (markets), and NFTs listed on CoinGecko.com. You may query by name or symbol.
* [/search-pools](https://docs.coingecko.com/reference/search-pools) endpoint allows you to search for pools listed on GeckoTerminal.com. You may query by pool contract address, token contract address, or token symbol.
## 19. Get List of Blockchain Networks supported on CoinGecko and GeckoTerminal.
CoinGecko and GeckoTerminal support different sets of blockchain networks. You can use the following endpoints to find the list of supported networks and their respective IDs:
You may use the [/asset-platforms-list](https://docs.coingecko.com/reference/asset-platforms-list) endpoint to obtain the native coin ID of all networks (asset platforms) listed on [www.coingecko.com](http://www.coingecko.com.).
There are multiple onchain endpoints that provide the liquidity data (`reserve_in_usd`) of a pool, for example: [Specific Pool Data by Pool Address](https://docs.coingecko.com/reference/pool-address). You may also get liquidity data (`total_reserve_in_usd`) of a token, using endpoints like: [Token Data by Token Address](https://docs.coingecko.com/reference/token-data-contract-address).
Note: `reserve_in_usd` (pool) represents the total liquidity of all tokens within a specific pool, whereas `total_reserve_in_usd` (token) refers to the total liquidity portion attributable to a specific token across all available pools.
## 22. Get list of onchain DEX pools based on specific criteria
* Use [/pools/megafilter](https://docs.coingecko.com/reference/pools-megafilter) to retrieve data for onchain DEX pools that match a given set of filters.
* Custom filtering: Combine multiple params — like liquidity thresholds, FDV ranges, 24-hour volume, and more — to extract the precise datasets you need.
* Risk and Quality checks: Apply fraud filters to weed out risky projects.
* For more details on examples and available filters, refer to:
* [Trending Search List](https://docs.coingecko.com/reference/trending-search/) — Trending Coins, NFTs, Categories on CoinGecko.com, based on user searches.
* [Trending Search Pools](https://docs.coingecko.com/reference/trending-search-pools/) — Trending Pools and Tokens on GeckoTerminal.com, based on user searches.
* [Top Gainers & Losers](https://docs.coingecko.com/reference/coins-top-gainers-losers) on CoinGecko.com, by specific time duration.
* [Trending Pools List](https://docs.coingecko.com/reference/trending-pools-list) and [Trending Pools by Network](https://docs.coingecko.com/reference/trending-pools-network) on GeckoTerminal.com, by specific time duration.
* By using [Token Info by Token Address](https://docs.coingecko.com/reference/token-info-contract-address) endpoint, you can obtain the following security related data:
* Use [megafilter](https://docs.coingecko.com/reference/pools-megafilter) endpoint to retrieve latest launchpad data, by flagging `sort=pool_created_at_desc`. Learn more on [changelog](https://docs.coingecko.com/changelog#now-supported%3A-launchpad-data-pump-fun-%26-more-%2C-granular-ohlcv%2C-and-honeypot-info).
v3.0.1/reference/api-reference/coingecko-demo.json get /coins/{id}/tickers
This endpoint allows you to **query the coin tickers on both centralized exchange (CEX) and decentralized exchange (DEX) based on a particular coin ID**
* You may obtain the coin ID (API ID) via several ways:
* refers to respective coin page and find 'API ID'.
* refers to google sheets [here](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
* You may specify the `exchange_ids` if you want to retrieve tickers for specific exchange only.
* You may include values such as `page` to specify which page of responses you would like to show.
* You may also flag to include more data such as exchange logo and depth.
</Tip>
* The tickers are paginated to 100 items.
* When `dex_pair_format=symbol`, the DEX pair `base` and `target` are displayed in symbol format (e.g. `WETH`, `USDC`) instead of as contract addresses.
* When order is sorted by `volume`, ***converted\_volume*** will be used instead of ***volume***.
* Cache / Update Frequency: every 2 minutes for all the API plans.
reference/api-reference/onchain-pro.json get /pools/megafilter
This endpoint allows you to **query pools based on various filters across all networks on GeckoTerminal**
* Using `checks` param to filter pools based on various checks:
*`checks=no_honeypot` — Filter out Honeypot pools, using GoPlus Token Security and De.Fi Scanner.
*`checks=good_gt_score` — Show only pools with a GT Score of at least 75.
*`checks=on_coingecko` — Show only pools with tokens that are listed on CoinGecko.
*`checks=has_social` — Show only pools with their social links and token information updated.
* You may include values such as `page` to specify which page of responses you would like to show.
</Tip>
* Trending rankings are determined by a combination of factors:
* User engagement on geckoterminal.com
* Market activity, such as trading volume and transactions
* Pool security and credibility, including liquidity and honeypot checks
*`dexes` param can only be used when **only 1`networks`** is specified.
* If the token's market cap is not verified by the team, the API response will return `null` for its market cap value, even though it has a displayed value on GeckoTerminal, which might not be accurate as it often matches the Fully Diluted Valuation (FDV).
* Attributes specified in the `include` param will be returned under the top-level "included" key.
* This endpoint returns up to 20 pools per page. Use the `page` param to navigate more results.
* Setting `include_unknown_honeypot_tokens=true` will include tokens with an 'unknown' honeypot status.
* Please note that this param only takes effect when `checks=no_honeypot` is specified.
* Cache/Update frequency: every 30 seconds.
* 💼 Exclusive for [Paid Plan](https://www.coingecko.com/en/api/pricing) subscribers (Analyst plan or above).
v3.0.1/reference/api-reference/onchain-demo.json get /simple/networks/{network}/token_price/{addresses}
This endpoint allows you to **get token price based on the provided token contract address on a network**
* If the token's market cap is not verified by the team, the API response will return `null` for its market cap value, even though it has a displayed value on GeckoTerminal, which might not be accurate as it often matches the Fully Diluted Valuation (FDV).
* If you require `market_cap_usd` to return FDV value (as seen in [GeckoTerminal.com](https://www.geckoterminal.com/)) when market cap data is unavailable, please specify this parameter `mcap_fdv_fallback=true`.
* The returned price currency is in USD.
* Addresses not found in GeckoTerminal will be ignored.
* This endpoint allows querying **up to 30 contract addresses** per request.
* When using this endpoint, GeckoTerminal's routing decides the best pool for token price. The price source may change based on liquidity and pool activity. For full control over the price, you may use [`/networks/{network}/pools/{address}`](https://docs.coingecko.com/v3.0.1/reference/pool-address) endpoint by providing a specific pool address.
* If you would like to query token information such as socials, websites, description and etc. You can go to this endpoint [`/networks/{network}/tokens/{address}/info`](https://docs.coingecko.com/v3.0.1/reference/token-info-contract-address) instead.
* Addresses not found in GeckoTerminal.com will be ignored.
* This endpoint allows querying **up to 30 contract addresses** per request.
* The endpoint will only return the first top pool for each token.
* If the token's market cap is not verified by the team, the API response will return `null` for its market cap value, even though it has a displayed value on GeckoTerminal, which might not be accurate as it often matches the Fully Diluted Valuation (FDV).
* Market Cap can be verified by and sourced from CoinGecko, and the number may be higher than FDV as it may include Market Cap of tokens issued on other blockchain network.
* Attributes specified in the `include` param will be returned under the top-level "included" key.
* Set `include_composition=true` to surface the balance and liquidity value of the pool's base and quote tokens. (requires `include=top_pools`)
* For tokens on a bonding curve (i.e. non-graduated tokens from launchpads), the response will include a `launchpad_details` object containing their graduation status and details.
v3.0.1/reference/api-reference/onchain-demo.json get /networks/{network}/pools/multi/{addresses}
This endpoint allows you to **query multiple pools based on the provided network and pool address**
* Addresses not found in GeckoTerminal will be ignored.
* If the token's market cap is not verified by the team, the API response will return `null` for its market cap value, even though it has a displayed value on GeckoTerminal, which might not be accurate as it often matches the Fully Diluted Valuation (FDV).
* This endpoint allows querying **up to 30 contract addresses** per request.
* Market Cap can be verified by and sourced from CoinGecko, and the number may be higher than FDV as it may include Market Cap of tokens issued on other blockchain network.
* Attributes specified in the `include ` params will be included under the "included" key at the top level.
*`locked_liquidity_percentage` will be updated on daily basis.
* Set `include_composition=true` to surface the balance and liquidity value of the pool's base and quote tokens.
* Pools on a bonding curve (e.g. non-graduated pools from launchpads) will return `launchpad_details` object with their graduation status and migration details.
* Cache/Update Frequency: every 60 seconds.
</Note>
---
## 👑 Circulating Supply Chart within Time Range by ID
reference/api-reference/onchain-pro.json get /networks/{network}/tokens/{token_address}/trades
This endpoint allows you to **query the last 300 trades in the past 24 hours, across all pools, based on the provided token contract address on a network**
* Exclusive for all [Paid Plan](https://www.coingecko.com/en/api/pricing) Subscribers (Analyst, Lite, Pro and Enterprise).
* Cache/Update Frequency: every 10 seconds for Pro API (Analyst, Lite, Pro, Enterprise).
* For historical chart data with better granularity, you may consider using [/coins/{`id`}/market\_chart](https://docs.coingecko.com/reference/coins-id-market-chart) endpoint.
v3.0.1/reference/api-reference/onchain-demo.json get /networks/{network}/tokens/{address}/info
This endpoint allows you to **query token metadata (name, symbol, CoinGecko ID, image, socials, websites, description, etc.) based on a provided token contract address on a network**
* If you would like to query token data such as decimals, total supply, price and etc. You can go to this endpoint [`/networks/{network}/tokens/{address}`](https://docs.coingecko.com/v3.0.1/reference/token-data-contract-address) instead.
* Learn more about GT score [here](https://support.coingecko.com/hc/en-us/articles/38381394237593-What-is-GT-Score-How-is-GT-Score-calculated).
* Metadata (image, websites, description, socials) may be sourced on-chain and is not vetted by the CoinGecko team. If you wish to get metadata reviewed by CoinGecko team, you may use the following endpoints:
*`holders` data is currently in Beta, with ongoing improvements to data quality, coverage, and update frequency.
* Supported chains include: Solana, EVM (Ethereum, Polygon, BNB, Arbitrum, Optimism, Base), Sui, TON, and Ronin.
*`distribution_percentage` coverage:
* Solana: `top_10`, `11_20`, `21_40`, `rest`
* Other chains: `top_10`, `11_30`, `31_50`, `rest`
* For tokens on a bonding curve (i.e. non-graduated tokens from launchpads), the response will include a `launchpad_details` object containing their graduation status and details.
v3.0.1/reference/api-reference/coingecko-demo.json get /coins/list
This endpoint allows you to **query all the supported coins on CoinGecko with coins ID, name and symbol**
* You may use this endpoint to query the list of coins with coin ID for other endpoints that contain params like `id` or `ids` (coin ID).
</Tip>
* There is no pagination required for this endpoint.
* Access to inactive coins via the Public API (Demo plan) is restricted. To access them, please subscribe to one of our paid plans to obtain a Pro-API key.
* Cache/Update Frequency:
* Every 30 minutes for Public API.
* Every 5 minutes for Pro API (Analyst, Lite, Pro, Enterprise).
</Note>
---
## CGSimplePrice
**URL:** llms-txt#cgsimpleprice
**Contents:**
- Data Payload
- 1. Establish Connection to Websocket
- 2. Subscribe to a specific channel - CGSimplePrice
- 3. Stream CGSimplePrice
- Tips:
- Un-subscribe to stop streaming CGSimplePrice data
| `c` | `channel_type` | string | Indicates the type of channel subscribed to. | C1 |
| `i` | `coin_id` | string | Identifier of the coins. Check full list of IDs [here](https://api.coingecko.com/api/v3/coins/list). | `ethereum`, `usd-coin` |
| `p` | `usd_price` | string | Current token price in USD. | 3639.78228844745 |
| `pp` | `usd_price_24h_change_percentage` | float | Percentage change in token price over the last 24 hours. | 3.566 |
| `t` | `last_updated_at` | integer | Timestamp of the last data update in UNIX time. | 1709542750 |
**Tips**: The Websocket payload will use the value `null` when specific data is unavailable. Ensure your application is capable of handling null values for fields that may not always have data.
## 1. Establish Connection to Websocket
<CodeGroup>
</CodeGroup>
## 2. Subscribe to a specific channel - CGSimplePrice
<CodeGroup>
</CodeGroup>
<CodeGroup>
</CodeGroup>
## 3. Stream CGSimplePrice
<CodeGroup>
</CodeGroup>
<CodeGroup>
</CodeGroup>
<CodeGroup>
</CodeGroup>
The output keys will be in random order.
### Un-subscribe to stop streaming CGSimplePrice data
**Input Example:** Unsubscribe for 1 specific token data:
<CodeGroup>
</CodeGroup>
<CodeGroup>
</CodeGroup>
**Input Example:** Unsubscribe from CGSimplePrice channel and all token data:
<CodeGroup>
</CodeGroup>
<CodeGroup>
</CodeGroup>
**Examples:**
Example 1 (unknown):
```unknown
</CodeGroup>
## 2. Subscribe to a specific channel - CGSimplePrice
v3.0.1/reference/api-reference/onchain-demo.json get /networks/{network}/tokens/{token_address}/pools
This endpoint allows you to **query top pools based on the provided token contract address on a network**
* You may include values such as `page` to specify which page of responses you would like to show.
</Tip>
* The ranking of the top 20 pools is established by evaluating their liquidity and trading activity to identify the most liquid ones. This ranking is determined through a combination of two key factors: liquidity (`reserve_in_usd`) and 24-Hour Trading Volume (`volume_usd`).
* If the token's market cap is not verified by the team, the API response will return `null` for its market cap value, even though it has a displayed value on GeckoTerminal, which might not be accurate as it often matches the Fully Diluted Valuation (FDV).
* Attributes specified in the `include` param will be returned under the top-level "included" key.
* This endpoint returns up to 20 pools per page. Use the `page` param to navigate more results.
*`page`: Pagination beyond 10 pages is available for [Paid Plan](https://www.coingecko.com/en/api/pricing) subscribers (Analyst plan or above).
**How to obtain the pool contract address? (e.g.`WETH/USDC`)**
* Look for the contract address section of pool page on [GeckoTerminal](https://www.geckoterminal.com/eth/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640):
Apart from the pool contract address, you also have the option to query onchain data by using the token contract address, using [/onchain/networks/\{network}/tokens/\{token\_address}/pools](https://docs.coingecko.com/reference/top-pools-contract-address) as example:
v3.0.1/reference/api-reference/coingecko-demo.json get /coins/{id}/market_chart/range
This endpoint allows you to **get the historical chart data of a coin within certain time range in UNIX along with price, market cap and 24hr volume based on particular coin ID**
* You may obtain the coin ID (API ID) via several ways:
* refers to respective coin page and find 'API ID'.
* refers to google sheets [here](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
</Tip>
* You may leave the interval params as empty for automatic granularity:
* 1 day from current time = **5-minutely** data
* 1 day from any time (except current time) = **hourly** data
* 2 - 90 days from any time = **hourly** data
* above 90 days from any time = **daily** data (00:00 UTC)
* Cache / Update Frequency:\
Based on days range (all the API plans)
* 1 day = 30 seconds cache
* 2 -90 days = 30 minutes cache
* 90 days = 12 hours cache
* The last completed UTC day (00:00) is available 35 minutes after midnight on the next UTC day (00:35). The cache will always expire at 00:40 UTC.
* Access to historical data via the Public API (Demo plan) is **restricted to the past 365 days** only. To access the complete range of historical data, please subscribe to one of our [paid plans](https://www.coingecko.com/en/api/pricing) to obtain a Pro-API key.
reference/api-reference/onchain-pro.json get /networks/{network}/tokens/{token_address}/ohlcv/{timeframe}
This endpoint allows you to **get the OHLCV chart (Open, High, Low, Close, Volume) of a token based on the provided token address on a network**
* This endpoint will return OHLCV data of the **most liquid pool** of the specified token. You may use this endpoint [Top Pools by Token Address](https://docs.coingecko.com/update/reference/top-pools-contract-address#/) to check the top pools of a token.
* This endpoint uses epoch/unix format for its timestamp. Example: `1708850449`.
* [Paid plan](https://www.coingecko.com/en/api/pricing) subscribers (Analyst plan & above) can access data from **September 2021 to the present**, depending on when the pool started tracking on GeckoTerminal.
* If no earlier data is available, an empty response will be returned.
* Each API call can only retrieve data for a **maximum range of 6 months**. To fetch older data, use the `before_timestamp` parameter to query in multiple requests.
* Pools with more than 2 tokens are not yet supported for this endpoint.
* Each OHLCV array (under "ohlcv\_list") consists of 6 elements in the following order:
* Timestamp: The epoch/unix timestamp representing the start of the time interval.
* Open: The opening price of the asset at the beginning of the interval.
* High: The highest price reached during the interval.
* Low: The lowest price reached during the interval.
* Close: The price of the asset at the end of the interval.
* Volume: The total trading volume of the asset during the interval.
* **Skipped Intervals**: To ensure concise and relevant data, specific timeframe intervals (e.g. minutely) with no recorded swaps are **excluded** from the response.
* Higher granularity timeframes (e.g. 1 minute) are more likely to skip intervals due to periods of inactivity, while lower granularity timeframes (e.g. daily) are less affected.
* For `include_empty_intervals` param:
* When `false` (default): Only intervals with trade data are returned.
* When `true`: All requested intervals are returned, those with no trade data are populated as follows:
* OHLC (Open, High, Low, Close) are all set to the Close price of the previous interval.
* *O = H = L = C = previous Close*
* Volume (V) is set to 0, reflecting no trade activity.
* Cache/Update Frequency: every 10 seconds for Pro API (Analyst, Lite, Pro, Enterprise).
v3.0.1/reference/api-reference/coingecko-demo.json get /token_lists/{asset_platform_id}/all.json
This endpoint allows you to **get full list of tokens of a blockchain network (asset platform) that is supported by [Ethereum token list standard](https://tokenlists.org/)**
* Cache/Update Frequency: 5 minutes.
* A token will only be included in the list if the contract address is added by CoinGecko team. If you identified any missing token, you may submit a request [here](https://support.coingecko.com/hc/en-us/requests/new).
