# CoinGecko Agent SKILL
Source: https://docs.coingecko.com/ai-integration/agent-skill
Give AI agents built-in knowledge of the CoinGecko API with the installable SKILL package
[CoinGecko SKILL](https://github.com/coingecko/skills) is an installable package that gives AI agents built-in knowledge of the CoinGecko API — endpoints, parameters, and common workflows — so your agent can write accurate queries and code without manual prompting.
Works with Claude Code, Gemini CLI, Codex CLI, and other SKILL-compatible agents. Setup takes under 3 minutes.
## Installation
Install the SKILL for agents like Claude Code, Gemini CLI, or Codex CLI.
### Via [skills.sh](https://skills.sh/)
```bash theme={null}
npm install -g skills
```
> See [npmjs/skills](https://www.npmjs.com/package/skills) for details.
```bash theme={null}
npx skills add coingecko/skills -g -y
```
> `-g` installs globally for all agents.
### Via GitHub
```bash theme={null}
git clone https://github.com/coingecko/skills.git coingecko-skills
```
```bash theme={null}
mv coingecko-skills ~/.claude/skills/coingecko
```
> Path varies by agent and OS. Example above is for Claude Code on Mac/Linux.
Download [skills-main.zip](https://github.com/coingecko/skills/archive/refs/heads/main.zip) from GitHub.
Go to [claude.ai/customize/skills](https://claude.ai/customize/skills) and select **+** → **Upload a skill**.
![]()
Upload the `skills-main.zip` file.
![]()
Done — the SKILL is now active.
![]()
### Claude Web Constraints
The SKILL includes built-in workarounds for Claude platform restrictions. If your API calls fail silently or return network errors, check the following:
#### Allowlist CoinGecko domains
Claude blocks outbound requests to domains not on your allowlist. Go to [claude.ai/settings/capabilities](https://claude.ai/settings/capabilities), scroll to **Domain allowlist**, and add:
* `pro-api.coingecko.com`
* `api.coingecko.com`
![]()
#### Artifacts cannot make API calls directly
* Claude Artifacts run in a sandboxed environment that blocks external API calls.
* The SKILL handles this automatically by fetching data server-side first, then passing results into the Artifact as static data.
For the best experience — especially on the Claude free plan — set up the [CoinGecko MCP Server](/ai-integration/mcp-server) alongside the SKILL.
## Try It Out
Once installed, try asking your agent:
* *"If I invested \$100 in Bitcoin back in December 2018, how much would it be worth today?"*
* *"What was the ATH of XPL?"*
* *"What is the current market cap of DZnQi17HFgSM8mJ4nhVicz32B97XyTsd6MUVuDJgP9Jo from Solana?"*
* *"What are the top NFT collections this week?"*
***
Tell us how you're using the CoinGecko SKILL and what we should improve.
# Google Antigravity
Source: https://docs.coingecko.com/ai-integration/antigravity
Connect CoinGecko to Antigravity — MCP server, SKILL, and SDK prompts in one place
[Antigravity](https://antigravity.google/) is Google's agent-first development platform — desktop app, CLI, and SDK for multi-agent orchestration. The integrations below are complementary — use any combination.
**Migrating from Gemini CLI?** Antigravity CLI is its direct successor.
The setup below works for both the desktop app and CLI.
## Setup
Gives Antigravity built-in knowledge of the CoinGecko API — writes correct requests without manual prompting.
Clone into Antigravity's skills directory:
```bash Project-level theme={null}
git clone https://github.com/coingecko/skills.git .agent/skills/coingecko
```
```bash Global theme={null}
git clone https://github.com/coingecko/skills.git ~/.gemini/antigravity/skills/coingecko
```
Antigravity loads the skill automatically when it detects a CoinGecko-related task.
> Full details: [Agent SKILL](/ai-integration/agent-skill)
Connects Antigravity to live CoinGecko data — prices, market caps, onchain pools, OHLCV, NFTs, and more.
Open **⋯ → MCP Servers → Manage MCP Servers → View raw config** to edit `~/.gemini/antigravity/mcp_config.json`:
![]()
Add the CoinGecko MCP:
```json Free (Keyless) theme={null}
"coingecko": {
"serverUrl": "https://mcp.api.coingecko.com/mcp",
"disabled": false
}
```
```json Use your API key theme={null}
"coingecko": {
"serverUrl": "https://mcp.pro-api.coingecko.com/mcp",
"disabled": false
}
```
Save and reload the MCP panel.
> Full details: [CoinGecko MCP](/ai-integration/mcp-server)
Lets Antigravity search CoinGecko documentation directly — endpoint references, guides, and tutorials.
Add to the same config:
```json theme={null}
"coingecko-docs": {
"serverUrl": "https://docs.coingecko.com/mcp",
"disabled": false
}
```
> Full details: [Docs MCP](/ai-integration/docs-mcp)
## SDK Prompts
Copy the prompt into one of Antigravity's rules files:
| File | Scope |
| --------------------------- | ----------------------------------------------------------- |
| `AGENTS.md` in project root | Project-level — also read by Cursor, Claude Code, and Codex |
| `~/.gemini/AGENTS.md` | Global — all projects |
| `GEMINI.md` in project root | Antigravity-only, takes precedence over `AGENTS.md` |
# CoinGecko Python SDK — AI Prompt Rules
## Install
```
pip install coingecko_sdk
```
## Client Setup
```python theme={null}
import os
from coingecko_sdk import Coingecko
client = Coingecko(
pro_api_key=os.environ.get("YOUR_API_KEY"),
environment="pro", # or "demo" with demo_api_key
max_retries=2,
)
```
* Load API keys from environment variables. Never hardcode.
* Initialize one reusable client instance.
* For async: use `AsyncCoingecko` with `await`.
## Finding Methods
Methods map to endpoint paths using snake\_case, but names are **not always predictable**
— path parameters like `{address}` may become part of the method name
(e.g. `get_address()`, `get_addresses()`, `get_network()`).
**Before using any SDK method, you MUST verify the exact method name.** Do not guess.
1. **Check the reference page first** — every endpoint page includes an SDK Examples section
at the bottom with copy-ready code:
* URL pattern: `https://docs.coingecko.com/reference/{operationId}.md`
* Look for the `#### SDK Examples` block and use the Python snippet exactly as shown.
2. **Full method list** — if you need to search across all methods:
`https://docs.coingecko.com/docs/sdk-python-methods.md`
3. **Parameter details and endpoint caveats**:
`https://docs.coingecko.com/reference/{operationId}.md`
## Error Handling
Catch specific SDK exceptions — never use bare `except Exception`.
```python theme={null}
import coingecko_sdk
try:
response = client.simple.price.get(vs_currencies="usd", ids="bitcoin")
except coingecko_sdk.RateLimitError:
# Back off — 429 received
pass
except coingecko_sdk.NotFoundError:
# Invalid coin ID or endpoint
pass
except coingecko_sdk.APIError as e:
print(e.status_code, e.response)
```
## Rules
* ALWAYS use `coingecko_sdk`. Never use `pycoingecko` or raw `requests`/`httpx`.
* Rely on the SDK's built-in retry (`max_retries`). Never write manual retry loops.
* Responses are Pydantic models — use `.to_dict()` or `.to_json()` when needed.
* Use `client.with_options()` for per-request overrides (timeout, retries).
# CoinGecko TypeScript SDK — AI Prompt Rules
## Install
```
npm install @coingecko/coingecko-typescript
```
## Client Setup
```typescript theme={null}
import Coingecko from '@coingecko/coingecko-typescript';
const client = new Coingecko({
proAPIKey: process.env['YOUR_API_KEY'],
environment: 'pro', // or 'demo' with demoAPIKey
maxRetries: 2,
});
```
* Load API keys from environment variables. Never hardcode.
* Initialize one reusable client instance.
## Finding Methods
Methods map to endpoint paths using camelCase, but names are **not always predictable**
— path parameters like `{address}` may become part of the method name
(e.g. `getAddress()`, `getAddresses()`, `getNetwork()`, `getID()`).
**Before using any SDK method, you MUST verify the exact method name.** Do not guess.
1. **Check the reference page first** — every endpoint page includes an SDK Examples section
at the bottom with copy-ready code:
* URL pattern: `https://docs.coingecko.com/reference/{operationId}.md`
* Look for the `#### SDK Examples` block and use the TypeScript snippet exactly as shown.
2. **Full method list** — if you need to search across all methods:
`https://docs.coingecko.com/docs/sdk-typescript-methods.md`
3. **Parameter details and endpoint caveats**:
`https://docs.coingecko.com/reference/{operationId}.md`
## Error Handling
Catch specific SDK exceptions — never use bare `catch (e)` without checking the type.
```typescript theme={null}
import Coingecko from '@coingecko/coingecko-typescript';
try {
const response = await client.simple.price.get({ vs_currencies: 'usd', ids: 'bitcoin' });
} catch (err) {
if (err instanceof Coingecko.RateLimitError) {
// Back off — 429 received
} else if (err instanceof Coingecko.NotFoundError) {
// Invalid coin ID or endpoint
} else if (err instanceof Coingecko.APIError) {
console.log(err.status, err.headers);
} else {
throw err;
}
}
```
## Rules
* ALWAYS use `@coingecko/coingecko-typescript`. Never use raw `fetch`/`axios`/`node-fetch`.
* Rely on the SDK's built-in retry (`maxRetries`). Never write manual retry loops.
* Use SDK types for params and responses: `Coingecko.Simple.PriceGetParams`, `Coingecko.Simple.PriceGetResponse`.
* Use the second argument for per-request overrides: `client.simple.price.get(params, { maxRetries: 5 })`.
## Try It Out
Once everything's wired up, try asking Antigravity:
* *"Using the CoinGecko MCP, show me the top 10 trending pools on Base and export them to CSV."*
* *"Write a Python script using coingecko-sdk that tracks my portfolio and alerts if any coin moves more than 10% in an hour."*
Use Antigravity's **Manager view** to run agents in parallel — spawn one agent per chain to compare onchain activity across Base, Solana, and Ethereum simultaneously.
# Claude Code
Source: https://docs.coingecko.com/ai-integration/claude-code
Wire CoinGecko into Anthropic's terminal coding agent — MCP, SKILL, and SDK prompts in one place
[Claude Code](https://www.anthropic.com/claude-code) is Anthropic's terminal-native coding agent. The integrations below are complementary — use any combination.
## Setup
Gives Claude Code built-in knowledge of the CoinGecko API — writes correct requests without manual prompting.
```bash theme={null}
npx skills add coingecko/skills -g -y
```
> Full details: [Agent SKILL](/ai-integration/agent-skill)
Connects Claude Code to live CoinGecko data — prices, market caps, onchain pools, OHLCV, NFTs, and more.
```bash Free (Keyless) theme={null}
claude mcp add --transport http \
coingecko https://mcp.api.coingecko.com/mcp
```
```bash Use your API key theme={null}
claude mcp add --transport http \
coingecko https://mcp.pro-api.coingecko.com/mcp
```
If **using your API key**, run `/mcp` inside a Claude Code session to authenticate:
```bash Example Session theme={null}
❯ /mcp
Manage MCP servers
1 server
❯ coingecko · △ needs authentication
↑↓ to navigate · Enter to confirm · Esc to cancel
```
> Full details: [CoinGecko MCP](/ai-integration/mcp-server)
Lets Claude Code search CoinGecko documentation directly — endpoint references, guides, and tutorials.
```bash theme={null}
claude mcp add --transport http \
coingecko-docs https://docs.coingecko.com/mcp
```
> Full details: [Docs MCP](/ai-integration/docs-mcp)
```bash theme={null}
claude mcp list
```
## SDK Prompts
Copy these prompts into your `CLAUDE.md` or paste at the start of a conversation to ensure Claude Code generates correct SDK code.
# CoinGecko Python SDK — AI Prompt Rules
## Install
```
pip install coingecko_sdk
```
## Client Setup
```python theme={null}
import os
from coingecko_sdk import Coingecko
client = Coingecko(
pro_api_key=os.environ.get("YOUR_API_KEY"),
environment="pro", # or "demo" with demo_api_key
max_retries=2,
)
```
* Load API keys from environment variables. Never hardcode.
* Initialize one reusable client instance.
* For async: use `AsyncCoingecko` with `await`.
## Finding Methods
Methods map to endpoint paths using snake\_case, but names are **not always predictable**
— path parameters like `{address}` may become part of the method name
(e.g. `get_address()`, `get_addresses()`, `get_network()`).
**Before using any SDK method, you MUST verify the exact method name.** Do not guess.
1. **Check the reference page first** — every endpoint page includes an SDK Examples section
at the bottom with copy-ready code:
* URL pattern: `https://docs.coingecko.com/reference/{operationId}.md`
* Look for the `#### SDK Examples` block and use the Python snippet exactly as shown.
2. **Full method list** — if you need to search across all methods:
`https://docs.coingecko.com/docs/sdk-python-methods.md`
3. **Parameter details and endpoint caveats**:
`https://docs.coingecko.com/reference/{operationId}.md`
## Error Handling
Catch specific SDK exceptions — never use bare `except Exception`.
```python theme={null}
import coingecko_sdk
try:
response = client.simple.price.get(vs_currencies="usd", ids="bitcoin")
except coingecko_sdk.RateLimitError:
# Back off — 429 received
pass
except coingecko_sdk.NotFoundError:
# Invalid coin ID or endpoint
pass
except coingecko_sdk.APIError as e:
print(e.status_code, e.response)
```
## Rules
* ALWAYS use `coingecko_sdk`. Never use `pycoingecko` or raw `requests`/`httpx`.
* Rely on the SDK's built-in retry (`max_retries`). Never write manual retry loops.
* Responses are Pydantic models — use `.to_dict()` or `.to_json()` when needed.
* Use `client.with_options()` for per-request overrides (timeout, retries).
# CoinGecko TypeScript SDK — AI Prompt Rules
## Install
```
npm install @coingecko/coingecko-typescript
```
## Client Setup
```typescript theme={null}
import Coingecko from '@coingecko/coingecko-typescript';
const client = new Coingecko({
proAPIKey: process.env['YOUR_API_KEY'],
environment: 'pro', // or 'demo' with demoAPIKey
maxRetries: 2,
});
```
* Load API keys from environment variables. Never hardcode.
* Initialize one reusable client instance.
## Finding Methods
Methods map to endpoint paths using camelCase, but names are **not always predictable**
— path parameters like `{address}` may become part of the method name
(e.g. `getAddress()`, `getAddresses()`, `getNetwork()`, `getID()`).
**Before using any SDK method, you MUST verify the exact method name.** Do not guess.
1. **Check the reference page first** — every endpoint page includes an SDK Examples section
at the bottom with copy-ready code:
* URL pattern: `https://docs.coingecko.com/reference/{operationId}.md`
* Look for the `#### SDK Examples` block and use the TypeScript snippet exactly as shown.
2. **Full method list** — if you need to search across all methods:
`https://docs.coingecko.com/docs/sdk-typescript-methods.md`
3. **Parameter details and endpoint caveats**:
`https://docs.coingecko.com/reference/{operationId}.md`
## Error Handling
Catch specific SDK exceptions — never use bare `catch (e)` without checking the type.
```typescript theme={null}
import Coingecko from '@coingecko/coingecko-typescript';
try {
const response = await client.simple.price.get({ vs_currencies: 'usd', ids: 'bitcoin' });
} catch (err) {
if (err instanceof Coingecko.RateLimitError) {
// Back off — 429 received
} else if (err instanceof Coingecko.NotFoundError) {
// Invalid coin ID or endpoint
} else if (err instanceof Coingecko.APIError) {
console.log(err.status, err.headers);
} else {
throw err;
}
}
```
## Rules
* ALWAYS use `@coingecko/coingecko-typescript`. Never use raw `fetch`/`axios`/`node-fetch`.
* Rely on the SDK's built-in retry (`maxRetries`). Never write manual retry loops.
* Use SDK types for params and responses: `Coingecko.Simple.PriceGetParams`, `Coingecko.Simple.PriceGetResponse`.
* Use the second argument for per-request overrides: `client.simple.price.get(params, { maxRetries: 5 })`.
## Try It Out
Once everything's wired up, try asking Claude Code:
* *"Using the CoinGecko MCP, show me the top 10 trending pools on Base and export them to CSV."*
* *"What parameters does `/coins/markets` accept? Write a Python function that fetches the top 100 coins by market cap."*
* *"Write a TypeScript script that tracks my portfolio and alerts if any coin moves more than 10% in an hour."*
# CoinGecko CLI
Source: https://docs.coingecko.com/ai-integration/cli
A high-performance terminal interface for real-time and historical crypto data
![]()
A fast, full-featured terminal interface for developers, analysts, and AI agents. Interactive dashboards, CSV exports, WebSocket streaming, and machine-readable JSON output — all from the command line.
[GitHub →](https://github.com/coingecko/coingecko-cli) | [Commands Reference →](https://github.com/coingecko/coingecko-cli#commands)
Full-screen terminal dashboard with live navigation and 7-day braille price charts.
Export market rankings and historical data directly to CSV or JSON for pipelines and analysis.
Real-time price updates via `cg watch` with NDJSON output for piping.
`--dry-run` mode and `cg commands` for tool discovery and LLM integration.
## Get Started
```bash Homebrew theme={null}
brew install coingecko/coingecko-cli/cg
```
```bash npm theme={null}
npm install -g @coingecko/cg
```
```bash Bash wrap theme={null}
curl -sSfL https://raw.githubusercontent.com/coingecko/coingecko-cli/main/install.sh | sh
```
```bash Go theme={null}
go install github.com/coingecko/coingecko-cli@latest
```
> Or download a binary from [GitHub Releases](https://github.com/coingecko/coingecko-cli/releases).
Get a [Demo (free) or Pro (paid) API key](https://www.coingecko.com/en/api/pricing), then run:
```bash theme={null}
cg auth
```
Or pass credentials directly:
```bash Demo (Free) theme={null}
cg auth --key YOUR_API_KEY --tier demo
```
```bash Pro (Paid) theme={null}
cg auth --key YOUR_API_KEY --tier paid
```
Verify with `cg status`.
```bash theme={null}
cg price --ids bitcoin,ethereum
cg markets --total 100
cg history bitcoin --days 7
cg tui markets
```
> See the full [Commands Reference](https://github.com/coingecko/coingecko-cli#commands) for all available commands.
## Use Cases
* **CI/CD alerts** — integrate into GitHub Actions or cron jobs, monitor price thresholds with `-o json` and `jq`
* **Dataset generation** — fetch and export top 1000 coins to CSV in seconds
* **Debugging** — use `--dry-run` to preview exact API parameters and URLs before production code
* **Shell integration** — embed in your terminal prompt for live metrics
* **Function calling** — give your LLM the `cg` binary as a tool, resolve symbols via `cg search`, and analyze results
* **Market research** — identify hot sectors with `cg trending`, drill into performers with `--category`
* **Context injection** — feed fresh `-o json` data to ensure reasoning uses real-time market conditions
* **Self-documentation** — `cg commands` lets agents discover available sub-commands
* **Historical snapshots** — generate CSV reports for specific dates or ranges for Excel or Python
* **Movers analysis** — track biggest gainers/losers across timeframes
* **Category benchmarking** — export sector data (Layer-2, RWA, etc.) for cross-category comparison
***
Tell us how you're using the CLI and what we should improve.
Report bugs, request features, or contribute on GitHub.
# Cursor
Source: https://docs.coingecko.com/ai-integration/cursor
Connect CoinGecko to Cursor — MCP server and SDK prompts in one place
[Cursor](https://cursor.com) is an AI-first code editor with built-in chat and agent mode. The integrations below are complementary — use any combination.
## Setup
Connects Cursor to live CoinGecko data — prices, market caps, onchain pools, OHLCV, NFTs, and more.
Open **Settings → MCP → Add new MCP server**, or edit `~/.cursor/mcp.json` directly:
```json Free (Keyless) theme={null}
{
"mcpServers": {
"coingecko": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.api.coingecko.com/mcp"
]
}
}
}
```
```json Use your API key theme={null}
{
"mcpServers": {
"coingecko": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.pro-api.coingecko.com/mcp"
]
}
}
}
```
Restart Cursor after saving. `coingecko` appears under **Available Tools** in the chat sidebar.
> Full details: [CoinGecko MCP](/ai-integration/mcp-server)
Lets Cursor search CoinGecko documentation directly — endpoint references, guides, and tutorials.
Add to the same `mcp.json`:
```json theme={null}
{
"mcpServers": {
"coingecko-docs": {
"command": "npx",
"args": [
"mcp-remote",
"https://docs.coingecko.com/mcp"
]
}
}
}
```
> Full details: [Docs MCP](/ai-integration/docs-mcp)
## SDK Prompts
Copy the prompt into `.cursor/rules/coingecko-sdk.mdc` so every generation follows the right SDK patterns.
Set `alwaysApply: true` in the rule file frontmatter so it's loaded on every request.
# CoinGecko Python SDK — AI Prompt Rules
## Install
```
pip install coingecko_sdk
```
## Client Setup
```python theme={null}
import os
from coingecko_sdk import Coingecko
client = Coingecko(
pro_api_key=os.environ.get("YOUR_API_KEY"),
environment="pro", # or "demo" with demo_api_key
max_retries=2,
)
```
* Load API keys from environment variables. Never hardcode.
* Initialize one reusable client instance.
* For async: use `AsyncCoingecko` with `await`.
## Finding Methods
Methods map to endpoint paths using snake\_case, but names are **not always predictable**
— path parameters like `{address}` may become part of the method name
(e.g. `get_address()`, `get_addresses()`, `get_network()`).
**Before using any SDK method, you MUST verify the exact method name.** Do not guess.
1. **Check the reference page first** — every endpoint page includes an SDK Examples section
at the bottom with copy-ready code:
* URL pattern: `https://docs.coingecko.com/reference/{operationId}.md`
* Look for the `#### SDK Examples` block and use the Python snippet exactly as shown.
2. **Full method list** — if you need to search across all methods:
`https://docs.coingecko.com/docs/sdk-python-methods.md`
3. **Parameter details and endpoint caveats**:
`https://docs.coingecko.com/reference/{operationId}.md`
## Error Handling
Catch specific SDK exceptions — never use bare `except Exception`.
```python theme={null}
import coingecko_sdk
try:
response = client.simple.price.get(vs_currencies="usd", ids="bitcoin")
except coingecko_sdk.RateLimitError:
# Back off — 429 received
pass
except coingecko_sdk.NotFoundError:
# Invalid coin ID or endpoint
pass
except coingecko_sdk.APIError as e:
print(e.status_code, e.response)
```
## Rules
* ALWAYS use `coingecko_sdk`. Never use `pycoingecko` or raw `requests`/`httpx`.
* Rely on the SDK's built-in retry (`max_retries`). Never write manual retry loops.
* Responses are Pydantic models — use `.to_dict()` or `.to_json()` when needed.
* Use `client.with_options()` for per-request overrides (timeout, retries).
# CoinGecko TypeScript SDK — AI Prompt Rules
## Install
```
npm install @coingecko/coingecko-typescript
```
## Client Setup
```typescript theme={null}
import Coingecko from '@coingecko/coingecko-typescript';
const client = new Coingecko({
proAPIKey: process.env['YOUR_API_KEY'],
environment: 'pro', // or 'demo' with demoAPIKey
maxRetries: 2,
});
```
* Load API keys from environment variables. Never hardcode.
* Initialize one reusable client instance.
## Finding Methods
Methods map to endpoint paths using camelCase, but names are **not always predictable**
— path parameters like `{address}` may become part of the method name
(e.g. `getAddress()`, `getAddresses()`, `getNetwork()`, `getID()`).
**Before using any SDK method, you MUST verify the exact method name.** Do not guess.
1. **Check the reference page first** — every endpoint page includes an SDK Examples section
at the bottom with copy-ready code:
* URL pattern: `https://docs.coingecko.com/reference/{operationId}.md`
* Look for the `#### SDK Examples` block and use the TypeScript snippet exactly as shown.
2. **Full method list** — if you need to search across all methods:
`https://docs.coingecko.com/docs/sdk-typescript-methods.md`
3. **Parameter details and endpoint caveats**:
`https://docs.coingecko.com/reference/{operationId}.md`
## Error Handling
Catch specific SDK exceptions — never use bare `catch (e)` without checking the type.
```typescript theme={null}
import Coingecko from '@coingecko/coingecko-typescript';
try {
const response = await client.simple.price.get({ vs_currencies: 'usd', ids: 'bitcoin' });
} catch (err) {
if (err instanceof Coingecko.RateLimitError) {
// Back off — 429 received
} else if (err instanceof Coingecko.NotFoundError) {
// Invalid coin ID or endpoint
} else if (err instanceof Coingecko.APIError) {
console.log(err.status, err.headers);
} else {
throw err;
}
}
```
## Rules
* ALWAYS use `@coingecko/coingecko-typescript`. Never use raw `fetch`/`axios`/`node-fetch`.
* Rely on the SDK's built-in retry (`maxRetries`). Never write manual retry loops.
* Use SDK types for params and responses: `Coingecko.Simple.PriceGetParams`, `Coingecko.Simple.PriceGetResponse`.
* Use the second argument for per-request overrides: `client.simple.price.get(params, { maxRetries: 5 })`.
## Try It Out
Try prompting Cursor's agent mode with:
* *"Using the CoinGecko MCP tool, fetch the current BTC and ETH prices and build a React widget that displays them."*
* *"Write a TypeScript script that pulls the top 50 coins by market cap and exports them to a CSV."*
# CoinGecko Docs MCP
Source: https://docs.coingecko.com/ai-integration/docs-mcp
Let AI agents search CoinGecko documentation via the Docs MCP Server
Give your AI agent direct access to CoinGecko's documentation — endpoint references, guides, tutorials, and more — without leaving the conversation.
```
https://docs.coingecko.com/mcp
```
This server searches the **documentation**.
To query live crypto data (prices, markets, onchain), use [CoinGecko API MCP ->](/ai-integration/mcp-server)
## Setup
Go to [Settings > Connectors](https://claude.ai/customize/connectors?modal=add-custom-connector) on claude.ai.
![]()
* **Name:** `CoinGecko Docs`
* **Remote MCP server URL:** `https://docs.coingecko.com/mcp`
Click **Add**.
Edit `claude_desktop_config.json` ([find this file](https://modelcontextprotocol.io/docs/develop/connect-local-servers)).
```json theme={null}
{
"mcpServers": {
"coingecko-docs": {
"command": "npx",
"args": [
"mcp-remote",
"https://docs.coingecko.com/mcp"
]
}
}
}
```
Requires [Node.js](https://nodejs.org/en/download).
Restart to load the new server.
```bash theme={null}
claude mcp add --transport http \
coingecko-docs https://docs.coingecko.com/mcp
```
```bash theme={null}
claude mcp list
```
## What can it do?
Once connected, your AI agent can search the CoinGecko documentation directly. For example:
* "How do I authenticate with the CoinGecko API?"
* "What parameters does the `/coins/markets` endpoint accept?"
* "Show me the WebSocket subscription format"
Need real-time prices, market data, or onchain analytics? Use the CoinGecko API MCP Server.
# AI Integration
Source: https://docs.coingecko.com/ai-integration/index
Connect AI agents and coding assistants to CoinGecko — MCP servers, SDK prompts, CLI, and per-platform setup guides
![]()
Give your AI agents and coding assistants direct access to real-time crypto data, onchain analytics, and the full CoinGecko API — through MCP servers, SDK prompts, and one-command setup for every major platform.
## Core Tools
Connect AI agents to live crypto data via the CoinGecko MCP Server.
Let AI agents search CoinGecko documentation directly.
Give AI agents built-in knowledge of the CoinGecko API.
Terminal interface for real-time and historical crypto data.
Pay-per-use crypto data with native stablecoin payments.
## Coding Agents
Per-platform setup guides — MCP, SKILL, and SDK prompts in one place.
Anthropic
OpenAI
Cursor
AWS
Google
## Platforms
Wire CoinGecko MCP, SKILL, and CLI into OpenClaw agents.
Connect Notion AI Agents to live CoinGecko data via MCP.
# AWS Kiro
Source: https://docs.coingecko.com/ai-integration/kiro
Connect CoinGecko to Kiro — MCP server, SKILL, and steering rules in one place
[Kiro](https://kiro.dev/) is an IDE and coding agent from AWS. The integrations below are complementary — use any combination.
## Setup
Gives Kiro built-in knowledge of the CoinGecko API — writes correct requests without manual prompting.
Clone the repo into your working directory:
```bash theme={null}
git clone https://github.com/coingecko/skills.git
```
Then add the skill in Kiro by pointing to the cloned file path:
![]()
![]()
> Full details: [Agent SKILL](/ai-integration/agent-skill)
Connects Kiro to live CoinGecko data — prices, market caps, onchain pools, OHLCV, NFTs, and more.
Open the MCP settings in Kiro:
![]()
Add the CoinGecko MCP to your config:
```json Free (Keyless) theme={null}
"coingecko": {
"url": "https://mcp.api.coingecko.com/mcp",
"disabled": false
}
```
```json Use your API key theme={null}
"coingecko": {
"url": "https://mcp.pro-api.coingecko.com/mcp",
"disabled": false
}
```
> Full details: [CoinGecko MCP](/ai-integration/mcp-server)
Lets Kiro search CoinGecko documentation directly — endpoint references, guides, and tutorials.
Add to the same MCP config:
```json theme={null}
"coingecko-docs": {
"url": "https://docs.coingecko.com/mcp",
"disabled": false
}
```
> Full details: [Docs MCP](/ai-integration/docs-mcp)
## SDK Prompts (Steering)
Copy the prompt into a Kiro steering file so every generation follows the right SDK patterns.
![]()
![]()
# CoinGecko Python SDK — AI Prompt Rules
## Install
```
pip install coingecko_sdk
```
## Client Setup
```python theme={null}
import os
from coingecko_sdk import Coingecko
client = Coingecko(
pro_api_key=os.environ.get("YOUR_API_KEY"),
environment="pro", # or "demo" with demo_api_key
max_retries=2,
)
```
* Load API keys from environment variables. Never hardcode.
* Initialize one reusable client instance.
* For async: use `AsyncCoingecko` with `await`.
## Finding Methods
Methods map to endpoint paths using snake\_case, but names are **not always predictable**
— path parameters like `{address}` may become part of the method name
(e.g. `get_address()`, `get_addresses()`, `get_network()`).
**Before using any SDK method, you MUST verify the exact method name.** Do not guess.
1. **Check the reference page first** — every endpoint page includes an SDK Examples section
at the bottom with copy-ready code:
* URL pattern: `https://docs.coingecko.com/reference/{operationId}.md`
* Look for the `#### SDK Examples` block and use the Python snippet exactly as shown.
2. **Full method list** — if you need to search across all methods:
`https://docs.coingecko.com/docs/sdk-python-methods.md`
3. **Parameter details and endpoint caveats**:
`https://docs.coingecko.com/reference/{operationId}.md`
## Error Handling
Catch specific SDK exceptions — never use bare `except Exception`.
```python theme={null}
import coingecko_sdk
try:
response = client.simple.price.get(vs_currencies="usd", ids="bitcoin")
except coingecko_sdk.RateLimitError:
# Back off — 429 received
pass
except coingecko_sdk.NotFoundError:
# Invalid coin ID or endpoint
pass
except coingecko_sdk.APIError as e:
print(e.status_code, e.response)
```
## Rules
* ALWAYS use `coingecko_sdk`. Never use `pycoingecko` or raw `requests`/`httpx`.
* Rely on the SDK's built-in retry (`max_retries`). Never write manual retry loops.
* Responses are Pydantic models — use `.to_dict()` or `.to_json()` when needed.
* Use `client.with_options()` for per-request overrides (timeout, retries).
# CoinGecko TypeScript SDK — AI Prompt Rules
## Install
```
npm install @coingecko/coingecko-typescript
```
## Client Setup
```typescript theme={null}
import Coingecko from '@coingecko/coingecko-typescript';
const client = new Coingecko({
proAPIKey: process.env['YOUR_API_KEY'],
environment: 'pro', // or 'demo' with demoAPIKey
maxRetries: 2,
});
```
* Load API keys from environment variables. Never hardcode.
* Initialize one reusable client instance.
## Finding Methods
Methods map to endpoint paths using camelCase, but names are **not always predictable**
— path parameters like `{address}` may become part of the method name
(e.g. `getAddress()`, `getAddresses()`, `getNetwork()`, `getID()`).
**Before using any SDK method, you MUST verify the exact method name.** Do not guess.
1. **Check the reference page first** — every endpoint page includes an SDK Examples section
at the bottom with copy-ready code:
* URL pattern: `https://docs.coingecko.com/reference/{operationId}.md`
* Look for the `#### SDK Examples` block and use the TypeScript snippet exactly as shown.
2. **Full method list** — if you need to search across all methods:
`https://docs.coingecko.com/docs/sdk-typescript-methods.md`
3. **Parameter details and endpoint caveats**:
`https://docs.coingecko.com/reference/{operationId}.md`
## Error Handling
Catch specific SDK exceptions — never use bare `catch (e)` without checking the type.
```typescript theme={null}
import Coingecko from '@coingecko/coingecko-typescript';
try {
const response = await client.simple.price.get({ vs_currencies: 'usd', ids: 'bitcoin' });
} catch (err) {
if (err instanceof Coingecko.RateLimitError) {
// Back off — 429 received
} else if (err instanceof Coingecko.NotFoundError) {
// Invalid coin ID or endpoint
} else if (err instanceof Coingecko.APIError) {
console.log(err.status, err.headers);
} else {
throw err;
}
}
```
## Rules
* ALWAYS use `@coingecko/coingecko-typescript`. Never use raw `fetch`/`axios`/`node-fetch`.
* Rely on the SDK's built-in retry (`maxRetries`). Never write manual retry loops.
* Use SDK types for params and responses: `Coingecko.Simple.PriceGetParams`, `Coingecko.Simple.PriceGetResponse`.
* Use the second argument for per-request overrides: `client.simple.price.get(params, { maxRetries: 5 })`.
## Try It Out
Once everything's wired up, try asking Kiro:
* *"Using the CoinGecko MCP, show me the top 10 trending pools on Base and export them to CSV."*
* *"Write a Python script using coingecko-sdk that tracks my portfolio and alerts if any coin moves more than 10% in an hour."*
# CoinGecko MCP
Source: https://docs.coingecko.com/ai-integration/mcp-server
Connect AI agents to real-time crypto data via the CoinGecko MCP Server
![]()
Live and historical prices, market caps, and trading volumes.
Exchange data, trending coins, and market analytics.
Token and pool data across DEXes and networks.
## Servers
| Server | Endpoint | Details |
| ------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Free (Keyless)** | `https://mcp.api.coingecko.com/mcp` | No API key needed.
Shared rate limits. |
| **Use your API key** | `https://mcp.pro-api.coingecko.com/mcp` | [CoinGecko API key](https://www.coingecko.com/en/api/pricing) required.
Higher limits, full tool set. |
| **[Local](#setup-your-local-server)** | [`@coingecko/coingecko-mcp`](https://www.npmjs.com/package/@coingecko/coingecko-mcp) | Pro or Demo API key.
Runs on your machine. [GitHub →](https://github.com/coingecko/coingecko-typescript/tree/main/packages/mcp-server) |
* Both servers support `/mcp` (Streamable HTTP) and `/sse` (Server-Sent Events).
* Always prefer `/mcp` — only fall back to `/sse` if your client doesn't support Streamable HTTP.
> See the full list of [available tools and methods](/ai-integration/mcp-tools).
## Connect to Remote Server
Go to [Settings > Connectors](https://claude.ai/customize/connectors?modal=add-custom-connector) on claude.ai.
![]()
* **Name:** `CoinGecko`
* **Remote MCP server URL:**
| Server | URL |
| -------------------- | --------------------------------------- |
| **Free (Keyless)** | `https://mcp.api.coingecko.com/mcp` |
| **Use your API key** | `https://mcp.pro-api.coingecko.com/mcp` |
Click **Add**.
Using your API key opens a browser tab to enter it on first connection.
[Get an API key →](https://www.coingecko.com/en/api/pricing)
Edit `claude_desktop_config.json` ([find this file](https://modelcontextprotocol.io/docs/develop/connect-local-servers)).
```json Free (Keyless) theme={null}
{
"mcpServers": {
"coingecko": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.api.coingecko.com/mcp"
]
}
}
}
```
```json Use your API key theme={null}
{
"mcpServers": {
"coingecko": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.pro-api.coingecko.com/mcp"
]
}
}
}
```
Requires [Node.js](https://nodejs.org/en/download).
Using your API key opens a browser tab to enter it on first connection.
[Get an API key →](https://www.coingecko.com/en/api/pricing)
Restart to load the new server.
```bash Free (Keyless) theme={null}
claude mcp add --transport http \
coingecko https://mcp.api.coingecko.com/mcp
```
```bash Use your API key theme={null}
claude mcp add --transport http \
coingecko https://mcp.pro-api.coingecko.com/mcp
```
If **using your API key**, run `/mcp` inside a Claude Code session to authenticate:
```bash Example Session theme={null}
❯ /mcp
Manage MCP servers
1 server
❯ coingecko · △ needs authentication
↑↓ to navigate · Enter to confirm · Esc to cancel
```
```bash theme={null}
claude mcp list
```
## Setup your Local Server
Run the server on your machine using [`@coingecko/coingecko-mcp`](https://www.npmjs.com/package/@coingecko/coingecko-mcp). Requires [Node.js](https://nodejs.org/en/download).
Edit `claude_desktop_config.json` ([find this file](https://modelcontextprotocol.io/docs/develop/connect-local-servers)).
```json Pro API Key theme={null}
{
"mcpServers": {
"coingecko": {
"command": "npx",
"args": [
"-y",
"@coingecko/coingecko-mcp"
],
"env": {
"COINGECKO_PRO_API_KEY": "YOUR_API_KEY",
"COINGECKO_ENVIRONMENT": "pro"
}
}
}
}
```
```json Demo API Key theme={null}
{
"mcpServers": {
"coingecko": {
"command": "npx",
"args": [
"-y",
"@coingecko/coingecko-mcp"
],
"env": {
"COINGECKO_DEMO_API_KEY": "YOUR_API_KEY",
"COINGECKO_ENVIRONMENT": "demo"
}
}
}
}
```
> Replace `YOUR_API_KEY` with your actual API key.
> [Get a free Demo key or upgrade to Pro →](https://www.coingecko.com/en/api/pricing)
Restart to load the new server.
```bash Pro API Key theme={null}
claude mcp add coingecko \
-e COINGECKO_PRO_API_KEY=YOUR_API_KEY \
-e COINGECKO_ENVIRONMENT=pro \
-- npx -y @coingecko/coingecko-mcp
```
```bash Demo API Key theme={null}
claude mcp add coingecko \
-e COINGECKO_DEMO_API_KEY=YOUR_API_KEY \
-e COINGECKO_ENVIRONMENT=demo \
-- npx -y @coingecko/coingecko-mcp
```
> Replace `YOUR_API_KEY` with your actual API key.
> [Get a free Demo key or upgrade to Pro →](https://www.coingecko.com/en/api/pricing)
```bash theme={null}
claude mcp list
```
## FAQ
The Free server requires no authentication and uses shared rate limits. The API key server gives you higher rate limits and access to the full tool set — including premium endpoints available on your [CoinGecko plan](https://www.coingecko.com/en/api/pricing).
Use a local server if you need full control over the runtime, want to avoid browser-based OAuth, or prefer passing your API key via environment variables instead of the browser auth flow.
`/mcp` uses Streamable HTTP — the newer, recommended transport. `/sse` uses Server-Sent Events, an older protocol. Always prefer `/mcp` unless your client only supports SSE.
Any client that supports the [Model Context Protocol](https://modelcontextprotocol.io) — including Claude (Web, Desktop, Code), Cursor, Windsurf, and others. The setup steps on this page use Claude as an example, but the endpoints and configs work with any MCP-compatible client.
Yes. Each tool call the AI makes through MCP triggers one or more API requests, which count toward your plan's rate limit and credits.
***
Help us improve MCP — share your suggestions and feedback.
# Notion
Source: https://docs.coingecko.com/ai-integration/notion
Connect your Notion AI agent to CoinGecko MCP for live crypto data
[Notion](https://www.notion.com) AI Agents support custom MCP connections, giving your agent access to live CoinGecko data — prices, market trends, onchain analytics, and more.
Notion requires authenticated MCP — [CoinGecko API key](https://www.coingecko.com/en/api/pricing) is needed.
## Setup
Open Notion and navigate to **AI Agents** (or click **+ New agent** from the sidebar). Describe what your agent should do.
![]()
In your agent's settings, click **Add connection**. Scroll to the bottom of the left sidebar and click **+ Add custom MCP**.
![]()
Fill in the connection form:
| Field | Value |
| ------------------ | --------------------------------------- |
| **MCP server URL** | `https://mcp.pro-api.coingecko.com/mcp` |
| **Name** | `CoinGecko MCP` |
| **Authentication** | OAuth |
![]()
> Notion displays a warning: *"Notion hasn't reviewed this server."* This is expected for all custom MCP servers.
Click **Connect**.
A browser tab opens at `mcp.pro-api.coingecko.com/authorize`. Paste your API key and click **Log in and Approve**.
> Get a key at [coingecko.com/en/api/pricing](https://www.coingecko.com/en/api/pricing).
## Try It Out
Your Notion AI agent now has access to live CoinGecko data. Try these prompts:
* *"What is the current price of Bitcoin in USD?"*
* *"Show me the top 10 cryptocurrencies by market cap with price, 24h change, and volume in a table."*
* *"What are the top trending coins on CoinGecko right now?"*
* *"Research the top 5 DeFi coins and save a summary to this page."*
* *"Pull today's trending coins and add them as a database entry."*
## Troubleshooting
Make sure the MCP server URL begins with `https://` and is a complete, valid URL.
This appears for all custom MCP connections and is not an error. Safe to proceed.
Check that your browser isn't blocking popups from Notion. Allow popups and retry.
Confirm the MCP connection is active in your agent's settings. Re-authorize if your session has expired.
# OpenAI Codex
Source: https://docs.coingecko.com/ai-integration/openai-codex
Wire CoinGecko into OpenAI's Codex coding agent — MCP, SKILL, and SDK prompts in one place
[Codex](https://chatgpt.com/codex/) is OpenAI's coding agent available as both a terminal CLI and native app. The integrations below are complementary — use any combination.
## Setup
Gives Codex built-in knowledge of the CoinGecko API — writes correct requests without manual prompting.
```bash theme={null}
npx skills add coingecko/skills -g -y
```
> Full details: [Agent SKILL](/ai-integration/agent-skill)
Connects Codex to live CoinGecko data — prices, market caps, onchain pools, OHLCV, NFTs, and more.
```bash Free (Keyless) theme={null}
codex mcp add coingecko -- \
npx -y mcp-remote https://mcp.api.coingecko.com/mcp
```
```bash Use your API key theme={null}
codex mcp add coingecko -- \
npx -y mcp-remote https://mcp.pro-api.coingecko.com/mcp
```
> Full details: [CoinGecko MCP](/ai-integration/mcp-server)
Lets Codex search CoinGecko documentation directly — endpoint references, guides, and tutorials.
```bash theme={null}
codex mcp add coingecko-docs -- \
npx -y mcp-remote https://docs.coingecko.com/mcp
```
> Full details: [Docs MCP](/ai-integration/docs-mcp)
## SDK Prompts
Copy these prompts into your `AGENTS.md` or paste at the start of a conversation to ensure Codex generates correct SDK code.
# CoinGecko Python SDK — AI Prompt Rules
## Install
```
pip install coingecko_sdk
```
## Client Setup
```python theme={null}
import os
from coingecko_sdk import Coingecko
client = Coingecko(
pro_api_key=os.environ.get("YOUR_API_KEY"),
environment="pro", # or "demo" with demo_api_key
max_retries=2,
)
```
* Load API keys from environment variables. Never hardcode.
* Initialize one reusable client instance.
* For async: use `AsyncCoingecko` with `await`.
## Finding Methods
Methods map to endpoint paths using snake\_case, but names are **not always predictable**
— path parameters like `{address}` may become part of the method name
(e.g. `get_address()`, `get_addresses()`, `get_network()`).
**Before using any SDK method, you MUST verify the exact method name.** Do not guess.
1. **Check the reference page first** — every endpoint page includes an SDK Examples section
at the bottom with copy-ready code:
* URL pattern: `https://docs.coingecko.com/reference/{operationId}.md`
* Look for the `#### SDK Examples` block and use the Python snippet exactly as shown.
2. **Full method list** — if you need to search across all methods:
`https://docs.coingecko.com/docs/sdk-python-methods.md`
3. **Parameter details and endpoint caveats**:
`https://docs.coingecko.com/reference/{operationId}.md`
## Error Handling
Catch specific SDK exceptions — never use bare `except Exception`.
```python theme={null}
import coingecko_sdk
try:
response = client.simple.price.get(vs_currencies="usd", ids="bitcoin")
except coingecko_sdk.RateLimitError:
# Back off — 429 received
pass
except coingecko_sdk.NotFoundError:
# Invalid coin ID or endpoint
pass
except coingecko_sdk.APIError as e:
print(e.status_code, e.response)
```
## Rules
* ALWAYS use `coingecko_sdk`. Never use `pycoingecko` or raw `requests`/`httpx`.
* Rely on the SDK's built-in retry (`max_retries`). Never write manual retry loops.
* Responses are Pydantic models — use `.to_dict()` or `.to_json()` when needed.
* Use `client.with_options()` for per-request overrides (timeout, retries).
# CoinGecko TypeScript SDK — AI Prompt Rules
## Install
```
npm install @coingecko/coingecko-typescript
```
## Client Setup
```typescript theme={null}
import Coingecko from '@coingecko/coingecko-typescript';
const client = new Coingecko({
proAPIKey: process.env['YOUR_API_KEY'],
environment: 'pro', // or 'demo' with demoAPIKey
maxRetries: 2,
});
```
* Load API keys from environment variables. Never hardcode.
* Initialize one reusable client instance.
## Finding Methods
Methods map to endpoint paths using camelCase, but names are **not always predictable**
— path parameters like `{address}` may become part of the method name
(e.g. `getAddress()`, `getAddresses()`, `getNetwork()`, `getID()`).
**Before using any SDK method, you MUST verify the exact method name.** Do not guess.
1. **Check the reference page first** — every endpoint page includes an SDK Examples section
at the bottom with copy-ready code:
* URL pattern: `https://docs.coingecko.com/reference/{operationId}.md`
* Look for the `#### SDK Examples` block and use the TypeScript snippet exactly as shown.
2. **Full method list** — if you need to search across all methods:
`https://docs.coingecko.com/docs/sdk-typescript-methods.md`
3. **Parameter details and endpoint caveats**:
`https://docs.coingecko.com/reference/{operationId}.md`
## Error Handling
Catch specific SDK exceptions — never use bare `catch (e)` without checking the type.
```typescript theme={null}
import Coingecko from '@coingecko/coingecko-typescript';
try {
const response = await client.simple.price.get({ vs_currencies: 'usd', ids: 'bitcoin' });
} catch (err) {
if (err instanceof Coingecko.RateLimitError) {
// Back off — 429 received
} else if (err instanceof Coingecko.NotFoundError) {
// Invalid coin ID or endpoint
} else if (err instanceof Coingecko.APIError) {
console.log(err.status, err.headers);
} else {
throw err;
}
}
```
## Rules
* ALWAYS use `@coingecko/coingecko-typescript`. Never use raw `fetch`/`axios`/`node-fetch`.
* Rely on the SDK's built-in retry (`maxRetries`). Never write manual retry loops.
* Use SDK types for params and responses: `Coingecko.Simple.PriceGetParams`, `Coingecko.Simple.PriceGetResponse`.
* Use the second argument for per-request overrides: `client.simple.price.get(params, { maxRetries: 5 })`.
## Try It Out
Once everything's wired up, try asking Codex:
* *"Using the CoinGecko MCP, show me the top 10 trending pools on Base and export them to CSV."*
* *"Write a Python script using coingecko-sdk that tracks my portfolio and alerts if any coin moves more than 10% in an hour."*
# OpenClaw
Source: https://docs.coingecko.com/ai-integration/openclaw
Connect CoinGecko to your OpenClaw agent — MCP server, SKILL, and CLI in one place
[OpenClaw](https://openclaw.ai) is an AI agent platform for crypto. Plug CoinGecko in through any combination of the three integrations below — they're complementary, not exclusive.
## Setup
Connects your agent to live CoinGecko data — prices, market caps, onchain pools, OHLCV, NFTs, and more.
```bash Demo API Key theme={null}
openclaw mcp set coingecko_mcp \
'{"command":"npx","args":["-y","@coingecko/coingecko-mcp"],"env":{
"COINGECKO_DEMO_API_KEY":"YOUR_API_KEY",
"COINGECKO_ENVIRONMENT":"demo"
}}'
```
```bash Pro API Key theme={null}
openclaw mcp set coingecko_mcp \
'{"command":"npx","args":["-y","@coingecko/coingecko-mcp"],"env":{
"COINGECKO_PRO_API_KEY":"YOUR_API_KEY",
"COINGECKO_ENVIRONMENT":"pro"
}}'
```
> Replace `YOUR_API_KEY` with your key from the [Developer Dashboard](https://www.coingecko.com/en/developers/dashboard).
> Full setup details: [CoinGecko MCP](/ai-integration/mcp-server)
Gives your agent built-in knowledge of the CoinGecko API — writes correct requests without manual prompting.
```bash theme={null}
openclaw skills install coingecko-api
```
> Full setup details: [Agent SKILL](/ai-integration/agent-skill)
Terminal interface for querying real-time and historical crypto data, with interactive dashboards, CSV/JSON export, and WebSocket streaming.
```bash wrap theme={null}
curl -sSfL https://raw.githubusercontent.com/coingecko/coingecko-cli/main/install.sh | sh
```
Then authenticate and verify:
```bash theme={null}
cg auth
cg price --ids bitcoin
```
> Full setup details: [CoinGecko CLI](/ai-integration/cli)
## Try It Out
Once everything's wired up, try asking your OpenClaw agent:
* *"Using the CoinGecko MCP, show me the top 10 trending pools on Base in the last 5 minutes."*
* *"What are the top gainers in the last 24 hours? Export them to CSV."*
# Pay-Per-Use Crypto Data (x402)
Source: https://docs.coingecko.com/ai-integration/x402
Access CoinGecko API endpoints with native crypto payments — no API key or account required
Experimental endpoints — features, pricing, and availability may change without notice.
For production systems, use the standard [subscription endpoints](/reference/endpoint-overview).
[x402](https://docs.cdp.coinbase.com/x402/welcome) is an open payment protocol by Coinbase that enables instant stablecoin payments over HTTP.
## Getting Started
Follow the [x402 Quickstart for Buyers](https://docs.cdp.coinbase.com/x402/quickstart-for-buyers) to configure your wallet.
Insert `/x402/` after `/v3/` in any supported endpoint path.
```bash theme={null}
https://pro-api.coingecko.com/api/v3/x402/...
```
The server responds with `402` code and payment requirements.
Your wallet signs a USDC authorization.
Resend the request with the `PAYMENT-SIGNATURE` header:
```bash wrap theme={null}
curl --request GET \
--url https://pro-api.coingecko.com/api/v3/onchain/simple/networks/eth/token_price/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 \
-H 'PAYMENT-SIGNATURE: {{paymentSignature}}'
```
> The x402 client generates the `PAYMENT-SIGNATURE` header automatically — you don't need to create it manually.
```json theme={null}
"token_prices": {
"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2": "1678.6456001894"
}
```
> See each [endpoint reference](/reference/endpoint-overview) for full payload details.
Do **NOT** send `x-cg-pro-api-key` or `x-cg-demo-api-key` — no API key is required for x402 requests.
## Supported Endpoints
| Endpoint | x402 Path |
| --------------------------------------------------------------- | ---------------------------------------------------------- |
| [Simple Price](/reference/simple-price) | `/x402/simple/price` |
| [Simple Token Price](/reference/onchain-simple-price) | `/x402/onchain/simple/networks/{id}/token_price/{address}` |
| [Search Pools](/reference/search-pools) | `/x402/onchain/search/pools` |
| [Trending Pools by Network](/reference/trending-pools-network) | `/x402/onchain/networks/{id}/trending_pools` |
| [Token Data by Address](/reference/token-data-contract-address) | `/x402/onchain/networks/{network}/tokens/{address}` |
* All parameters from the [Pro API](/reference/endpoint-overview) are supported — refer to each endpoint's reference page for details.
* For `network_id` values, see the [Networks List](/reference/networks-list) or this [Google Sheet](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?gid=1120233236#gid=1120233236).
* See the [x402 guide](https://www.coingecko.com/learn/x402-pay-per-use-crypto-api) for more usage details.
## Request Examples
```bash theme={null}
GET /api/v3/x402/onchain/simple/networks/base/token_price/0x0b3e328455c4059eeb9e3f84b5543f74e24e7e1b,0x4200000000000000000000000000000000000006
?include_market_cap=true
&include_24hr_vol=true
&include_24hr_price_change=true
```
```bash theme={null}
GET /api/v3/x402/onchain/search/pools
?query=pump
&network=solana
&include=base_token,quote_token,dex
&page=1
```
```bash theme={null}
GET /api/v3/x402/onchain/networks/base/trending_pools
?page=1
&duration=5m
&include=base_token,quote_token,dex
```
```bash theme={null}
GET /api/v3/x402/onchain/networks/base/tokens/0xc0634090f2fe6c6d75e61be2b949464abb498973
?include=top_pools
&include_composition=true
```
```bash theme={null}
GET /api/v3/x402/simple/price
?vs_currencies=usd
&symbols=btc,eth,sol
&include_market_cap=true
&include_24hr_vol=true
&include_24hr_change=true
&precision=full
```
## Pricing & Payment
* **\$0.01 USDC per request** for all supported endpoints.
* Payment networks: Base, Solana
Pricing is subject to change without notice.
Always check the latest pricing from the `402` response when generating your payment header.
**Paying with Privy Wallet**
*Privy provides embedded and agent wallets with native x402 support — an all-in-one option for paying CoinGecko API calls.*
* [x402 integration recipe](https://docs.privy.io/recipes/agent-integrations/x402)
* [Privy Agent Wallet CLI](https://docs.privy.io/recipes/agent-integrations/agent-wallets-cli)
***
Questions or feedback about x402 endpoints? Let us know.
# Changelog
Source: https://docs.coingecko.com/changelog
Product updates and announcements
## New Endpoints: Onchain Price and Token Data across Networks
🗓️ **September 10, 2026**
Query tokens on different networks in a single call, instead of one call per network.
| Endpoint | Description |
| :-------------------------------------------------------------------------- | :--------------------------------------------------------------- |
| [/onchain/simple/token\_price/multi](/reference/onchain-simple-price-multi) | Token price by token contract addresses across networks |
| [/onchain/tokens/multi](/reference/tokens-data-contract-addresses-multi) | Multiple tokens data by token contract addresses across networks |
Both take a new `tokens` param, up to 50 `network_id:token_address` pairs:
`?tokens=eth:0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,`
`polygon_pos:0x0d500b1d8e8ef31e21c99d1db9a6444d3adf1270`
> 👑 Exclusive for Enterprise plan subscribers. [Contact sales →](https://www.coingecko.com/en/api/enterprise)
***
## Market Chart Endpoints: 1-Minutely Data with `interval=1m`
🗓️ **September 10, 2026**
`interval=1m` now returns 1-minutely historical data on:
* [/coins/\{id}/market\_chart](/reference/coins-id-market-chart)
* [/coins/\{id}/market\_chart/range](/reference/coins-id-market-chart-range)
* [/coins/\{id}/contract/\{contract\_address}/market\_chart](/reference/contract-address-market-chart)
* [/coins/\{id}/contract/\{contract\_address}/market\_chart/range](/reference/contract-address-market-chart-range)
`interval=1m` is capped at **1 day** per request, with data available from 1 June 2026 onward.
> 👑 Exclusive for Enterprise plan subscribers. [Contact sales →](https://www.coingecko.com/en/api/enterprise)
***
## Introducing Wallet Endpoints — Token Balances and Transfers by Wallet Address
🗓️ **September 9, 2026**
CoinGecko now supports wallet-level onchain data via the API — every token a wallet holds, and the raw transfers behind those holdings.
| Endpoint | Description |
| :--------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------- |
| [/onchain/wallets/\{address}/balances](/reference/wallet-token-balances) | Token balances of a wallet across networks, with USD value and liquidity per holding |
| [/onchain/networks/\{network}/wallets
/\{address}/transfers](/reference/wallet-token-transfers) | Token transfers of a wallet on a network, cursor-paginated |
Supported at launch on Ethereum, Base, BNB Chain, Polygon, Arbitrum, Optimism, Avalanche, Stable and Robinhood, with more networks and more [Wallets](/reference/onchain-wallets-overview) endpoints to follow.
> 💼 Exclusive for [Analyst plan & above](https://www.coingecko.com/en/api/pricing) subscribers.
***
## Trades Endpoints: Cursor Pagination and `trading_period` Lookback
🗓️ **September 8, 2026**
[Trades by Pool Address](/reference/pool-trades-contract-address) and [Trades by Token Address](/reference/token-trades-contract-address) now look back further than 24 hours and page through results with a cursor, lifting the previous 300-trade ceiling.
| Param | Description |
| :--------------- | :------------------------------------------------------------------------------ |
| `trading_period` | Lookback period — `1d`, `7d` or `30d`. Defaults to `1d` |
| `cursor` | Cursor from the previous response, passed back unchanged to fetch the next page |
| `per_page` | Total results per page. Defaults to 300 |
Responses now carry `meta.next_cursor` — pass it back as `cursor` to page through the full set of trades.
> `trading_period`, `cursor` and `per_page` require [Analyst plan & above](https://www.coingecko.com/en/api/pricing).
> Both endpoints remain available to all paid plans, with [Trades by Pool Address](/reference/pool-trades-contract-address) also on [Demo](/demo/reference/endpoint-overview).
***
## New Endpoints: Trades within Time Range
🗓️ **September 7, 2026**
Query onchain trades inside an absolute `from`/`to` window — for a named period such as March 2026, which a relative lookback cannot express.
| Endpoint | Description |
| :------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------- |
| [/onchain/networks/\{network}/pools
/\{pool\_address}/trades/range](/reference/pool-trades-contract-address-range) | Trades within a time range by pool address |
| [/onchain/networks/\{network}/tokens
/\{token\_address}/trades/range](/reference/token-trades-contract-address-range) | Trades within a time range across all pools by token address |
`from` and `to` are both required, accept an ISO date string or a UNIX timestamp, and may span at most 30 days. Results are cursor-paginated through `meta.next_cursor`.
> 💼 Exclusive for [Analyst plan & above](https://www.coingecko.com/en/api/pricing) subscribers.
## New CGSimplePrice Fields: Price Change Percentages, Circulating Supply & FDV
🗓️ **August 28, 2026**
[CGSimplePrice](/websocket/cgsimpleprice) now streams six additional fields, included by default with no extra parameter.
| Key | Field | Description |
| :------ | :---------------------------- | :----------------------------------------------------- |
| `pp7d` | `price_7d_change_percentage` | Price change percentage over the last 7 days |
| `pp30d` | `price_30d_change_percentage` | Price change percentage over the last 30 days |
| `pp60d` | `price_60d_change_percentage` | Price change percentage over the last 60 days |
| `pp1y` | `price_1y_change_percentage` | Price change percentage over the last 1 year |
| `cs` | `circulating_supply` | Circulating supply of coin |
| `fdv` | `fully_diluted_value` | Fully diluted valuation in the specified `vs_currency` |
```json Example Payload highlight={7-10,12-13} theme={null}
{
"c": "C1",
"i": "bitcoin",
"vs": "usd",
"p": 61696.67928656691,
"pp": 1.4192404041947198,
"pp7d": 3.8214,
"pp30d": -2.1543,
"pp60d": 12.4512,
"pp1y": 120.8541,
"m": 1236047139289.684,
"cs": 19734150,
"fdv": 1312500000000,
"v": 30595921115.53988,
"t": 1780839768
}
```
> [WebSocket](/websocket) requires [Basic plan & above](https://www.coingecko.com/en/api/pricing).
***
## Introducing RWA Endpoints — Aggregated Tokenized Market Data
🗓️ **August 27, 2026**
CoinGecko now supports tokenized real world assets (RWAs) via the API — aggregated market data for tokenized stocks and commodities, and the issuers behind them.
| Endpoint | Description |
| :----------------------------------------------------------- | :--------------------------------------------------------------- |
| [/rwas/list](/reference/rwas-list) | All supported RWAs with RWA ID, name and symbol |
| [/rwas/markets](/reference/rwas-markets) | All RWAs with price, market cap, volume and market data |
| [/rwas/\{id}](/reference/rwas-id) | Metadata, market data and tokens of an RWA |
| [/rwas/\{id}/tickers](/reference/rwas-id-tickers) | RWA token tickers across centralized and decentralized exchanges |
| [/rwas/\{id}/market\_chart](/reference/rwas-id-market-chart) | Historical price, market cap and volume |
| [/rwas/issuers/list](/reference/rwas-issuers-list) | All supported RWA issuers with issuer ID and name |
| [/rwas/issuers/\{id}](/reference/rwas-issuers-id) | Market data and tokens of an issuer |
See live data on [Real World Assets](https://www.coingecko.com/en/real-world-assets), [Stocks](https://www.coingecko.com/en/stocks), and [Commodities](https://www.coingecko.com/en/commodities).
All market data reflects the aggregated onchain tokenized market, not the underlying stock or commodity spot market. All values are in USD.
> [/rwas/\{id}/tickers](/reference/rwas-id-tickers) and [/rwas/\{id}/market\_chart](/reference/rwas-id-market-chart) require **Basic plan and above**.
> All other RWA endpoints are available on every plan, including [Demo](/demo/reference/endpoint-overview).
***
## Upcoming Change Notice: Removal of community\_data and developer\_data
🗓️ **August 14, 2026**
**Effective August 28, 2026**
The `community_data` and `developer_data` objects will be removed from the following endpoints:
* [Coin Data by ID](/reference/coins-id)
* [Coin Historical Data by ID](/reference/coins-id-history)
* [Coin Data by Token Address](/reference/coins-contract-address)
Until then, both objects remain in the response, but the values are no longer being updated and will stay stale.
```json What we're deprecating expandable theme={null}
"community_data": {
"facebook_likes": null,
"reddit_average_posts_48h": 7.333,
"reddit_average_comments_48h": 384.667,
"reddit_subscribers": 6127543,
"reddit_accounts_active_48h": 3498,
"telegram_channel_user_count": null
},
"developer_data": {
"forks": 36433,
"stars": 76697,
"subscribers": 3967,
"total_issues": 7743,
"closed_issues": 7379,
"pull_requests_merged": 11204,
"pull_request_contributors": 829,
"code_additions_deletions_4_weeks": {
"additions": 1264,
"deletions": -1314
},
"commit_count_4_weeks": 108,
"last_4_weeks_commit_activity_series": [0, 3, 2, 0, 1, 0, 0]
}
```
If your application relies on this, update your code to handle its absence.
## Pro API Update: More Consistent Historical Price Data Spacing
🗓️ **July 21, 2026**
We're improving the historical data returned by the endpoints below so that 5-minute and hourly data points are interval-aligned, landing precisely on fixed interval boundaries (for example, exactly on the hour) rather than slightly before or after. This is a data-quality improvement: response schemas and structure are unchanged, and no request or response format changes are required on your end.
**Who this affects**
This rollout applies to all paid plan users: **Basic, Analyst, Lite, Pro, Pro+, and Enterprise**. Please refer to the rollout schedule below for the exact effective date and time for each plan tier.
**Improved endpoints**
* [/coins/:id/market\_chart](/reference/coins-id-market-chart)
* [/coins/:id/market\_chart/range](/reference/coins-id-market-chart-range)
* [/coins/:id/contract/:contract\_address/market\_chart](/reference/contract-address-market-chart)
* [/coins/:id/contract/:contract\_address/market\_chart/range](/reference/contract-address-market-chart-range)
* [/coins/:id/history](/reference/coins-id-history)
* [/coins/:id/circulating\_supply\_chart](/reference/coins-id-circulating-supply-chart)
* [/coins/:id/circulating\_supply\_chart/range](/reference/coins-id-circulating-supply-chart-range)
**What's improving**
* Previously, data points landed close to, but not exactly on, each interval boundary. For example, hourly data might return timestamps like:
```json theme={null}
1704067241 (2024-01-01 00:00:41)
1704070877 (2024-01-01 01:01:17)
1704074383 (2024-01-01 01:59:43)
```
* After the rollout, data points will land precisely on the interval boundary:
```json theme={null}
1704067200 (2024-01-01 00:00:00)
1704070800 (2024-01-01 01:00:00)
1704074400 (2024-01-01 02:00:00)
```
This makes historical series easier to align, join, and compare programmatically, without needing to round or bucket timestamps yourself.
**What you need to do**
Values, not structure, will change. The JSON schema and field structure for these endpoints stay exactly the same, so you don't need to update any parsing logic. What differs is the value returned for a given historical timestamp, since it now reflects the interval-aligned data point.
| **Endpoints** | **Improved fields** |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------ |
| [/coins/:id/market\_chart](/reference/coins-id-market-chart),
[/coins/:id/market\_chart/range](/reference/coins-id-market-chart-range),
[/coins/../contract/../market\_chart](/reference/contract-address-market-chart),
[/coins/../contract/../market\_chart/range](/reference/contract-address-market-chart-range) | `prices`,
`market_caps`,
`total_volumes` |
| [/coins/:id/history](/reference/coins-id-history) | `market_data.current_price`,
`market_data.market_cap`,
`market_data.total_volume` |
| [/coins/:id/circulating\_supply\_chart](/reference/coins-id-circulating-supply-chart),
[/coins/:id/circulating\_supply\_chart/range](/reference/coins-id-circulating-supply-chart-range) | `circulating_supply` |
If you cache or store historical data locally, expect that re-querying a historical timestamp after your plan's effective date may return a value that differs slightly from what you previously stored, since it's now sourced from the corrected, interval-aligned timestamp.
If your integration does exact-timestamp matching or joins against externally stored data, this change should make that easier and more reliable going forward, but double-check any logic written to accommodate the old unaligned timestamps.
**Why values may look different — this is an improvement, not an error.**
If you compare historical values before and after this change, you may notice differences. This is expected: the new data pipeline sources prices more accurately than the previous system. We've measured and validated the new values against major assets and confirmed the differences fall within an acceptable, expected range.
If you see something that looks like an outlier beyond that, let us know by submitting a ticket at [support.coingecko.com](https://support.coingecko.com).
**Rollout schedule**
This will roll out progressively by plan tier:
| **Plan** | **Effective time** |
| --------------- | :-------------------------- |
| Basic, Analyst | 4 August 2026, 02:00:00 UTC |
| Lite, Pro, Pro+ | 5 August 2026, 02:00:00 UTC |
| Enterprise | 6 August 2026, 02:00:00 UTC |
No action is needed on your end during this window.
***
## Public API Update: More Consistent Historical Price Data Spacing
🗓️ **July 17, 2026**
We're improving the historical data returned by the endpoints below so that 5-minute and hourly data points are interval-aligned, landing precisely on fixed interval boundaries (for example, exactly on the hour) rather than slightly before or after. This is a data-quality improvement: response schemas and structure are unchanged, and no request or response format changes are required on your end.
**Who this affects**
This rollout applies to **free-tier users only**, including both keyless (unauthenticated) requests and requests made with a registered Demo API key. If you're on a paid plan (Basic, Analyst, Lite, Pro/Pro+, or Enterprise), this change doesn't affect you yet. You'll be notified separately when it's extended to your plan, on its own schedule.
**Improved endpoints**
* [/coins/:id/market\_chart](/demo/reference/coins-id-market-chart)
* [/coins/:id/market\_chart/range](/demo/reference/coins-id-market-chart-range)
* [/coins/:id/contract/:contract\_address/market\_chart](/demo/reference/contract-address-market-chart)
* [/coins/:id/contract/:contract\_address/market\_chart/range](/demo/reference/contract-address-market-chart-range)
* [/coins/:id/history](/demo/reference/coins-id-history)
**What's improving**
* Previously, data points landed close to, but not exactly on, each interval boundary. For example, hourly data might return timestamps like:
```json theme={null}
1704067241 (2024-01-01 00:00:41)
1704070877 (2024-01-01 01:01:17)
1704074383 (2024-01-01 01:59:43)
```
* After the rollout, data points will land precisely on the interval boundary:
```json theme={null}
1704067200 (2024-01-01 00:00:00)
1704070800 (2024-01-01 01:00:00)
1704074400 (2024-01-01 02:00:00)
```
This makes historical series easier to align, join, and compare programmatically, without needing to round or bucket timestamps yourself.
**What you need to do**
Values, not structure, will change. The JSON schema and field structure for these endpoints stay exactly the same, so you don't need to update any parsing logic. What differs is the value returned for a given historical timestamp, since it now reflects the interval-aligned data point.
| **Endpoints** | **Improved fields** |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------ |
| [/coins/:id/market\_chart](/demo/reference/coins-id-market-chart),
[/coins/:id/market\_chart/range](/demo/reference/coins-id-market-chart-range),
[/coins/../contract/../market\_chart](/demo/reference/contract-address-market-chart),
[/coins/../contract/../market\_chart/range](/demo/reference/contract-address-market-chart-range) | `prices`,
`market_caps`,
`total_volumes` |
| [/coins/:id/history](/demo/reference/coins-id-history) | `market_data.current_price`,
`market_data.market_cap`,
`market_data.total_volume` |
If you cache or store historical data locally, expect that re-querying a historical timestamp after the rollout may return a value that differs slightly from what you previously stored, since it's now sourced from the corrected, interval-aligned timestamp.
If your integration does exact-timestamp matching or joins against externally stored data, this change should make that easier and more reliable going forward, but double-check any logic written to accommodate the old unaligned timestamps.
**Why values may look different — this is an improvement, not an error.**
If you compare historical values before and after this change, you may notice differences. This is expected: the new data pipeline sources prices more accurately than the previous system. We've measured and validated the new values against major assets and confirmed the differences fall within an acceptable, expected range.
If you see something that looks like an outlier beyond that, let us know by submitting a ticket at [support.coingecko.com](https://support.coingecko.com).
**Rollout: 02:00 UTC, 23 July 2026**
This will roll out at 02:00 UTC on 23 July 2026 via phased deployment. Traffic will shift gradually over approximately 2 hours, so during this window some requests may be served by the improved pipeline while others are still served by the previous one. This is expected and temporary. Once the rollout completes, all traffic will be fully migrated to the improved pipeline.
No action is needed on your end during this window.
Other plans (Basic, Analyst, Lite, Pro, Pro+, Enterprise) will follow on a separate, staggered schedule to be announced.
***
## Pay for Your API Subscription with Crypto
🗓️ **July 14, 2026**
You can now pay for an annual Analyst plan (or above) API subscription with crypto instead of a card.
* Supported chains: **Solana**, **Ethereum**, **Base**, **Polygon**, **Arbitrum**, and **BNB Chain**
* **USDC** and **USDT** are supported on every chain, with more available at checkout
Learn more in [Pay with Crypto](/docs/crypto-payment).
***
## New Supported Chain: Robinhood for Top Token Holders
🗓️ **July 2, 2026**
Robinhood chain is now supported on [Top Token Holders by Token Address](/reference/top-token-holders-token-address) and [Historical Token Holders Chart by Token Address](/reference/token-holders-chart-token-address).
***
## Robinhood Chain is now live on CoinGecko Onchain Data
🗓️ **July 1, 2026**
* CoinGecko API now supports the Robinhood network across [onchain endpoints](/reference/endpoint-overview#onchain). Pass `robinhood` as the `network` parameter to query it like any other supported chain.
* Prefer CoinGecko's aggregated coin data over onchain? You can also fetch Robinhood coins via [Token Lists](/reference/token-lists) (`asset_platform_id=robinhood`) or [Coins Markets](/reference/coins-markets) filtered to the Robinhood ecosystem category.
* Robinhood joins our lineup as we keep pushing the widest chain coverage in the industry.
## Deprecation: VEF (Venezuelan Bolívar Fuerte) Currency
🗓️ **June 24, 2026**
Starting June 30, 2026, we will begin a phased deprecation of the **VEF (Venezuelan Bolívar Fuerte)** currency across all API endpoints, affecting all query parameters and endpoint responses.
This means that **only the specific data points involving VEF** will either be missing or inaccurate. To avoid any service disruptions, all clients must update their integrations and completely remove any dependencies on this deprecated currency **by June 30, 2026.**
***
## Top Token Traders: New `token_balance_desc` Sort Option
🗓️ **June 21, 2026**
[Top Token Traders by Token Address](/reference/top-token-traders-token-address) now supports `token_balance_desc` as a `sort` option, allowing you to sort traders by their current remaining token balance.
***
## New Token Info Field: Banner Image URL
🗓️ **June 21, 2026**
New `banner_image_url` field is now available on:
* [Token Info by Token Address](/reference/token-info-contract-address)
* [Pool Token Info by Token Address](/reference/pool-token-info-contract-address)
```json Example Payload highlight={8} theme={null}
{
"data": {
"id": "solana_Dfh5DzRgSvvCFDoYc2ciTkMrbDfRKybA4SoFbPmApump",
"type": "token",
"attributes": {
...
"image": { ... },
"banner_image_url": "https://assets.geckoterminal.com/kn680ou6904r03syp0ecu52ihy9c",
"coingecko_coin_id": "pippin",
```
***
## New Token Info Fields: Developer Address & Holding Percentage
🗓️ **June 16, 2026**
[Token Info by Token Address](/reference/token-info-contract-address) and [Pool Token Info by Token Address](/reference/pool-token-info-contract-address) now include:
* `developer_address` — developer wallet address
* `developer_holding_percentage` — developer holding as a percentage of total supply
```json Example Payload highlight={4-5} theme={null}
...
"freeze_authority": "no",
"is_honeypot": "unknown",
"developer_address": "4t7dHZcUzNC96d79won5TRZsvwP1bumhPNf3awR5BHdu",
"developer_holding_percentage": "0.0"
}
```
***
## New Megafilter Parameters: Holder Count & Top Holders Percentage
🗓️ **June 15, 2026**
[Megafilter for Pools](/reference/pools-megafilter) now supports filtering by holder count and top holder concentration:
* `holder_count_min` / `holder_count_max` — filter pools by token holder count
* `top_10_holders_percentage_min` / `top_10_holders_percentage_max` — filter by top 10 holders' percentage of total supply
***
## New Endpoint: Coin Supply Breakdown
🗓️ **June 10, 2026**
New [/coins/\{id}/supply\_breakdown](/reference/coins-id-supply-breakdown) endpoint — query the supply breakdown of a coin, including non-circulating wallet addresses and balances.
* Returns `supply_data` with total, circulating, non-circulating, and outstanding supply
* Includes `non_circulating_wallets` with wallet address, label, balance, percentage of total supply, and anomaly flag
* Use the new `has_supply_breakdown` field in [/coins/\{id}](/reference/coins-id) and [/coins/\{id}/contract/\{contract\_address}](/reference/coins-contract-address) to check if breakdown data is available for a coin
```json Example Payload expandable theme={null}
{
"id": "uniswap",
"symbol": "uni",
"name": "Uniswap",
"supply_data": {
"total_supply": 894488420.0329479,
"circulating_supply": 622353561.5538775,
"outstanding_supply": 0.0,
"non_circulating_supply": 272134858.4790704,
"last_updated": "2026-06-11T09:16:07.477Z"
},
"non_circulating_wallets": [
{
"address": "0x1a9C8182C09F50C8318d769245beA52c32BE35BC",
"label": "UNI Timelock",
"balance": 272134858.4790704,
"percentage_of_total_supply": 30.423383405422996,
"anomaly": false,
"last_updated": "2026-06-11T06:14:14.076Z"
}
]
}
```
> 💼 Exclusive for paid plan subscribers (Analyst, Lite, Pro, and Enterprise). [View pricing →](https://www.coingecko.com/en/api/pricing)
***
## New Endpoint: Coin Insights
🗓️ **June 10, 2026**
New [/insights](/reference/insights) endpoint — query the latest AI-generated coin insights on CoinGecko.
* Filter by `coin_id`, `from`, and `to` date parameters
```json Example Payload theme={null}
[
{
"title": "BTC Prague 2026 Conference Goes Live",
"description": "The BTC Prague 2026 conference is now live, featuring high-profile speakers and institutional attendance...",
"related_coin_ids": ["bitcoin"],
"posted_at": "2026-06-11T07:57:14.180091Z"
}
]
```
> 👑 Exclusive for Enterprise plan subscribers. [Contact sales →](https://www.coingecko.com/en/api/enterprise)
## Breaking Change: Sparkline Image URL Domain Migration for Trending Search
🗓️ **May 20, 2026**
**Effective June 4, 2026** — `sparkline` image URLs returned by [Trending Search List](/reference/trending-search) are migrating from `www.coingecko.com` to `data.coingecko.com`.
Affects the `sparkline` field across **coins**, **NFTs**, and **categories**:
| Section | Before | After |
| :--------- | :-------------------------------------------------------- | :--------------------------------------------------------- |
| Coins | `https://www.coingecko.com/coins/{id}/sparkline.svg` | `https://data.coingecko.com/coins/{id}/sparkline.svg` |
| NFTs | `https://www.coingecko.com/nft/{id}/sparkline.svg` | `https://data.coingecko.com/nft/{id}/sparkline.svg` |
| Categories | `https://www.coingecko.com/categories/{id}/sparkline.svg` | `https://data.coingecko.com/categories/{id}/sparkline.svg` |
If your application references or validates the sparkline URL domain, update your code to use `data.coingecko.com`.
***
## Introducing Webhooks — Real-Time Push Notifications for Coin Data Changes
🗓️ **May 19, 2026**
CoinGecko now supports [Webhooks](/webhooks) — real-time push notifications to your server when data changes occur, eliminating constant API polling.
* Supports the [`cg.coin.info.updated`](/webhooks/cg-coin-info-updated) event — triggers on updates to coin info (`name`, `symbol`, `categories`, `platforms`, `links`, `image`, `public_notices`, and more)
* Set up via the [Developer Dashboard](https://www.coingecko.com/en/developers/dashboard#webhook) — payloads are signed with HMAC SHA256
* 10 credits per event delivery — retries are free
* Up to 5 webhook endpoints per account
> 💼 Exclusive for paid plan subscribers (Analyst, Lite, Pro, and Enterprise). [Learn more →](/webhooks)
***
## Higher Minute Rate Limits for Demo & Basic Plans
🗓️ **May 17, 2026**
Requests-per-minute (RPM) rate limits have been increased:
| Plan | Previous | New |
| :---------- | :------: | :-----: |
| Demo (Free) | 30 | **100** |
| Basic | 250 | **300** |
No action required — new limits are already in effect.
***
## Track Per-Key Monthly API Usage with `/key` Endpoint
🗓️ **May 17, 2026**
[/key](/reference/api-usage) now returns `api_key_current_total_monthly_calls` — the total API calls made this month by the specific API key used to authenticate the request.
```json Example Payload highlight={8} theme={null}
{
"plan": "Other",
"rate_limit_request_per_minute": 1000,
"monthly_call_credit": 1000000,
"current_total_monthly_calls": 104,
"current_remaining_monthly_calls": 999896,
...
"api_key_current_total_monthly_calls": 8
}
```
Available for accounts with custom per-key rate limits. [Contact sales](https://www.coingecko.com/en/api/enterprise) to set up per-key limits.
## Stay Ahead with the New Crypto News Endpoint
🗓️ **March 27, 2026**
New [/news](/reference/news) endpoint — query crypto news and guides as seen on [CoinGecko News](https://www.coingecko.com/en/news).
* Filter by `coin_id`, `language`, and `type` (news, guides, or both)
* Pagination with `page` and `per_page`
```json Example Payload expandable theme={null}
[
{
"title": "Bitcoin stalls: Why BTC risks $65K fall despite $23M whale buy",
"url": "https://ambcrypto.com/bitcoin-stalls-why-btc-risks-65k-fall-despite-23m-whale-buy/",
"image": "https://assets.coingecko.com/articles/images/106731445/large/open-uri20260327-7-fuq6r9.?1774609423",
"author": "Gladys Makena",
"posted_at": "2026-03-27T11:00:42Z",
"type": "news",
"source_name": "AMBCrypto",
"related_coin_ids": [
"1-token-2",
"1-token",
"bitcoin"
]
}
]
```
> 💼 Exclusive for paid plan subscribers (Analyst, Lite, Pro, and Enterprise).
***
## CGSimplePrice WebSocket Now Supports `vs_currencies`
🗓️ **March 25, 2026**
[CGSimplePrice](/websocket/cgsimpleprice) now supports `vs_currencies` to specify preferred exchange rates. Choose from any currency supported by [/simple/supported\_vs\_currencies](/reference/simple-supported-currencies). Defaults to USD if not specified.
A new `vs` field in every response indicates the target currency.
**Input:**
```json theme={null}
{
"command": "message",
"identifier": "{\"channel\":\"CGSimplePrice\"}",
"data": "{\"coin_id\":[\"ethereum\",\"bitcoin\"],\"vs_currencies\":[\"usd\",\"eur\"],\"action\":\"set_tokens\"}"
}
```
**Response:**
```json highlight={4} theme={null}
{
"c": "C1",
"i": "ethereum",
"vs": "usd",
"m": 312938652962.8005,
"p": 2591.080889351465,
"pp": 1.3763793110454519,
"t": 1747808150.269067,
"v": 20460612214.801384
}
```
***
## `interval=hourly` Now Available for All Plans on Coin Market Chart Endpoints
🗓️ **March 24, 2026**
`interval=hourly` is now accessible to all API users (Demo, Basic, Analyst & above) on:
* [/coins/\{id}/market\_chart](/reference/coins-id-market-chart) — hourly data up to the **past 100 days**
* [/coins/\{id}/market\_chart/range](/reference/coins-id-market-chart-range) — hourly data up to **any 100-day** range per request
Previously restricted to Enterprise subscribers. The `interval=5m` parameter remains Enterprise-only.
***
## GT Verified Badge & Outstanding Token Value for Coin Endpoints
🗓️ **March 23, 2026**
### New `gt_verified` Field
New `gt_verified` boolean field on [Token Info by Token Address](/reference/token-info-contract-address) and [Pool Tokens Info by Pool Address](/reference/pool-token-info-contract-address). [Learn more about GT Verified →](https://support.coingecko.com/hc/en-us/articles/54413671274649-What-is-GT-Verified-Badge)
```json Example Payload highlight={4} theme={null}
{
...
"gt_score": 92.6605504587156,
"gt_verified": true,
"discord_url": null,
...
}
```
### New `outstanding_token_value_usd` & `outstanding_supply` Fields
Two new fields in `market_data` for [Coin Data by ID](/reference/coins-id) and [Coin Data by Token Address](/reference/coins-contract-address):
* `outstanding_token_value_usd` — outstanding token value in USD (nullable)
* `outstanding_supply` — tokens outstanding in the market, including circulated/tradable or planned-for-circulation tokens (nullable)
```json Example Payload highlight={3,7} theme={null}
"market_data": {
"market_cap_rank": 1,
"outstanding_token_value_usd": null,
...
"circulating_supply": 19675962,
"total_supply": 21000000,
"outstanding_supply": 20003043.0,
...
}
```
## Comprehensive Token Holder Analytics with PnL Details
🗓️ **February 25, 2026**
[Top Token Holders by Token Address](/reference/top-token-holders-token-address) now supports `include_pnl_details=true` to return PnL metrics and trading analytics for each holder:
* `average_buy_price_usd` — average purchase price per token
* `total_buy_count` / `total_sell_count` — transaction counts
* `unrealized_pnl_usd` / `unrealized_pnl_percentage` — unrealized P\&L
* `realized_pnl_usd` / `realized_pnl_percentage` — realized P\&L
* `explorer_url` — link to the holder's address on the blockchain explorer
```json Example Payload expandable highlight={15-22} theme={null}
{
"data": {
"id": "base_0x6921b130d297cc43754afba22e5eac0fbf8db75b",
"type": "top_holder",
"attributes": {
"last_updated_at": "2026-02-16T09:56:34.328Z",
"holders": [
{
"rank": 1,
"address": "0x56bbe4200fdd412854bcf05f2c992827b64ee5c1",
"label": null,
"amount": "9703812154.0",
"percentage": "14.3507",
"value": "966572.07",
"average_buy_price_usd": null,
"total_buy_count": null,
"total_sell_count": null,
"unrealized_pnl_usd": null,
"unrealized_pnl_percentage": null,
"realized_pnl_usd": null,
"realized_pnl_percentage": null,
"explorer_url": "https://basescan.org/address/0x56bbe4200fdd412854bcf05f2c992827b64ee5c1"
},
```
***
## Enhanced Pool Discovery and Treasury Analytics with New Sorting and Holdings Metrics
🗓️ **February 12, 2026**
### New Sort Options for Megafilter
[Megafilter for Pools](/reference/pools-megafilter) now supports four new sort options: `price_asc`, `price_desc`, `h24_tx_count_asc`, `h24_volume_usd_asc`
### Enriched Treasury Holdings Data
[Crypto Treasury Holdings by Entity ID](/reference/public-treasury-entity) now returns additional financial metrics by default:
* `total_treasury_value_usd`, `unrealized_pnl`, `m_nav`, `total_asset_value_per_share_usd`
* Per-holding: `amount_per_share`, `entity_value_usd_percentage`, `current_value_usd`, `total_entry_value_usd`, `average_entry_value_usd`, `unrealized_pnl`
```json Example Payload expandable highlight={9-12,18-23} theme={null}
{
"name": "Strategy",
"id": "strategy",
"type": "company",
"symbol": "MSTR.US",
"country": "US",
"website_url": "https://www.strategy.com/",
"twitter_screen_name": "Strategy",
"total_treasury_value_usd": 48119580010.663155,
"unrealized_pnl": -6554973853.336845,
"m_nav": 0.99,
"total_asset_value_per_share_usd": 150.46302495438903,
"holdings": [
{
"coin_id": "bitcoin",
"amount": 714644.0,
"percentage_of_total_supply": 3.403,
"amount_per_share": 0.0022345892873893874,
"entity_value_usd_percentage": 100.0,
"current_value_usd": 48119580010.663155,
"total_entry_value_usd": 54674553864.0,
"average_entry_value_usd": 76506.0,
"unrealized_pnl": -6554973853.336845
}
]
}
```
**New optional parameters for historical tracking:**
* `holding_amount_change` — absolute holding changes over time
* `holding_change_percentage` — percentage changes in holdings
* Supported timeframes: `7d`, `14d`, `30d`, `90d`, `1y`, `ytd` (comma-separated)
```json Example Payload expandable highlight={14-29} theme={null}
...
"total_asset_value_per_share_usd": 150.46302495438903,
"holdings": [
{
"coin_id": "bitcoin",
"amount": 714644.0,
"percentage_of_total_supply": 3.403,
"amount_per_share": 0.0022345892873893874,
"entity_value_usd_percentage": 100.0,
"current_value_usd": 48119580010.663155,
"total_entry_value_usd": 54674553864.0,
"average_entry_value_usd": 76506.0,
"unrealized_pnl": -6554973853.336845,
"holding_amount_change": {
"7d": 1142.0,
"14d": 1997.0,
"30d": 27234.0,
"90d": 72952.0,
"1y": 235904.0,
"ytd": 42144.0
},
"holding_change_percentage": {
"7d": 0.16,
"14d": 0.28,
"30d": 3.962,
"90d": 11.369,
"1y": 49.276,
"ytd": 6.267
}
}
]
}
```
## \[Upcoming Change] Starknet Address Format Update
🗓️ **January 30, 2026**
**Effective February 10, 2026, 02:00 UTC** — Starknet addresses (tokens and pools) are being standardized to the **padded format** (66 characters). This only affects onchain API endpoints and onchain WebSocket channels.
| Feature | Change |
| :--------------- | :-------------------------------------------------------- |
| API Responses | All address fields return in **padded format** (`0x0...`) |
| API Requests | Both padded and unpadded formats accepted |
| WebSockets | Broadcasted messages use **padded format** |
| WS Subscriptions | Both padded and unpadded formats accepted |
### Padded vs. Unpadded
* **Unpadded:** `0x4718...` (65 characters)
* **Padded:** `0x04718...` (66 characters)
### Impact
* **API requests** continue to work with unpadded addresses — the system normalizes inputs automatically
* **String matching** — if your app performs strict comparisons, normalize addresses to a consistent length before comparing
* **Data storage** — future records will include the padding
> This change is specific to **Starknet**. Address formats for other chains remain unaffected.
***
## Streamlined Notification Management with Multi-Recipient Email Alerts
🗓️ **January 27, 2026**
Account owners can now add multiple email recipients for billing alerts and usage threshold notifications from the [Notifications](https://www.coingecko.com/en/developers/dashboard#notifications) dashboard tab. Recipients don't need CoinGecko accounts.
**Available on:** Analyst plans and above (expanded recipient limits for Enterprise). [Learn more →](https://support.coingecko.com/hc/en-us/articles/54516497903129-How-to-Manage-API-Email-Recipients)
***
## Enhanced Team Collaboration with Role-Based Dashboard Access
🗓️ **January 26, 2026**
Invite team members to collaborate on your API subscription via the [Access](https://www.coingecko.com/en/developers/dashboard#access) dashboard tab — no shared login credentials needed. Collaborators can:
* Manage API keys
* Monitor credit usage across API and WebSocket
* Access billing details from the Stripe portal
A dashboard switcher lets users toggle between multiple team views.
**Available on:** All plans (increased seat limits for higher tiers).
**Learn more:**
* [How to Manage Team Access on Your API Dashboard](https://support.coingecko.com/hc/en-us/articles/54503844273945-How-to-Manage-Team-Access-on-Your-API-Dashboard)
* [Team Access for API Plans FAQ](https://support.coingecko.com/hc/en-us/articles/54503941840025-Team-Access-for-API-Plans-FAQ)
***
## Advanced Filtering with Pagination for Treasury Data and Price Change Filters for Megafilter
🗓️ **January 22, 2026**
### Pagination and Sorting for Public Treasury
[Crypto Treasury Holdings by Coin ID](/reference/companies-public-treasury) now supports:
* `per_page` — results per page (1–250, default: 250)
* `page` — paginate through results (default: 1)
* `order` — `total_holdings_usd_desc` (default) or `total_holdings_usd_asc`
### Price Change Filters for Megafilter
[Megafilter for Pools](/reference/pools-megafilter) now supports filtering by price change percentage:
* `price_change_percentage_min` — minimum threshold
* `price_change_percentage_max` — maximum threshold
* `price_change_percentage_duration` — time window: `5m`, `1h`, `6h`, `24h`
***
## Enhanced Market Analytics with Volume Change Tracking and Historical OHLC for Inactive Coins
🗓️ **January 21, 2026**
### Volume Change Percentage for Global Market Data
New `volume_change_percentage_24h_usd` field in [Crypto Global Market Data](/reference/crypto-global):
```json Example Payload highlight={3} theme={null}
{
"market_cap_change_percentage_24h_usd": 0.7227196786856437,
"volume_change_percentage_24h_usd": -0.2692391926571914,
"updated_at": 1769062741
}
```
### Historical OHLC for Inactive Coins
Historical candlestick data is now available for inactive and delisted coins:
* [Coin OHLC by ID](/reference/coins-id-ohlc)
* [Coin OHLC Range by ID](/reference/coins-id-ohlc-range)
***
## Expanded WebSocket Streaming with New Intervals and Quote Token Data
🗓️ **January 20, 2026**
### New Intervals for OnchainOHLCV
[OnchainOHLCV](/websocket/onchainohlcv) now supports three new intervals: `15m`, `12h`, `1d`
Complete interval options: `1s`, `1m`, `5m`, `15m`, `1h`, `2h`, `4h`, `8h`, `12h`, `1d`
### Quote Token Amount for OnchainTrade
New `toq` (quote\_token\_amount) field in [OnchainTrade](/websocket/onchaintrade) — the amount of quote token transacted in each swap:
```json Example Payload highlight={7} theme={null}
{
"c": "G2",
"n": "bsc",
"pa": "0x172fcd41e0913e95784454622d1c3724f546f849",
"ty": "b",
"to": 11.0818733869477,
"toq": 0.0124384489204242,
"vo": 11.0724584599832,
"tx": "0xbc6afc1584fcbef90efe69b96602ef3ba4778727bacfdfece46bbbb075721bb4"
}
```
***
## Breaking Change: Ticker Trust Score Deprecation
🗓️ **January 19, 2026**
**Effective March 3, 2026** — the `trust_score` field (previously `green`, `yellow`, or `red`) now returns `null` across all affected endpoints:
* [Coin Tickers by ID](/reference/coins-id-tickers)
* [Exchange Tickers by ID](/reference/exchanges-id-tickers)
* [Exchange Data by ID](/reference/exchanges-id)
* [Coin Data by ID](/reference/coins-id)
* [Coin Data by Token Address](/reference/coins-contract-address)
```json Example Payload highlight={4} theme={null}
"trust_score": null,
"bid_ask_spread_percentage": 0.010014,
"timestamp": "2024-04-08T04:02:01+00:00",
```
If your application relies on `trust_score`, update your code to handle `null` values.
## Access Inactive Token Data with New `include_inactive_source` Parameter
🗓️ **December 16, 2025**
New `include_inactive_source` query parameter for retrieving data on tokens with no active pools (no valid swaps in the past 7 days). When set to `true`, the API sources data from the pool with the most recent swap, regardless of age.
**Updated endpoints:**
* [Token Data by Token Address](/reference/token-data-contract-address) and [Tokens Data by Token Addresses](/reference/tokens-data-contract-addresses) — new `last_trade_timestamp` field:
```json Example Payload highlight={2} theme={null}
"market_cap_usd": "1544052409.96629",
"last_trade_timestamp": 1712534400
```
* [Top Pools by Token Address](/reference/top-pools-contract-address) — new `last_trade_timestamp` field:
```json Example Payload highlight={2} theme={null}
"reserve_in_usd": "163988541.3812",
"last_trade_timestamp": 1712534400
```
* [Token Price by Token Addresses](/reference/onchain-simple-price) — new `last_trade_timestamp` object:
```json Example Payload highlight={4-6} theme={null}
"total_reserve_in_usd": {
"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2": "1576179559.946697"
},
"last_trade_timestamp": {
"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2": 1712534400
}
```
* [Token OHLCV Chart by Token Address](/reference/token-ohlcv-token-address) — no payload changes
***
## Upcoming Changes to Market Cap Rankings and API for Rehypothecated Tokens
🗓️ **December 15, 2025**
Changes to how rehypothecated tokens (wrapped assets, liquid staking tokens) are ranked in market cap data. [Read the full announcement →](https://www.coingecko.com/learn/upcoming-changes-to-market-cap-rankings-and-api-for-rehypothecated-tokens)
**Effective February 4, 2026.** If your application does not handle rehypothecated tokens specifically, no action is required.
### Coin Data by ID and Coin Data by Token Address
[/coins/\{id}](/reference/coins-id) and [/coins/\{id}/contract/\{contract\_address}](/reference/coins-contract-address):
* **Breaking:** `market_cap_rank` returns `null` for rehypothecated tokens
* **New field:** `market_cap_rank_with_rehypothecated` — available in both the parent object and `market_data`
```json Example Payload highlight={3,7} theme={null}
{
"market_cap_rank": 1,
"market_cap_rank_with_rehypothecated": 1,
"market_data": {
...
"market_cap_rank": 1,
"market_cap_rank_with_rehypothecated": 1,
"fully_diluted_valuation": { ... }
}
}
```
### Coins List with Market Data
[/coins/markets](/reference/coins-markets):
* **Breaking:** Rehypothecated tokens are **excluded by default** (when using `category`, they're included but `market_cap_rank` returns `null`)
* **New parameter:** `include_rehypothecated` (boolean, default: `false`)
* **New field (conditional):** `market_cap_rank_with_rehypothecated` — only present when `include_rehypothecated=true`
```json Example Payload highlight={4} theme={null}
{
"market_cap_rank": 1,
"last_updated": "2026-02-05T08:44:05.527Z",
"market_cap_rank_with_rehypothecated": 1
}
```
***
## New Top Traders by Token Address Endpoint
🗓️ **December 4, 2025**
[Top Traders by Token Address](/reference/top-token-traders-token-address) — monitor whale activity, track significant holders, and analyze trading patterns for any token.
```json Example Payload expandable theme={null}
{
"data": {
"id": "base_0x6921b130d297cc43754afba22e5eac0fbf8db75b",
"type": "top_trader",
"attributes": {
"traders": [
{
"address": "0xf748879edbe8cca140940788163d7be4d2a2e46a",
"name": "@zimagetsfox",
"label": "zimagetsfox.eth",
"type": "other",
"realized_pnl_usd": "1157358.77",
"unrealized_pnl_usd": "255071.37",
"token_balance": "1454984.43",
"average_buy_price_usd": "0.01144",
"average_sell_price_usd": "0.03460",
"total_buy_count": 48,
"total_sell_count": 109,
"total_buy_token_amount": "51422264.86",
"total_sell_token_amount": "49967280.42",
"total_buy_usd": "588308.47",
"total_sell_usd": "1729021.16",
"explorer_url": "https://etherscan.io/address/0xf748879edbe8cca140940788163d7be4d2a2e46a"
}
]
}
}
}
```
## New Public Treasury Endpoints: Historical Holdings and Transactions History
🗓️ **November 27, 2025**
Two new treasury endpoints — both support ID lookup via entity or coin IDs. See live data at [coingecko.com/en/treasuries/companies/strategy](https://www.coingecko.com/en/treasuries/companies/strategy).
### Historical Holdings Chart
[Crypto Treasury Holdings Historical Chart Data by ID](/reference/public-treasury-entity-chart) — query historical holdings for public companies and governments.
```json Example Payload theme={null}
{
"holdings": [
[1763683200000, 649870.0],
...
],
"holding_value_in_usd": [
[1763683200000, 56311217680.033195],
...
]
}
```
### Transaction History
[Crypto Treasury Transaction History by Entity ID](/reference/public-treasury-transaction-history) — retrieve detailed transaction history.
```json Example Payload expandable theme={null}
{
"transactions": [
{
"date": 1763337600000,
"source_url": "https://assets.contentstack.io/v3/assets/.../form-8-k_11-17-2025.pdf",
"coin_id": "bitcoin",
"type": "buy",
"holding_net_change": 8178.0,
"transaction_value_usd": 835554438.0,
"holding_balance": 649870.0,
"average_entry_value_usd": 102171.0
}
]
}
```
***
## GT Community Data for More Pool Endpoints, plus Farcaster and Zora Social URL Support
🗓️ **November 15, 2025**
### GT Community Data for More Pool Endpoints
Flag `include_gt_community_data=true` to receive sentiment voting and community reporting data:
```json Example Payload highlight={2-4} theme={null}
"reserve_in_usd": "163988541.3812",
"sentiment_vote_positive_percentage": 60,
"sentiment_vote_negative_percentage": 40,
"community_sus_report": 18
```
Improved endpoints:
* [Trending Pools List](/reference/trending-pools-list)
* [New Pools by Network](/reference/latest-pools-network)
* [Trending Pools by Network](/reference/trending-pools-network)
* [Top Pools by Network](/reference/top-pools-network)
* [Top Pools by DEX](/reference/top-pools-dex)
* [New Pools List](/reference/latest-pools-list)
### Farcaster and Zora Social URLs
`farcaster_url` and `zora_url` fields are now included by default in token info endpoints:
```json Example Payload highlight={2-3} theme={null}
"discord_url": null,
"farcaster_url": null,
"zora_url": null,
"telegram_handle": null,
```
* [Token Info by Token Address](/reference/token-info-contract-address)
* [Pool Tokens Info by Pool Address](/reference/pool-token-info-contract-address)
***
## True Real-Time Data Update: Cache Removed for Key On-chain Endpoints
🗓️ **November 14, 2025**
> Applicable to all [paid plan](https://www.coingecko.com/en/api/pricing) subscribers.
The 10-second edge cache has been **completely removed** for the following endpoints — requests now return data directly from origin with zero cache delay:
| Effective From | Endpoints |
| :--------------- | :------------------------------------------------------------------------------- |
| December 1, 2025 | [Token Price by Token Addresses](/reference/onchain-simple-price) |
| December 2, 2025 | [Past 24 Hour Trades by Pool Address](/reference/pool-trades-contract-address) |
| December 3, 2025 | [Past 24 Hour Trades by Token Address](/reference/token-trades-contract-address) |
Requests that hit the origin server may use additional credits. To avoid extra credit usage, maintain a polling interval of 10 seconds or more.
***
## Onchain OHLCV Support Extended to Pools with 3+ Tokens
🗓️ **November 8, 2025**
Onchain OHLCV endpoints now support pools with more than 2 tokens — e.g. [crvUSD/WETH/CRV](https://www.geckoterminal.com/eth/pools/0x4ebdf703948ddcea3b11f675b4d1fba9d2414a14).
* [Pool OHLCV Chart by Pool Address](/reference/pool-ohlcv-contract-address)
* [Token OHLCV Chart by Token Address](/reference/token-ohlcv-token-address)
## WebSocket is now supported for Self-serve API subscribers
🗓️ **October 23, 2025**
### WebSocket (Beta) for Paid Plan Subscribers
Self-serve customers (Analyst, Lite, Pro, Pro+) can now stream real-time data via [WebSocket](/websocket) using monthly API plan credits:
* **Max connections:** 10 concurrent sockets
* **Max subscriptions:** 100 token or pool subscriptions per channel, per socket
* **Channel access:** [all 4 channels](/websocket#channel-%26-data-support)
* **Credit charge:** 0.1 credit per response
### Notice: Temporary MagicEden NFT Data Disruption
Due to MagicEden API updates, NFT data endpoints may temporarily return incomplete data while the integration is updated.
***
## More Bonding Curve Support and New Ascending Sort for Megafilter
🗓️ **October 4, 2025**
### Bonding Curve Data for More Endpoints
Bonding curve (launchpad graduation) data is now available on token endpoints:
* [Token Data by Token Address](/reference/token-data-contract-address)
* [Tokens Data by Token Addresses](/reference/tokens-data-contract-addresses)
* [Token Info by Token Address](/reference/token-info-contract-address)
* [Pool Tokens Info by Pool Address](/reference/pool-token-info-contract-address)
```json Example Payload theme={null}
"launchpad_details": {
"graduation_percentage": 2.16,
"completed": false,
"completed_at": null,
"migrated_destination_pool_address": null
}
```
### Megafilter: Ascending Sort for Price Change %
[Megafilter for Pools](/reference/pools-megafilter) now supports ascending sort options: `m5_price_change_percentage_asc`, `h1_price_change_percentage_asc`, `h6_price_change_percentage_asc`, `h24_price_change_percentage_asc`
### Token OHLCV: Bug Fix
Fixed an issue where [Token OHLCV Chart by Token Address](/reference/token-ohlcv-token-address) returned data for the base token of the top pool instead of the requested token.
## SDK Gains Public Treasury Coverage, MCP Adds Exchanges, NFTs, and ISO Support
🗓️ **September 25, 2025**
### Expanded SDK Coverage for Public Treasuries
New functions in the [TypeScript SDK](https://github.com/coingecko/coingecko-typescript):
* [`publicTreasury.getCoinID(coinID, { ...params })`](https://github.com/coingecko/coingecko-typescript/blob/main/api.md#publictreasury) — query holdings by Coin ID
* [`publicTreasury.getEntityID(entityID)`](https://github.com/coingecko/coingecko-typescript/blob/main/api.md#publictreasury) — query holdings by Entity ID
* [`entities.getList({ ...params })`](https://github.com/coingecko/coingecko-typescript/blob/main/api.md#entities) — list all supported entities with ID, name, symbol, and country
### New MCP Tools: Exchanges, NFTs & Multi-Address Queries
New tools:
* Exchange coverage: [/exchanges/list](/reference/exchanges-list), [/exchanges/\{id}](/reference/exchanges-id), [/exchanges/\{id}/tickers](/reference/exchanges-id-tickers), [/exchanges/\{id}/volume\_chart/range](/reference/exchanges-id-volume-chart-range)
* NFT markets: [/nfts/markets](/reference/nfts-markets)
* Multi-address queries: [/onchain/networks/\{network}/pools/multi/\{addresses}](/reference/pools-addresses), [/onchain/networks/\{network}/tokens/multi/\{addresses}](/reference/tokens-data-contract-addresses)
Retired tools:
* Removed [/coins/list](/reference/coins-list), [/onchain/networks/trending\_pools](/reference/trending-pools-network), and single-address pool/token queries in favor of multi-address endpoints
### MCP: ISO Date String Support
MCP tools now accept **ISO date strings** (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM`) alongside UNIX timestamps — no more manual conversion for time-based queries like [Coin Historical Chart Data within Time Range](/reference/coins-id-market-chart-range).
***
## New Crypto Treasury Endpoints and Improvements
🗓️ **September 19, 2025**
1. [Crypto Treasury Holdings by Coin ID](/reference/companies-public-treasury) now supports governments and more coins — see [coingecko.com/en/treasuries/bitcoin](https://www.coingecko.com/en/treasuries/bitcoin)
2. **New endpoints:**
* [Crypto Treasury Holdings by Entity ID](/reference/public-treasury-entity)
* [Entities List (ID Map)](/reference/entities-list)
3. [Derivatives Exchange Data by ID](/reference/derivatives-exchanges-id) now supports `coin_id` and `target_coin_id` to identify coins of ticker pairs:
```json Example Payload highlight={6-7} theme={null}
"tickers": [
{
"symbol": "ASTERUSDT",
"base": "ASTER",
"target": "USDT",
"coin_id": "aster-2",
"target_coin_id": "tether"
}
]
```
***
## Multiple Improvements: Bonding Curve Data, Pooled Token Balance, and More
🗓️ **September 12, 2025**
### Bonding Curve Data
Launchpad graduation data is now available on [Specific Pool Data by Pool Address](/reference/pool-address) and [Multiple Pools Data by Pool Addresses](/reference/pools-addresses):
```json Example Payload theme={null}
"launchpad_details": {
"graduation_percentage": 100,
"completed": true,
"completed_at": "2024-04-08T16:52:35Z",
"migrated_destination_pool_address": "5wNu5QhdpRGrL37ffcd6TMMqZugQgxwafgz477rShtHy"
}
```
### Pooled Token Balance Data
Flag `include_composition=true` to get pool token balance breakdowns:
* [Specific Pool Data by Pool Address](/reference/pool-address)
* [Multiple Pools Data by Pool Addresses](/reference/pools-addresses)
* [Token Data by Token Address](/reference/token-data-contract-address) (also requires `include=top_pools`)
* [Tokens Data by Token Addresses](/reference/tokens-data-contract-addresses) (also requires `include=top_pools`)
```json Example Payload theme={null}
"base_token_balance": "11700.98",
"base_token_liquidity_usd": "29630000",
"quote_token_balance": "66384614.21",
"quote_token_liquidity_usd": "66330000",
```
### Other Improvements
* [Megafilter for Pools](/reference/pools-megafilter) — new `sort` options: `m5_price_change_percentage_desc`, `h1_price_change_percentage_desc`, `h6_price_change_percentage_desc`, `fdv_usd_asc`, `fdv_usd_desc`, `reserve_in_usd_asc`, `reserve_in_usd_desc`
* [Top Gainers & Losers](/reference/coins-top-gainers-losers) — new `price_change_percentage` parameter with options: `1h`, `24h`, `7d`, `14d`, `30d`, `60d`, `200d`, `1y`
```json Example Payload theme={null}
"usd_1y_change": 21740.8866287307,
"usd_1h_change": -0.279590756868549,
"usd_24h_change": 3.13876587906131,
"usd_7d_change": -9.67782096261206,
"usd_14d_change": -3.39755498745517,
"usd_30d_change": -13.7768698159765,
"usd_60d_change": 29.9096824213076,
"usd_200d_change": 2282.33681679488
```
* [Exchange Tickers by ID](/reference/exchanges-id-tickers) — new `order` options: `market_cap_desc`, `market_cap_asc`
## Improved Update Frequency for selected Pro-API On-chain Endpoints
🗓️ **August 18, 2025**
> Applicable to all [paid plan](https://www.coingecko.com/en/api/pricing) subscribers.
Edge cache durations for the following onchain endpoints have been reduced from 30s to **10s**:
| Effective From | Endpoints |
| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| September 2, 2025 | [Token Price by Token Addresses](/reference/onchain-simple-price)
[Token Data by Token Address](/reference/token-data-contract-address)
[Tokens Data by Token Addresses](/reference/tokens-data-contract-addresses) |
| September 3, 2025 | [Specific Pool Data by Pool Address](/reference/pool-address)
[Multiple Pools Data by Pool Addresses](/reference/pools-addresses) |
| September 4, 2025 | [Pool OHLCV Chart by Pool Address](/reference/pool-ohlcv-contract-address)
[Token OHLCV Chart by Token Address](/reference/token-ohlcv-token-address)
[Past 24 Hour Trades by Pool Address](/reference/pool-trades-contract-address)
[Past 24 Hour Trades by Token Address](/reference/token-trades-contract-address) |
Cached responses incur no extra credits. Requests that bypass the cache and hit the origin server may use additional credits — adjust your polling interval accordingly.
***
## Now Supported: Launchpad Data (Pump.fun & More), Granular OHLCV, and Honeypot Info
🗓️ **August 5, 2025**
### Launchpad Data (Pump.fun & More)
Token data from popular launchpad platforms is now available through the API:
| Launchpad | Network | DEX ID |
| :---------------------------------------------------------------------------------------------- | :------ | :------------------ |
| [Meteora DBC](https://www.geckoterminal.com/solana/meteora-dbc/pools) | solana | `meteora-dbc` |
| [Pump.fun](https://www.geckoterminal.com/solana/pump-fun/pools) | solana | `pump-fun` |
| [Raydium Launchpad](https://www.geckoterminal.com/solana/raydium-launchlab/pools) (LetsBonkFun) | solana | `raydium-launchlab` |
| [Boop.fun](https://www.geckoterminal.com/solana/boop-fun/pools) | solana | `boop-fun` |
| [Virtuals (Base)](https://www.geckoterminal.com/base/virtuals-base/pools) | base | `virtuals-base` |
Improved endpoints:
* [Token Data by Token Address](/reference/token-data-contract-address)
* [Tokens Data by Token Addresses](/reference/tokens-data-contract-addresses)
* [Specific Pool Data by Pool Address](/reference/pool-address)
* [Multiple Pools Data by Pool Addresses](/reference/pools-addresses)
**Tip:** Use [Megafilter for Pools](/reference/pools-megafilter) with `sort=pool_created_at_desc` to retrieve the latest launchpad pools.
```bash wrap theme={null}
https://pro-api.coingecko.com/api/v3/onchain/pools/megafilter?page=1&networks=solana&dexes=pump-fun&sort=pool_created_at_desc&x_cg_pro_api_key=YOUR_KEY
```
### Granular OHLCV Data
Onchain OHLCV endpoints now support sub-minute intervals down to 1-second granularity:
| Timeframe | Aggregates |
| :-------- | :------------------ |
| day | 1 |
| hour | 1, 4, 12 |
| minute | 1, 5, 15 |
| second | **1, 15, 30** (new) |
Improved endpoints:
* [Pool OHLCV Chart by Pool Address](/reference/pool-ohlcv-contract-address)
* [Token OHLCV Chart by Token Address](/reference/token-ohlcv-token-address)
> Paid plan subscribers (Analyst & above) only.
```bash wrap theme={null}
https://pro-api.coingecko.com/api/v3/onchain/networks/eth/pools/0x06da0fd433c1a5d7a4faa01111c044910a184553/ohlcv/second?aggregate=1&limit=100&x_cg_pro_api_key=YOUR_KEY
```
### Honeypot Detection
[Token Info by Token Address](/reference/token-info-contract-address) and [Pool Tokens Info by Pool Address](/reference/pool-token-info-contract-address) now include `is_honeypot` (values: `true`, `false`, or `unknown`):
```json Example Payload theme={null}
{
"mint_authority": null,
"freeze_authority": null,
"is_honeypot": true
}
```
### Megafilter: Include Unknown Honeypot Tokens
[Megafilter for Pools](/reference/pools-megafilter) now supports `include_unknown_honeypot_tokens=true` to include tokens with unknown honeypot status. Only takes effect when `checks=no_honeypot` is also specified.
```bash wrap theme={null}
https://pro-api.coingecko.com/api/v3/onchain/pools/megafilter?page=1&sort=h6_trending&checks=no_honeypot&include_unknown_honeypot_tokens=true&x_cg_pro_api_key=YOUR_KEY
```
### Pool Tokens Info: Expanded Pool Data
[Pool Tokens Info by Pool Address](/reference/pool-token-info-contract-address) now supports `include=pool` to retrieve pool context:
* Base and quote token addresses
* Sentiment vote percentages (positive/negative)
* Community suspicious reports count
```json Example Payload expandable theme={null}
"included": [
{
"id": "eth_0x06da0fd433c1a5d7a4faa01111c044910a184553",
"type": "pool",
"attributes": {
"base_token_address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
"quote_token_address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
"sentiment_vote_positive_percentage": 100,
"sentiment_vote_negative_percentage": 0,
"community_sus_report": 0
}
}
]
```
## SOL Currency Is Now Supported for CoinGecko Endpoints
🗓️ **June 19, 2025**
Real-time and historical price and market data can now be returned in **SOL** (Solana) currency across the following endpoints:
* [Coin Price by IDs](/reference/simple-price)
* [Coin Price by Token Addresses](/reference/simple-token-price)
* [Supported Currencies List](/reference/simple-supported-currencies)
* [Top Gainers & Losers](/reference/coins-top-gainers-losers)
* [Coins List with Market Data](/reference/coins-markets)
* [Coin Data by ID](/reference/coins-id)
* [Coin Historical Data by ID](/reference/coins-id-history)
* [Coin Historical Chart Data by ID](/reference/coins-id-market-chart)
* [Coin Historical Chart Data within Time Range by ID](/reference/coins-id-market-chart-range)
* [Coin OHLC Chart by ID](/reference/coins-id-ohlc)
* [Coin OHLC Chart within Time Range by ID](/reference/coins-id-ohlc-range)
* [Coin Data by Token Address](/reference/coins-contract-address)
* [Coin Historical Chart Data by Token Address](/reference/contract-address-market-chart)
* [Coin Historical Chart Data within Time Range by Token Address](/reference/contract-address-market-chart-range)
* [Trending Search List](/reference/trending-search)
* [Crypto Global Market Data](/reference/crypto-global)
> For dates prior to May 2025, SOL historical data is limited to hourly and daily granularity.
**Example** — price of Bitcoin in SOL:
```json theme={null}
{
"bitcoin": {
"sol": 720.21
}
}
```
**Example** — historical daily data of Trump in SOL:
```json expandable theme={null}
{
"prices": [
[1750118400000, 0.0640701365814472],
[1750204800000, 0.0644263929356261],
[1750291200000, 0.0639713357587322]
],
"market_caps": [
[1750118400000, 12843589.584485611],
[1750204800000, 12882547.839086628],
[1750291200000, 12793790.726102708]
],
"total_volumes": [
[1750118400000, 2425793.780846796],
[1750204800000, 2055697.9106767387],
[1750291200000, 1871087.4334618242]
]
}
```
***
## New Endpoints & Improvements: Historical Token Holders Chart, OHLCV by Token Address, Multi-pool Token Data Support
🗓️ **June 9, 2025**
### New Endpoint: Historical Token Holders Chart
[Historical Token Holders Chart by Token Address](/reference/token-holders-chart-token-address) — get the historical token holders chart for a token on a network.
**Supported chains:** Solana, EVM (Ethereum, Polygon, BNB, Arbitrum, Optimism, Base), Sui, TON, Ronin
> Paid plan subscribers (Analyst & above) only.
### New Endpoint: Token OHLCV by Token Address
[Token OHLCV Chart by Token Address](/reference/token-ohlcv-token-address) — get OHLCV data for a token based on its most liquid pool. Use [Top Pools by Token Address](/reference/top-pools-contract-address) to check which pool is used.
> Paid plan subscribers (Analyst & above) only.
### Multi-pool Token Data Support
For pools with 3+ tokens, extra quote tokens are now listed under `relationships.quote_tokens`. If `include=quote_token` is flagged, the extra tokens also appear under `included`.
```json Example Payload expandable highlight={14-25} theme={null}
"relationships": {
"base_token": {
"data": {
"id": "eth_0x40d16fc0246ad3160ccc09b8d0d3a2cd28ae6c2f",
"type": "token"
}
},
"quote_token": {
"data": {
"id": "eth_0x8353157092ed8be69a9df8f95af097bbf33cb2af",
"type": "token"
}
},
"quote_tokens": {
"data": [
{
"id": "eth_0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"type": "token"
},
{
"id": "eth_0xdac17f958d2ee523a2206206994597c13d831ec7",
"type": "token"
}
]
}
}
```
Applies to all onchain pool endpoints with `relationships.quote_token`, including:
* [Top Pools by Token Address](/reference/top-pools-contract-address)
* [Search Pools](/reference/search-pools)
* [Megafilter for Pools](/reference/pools-megafilter)
* [Trending Pools List](/reference/trending-pools-list)
* [Specific Pool Data by Pool Address](/reference/pool-address)
* [Top Pools by Network](/reference/top-pools-network)
* [New Pools List](/reference/latest-pools-list)
## Upcoming Change Notice: Removal of normalized\_volume\_btc Data
🗓️ **May 30, 2025**
**Effective June 16, 2025** — the `trade_volume_24h_btc_normalized` field has been removed from the following endpoints, due to changes in a third-party data source:
* [Exchange Data by ID](/reference/exchanges-id)
* [Exchanges List with Data](/reference/exchanges)
```json theme={null}
{
"trade_volume_24h_btc_normalized": 47765.5886637453
}
```
If your application relies on `trade_volume_24h_btc_normalized`, update your code to handle its absence.
***
## New Endpoint & Improvements: On-Chain Trades, Net Buy Volume, and More
🗓️ **May 29, 2025**
### New Endpoint: Onchain Trades by Token Address
[Past 24 Hour Trades by Token Address](/reference/token-trades-contract-address) retrieves the last 300 trades **across different pools** for a token, unlike [Past 24 Hour Trades by Pool Address](/reference/pool-trades-contract-address) which is limited to a single pool.
> Paid plan subscribers (Analyst & above) only.
### Net Buy Volume Data
[Specific Pool Data by Pool Address](/reference/pool-address) and [Multiple Pools Data by Pool Addresses](/reference/pools-addresses) now support `include_volume_breakdown=true`, returning:
* `net_buy_volume_usd`
* `buy_volume_usd`
* `sell_volume_usd`
```json Example Payload expandable highlight={6-21} theme={null}
{
"data": {
"id": "eth_0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
"type": "pool",
"attributes": {
"net_buy_volume_usd": {
"m5": "-40796.577553965",
"m15": "-69765.771189161",
"m30": "-88014.095440243",
"h1": "0.000000000000",
"h6": "1884879.921855301",
"h24": "17555422.243003801"
},
"buy_volume_usd": {
"m5": "30597.433165473",
"h24": "52666266.729011402"
},
"sell_volume_usd": {
"m5": "71394.010719438",
"h24": "35110844.486007601"
}
}
}
}
```
### OHLCV: Empty Interval Padding
[Pool OHLCV Chart by Pool Address](/reference/pool-ohlcv-contract-address) now supports `include_empty_intervals=true`. Intervals with no recorded swaps are padded — OHLC values follow the previous close, and volume is set to zero.
```json Example Payload expandable theme={null}
{
"data": {
"id": "81da0682-1c4f-445a-9bed-9b5454004df5",
"type": "ohlcv_request_response",
"attributes": {
"ohlcv_list": [
[
1744712700,
0.000212149802253853,
0.000212173305907688,
0.000212149802253853,
0.000212173305907688,
46.48164903882
],
[
1744712400,
0.000212149802253853, 👈 O — Follow previous Close value
0.000212149802253853, 👈 H — Follow previous Close value
0.000212149802253853, 👈 L — Follow previous Close value
0.000212149802253853, 👈 C — Follow previous Close value
0.0 👈 V — Set to zero
],
[
1744712100,
0.000210532522666822,
0.000212149802253853,
0.000210532522666822,
0.000212149802253853, 👈 Previous Close value
46.4765
]
]
}
}
}
```
### Token Info: Large Image Sizes
[Token Info by Token Address](/reference/token-info-contract-address) and [Pool Tokens Info by Pool Address](/reference/pool-token-info-contract-address) now include an `image` object with `thumb`, `small`, and `large` URLs:
```json Example Payload highlight={5} theme={null}
"image_url": "https://assets.coingecko.com/coins/images/325/small/Tether.png?1696501661",
"image": {
"thumb": "https://assets.coingecko.com/coins/images/325/thumb/Tether.png?1696501661",
"small": "https://assets.coingecko.com/coins/images/325/small/Tether.png?1696501661",
"large": "https://assets.coingecko.com/coins/images/325/large/Tether.png?1696501661"
},
```
### Token Data: Normalized Total Supply
[Token Data by Token Address](/reference/token-data-contract-address) and [Tokens Data by Token Addresses](/reference/tokens-data-contract-addresses) now include `normalized_total_supply`:
```json Example Payload highlight={3} theme={null}
"decimals": 6,
"total_supply": "49999156520373530.0",
"normalized_total_supply": "49999156520.37353",
```
### Pool Data: Pool Name and Fee
[Specific Pool Data by Pool Address](/reference/pool-address) and [Multiple Pools Data by Pool Addresses](/reference/pools-addresses) now include `pool_name` and `pool_fee_percentage`:
```json Example Payload highlight={2-3} theme={null}
"name": "WETH / USDC 0.05%",
"pool_name": "WETH / USDC",
"pool_fee_percentage": "0.05",
```
### DEX Pair Symbols
Flag `dex_pair_format=symbol` to return DEX pair symbols instead of contract addresses on:
* [Coin Data by ID](/reference/coins-id)
* [Coin Tickers by ID](/reference/coins-id-tickers)
* [Exchange Tickers by ID](/reference/exchanges-id-tickers)
* [Exchange Data by ID](/reference/exchanges-id)
**Before:**
```json theme={null}
{
"base": "0X8FC8F8269EBCA376D046CE292DC7EAC40C8D358A",
"target": "0XA0B86991C6218B36C1D19D4A2E9EB0CE3606EB48"
}
```
**After** (`dex_pair_format=symbol`):
```json theme={null}
{
"base": "DFI",
"target": "USDC"
}
```
## New Endpoint & Improvements: On-Chain Trending Data, Enhanced Trending Search, and Improved Token Lookup
🗓️ **April 25, 2025**
### New Endpoint: Onchain Trending Search Data
[Trending Search Pools](/reference/trending-search-pools) returns onchain trending pools and tokens as seen on GeckoTerminal.com. Returns top 4 pools by default — set `pools` to retrieve up to 10.
**Tip:** Flag `include=base_token` to also retrieve trending token data.
> Paid plan subscribers (Analyst & above) only.
### Trending Search List: `show_max` Parameter
[Trending Search List](/reference/trending-search) now supports `show_max` to retrieve more trending results for paid plan subscribers:
| Trending Data | Demo | Analyst & Above |
| :-------------- | :--: | :-------------: |
| Coins | 15 | 30 |
| NFTs | 7 | 10 |
| Coin Categories | 6 | 10 |
### Token Lookup by Symbol and Name
[Coin Price by IDs](/reference/simple-price) and [Coins List with Market Data](/reference/coins-markets) now support token lookup by `symbol` and `name`, in addition to API ID.
| API ID | Symbol | Name |
| :------- | :----- | :------ |
| bitcoin | btc | Bitcoin |
| tether | usdt | Tether |
| usd-coin | usdc | USDC |
**Lookup priority:** `id` (highest) > `name` > `symbol` (lowest).
**Filtering by symbol with `include_tokens`:**
* `include_tokens=top` — returns only the top market cap token for the symbol
* `include_tokens=all` — returns all tokens sharing the symbol
### /coins/markets: Pagination Response Headers
[Coins List with Market Data](/reference/coins-markets) now includes `total` and `per-page` values in the response headers, enabling accurate pagination across all active coins.
```text Response Header (Example) theme={null}
per-page: 250
total: 16989
```
***
## Upcoming Change Notice: Removal of twitter\_followers Data
🗓️ **April 25, 2025**
**Effective May 15, 2025** — the `twitter_followers` field within `community_data` has been removed from the following endpoints, due to changes in the X (formerly Twitter) API:
* [Coin Data by ID](/reference/coins-id)
* [Coin Data by Token Address](/reference/coins-contract-address)
* [Coin Historical Data by ID](/reference/coins-id-history)
```json theme={null}
"community_data": {
"twitter_followers": 7694251
}
```
If your application relies on `twitter_followers`, update your code to handle its absence.
## New Endpoint & Multiple Improvements: On-Chain Top Token Holder Address, Security Data, Historical Supply.
🗓️ **March 28, 2025**
### New Endpoint: Top Token Holder Address Data
Access the top 50 token holder addresses, as seen on GeckoTerminal.com. Returns top 10 by default — set `holders` to retrieve up to 50.
[Top Token Holders by Token Address →](/reference/top-token-holders-token-address)
**Supported networks:** Ethereum, Polygon, BNB, Arbitrum, Optimism, Base, Solana, Sui, TON, Ronin
> Paid plan subscribers (Analyst & above) only. Holders data is in **Beta** — data quality, coverage, and update frequency are being improved. Solana tokens support a maximum of 40 holders.
**Tip:** Use [Token Info by Token Address](/reference/token-info-contract-address) or [Pool Tokens Info by Pool Address](/reference/pool-token-info-contract-address) for **holders count** and **top holders distribution percentage**.
### Historical Supply: Support for Inactive Coins
Historical total and circulating supply data is now available for inactive coins. Use [Coin List (ID Map)](/reference/coins-list) with `status=inactive` to find inactive coin IDs.
> Enterprise plan only.
* [Circulating Supply Chart by ID](/reference/coins-id-circulating-supply-chart)
* [Circulating Supply Chart within Time Range by ID](/reference/coins-id-circulating-supply-chart-range)
* [Total Supply Chart by ID](/reference/coins-id-total-supply-chart)
* [Total Supply Chart within Time Range by ID](/reference/coins-id-total-supply-chart-range)
### Onchain Pool Data: Locked Liquidity
New `locked_liquidity_percentage` field available on:
* [Specific Pool Data by Pool Address](/reference/pool-address)
* [Multiple Pools Data by Pool Addresses](/reference/pools-addresses)
```json Example Payload expandable highlight={17} theme={null}
{
"data": [
{
"id": "eth_0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
"type": "pool",
"attributes": {
"base_token_price_usd": "3653.12491645176",
"base_token_price_native_currency": "1.0",
...
"volume_usd": {
"m5": "868581.7348314",
"h1": "16798158.0138526",
"h6": "164054610.850188",
"h24": "536545444.904535"
},
"reserve_in_usd": "163988541.3812",
"locked_liquidity_percentage": "99.82"
},
```
### Onchain Token Info: GT Score, Mint Authority, Freeze Authority
Token Info endpoints now include security-related fields:
* **GT Score Details** — breakdown by pool, transaction, creation, info, and holders. [Learn more](https://support.coingecko.com/hc/en-us/articles/38381394237593-What-is-GT-Score-How-is-GT-Score-calculated).
* **Mint Authority** and **Freeze Authority**
Improved endpoints:
* [Token Info by Token Address](/reference/token-info-contract-address)
* [Pool Tokens Info by Pool Address](/reference/pool-token-info-contract-address)
```json Example Payload theme={null}
"gt_score": 92.6605504587156,
"gt_score_details": {
"pool": 0,
"transaction": 32.2,
"creation": 0,
"info": 0,
"holders": 0
},
"mint_authority": "no",
"freeze_authority": "no"
```
### Onchain Simple Token Price: Market Cap to FDV Fallback
[Token Price by Token Addresses](/reference/onchain-simple-price) now supports `mcap_fdv_fallback=true` — when a token's market cap is unverified, the `market_cap_usd` field returns the FDV value instead (matching GeckoTerminal.com behavior).
* Unverified tokens return `null` for market cap by default, even if GeckoTerminal shows a value (which may equal FDV)
* Verified market cap is sourced from CoinGecko and may exceed FDV when it includes tokens on other chains
***
## Update Frequency Improvements for selected Pro-API endpoints (March 2025)
🗓️ **March 14, 2025**
> Applicable to [paid plan](https://www.coingecko.com/en/api/pricing) subscribers (Analyst & above) only.
Edge cache durations for the following onchain endpoints have been reduced from 60s to **30s**:
| Effective From | Endpoints |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| March 25, 2025 | [Trending Pools List](/reference/trending-pools-list)
[Trending Pools by Network](/reference/trending-pools-network)
[Top Pools by Network](/reference/top-pools-network)
[Top Pools by DEX](/reference/top-pools-dex) |
| March 26, 2025 | [New Pools by Network](/reference/latest-pools-network)
[New Pools List](/reference/latest-pools-list)
[Megafilter for Pools](/reference/pools-megafilter)
[Search Pools](/reference/search-pools) |
| March 27, 2025 | [Top Pools by Token Address](/reference/top-pools-contract-address)
[Most Recently Updated Tokens List](/reference/tokens-info-recent-updated)
[Pools by Category ID](/reference/pools-category) |
Cached responses incur no extra credits. Requests that bypass the cache and hit the origin server may use additional credits — adjust your polling interval accordingly.
***
## Multiple Improvements: Holders data, Pool Stats, Simple Token Price
🗓️ **March 14, 2025**
### Onchain Token Info: Holders Data (Beta)
New holder fields available:
* `holders.count` — total holder count
* `holders.distribution_percentage` — top 10, 11–20, 21–40, and rest breakdown
Improved endpoints:
* [Token Info by Token Address](/reference/token-info-contract-address)
* [Pool Tokens Info by Pool Address](/reference/pool-token-info-contract-address)
```json Example Payload theme={null}
"holders": {
"count": 1432761,
"distribution_percentage": {
"top_10": "1.3019",
"11_20": "0.1024",
"21_40": "0.095",
"rest": "98.5007"
},
"last_updated": "2025-03-06T01:21:18Z"
```
### Onchain Pool Data: New Intervals
New time intervals for `price_change_percentage`, `volume_usd`, and `transactions`:
* `price_change_percentage`: added `m15`, `m30`
* `volume_usd`: added `m15`, `m30`
* `transactions`: added `h6`
Improved endpoints:
* [Specific Pool Data by Pool Address](/reference/pool-address)
* [Multiple Pools Data by Pool Addresses](/reference/pools-addresses)
```json Example Payload expandable highlight={3-4,34-39,49-50} theme={null}
"price_change_percentage": {
"m5": "0.06",
"m15": "0.06",
"m30": "0.89",
"h1": "-4.31",
"h6": "-1.02",
"h24": "3.32"
},
"transactions": {
"m5": {
"buys": 0,
"sells": 2,
"buyers": 0,
"sellers": 2
},
"m15": {
"buys": 0,
"sells": 2,
"buyers": 0,
"sellers": 2
},
"m30": {
"buys": 0,
"sells": 3,
"buyers": 0,
"sellers": 3
},
"h1": {
"buys": 1,
"sells": 23,
"buyers": 1,
"sellers": 7
},
"h6": {
"buys": 60,
"sells": 38,
"buyers": 23,
"sellers": 18
},
"h24": {
"buys": 206,
"sells": 138,
"buyers": 96,
"sellers": 77
}
},
"volume_usd": {
"m5": "130.5119858698",
"m15": "130.5119858698",
"m30": "177.109036156",
"h1": "4942.2463835639",
"h6": "28362.2127269542",
"h24": "112426.585893123"
}
```
### Onchain Simple Token Price: Liquidity & Price Change
[Token Price by Token Addresses](/reference/onchain-simple-price) now supports two new optional parameters:
* `include_24hr_price_change` — 24h price change percentage
* `include_total_reserve_in_usd` — total liquidity attributable to a token across all pools
```json Example Payload expandable highlight={18-25} theme={null}
{
"data": {
"id": "e58258f7-8368-4968-bbe1-b5343540cd71",
"type": "simple_token_price",
"attributes": {
"token_prices": {
"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": "1.00276143983565",
"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2": "3175.22870146126"
},
"market_cap_usd": {
"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": "25000000000",
"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2": "500000000000"
},
"h24_volume_usd": {
"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": "50000000",
"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2": "10000000000"
},
"h24_price_change_percentage": {
"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": "-0.15",
"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2": "1.15"
},
"total_reserve_in_usd": {
"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": "417994486.4342195821530162288",
"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2": "417994486.4342195821530162288"
}
}
}
}
```
## New Megafilter Endpoint, 200+ Chains Supported: Hyperliquid, Abstract, Berachain & MOAR!
🗓️ **February 27, 2025**
The CoinGecko API now supports onchain data across **200+ blockchain networks**, including Hyperliquid, HyperEVM, Abstract, Berachain, Story, Monad, Unichain, and Soneium.
A new endpoint for slicing and dicing onchain pool data with full flexibility. [Megafilter for Pools →](/reference/pools-megafilter)
* Filter across 200+ networks, 1,400+ DEXes, 6M+ pools, and 5M+ tokens
* Advanced filters by liquidity, FDV, volume, transactions, buy/sell trends, and time range
* Custom sorting — trending pools (5m), newest pools, liquidity growth, and more
* Fraud detection — exclude honeypots, check GT Score, verify CG listings, track social metrics
**Examples:**
* Track fresh pools on Uniswap V4 & Aerodrome with liquidity above \$1,000
* Discover trending DEX pools across Solana, Base, and other chains with a high GT Score
* Filter out risky pools with built-in honeypot protection and fraud checks
> Paid plan subscribers (Analyst & above) only.
***
## Update Frequency Improvements for selected Pro-API endpoints
🗓️ **February 14, 2025**
> Applicable to [paid plan](https://www.coingecko.com/en/api/pricing) subscribers (Analyst & above) only.
Edge cache durations for the following onchain endpoints have been reduced from 60s to **30s**:
| Effective From | Endpoints |
| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
| February 24, 2025 | [/networks/../tokens/](/reference/token-data-contract-address)
[/networks/../tokens/multi/](/reference/tokens-data-contract-addresses) |
| February 25–26, 2025 | [/networks/../pools/../ohlcv](/reference/pool-ohlcv-contract-address) |
Cached responses incur no extra credits. Requests that bypass the cache and hit the origin server may use additional credits — adjust your polling interval accordingly.
***
## Enhanced Onchain Metadata, Increased Max Address Limit for Multi Endpoints, Improved Exchange Tickers Sorting
🗓️ **February 9, 2025**
### Onchain Metadata: Improved Coverage
Metadata coverage (images, websites, description, socials) is now improved for tokens on Solana, TON, Base, and Sui. Tokens without image data now return `null` for `image_url` instead of `missing.png`.
**Endpoints with improved image data:**
* [Trending Pools List](/reference/trending-pools-list)
* [Trending Pools by Network](/reference/trending-pools-network)
* [Specific Pool Data by Pool Address](/reference/pool-address)
* [Multiple Pools Data by Pool Addresses](/reference/pools-addresses)
* [Top Pools by Network](/reference/top-pools-network)
* [Top Pools by DEX](/reference/top-pools-dex)
* [New Pools by Network](/reference/latest-pools-network)
* [New Pools List](/reference/latest-pools-list)
* [Search Pools](/reference/search-pools)
* [Top Pools by Token Address](/reference/top-pools-contract-address)
* [Token Data by Token Address](/reference/token-data-contract-address)
* [Tokens Data by Token Addresses](/reference/tokens-data-contract-addresses)
* [Token Info by Token Address](/reference/token-info-contract-address)
* [Pool Tokens Info by Pool Address](/reference/pool-token-info-contract-address)
* [Most Recently Updated Tokens List](/reference/tokens-info-recent-updated)
**Endpoints with improved full metadata** (images, websites, description, socials):
* [Token Info by Token Address](/reference/token-info-contract-address)
* [Pool Tokens Info by Pool Address](/reference/pool-token-info-contract-address)
* [Most Recently Updated Tokens List](/reference/tokens-info-recent-updated)
> Onchain metadata may be sourced on-chain and is not vetted by CoinGecko. For reviewed metadata, use [Coin Data by ID](/reference/coins-id) or [Coin Data by Token Address](/reference/coins-contract-address).
### Max Address Limit Increased for /multi Endpoints
Onchain `/multi` endpoints now support up to **50** token or pool addresses per request (previously 30):
* [Tokens Data by Token Addresses](/reference/tokens-data-contract-addresses)
* [Multiple Pools Data by Pool Addresses](/reference/pools-addresses)
> Paid plan subscribers (Analyst & above) only.
### Exchange Tickers: New `base_target` Sort Order
[Exchange Tickers by ID](/reference/exchanges-id-tickers) now supports `order=base_target`, which sorts tickers by base symbol then target symbol in lexicographical order. This ensures **stable pagination** — the default `trust_score_desc` sort can cause duplicates or missing tickers when ranks shift between paginated requests.
```bash theme={null}
pro-api.coingecko.com/api/v3/exchanges/binance/tickers?order=base_target
```
## Multiple Improvements: Onchain Pools Page Limit, Trades Token Filter
🗓️ **January 27, 2025**
### Onchain Pools: Pagination Beyond 10 Pages
Paid plan subscribers (Analyst & above) can now access more than 10 pages of pools data on the following endpoints:
* [Search Pools](/reference/search-pools)
* [Top Pools by Token Address](/reference/top-pools-contract-address)
* [Trending Pools List](/reference/trending-pools-list)
* [Trending Pools by Network](/reference/trending-pools-network)
* [New Pools by Network](/reference/latest-pools-network)
* [New Pools List](/reference/latest-pools-list)
* [Top Pools by Network](/reference/top-pools-network)
* [Top Pools by DEX](/reference/top-pools-dex)
### Onchain Trades: Token Filter
[Past 24 Hour Trades by Pool Address](/reference/pool-trades-contract-address) now supports a `token` parameter to filter trades by base or quote token:
* `?token=base` — base token trades only
* `?token=quote` — quote token trades only
* `?token={token_address}` — trades for a specific token address
***
## Multiple Improvements: Onchain Token Price, NFT Market Cap
🗓️ **January 24, 2025**
### Onchain Simple Token Price: Market Cap and 24h Volume
[Token Price by Token Addresses](/reference/onchain-simple-price) now supports `include_market_cap=true` and `include_24hr_vol=true`:
```json Example Payload expandable theme={null}
{
"data": {
"id": "e1979db1-5c3e-4ba8-b103-cb0258af4a7c",
"type": "simple_token_price",
"attributes": {
"token_prices": {
"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": "0.999365729816931",
"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2": "3399.24368371279"
},
"market_cap_usd": {
"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": "51963214441.24363",
"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2": "10005535878.50094"
},
"h24_volume_usd": {
"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": "2095689865.85327",
"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2": "2544539948.02599"
}
}
}
}
```
### NFT Data: Market Cap Rank
`market_cap_rank` is now available for NFT collections via:
* [NFTs Collection Data by ID](/reference/nfts-id)
* [NFTs Collection Data by Contract Address](/reference/nfts-contract-address)
```json Example Payload theme={null}
"market_cap_rank": 75,
```
***
## Removal of Unsupported Categories
🗓️ **January 23, 2025**
The following categories have been removed from CoinGecko and the API, effective **February 12, 2025**:
| Category Name | Category ID |
| :--------------------- | :-------------------- |
| US Election 2020 | `us-election-2020` |
| Governance | `governance` |
| Cryptocurrency | `cryptocurrency` |
| Technology and Science | `technology-science` |
| Presale Meme | `presale-meme-coins` |
| Business Platform | `business-platform` |
| Number | `number` |
| Structured Product | `structured-products` |
| Investment | `investment` |
| Niftex Shards | `niftex-shards` |
| Ethereum POW IOU | `ethereum-pow-iou` |
| Mirrored Assets | `mirrored-assets` |
| Remittance | `remittance` |
| Protocol | `protocol` |
| Unicly Ecosystem | `utokens` |
| Finance and Banking | `finance-banking` |
| Eth 2.0 Staking | `eth-2-0-staking` |
These categories were either empty (no associated coins) or outdated. Requests to [/coins/markets](/reference/coins-markets) specifying any of these categories will return an error.
***
## Extended Historical Data for Onchain OHLCV Endpoint
🗓️ **January 15, 2025**
The [Pool OHLCV Chart by Pool Address](/reference/pool-ohlcv-contract-address) endpoint now supports historical data going back to **September 2021**, depending on when the pool was first tracked on GeckoTerminal.
* **Before:** Limited to the past 6 months from today
* **After:** Data available from September 2021 to present
* Each request is still limited to a **6-month date range** — use the `before_timestamp` parameter to page through older data
> Access to data beyond the past 6 months requires a [paid plan](https://www.coingecko.com/en/api/pricing) (Analyst & above).
No changes required for existing integrations.
***
## Update to Total Supply of POW Coins
🗓️ **January 15, 2025**
Total Supply for PoW (Proof-of-Work) coins now reflects the actual number of mined coins, rather than the maximum supply. This also applies to historical Total Supply data.
* **Before:** Maximum possible supply (e.g., Bitcoin: 21,000,000)
* **After:** Actual mined coins (e.g., Bitcoin: \~19,500,000 as of January 2025)
**Affected endpoints** with `total_supply` data:
* [Coin Data by ID](/reference/coins-id)
* [Coins List with Market Data](/reference/coins-markets)
* [Total Supply Chart by ID](/reference/coins-id-total-supply-chart)
* [Total Supply Chart within Time Range by ID](/reference/coins-id-total-supply-chart-range)
**Timeline:**
* **Bitcoin:** Updated January 14, 2025
* **Other PoW coins:** Updated January 22, 2025 — including Bitcoin Cash, Litecoin, Ethereum Classic, Bitcoin SV, Zcash, eCash, Dash, Kadena, Decred, Flux, DigiByte, Ravencoin, Groestlcoin, Firo, Vertcoin, Handshake, and more
***
## Improved Update Frequency for selected Pro-API endpoints
🗓️ **January 13, 2025**
> Applicable to [paid plan](https://www.coingecko.com/en/api/pricing) subscribers (Analyst & above) only.
Edge cache durations for the following endpoints have been reduced to 20–30s:
| Endpoint | Previous | New |
| :---------------------------------------------------------------------- | :------: | :-: |
| [/simple/price](/reference/simple-price) | 30s | 20s |
| [/simple/token\_price](/reference/simple-token-price) | 30s | 20s |
| [/simple/networks/../token\_price](/reference/onchain-simple-price) | 60s | 30s |
| [/networks/../pools/../trades](/reference/pool-trades-contract-address) | 60s | 30s |
| [/networks/../pools/..](/reference/pool-address) | 60s | 30s |
| [/networks/../pools/multi/..](/reference/pools-addresses) | 60s | 30s |
Cached responses incur no extra credits. Requests that bypass the cache and hit the origin server may use additional credits — adjust your polling interval accordingly.
***
## Improved 5-minutely data for Historical Chart Data endpoints
🗓️ **January 9, 2025**
The last 48 hours of data is no longer excluded from the following historical chart endpoints:
* [Coin Historical Chart Data by ID](/reference/coins-id-market-chart)
* [Coin Historical Chart Data within Time Range by ID](/reference/coins-id-market-chart-range)
* [Coin Historical Chart Data by Token Address](/reference/contract-address-market-chart)
* [Coin Historical Chart Data within Time Range by Token Address](/reference/contract-address-market-chart-range)
**Note:** The `interval=5m` and `interval=hourly` params are exclusive to Enterprise plan subscribers, bypassing auto-granularity:
* `interval=5m` — 5-minutely data, up to any 10-day range per request. Available from 9 February 2018 onwards.
* `interval=hourly` — hourly data, up to any 100-day range per request. Available from 30 January 2018 onwards.
For non-Enterprise subscribers, leave `interval` empty for auto-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)
# Asset Platforms List
Source: https://docs.coingecko.com/demo/reference/asset-platforms-list
openapi-specs/demo-api.json get /asset_platforms
To query all the supported asset platforms (blockchain networks) on CoinGecko
#### Notes
* Use this endpoint to get asset platform IDs for other endpoints that require an `id` parameter (asset platform).
* Use `filter=nft` to get only NFT-supported asset platforms.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.assetPlatforms.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.asset_platforms.get()
print(response)
```
# Authentication (Demo API)
Source: https://docs.coingecko.com/demo/reference/authentication
How to authenticate requests to the CoinGecko Demo API
Get higher rate limits, more credits, and access to premium endpoints.
[Sign up](https://www.coingecko.com/en/api/pricing) and grab your key from the [Developer Dashboard](https://www.coingecko.com/en/developers/dashboard#api-keys).
| Method | Key | Example |
| ------------------------ | ------------------- | -------------------------------------- |
| **Header** (recommended) | `x-cg-demo-api-key` | `-H "x-cg-demo-api-key: YOUR_API_KEY"` |
| **Query string** | `x_cg_demo_api_key` | `?x_cg_demo_api_key=YOUR_API_KEY` |
All requests use the Demo API root URL: `https://api.coingecko.com/api/v3/`
```bash Header (recommended) theme={null}
curl "https://api.coingecko.com/api/v3/ping" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
```bash Query string theme={null}
curl "https://api.coingecko.com/api/v3/ping?x_cg_demo_api_key=YOUR_API_KEY"
```
> Replace `YOUR_API_KEY` with your key from the [Developer Dashboard](https://www.coingecko.com/en/developers/dashboard#api-keys).
Onchain endpoints use the same authentication — just include `/onchain` in the path.
e.g. `https://api.coingecko.com/api/v3/onchain/simple/networks/...`
Store your API key in your backend and use a proxy to inject it into requests.
Avoid query string parameters in production — they risk exposing your key in logs and browser history.
Connect it to AI agents via MCP, SDK prompts, and coding agent integrations.
### Usage Credits
* Each successful request (HTTP 200) deducts 1 credit from your monthly quota.
* Monthly credits and rate limits depend on your [plan](https://www.coingecko.com/en/api/pricing).
* Check usage in the [Developer Dashboard](https://www.coingecko.com/en/developers/dashboard#usage-reports).
# Categories
Source: https://docs.coingecko.com/demo/reference/categories-overview
Coin categories and their aggregate market cap and volume, for filtering coins by sector.
| Endpoint | Description |
| --------------------------------------------------------------- | --------------------------------------------------------------------- |
| [/coins/categories/list](/demo/reference/coins-categories-list) | Query all supported coin categories on CoinGecko |
| [/coins/categories](/demo/reference/coins-categories) | Query all coin categories with market data (market cap, volume, etc.) |
# Coin Charts
Source: https://docs.coingecko.com/demo/reference/coin-charts-overview
Historical price, market cap, volume, OHLC and supply charts for any coin, by coin ID or token contract address.
| Endpoint | Description |
| --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [/coins/\{id}/market\_chart](/demo/reference/coins-id-market-chart) | Historical chart data (price, market cap, 24hr volume) by coin ID |
| [/coins/\{id}/market\_chart/range](/demo/reference/coins-id-market-chart-range) | Historical chart data within a time range by coin ID |
| [/coins/\{id}/contract
/\{contract\_address}/market\_chart](/demo/reference/contract-address-market-chart) | Historical chart data by asset platform and token contract address |
| [/coins/\{id}/contract
/\{contract\_address}/market\_chart/range](/demo/reference/contract-address-market-chart-range) | Historical chart data within a time range by asset platform and token contract address |
| [/coins/\{id}/ohlc](/demo/reference/coins-id-ohlc) | OHLC chart by coin ID |
# Coins Categories List with Market Data
Source: https://docs.coingecko.com/demo/reference/coins-categories
openapi-specs/demo-api.json get /coins/categories
To query all the coins categories with market data (market cap, volume, etc.) on CoinGecko
#### Notes
* To get coins within a specific category, use [Coins List with Market Data](/demo/reference/coins-markets) with the `category` parameter.
* Equivalent page on [CoinGecko Categories](https://www.coingecko.com/en/categories).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.categories.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.categories.get()
print(response)
```
# Coins Categories List
Source: https://docs.coingecko.com/demo/reference/coins-categories-list
openapi-specs/demo-api.json get /coins/categories/list
To query all the supported coins categories on CoinGecko
#### Notes
* Use this endpoint to get category IDs for endpoints that require a `category` parameter, such as [Coins List with Market Data](/demo/reference/coins-markets).
* Equivalent page on [CoinGecko Categories](https://www.coingecko.com/en/categories).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.categories.getList();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.categories.get_list()
print(response)
```
# Coin Data by Token Address
Source: https://docs.coingecko.com/demo/reference/coins-contract-address
openapi-specs/demo-api.json get /coins/{id}/contract/{contract_address}
To query all the metadata (image, websites, socials, description, contract address, etc.) and market data (price, ATH, exchange tickers, etc.) of a coin based on an asset platform and a particular token contract address
#### Notes
* Find a token's contract address on its [CoinGecko](https://www.coingecko.com) page or via [Coins List](/demo/reference/coins-list) with `include_platform=true`.
* Coin descriptions may contain `\r\n` escape sequences that require processing for proper formatting.
As of 28 August 2026, the `community_data` and `developer_data` objects are no longer returned. See the [changelog](/changelog#upcoming-change-notice-removal-of-community_data-and-developer_data) for details.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.contract.get('0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2', {
id: 'ethereum',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.contract.get(
"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
id="ethereum",
)
print(response.model_dump_json(indent=2))
```
# Coin Data by ID
Source: https://docs.coingecko.com/demo/reference/coins-id
openapi-specs/demo-api.json get /coins/{id}
To query all the metadata (image, websites, socials, description, contract address, etc.) and market data (price, ATH, exchange tickers, etc.) of a coin based on a particular coin ID
#### Notes
* Find a coin's API ID on its [CoinGecko](https://www.coingecko.com) page, via [Coins List](/demo/reference/coins-list), or this [Google Sheet](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
* Tickers are limited to 100 items. Use [Coin Tickers](/demo/reference/coins-id-tickers) for more.
* Coin descriptions may contain `\r\n` escape sequences that require processing for proper formatting.
* When `dex_pair_format=symbol`, DEX pair `base` and `target` display as symbols (e.g. `WETH`, `USDC`) instead of contract addresses.
* Use `last_updated` in the response to check whether the price is stale.
As of 28 August 2026, the `community_data` and `developer_data` objects are no longer returned. The `community_data` and `developer_data` query params are kept for backward compatibility but have no effect. See the [changelog](/changelog#upcoming-change-notice-removal-of-community_data-and-developer_data) for details.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.getID('bitcoin');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.get_id("bitcoin")
print(response.model_dump_json(indent=2))
```
# Coin Historical Data by ID
Source: https://docs.coingecko.com/demo/reference/coins-id-history
openapi-specs/demo-api.json get /coins/{id}/history
To query the historical data (price, market cap, 24hrs volume, etc.) at a given date for a coin based on a particular coin ID
#### Notes
* Find a coin's API ID on its [CoinGecko](https://www.coingecko.com) page, via [Coins List](/demo/reference/coins-list), or this [Google Sheet](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
* Data returned is a snapshot at `00:00:00 UTC` for the given date.
The last completed UTC day (00:00) becomes available 35 minutes after midnight (00:35 UTC).
As of 28 August 2026, the `community_data` and `developer_data` objects are no longer returned. See the [changelog](/changelog#upcoming-change-notice-removal-of-community_data-and-developer_data) for details.
Historical data via the Demo API is restricted to the past 365 days. Subscribe to [Analyst plan & above](https://www.coingecko.com/en/api/pricing) for the full range.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.history.get('bitcoin', {
date: '2025-12-30',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.history.get(
"bitcoin",
date="2025-12-30",
)
print(response.model_dump_json(indent=2))
```
# Coin Historical Chart Data by ID
Source: https://docs.coingecko.com/demo/reference/coins-id-market-chart
openapi-specs/demo-api.json get /coins/{id}/market_chart
To get the historical chart data of a coin including time in UNIX, price, market cap and 24hrs volume based on particular coin ID
#### Notes
* Find a coin's API ID on its [CoinGecko](https://www.coingecko.com) page, via [Coins List](/demo/reference/coins-list), or this [Google Sheet](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
* Auto-granularity when `interval` is not specified:
| Date range | Granularity |
| ----------------------- | --------------------- |
| 1 day from current time | **5-minutely** |
| 2–90 days | **hourly** |
| Above 90 days | **daily** (00:00 UTC) |
* Override with the `interval` parameter:
| `interval` | Lookback |
| ---------- | ------------------------------------------ |
| `daily` | — |
| `hourly` | **Past 100 days** |
| `5m` | **Past 10 days** (Enterprise only) |
| `1m` | **Past 1 day** (Enterprise only, **Beta**) |
The last completed UTC day (00:00) data is available 10 minutes after midnight (00:10 UTC).
Historical data via the Demo API is restricted to the past 365 days. Subscribe to [Analyst plan & above](https://www.coingecko.com/en/api/pricing) for the full range.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.marketChart.get('bitcoin', {
vs_currency: 'usd',
days: '1',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.market_chart.get(
"bitcoin",
vs_currency="usd",
days="1",
)
print(response.model_dump_json(indent=2))
```
# Coin Historical Chart Data within Time Range by ID
Source: https://docs.coingecko.com/demo/reference/coins-id-market-chart-range
openapi-specs/demo-api.json get /coins/{id}/market_chart/range
To get the historical chart data of a coin within certain time range in UNIX along with price, market cap and 24hrs volume based on particular coin ID
#### Notes
* Find a coin's API ID on its [CoinGecko](https://www.coingecko.com) page, via [Coins List](/demo/reference/coins-list), or this [Google Sheet](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
* Accepts ISO date strings (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM`, recommended) or UNIX timestamps for `from` and `to`.
* Auto-granularity when `interval` is not specified:
| Date range | Granularity |
| ------------------------- | --------------------- |
| 1 day from current time | **5-minutely** |
| 1 day from any other time | **hourly** |
| 2–90 days | **hourly** |
| Above 90 days | **daily** (00:00 UTC) |
* Override with the `interval` parameter:
| `interval` | Per request |
| ---------- | ----------------------------------------- |
| `daily` | — |
| `hourly` | **Any 100 days** |
| `5m` | **Any 10 days** (Enterprise only) |
| `1m` | **Any 1 day** (Enterprise only, **Beta**) |
The last completed UTC day (00:00) is available 35 minutes after midnight (00:35 UTC). Cache expires at 00:40 UTC.
Historical data via the Demo API is restricted to the past 365 days. Subscribe to [Analyst plan & above](https://www.coingecko.com/en/api/pricing) for the full range.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.marketChart.getRange('bitcoin', {
vs_currency: 'usd',
from: '1776787200',
to: '1777564800',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.market_chart.get_range(
"bitcoin",
vs_currency="usd",
from_="1776787200",
to="1777564800",
)
print(response.model_dump_json(indent=2))
```
# Coin OHLC Chart by ID
Source: https://docs.coingecko.com/demo/reference/coins-id-ohlc
openapi-specs/demo-api.json get /coins/{id}/ohlc
To get the OHLC chart (Open, High, Low, Close) of a coin based on particular coin ID
#### Notes
* Find a coin's API ID on its [CoinGecko](https://www.coingecko.com) page, via [Coins List](/demo/reference/coins-list), or this [Google Sheet](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
* The timestamp in the response indicates the **close** time of each OHLC candle.
* Auto-granularity (candle body):
* 1–2 days: 30 minutes
* 3–30 days: 4 hours
* 31 days and beyond: 4 days
* For better granularity, consider [Coin Historical Chart Data](/demo/reference/coins-id-market-chart).
The last completed UTC day (00:00) is available 35 minutes after midnight (00:35 UTC).
Historical data via the Demo API is restricted to the past 365 days. Subscribe to [Analyst plan & above](https://www.coingecko.com/en/api/pricing) for the full range.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.ohlc.get('bitcoin', {
vs_currency: 'usd',
days: '1',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.ohlc.get(
"bitcoin",
vs_currency="usd",
days="1",
)
print(response)
```
# Coin Tickers by ID
Source: https://docs.coingecko.com/demo/reference/coins-id-tickers
openapi-specs/demo-api.json get /coins/{id}/tickers
To query the coin tickers on both centralized exchange (CEX) and decentralized exchange (DEX) based on a particular coin ID
#### Notes
* Tickers are paginated to 100 items per page.
* Use `exchange_ids` to filter tickers for a specific exchange.
* When `dex_pair_format=symbol`, DEX pair `base` and `target` display as symbols (e.g. `WETH`, `USDC`) instead of contract addresses.
* When sorting by `volume`, `converted_volume` is used instead of `volume`.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.tickers.get('bitcoin');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.tickers.get("bitcoin")
print(response.model_dump_json(indent=2))
```
# Coins List
Source: https://docs.coingecko.com/demo/reference/coins-list
openapi-specs/demo-api.json get /coins/list
To query all the supported coins on CoinGecko with coin ID, name and symbol
#### Notes
* Use this endpoint to get coin IDs for other endpoints that require `id` or `ids` parameters.
* Returns the full list of active coins by default. Use `status=inactive` to retrieve coins no longer listed on CoinGecko ([Analyst plan or above](https://www.coingecko.com/en/api/pricing)).
* No pagination required — the full list is returned in a single response.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.list.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.list.get()
print(response)
```
# Coins List with Market Data
Source: https://docs.coingecko.com/demo/reference/coins-markets
openapi-specs/demo-api.json get /coins/markets
To query all the supported coins with price, market cap, volume and market related data
#### Notes
* Filter by `ids`, `names`, `symbols`, or `category`. When multiple are provided, priority is: `category` > `ids` > `names` > `symbols`.
* URL-encode spaces in `names` (e.g. `Binance%20Coin`).
* `include_tokens=all` only works with `symbols` lookups, limited to 50 symbols per request.
* Maximum of **250** IDs per request. Wildcard searches are not supported.
* Use `per_page` and `page` to paginate results.
Filter by category using the `category` param — refer to [Coins Categories List](/demo/reference/coins-categories-list) for available values.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.markets.get({
vs_currency: 'usd',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.markets.get(
vs_currency="usd",
)
print(response)
```
# Coins
Source: https://docs.coingecko.com/demo/reference/coins-overview
Coin metadata, market data, tickers, historical snapshots, new listings and top gainers and losers.
| Endpoint | Description |
| ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| [/coins/markets](/demo/reference/coins-markets) | Query all supported coins with price, market cap, volume and market data |
| [/coins/\{id}](/demo/reference/coins-id) | Query all metadata and market data of a coin by coin ID |
| [/coins/\{id}/contract/\{contract\_address}](/demo/reference/coins-contract-address) | Query all metadata and market data of a coin by asset platform and token contract address |
| [/coins/\{id}/tickers](/demo/reference/coins-id-tickers) | Query coin tickers on both CEX and DEX by coin ID |
| [/coins/\{id}/history](/demo/reference/coins-id-history) | Query historical data (price, market cap, 24hr volume, etc.) at a given date by coin ID |
# Crypto Treasury Holdings by Coin ID
Source: https://docs.coingecko.com/demo/reference/companies-public-treasury
openapi-specs/demo-api.json get /{entity}/public_treasury/{coin_id}
To query public companies' and governments' cryptocurrency holdings by coin ID
#### Notes
* Results are sorted by total holdings in descending order.
* Equivalent page on [CoinGecko Bitcoin Treasuries](https://www.coingecko.com/en/treasuries/bitcoin).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.publicTreasury.getCoinID('bitcoin', {
entity: 'companies',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.public_treasury.get_coin_id(
"bitcoin",
entity="companies",
)
print(response.model_dump_json(indent=2))
```
# Coin Historical Chart Data by Token Address
Source: https://docs.coingecko.com/demo/reference/contract-address-market-chart
openapi-specs/demo-api.json get /coins/{id}/contract/{contract_address}/market_chart
To get the historical chart data including time in UNIX, price, market cap and 24hrs volume based on asset platform and particular token contract address
#### Notes
* Find a token's contract address on its [CoinGecko](https://www.coingecko.com) page or via [Coins List](/demo/reference/coins-list) with `include_platform=true`.
* Auto-granularity when `interval` is not specified:
| Date range | Granularity |
| ----------------------- | --------------------- |
| 1 day from current time | **5-minutely** |
| 2–90 days | **hourly** |
| Above 90 days | **daily** (00:00 UTC) |
The last completed UTC day (00:00) is available 35 minutes after midnight (00:35 UTC). Cache expires at 00:40 UTC.
Historical data via the Demo API is restricted to the past 365 days. Subscribe to [Analyst plan & above](https://www.coingecko.com/en/api/pricing) for the full range.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.contract.marketChart.get('0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', {
id: 'ethereum',
vs_currency: 'usd',
days: '1',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.contract.market_chart.get(
"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
id="ethereum",
vs_currency="usd",
days="1",
)
print(response.model_dump_json(indent=2))
```
# Coin Historical Chart Data within Time Range by Token Address
Source: https://docs.coingecko.com/demo/reference/contract-address-market-chart-range
openapi-specs/demo-api.json get /coins/{id}/contract/{contract_address}/market_chart/range
To get the historical chart data within certain time range in UNIX along with price, market cap and 24hrs volume based on asset platform and particular token contract address
#### Notes
* Find a token's contract address on its [CoinGecko](https://www.coingecko.com) page or via [Coins List](/demo/reference/coins-list) with `include_platform=true`.
* Accepts ISO date strings (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM`, recommended) or UNIX timestamps for `from` and `to`.
* Auto-granularity when `interval` is not specified:
| Date range | Granularity |
| ------------------------- | --------------------- |
| 1 day from current time | **5-minutely** |
| 1 day from any other time | **hourly** |
| 2–90 days | **hourly** |
| Above 90 days | **daily** (00:00 UTC) |
The last completed UTC day (00:00) is available 35 minutes after midnight (00:35 UTC). Cache expires at 00:40 UTC.
Historical data via the Demo API is restricted to the past 365 days. Subscribe to [Analyst plan & above](https://www.coingecko.com/en/api/pricing) for the full range.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.contract.marketChart.getRange('0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', {
id: 'ethereum',
vs_currency: 'usd',
from: '1776787200',
to: '1777564800',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.contract.market_chart.get_range(
"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
id="ethereum",
vs_currency="usd",
from_="1776787200",
to="1777564800",
)
print(response.model_dump_json(indent=2))
```
# Crypto Global Market Data
Source: https://docs.coingecko.com/demo/reference/crypto-global
openapi-specs/demo-api.json get /global
To query cryptocurrency global data including active cryptocurrencies, markets, total crypto market cap and etc
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.global.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.global_.get()
print(response.model_dump_json(indent=2))
```
# Derivatives Exchanges List with Data
Source: https://docs.coingecko.com/demo/reference/derivatives-exchanges
openapi-specs/demo-api.json get /derivatives/exchanges
To query all the derivatives exchanges with related data (ID, name, open interest, ...) on CoinGecko
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.derivatives.exchanges.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.derivatives.exchanges.get()
print(response)
```
# Derivatives Exchange Data by ID
Source: https://docs.coingecko.com/demo/reference/derivatives-exchanges-id
openapi-specs/demo-api.json get /derivatives/exchanges/{id}
To query the derivatives exchange's related data (name, open interest, trade volume, ...) based on the exchange's ID
Use `include_tickers=all` to include all tickers, `unexpired` for unexpired tickers only, or leave blank to omit tickers.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.derivatives.exchanges.getID('binance_futures');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.derivatives.exchanges.get_id("binance_futures")
print(response.model_dump_json(indent=2))
```
# Derivatives Exchanges List
Source: https://docs.coingecko.com/demo/reference/derivatives-exchanges-list
openapi-specs/demo-api.json get /derivatives/exchanges/list
To query all the supported derivatives exchanges with ID and name on CoinGecko
Use this endpoint to get derivatives exchange IDs for other endpoints that require an `id` parameter.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.derivatives.exchanges.getList();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.derivatives.exchanges.get_list()
print(response)
```
# Derivatives
Source: https://docs.coingecko.com/demo/reference/derivatives-overview
Derivatives exchanges, perpetual and futures tickers, open interest and trading volume.
| Endpoint | Description |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [/derivatives/exchanges/list](/demo/reference/derivatives-exchanges-list) | Query all supported derivatives exchanges with ID and name |
| [/derivatives](/demo/reference/derivatives-tickers) | Query all tickers from derivatives exchanges |
| [/derivatives/exchanges](/demo/reference/derivatives-exchanges) | Query all derivatives exchanges with data (ID, name, open interest, etc.) |
| [/derivatives/exchanges/\{id}](/demo/reference/derivatives-exchanges-id) | Query derivatives exchange data by exchange ID |
# Derivatives Tickers List
Source: https://docs.coingecko.com/demo/reference/derivatives-tickers
openapi-specs/demo-api.json get /derivatives
To query all the tickers from derivatives exchanges on CoinGecko
`open_interest` and `volume_24h` values in the response are in USD.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.derivatives.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.derivatives.get()
print(response)
```
# DEXs List by Network
Source: https://docs.coingecko.com/demo/reference/dexes-list
openapi-specs/demo-api.json get /onchain/networks/{network}/dexes
To query all the supported decentralized exchanges (DEXs) based on the provided network on GeckoTerminal
Use this endpoint to get DEX IDs for other endpoints that require a `dex` parameter.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.dexes.get('eth');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.dexes.get("eth")
print(response.model_dump_json(indent=2))
```
# Endpoint Overview
Source: https://docs.coingecko.com/demo/reference/endpoint-overview
Complete list of endpoints available in the Demo / Keyless API
Authenticate your requests to start using the Demo API.
The Demo API covers a subset of endpoints.
**Upgrade for higher rate limits, more credits, and access to all 85+ endpoints.**
## CoinGecko
### Price
| Endpoint | Description |
| ---------------------------------------------------------------- | -------------------------------------------------------------------- |
| [/simple/price](/demo/reference/simple-price) | Query prices of one or more coins by Coin API IDs, symbols, or names |
| [/simple/token\_price/\{id}](/demo/reference/simple-token-price) | Query one or more token prices by token contract addresses |
### Search & ID Map
| Endpoint | Description |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| [/search](/demo/reference/search-data) | Search for coins, categories and markets on CoinGecko |
| [/coins/list](/demo/reference/coins-list) | Query all supported coins with coin ID, name and symbol |
| [/asset\_platforms](/demo/reference/asset-platforms-list) | Query all supported asset platforms (blockchain networks) |
| [/token\_lists/\{asset\_platform\_id}/all.json](/demo/reference/token-lists) | Full list of tokens on a blockchain network supported by Ethereum token list standard |
| [/simple/supported\_vs\_currencies](/demo/reference/simple-supported-currencies) | Query all supported currencies on CoinGecko |
### Coins
| Endpoint | Description |
| ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| [/coins/markets](/demo/reference/coins-markets) | Query all supported coins with price, market cap, volume and market data |
| [/coins/\{id}](/demo/reference/coins-id) | Query all metadata and market data of a coin by coin ID |
| [/coins/\{id}/contract/\{contract\_address}](/demo/reference/coins-contract-address) | Query all metadata and market data of a coin by asset platform and token contract address |
| [/coins/\{id}/tickers](/demo/reference/coins-id-tickers) | Query coin tickers on both CEX and DEX by coin ID |
| [/coins/\{id}/history](/demo/reference/coins-id-history) | Query historical data (price, market cap, 24hr volume, etc.) at a given date by coin ID |
### Coin Charts
| Endpoint | Description |
| --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [/coins/\{id}/market\_chart](/demo/reference/coins-id-market-chart) | Historical chart data (price, market cap, 24hr volume) by coin ID |
| [/coins/\{id}/market\_chart/range](/demo/reference/coins-id-market-chart-range) | Historical chart data within a time range by coin ID |
| [/coins/\{id}/contract
/\{contract\_address}/market\_chart](/demo/reference/contract-address-market-chart) | Historical chart data by asset platform and token contract address |
| [/coins/\{id}/contract
/\{contract\_address}/market\_chart/range](/demo/reference/contract-address-market-chart-range) | Historical chart data within a time range by asset platform and token contract address |
| [/coins/\{id}/ohlc](/demo/reference/coins-id-ohlc) | OHLC chart by coin ID |
### Categories
| Endpoint | Description |
| --------------------------------------------------------------- | --------------------------------------------------------------------- |
| [/coins/categories/list](/demo/reference/coins-categories-list) | Query all supported coin categories on CoinGecko |
| [/coins/categories](/demo/reference/coins-categories) | Query all coin categories with market data (market cap, volume, etc.) |
### RWA
| Endpoint | Description |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [/rwas/list](/demo/reference/rwas-list) | Query all supported tokenized real world assets (RWAs) with RWA ID, name and symbol |
| [/rwas/markets](/demo/reference/rwas-markets) | Query all supported RWAs with price, market cap, volume and market data |
| [/rwas/\{id}](/demo/reference/rwas-id) | Query all metadata, market data and tokens of an RWA by RWA ID |
| [/rwas/issuers/list](/demo/reference/rwas-issuers-list) | Query all supported RWA issuers with issuer ID and name |
| [/rwas/issuers/\{id}](/demo/reference/rwas-issuers-id) | Query market data and tokens of an RWA issuer by issuer ID |
### Exchanges
| Endpoint | Description |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| [/exchanges/list](/demo/reference/exchanges-list) | Query all supported exchanges with ID and name |
| [/exchanges](/demo/reference/exchanges) | Query all supported exchanges with data (ID, name, country, etc.) |
| [/exchanges/\{id}](/demo/reference/exchanges-id) | Query exchange data and top 100 tickers by exchange ID |
| [/exchanges/\{id}/tickers](/demo/reference/exchanges-id-tickers) | Query exchange tickers by exchange ID |
| [/exchanges/\{id}/volume\_chart](/demo/reference/exchanges-id-volume-chart) | Historical volume chart data in BTC by exchange ID |
### Derivatives
| Endpoint | Description |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [/derivatives/exchanges/list](/demo/reference/derivatives-exchanges-list) | Query all supported derivatives exchanges with ID and name |
| [/derivatives](/demo/reference/derivatives-tickers) | Query all tickers from derivatives exchanges |
| [/derivatives/exchanges](/demo/reference/derivatives-exchanges) | Query all derivatives exchanges with data (ID, name, open interest, etc.) |
| [/derivatives/exchanges/\{id}](/demo/reference/derivatives-exchanges-id) | Query derivatives exchange data by exchange ID |
### Public Treasury
| Endpoint | Description |
| ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [/entities/list](/demo/reference/entities-list) | Query all supported entities with entity ID, name, symbol, and country |
| [/\{entity}/public\_treasury/\{coin\_id}](/demo/reference/companies-public-treasury) | Query public companies' and governments' crypto holdings by coin ID |
| [/public\_treasury/\{entity\_id}](/demo/reference/public-treasury-entity) | Query public companies' and governments' crypto holdings by entity ID |
| [/public\_treasury/\{entity\_id}/\{coin\_id}
/holding\_chart](/demo/reference/public-treasury-entity-chart) | Historical crypto holdings chart by entity ID and coin ID |
| [/public\_treasury/\{entity\_id}
/transaction\_history](/demo/reference/public-treasury-transaction-history) | Crypto transaction history by entity ID |
### NFTs
| Endpoint | Description |
| --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [/nfts/list](/demo/reference/nfts-list) | Query all supported NFTs with ID, contract address, name, asset platform ID and symbol |
| [/nfts/\{id}](/demo/reference/nfts-id) | Query NFT data (name, floor price, 24hr volume, etc.) by collection ID |
| [/nfts/\{asset\_platform\_id}/contract
/\{contract\_address}](/demo/reference/nfts-contract-address) | Query NFT data by collection contract address and asset platform |
### Trending
| Endpoint | Description |
| --------------------------------------------------- | --------------------------------------------------------------------- |
| [/search/trending](/demo/reference/trending-search) | Query trending search coins, NFTs and categories in the last 24 hours |
### Global
| Endpoint | Description |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [/global](/demo/reference/crypto-global) | Query global crypto data (active cryptocurrencies, markets, total market cap, etc.) |
| [/global/decentralized\_finance\_defi](/demo/reference/global-defi) | Query top 100 global DeFi data (market cap, trading volume) |
### Utility
| Endpoint | Description |
| -------------------------------------------------- | ---------------------------------------------- |
| [/exchange\_rates](/demo/reference/exchange-rates) | Query BTC exchange rates with other currencies |
| [/ping](/demo/reference/ping-server) | Check API server status |
***
## Onchain
### Price
| Endpoint | Description |
| ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| [/onchain/simple/networks/\{network}
/token\_price/\{addresses}](/demo/reference/onchain-simple-price) | Token price by token contract addresses on a network |
### Search & ID Map
| Endpoint | Description |
| ---------------------------------------------------------------- | --------------------------------------------------------------------- |
| [/onchain/search/pools](/demo/reference/search-pools) | Search pools by pool address, token name, symbol, or contract address |
| [/onchain/networks](/demo/reference/networks-list) | All supported networks on GeckoTerminal |
| [/onchain/networks/\{network}/dexes](/demo/reference/dexes-list) | All supported DEXs by network |
### Pools
| Endpoint | Description |
| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ |
| [/onchain/networks/\{network}/pools
/\{address}](/demo/reference/pool-address) | Query specific pool by network and pool address |
| [/onchain/networks/\{network}/pools/multi
/\{addresses}](/demo/reference/pools-addresses) | Query multiple pools by network and pool addresses |
| [/onchain/networks/\{network}/pools
/\{pool\_address}/info](/demo/reference/pool-token-info-contract-address) | Pool metadata (token details, socials, etc.) by pool address |
| [/onchain/networks/\{network}/pools](/demo/reference/top-pools-network) | Top pools by network |
| [/onchain/networks/\{network}/dexes/\{dex}
/pools](/demo/reference/top-pools-dex) | Top pools by network and DEX |
| [/onchain/networks/\{network}/tokens
/\{token\_address}/pools](/demo/reference/top-pools-contract-address) | Top pools by token contract address |
### New & Trending Pools
| Endpoint | Description |
| -------------------------------------------------------------------------------------------- | ---------------------------------- |
| [/onchain/networks/new\_pools](/demo/reference/latest-pools-list) | Latest pools across all networks |
| [/onchain/networks/\{network}/new\_pools](/demo/reference/latest-pools-network) | Latest pools by network |
| [/onchain/networks/trending\_pools](/demo/reference/trending-pools-list) | Trending pools across all networks |
| [/onchain/networks/\{network}
/trending\_pools](/demo/reference/trending-pools-network) | Trending pools by network |
### Tokens
| Endpoint | Description |
| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| [/onchain/networks/\{network}/tokens
/\{address}](/demo/reference/token-data-contract-address) | Token data by token contract address on a network |
| [/onchain/networks/\{network}/tokens/multi
/\{addresses}](/demo/reference/tokens-data-contract-addresses) | Multiple tokens data by token contract addresses on a network |
| [/onchain/networks/\{network}/tokens
/\{address}/info](/demo/reference/token-info-contract-address) | Token metadata (name, symbol, CoinGecko ID, socials, etc.) by token contract address |
| [/onchain/tokens/info\_recently\_updated](/demo/reference/tokens-info-recent-updated) | 100 most recently updated tokens info across all networks |
### Charts
| Endpoint | Description |
| --------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| [/onchain/networks/\{network}/pools
/\{pool\_address}/ohlcv/\{timeframe}](/demo/reference/pool-ohlcv-contract-address) | Pool OHLCV chart by pool address |
### Trades
| Endpoint | Description |
| ---------------------------------------------------------------------------------------------------------------- | ---------------------- |
| [/onchain/networks/\{network}/pools
/\{pool\_address}/trades](/demo/reference/pool-trades-contract-address) | Trades by pool address |
***
⚡ **Need real-time data streams?**
Stream prices, trades, and OHLCV data with ultra-low latency via [WebSocket](/websocket).
![]()
Requires [Basic plan & above](https://www.coingecko.com/en/api/pricing).
# Entities List
Source: https://docs.coingecko.com/demo/reference/entities-list
openapi-specs/demo-api.json get /entities/list
To query all the supported entities on CoinGecko with entity ID, name, symbol, and country
Use this endpoint to get entity IDs for other Public Treasury endpoints.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.entities.getList();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.entities.get_list()
print(response)
```
# BTC-to-Currency Exchange Rates
Source: https://docs.coingecko.com/demo/reference/exchange-rates
openapi-specs/demo-api.json get /exchange_rates
To query BTC exchange rates with other currencies
Use this endpoint to convert BTC-denominated response data from other endpoints to different currencies.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.exchangeRates.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.exchange_rates.get()
print(response.model_dump_json(indent=2))
```
# Exchanges List with Data
Source: https://docs.coingecko.com/demo/reference/exchanges
openapi-specs/demo-api.json get /exchanges
To query all the supported exchanges with exchanges' data (ID, name, country, etc.) that have active trading volumes on CoinGecko
Only exchanges with active trading volume on CoinGecko are included. Inactive or deactivated exchanges are removed from the list.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.exchanges.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.exchanges.get()
print(response)
```
# Exchange Data by ID
Source: https://docs.coingecko.com/demo/reference/exchanges-id
openapi-specs/demo-api.json get /exchanges/{id}
To query exchange's data (name, year established, country, etc.), exchange volume in BTC and top 100 tickers based on exchange's ID
#### Notes
* Exchange volume is provided in BTC. Use [Exchange Rates](/demo/reference/exchange-rates) to convert to other currencies.
* Tickers are limited to 100 items. Use [Exchange Tickers](/demo/reference/exchanges-id-tickers) for more.
* For derivatives exchanges (e.g. `bitmex`, `binance_futures`), use [Derivatives Exchange Data](/demo/reference/derivatives-exchanges-id) instead.
* When `dex_pair_format=symbol`, DEX pair `base` and `target` display as symbols (e.g. `WETH`, `USDC`) instead of contract addresses.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.exchanges.getID('binance');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.exchanges.get_id("binance")
print(response.model_dump_json(indent=2))
```
# Exchange Tickers by ID
Source: https://docs.coingecko.com/demo/reference/exchanges-id-tickers
openapi-specs/demo-api.json get /exchanges/{id}/tickers
To query exchange's tickers based on exchange's ID
#### Notes
* Tickers are paginated to 100 items per page.
* Use `order=base_target` for stable pagination — sorts by `base` then `target` symbol in lexicographical order, preventing duplicate or missing tickers across pages.
* When `dex_pair_format=symbol`, DEX pair `base` and `target` display as symbols (e.g. `WETH`, `USDC`) instead of contract addresses.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.exchanges.tickers.get('binance');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.exchanges.tickers.get("binance")
print(response.model_dump_json(indent=2))
```
# Exchange Volume Chart by ID
Source: https://docs.coingecko.com/demo/reference/exchanges-id-volume-chart
openapi-specs/demo-api.json get /exchanges/{id}/volume_chart
To query the historical volume chart data with time in UNIX and trading volume data in BTC based on exchange's ID
#### Notes
* Also works for derivatives exchanges (e.g. `bitmex`, `binance_futures`).
* Volume is provided in BTC. Use [Exchange Rates](/demo/reference/exchange-rates) to convert to other currencies.
* Auto-granularity (cannot be adjusted):
* 1 day = 10-minutely
* 7, 14 days = hourly
* 30 days and above = daily
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.exchanges.volumeChart.get('binance', {
days: '1',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.exchanges.volume_chart.get(
"binance",
days="1",
)
print(response)
```
# Exchanges List
Source: https://docs.coingecko.com/demo/reference/exchanges-list
openapi-specs/demo-api.json get /exchanges/list
To query all the supported exchanges with ID and name
#### Notes
* Use this endpoint to get exchange IDs (including derivatives exchanges) for other endpoints that require an `id` parameter.
* No pagination required — the full list is returned in a single response.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.exchanges.getList();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.exchanges.get_list()
print(response)
```
# Exchanges
Source: https://docs.coingecko.com/demo/reference/exchanges-overview
Centralized exchange data, trading pairs and tickers, and historical exchange volume in BTC.
| Endpoint | Description |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| [/exchanges/list](/demo/reference/exchanges-list) | Query all supported exchanges with ID and name |
| [/exchanges](/demo/reference/exchanges) | Query all supported exchanges with data (ID, name, country, etc.) |
| [/exchanges/\{id}](/demo/reference/exchanges-id) | Query exchange data and top 100 tickers by exchange ID |
| [/exchanges/\{id}/tickers](/demo/reference/exchanges-id-tickers) | Query exchange tickers by exchange ID |
| [/exchanges/\{id}/volume\_chart](/demo/reference/exchanges-id-volume-chart) | Historical volume chart data in BTC by exchange ID |
# Global DeFi Market Data
Source: https://docs.coingecko.com/demo/reference/global-defi
openapi-specs/demo-api.json get /global/decentralized_finance_defi
To query top 100 cryptocurrency global decentralized finance (DeFi) data including DeFi market cap, trading volume
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.global.decentralizedFinanceDefi.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.global_.decentralized_finance_defi.get()
print(response.model_dump_json(indent=2))
```
# Global
Source: https://docs.coingecko.com/demo/reference/global-overview
Total crypto market cap, volume, DeFi dominance and historical global market cap charts.
| Endpoint | Description |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [/global](/demo/reference/crypto-global) | Query global crypto data (active cryptocurrencies, markets, total market cap, etc.) |
| [/global/decentralized\_finance\_defi](/demo/reference/global-defi) | Query top 100 global DeFi data (market cap, trading volume) |
# New Pools List
Source: https://docs.coingecko.com/demo/reference/latest-pools-list
openapi-specs/demo-api.json get /onchain/networks/new_pools
To query all the latest pools across all networks on GeckoTerminal
#### Notes
* Returns up to 20 pools per page. Use the `page` param to navigate more results. Pagination beyond 10 pages requires [Analyst plan or above](https://www.coingecko.com/en/api/pricing).
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate.
* Use `include` to return related attributes under the top-level `included` key.
* Equivalent page on [GeckoTerminal New Pools](https://www.geckoterminal.com/explore/new-crypto-pools).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.newPools.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.new_pools.get()
print(response.model_dump_json(indent=2))
```
# New Pools by Network
Source: https://docs.coingecko.com/demo/reference/latest-pools-network
openapi-specs/demo-api.json get /onchain/networks/{network}/new_pools
To query all the latest pools based on the provided network
#### Notes
* Includes pools created within the past 48 hours.
* Returns up to 20 pools per page. Use the `page` param to navigate more results. Pagination beyond 10 pages requires [Analyst plan or above](https://www.coingecko.com/en/api/pricing).
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate.
* Use `include` to return related attributes under the top-level `included` key.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.newPools.getNetwork('eth');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.new_pools.get_network("eth")
print(response.model_dump_json(indent=2))
```
# Networks List
Source: https://docs.coingecko.com/demo/reference/networks-list
openapi-specs/demo-api.json get /onchain/networks
To retrieve a list of all supported networks on GeckoTerminal
Use this endpoint to get network IDs for other endpoints that require a `network` parameter.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.get()
print(response.model_dump_json(indent=2))
```
# NFTs Collection Data by Contract Address
Source: https://docs.coingecko.com/demo/reference/nfts-contract-address
openapi-specs/demo-api.json get /nfts/{asset_platform_id}/contract/{contract_address}
To query all the NFT data (name, floor price, 24hr volume, ...) based on the NFT collection contract address and respective asset platform
Get `asset_platform_id` and `contract_address` from [NFTs List](/demo/reference/nfts-list).
Solana NFTs and Art Blocks are not supported for this endpoint. Use [NFTs Collection Data by ID](/demo/reference/nfts-id) instead.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.nfts.contract.getContractAddress('0xBd3531dA5CF5857e7CfAA92426877b022e612cf8', {
asset_platform_id: 'ethereum',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.nfts.contract.get_contract_address(
"0xBd3531dA5CF5857e7CfAA92426877b022e612cf8",
asset_platform_id="ethereum",
)
print(response.model_dump_json(indent=2))
```
# NFTs Collection Data by ID
Source: https://docs.coingecko.com/demo/reference/nfts-id
openapi-specs/demo-api.json get /nfts/{id}
To query all the NFT data (name, floor price, 24hr volume, ...) based on the NFT collection ID
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.nfts.getID('pudgy-penguins');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.nfts.get_id("pudgy-penguins")
print(response.model_dump_json(indent=2))
```
# NFTs List
Source: https://docs.coingecko.com/demo/reference/nfts-list
openapi-specs/demo-api.json get /nfts/list
To query all supported NFTs with ID, contract address, name, asset platform ID and symbol on CoinGecko
#### Notes
* Use this endpoint to get NFT collection IDs, `asset_platform_id`, and `contract_address` for other NFT endpoints.
* Results are paginated to 100 items per page.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.nfts.getList();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.nfts.get_list()
print(response)
```
# NFTs
Source: https://docs.coingecko.com/demo/reference/nfts-overview
NFT collection floor price, market cap, 24h volume, marketplace tickers and historical charts.
| Endpoint | Description |
| --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [/nfts/list](/demo/reference/nfts-list) | Query all supported NFTs with ID, contract address, name, asset platform ID and symbol |
| [/nfts/\{id}](/demo/reference/nfts-id) | Query NFT data (name, floor price, 24hr volume, etc.) by collection ID |
| [/nfts/\{asset\_platform\_id}/contract
/\{contract\_address}](/demo/reference/nfts-contract-address) | Query NFT data by collection contract address and asset platform |
# Onchain Charts
Source: https://docs.coingecko.com/demo/reference/onchain-charts-overview
OHLCV candlestick charts for DEX pools and tokens, from second to day timeframes.
| Endpoint | Description |
| --------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| [/onchain/networks/\{network}/pools
/\{pool\_address}/ohlcv/\{timeframe}](/demo/reference/pool-ohlcv-contract-address) | Pool OHLCV chart by pool address |
# Onchain New & Trending Pools
Source: https://docs.coingecko.com/demo/reference/onchain-new-and-trending-pools-overview
Newly created and trending DEX liquidity pools, across all networks or a single network.
| Endpoint | Description |
| -------------------------------------------------------------------------------------------- | ---------------------------------- |
| [/onchain/networks/new\_pools](/demo/reference/latest-pools-list) | Latest pools across all networks |
| [/onchain/networks/\{network}/new\_pools](/demo/reference/latest-pools-network) | Latest pools by network |
| [/onchain/networks/trending\_pools](/demo/reference/trending-pools-list) | Trending pools across all networks |
| [/onchain/networks/\{network}
/trending\_pools](/demo/reference/trending-pools-network) | Trending pools by network |
# Onchain Pools
Source: https://docs.coingecko.com/demo/reference/onchain-pools-overview
DEX liquidity pool data by network, DEX, pool address or token address, with pool metadata.
| Endpoint | Description |
| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ |
| [/onchain/networks/\{network}/pools
/\{address}](/demo/reference/pool-address) | Query specific pool by network and pool address |
| [/onchain/networks/\{network}/pools/multi
/\{addresses}](/demo/reference/pools-addresses) | Query multiple pools by network and pool addresses |
| [/onchain/networks/\{network}/pools
/\{pool\_address}/info](/demo/reference/pool-token-info-contract-address) | Pool metadata (token details, socials, etc.) by pool address |
| [/onchain/networks/\{network}/pools](/demo/reference/top-pools-network) | Top pools by network |
| [/onchain/networks/\{network}/dexes/\{dex}
/pools](/demo/reference/top-pools-dex) | Top pools by network and DEX |
| [/onchain/networks/\{network}/tokens
/\{token\_address}/pools](/demo/reference/top-pools-contract-address) | Top pools by token contract address |
# Onchain Price
Source: https://docs.coingecko.com/demo/reference/onchain-price-overview
Onchain token prices by contract address across every network GeckoTerminal indexes.
| Endpoint | Description |
| ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| [/onchain/simple/networks/\{network}
/token\_price/\{addresses}](/demo/reference/onchain-simple-price) | Token price by token contract addresses on a network |
# Onchain Search & ID Map
Source: https://docs.coingecko.com/demo/reference/onchain-search-and-id-map-overview
Search DEX pools and look up the network and DEX identifiers the onchain endpoints require.
| Endpoint | Description |
| ---------------------------------------------------------------- | --------------------------------------------------------------------- |
| [/onchain/search/pools](/demo/reference/search-pools) | Search pools by pool address, token name, symbol, or contract address |
| [/onchain/networks](/demo/reference/networks-list) | All supported networks on GeckoTerminal |
| [/onchain/networks/\{network}/dexes](/demo/reference/dexes-list) | All supported DEXs by network |
# Token Price by Token Addresses
Source: https://docs.coingecko.com/demo/reference/onchain-simple-price
openapi-specs/demo-api.json get /onchain/simple/networks/{network}/token_price/{addresses}
To get token price based on the provided token contract address on a network
#### Notes
* Prices are returned in USD. Addresses not found in GeckoTerminal will be ignored.
* Supports up to **30 contract addresses** per request. [Analyst plan or above](https://www.coingecko.com/en/api/pricing) supports up to 100.
* Unverified token market cap returns `null`. Use `mcap_fdv_fallback=true` to return FDV value (as seen on [GeckoTerminal](https://www.geckoterminal.com/)) when market cap data is unavailable.
* GeckoTerminal's routing selects the best pool for pricing based on liquidity and activity. For full control, use [Specific Pool Data](/demo/reference/pool-address) with a specific pool address.
* Set `include_inactive_source=true` to expand the search to recently active pools (up to 1 year) if no top pool is found.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.simple.networks.tokenPrice.getAddresses('0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2', {
network: 'eth',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.simple.networks.token_price.get_addresses(
"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
network="eth",
)
print(response.model_dump_json(indent=2))
```
# Onchain Tokens
Source: https://docs.coingecko.com/demo/reference/onchain-tokens-overview
Onchain token data, metadata and socials by contract address, for one or many tokens.
| Endpoint | Description |
| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| [/onchain/networks/\{network}/tokens
/\{address}](/demo/reference/token-data-contract-address) | Token data by token contract address on a network |
| [/onchain/networks/\{network}/tokens/multi
/\{addresses}](/demo/reference/tokens-data-contract-addresses) | Multiple tokens data by token contract addresses on a network |
| [/onchain/networks/\{network}/tokens
/\{address}/info](/demo/reference/token-info-contract-address) | Token metadata (name, symbol, CoinGecko ID, socials, etc.) by token contract address |
| [/onchain/tokens/info\_recently\_updated](/demo/reference/tokens-info-recent-updated) | 100 most recently updated tokens info across all networks |
# Onchain Trades
Source: https://docs.coingecko.com/demo/reference/onchain-trades-overview
DEX trade history for a pool or token, plus a token's top traders.
| Endpoint | Description |
| ---------------------------------------------------------------------------------------------------------------- | ---------------------- |
| [/onchain/networks/\{network}/pools
/\{pool\_address}/trades](/demo/reference/pool-trades-contract-address) | Trades by pool address |
# API Server Status
Source: https://docs.coingecko.com/demo/reference/ping-server
openapi-specs/demo-api.json get /ping
To check the API server status
You can also check [status.coingecko.com](https://status.coingecko.com/) for real-time API server status and maintenance notices.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.ping.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.ping.get()
print(response.model_dump_json(indent=2))
```
# Specific Pool Data by Pool Address
Source: https://docs.coingecko.com/demo/reference/pool-address
openapi-specs/demo-api.json get /onchain/networks/{network}/pools/{address}
To query the specific pool based on the provided network and pool address
#### Notes
* Addresses not found in GeckoTerminal will be ignored.
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate. Verified market cap is sourced from CoinGecko and may exceed FDV if it includes tokens on other networks.
* Use `include` to return related attributes under the top-level `included` key.
* `locked_liquidity_percentage` is updated daily.
* Set `include_composition=true` to surface the balance and liquidity value of base and quote tokens.
* Bonding curve pools (e.g. non-graduated launchpad pools) return a `launchpad_details` object with graduation status and migration details.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.pools.getAddress('0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640', {
network: 'eth',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.pools.get_address(
"0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
network="eth",
)
print(response.model_dump_json(indent=2))
```
# Pool OHLCV Chart by Pool Address
Source: https://docs.coingecko.com/demo/reference/pool-ohlcv-contract-address
openapi-specs/demo-api.json get /onchain/networks/{network}/pools/{pool_address}/ohlcv/{timeframe}
To get the OHLCV chart (Open, High, Low, Close, Volume) of a pool based on the provided pool address on a network
#### Notes
* Use `timeframe` with `aggregate` for custom intervals (e.g. `minute?aggregate=15` for 15-minute OHLCV).
* Timestamps use epoch/unix format (e.g. `1708850449`).
* Each call retrieves a **max 6-month range** — use `before_timestamp` for older data.
* Each `ohlcv_list` element:
```
[
timestamp,
open,
high,
low,
close,
volume
]
```
* Intervals with no swaps are skipped by default. Set `include_empty_intervals=true` to fill gaps (OHLC = previous close, volume = 0).
**Historical Access by Plan:**
* **Basic:** past 6 months
* **[Analyst and above](https://www.coingecko.com/en/api/pricing):** September 2021 to present (depending on pool tracking start)
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.pools.ohlcv.getTimeframe('day', {
network: 'eth',
pool_address: '0x06da0fd433c1a5d7a4faa01111c044910a184553',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.pools.ohlcv.get_timeframe(
"day",
network="eth",
pool_address="0x06da0fd433c1a5d7a4faa01111c044910a184553",
)
print(response.model_dump_json(indent=2))
```
# Pool Tokens Info by Pool Address
Source: https://docs.coingecko.com/demo/reference/pool-token-info-contract-address
openapi-specs/demo-api.json get /onchain/networks/{network}/pools/{pool_address}/info
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
#### Notes
* Learn more about [GT Score](https://support.coingecko.com/hc/en-us/articles/38381394237593-What-is-GT-Score-How-is-GT-Score-calculated) and [GT Verified](https://support.coingecko.com/hc/en-us/articles/54413671274649-What-is-GT-Verified-Badge).
* `holders` data is currently in Beta, with ongoing improvements to coverage and update frequency.
| Chain | Network `id` |
| --------- | ------------- |
| Solana | `solana` |
| Ethereum | `eth` |
| Base | `base` |
| BNB Chain | `bsc` |
| Optimism | `optimism` |
| Arbitrum | `arbitrum` |
| Polygon | `polygon_pos` |
| TON | `ton` |
| Sui | `sui-network` |
| Robinhood | `robinhood` |
| Ronin | `ronin` |
| Bittensor | `bittensor` |
* `distribution_percentage` coverage:
* Solana: `top_10`, `11_20`, `21_40`, `rest`
* Other chains: `top_10`, `11_30`, `31_50`, `rest`
* Bonding curve tokens (non-graduated launchpad tokens) include a `launchpad_details` object with graduation status.
- Metadata (image, websites, description, socials) is unvetted unless the token is [GT Verified](https://support.coingecko.com/hc/en-us/articles/54413671274649-What-is-GT-Verified-Badge) (`gt_verified: true`) or reviewed by CoinGecko.
- For CoinGecko-reviewed metadata, use [Coin Data by ID](/demo/reference/coins-id) or [Coin Data by Token Address](/demo/reference/coins-contract-address).
For pool market data (price, transactions, volume), use [Specific Pool Data](/demo/reference/pool-address) instead.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.pools.info.get('8WwcNqdZjCY5Pt7AkhupAFknV2txca9sq6YBkGzLbvdt', {
network: 'solana',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.pools.info.get(
"8WwcNqdZjCY5Pt7AkhupAFknV2txca9sq6YBkGzLbvdt",
network="solana",
)
print(response.model_dump_json(indent=2))
```
# Trades by Pool Address
Source: https://docs.coingecko.com/demo/reference/pool-trades-contract-address
openapi-specs/demo-api.json get /onchain/networks/{network}/pools/{pool_address}/trades
To query the trades based on the provided pool address
Returns the last 300 trades from the past 24 hours. A longer `trading_period` lookback and cursor pagination require [Analyst plan & above](https://www.coingecko.com/en/api/pricing).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.pools.trades.get('0x06da0fd433c1a5d7a4faa01111c044910a184553', {
network: 'eth',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.pools.trades.get(
"0x06da0fd433c1a5d7a4faa01111c044910a184553",
network="eth",
)
print(response.model_dump_json(indent=2))
```
# Multiple Pools Data by Pool Addresses
Source: https://docs.coingecko.com/demo/reference/pools-addresses
openapi-specs/demo-api.json get /onchain/networks/{network}/pools/multi/{addresses}
To query multiple pools based on the provided network and pool addresses
#### Notes
* Addresses not found in GeckoTerminal will be ignored.
* Supports up to **30 pool addresses** per request. [Analyst plan or above](https://www.coingecko.com/en/api/pricing) supports up to 50.
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate. Verified market cap is sourced from CoinGecko and may exceed FDV if it includes tokens on other networks.
* Use `include` to return related attributes under the top-level `included` key.
* `locked_liquidity_percentage` is updated daily.
* Set `include_composition=true` to surface balance and liquidity of base and quote tokens.
* Bonding curve pools (non-graduated launchpad pools) return a `launchpad_details` object with graduation status.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.pools.multi.getAddresses('0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640', {
network: 'eth',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.pools.multi.get_addresses(
"0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
network="eth",
)
print(response.model_dump_json(indent=2))
```
# Price
Source: https://docs.coingecko.com/demo/reference/price-overview
Current prices for coins and tokens by ID, symbol, name, or contract address.
| Endpoint | Description |
| ---------------------------------------------------------------- | -------------------------------------------------------------------- |
| [/simple/price](/demo/reference/simple-price) | Query prices of one or more coins by Coin API IDs, symbols, or names |
| [/simple/token\_price/\{id}](/demo/reference/simple-token-price) | Query one or more token prices by token contract addresses |
# Crypto Treasury Holdings by Entity ID
Source: https://docs.coingecko.com/demo/reference/public-treasury-entity
openapi-specs/demo-api.json get /public_treasury/{entity_id}
To query public companies' and governments' cryptocurrency holdings by entity ID
Equivalent page on [CoinGecko Bitcoin Treasuries](https://www.coingecko.com/en/treasuries/bitcoin).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.publicTreasury.getEntityID('strategy');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.public_treasury.get_entity_id("strategy")
print(response.model_dump_json(indent=2))
```
# Crypto Treasury Holdings Historical Chart Data by ID
Source: https://docs.coingecko.com/demo/reference/public-treasury-entity-chart
openapi-specs/demo-api.json get /public_treasury/{entity_id}/{coin_id}/holding_chart
To query historical cryptocurrency holdings chart of public companies and governments by entity ID and coin ID
#### Notes
* Find entity IDs via [Entities List](/demo/reference/entities-list) and coin IDs via [Coins List](/demo/reference/coins-list).
* Data available from August 2020 onwards.
* Historical access varies by plan:
| Plan | Maximum period | `days` values |
| ------------------ | -------------- | ----------------------------------- |
| Demo / Keyless API | 1 year | `7, 14, 30, 90, 180, 365` |
| Basic | 2 years | `7, 14, 30, 90, 180, 365, 730` |
| Analyst and above | Full | `7, 14, 30, 90, 180, 365, 730, max` |
To access longer historical periods, subscribe to a [paid plan](https://www.coingecko.com/en/api/pricing).
* `include_empty_intervals=false` (default): only intervals with transactions. Set to `true` to return all intervals, filled with the most recent data.
* Equivalent page on [CoinGecko Strategy Treasury](https://www.coingecko.com/en/treasuries/companies/strategy).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.publicTreasury.getHoldingChart('bitcoin', {
entity_id: 'strategy',
days: '365',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.public_treasury.get_holding_chart(
"bitcoin",
entity_id="strategy",
days="365",
)
print(response.model_dump_json(indent=2))
```
# Public Treasury
Source: https://docs.coingecko.com/demo/reference/public-treasury-overview
Bitcoin and crypto holdings of public companies and governments, with holding charts and transaction history.
| Endpoint | Description |
| ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [/entities/list](/demo/reference/entities-list) | Query all supported entities with entity ID, name, symbol, and country |
| [/\{entity}/public\_treasury/\{coin\_id}](/demo/reference/companies-public-treasury) | Query public companies' and governments' crypto holdings by coin ID |
| [/public\_treasury/\{entity\_id}](/demo/reference/public-treasury-entity) | Query public companies' and governments' crypto holdings by entity ID |
| [/public\_treasury/\{entity\_id}/\{coin\_id}
/holding\_chart](/demo/reference/public-treasury-entity-chart) | Historical crypto holdings chart by entity ID and coin ID |
| [/public\_treasury/\{entity\_id}
/transaction\_history](/demo/reference/public-treasury-transaction-history) | Crypto transaction history by entity ID |
# Crypto Treasury Transaction History by Entity ID
Source: https://docs.coingecko.com/demo/reference/public-treasury-transaction-history
openapi-specs/demo-api.json get /public_treasury/{entity_id}/transaction_history
To query public companies' and governments' cryptocurrency transaction history by entity ID
#### Notes
* Find entity IDs via [Entities List](/demo/reference/entities-list). Filter by coin using `coin_ids` (comma-separated), with IDs from [Coins List](/demo/reference/coins-list).
* Data available from August 2020 onwards.
* Equivalent page on [CoinGecko Strategy Treasury](https://www.coingecko.com/en/treasuries/companies/strategy).
Multi-page access (`page` > `1`) is exclusive to Analyst plan and above. Subscribe to a [paid plan](https://www.coingecko.com/en/api/pricing) to access.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.publicTreasury.getTransactionHistory('strategy');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.public_treasury.get_transaction_history("strategy")
print(response.model_dump_json(indent=2))
```
# Real World Assets (RWA)
Source: https://docs.coingecko.com/demo/reference/rwa-overview
Aggregated onchain market data for tokenized stocks, commodities and ETFs, their tokens and issuers.
| Endpoint | Description |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [/rwas/list](/demo/reference/rwas-list) | Query all supported tokenized real world assets (RWAs) with RWA ID, name and symbol |
| [/rwas/markets](/demo/reference/rwas-markets) | Query all supported RWAs with price, market cap, volume and market data |
| [/rwas/\{id}](/demo/reference/rwas-id) | Query all metadata, market data and tokens of an RWA by RWA ID |
| [/rwas/issuers/list](/demo/reference/rwas-issuers-list) | Query all supported RWA issuers with issuer ID and name |
| [/rwas/issuers/\{id}](/demo/reference/rwas-issuers-id) | Query market data and tokens of an RWA issuer by issuer ID |
# RWA Data by ID
Source: https://docs.coingecko.com/demo/reference/rwas-id
openapi-specs/demo-api.json get /rwas/{id}
To query all the metadata, market data and tokens of a RWA based on a particular RWA ID
#### Notes
* Find an RWA's API ID via [RWA List](/demo/reference/rwas-list).
* Returns metadata only by default — set `tokens` and `tokenized_market_data` to `true` to include those objects.
* Each `tokens.id` is also a coin ID. Use it with [Coin Data by ID](/demo/reference/coins-id) to query the individual token.
`tokenized_market_data` reflects the aggregated onchain tokenized market, not the underlying asset's spot market. All values are in USD.
# RWA Issuer Data by ID
Source: https://docs.coingecko.com/demo/reference/rwas-issuers-id
openapi-specs/demo-api.json get /rwas/issuers/{id}
To query the market data (market cap, volume, etc.) and tokens of an issuer based on a particular issuer ID
#### Notes
* Find an issuer's API ID via [RWA Issuers List](/demo/reference/rwas-issuers-list).
* Each `tokens.id` is also a coin ID. Use it with [Coin Data by ID](/demo/reference/coins-id) to query the individual token.
`market_cap`, `market_cap_change_24h`, and `volume_24h` are aggregated across the tokens issued by this issuer. All values are in USD.
# RWA Issuers List
Source: https://docs.coingecko.com/demo/reference/rwas-issuers-list
openapi-specs/demo-api.json get /rwas/issuers/list
To query all the supported RWA issuers on CoinGecko
#### Notes
* Use this endpoint to get issuer IDs for endpoints that require an `issuer` parameter, such as [RWA List with Market Data](/demo/reference/rwas-markets).
* No pagination required — the full list is returned in a single response.
# RWA List
Source: https://docs.coingecko.com/demo/reference/rwas-list
openapi-specs/demo-api.json get /rwas/list
To query all the supported tokenized real world assets (RWAs) on CoinGecko with RWA ID, name and symbol
#### Notes
* Use this endpoint to get RWA IDs for other endpoints that require an `id` parameter.
* Returns all RWAs by default. Use `asset_type` to filter for a single type.
* No pagination required — the full list is returned in a single response.
* Equivalent page on [CoinGecko Real World Assets](https://www.coingecko.com/en/real-world-assets).
# RWA List with Market Data
Source: https://docs.coingecko.com/demo/reference/rwas-markets
openapi-specs/demo-api.json get /rwas/markets
To query all the supported RWAs with price, market cap, volume and market related data
#### Notes
* Filter by `ids`, `names`, or `symbols`. When multiple are provided, priority is: `ids` > `names` > `symbols`.
* URL-encode spaces in `names` (e.g. `Micron%20Technology`).
* Maximum of **250** IDs per request. Wildcard searches are not supported.
* Use `per_page` and `page` to paginate results.
* Equivalent page on [CoinGecko Real World Assets](https://www.coingecko.com/en/real-world-assets).
Filter by issuer using the `issuer` param — refer to [RWA Issuers List](/demo/reference/rwas-issuers-list) for available values.
`tokenized_market_data` reflects the aggregated onchain tokenized market, not the underlying asset's spot market. All values are in USD.
# Search & ID Map
Source: https://docs.coingecko.com/demo/reference/search-and-id-map-overview
Search coins, categories and markets, and look up the coin, asset platform and currency IDs other endpoints require.
| Endpoint | Description |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| [/search](/demo/reference/search-data) | Search for coins, categories and markets on CoinGecko |
| [/coins/list](/demo/reference/coins-list) | Query all supported coins with coin ID, name and symbol |
| [/asset\_platforms](/demo/reference/asset-platforms-list) | Query all supported asset platforms (blockchain networks) |
| [/token\_lists/\{asset\_platform\_id}/all.json](/demo/reference/token-lists) | Full list of tokens on a blockchain network supported by Ethereum token list standard |
| [/simple/supported\_vs\_currencies](/demo/reference/simple-supported-currencies) | Query all supported currencies on CoinGecko |
# Search Queries
Source: https://docs.coingecko.com/demo/reference/search-data
openapi-specs/demo-api.json get /search
To search for coins, categories and markets listed on CoinGecko
Results are sorted by market cap in descending order.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.search.get({
query: 'bitcoin',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.search.get(
query="bitcoin",
)
print(response.model_dump_json(indent=2))
```
# Search Pools & Tokens
Source: https://docs.coingecko.com/demo/reference/search-pools
openapi-specs/demo-api.json get /onchain/search/pools
To search for pools across all networks by pool address, token name, token symbol, or token contract address
#### Notes
* Search by pool address, token name, token symbol, or token contract address.
* Returns up to 20 pools per page. Use the `page` param to navigate more results. Pagination beyond 10 pages requires [Analyst plan or above](https://www.coingecko.com/en/api/pricing).
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate.
* Use `include` to return related attributes under the top-level `included` key.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.search.pools.get({
query: 'weth',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.search.pools.get(
query="weth",
)
print(response.model_dump_json(indent=2))
```
# Coin Price by IDs, Symbols, or Names
Source: https://docs.coingecko.com/demo/reference/simple-price
openapi-specs/demo-api.json get /simple/price
To query the prices of one or more coins by using their unique Coin API IDs, symbols, or names
#### Notes
* You can look up coins by `ids`, `names`, or `symbols`. When multiple are provided, priority is: `ids` > `names` > `symbols`.
* Find a coin's API ID on its [CoinGecko](https://www.coingecko.com) page, via [Coins List](/demo/reference/coins-list), or this [Google Sheet](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
* Use `include_last_updated_at=true` or `include_24hr_change=true` (returns `null` if stale) to verify price freshness.
* `include_tokens=all` only works with `symbols` lookups, limited to 50 symbols per request.
* Maximum of **515** IDs per request. Wildcard searches are not supported.
* URL-encode spaces in `names` (e.g. `Binance%20Coin`).
Cross-check prices on [CoinGecko](https://www.coingecko.com) and learn about the [price methodology](https://www.coingecko.com/en/methodology).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.simple.price.get({
vs_currencies: 'usd',
ids: 'bitcoin',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.simple.price.get(
vs_currencies="usd",
ids="bitcoin",
)
print(response)
```
# Currencies List
Source: https://docs.coingecko.com/demo/reference/simple-supported-currencies
openapi-specs/demo-api.json get /simple/supported_vs_currencies
To query all the supported currencies on CoinGecko
Use this endpoint to get valid values for `vs_currencies` parameters in other endpoints like [Coin Price](/demo/reference/simple-price).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.simple.supportedVsCurrencies.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.simple.supported_vs_currencies.get()
print(response)
```
# Coin Price by Token Addresses
Source: https://docs.coingecko.com/demo/reference/simple-token-price
openapi-specs/demo-api.json get /simple/token_price/{id}
To query one or more token prices by using their token contract addresses
#### Notes
* Returns the global average price aggregated across all active exchanges on CoinGecko.
* Find a token's contract address on its [CoinGecko](https://www.coingecko.com) page or via [Coins List](/demo/reference/coins-list) with `include_platform=true`.
* Maximum of **515** contract addresses per request.
Cross-check prices on [CoinGecko](https://www.coingecko.com) and learn about the [price methodology](https://www.coingecko.com/en/methodology).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.simple.tokenPrice.getID('ethereum', {
contract_addresses: '0x2260fac5e5542a773aa44fbcfedf7c193bc2c599',
vs_currencies: 'usd',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.simple.token_price.get_id(
"ethereum",
contract_addresses="0x2260fac5e5542a773aa44fbcfedf7c193bc2c599",
vs_currencies="usd",
)
print(response)
```
# Token Data by Token Address
Source: https://docs.coingecko.com/demo/reference/token-data-contract-address
openapi-specs/demo-api.json get /onchain/networks/{network}/tokens/{address}
To query specific token data based on the provided token contract address on a network
#### Notes
* `total_reserve_in_usd` represents the total reserve of the requested token only across all its pools, not both tokens in a pair.
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate. Verified market cap is sourced from CoinGecko and may exceed FDV if it includes tokens on other networks.
* Use `include=top_pools` to include top pools data. Add `include_composition=true` to surface balance and liquidity of base and quote tokens (requires `include=top_pools`).
* Bonding curve tokens (non-graduated launchpad tokens) include a `launchpad_details` object with graduation status.
For token metadata (socials, websites, description), use [Token Info](/demo/reference/token-info-contract-address) instead.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.tokens.getAddress('0xdac17f958d2ee523a2206206994597c13d831ec7', {
network: 'eth',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.tokens.get_address(
"0xdac17f958d2ee523a2206206994597c13d831ec7",
network="eth",
)
print(response.model_dump_json(indent=2))
```
# Token Info by Token Address
Source: https://docs.coingecko.com/demo/reference/token-info-contract-address
openapi-specs/demo-api.json get /onchain/networks/{network}/tokens/{address}/info
To query token metadata (name, symbol, CoinGecko ID, image, socials, websites, description, etc.) based on a provided token contract address on a network
#### Notes
* Learn more about [GT Score](https://support.coingecko.com/hc/en-us/articles/38381394237593-What-is-GT-Score-How-is-GT-Score-calculated) and [GT Verified](https://support.coingecko.com/hc/en-us/articles/54413671274649-What-is-GT-Verified-Badge).
* `holders` data is currently in Beta, with ongoing improvements to coverage and update frequency.
| Chain | Network `id` |
| --------- | ------------- |
| Solana | `solana` |
| Ethereum | `eth` |
| Base | `base` |
| BNB Chain | `bsc` |
| Optimism | `optimism` |
| Arbitrum | `arbitrum` |
| Polygon | `polygon_pos` |
| TON | `ton` |
| Sui | `sui-network` |
| Robinhood | `robinhood` |
| Ronin | `ronin` |
| Bittensor | `bittensor` |
* `distribution_percentage` is based on total supply and includes all wallet types (CEX, treasury, etc.):
* Solana: `top_10`, `11_20`, `21_40`, `rest`
* Other chains: `top_10`, `11_30`, `31_50`, `rest`
* Bonding curve tokens (non-graduated launchpad tokens) include a `launchpad_details` object with graduation status.
- Metadata (image, websites, description, socials) is unvetted unless the token is [GT Verified](https://support.coingecko.com/hc/en-us/articles/54413671274649-What-is-GT-Verified-Badge) (`gt_verified: true`) or reviewed by CoinGecko.
- For CoinGecko-reviewed metadata, use [Coin Data by ID](/demo/reference/coins-id) or [Coin Data by Token Address](/demo/reference/coins-contract-address).
For token market data (price, supply, volume), use [Token Data](/demo/reference/token-data-contract-address) instead.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.tokens.info.get('Dfh5DzRgSvvCFDoYc2ciTkMrbDfRKybA4SoFbPmApump', {
network: 'solana',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.tokens.info.get(
"Dfh5DzRgSvvCFDoYc2ciTkMrbDfRKybA4SoFbPmApump",
network="solana",
)
print(response.model_dump_json(indent=2))
```
# Token Lists by Asset Platform ID
Source: https://docs.coingecko.com/demo/reference/token-lists
openapi-specs/demo-api.json get /token_lists/{asset_platform_id}/all.json
To get full list of tokens of a blockchain network (asset platform) that is supported by [Ethereum token list standard](https://tokenlists.org/)
A token is only included if its contract address has been added by the CoinGecko team. To request a missing token, [submit a request](https://support.coingecko.com/hc/en-us/requests/new).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.tokenLists.getAllJson('ethereum');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.token_lists.get_all_json("ethereum")
print(response.model_dump_json(indent=2))
```
# Tokens Data by Token Addresses
Source: https://docs.coingecko.com/demo/reference/tokens-data-contract-addresses
openapi-specs/demo-api.json get /onchain/networks/{network}/tokens/multi/{addresses}
To query multiple tokens data based on the provided token contract addresses on a network
#### Notes
* Addresses not found in GeckoTerminal will be ignored.
* Supports up to **30 contract addresses** per request. [Analyst plan or above](https://www.coingecko.com/en/api/pricing) supports up to 50.
* Returns the top most liquid pool per token.
* `total_reserve_in_usd` represents the total reserve of the requested token only across all its pools, not both tokens in a pair.
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate. Verified market cap is sourced from CoinGecko and may exceed FDV if it includes tokens on other networks.
* Use `include=top_pools` to include top pools data. Add `include_composition=true` to surface balance and liquidity of base and quote tokens (requires `include=top_pools`).
* Bonding curve tokens (non-graduated launchpad tokens) include a `launchpad_details` object with graduation status.
For token metadata (socials, websites, description), use [Token Info](/demo/reference/token-info-contract-address) instead.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.tokens.multi.getAddresses('6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN,2g4LS3y2myPe6vj9wTvoBE1wKqxvhnZPoZA9QU9upump', {
network: 'solana',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.tokens.multi.get_addresses(
"6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN,2g4LS3y2myPe6vj9wTvoBE1wKqxvhnZPoZA9QU9upump",
network="solana",
)
print(response.model_dump_json(indent=2))
```
# Most Recently Updated Tokens List
Source: https://docs.coingecko.com/demo/reference/tokens-info-recent-updated
openapi-specs/demo-api.json get /onchain/tokens/info_recently_updated
To query 100 most recently updated tokens info of a specific network or across all networks on GeckoTerminal
#### Notes
* Use `include=network` to include network data alongside the updated tokens list.
* Attributes specified in the `include` param will be returned under the top-level `included` key.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.tokens.infoRecentlyUpdated.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.tokens.info_recently_updated.get()
print(response.model_dump_json(indent=2))
```
# Top Pools by Token Address
Source: https://docs.coingecko.com/demo/reference/top-pools-contract-address
openapi-specs/demo-api.json get /onchain/networks/{network}/tokens/{token_address}/pools
To query top pools based on the provided token contract address on a network
#### Notes
* Top pools are ranked by a combination of liquidity (`reserve_in_usd`) and 24-hour trading volume (`volume_usd`).
* Returns up to 20 pools per page. Pagination beyond 10 pages requires [Analyst plan or above](https://www.coingecko.com/en/api/pricing).
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate.
* Use `include` to return related attributes under the top-level `included` key.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.tokens.pools.get('0xdac17f958d2ee523a2206206994597c13d831ec7', {
network: 'eth',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.tokens.pools.get(
"0xdac17f958d2ee523a2206206994597c13d831ec7",
network="eth",
)
print(response.model_dump_json(indent=2))
```
# Top Pools by DEX
Source: https://docs.coingecko.com/demo/reference/top-pools-dex
openapi-specs/demo-api.json get /onchain/networks/{network}/dexes/{dex}/pools
To query all the top pools based on the provided network and decentralized exchange (DEX)
#### Notes
* Returns up to 20 pools per page. Pagination beyond 10 pages requires [Analyst plan or above](https://www.coingecko.com/en/api/pricing).
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate.
* Use `include` to return related attributes under the top-level `included` key.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.dexes.getPools('sushiswap', {
network: 'eth',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.dexes.get_pools(
"sushiswap",
network="eth",
)
print(response.model_dump_json(indent=2))
```
# Top Pools by Network
Source: https://docs.coingecko.com/demo/reference/top-pools-network
openapi-specs/demo-api.json get /onchain/networks/{network}/pools
To query all the top pools based on the provided network
#### Notes
* Returns up to 20 pools per page. Pagination beyond 10 pages requires [Analyst plan or above](https://www.coingecko.com/en/api/pricing).
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate.
* Use `include` to return related attributes under the top-level `included` key.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.pools.get('eth');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.pools.get("eth")
print(response.model_dump_json(indent=2))
```
# Trending
Source: https://docs.coingecko.com/demo/reference/trending-overview
Trending coins, NFTs and categories by search volume on CoinGecko in the last 24 hours.
| Endpoint | Description |
| --------------------------------------------------- | --------------------------------------------------------------------- |
| [/search/trending](/demo/reference/trending-search) | Query trending search coins, NFTs and categories in the last 24 hours |
# Trending Pools List
Source: https://docs.coingecko.com/demo/reference/trending-pools-list
openapi-specs/demo-api.json get /onchain/networks/trending_pools
To query all the trending pools across all networks on GeckoTerminal
#### Notes
* Trending rankings are determined by:
* User engagement on GeckoTerminal
* Market activity (volume, transactions)
* Pool security (liquidity, honeypot checks)
* Returns up to 20 pools per page. Pagination beyond 10 pages requires [Analyst plan or above](https://www.coingecko.com/en/api/pricing).
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate.
* Use `include` to return related attributes under the top-level `included` key.
* Equivalent page on [GeckoTerminal](https://www.geckoterminal.com).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.trendingPools.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.trending_pools.get()
print(response.model_dump_json(indent=2))
```
# Trending Pools by Network
Source: https://docs.coingecko.com/demo/reference/trending-pools-network
openapi-specs/demo-api.json get /onchain/networks/{network}/trending_pools
To query the trending pools based on the provided network
#### Notes
* Trending rankings are determined by:
* User engagement on GeckoTerminal
* Market activity (volume, transactions)
* Pool security (liquidity, honeypot checks)
* Returns up to 20 pools per page. Pagination beyond 10 pages requires [Analyst plan or above](https://www.coingecko.com/en/api/pricing).
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate.
* Use `include` to return related attributes under the top-level `included` key.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.trendingPools.getNetwork('eth');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.trending_pools.get_network("eth")
print(response.model_dump_json(indent=2))
```
# Trending Search List
Source: https://docs.coingecko.com/demo/reference/trending-search
openapi-specs/demo-api.json get /search/trending
To query trending search coins, NFTs and categories on CoinGecko in the last 24 hours
#### Notes
* Default results:
* Top 15 trending coins (by most popular searches)
* Top 7 trending NFTs (by highest floor price change %)
* Top 5 trending categories (by most popular searches)
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.search.trending.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.search.trending.get()
print(response.model_dump_json(indent=2))
```
# Utility
Source: https://docs.coingecko.com/demo/reference/utility-overview
BTC exchange rates, API server status, and account credit and rate limit usage.
| Endpoint | Description |
| -------------------------------------------------- | ---------------------------------------------- |
| [/exchange\_rates](/demo/reference/exchange-rates) | Query BTC exchange rates with other currencies |
| [/ping](/demo/reference/ping-server) | Check API server status |
# AI Agents & LLM Apps
Source: https://docs.coingecko.com/docs/ai-agents-llm-apps
Build AI agents and LLM-powered apps with real-time crypto data from CoinGecko — MCP, SDK function calling, and prompt patterns
**TL;DR**
Connect via [MCP](/ai-integration/mcp-server) for zero-code data access, use the [SDK](/docs/sdk) for function calling in custom agents, and query [/simple/price](/reference/simple-price), [/search](/reference/search-data), [/search/trending](/reference/trending-search), and onchain endpoints for real-time context.
> Replace `YOUR_API_KEY` in the examples below with your actual key. [Get one here →](https://www.coingecko.com/en/api/pricing)
## Option 1: MCP Server (Zero-Code)
The fastest way to give an AI agent access to CoinGecko data. No SDK code needed — the agent calls tools directly through the [Model Context Protocol](/ai-integration/mcp-server).
```bash theme={null}
claude mcp add --transport http \
coingecko https://mcp.api.coingecko.com/mcp
```
For higher limits, use `https://mcp.pro-api.coingecko.com/mcp` and authenticate via `/mcp`.
Add to `~/.cursor/mcp.json` (or your IDE's MCP config):
```json theme={null}
{
"mcpServers": {
"coingecko": {
"command": "npx",
"args": ["mcp-remote", "https://mcp.api.coingecko.com/mcp"]
}
}
}
```
```python theme={null}
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
async with streamablehttp_client(
"https://mcp.api.coingecko.com/mcp"
) as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
tools = await session.list_tools()
```
> Full setup for all platforms: [CoinGecko MCP →](/ai-integration/mcp-server) | [MCP Tools →](/ai-integration/mcp-tools)
Let your agent search CoinGecko documentation for endpoint details and parameter info.
```bash theme={null}
claude mcp add --transport http \
coingecko-docs https://docs.coingecko.com/mcp
```
> [Docs MCP →](/ai-integration/docs-mcp)
The agent now has access to 85+ CoinGecko tools. Try:
* *"What's the current price of Bitcoin, Ethereum, and Solana?"*
* *"Show me the top 10 trending pools on Base"*
* *"Find all tokens related to 'AI' and get their market data"*
***
## Option 2: SDK Function Calling (Custom Agents)
For custom AI agents where you control the tool definitions and execution flow — use the SDK as the function calling backend.
```bash Python theme={null}
pip install coingecko_sdk
```
```bash TypeScript theme={null}
npm install @coingecko/coingecko-typescript
```
```python Python theme={null}
import os
from coingecko_sdk import Coingecko
client = Coingecko(
pro_api_key=os.environ.get("COINGECKO_PRO_API_KEY"),
environment="pro", # or "demo" with demo_api_key
)
```
```typescript TypeScript theme={null}
import Coingecko from '@coingecko/coingecko-typescript';
const client = new Coingecko({
proAPIKey: process.env['COINGECKO_PRO_API_KEY'],
environment: 'pro', // or 'demo' with demoAPIKey
});
```
> Full SDK setup: [Python →](/docs/sdk-python) | [TypeScript →](/docs/sdk-typescript)
Map SDK methods to tool definitions your LLM can call. Example tool schema:
```json theme={null}
{
"name": "get_crypto_price",
"description": "Get current prices for one or more cryptocurrencies",
"parameters": {
"type": "object",
"properties": {
"ids": {
"type": "string",
"description": "Comma-separated CoinGecko coin IDs (e.g. bitcoin,ethereum)"
},
"vs_currencies": {
"type": "string",
"description": "Comma-separated target currencies (e.g. usd,eur)"
}
},
"required": ["ids", "vs_currencies"]
}
}
```
When the LLM returns a tool call, execute it against the SDK:
```python Python theme={null}
def execute_tool(name, args):
if name == "get_crypto_price":
return client.simple.price.get(**args)
elif name == "search_coins":
return client.search.get(**args)
elif name == "get_trending":
return client.search.trending.get()
```
```typescript TypeScript theme={null}
async function executeTool(name: string, args: Record) {
if (name === 'get_crypto_price') {
return client.simple.price.get(args);
} else if (name === 'search_coins') {
return client.search.get(args);
} else if (name === 'get_trending') {
return client.search.trending.get();
}
}
```
> All available methods: [TypeScript →](/docs/sdk-typescript-methods) | [Python →](/docs/sdk-python-methods)
***
## Key Endpoints for AI Agents
The most useful endpoints for agent tool definitions — each maps to a common user intent.
| Intent | Endpoint | What it returns |
| ----------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------- |
| "What's the price of X?" | [/simple/price](/reference/simple-price) | Spot prices with optional market cap, volume, 24h change |
| "Find tokens matching Y" | [/search](/reference/search-data) | Coins, categories, and markets matching a query |
| "What's trending?" | [/search/trending](/reference/trending-search) | Top trending coins, NFTs, and categories (24h) |
| "Show me market data" | [/coins/markets](/reference/coins-markets) | Bulk market data — rankings, sparklines, price changes |
| "Price of this token address" | [/onchain/.../token\_price](/reference/onchain-simple-price) | Onchain token price by contract address |
| "Token info for address" | [/onchain/.../tokens/\{addr}](/reference/token-data-contract-address) | Token metadata, price, volume, and top pools |
| "Trending DEX pools" | [/onchain/.../trending\_pools](/reference/trending-pools-list) | Hottest liquidity pools across all networks |
Use [/search](/reference/search-data) as your agent's **resolver** — when a user mentions a coin by name or symbol, search first to get the correct CoinGecko ID, then pass it to other endpoints.
***
## Prompt Engineering Tips
* **Always resolve IDs first.** Coin names are ambiguous — use `/search` or `/coins/list` to resolve to a CoinGecko ID before querying price or market data.
* **Include units in responses.** When returning prices, always include the currency (e.g. "\$67,432 USD" not just "67432").
* **Handle missing data.** Not all coins have market cap, volume, or contract addresses. Instruct your agent to check for null fields.
* **Rate limit awareness.** Tell your agent to batch requests where possible (e.g. `ids=bitcoin,ethereum,solana` in one call instead of three).
AI prompt rules for generating correct CoinGecko SDK code.
# API Status
Source: https://docs.coingecko.com/docs/api-status
Live status, incident history, and uptime for the CoinGecko API
Current API health and active incidents.
Past incidents and maintenance events.
Historical uptime by month.
![]()
* Subscribe to status updates via Email, Slack, or Discord.
* Use **Select services** to filter by Public or Pro API.
# Common Use Cases
Source: https://docs.coingecko.com/docs/common-use-cases
Step-by-step guides for building with the CoinGecko API — trading, portfolio tracking, market research, and more
Thousands of projects use the CoinGecko API across:
| | |
| ------------------------ | --------------------------------------------------------------------- |
| **Trading & Exchanges** | CEX/DEX platforms, trading bots, backtesting engines |
| **Wallets & Portfolios** | Hot/cold wallets, portfolio trackers, block explorers |
| **Analytics & Research** | Screeners, dashboards, VC/institutional research |
| **DeFi & Onchain** | DeFi protocols, DEX aggregators, NFT marketplaces, security platforms |
| **AI & Automation** | AI agents, DeFAI apps, oracles, bots |
| **Finance & Compliance** | Accounting, tax, audit, payroll, RWA platforms |
Pick the guide that matches what you're building:
Spot prices, OHLC candles, backtesting, and onchain DEX data.
Live valuation, cost basis, and performance charts.
Fundamentals, trending data, sector analysis, and onchain analytics.
Tokens, pools, trades, OHLCV, and holder distribution onchain.
Tax event prices, OHLC benchmarks, and NAV snapshots.
MCP server, SDK function calling, and prompt patterns for AI agents.
# Compliance & Reporting
Source: https://docs.coingecko.com/docs/compliance-reporting
Build tax reporting, fund accounting, and audit pipelines with timestamped historical prices from CoinGecko API
**TL;DR**
Use [/coins/\{id}/history](/reference/coins-id-history) for point-in-time tax event prices, [/coins/\{id}/market\_chart/range](/reference/coins-id-market-chart-range) for historical time series, [/coins/\{id}/ohlc/range](/reference/coins-id-ohlc-range) for OHLC benchmarks, and [/simple/price](/reference/simple-price) with `include_last_updated_at` for timestamped NAV snapshots.
> Replace `YOUR_API_KEY` in the examples below with your actual key. [Get one here →](https://www.coingecko.com/en/api/pricing)
## Pipeline Setup
Build a lookup table mapping your internal identifiers to CoinGecko coin IDs and contract addresses.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/coins/list?include_platform=true" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Coins List →](/reference/coins-list)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/coins/list?include_platform=true" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Coins List →](/demo/reference/coins-list)
| Key param | Use |
| ------------------ | ------------------------------------------------------------------------------------- |
| `include_platform` | Include contract addresses per platform — essential for reconciling tokens by address |
Confirm your reporting currencies are supported before building queries.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/simple/supported_vs_currencies" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Supported Currencies →](/reference/simple-supported-currencies)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/simple/supported_vs_currencies" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Supported Currencies →](/demo/reference/simple-supported-currencies)
Cache this list at pipeline startup. Unsupported currencies return empty results without an error.
***
## Historical Data
Fair market value at a specific date — the core endpoint for tax reporting and trade reconciliation.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/coins/bitcoin/history?date=15-04-2024&localization=false" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Coin Historical Data →](/reference/coins-id-history)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/coins/bitcoin/history?date=15-04-2024&localization=false" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Coin Historical Data →](/demo/reference/coins-id-history)
Prices are returned in all supported fiat currencies simultaneously — no separate calls needed for multi-jurisdiction reports.
The `date` parameter uses **dd-mm-yyyy** format (not ISO). Data is a snapshot at **00:00:00 UTC**.
Price, market cap, and volume as `[timestamp, value]` arrays for a custom date range — maps directly to database columns.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/coins/bitcoin/market_chart/range?vs_currency=usd&from=2024-01-01&to=2024-12-31&interval=daily" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Market Chart Range →](/reference/coins-id-market-chart-range)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/coins/bitcoin/market_chart/range?vs_currency=usd&from=2024-01-01&to=2024-12-31&interval=daily" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Market Chart Range →](/demo/reference/coins-id-market-chart-range)
| Key param | Use |
| ------------- | ---------------------------------------------------------------- |
| `from` / `to` | ISO dates or UNIX timestamps |
| `interval` | `daily` or `hourly` for consistent data points, or omit for auto |
For tokens tracked by contract address, use [Contract Market Chart Range](/reference/contract-address-market-chart-range) — same schema, queried by address instead of coin ID.
Daily or hourly OHLC candles for a custom date range — use closing price as end-of-day valuation, or open/close spread for volatility reporting.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/coins/ethereum/ohlc/range?vs_currency=usd&from=2024-01-01&to=2024-03-31&interval=daily" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [OHLC Range →](/reference/coins-id-ohlc-range)
`/coins/{id}/ohlc/range` is not available on the Demo API.
[Upgrade to Pro →](https://www.coingecko.com/en/api/pricing)
Response format: `[timestamp, open, high, low, close]` — consistent five-element arrays.
For simpler lookbacks without custom date ranges, use [/coins/\{id}/ohlc](/reference/coins-id-ohlc) with a `days` parameter.
***
## Daily Snapshots
Current prices with `last_updated_at` — the audit timestamp confirming when CoinGecko last updated the price.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/simple/price?ids=bitcoin,ethereum,solana&vs_currencies=usd,eur&include_market_cap=true&include_last_updated_at=true" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Simple Price →](/reference/simple-price)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/simple/price?ids=bitcoin,ethereum,solana&vs_currencies=usd,eur&include_market_cap=true&include_last_updated_at=true" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Simple Price →](/demo/reference/simple-price)
```json theme={null}
{
"bitcoin": {
"usd": 67432.51,
"eur": 63521.12,
"usd_market_cap": 1326789012345,
"last_updated_at": 1712345678
}
}
```
| Key param | Use |
| ------------------------- | ------------------------------------------ |
| `include_last_updated_at` | UNIX timestamp — critical for audit trails |
| `include_market_cap` | AUM and exposure reporting |
| `precision` | Consistent decimal formatting |
Schedule this call daily for end-of-day NAV records.
# Pay with Crypto
Source: https://docs.coingecko.com/docs/crypto-payment
Pay for a CoinGecko API subscription with crypto (USDC, USDT, and more)
You can now pay for a CoinGecko API subscription with crypto instead of a card. The option shows up when you're on an **annual Analyst plan or above** and don't have an active subscription already.
## Which chains and tokens are supported
* Payment runs across six chains:
**Solana**, **Ethereum**, **Base**, **Polygon**, **Arbitrum**, and **BNB Chain**
* **USDC** and **USDT** are supported on every chain, and the complete list of accepted tokens per chain appears at checkout.
Payments settle onchain, so **gas fees apply on top of the subscription price**.
Please leave enough in your wallet to cover them.
## How to pay with crypto
Start at [coingecko.com/en/api/pricing](https://www.coingecko.com/en/api/pricing)
Crypto appears alongside card as a payment method.
Select it, then fill in your checkout details as usual.
![CoinGecko checkout modal with Cryptocurrency selected as the payment method, showing supported tokens and a notice about non-refundable payments, unsupported plan changes, and no overage]()
Pick your chain and token, then confirm the transaction in your wallet.
![Helio checkout screen showing a $1,238 USDC yearly subscription payment on Solana, with options to connect a wallet or pay with QR code]()
## Do crypto subscriptions renew automatically
There's no card on file to charge, so renewing means running through checkout again before your subscription expires.
We send renewal reminders at:
* **14 days** before expiry
* **7 days** before expiry
If payment doesn't land before expiry, API access pauses until you renew.
Onchain confirmations take time. Renew a few days early so you don't get caught by network congestion.
## Limitations of paying with crypto
No monthly billing option for crypto.
Crypto-paid plans can't run over their included usage.
You can cancel, but not change plans mid-subscription.
All crypto payments are final.
## FAQ
Your plan activates as soon as the onchain transaction confirms — full API access starts immediately, no manual approval needed.
You can't self-serve that change — [contact support](https://support.coingecko.com) to move over.
***
Questions about crypto payment, stuck transactions, or renewal timing?
# Data Delivery Methods
Source: https://docs.coingecko.com/docs/data-delivery-methods
REST API, WebSocket, and Webhooks — choose the right method for your use case
Three ways to access CoinGecko data. Pick the one that fits your application — or combine them.
![Diagram showing three data delivery methods: REST API uses HTTP request-response, WebSocket maintains a persistent connection, and Webhook sends event-driven HTTP callbacks]()
| | REST API | WebSocket | Webhooks NEW |
| ----------------- | -------------------------- | ----------------------- | ------------------------ |
| **Communication** | Request → Response | Persistent connection | Event-driven callback |
| **Data flow** | You pull | Pushed to you | Pushed to you |
| **Latency** | Per-request | Real-time | Near real-time |
| **Use case** | On-demand queries, polling | Live streaming, trading | Reacting to data changes |
Tell us how you use CoinGecko's data delivery methods and what you'd like to see next.
***
## REST API — You ask, we answer
Send an HTTP request, get a JSON response. The simplest way to query prices, market data, historical charts, and more.
```bash Pro API theme={null}
curl "https://pro-api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
```bash Demo API theme={null}
curl "https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
* On-demand data fetches (prices, coin info, historical charts)
* Periodic polling on a schedule
* Backfilling or one-time data pulls
* Prototyping and quick integrations
* 50+ endpoints on Demo & Basic plans
* 80+ endpoints on Analyst plan & above
* Prices, market data, exchanges, NFTs, onchain DEX data, and more
Available on **all plans**, including the free Demo plan.
Browse all available endpoints across CoinGecko and Onchain APIs.
***
## WebSocket — Stream data in real time
A persistent connection that pushes updates to your application as they happen. Subscribe once, receive continuous data — no repeated requests.
* Live price tickers and trading dashboards
* Real-time DEX trade monitoring
* Streaming OHLCV candlestick charts
* Any application where latency matters
* `C1` — CoinGecko coin prices
* `G1` — Onchain token prices
* `G2` — Onchain trades
* `G3` — Onchain OHLCV candles
Requires [Basic plan & above](https://www.coingecko.com/en/api/pricing).
Stream real-time prices, trades, and OHLCV data.
***
## Webhooks — Get notified when data changes
Event-driven callbacks that push notifications to your server when specific changes happen on CoinGecko — no polling required.
* Keeping your database in sync with CoinGecko
* Reacting to coin metadata changes (rebrands, new chains, alerts)
* Compliance and risk monitoring
* Replacing cron jobs with event-driven updates
* `cg.coin.info.updated` — coin metadata changes across all active coins
* `cg.coin.price.updated` — price target alerts *(Private Beta)*
* `cg.coin.listed` — new token listings *(Private Beta)*
Requires [Basic plan & above](https://www.coingecko.com/en/api/pricing).
Set up event-driven notifications for coin data changes.
***
## Plan Access
| | REST API | WebSocket | Webhooks NEW |
| ------------------- | :-----------: | :--------------: | :---------------------: |
| **Demo** (Free) | 50+ endpoints | — | — |
| **Basic** | 50+ endpoints | ✅ 5 sockets | ✅ 1 endpoint |
| **Analyst & above** | 80+ endpoints | ✅ 10 sockets | ✅ 5 endpoints |
| **Enterprise** | 80+ endpoints | ✅ Custom | ✅ Custom |
| **Credit cost** | 1 per call | 0.1 per response | 10 per event |
Not sure which plan to choose? Check out the [pricing page](https://www.coingecko.com/en/api/pricing) for a full breakdown.
## Which Method Should You Use?
Use **REST API** to fetch prices and historical data on a schedule. Add **WebSocket** if you need live price updates on a dashboard.
Use **WebSocket** for real-time price feeds and trade data. Supplement with **REST API** for reference data like coin metadata or historical OHLC.
Use **Webhooks** to receive notifications when data changes — no constant polling. Use **REST API** to backfill or fetch full records on demand.
Start with **REST API** — available on all plans including the free Demo. Add WebSocket or Webhooks later as your needs grow.
***
Tell us how you use CoinGecko's data delivery methods and what you'd like to see next.
![Pay for your CoinGecko API subscription with crypto]()
# DeFi & Onchain Analytics
Source: https://docs.coingecko.com/docs/defi-onchain-analytics
Analyze onchain tokens, pools, trades, and holder distribution across 200+ networks from CoinGecko API
**TL;DR**
Use [/onchain/.../token\_price](/reference/onchain-simple-price) for onchain pricing, [/onchain/.../pools/.../ohlcv](/reference/pool-ohlcv-contract-address) for DEX charts, [/onchain/.../pools/.../trades](/reference/pool-trades-contract-address) for trade history, and [/onchain/.../tokens/.../top\_holders](/reference/top-token-holders-token-address) for wallet distribution.
> Replace `YOUR_API_KEY` in the examples below with your actual key. [Get one here →](https://www.coingecko.com/en/api/pricing)
## Token Analytics
Real-time prices for any onchain token by contract address — including tokens not listed on CoinGecko. Batch multiple addresses in one call.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/onchain/simple/networks/eth/token_price/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48,0x6b175474e89094c44da98b954eedeac495271d0f" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Onchain Simple Price →](/reference/onchain-simple-price)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/onchain/simple/networks/eth/token_price/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48,0x6b175474e89094c44da98b954eedeac495271d0f" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Onchain Simple Price →](/demo/reference/onchain-simple-price)
Use [/onchain/networks](/reference/networks-list) to get the full list of 200+ supported network IDs.
Price, volume, FDV, market cap, price changes, and transaction counts for a token.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/onchain/networks/eth/tokens/0x6982508145454ce325ddbe47a25d4ec3d2311933?include=top_pools" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Token Data →](/reference/token-data-contract-address)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/onchain/networks/eth/tokens/0x6982508145454ce325ddbe47a25d4ec3d2311933?include=top_pools" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Token Data →](/demo/reference/token-data-contract-address)
| Key param | Use |
| --------- | ------------------------------------------------------- |
| `include` | `top_pools` to see the most active pools for this token |
Description, socials, websites, CoinGecko ID, and GeckoTerminal analytics score.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/onchain/networks/eth/tokens/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/info" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Token Info →](/reference/token-info-contract-address)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/onchain/networks/eth/tokens/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/info" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Token Info →](/demo/reference/token-info-contract-address)
The `coingecko_coin_id` field bridges onchain data to CoinGecko's main API — use it with [/coins/\{id}](/reference/coins-id) for community and developer metrics.
***
## Pool Discovery & Liquidity
Reserve (TVL), volume, price, transaction counts, and price changes for a specific pool.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/onchain/networks/eth/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640?include=base_token,quote_token,dex" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Pool Data →](/reference/pool-address)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/onchain/networks/eth/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640?include=base_token,quote_token,dex" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Pool Data →](/demo/reference/pool-address)
`reserve_in_usd` is your liquidity indicator — total value locked in the pool.
Hottest liquidity pools across all networks — spot early DeFi momentum.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/onchain/networks/trending_pools?include=base_token,dex,network&duration=24h" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Trending Pools →](/reference/trending-pools-list) | [By Network →](/reference/trending-pools-network)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/onchain/networks/trending_pools?include=base_token,dex,network&duration=24h" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Trending Pools →](/demo/reference/trending-pools-list) | [By Network →](/demo/reference/trending-pools-network)
| Key param | Use |
| ---------- | ---------------------------------------------------------------- |
| `include` | `base_token`, `quote_token`, `dex`, `network` for richer context |
| `duration` | `1h`, `6h`, or `24h` trending window |
Filter pools by volume, liquidity, age, network, DEX, and more — the most powerful pool discovery endpoint.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/onchain/pools/megafilter?networks=eth,solana&volume_24h_usd_min=100000&reserve_usd_min=50000&sort=volume_24h_usd_desc" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Pools Megafilter →](/reference/pools-megafilter)
`/onchain/pools/megafilter` is not available on the Demo API.
[Upgrade to Pro →](https://www.coingecko.com/en/api/pricing)
| Key param | Use |
| ---------------------------- | ----------------------------------------------- |
| `networks` | Filter by chains (e.g. `eth,solana,base`) |
| `volume_24h_usd_min` / `max` | Volume thresholds |
| `reserve_usd_min` / `max` | Liquidity depth |
| `pool_age_min` / `max` | Pool age in hours — find new pools |
| `sort` | `volume_24h_usd_desc`, `reserve_usd_desc`, etc. |
***
## DEX Charts & Trades
OHLCV for a specific pool with `second`, `minute`, `hour`, and `day` timeframes.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/onchain/networks/eth/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640/ohlcv/minute?aggregate=5&limit=100¤cy=usd" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Pool OHLCV →](/reference/pool-ohlcv-contract-address)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/onchain/networks/eth/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640/ohlcv/minute?aggregate=5&limit=100¤cy=usd" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Pool OHLCV →](/demo/reference/pool-ohlcv-contract-address)
Response format: `[timestamp, open, high, low, close, volume]`.
| Key param | Use |
| ----------- | ----------------------------------------------------- |
| `aggregate` | Combine candles — `5` for 5-min, `4` for 4-hour |
| `limit` | Up to 1000 data points |
| `currency` | `usd` for fiat or `token` for base-token denomination |
Same format as pool OHLCV, but aggregated across all pools for a token — broader market view.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/onchain/networks/eth/tokens/0x6982508145454ce325ddbe47a25d4ec3d2311933/ohlcv/day?aggregate=1&limit=30¤cy=usd" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Token OHLCV →](/reference/token-ohlcv-token-address)
`/onchain/.../tokens/.../ohlcv` is not available on the Demo API.
[Upgrade to Pro →](https://www.coingecko.com/en/api/pricing)
Pool OHLCV reflects a single pool's price action. Token OHLCV aggregates across all pools — use it for a broader market view.
Recent swap activity for a specific pool — monitor execution or trigger alerts on large trades.
On **Analyst & above**, set `trading_period` to `7d` or `30d` to look further back than the 24-hour default, and page through the results with `cursor`.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/onchain/networks/eth/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640/trades?trade_volume_in_usd_greater_than=10000" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Pool Trades →](/reference/pool-trades-contract-address)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/onchain/networks/eth/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640/trades?trade_volume_in_usd_greater_than=10000" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Pool Trades →](/demo/reference/pool-trades-contract-address)
Use [Token Trades](/reference/token-trades-contract-address) for a cross-pool view of all trading activity for a token (Pro only).
***
## Token Holder Analytics
Wallet addresses, balances, and ownership percentages for the largest holders. The `wallet_tag` field identifies known entities (exchanges, protocols, treasuries).
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/onchain/networks/eth/tokens/0x6982508145454ce325ddbe47a25d4ec3d2311933/top_holders" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Top Holders →](/reference/top-token-holders-token-address)
`/onchain/.../tokens/.../top_holders` is not available on the Demo API.
[Upgrade to Pro →](https://www.coingecko.com/en/api/pricing)
Historical holder count — rising count signals adoption, declining count may indicate distribution concerns.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/onchain/networks/eth/tokens/0x6982508145454ce325ddbe47a25d4ec3d2311933/holders_chart?timeframe=one_month" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Holders Chart →](/reference/token-holders-chart-token-address)
`/onchain/.../tokens/.../holders_chart` is not available on the Demo API.
[Upgrade to Pro →](https://www.coingecko.com/en/api/pricing)
Combine top holders with the holders chart — top holders shows current concentration, the chart reveals adoption trends over time.
# Endpoint Showcase
Source: https://docs.coingecko.com/docs/endpoint-showcase
See how CoinGecko API powers CoinGecko.com and GeckoTerminal.com
## CoinGecko
### [Home Page](https://www.coingecko.com)
![]()
1. [/global](/reference/crypto-global) — Global crypto stats: total market cap, 24h volume, BTC/ETH dominance.
2. [/search/trending](/reference/trending-search) — Trending coins, NFTs, and categories.
3. [/coins/top\_gainers\_losers](/reference/coins-top-gainers-losers) — Top gainers and losers.
4. [/coins/categories](/reference/coins-categories) — Category tabs and narratives.
5. [/coins/markets](/reference/coins-markets) — Coin rankings with price, volume, market cap, and sparkline.
6. * [/news](/reference/news) — Latest market news.
* [/insights](/reference/insights) — Coin insights.
### [Coin Page](https://www.coingecko.com/en/coins/bitcoin)
![]()
1. [/coins/\{id}](/reference/coins-id), [/simple/price](/reference/simple-price) — Coin price, 24h change, BTC price.
2. [/coins/\{id}](/reference/coins-id) — Market cap, FDV, volume, supply, info, links, and community.
3. * [/coins/\{id}/history](/reference/coins-id-history) — Historical price at a given date.
* [/coins/\{id}/market\_chart](/reference/coins-id-market-chart) — Line chart data.
* [/coins/\{id}/ohlc](/reference/coins-id-ohlc) — Candlestick chart data.
4. * [/news](/reference/news) — Coin-related news.
* [/insights](/reference/insights) — Coin insights.
### [Exchanges Page](https://www.coingecko.com/en/exchanges/hyperliquid-spot)
![]()
1. [/exchanges/\{id}](/reference/exchanges-id) — Exchange info: name, type, trading volume, and trust score.
2. [/exchanges/\{id}/volume\_chart](/reference/exchanges-id-volume-chart) — Historical volume chart.
3. [/exchanges/\{id}/tickers](/reference/exchanges-id-tickers) — Exchange trading pairs and tickers.
### [NFTs Page](https://www.coingecko.com/en/nft/pudgy-penguins)
![]()
1. [/nfts/\{id}](/reference/nfts-id) — NFT collection data: name, contract address, floor price, market cap, volume, and description.
2. [/nfts/\{id}/market\_chart](/reference/nfts-id-market-chart) — Historical market data chart.
3. [/nfts/\{id}/tickers](/reference/nfts-id-tickers) — Tickers across NFT marketplaces.
***
## GeckoTerminal
### [Home Page](https://www.geckoterminal.com)
![]()
1. [/onchain/search/pools](/reference/search-pools) — Search tokens, categories, chains, and DEXs.
2. [/onchain/networks](/reference/networks-list) — Supported blockchain networks.
3. [/onchain/categories](/reference/categories-list) — Trending categories.
4. [/onchain/networks/trending\_pools](/reference/trending-pools-list) — Top gainers by price change.
5. [/onchain/networks/new\_pools](/reference/latest-pools-list) — Recently created pools.
### [Chain Page](https://www.geckoterminal.com/eth/pools)
![]()
1. [/onchain/networks/\{network}/dexes](/reference/dexes-list) — DEXs on the network.
2. [/onchain/categories/\{category\_id}/pools](/reference/pools-category) — Trending categories and pools by category.
3. [/onchain/networks/\{network}/trending\_pools](/reference/trending-pools-network) — Top gainers on the network.
4. [/onchain/networks/\{network}/new\_pools](/reference/latest-pools-network) — New pools on the network.
5. [/onchain/networks/\{network}/pools](/reference/top-pools-network) — Top pools on the network.
### [Pool Page](https://www.geckoterminal.com/eth/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640)
![]()
1. Pool data and info:
* [/onchain/networks/\{network}/pools/\{address}](/reference/pool-address) — Price, volume, transactions, liquidity.
* [/onchain/networks/\{network}/pools/\{address}/info](/reference/pool-token-info-contract-address) — Name, symbol, image, description, GT Score.
2. [/onchain/networks/\{network}/pools/\{address}/ohlcv/\{timeframe}](/reference/pool-ohlcv-contract-address) — OHLCV candlestick chart.
3. [/onchain/networks/\{network}/pools/\{address}/trades](/reference/pool-trades-contract-address) — Recent trades.
4. [/onchain/networks/\{network}/tokens/\{address}/top\_holders](/reference/top-token-holders-token-address) — Token holders.
### [Categories Page](https://www.geckoterminal.com/category)
![]()
1. [/onchain/categories/\{category\_id}/pools](/reference/pools-category) — Pools within a specific category.
2. [/onchain/categories](/reference/categories-list) — Onchain categories with market data.
# Errors & Rate Limits
Source: https://docs.coingecko.com/docs/errors-and-rate-limits
HTTP status codes, CoinGecko error codes, and rate limit behavior
## Error Codes
### HTTP Status Codes
| Code | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `400` Bad Request | Invalid request — check your parameters. |
| `401` Unauthorized | Missing or invalid API key. |
| `403` Forbidden | Access blocked by the server. |
| `408` Timeout | Request took too long — usually caused by slow network on your end. |
| `429` Too Many Requests | Rate limit exceeded. Reduce call frequency or [upgrade your plan](https://www.coingecko.com/en/api/pricing). |
| `500` Internal Server Error | Unexpected server error. |
| `503` Service Unavailable | Check [status.coingecko.com](https://status.coingecko.com) for outages. |
| `1020` Access Denied | Blocked by CDN firewall rule. |
### CoinGecko Error Codes
| Code | Description |
| ----------------------- | ----------------------------------------------------------------------------------------------------------- |
| `10002` Missing API Key | No API key provided. Pro API requires `x_cg_pro_api_key`, Demo API requires `x_cg_demo_api_key`. |
| `10005` Plan Restricted | Endpoint not available on your plan. [View plans](https://www.coingecko.com/en/api/pricing). |
| `10010` Invalid API Key | Wrong key type. If using a Pro key, your root URL must be `pro-api.coingecko.com`. |
| `10011` Invalid API Key | Wrong key type. If using a Demo key, your root URL must be `api.coingecko.com`. |
| CORS Error | Server didn't return CORS headers. Proxy requests through your backend instead of calling from the browser. |
## Rate Limits
* **Paid plans:** Rate limit depends on your [plan](https://www.coingecko.com/en/api/pricing).
* **Demo plan:** 100 calls/min.
* **Keyless (no API key):** IP-based rate limiting — shared across all users on the same IP.
All requests count toward your per-minute rate limit — including `4xx` and `5xx` errors.
**Using the API via Google Sheets?**
Rate limit errors may occur due to shared IP addresses among Google Sheets users. For reliable performance, use a dedicated API key with a [paid plan](https://www.coingecko.com/en/api/pricing).
# CoinGecko for Microsoft Excel
Source: https://docs.coingecko.com/docs/excel
Pull live prices, historical data, NFT floors, onchain token prices, and market cap rankings into Excel with =CG. formulas
![]()
The add-in only communicates with the CoinGecko API using your saved API key. No personal data is sent to any third party.
## Quick Start
Search for **CoinGecko** in the Excel Add-ins store, or visit the [Microsoft Marketplace](https://marketplace.microsoft.com/en-us/product/office/WA200010662).
![]()
Go to **Home** > **CoinGecko** in the Excel ribbon.
Enter your [CoinGecko API key](https://www.coingecko.com/en/api/pricing) and click **Save Settings**. A green status dot confirms a valid connection.
![]()
## Formulas
All formulas use the `CG` namespace. Enter them in any cell like a standard Excel formula.
Use the **Coin ID** (e.g. `bitcoin`, `ethereum`) rather than the ticker symbol for the most reliable results.
* Find the coin ID in the URL on CoinGecko — e.g. `coingecko.com/en/coins/bitcoin`
* Browse the full list via [Coins List](/reference/coins-list) endpoint or this [Google Sheet](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?gid=0#gid=0)
***
### `=CG.PRICE(id)`
Returns the **current USD price** of a coin.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | string | [Coin ID](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?gid=0#gid=0) (e.g. `"bitcoin"`, `"ethereum"`) |
```text theme={null}
=CG.PRICE("bitcoin") → 95000
=CG.PRICE("ethereum") → 3400
=CG.PRICE("solana") → 180
```
***
### `=CG.HISTORY(id, date)`
Returns the **historical USD price** of a coin on a specific date.
| Parameter | Type | Description |
| --------- | ------ | --------------------------------------------------------------------------------------------------------------- |
| `id` | string | [Coin ID](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?gid=0#gid=0) |
| `date` | string | Date in `YYYY-MM-DD` format |
```text theme={null}
=CG.HISTORY("bitcoin", "2023-12-31") → 16541.77
=CG.HISTORY("ethereum", "2021-12-31") → 3682.45
```
***
### `=CG.NFT(id)`
Returns the **current floor price (USD)** of an NFT collection.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | [NFT ID](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?gid=207968092#gid=207968092) (e.g. `"bored-ape-yacht-club"`) |
```text theme={null}
=CG.NFT("bored-ape-yacht-club") → 24500
=CG.NFT("cryptopunks") → 68000
=CG.NFT("pudgy-penguins") → 8200
```
***
### `=CG.ONCHAIN(network, address)`
Returns the **current USD price** of an onchain token by network and contract address.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `network` | string | [Network ID](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?gid=1120233236#gid=1120233236) (e.g. `"eth"`, `"bsc"`, `"solana"`) |
| `address` | string | Token contract address |
```text theme={null}
=CG.ONCHAIN("eth", "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48")
=CG.ONCHAIN("bsc", "0x55d398326f99059ff775485246999027b3197955")
```
Common network IDs: `eth`, `bsc`, `solana`, `arbitrum`, `base`
***
### `=CG.TOP(limit, [category])`
Returns a **ranked table of top coins by market cap**.
*\*results spill into adjacent rows and columns.*
![]()
| Parameter | Type | Description |
| ---------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `limit` | number | Number of coins (1–10000) |
| `category` | string *(optional)* | [Category ID](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?gid=214581757#gid=214581757) to filter results |
```text theme={null}
=CG.TOP(10) → Top 10 coins by market cap
=CG.TOP(100) → Top 100 coins by market cap
=CG.TOP(50, "decentralized-exchange") → Top 50 DEX tokens
=CG.TOP(20, "layer-1") → Top 20 Layer-1 coins
```
Enter `=CG.TOP(...)` in a single cell and leave adjacent cells empty so the array can spill.
***
## Taskpane
![]()
* **Refresh All Data** — clears the cache and forces all `=CG.*` formulas to recalculate with fresh API data.
* **Save** — saves your API key and plan selection, validates the key, and clears the cache.
***
## FAQ
Ensure the add-in is installed and loaded. The `CG` namespace is only available when the add-in is active.
Use the [full ID list](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?gid=0#gid=0), or find the "API ID" on the coin's [CoinGecko](https://www.coingecko.com) page.
Open the taskpane, re-enter your API key, and click **Save**.
You've exceeded the API rate limit. Wait a moment, then click **Refresh All Data**.
Confirm the date is in `YYYY-MM-DD` format and that the coin existed on that date.
Make sure the cells below and to the right are empty so the array can spill.
View the full [privacy policy](/docs/excel/privacy-policy).
View the full [terms of use](/docs/excel/terms).
***
Have questions or feedback? Let us know.
# CoinGecko for Google Sheets
Source: https://docs.coingecko.com/docs/google-sheets
Pull live prices, historical data, NFT floors, and onchain data into Google Sheets with the =COINGECKO() function
![]()
This official add-on follows the principle of least privilege — it only accesses the sheet you currently have open. It does **not** request access to Google Drive or other spreadsheets.
## Quick Start
Visit [CoinGecko for Sheets](https://workspace.google.com/marketplace/app/coingecko_for_sheets_live_crypto_prices/429190203358) on Google Workspace Marketplace and click **Install**.
Check **Select all** to grant the required permissions.
![]()
The add-on needs these permissions to communicate with the CoinGecko API and write data to your sheet. CoinGecko does **NOT** have access to your email or personal data.
Go to **Extensions** > **CoinGecko** > **Settings & API Key**.
![]()
Enter your [CoinGecko API key](https://www.coingecko.com/en/api/pricing), select your plan (Demo or Pro), and click **Save Settings**.
## Using `=COINGECKO()`
A single "Smart Routing" function that auto-detects whether you're querying a ticker, coin ID, onchain token, or NFT.
### Latest Price
| Syntax | Description | Example |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `=COINGECKO("SYMBOL")` | **Price by ticker symbol.**
If multiple coins share the symbol, the largest by market cap is returned.
Falls back to GeckoTerminal if not found on CoinGecko. | `=COINGECKO("BTC")` |
| `=COINGECKO("name:NAME")` | **Price by coin name.**
Prioritizes CoinGecko-listed tokens. | `=COINGECKO("name:Ethereum")` |
| `=COINGECKO("id:COIN_ID")` | **Price by [coin ID](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?gid=0#gid=0).**
Most reliable — avoids ticker conflicts. | `=COINGECKO("id:solana")` |
| `=COINGECKO("NETWORK:ADDRESS")` | **Onchain DEX price by [network ID](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?gid=1120233236#gid=1120233236) and token address.** | `=COINGECKO("base:0x...")` |
| `=COINGECKO("nft:NFT_ID")` | **NFT floor price by [NFT ID](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?gid=207968092#gid=207968092).** | `=COINGECKO("nft:pudgy-penguins")` |
Use the **Coin ID** (e.g. `id:bitcoin-cash` instead of `BCH`) for the most reliable results — symbols can be shared by multiple tokens.
### Historical Price
| Syntax | Description | Example |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `=COINGECKO("id:COIN_ID", "YYYY-MM-DD")` | **Historical price at a specific date** (daily 00:00 UTC).
View [coin IDs](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?gid=0#gid=0). | `=COINGECKO("id:bitcoin", "2025-12-31")` |
### Top Market Cap Rankings
![]()
Get up to 1,000 tokens with a single formula:
| Syntax | Description | Example |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| `=COINGECKO("top:N")` | **Top N coins by market cap.** | `=COINGECKO("top:100")` |
| `=COINGECKO("top:N:CATEGORY_ID")` | **Top N coins by market cap in a [category](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?gid=214581757#gid=214581757).** | `=COINGECKO("top:10:meme-token")` |
![]()
***
## Other Features
![]()
### Bulk Refresh
Google Sheets caches formulas for 1–2 hours. To force-update all `=COINGECKO` formulas:
Open the CoinGecko Sidebar and click **Refresh All Data**.
### Error Debugging
Go to **Extensions** > **CoinGecko** > **View Error Logs**:
Opens a log sheet with exact API error responses (e.g. `429: Rate Limit Exceeded`, `403: Invalid API Key`).
***
## FAQ
Ensure the add-on is installed and "CoinGecko" appears under the Extensions menu. If it's missing, refresh your browser.
Use the [full ID list](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?gid=0#gid=0), or find the "API ID" on the coin's [CoinGecko](https://www.coingecko.com) or [GeckoTerminal](https://www.geckoterminal.com) page.
Yes. Your key is stored using Google's PropertiesService — encrypted and unique to your Google account. CoinGecko does not see or store your key.
* **View and manage spreadsheets** — to populate cells with data and create error log sheets.
* **Connect to an external service** — to fetch prices from the CoinGecko API.
* **Run when you are not present** — to keep formulas active without the sidebar open.
* **Display third-party web content** — to render the sidebar UI.
We recommend checking **Select all** during authorization. Unchecking any permission may cause errors.
View the full [privacy policy](/docs/google-sheet-privacy-policy).
***
Have questions or feedback? Let us know.
# How-To
Source: https://docs.coingecko.com/docs/how-to
Learn how to query CoinGecko and onchain data — identifiers, common patterns, and quick answers
Coin IDs, contract addresses, bulk queries, historical data.
Network IDs, DEX IDs, pool and token queries.
Step-by-step guides for trading, portfolio tracking, market research, and more.
# Market Research
Source: https://docs.coingecko.com/docs/market-research
Conduct deep market research with fundamentals, trending data, sector analysis, and onchain analytics from CoinGecko API
**TL;DR**
Use [/coins/\{id}](/reference/coins-id) for deep-dive fundamentals, [/coins/markets](/reference/coins-markets) for bulk screening, [/search/trending](/reference/trending-search) for momentum signals, [/coins/categories](/reference/coins-categories) for sector performance, and [/global](/reference/crypto-global) for the macro view.
> Replace `YOUR_API_KEY` in the examples below with your actual key. [Get one here →](https://www.coingecko.com/en/api/pricing)
## Research Workflow
Total market cap, BTC dominance, volume, and active coins. Frame your research in the context of overall market conditions.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/global" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Global Data →](/reference/crypto-global)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/global" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Global Data →](/demo/reference/crypto-global)
The `market_cap_percentage` field gives BTC and ETH dominance — a key signal for market rotation.
Coins, NFTs, and categories trending in CoinGecko search over the last 24 hours.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/search/trending" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Trending Search →](/reference/trending-search)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/search/trending" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Trending Search →](/demo/reference/trending-search)
Top 30 coins with the largest price gains and losses — spot breakout or breakdown opportunities.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/coins/top_gainers_losers?vs_currency=usd&duration=24h" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Top Gainers/Losers →](/reference/coins-top-gainers-losers)
`/coins/top_gainers_losers` is not available on the Demo API.
[Upgrade to Pro →](https://www.coingecko.com/en/api/pricing)
| Key param | Use |
| ---------- | -------------------------------------------- |
| `duration` | `1h`, `24h`, `7d`, `14d`, `30d`, `60d`, `1y` |
Category-level market cap, volume, and 24h change. Identify which sectors are leading or lagging.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/coins/categories?order=market_cap_change_percentage_24h_desc" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Coin Categories →](/reference/coins-categories)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/coins/categories?order=market_cap_change_percentage_24h_desc" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Coin Categories →](/demo/reference/coins-categories)
Combine with `/coins/markets?category=layer-1` to drill into individual coins within a strong sector.
Bulk market data for up to 250 coins per page — rankings, sparklines, and multi-timeframe changes.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/coins/markets?vs_currency=usd&order=market_cap_desc&per_page=100&sparkline=true&price_change_percentage=1h,24h,7d,30d" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Coins Markets →](/reference/coins-markets)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/coins/markets?vs_currency=usd&order=market_cap_desc&per_page=100&sparkline=true&price_change_percentage=1h,24h,7d,30d" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Coins Markets →](/demo/reference/coins-markets)
| Key param | Use |
| ------------------------- | -------------------------------------------------------------------------- |
| `order` | `market_cap_desc`, `volume_desc`, `market_cap_asc` |
| `category` | Filter to a specific sector (e.g. `layer-1`, `decentralized-finance-defi`) |
| `sparkline` | 7-day sparkline data for quick visual scanning |
| `price_change_percentage` | `1h,24h,7d,30d` for multi-timeframe momentum |
The most comprehensive endpoint for a single coin — ATH/ATL, supply, volume, categories, and exchange tickers in one call.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/coins/bitcoin?localization=false&tickers=false" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Coin Data →](/reference/coins-id)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/coins/bitcoin?localization=false&tickers=false" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Coin Data →](/demo/reference/coins-id)
| Key param | Use |
| -------------- | ---------------------------------------------- |
| `localization` | `false` to reduce response size |
| `tickers` | `false` if you don't need exchange ticker data |
| `market_data` | `false` if you only need metadata |
| `sparkline` | `true` for 7-day price sparkline data |
OHLC candles for a custom date range, or price + volume + market cap time series.
* **OHLC candles** for a custom range:
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/coins/ethereum/ohlc/range?vs_currency=usd&from=2024-01-01&to=2024-12-31&interval=daily" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [OHLC Range →](/reference/coins-id-ohlc-range)
`/coins/{id}/ohlc/range` is not available on the Demo API.
[Upgrade to Pro →](https://www.coingecko.com/en/api/pricing)
* **Price + volume + market cap** over time:
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/coins/solana/market_chart?vs_currency=usd&days=365&interval=daily" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Coin Market Chart →](/reference/coins-id-market-chart)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/coins/solana/market_chart?vs_currency=usd&days=365&interval=daily" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Coin Market Chart →](/demo/reference/coins-id-market-chart)
***
## Onchain Research
Hottest liquidity pools across all networks — spot early DeFi momentum before it shows up in CoinGecko's main listings.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/onchain/networks/trending_pools?include=base_token&duration=24h" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Trending Pools →](/reference/trending-pools-list)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/onchain/networks/trending_pools?include=base_token&duration=24h" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Trending Pools →](/demo/reference/trending-pools-list)
| Key param | Use |
| ---------- | ---------------------------------------------------------------- |
| `include` | `base_token`, `quote_token`, `dex`, `network` for richer context |
| `duration` | `1h`, `6h`, or `24h` trending window |
Metadata for any onchain token — description, socials, websites, and GeckoTerminal analytics score.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/onchain/networks/eth/tokens/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/info" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Token Info →](/reference/token-info-contract-address)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/onchain/networks/eth/tokens/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/info" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Token Info →](/demo/reference/token-info-contract-address)
Combine with [Pool OHLCV](/reference/pool-ohlcv-contract-address) for a complete onchain research workflow — fundamentals from token info, price action from OHLCV.
# Portfolio Tracking
Source: https://docs.coingecko.com/docs/portfolio-tracking
Build portfolio trackers with real-time valuation, cost basis, and multi-currency support from CoinGecko API
**TL;DR**
Use [/simple/price](/reference/simple-price) for live valuation, [/coins/\{id}/history](/reference/coins-id-history) for cost basis on purchase dates, [/coins/markets](/reference/coins-markets) for dashboard data, and [/coins/\{id}/market\_chart](/reference/coins-id-market-chart) for performance charts.
> Replace `YOUR_API_KEY` in the examples below with your actual key. [Get one here →](https://www.coingecko.com/en/api/pricing)
## Portfolio Workflow
Fetch all supported fiat and crypto currencies to populate a currency selector in your UI.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/simple/supported_vs_currencies" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Supported Currencies →](/reference/simple-supported-currencies)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/simple/supported_vs_currencies" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Supported Currencies →](/demo/reference/simple-supported-currencies)
```json theme={null}
["btc", "eth", "usd", "eur", "jpy", "gbp", "aud", "cad", "sgd", "myr", ...]
```
Pass the user's choice as `vs_currencies` to pricing endpoints.
Poll spot prices for all holdings. Batch multiple coins in one call — minimal overhead for frequent polling.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/simple/price?ids=bitcoin,ethereum,solana&vs_currencies=usd,eur&include_market_cap=true&include_24hr_change=true" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Simple Price →](/reference/simple-price)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/simple/price?ids=bitcoin,ethereum,solana&vs_currencies=usd,eur&include_market_cap=true&include_24hr_change=true" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Simple Price →](/demo/reference/simple-price)
```json theme={null}
{
"bitcoin": {
"usd": 67432.51,
"eur": 62145.30,
"usd_market_cap": 1326789012345,
"usd_24h_change": 2.34
}
}
```
Multiply each price by your holding quantity, then sum for total portfolio value.
For ERC-20 and other contract-based tokens — look up prices by contract address instead of coin ID.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/simple/token_price/ethereum?contract_addresses=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48,0x6b175474e89094c44da98b954eedeac495271d0f&vs_currencies=usd&include_market_cap=true" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Simple Token Price →](/reference/simple-token-price)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/simple/token_price/ethereum?contract_addresses=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48,0x6b175474e89094c44da98b954eedeac495271d0f&vs_currencies=usd&include_market_cap=true" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Simple Token Price →](/demo/reference/simple-token-price)
| Key param | Use |
| -------------------- | ---------------------------------------------------------- |
| `id` (path) | Asset platform — `ethereum`, `polygon-pos`, `solana`, etc. |
| `contract_addresses` | Comma-separated token addresses |
For onchain tokens not listed on CoinGecko, use [Onchain Simple Price](/reference/onchain-simple-price) — returns prices by contract address across any supported network.
Rich market data for up to 250 coins per page — rankings, sparklines, highs/lows, and multi-timeframe changes.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/coins/markets?vs_currency=usd&ids=bitcoin,ethereum,solana&sparkline=true&price_change_percentage=1h,24h,7d,30d" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Coins Markets →](/reference/coins-markets)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/coins/markets?vs_currency=usd&ids=bitcoin,ethereum,solana&sparkline=true&price_change_percentage=1h,24h,7d,30d" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Coins Markets →](/demo/reference/coins-markets)
| Key param | Use |
| ------------------------- | ----------------------------------------------- |
| `ids` | Filter to your portfolio coins only |
| `sparkline` | 7-day sparkline data for inline mini-charts |
| `price_change_percentage` | `1h,24h,7d,30d` for multi-timeframe performance |
Price snapshot on a specific date — calculate cost basis for each purchase.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/coins/bitcoin/history?date=15-01-2024" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Coin Historical Data →](/reference/coins-id-history)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/coins/bitcoin/history?date=15-01-2024" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Coin Historical Data →](/demo/reference/coins-id-history)
```json theme={null}
{
"market_data": {
"current_price": {
"usd": 42856.23,
"eur": 39456.78
}
}
}
```
The `date` parameter uses **dd-mm-yyyy** format (not ISO). Data returned is a snapshot at **00:00:00 UTC**.
Price, market cap, and volume over time — for charting portfolio value and calculating time-weighted returns.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/coins/ethereum/market_chart?vs_currency=usd&days=365&interval=daily" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Coin Market Chart →](/reference/coins-id-market-chart)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/coins/ethereum/market_chart?vs_currency=usd&days=365&interval=daily" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Coin Market Chart →](/demo/reference/coins-id-market-chart)
| Key param | Use |
| ---------- | ---------------------------------------------------------------- |
| `days` | Lookback: `1`, `7`, `14`, `30`, `90`, `180`, `365`, or `max` |
| `interval` | `daily` for consistent data points, or omit for auto granularity |
For tokens tracked by contract address, use [Contract Address Market Chart](/reference/contract-address-market-chart) — same data, queried by address instead of coin ID.
# Querying Coin Data
Source: https://docs.coingecko.com/docs/querying-coin-data
Coin IDs, contract addresses, bulk queries, historical data, and common CoinGecko API patterns
## Finding a Coin ID
Most endpoints require a **coin ID** (e.g. `bitcoin`, `ethereum`).
> Find a coin's API ID on its [CoinGecko](https://www.coingecko.com) page, via [Coins List](/reference/coins-list), or this [Google Sheet](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
To resolve a name or symbol to a coin ID at runtime, use [/search](/reference/search-data) — it returns matching coins, categories, and markets:
```bash wrap theme={null}
https://pro-api.coingecko.com/api/v3/search?query=bitcoin
```
![]()
```bash wrap theme={null}
https://pro-api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd
```
## Using Contract Addresses
Query by **contract address** instead of coin ID — useful when you don't know the CoinGecko ID.
```bash wrap theme={null}
https://pro-api.coingecko.com/api/v3/simple/token_price/ethereum?contract_addresses=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&vs_currencies=usd
```
* `id`: [asset platform](/reference/asset-platforms-list) ID (e.g. `ethereum`)
* `contract_addresses`: token contract address
Find contract addresses on the coin page at [CoinGecko](https://www.coingecko.com):
![]()
Not all coins have a contract address on CoinGecko. If unlisted, you can't query by address.
Find addresses via [/coins/list](/reference/coins-list) with `include_platform=true`:
```json {5-9} theme={null}
{
"id": "1inch",
"symbol": "1inch",
"name": "1inch",
"platforms": {
"ethereum": "0x111111111117dc0aa78b770fa6a738034120c302",
"avalanche": "0xd501281565bf7789224523144fe5d98e8b28f267",
"binance-smart-chain": "0x111111111117dc0aa78b770fa6a738034120c302"
}
}
```
## Target Currencies
| Type | Examples |
| ------ | -------------------------- |
| Fiat | `usd`, `eur`, `jpy`, `gbp` |
| Crypto | `btc`, `eth`, `bnb` |
Full list: [/simple/supported\_vs\_currencies](/reference/simple-supported-currencies)
## Bulk Queries
[/coins/markets](/reference/coins-markets) — price and market data for many coins at once (up to 250 per page).
```bash wrap theme={null}
https://pro-api.coingecko.com/api/v3/coins/markets?vs_currency=usd&order=market_cap_desc&per_page=100&page=1
```
## Historical Data
| Endpoint | Query by | Description |
| ------------------------------------------------------------------------------------------------------ | ---------------- | ------------------------------- |
| [/coins/\{id}/history](/reference/coins-id-history) | Coin ID | Snapshot at a specific date |
| [/coins/\{id}/market\_chart](/reference/coins-id-market-chart) | Coin ID | Time series over N days |
| [/coins/\{id}/market\_chart/range](/reference/coins-id-market-chart-range) | Coin ID | Time series within a date range |
| [/coins/\{id}/contract/\{address}/market\_chart](/reference/contract-address-market-chart) | Contract address | Time series over N days |
| [/coins/\{id}/contract/\{address}/market\_chart/range](/reference/contract-address-market-chart-range) | Contract address | Time series within a date range |
Auto-granularity based on time range:
* **1 day from now** → 5-minute intervals
* **1 day from any other time** → hourly
* **2–90 days** → hourly
* **90+ days** → daily (00:00 UTC)
### Historical Data for Inactive Coins
Coins delisted from CoinGecko are excluded from [/coins/list](/reference/coins-list) by default, but their historical data stays queryable ([Analyst plan or above](https://www.coingecko.com/en/api/pricing)).
Call [/coins/list](/reference/coins-list) with `status=inactive`, then take the coin ID from the response.
```bash wrap theme={null}
https://pro-api.coingecko.com/api/v3/coins/list?include_platform=false&status=inactive
```
Pass that coin ID to any of:
* [/coins/\{id}/history](/reference/coins-id-history) — snapshot at a specific date
* [/coins/\{id}/market\_chart](/reference/coins-id-market-chart) — time series over N days
* [/coins/\{id}/market\_chart/range](/reference/coins-id-market-chart-range) — time series within a date range
* [/coins/\{id}/contract/\{address}/market\_chart](/reference/contract-address-market-chart) — by contract address, over N days
* [/coins/\{id}/contract/\{address}/market\_chart/range](/reference/contract-address-market-chart-range) — by contract address, within a date range
***
## Common Patterns
| Pattern | How |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **BTC exchange rate** | **Current:** Use [/exchange\_rates](/reference/exchange-rates)
**Historical:** Use [/coins/id/history](/reference/coins-id-history) |
| **BTC dominance** | Use [/global](/reference/crypto-global)
Read `market_cap_percentage.btc` |
| **Category market caps** | Use [/coins/categories](/reference/coins-categories)
Includes 24h change |
| **Sparkline** | Use [/coins/id](/reference/coins-id) or [/coins/markets](/reference/coins-markets)
Set `sparkline=true` |
| **Stale price detection** | Use [/simple/price](/reference/simple-price)
Set `include_last_updated_at=true` |
| **DEX vs CEX** | Use [/exchanges/id](/reference/exchanges-id)
Check `"centralized": false` |
# Querying Onchain Data
Source: https://docs.coingecko.com/docs/querying-onchain-data
Network IDs, DEX IDs, pool and token queries, and common onchain API patterns
Onchain endpoints use identifiers from [GeckoTerminal](https://www.geckoterminal.com), not CoinGecko.
CoinGecko Asset Platform IDs and GeckoTerminal Network IDs are **not** the same.
* Asset Platform: `ethereum`
* Network ID: `eth`
Always use Network IDs for `/onchain` endpoints.
## Finding Network IDs
Use [/onchain/networks](/reference/networks-list), or copy the slug from a GeckoTerminal URL: `geckoterminal.com/`**`eth`**`/pools/...`
```json {2} theme={null}
{
"id": "eth",
"type": "network",
"attributes": {
"name": "Ethereum",
"coingecko_asset_platform_id": "ethereum"
}
}
```
## Finding DEX IDs
Use [/onchain/networks/\{network}/dexes](/reference/dexes-list), or copy from a GeckoTerminal URL: `geckoterminal.com/eth/`**`uniswap_v3`**
```json {2} theme={null}
{
"id": "uniswap_v3",
"type": "dex",
"attributes": {
"name": "Uniswap V3"
}
}
```
## Querying by Pool Address
**network ID + pool address** — e.g. [/onchain/networks/\{network}/pools/\{address}](/reference/pool-address):
```bash wrap theme={null}
https://pro-api.coingecko.com/api/v3/onchain/networks/eth/pools/0xb4e16d0168e52d35cacd2c6185b44281ec28c9dc
```
Find pool addresses on the pool page at [GeckoTerminal](https://www.geckoterminal.com):
![]()
To look up a pool by token name, symbol, or address instead, use [/onchain/search/pools](/reference/search-pools):
```bash wrap theme={null}
https://pro-api.coingecko.com/api/v3/onchain/search/pools?query=weth&network=eth
```
## Querying by Token Address
**network ID + token address** — e.g. [/onchain/networks/\{network}/tokens/\{address}/pools](/reference/top-pools-contract-address):
```bash wrap theme={null}
https://pro-api.coingecko.com/api/v3/onchain/networks/eth/tokens/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/pools
```
Find token addresses on the token page at [GeckoTerminal](https://www.geckoterminal.com):
![]()
***
## Common Patterns
| Pattern | How |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Pool liquidity** | Use [Pool Data](/reference/pool-address)
Read `reserve_in_usd` |
| **Token liquidity** | Use [Token Data](/reference/token-data-contract-address)
Read `total_reserve_in_usd` (across all pools) |
| **Filter pools** | Use [/pools/megafilter](/reference/pools-megafilter)
Filter by liquidity, FDV, volume, network, DEX |
| **Launchpad data** | Use [/pools/megafilter](/reference/pools-megafilter)
Set `sort=pool_created_at_desc` and filter by DEX |
| **Token security** | Use [Token Info](/reference/token-info-contract-address)
Returns GT scores, holder distribution, mint/freeze authority |
| **Inactive tokens** | Set `include_inactive_source=true` on supported endpoints
Read `last_trade_timestamp` for last swap time |
| **CoinGecko vs GT networks** | **CoinGecko:** [/asset\_platforms](/reference/asset-platforms-list)
**GeckoTerminal:** [/onchain/networks](/reference/networks-list) |
# CoinGecko SDK
Source: https://docs.coingecko.com/docs/sdk
Official TypeScript and Python SDKs for the CoinGecko API
![]()
**Skip the boilerplate**
The official CoinGecko SDKs give you full type safety, auto-complete, and structured responses out of the box. Maintained by the CoinGecko team, compatible with both Pro and Demo APIs.
**Get started in minutes with our SDKs:**
Full type safety and auto-complete
Pythonic and intuitive interface
Using AI to write code? Grab the [SDK prompts](/ai-integration/sdk-prompts) for your AI assistant.
# Python SDK
Source: https://docs.coingecko.com/docs/sdk-python
Official CoinGecko Python SDK — install, authenticate, and start querying
Pythonic and intuitive interface — write less code, ship faster.
# CoinGecko Python SDK — AI Prompt Rules
## Install
```
pip install coingecko_sdk
```
## Client Setup
```python theme={null}
import os
from coingecko_sdk import Coingecko
client = Coingecko(
pro_api_key=os.environ.get("YOUR_API_KEY"),
environment="pro", # or "demo" with demo_api_key
max_retries=2,
)
```
* Load API keys from environment variables. Never hardcode.
* Initialize one reusable client instance.
* For async: use `AsyncCoingecko` with `await`.
## Finding Methods
Methods map to endpoint paths using snake\_case, but names are **not always predictable**
— path parameters like `{address}` may become part of the method name
(e.g. `get_address()`, `get_addresses()`, `get_network()`).
**Before using any SDK method, you MUST verify the exact method name.** Do not guess.
1. **Check the reference page first** — every endpoint page includes an SDK Examples section
at the bottom with copy-ready code:
* URL pattern: `https://docs.coingecko.com/reference/{operationId}.md`
* Look for the `#### SDK Examples` block and use the Python snippet exactly as shown.
2. **Full method list** — if you need to search across all methods:
`https://docs.coingecko.com/docs/sdk-python-methods.md`
3. **Parameter details and endpoint caveats**:
`https://docs.coingecko.com/reference/{operationId}.md`
## Error Handling
Catch specific SDK exceptions — never use bare `except Exception`.
```python theme={null}
import coingecko_sdk
try:
response = client.simple.price.get(vs_currencies="usd", ids="bitcoin")
except coingecko_sdk.RateLimitError:
# Back off — 429 received
pass
except coingecko_sdk.NotFoundError:
# Invalid coin ID or endpoint
pass
except coingecko_sdk.APIError as e:
print(e.status_code, e.response)
```
## Rules
* ALWAYS use `coingecko_sdk`. Never use `pycoingecko` or raw `requests`/`httpx`.
* Rely on the SDK's built-in retry (`max_retries`). Never write manual retry loops.
* Responses are Pydantic models — use `.to_dict()` or `.to_json()` when needed.
* Use `client.with_options()` for per-request overrides (timeout, retries).
Or set up manually:
```bash pip theme={null}
pip install coingecko-sdk
```
```bash uv theme={null}
uv add coingecko-sdk
```
View on [PyPI](https://pypi.org/project/coingecko-sdk/) | [GitHub](https://github.com/coingecko/coingecko-python)
```python Pro API theme={null}
from coingecko_sdk import Coingecko
client = Coingecko(
pro_api_key='YOUR_API_KEY',
environment="pro",
)
```
```python Demo API theme={null}
from coingecko_sdk import Coingecko
client = Coingecko(
demo_api_key='YOUR_API_KEY',
environment="demo",
)
```
> Replace `YOUR_API_KEY` with your key from the [Developer Dashboard](https://www.coingecko.com/en/developers/dashboard#api-keys).
```python theme={null}
response = client.simple.price.get(
vs_currencies="usd",
ids="bitcoin",
)
print(response)
```
SDK methods map to endpoint paths. For example, `/simple/price` becomes `client.simple.price.get()`. Two ways to find the right method:
1. Every endpoint page includes an **SDK Examples** section at the bottom with copy-ready code. For example, see the [Coin Price by IDs](/reference/simple-price#sdk-examples) page:
![]()
2. Visit **[all methods](/docs/sdk-python-methods)** to browse the full list with endpoint mappings.
***
Found a bug or missing feature? [Open an issue](https://github.com/coingecko/coingecko-python/issues).
# TypeScript SDK
Source: https://docs.coingecko.com/docs/sdk-typescript
Official CoinGecko TypeScript SDK — install, authenticate, and start querying
Full type safety and auto-complete — catch errors at compile time, not runtime.
# CoinGecko TypeScript SDK — AI Prompt Rules
## Install
```
npm install @coingecko/coingecko-typescript
```
## Client Setup
```typescript theme={null}
import Coingecko from '@coingecko/coingecko-typescript';
const client = new Coingecko({
proAPIKey: process.env['YOUR_API_KEY'],
environment: 'pro', // or 'demo' with demoAPIKey
maxRetries: 2,
});
```
* Load API keys from environment variables. Never hardcode.
* Initialize one reusable client instance.
## Finding Methods
Methods map to endpoint paths using camelCase, but names are **not always predictable**
— path parameters like `{address}` may become part of the method name
(e.g. `getAddress()`, `getAddresses()`, `getNetwork()`, `getID()`).
**Before using any SDK method, you MUST verify the exact method name.** Do not guess.
1. **Check the reference page first** — every endpoint page includes an SDK Examples section
at the bottom with copy-ready code:
* URL pattern: `https://docs.coingecko.com/reference/{operationId}.md`
* Look for the `#### SDK Examples` block and use the TypeScript snippet exactly as shown.
2. **Full method list** — if you need to search across all methods:
`https://docs.coingecko.com/docs/sdk-typescript-methods.md`
3. **Parameter details and endpoint caveats**:
`https://docs.coingecko.com/reference/{operationId}.md`
## Error Handling
Catch specific SDK exceptions — never use bare `catch (e)` without checking the type.
```typescript theme={null}
import Coingecko from '@coingecko/coingecko-typescript';
try {
const response = await client.simple.price.get({ vs_currencies: 'usd', ids: 'bitcoin' });
} catch (err) {
if (err instanceof Coingecko.RateLimitError) {
// Back off — 429 received
} else if (err instanceof Coingecko.NotFoundError) {
// Invalid coin ID or endpoint
} else if (err instanceof Coingecko.APIError) {
console.log(err.status, err.headers);
} else {
throw err;
}
}
```
## Rules
* ALWAYS use `@coingecko/coingecko-typescript`. Never use raw `fetch`/`axios`/`node-fetch`.
* Rely on the SDK's built-in retry (`maxRetries`). Never write manual retry loops.
* Use SDK types for params and responses: `Coingecko.Simple.PriceGetParams`, `Coingecko.Simple.PriceGetResponse`.
* Use the second argument for per-request overrides: `client.simple.price.get(params, { maxRetries: 5 })`.
Or set up manually:
```bash npm theme={null}
npm install @coingecko/coingecko-typescript
```
```bash bun theme={null}
bun add @coingecko/coingecko-typescript
```
View on [npm](https://www.npmjs.com/package/@coingecko/coingecko-typescript) | [GitHub](https://github.com/coingecko/coingecko-typescript)
```typescript Pro API theme={null}
import Coingecko from '@coingecko/coingecko-typescript';
const client = new Coingecko({
proAPIKey: 'YOUR_API_KEY',
environment: 'pro',
});
```
```typescript Demo API theme={null}
import Coingecko from '@coingecko/coingecko-typescript';
const client = new Coingecko({
demoAPIKey: 'YOUR_API_KEY',
environment: 'demo',
});
```
> Replace `YOUR_API_KEY` with your key from the [Developer Dashboard](https://www.coingecko.com/en/developers/dashboard#api-keys).
```typescript theme={null}
async function main() {
const response = await client.simple.price.get({
vs_currencies: 'usd',
ids: 'bitcoin',
});
console.log(JSON.stringify(response, null, 2));
}
main()
```
SDK methods map to endpoint paths. For example, `/simple/price` becomes `client.simple.price.get()`. Two ways to find the right method:
1. Every endpoint page includes an **SDK Examples** section at the bottom with copy-ready code. For example, see the [Coin Price by IDs](/reference/simple-price#sdk-examples) page:
![]()
2. Visit **[all methods](/docs/sdk-typescript-methods)** to browse the full list with endpoint mappings.
***
Found a bug or missing feature? [Open an issue](https://github.com/coingecko/coingecko-typescript/issues).
# Setting Up Your API Key
Source: https://docs.coingecko.com/docs/setting-up-your-api-key
Create an API key and start making requests
**👋 New to CoinGecko API?**
Create an account at [coingecko.com/en/api/pricing](https://www.coingecko.com/en/api/pricing).
Go to the [Developer Dashboard](https://www.coingecko.com/en/developers/dashboard) and click **+ Add New Key**.
![]()
Follow the authentication guide for your plan:
For paid plan users — Basic, Analyst, Lite, Pro, Pro+, and Enterprise.
For free Demo plan users.
# Spreadsheet Add-ons
Source: https://docs.coingecko.com/docs/spreadsheet
Pull live CoinGecko data into Google Sheets and Microsoft Excel
`=COINGECKO()` formula reference.
`=CG.` formula reference.
***
### External Tutorials
Build a crypto portfolio tracker in Google Sheets.
Import live crypto prices into Microsoft Excel.
# Trading
Source: https://docs.coingecko.com/docs/trading
Build trading bots, charting tools, and backtesting pipelines with CoinGecko API
**TL;DR**
Use [/simple/price](/reference/simple-price) for spot prices, [/coins/\{id}/ohlc](/reference/coins-id-ohlc) for candlestick charts, [/coins/\{id}/market\_chart/range](/reference/coins-id-market-chart-range) for backtesting, and the onchain [OHLCV](/reference/pool-ohlcv-contract-address) endpoints for sub-minute DEX data.
> Replace `YOUR_API_KEY` in the examples below with your actual key. [Get one here →](https://www.coingecko.com/en/api/pricing)
## CEX Trading Workflow
Scan the market to find what to trade. Returns bulk data for ranking by volume, price change, or market cap.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/coins/markets?vs_currency=usd&order=volume_desc&per_page=50&price_change_percentage=1h,24h,7d" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Coins Markets →](/reference/coins-markets)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/coins/markets?vs_currency=usd&order=volume_desc&per_page=50&price_change_percentage=1h,24h,7d" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Coins Markets →](/demo/reference/coins-markets)
| Key param | Use |
| ------------------------- | --------------------------------------------- |
| `order` | `volume_desc` surfaces the most liquid assets |
| `price_change_percentage` | `1h,24h,7d` for multi-timeframe momentum |
| `per_page` | Up to 250 per page |
Poll spot prices for your selected assets. Minimal overhead — ideal for trading loops.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/simple/price?ids=bitcoin,ethereum,solana&vs_currencies=usd&include_24hr_vol=true&include_24hr_change=true" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Simple Price →](/reference/simple-price)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/simple/price?ids=bitcoin,ethereum,solana&vs_currencies=usd&include_24hr_vol=true&include_24hr_change=true" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Simple Price →](/demo/reference/simple-price)
```json theme={null}
{
"bitcoin": {
"usd": 67432.51,
"usd_24h_vol": 28394567890.12,
"usd_24h_change": 2.34
}
}
```
For onchain tokens not listed on CoinGecko, use [Onchain Simple Price](/reference/onchain-simple-price) — returns prices by contract address on any supported network.
Fetch OHLC candles for technical analysis (RSI, MACD, Bollinger Bands, etc.).
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/coins/bitcoin/ohlc?vs_currency=usd&days=30" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Coin OHLC →](/reference/coins-id-ohlc)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/coins/bitcoin/ohlc?vs_currency=usd&days=30" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Coin OHLC →](/demo/reference/coins-id-ohlc)
Response format: `[timestamp, open, high, low, close]` — timestamp is the candle **close** time.
**Auto-granularity** based on `days`:
* 1–2 days → 30-min candles
* 3–30 days → 4-hour candles
* 31+ days → 4-day candles
Paid plans can override with `interval=daily` or `interval=hourly`.
Compare trading pairs across CEXs and DEXs — bid/ask spreads, volume, and market depth.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/coins/bitcoin/tickers?exchange_ids=binance,coinbase&depth=true&order=volume_desc" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Coin Tickers →](/reference/coins-id-tickers)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/coins/bitcoin/tickers?exchange_ids=binance,coinbase&depth=true&order=volume_desc" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Coin Tickers →](/demo/reference/coins-id-tickers)
| Key param | Use |
| -------------- | ------------------------------------------------------------------------------------------ |
| `exchange_ids` | Filter to exchanges you trade on |
| `depth` | Includes `cost_to_move_up_usd` / `cost_to_move_down_usd` — how much capital moves price 2% |
Pull historical data for a specific time window.
* **OHLC candles** for a custom range:
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/coins/bitcoin/ohlc/range?vs_currency=usd&from=2024-01-01&to=2024-06-30&interval=daily" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [OHLC Range →](/reference/coins-id-ohlc-range)
`/coins/{id}/ohlc/range` is not available on the Demo API.
[Upgrade to Pro →](https://www.coingecko.com/en/api/pricing)
* **Price + volume + market cap** for a custom range:
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/coins/ethereum/market_chart/range?vs_currency=usd&from=2024-01-01&to=2024-12-31" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Market Chart Range →](/reference/coins-id-market-chart-range)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/coins/ethereum/market_chart/range?vs_currency=usd&from=2024-01-01&to=2024-12-31" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Market Chart Range →](/demo/reference/coins-id-market-chart-range)
Both accept ISO dates and UNIX timestamps for `from`/`to`.
***
## Onchain DEX Trading
For DeFi-native strategies — pool-level OHLCV with sub-minute granularity and individual trade feeds.
Supports `second`, `minute`, `hour`, and `day` timeframes with customizable aggregation (e.g., 5-min candles).
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/onchain/networks/eth/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640/ohlcv/minute?aggregate=5&limit=100¤cy=usd" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Pool OHLCV →](/reference/pool-ohlcv-contract-address) | [Token OHLCV →](/reference/token-ohlcv-token-address)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/onchain/networks/eth/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640/ohlcv/minute?aggregate=5&limit=100¤cy=usd" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Pool OHLCV →](/demo/reference/pool-ohlcv-contract-address)
Response format: `[timestamp, open, high, low, close, volume]`.
| Key param | Use |
| ------------------ | ----------------------------------------------------- |
| `aggregate` | Combine candles — `5` for 5-min, `4` for 4-hour |
| `limit` | Up to 1000 data points |
| `before_timestamp` | Paginate backward for historical data |
| `currency` | `usd` for fiat or `token` for base-token denomination |
Monitor execution, analyze microstructure, or trigger alerts on large swaps.
```bash theme={null}
curl -X GET \
"https://pro-api.coingecko.com/api/v3/onchain/networks/eth/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640/trades?trade_volume_in_usd_greater_than=10000" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
> [Pool Trades →](/reference/pool-trades-contract-address) | [Token Trades →](/reference/token-trades-contract-address)
```bash theme={null}
curl -X GET \
"https://api.coingecko.com/api/v3/onchain/networks/eth/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640/trades?trade_volume_in_usd_greater_than=10000" \
-H "x-cg-demo-api-key: YOUR_API_KEY"
```
> [Pool Trades →](/demo/reference/pool-trades-contract-address)
Use `trade_volume_in_usd_greater_than` to filter noise. On **Analyst & above**, set `trading_period` to `7d` or `30d` to look further back than the 24-hour default, and page through the results with `cursor`.
# Useful Links
Source: https://docs.coingecko.com/docs/useful-links
Quick links to resources, specs, and tools for the CoinGecko API
### ID Maps
### OpenAPI Specs (OAS)
Source: [coingecko/coingecko-api-oas](https://github.com/coingecko/coingecko-api-oas)
* [pro-api.json](https://raw.githubusercontent.com/coingecko/coingecko-api-oas/refs/heads/main/pro-api.json)
* [demo-api.json](https://raw.githubusercontent.com/coingecko/coingecko-api-oas/refs/heads/main/demo-api.json)
### AI & LLMs
* [llms.txt](/llms.txt) — Concise API overview for LLM context.
* [llms-full.txt](/llms-full.txt) — Full API documentation in plain text for LLM context.
### Reference
* [CoinGecko Methodologies](https://www.coingecko.com/en/methodology) — How CoinGecko calculates price, volume, trust score, and more.
* [Attribution Guide](https://brand.coingecko.com/resources/attribution-guide) — Guidelines for using the CoinGecko brand in your project.
# Welcome to CoinGecko API
Source: https://docs.coingecko.com/index
#### CoinGecko is the world's largest independent crypto data aggregator
The CoinGecko API provides comprehensive crypto market data through REST endpoints, WebSocket streams, Webhooks, and AI-native tools.
* **[CoinGecko](https://www.coingecko.com)** — 1,500+ exchanges, 18,000+ coins, 600+ categories
* **Onchain DEX data** — 200+ blockchain networks, 1,800+ DEXes, 39M+ tokens, powered by [GeckoTerminal](https://www.geckoterminal.com)
## Get Started
Create your CoinGecko API key and start making requests.
Choose between REST API, WebSocket, and Webhooks.
MCP servers, SKILL, CLI, and coding agent setup guides.
Trading, portfolio tracking, market research, DeFi analytics, and more.
## Build
Full endpoint reference for paid plan users.
Free Demo API with limited endpoints and rate limits.
Ultra-low latency streaming with persistent connections.
Receive automated metadata updates via HTTP callbacks.
## Explore
Official TypeScript and Python SDKs.
Google Sheets and Excel integrations for crypto data.
Querying coin data, onchain data, and common API patterns.
See which API endpoints power CoinGecko and GeckoTerminal features.
***
![Data Delivery Methods — REST API, WebSocket, and Webhooks]()
# API Usage
Source: https://docs.coingecko.com/reference/api-usage
openapi-specs/pro-api.json get /key
To monitor your account's API usage, including rate limits, monthly total credits, remaining credits, and more
For a more comprehensive overview of your API usage, visit the [Developer Dashboard](https://www.coingecko.com/en/developers/dashboard).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.key.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.key.get()
print(response.model_dump_json(indent=2))
```
# Asset Platforms List
Source: https://docs.coingecko.com/reference/asset-platforms-list
openapi-specs/pro-api.json get /asset_platforms
To query all the supported asset platforms (blockchain networks) on CoinGecko
#### Notes
* Use this endpoint to get asset platform IDs for other endpoints that require an `id` parameter (asset platform).
* Use `filter=nft` to get only NFT-supported asset platforms.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.assetPlatforms.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.asset_platforms.get()
print(response)
```
# Authentication (Pro API)
Source: https://docs.coingecko.com/reference/authentication
How to authenticate requests to the CoinGecko Pro API
[Sign up](https://www.coingecko.com/en/api/pricing) and grab your key from the [Developer Dashboard](https://www.coingecko.com/en/developers/dashboard#api-keys).
| Method | Key | Example |
| ------------------------ | ------------------ | ------------------------------------- |
| **Header** (recommended) | `x-cg-pro-api-key` | `-H "x-cg-pro-api-key: YOUR_API_KEY"` |
| **Query string** | `x_cg_pro_api_key` | `?x_cg_pro_api_key=YOUR_API_KEY` |
All requests use the Pro API root URL: `https://pro-api.coingecko.com/api/v3/`
```bash Header (recommended) theme={null}
curl "https://pro-api.coingecko.com/api/v3/ping" \
-H "x-cg-pro-api-key: YOUR_API_KEY"
```
```bash Query string theme={null}
curl "https://pro-api.coingecko.com/api/v3/ping?x_cg_pro_api_key=YOUR_API_KEY"
```
> Replace `YOUR_API_KEY` with your key from the [Developer Dashboard](https://www.coingecko.com/en/developers/dashboard#api-keys).
Onchain endpoints use the same authentication — just include `/onchain` in the path.
e.g. `https://pro-api.coingecko.com/api/v3/onchain/simple/networks/...`
Store your API key in your backend and use a proxy to inject it into requests.
Avoid query string parameters in production — they risk exposing your key in logs and browser history.
Connect it to AI agents via MCP, SDK prompts, and coding agent integrations.
### Usage Credits
* Each successful request (HTTP 200) deducts 1 credit from your monthly quota.
* Failed requests (4xx, 5xx) do **not** consume credits, but still count toward your per-minute rate limit.
* Monthly credits and rate limits depend on your [plan](https://www.coingecko.com/en/api/pricing).
* Check usage in the [Developer Dashboard](https://www.coingecko.com/en/developers/dashboard#usage-reports).
# Categories List
Source: https://docs.coingecko.com/reference/categories-list
openapi-specs/pro-api.json get /onchain/categories
To query all the supported categories on GeckoTerminal
#### Notes
* Returns 50 categories per page.
* Use category IDs with [Pools by Category ID](/reference/pools-category) to retrieve pools for a specific category.
* GeckoTerminal categories are different from [CoinGecko categories](/reference/coins-categories-list).
* Equivalent page on [GeckoTerminal Categories](https://www.geckoterminal.com/category).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.categories.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.categories.get()
print(response.model_dump_json(indent=2))
```
# Categories
Source: https://docs.coingecko.com/reference/categories-overview
Coin categories and their aggregate market cap and volume, for filtering coins by sector.
| Endpoint | Description |
| ---------------------------------------------------------- | --------------------------------------------------------------------- |
| [/coins/categories/list](/reference/coins-categories-list) | Query all supported coin categories on CoinGecko |
| [/coins/categories](/reference/coins-categories) | Query all coin categories with market data (market cap, volume, etc.) |
# Coin Charts
Source: https://docs.coingecko.com/reference/coin-charts-overview
Historical price, market cap, volume, OHLC and supply charts for any coin, by coin ID or token contract address.
| Endpoint | Description |
| ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [/coins/\{id}/market\_chart](/reference/coins-id-market-chart) | Historical chart data (price, market cap, 24hr volume) by coin ID |
| [/coins/\{id}/market\_chart/range](/reference/coins-id-market-chart-range) | Historical chart data within a time range by coin ID |
| [/coins/\{id}/contract
/\{contract\_address}/market\_chart](/reference/contract-address-market-chart) | Historical chart data by asset platform and token contract address |
| [/coins/\{id}/contract
/\{contract\_address}/market\_chart/range](/reference/contract-address-market-chart-range) | Historical chart data within a time range by asset platform and token contract address |
| [/coins/\{id}/ohlc](/reference/coins-id-ohlc) | OHLC chart by coin ID |
| 💼 [/coins/\{id}/ohlc/range](/reference/coins-id-ohlc-range) | OHLC chart within a time range by coin ID |
| 👑 [/coins/\{id}/circulating\_supply\_chart](/reference/coins-id-circulating-supply-chart) | Historical circulating supply by coin ID |
| 👑 [/coins/\{id}
/circulating\_supply\_chart/range](/reference/coins-id-circulating-supply-chart-range) | Historical circulating supply within a time range by coin ID |
| 👑 [/coins/\{id}/total\_supply\_chart](/reference/coins-id-total-supply-chart) | Historical total supply by coin ID |
| 👑 [/coins/\{id}/total\_supply\_chart/range](/reference/coins-id-total-supply-chart-range) | Historical total supply within a time range by coin ID |
# Coins Categories List with Market Data
Source: https://docs.coingecko.com/reference/coins-categories
openapi-specs/pro-api.json get /coins/categories
To query all the coins categories with market data (market cap, volume, etc.) on CoinGecko
#### Notes
* To get coins within a specific category, use [Coins List with Market Data](/reference/coins-markets) with the `category` parameter.
* CoinGecko categories are different from [GeckoTerminal categories](/reference/categories-list).
* Equivalent page on [CoinGecko Categories](https://www.coingecko.com/en/categories).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.categories.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.categories.get()
print(response)
```
# Coins Categories List
Source: https://docs.coingecko.com/reference/coins-categories-list
openapi-specs/pro-api.json get /coins/categories/list
To query all the supported coins categories on CoinGecko
#### Notes
* Use this endpoint to get category IDs for endpoints that require a `category` parameter, such as [Coins List with Market Data](/reference/coins-markets).
* CoinGecko categories are different from [GeckoTerminal categories](/reference/categories-list).
* Equivalent page on [CoinGecko Categories](https://www.coingecko.com/en/categories).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.categories.getList();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.categories.get_list()
print(response)
```
# Coin Data by Token Address
Source: https://docs.coingecko.com/reference/coins-contract-address
openapi-specs/pro-api.json get /coins/{id}/contract/{contract_address}
To query all the metadata (image, websites, socials, description, contract address, etc.) and market data (price, ATH, exchange tickers, etc.) of a coin based on an asset platform and a particular token contract address
#### Notes
* Find a token's contract address on its [CoinGecko](https://www.coingecko.com) page or via [Coins List](/reference/coins-list) with `include_platform=true`.
* Coin descriptions may contain `\r\n` escape sequences that require processing for proper formatting.
The `has_supply_breakdown` field indicates whether supply breakdown data is available for this coin. When `true`, use [/coins/\{id}/supply\_breakdown](/reference/coins-id-supply-breakdown) to get the full breakdown.
As of 28 August 2026, the `community_data` and `developer_data` objects are no longer returned. See the [changelog](/changelog#upcoming-change-notice-removal-of-community_data-and-developer_data) for details.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.contract.get('0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2', {
id: 'ethereum',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.contract.get(
"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
id="ethereum",
)
print(response.model_dump_json(indent=2))
```
# Coin Data by ID
Source: https://docs.coingecko.com/reference/coins-id
openapi-specs/pro-api.json get /coins/{id}
To query all the metadata (image, websites, socials, description, contract address, etc.) and market data (price, ATH, exchange tickers, etc.) of a coin based on a particular coin ID
#### Notes
* Find a coin's API ID on its [CoinGecko](https://www.coingecko.com) page, via [Coins List](/reference/coins-list), or this [Google Sheet](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
* Tickers are limited to 100 items. Use [Coin Tickers](/reference/coins-id-tickers) for more.
* Coin descriptions may contain `\r\n` escape sequences that require processing for proper formatting.
* When `dex_pair_format=symbol`, DEX pair `base` and `target` display as symbols (e.g. `WETH`, `USDC`) instead of contract addresses.
* Use `last_updated` in the response to check whether the price is stale.
The `has_supply_breakdown` field indicates whether supply breakdown data is available for this coin. When `true`, use [/coins/\{id}/supply\_breakdown](/reference/coins-id-supply-breakdown) to get the full breakdown.
As of 28 August 2026, the `community_data` and `developer_data` objects are no longer returned. The `community_data` and `developer_data` query params are kept for backward compatibility but have no effect. See the [changelog](/changelog#upcoming-change-notice-removal-of-community_data-and-developer_data) for details.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.getID('bitcoin');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.get_id("bitcoin")
print(response.model_dump_json(indent=2))
```
# Circulating Supply Chart by ID
Source: https://docs.coingecko.com/reference/coins-id-circulating-supply-chart
openapi-specs/pro-api.json get /coins/{id}/circulating_supply_chart
To query historical circulating supply of a coin by number of days away from now based on provided coin ID
#### Notes
* Auto-granularity when `interval` is not specified:
| Date range | Granularity |
| ----------------- | --------------------- |
| 1 day | **5-minutely** |
| 2–90 days | **hourly** |
| 91 days and above | **daily** (00:00 UTC) |
* Data available from 22 June 2019 onwards.
The last completed UTC day (00:00) is available 35 minutes after midnight (00:35 UTC).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.circulatingSupplyChart.get('bitcoin', {
days: '1',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.circulating_supply_chart.get(
"bitcoin",
days="1",
)
print(response.model_dump_json(indent=2))
```
# Circulating Supply Chart within Time Range by ID
Source: https://docs.coingecko.com/reference/coins-id-circulating-supply-chart-range
openapi-specs/pro-api.json get /coins/{id}/circulating_supply_chart/range
To query historical circulating supply of a coin, within a range of timestamp based on the provided coin ID
#### Notes
* Accepts ISO date strings (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM`, recommended) or UNIX timestamps for `from` and `to`.
* Auto-granularity when `interval` is not specified:
| Date range | Granularity |
| ------------------------- | --------------------- |
| 1 day from current time | **5-minutely** |
| 1 day from any other time | **hourly** |
| 2–90 days | **hourly** |
| Above 90 days | **daily** (00:00 UTC) |
* Data available from 22 June 2019 onwards.
The last completed UTC day (00:00) is available 35 minutes after midnight (00:35 UTC).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.circulatingSupplyChart.getRange('bitcoin', {
from: '2025-01-01',
to: '2025-12-31',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.circulating_supply_chart.get_range(
"bitcoin",
from_="2025-01-01",
to="2025-12-31",
)
print(response.model_dump_json(indent=2))
```
# Coin Historical Data by ID
Source: https://docs.coingecko.com/reference/coins-id-history
openapi-specs/pro-api.json get /coins/{id}/history
To query the historical data (price, market cap, 24hrs volume, etc.) at a given date for a coin based on a particular coin ID
#### Notes
* Find a coin's API ID on its [CoinGecko](https://www.coingecko.com) page, via [Coins List](/reference/coins-list), or this [Google Sheet](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
* Data returned is a snapshot at `00:00:00 UTC` for the given date.
The last completed UTC day (00:00) becomes available 35 minutes after midnight (00:35 UTC).
As of 28 August 2026, the `community_data` and `developer_data` objects are no longer returned. See the [changelog](/changelog#upcoming-change-notice-removal-of-community_data-and-developer_data) for details.
Historical data on the **Basic plan** is restricted to the past 2 years. Subscribe to [Analyst plan & above](https://www.coingecko.com/en/api/pricing) for the full range.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.history.get('bitcoin', {
date: '2025-12-30',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.history.get(
"bitcoin",
date="2025-12-30",
)
print(response.model_dump_json(indent=2))
```
# Coin Historical Chart Data by ID
Source: https://docs.coingecko.com/reference/coins-id-market-chart
openapi-specs/pro-api.json get /coins/{id}/market_chart
To get the historical chart data of a coin including time in UNIX, price, market cap and 24hrs volume based on particular coin ID
#### Notes
* Find a coin's API ID on its [CoinGecko](https://www.coingecko.com) page, via [Coins List](/reference/coins-list), or this [Google Sheet](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
* Auto-granularity when `interval` is not specified:
| Date range | Granularity |
| ----------------------- | --------------------- |
| 1 day from current time | **5-minutely** |
| 2–90 days | **hourly** |
| Above 90 days | **daily** (00:00 UTC) |
* Override with the `interval` parameter:
| `interval` | Lookback |
| ---------- | ------------------------------------------ |
| `daily` | — |
| `hourly` | **Past 100 days** |
| `5m` | **Past 10 days** (Enterprise only) |
| `1m` | **Past 1 day** (Enterprise only, **Beta**) |
* Data availability: `1m` from 1 Jun 2026, `5m` from 9 Feb 2018, `hourly` from 30 Jan 2018.
The last completed UTC day (00:00) data is available 10 minutes after midnight (00:10 UTC).
Historical data on the **Basic plan** is restricted to the past 2 years. Subscribe to [Analyst plan & above](https://www.coingecko.com/en/api/pricing) for the full range.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.marketChart.get('bitcoin', {
vs_currency: 'usd',
days: '1',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.market_chart.get(
"bitcoin",
vs_currency="usd",
days="1",
)
print(response.model_dump_json(indent=2))
```
# Coin Historical Chart Data within Time Range by ID
Source: https://docs.coingecko.com/reference/coins-id-market-chart-range
openapi-specs/pro-api.json get /coins/{id}/market_chart/range
To get the historical chart data of a coin within certain time range in UNIX along with price, market cap and 24hrs volume based on particular coin ID
#### Notes
* Find a coin's API ID on its [CoinGecko](https://www.coingecko.com) page, via [Coins List](/reference/coins-list), or this [Google Sheet](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
* Accepts ISO date strings (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM`, recommended) or UNIX timestamps for `from` and `to`.
* Auto-granularity when `interval` is not specified:
| Date range | Granularity |
| ------------------------- | --------------------- |
| 1 day from current time | **5-minutely** |
| 1 day from any other time | **hourly** |
| 2–90 days | **hourly** |
| Above 90 days | **daily** (00:00 UTC) |
* Override with the `interval` parameter:
| `interval` | Per request |
| ---------- | ----------------------------------------- |
| `daily` | — |
| `hourly` | **Any 100 days** |
| `5m` | **Any 10 days** (Enterprise only) |
| `1m` | **Any 1 day** (Enterprise only, **Beta**) |
* Data availability: `1m` from 1 Jun 2026, `5m` from 9 Feb 2018, `hourly` from 30 Jan 2018.
The last completed UTC day (00:00) is available 35 minutes after midnight (00:35 UTC). Cache expires at 00:40 UTC.
Historical data on the **Basic plan** is restricted to the past 2 years. Subscribe to [Analyst plan & above](https://www.coingecko.com/en/api/pricing) for the full range.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.marketChart.getRange('bitcoin', {
vs_currency: 'usd',
from: '2025-12-22',
to: '2025-12-31',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.market_chart.get_range(
"bitcoin",
vs_currency="usd",
from_="2025-12-22",
to="2025-12-31",
)
print(response.model_dump_json(indent=2))
```
# Coin OHLC Chart by ID
Source: https://docs.coingecko.com/reference/coins-id-ohlc
openapi-specs/pro-api.json get /coins/{id}/ohlc
To get the OHLC chart (Open, High, Low, Close) of a coin based on particular coin ID
#### Notes
* Find a coin's API ID on its [CoinGecko](https://www.coingecko.com) page, via [Coins List](/reference/coins-list), or this [Google Sheet](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
* The timestamp in the response indicates the **close** time of each OHLC candle.
* Auto-granularity (candle body):
* 1–2 days: 30 minutes
* 3–30 days: 4 hours
* 31 days and beyond: 4 days
* Paid plan subscribers can use `interval=daily` or `interval=hourly`:
* `daily`: available for 1 / 7 / 14 / 30 / 90 / 180 days
* `hourly`: available for 1 / 7 / 14 / 30 / 90 days
* For better granularity, consider [Coin Historical Chart Data](/reference/coins-id-market-chart).
The last completed UTC day (00:00) is available 35 minutes after midnight (00:35 UTC).
Historical data on the **Basic plan** is restricted to the past 2 years. Subscribe to [Analyst plan & above](https://www.coingecko.com/en/api/pricing) for the full range.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.ohlc.get('bitcoin', {
vs_currency: 'usd',
days: '1',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.ohlc.get(
"bitcoin",
vs_currency="usd",
days="1",
)
print(response)
```
# Coin OHLC Chart within Time Range by ID
Source: https://docs.coingecko.com/reference/coins-id-ohlc-range
openapi-specs/pro-api.json get /coins/{id}/ohlc/range
To get the OHLC chart (Open, High, Low, Close) of a coin within a range of timestamp based on particular coin ID
#### Notes
* Find a coin's API ID on its [CoinGecko](https://www.coingecko.com) page, via [Coins List](/reference/coins-list), or this [Google Sheet](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
* Accepts ISO date strings (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM`, recommended) or UNIX timestamps for `from` and `to`.
* The timestamp in the response indicates the **close** time of each OHLC candle.
* Interval options:
* `daily`: up to **any 180 days** per request (180 candles)
* `hourly`: up to **any 31 days** per request (744 candles)
* Data available from 9 February 2018 onwards.
* For better granularity, consider [Coin Historical Chart Data](/reference/coins-id-market-chart).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.ohlc.getRange('bitcoin', {
vs_currency: 'usd',
from: '2025-12-01',
to: '2025-12-31',
interval: 'daily',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.ohlc.get_range(
"bitcoin",
vs_currency="usd",
from_="2025-12-01",
to="2025-12-31",
interval="daily",
)
print(response)
```
# Coin Supply Breakdown by ID
Source: https://docs.coingecko.com/reference/coins-id-supply-breakdown
openapi-specs/pro-api.json get /coins/{id}/supply_breakdown
To query the supply breakdown of a coin based on provided coin ID
#### Notes
* Find a coin's API ID on its [CoinGecko](https://www.coingecko.com) page, via [Coins List](/reference/coins-list), or this [Google Sheet](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
* Check the `has_supply_breakdown` field from [/coins/\{id}](/reference/coins-id) to verify if supply breakdown data is available for a coin.
* When `non_circulating_wallets.anomaly` is `true`, it indicates an unreliable balance update. Circulating supply calculations will fall back to the last known-good balance until manually reviewed.
# Coin Tickers by ID
Source: https://docs.coingecko.com/reference/coins-id-tickers
openapi-specs/pro-api.json get /coins/{id}/tickers
To query the coin tickers on both centralized exchange (CEX) and decentralized exchange (DEX) based on a particular coin ID
#### Notes
* Tickers are paginated to 100 items per page.
* Use `exchange_ids` to filter tickers for a specific exchange.
* When `dex_pair_format=symbol`, DEX pair `base` and `target` display as symbols (e.g. `WETH`, `USDC`) instead of contract addresses.
* When sorting by `volume`, `converted_volume` is used instead of `volume`.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.tickers.get('bitcoin');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.tickers.get("bitcoin")
print(response.model_dump_json(indent=2))
```
# Total Supply Chart by ID
Source: https://docs.coingecko.com/reference/coins-id-total-supply-chart
openapi-specs/pro-api.json get /coins/{id}/total_supply_chart
To query historical total supply of a coin by number of days away from now based on provided coin ID
#### Notes
* Auto-granularity when `interval` is not specified:
| Date range | Granularity |
| ----------------- | --------------------- |
| 1 day | **5-minutely** |
| 2–90 days | **hourly** |
| 91 days and above | **daily** (00:00 UTC) |
* Data availability:
* Full coverage for all coins starts from **27 July 2023**
* Patched historical data from June 2019 is available for select coins only and may contain inaccuracies
The last completed UTC day (00:00) is available 35 minutes after midnight (00:35 UTC).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.totalSupplyChart.get('bitcoin', {
days: '1',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.total_supply_chart.get(
"bitcoin",
days="1",
)
print(response.model_dump_json(indent=2))
```
# Total Supply Chart within Time Range by ID
Source: https://docs.coingecko.com/reference/coins-id-total-supply-chart-range
openapi-specs/pro-api.json get /coins/{id}/total_supply_chart/range
To query historical total supply of a coin, within a range of timestamp based on the provided coin ID
#### Notes
* Accepts ISO date strings (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM`, recommended) or UNIX timestamps for `from` and `to`.
* Data is provided at daily intervals (00:00:00 UTC).
* Data availability:
* Full coverage for all coins starts from **27 July 2023**
* Patched historical data from June 2019 is available for select coins only and may contain inaccuracies
The last completed UTC day (00:00) is available 35 minutes after midnight (00:35 UTC).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.totalSupplyChart.getRange('bitcoin', {
from: '2025-01-01',
to: '2025-12-31',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.total_supply_chart.get_range(
"bitcoin",
from_="2025-01-01",
to="2025-12-31",
)
print(response.model_dump_json(indent=2))
```
# Coins List
Source: https://docs.coingecko.com/reference/coins-list
openapi-specs/pro-api.json get /coins/list
To query all the supported coins on CoinGecko with coin ID, name and symbol
#### Notes
* Use this endpoint to get coin IDs for other endpoints that require `id` or `ids` parameters.
* Returns the full list of active coins by default. Use `status=inactive` to retrieve coins no longer listed on CoinGecko ([Analyst plan or above](https://www.coingecko.com/en/api/pricing)).
* No pagination required — the full list is returned in a single response.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.list.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.list.get()
print(response)
```
# Recently Added Coins
Source: https://docs.coingecko.com/reference/coins-list-new
openapi-specs/pro-api.json get /coins/list/new
To query the latest 200 coins that recently listed on CoinGecko
Equivalent page on [CoinGecko New Cryptocurrencies](https://www.coingecko.com/en/new-cryptocurrencies).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.list.getNew();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.list.get_new()
print(response)
```
# Coins List with Market Data
Source: https://docs.coingecko.com/reference/coins-markets
openapi-specs/pro-api.json get /coins/markets
To query all the supported coins with price, market cap, volume and market related data
#### Notes
* Filter by `ids`, `names`, `symbols`, or `category`. When multiple are provided, priority is: `category` > `ids` > `names` > `symbols`.
* URL-encode spaces in `names` (e.g. `Binance%20Coin`).
* `include_tokens=all` only works with `symbols` lookups, limited to 50 symbols per request.
* Maximum of **250** IDs per request. Wildcard searches are not supported.
* Use `per_page` and `page` to paginate results.
Filter by category using the `category` param — refer to [Coins Categories List](/reference/coins-categories-list) for available values.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.markets.get({
vs_currency: 'usd',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.markets.get(
vs_currency="usd",
)
print(response)
```
# Coins
Source: https://docs.coingecko.com/reference/coins-overview
Coin metadata, market data, tickers, historical snapshots, new listings and top gainers and losers.
| Endpoint | Description |
| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| [/coins/markets](/reference/coins-markets) | Query all supported coins with price, market cap, volume and market data |
| [/coins/\{id}](/reference/coins-id) | Query all metadata and market data of a coin by coin ID |
| [/coins/\{id}/contract/\{contract\_address}](/reference/coins-contract-address) | Query all metadata and market data of a coin by asset platform and token contract address |
| [/coins/\{id}/tickers](/reference/coins-id-tickers) | Query coin tickers on both CEX and DEX by coin ID |
| [/coins/\{id}/history](/reference/coins-id-history) | Query historical data (price, market cap, 24hr volume, etc.) at a given date by coin ID |
| 💼 [/coins/list/new](/reference/coins-list-new) | Query the latest 200 coins recently listed on CoinGecko |
| 💼 [/coins/top\_gainers\_losers](/reference/coins-top-gainers-losers) | Query top 30 coins with largest price gain and loss by time duration |
| 💼 [/coins/\{id}/supply\_breakdown](/reference/coins-id-supply-breakdown) | Query the supply breakdown of a coin based on provided coin ID |
# Top Gainers & Losers
Source: https://docs.coingecko.com/reference/coins-top-gainers-losers
openapi-specs/pro-api.json get /coins/top_gainers_losers
To query the top 30 coins with largest price gain and loss by a specific time duration
* Only includes coins with a 24-hour trading volume of at least \$50,000.
* Equivalent page on [CoinGecko Gainers & Losers](https://www.coingecko.com/en/crypto-gainers-losers).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.topGainersLosers.get({
vs_currency: 'usd',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.top_gainers_losers.get(
vs_currency="usd",
)
print(response.model_dump_json(indent=2))
```
# Crypto Treasury Holdings by Coin ID
Source: https://docs.coingecko.com/reference/companies-public-treasury
openapi-specs/pro-api.json get /{entity}/public_treasury/{coin_id}
To query public companies' and governments' cryptocurrency holdings by coin ID
#### Notes
* Results are sorted by total holdings in descending order.
* Equivalent page on [CoinGecko Bitcoin Treasuries](https://www.coingecko.com/en/treasuries/bitcoin).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.publicTreasury.getCoinID('bitcoin', {
entity: 'companies',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.public_treasury.get_coin_id(
"bitcoin",
entity="companies",
)
print(response.model_dump_json(indent=2))
```
# Coin Historical Chart Data by Token Address
Source: https://docs.coingecko.com/reference/contract-address-market-chart
openapi-specs/pro-api.json get /coins/{id}/contract/{contract_address}/market_chart
To get the historical chart data including time in UNIX, price, market cap and 24hrs volume based on asset platform and particular token contract address
#### Notes
* Find a token's contract address on its [CoinGecko](https://www.coingecko.com) page or via [Coins List](/reference/coins-list) with `include_platform=true`.
* Auto-granularity when `interval` is not specified:
| Date range | Granularity |
| ----------------------- | --------------------- |
| 1 day from current time | **5-minutely** |
| 2–90 days | **hourly** |
| Above 90 days | **daily** (00:00 UTC) |
* Enterprise plan subscribers can bypass auto-granularity:
| `interval` | Lookback |
| ---------- | ------------------------- |
| `hourly` | **Past 100 days** |
| `5m` | **Past 10 days** |
| `1m` | **Past 1 day** (**Beta**) |
* Data availability: `1m` from 1 Jun 2026, `5m` from 9 Feb 2018, `hourly` from 30 Jan 2018.
The last completed UTC day (00:00) is available 35 minutes after midnight (00:35 UTC). Cache expires at 00:40 UTC.
Historical data on the **Basic plan** is restricted to the past 2 years. Subscribe to [Analyst plan & above](https://www.coingecko.com/en/api/pricing) for the full range.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.contract.marketChart.get('0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', {
id: 'ethereum',
vs_currency: 'usd',
days: '1',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.contract.market_chart.get(
"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
id="ethereum",
vs_currency="usd",
days="1",
)
print(response.model_dump_json(indent=2))
```
# Coin Historical Chart Data within Time Range by Token Address
Source: https://docs.coingecko.com/reference/contract-address-market-chart-range
openapi-specs/pro-api.json get /coins/{id}/contract/{contract_address}/market_chart/range
To get the historical chart data within certain time range in UNIX along with price, market cap and 24hrs volume based on asset platform and particular token contract address
#### Notes
* Find a token's contract address on its [CoinGecko](https://www.coingecko.com) page or via [Coins List](/reference/coins-list) with `include_platform=true`.
* Accepts ISO date strings (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM`, recommended) or UNIX timestamps for `from` and `to`.
* Auto-granularity when `interval` is not specified:
| Date range | Granularity |
| ------------------------- | --------------------- |
| 1 day from current time | **5-minutely** |
| 1 day from any other time | **hourly** |
| 2–90 days | **hourly** |
| Above 90 days | **daily** (00:00 UTC) |
* Enterprise plan subscribers can bypass auto-granularity:
| `interval` | Per request |
| ---------- | ------------------------ |
| `hourly` | **Any 100 days** |
| `5m` | **Any 10 days** |
| `1m` | **Any 1 day** (**Beta**) |
* Data availability: `1m` from 1 Jun 2026, `5m` from 9 Feb 2018, `hourly` from 30 Jan 2018.
The last completed UTC day (00:00) is available 35 minutes after midnight (00:35 UTC). Cache expires at 00:40 UTC.
Historical data on the **Basic plan** is restricted to the past 2 years. Subscribe to [Analyst plan & above](https://www.coingecko.com/en/api/pricing) for the full range.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.coins.contract.marketChart.getRange('0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', {
id: 'ethereum',
vs_currency: 'usd',
from: '2025-12-22',
to: '2025-12-31',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.coins.contract.market_chart.get_range(
"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
id="ethereum",
vs_currency="usd",
from_="2025-12-22",
to="2025-12-31",
)
print(response.model_dump_json(indent=2))
```
# Crypto Global Market Data
Source: https://docs.coingecko.com/reference/crypto-global
openapi-specs/pro-api.json get /global
To query cryptocurrency global data including active cryptocurrencies, markets, total crypto market cap and etc
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.global.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.global_.get()
print(response.model_dump_json(indent=2))
```
# Derivatives Exchanges List with Data
Source: https://docs.coingecko.com/reference/derivatives-exchanges
openapi-specs/pro-api.json get /derivatives/exchanges
To query all the derivatives exchanges with related data (ID, name, open interest, ...) on CoinGecko
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.derivatives.exchanges.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.derivatives.exchanges.get()
print(response)
```
# Derivatives Exchange Data by ID
Source: https://docs.coingecko.com/reference/derivatives-exchanges-id
openapi-specs/pro-api.json get /derivatives/exchanges/{id}
To query the derivatives exchange's related data (name, open interest, trade volume, ...) based on the exchange's ID
Use `include_tickers=all` to include all tickers, `unexpired` for unexpired tickers only, or leave blank to omit tickers.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.derivatives.exchanges.getID('binance_futures');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.derivatives.exchanges.get_id("binance_futures")
print(response.model_dump_json(indent=2))
```
# Derivatives Exchanges List
Source: https://docs.coingecko.com/reference/derivatives-exchanges-list
openapi-specs/pro-api.json get /derivatives/exchanges/list
To query all the supported derivatives exchanges with ID and name on CoinGecko
Use this endpoint to get derivatives exchange IDs for other endpoints that require an `id` parameter.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.derivatives.exchanges.getList();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.derivatives.exchanges.get_list()
print(response)
```
# Derivatives
Source: https://docs.coingecko.com/reference/derivatives-overview
Derivatives exchanges, perpetual and futures tickers, open interest and trading volume.
| Endpoint | Description |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [/derivatives/exchanges/list](/reference/derivatives-exchanges-list) | Query all supported derivatives exchanges with ID and name |
| [/derivatives](/reference/derivatives-tickers) | Query all tickers from derivatives exchanges |
| [/derivatives/exchanges](/reference/derivatives-exchanges) | Query all derivatives exchanges with data (ID, name, open interest, etc.) |
| [/derivatives/exchanges/\{id}](/reference/derivatives-exchanges-id) | Query derivatives exchange data by exchange ID |
# Derivatives Tickers List
Source: https://docs.coingecko.com/reference/derivatives-tickers
openapi-specs/pro-api.json get /derivatives
To query all the tickers from derivatives exchanges on CoinGecko
`open_interest` and `volume_24h` values in the response are in USD.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.derivatives.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.derivatives.get()
print(response)
```
# DEXs List by Network
Source: https://docs.coingecko.com/reference/dexes-list
openapi-specs/pro-api.json get /onchain/networks/{network}/dexes
To query all the supported decentralized exchanges (DEXs) based on the provided network on GeckoTerminal
Use this endpoint to get DEX IDs for other endpoints that require a `dex` parameter.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.dexes.get('eth');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.dexes.get("eth")
print(response.model_dump_json(indent=2))
```
# Endpoint Overview
Source: https://docs.coingecko.com/reference/endpoint-overview
Complete list of endpoints available in the Pro API
Authenticate your requests to start using the Pro API.
Plan-specific endpoint access is marked as:
* 💼 — [Analyst plan & above](https://www.coingecko.com/en/api/pricing) only
* 👑 — [Enterprise plan](https://www.coingecko.com/en/api/enterprise) only
* All other endpoints are available to all paid plans, including **Basic plan**
Some endpoints have parameters or data access exclusive to certain plans — refer to the endpoint reference page for details.
## CoinGecko
### Price
| Endpoint | Description |
| ----------------------------------------------------------- | -------------------------------------------------------------------- |
| [/simple/price](/reference/simple-price) | Query prices of one or more coins by Coin API IDs, symbols, or names |
| [/simple/token\_price/\{id}](/reference/simple-token-price) | Query one or more token prices by token contract addresses |
### Search & ID Map
| Endpoint | Description |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| [/search](/reference/search-data) | Search for coins, categories and markets on CoinGecko |
| [/coins/list](/reference/coins-list) | Query all supported coins with coin ID, name and symbol |
| [/asset\_platforms](/reference/asset-platforms-list) | Query all supported asset platforms (blockchain networks) |
| [/token\_lists/\{asset\_platform\_id}/all.json](/reference/token-lists) | Full list of tokens on a blockchain network supported by Ethereum token list standard |
| [/simple/supported\_vs\_currencies](/reference/simple-supported-currencies) | Query all supported currencies on CoinGecko |
### Coins
| Endpoint | Description |
| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| [/coins/markets](/reference/coins-markets) | Query all supported coins with price, market cap, volume and market data |
| [/coins/\{id}](/reference/coins-id) | Query all metadata and market data of a coin by coin ID |
| [/coins/\{id}/contract/\{contract\_address}](/reference/coins-contract-address) | Query all metadata and market data of a coin by asset platform and token contract address |
| [/coins/\{id}/tickers](/reference/coins-id-tickers) | Query coin tickers on both CEX and DEX by coin ID |
| [/coins/\{id}/history](/reference/coins-id-history) | Query historical data (price, market cap, 24hr volume, etc.) at a given date by coin ID |
| 💼 [/coins/list/new](/reference/coins-list-new) | Query the latest 200 coins recently listed on CoinGecko |
| 💼 [/coins/top\_gainers\_losers](/reference/coins-top-gainers-losers) | Query top 30 coins with largest price gain and loss by time duration |
| 💼 [/coins/\{id}/supply\_breakdown](/reference/coins-id-supply-breakdown) | Query the supply breakdown of a coin based on provided coin ID |
### Coin Charts
| Endpoint | Description |
| ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [/coins/\{id}/market\_chart](/reference/coins-id-market-chart) | Historical chart data (price, market cap, 24hr volume) by coin ID |
| [/coins/\{id}/market\_chart/range](/reference/coins-id-market-chart-range) | Historical chart data within a time range by coin ID |
| [/coins/\{id}/contract
/\{contract\_address}/market\_chart](/reference/contract-address-market-chart) | Historical chart data by asset platform and token contract address |
| [/coins/\{id}/contract
/\{contract\_address}/market\_chart/range](/reference/contract-address-market-chart-range) | Historical chart data within a time range by asset platform and token contract address |
| [/coins/\{id}/ohlc](/reference/coins-id-ohlc) | OHLC chart by coin ID |
| 💼 [/coins/\{id}/ohlc/range](/reference/coins-id-ohlc-range) | OHLC chart within a time range by coin ID |
| 👑 [/coins/\{id}/circulating\_supply\_chart](/reference/coins-id-circulating-supply-chart) | Historical circulating supply by coin ID |
| 👑 [/coins/\{id}
/circulating\_supply\_chart/range](/reference/coins-id-circulating-supply-chart-range) | Historical circulating supply within a time range by coin ID |
| 👑 [/coins/\{id}/total\_supply\_chart](/reference/coins-id-total-supply-chart) | Historical total supply by coin ID |
| 👑 [/coins/\{id}/total\_supply\_chart/range](/reference/coins-id-total-supply-chart-range) | Historical total supply within a time range by coin ID |
### Categories
| Endpoint | Description |
| ---------------------------------------------------------- | --------------------------------------------------------------------- |
| [/coins/categories/list](/reference/coins-categories-list) | Query all supported coin categories on CoinGecko |
| [/coins/categories](/reference/coins-categories) | Query all coin categories with market data (market cap, volume, etc.) |
### RWA
| Endpoint | Description |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| [/rwas/list](/reference/rwas-list) | Query all supported tokenized real world assets (RWAs) with RWA ID, name and symbol |
| [/rwas/markets](/reference/rwas-markets) | Query all supported RWAs with price, market cap, volume and market data |
| [/rwas/\{id}](/reference/rwas-id) | Query all metadata, market data and tokens of an RWA by RWA ID |
| [/rwas/\{id}/tickers](/reference/rwas-id-tickers) | Query RWA token tickers on centralized and decentralized exchanges by RWA ID |
| [/rwas/\{id}/market\_chart](/reference/rwas-id-market-chart) | Query historical chart data of an RWA including price, market cap and 24hrs volume |
| [/rwas/issuers/list](/reference/rwas-issuers-list) | Query all supported RWA issuers with issuer ID and name |
| [/rwas/issuers/\{id}](/reference/rwas-issuers-id) | Query market data and tokens of an RWA issuer by issuer ID |
### Exchanges
| Endpoint | Description |
| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [/exchanges/list](/reference/exchanges-list) | Query all supported exchanges with ID and name |
| [/exchanges](/reference/exchanges) | Query all supported exchanges with data (ID, name, country, etc.) |
| [/exchanges/\{id}](/reference/exchanges-id) | Query exchange data and top 100 tickers by exchange ID |
| [/exchanges/\{id}/tickers](/reference/exchanges-id-tickers) | Query exchange tickers by exchange ID |
| [/exchanges/\{id}/volume\_chart](/reference/exchanges-id-volume-chart) | Historical volume chart data in BTC by exchange ID |
| 💼 [/exchanges/\{id}/volume\_chart/range](/reference/exchanges-id-volume-chart-range) | Historical volume chart data in BTC within a date range by exchange ID |
### Derivatives
| Endpoint | Description |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [/derivatives/exchanges/list](/reference/derivatives-exchanges-list) | Query all supported derivatives exchanges with ID and name |
| [/derivatives](/reference/derivatives-tickers) | Query all tickers from derivatives exchanges |
| [/derivatives/exchanges](/reference/derivatives-exchanges) | Query all derivatives exchanges with data (ID, name, open interest, etc.) |
| [/derivatives/exchanges/\{id}](/reference/derivatives-exchanges-id) | Query derivatives exchange data by exchange ID |
### Public Treasury
| Endpoint | Description |
| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
| [/entities/list](/reference/entities-list) | Query all supported entities with entity ID, name, symbol, and country |
| [/\{entity}/public\_treasury/\{coin\_id}](/reference/companies-public-treasury) | Query public companies' and governments' crypto holdings by coin ID |
| [/public\_treasury/\{entity\_id}](/reference/public-treasury-entity) | Query public companies' and governments' crypto holdings by entity ID |
| [/public\_treasury/\{entity\_id}/\{coin\_id}
/holding\_chart](/reference/public-treasury-entity-chart) | Historical crypto holdings chart by entity ID and coin ID |
| [/public\_treasury/\{entity\_id}
/transaction\_history](/reference/public-treasury-transaction-history) | Crypto transaction history by entity ID |
### NFTs
| Endpoint | Description |
| ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| [/nfts/list](/reference/nfts-list) | Query all supported NFTs with ID, contract address, name, asset platform ID and symbol |
| [/nfts/\{id}](/reference/nfts-id) | Query NFT data (name, floor price, 24hr volume, etc.) by collection ID |
| [/nfts/\{asset\_platform\_id}/contract
/\{contract\_address}](/reference/nfts-contract-address) | Query NFT data by collection contract address and asset platform |
| 💼 [/nfts/markets](/reference/nfts-markets) | Query all supported NFT collections with floor price, market cap, volume and market data |
| 💼 [/nfts/\{id}/market\_chart](/reference/nfts-id-market-chart) | Historical NFT market data (floor price, market cap, 24hr volume) by collection ID |
| 💼 [/nfts/\{asset\_platform\_id}/contract
/\{contract\_address}/market\_chart](/reference/nfts-contract-address-market-chart) | Historical NFT market data by contract address |
| 💼 [/nfts/\{id}/tickers](/reference/nfts-id-tickers) | Latest floor price and 24hr volume per NFT marketplace by collection ID |
### Trending
| Endpoint | Description |
| ---------------------------------------------- | --------------------------------------------------------------------- |
| [/search/trending](/reference/trending-search) | Query trending search coins, NFTs and categories in the last 24 hours |
### News & Insights
| Endpoint | Description |
| ----------------------------------- | ---------------------------------------------------- |
| 💼 [/news](/reference/news) | Query the latest crypto news and guides on CoinGecko |
| 👑 [/insights](/reference/insights) | Query the latest coin insights on CoinGecko |
### Global
| Endpoint | Description |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [/global](/reference/crypto-global) | Query global crypto data (active cryptocurrencies, markets, total market cap, etc.) |
| [/global/decentralized\_finance\_defi](/reference/global-defi) | Query top 100 global DeFi data (market cap, trading volume) |
| 💼 [/global/market\_cap\_chart](/reference/global-market-cap-chart) | Historical global market cap and volume data |
### Utility
| Endpoint | Description |
| --------------------------------------------- | ------------------------------------------------------ |
| [/exchange\_rates](/reference/exchange-rates) | Query BTC exchange rates with other currencies |
| [/ping](/reference/ping-server) | Check API server status |
| [/key](/reference/api-usage) | Monitor account API usage (rate limits, credits, etc.) |
***
## Onchain
### Price
| Endpoint | Description |
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
| [/onchain/simple/networks/\{network}
/token\_price/\{addresses}](/reference/onchain-simple-price) | Token price by token contract addresses on a network |
| 👑 [/onchain/simple/token\_price/multi](/reference/onchain-simple-price-multi) | Token price by token contract addresses across networks |
### Search & ID Map
| Endpoint | Description |
| ----------------------------------------------------------- | --------------------------------------------------------------------- |
| [/onchain/search/pools](/reference/search-pools) | Search pools by pool address, token name, symbol, or contract address |
| [/onchain/networks](/reference/networks-list) | All supported networks on GeckoTerminal |
| [/onchain/networks/\{network}/dexes](/reference/dexes-list) | All supported DEXs by network |
### Pools
| Endpoint | Description |
| ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| [/onchain/networks/\{network}/pools
/\{address}](/reference/pool-address) | Query specific pool by network and pool address |
| [/onchain/networks/\{network}/pools/multi
/\{addresses}](/reference/pools-addresses) | Query multiple pools by network and pool addresses |
| [/onchain/networks/\{network}/pools
/\{pool\_address}/info](/reference/pool-token-info-contract-address) | Pool metadata (token details, socials, etc.) by pool address |
| [/onchain/networks/\{network}/pools](/reference/top-pools-network) | Top pools by network |
| [/onchain/networks/\{network}/dexes/\{dex}
/pools](/reference/top-pools-dex) | Top pools by network and DEX |
| [/onchain/networks/\{network}/tokens
/\{token\_address}/pools](/reference/top-pools-contract-address) | Top pools by token contract address |
| 💼 [/onchain/pools/megafilter](/reference/pools-megafilter) | Query pools by various filters across all networks |
### New & Trending Pools
| Endpoint | Description |
| --------------------------------------------------------------------------------------- | ----------------------------------------- |
| [/onchain/networks/new\_pools](/reference/latest-pools-list) | Latest pools across all networks |
| [/onchain/networks/\{network}/new\_pools](/reference/latest-pools-network) | Latest pools by network |
| [/onchain/networks/trending\_pools](/reference/trending-pools-list) | Trending pools across all networks |
| [/onchain/networks/\{network}
/trending\_pools](/reference/trending-pools-network) | Trending pools by network |
| 💼 [/onchain/pools/trending\_search](/reference/trending-search-pools) | Trending search pools across all networks |
### Tokens
| Endpoint | Description |
| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| [/onchain/networks/\{network}/tokens
/\{address}](/reference/token-data-contract-address) | Token data by token contract address on a network |
| [/onchain/networks/\{network}/tokens/multi
/\{addresses}](/reference/tokens-data-contract-addresses) | Multiple tokens data by token contract addresses on a network |
| 👑 [/onchain/tokens/multi](/reference/tokens-data-contract-addresses-multi) | Multiple tokens data by token contract addresses across networks |
| [/onchain/networks/\{network}/tokens
/\{address}/info](/reference/token-info-contract-address) | Token metadata (name, symbol, CoinGecko ID, socials, etc.) by token contract address |
| [/onchain/tokens/info\_recently\_updated](/reference/tokens-info-recent-updated) | 100 most recently updated tokens info across all networks |
### Charts
| Endpoint | Description |
| ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| [/onchain/networks/\{network}/pools
/\{pool\_address}/ohlcv/\{timeframe}](/reference/pool-ohlcv-contract-address) | Pool OHLCV chart by pool address |
| 💼 [/onchain/networks/\{network}/tokens
/\{token\_address}/ohlcv/\{timeframe}](/reference/token-ohlcv-token-address) | Token OHLCV chart by token address |
### Trades
| Endpoint | Description |
| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| [/onchain/networks/\{network}/pools
/\{pool\_address}/trades](/reference/pool-trades-contract-address) | Trades by pool address |
| 💼 [/onchain/networks/\{network}/pools
/\{pool\_address}/trades/range](/reference/pool-trades-contract-address-range) | Trades within a time range by pool address |
| 💼 [/onchain/networks/\{network}/tokens
/\{token\_address}/trades](/reference/token-trades-contract-address) | Trades across all pools by token address |
| 💼 [/onchain/networks/\{network}/tokens
/\{token\_address}/trades/range](/reference/token-trades-contract-address-range) | Trades within a time range across all pools by token address |
| 💼 [/onchain/networks/\{network}/tokens
/\{token\_address}/top\_traders](/reference/top-token-traders-token-address) | Top token traders by token contract address |
### Wallets
| Endpoint | Description |
| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| 💼 [/onchain/wallets/\{address}/balances](/reference/wallet-token-balances) | Query the token balances of a wallet address across networks |
| 💼 [/onchain/networks/\{network}/wallets
/\{address}/transfers](/reference/wallet-token-transfers) | Query the token transfers of a wallet address on a network |
### Holders
| Endpoint | Description |
| ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| 💼 [/onchain/networks/\{network}/tokens
/\{address}/top\_holders](/reference/top-token-holders-token-address) | Top token holders by token contract address |
| 💼 [/onchain/networks/\{network}/tokens
/\{token\_address}/holders\_chart](/reference/token-holders-chart-token-address) | Historical token holders chart by token contract address |
### Categories
| Endpoint | Description |
| ------------------------------------------------------------------------------- | ----------------------------------------------- |
| 💼 [/onchain/categories](/reference/categories-list) | Query all supported categories on GeckoTerminal |
| 💼 [/onchain/categories/\{category\_id}
/pools](/reference/pools-category) | Query pools by category ID |
***
⚡ **Need real-time data streams?**
Stream prices, trades, and OHLCV data with ultra-low latency via [WebSocket](/websocket).
![]()
Requires [Basic plan & above](https://www.coingecko.com/en/api/pricing).
# Entities List
Source: https://docs.coingecko.com/reference/entities-list
openapi-specs/pro-api.json get /entities/list
To query all the supported entities on CoinGecko with entity ID, name, symbol, and country
Use this endpoint to get entity IDs for other Public Treasury endpoints.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.entities.getList();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.entities.get_list()
print(response)
```
# BTC-to-Currency Exchange Rates
Source: https://docs.coingecko.com/reference/exchange-rates
openapi-specs/pro-api.json get /exchange_rates
To query BTC exchange rates with other currencies
Use this endpoint to convert BTC-denominated response data from other endpoints to different currencies.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.exchangeRates.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.exchange_rates.get()
print(response.model_dump_json(indent=2))
```
# Exchanges List with Data
Source: https://docs.coingecko.com/reference/exchanges
openapi-specs/pro-api.json get /exchanges
To query all the supported exchanges with exchanges' data (ID, name, country, etc.) that have active trading volumes on CoinGecko
Only exchanges with active trading volume on CoinGecko are included. Inactive or deactivated exchanges are removed from the list.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.exchanges.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.exchanges.get()
print(response)
```
# Exchange Data by ID
Source: https://docs.coingecko.com/reference/exchanges-id
openapi-specs/pro-api.json get /exchanges/{id}
To query exchange's data (name, year established, country, etc.), exchange volume in BTC and top 100 tickers based on exchange's ID
#### Notes
* Exchange volume is provided in BTC. Use [Exchange Rates](/reference/exchange-rates) to convert to other currencies.
* Tickers are limited to 100 items. Use [Exchange Tickers](/reference/exchanges-id-tickers) for more.
* For derivatives exchanges (e.g. `bitmex`, `binance_futures`), use [Derivatives Exchange Data](/reference/derivatives-exchanges-id) instead.
* When `dex_pair_format=symbol`, DEX pair `base` and `target` display as symbols (e.g. `WETH`, `USDC`) instead of contract addresses.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.exchanges.getID('binance');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.exchanges.get_id("binance")
print(response.model_dump_json(indent=2))
```
# Exchange Tickers by ID
Source: https://docs.coingecko.com/reference/exchanges-id-tickers
openapi-specs/pro-api.json get /exchanges/{id}/tickers
To query exchange's tickers based on exchange's ID
#### Notes
* Tickers are paginated to 100 items per page.
* Use `order=base_target` for stable pagination — sorts by `base` then `target` symbol in lexicographical order, preventing duplicate or missing tickers across pages.
* When `dex_pair_format=symbol`, DEX pair `base` and `target` display as symbols (e.g. `WETH`, `USDC`) instead of contract addresses.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.exchanges.tickers.get('binance');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.exchanges.tickers.get("binance")
print(response.model_dump_json(indent=2))
```
# Exchange Volume Chart by ID
Source: https://docs.coingecko.com/reference/exchanges-id-volume-chart
openapi-specs/pro-api.json get /exchanges/{id}/volume_chart
To query the historical volume chart data with time in UNIX and trading volume data in BTC based on exchange's ID
#### Notes
* Also works for derivatives exchanges (e.g. `bitmex`, `binance_futures`).
* Volume is provided in BTC. Use [Exchange Rates](/reference/exchange-rates) to convert to other currencies.
* Auto-granularity (cannot be adjusted):
* 1 day = 10-minutely
* 7, 14 days = hourly
* 30 days and above = daily
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.exchanges.volumeChart.get('binance', {
days: '1',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.exchanges.volume_chart.get(
"binance",
days="1",
)
print(response)
```
# Exchange Volume Chart within Time Range by ID
Source: https://docs.coingecko.com/reference/exchanges-id-volume-chart-range
openapi-specs/pro-api.json get /exchanges/{id}/volume_chart/range
To query the historical volume chart data in BTC by specifying date range in UNIX based on exchange's ID
#### Notes
* Also works for derivatives exchanges (e.g. `bitmex`, `binance_futures`).
* Data interval is fixed at daily.
* The date range between `from` and `to` must be within 31 days.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.exchanges.volumeChart.getRange('binance', {
from: 1767196800,
to: 1769702400,
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.exchanges.volume_chart.get_range(
"binance",
from_=1767196800,
to=1769702400,
)
print(response)
```
# Exchanges List
Source: https://docs.coingecko.com/reference/exchanges-list
openapi-specs/pro-api.json get /exchanges/list
To query all the supported exchanges with ID and name
#### Notes
* Use this endpoint to get exchange IDs (including derivatives exchanges) for other endpoints that require an `id` parameter.
* No pagination required — the full list is returned in a single response.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.exchanges.getList();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.exchanges.get_list()
print(response)
```
# Exchanges
Source: https://docs.coingecko.com/reference/exchanges-overview
Centralized exchange data, trading pairs and tickers, and historical exchange volume in BTC.
| Endpoint | Description |
| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [/exchanges/list](/reference/exchanges-list) | Query all supported exchanges with ID and name |
| [/exchanges](/reference/exchanges) | Query all supported exchanges with data (ID, name, country, etc.) |
| [/exchanges/\{id}](/reference/exchanges-id) | Query exchange data and top 100 tickers by exchange ID |
| [/exchanges/\{id}/tickers](/reference/exchanges-id-tickers) | Query exchange tickers by exchange ID |
| [/exchanges/\{id}/volume\_chart](/reference/exchanges-id-volume-chart) | Historical volume chart data in BTC by exchange ID |
| 💼 [/exchanges/\{id}/volume\_chart/range](/reference/exchanges-id-volume-chart-range) | Historical volume chart data in BTC within a date range by exchange ID |
# Global DeFi Market Data
Source: https://docs.coingecko.com/reference/global-defi
openapi-specs/pro-api.json get /global/decentralized_finance_defi
To query top 100 cryptocurrency global decentralized finance (DeFi) data including DeFi market cap, trading volume
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.global.decentralizedFinanceDefi.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.global_.decentralized_finance_defi.get()
print(response.model_dump_json(indent=2))
```
# Global Market Cap Chart Data
Source: https://docs.coingecko.com/reference/global-market-cap-chart
openapi-specs/pro-api.json get /global/market_cap_chart
To query historical global market cap and volume data by number of days away from now
#### Notes
* Auto-granularity:
* 1 day = **hourly** data
* 2 days and above = **daily** data
* Equivalent page on [CoinGecko Global Charts](https://www.coingecko.com/en/global-charts).
The last completed UTC day (00:00) is available 5 minutes after midnight (00:05 UTC). Cache always expires at 00:05 UTC.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.global.marketCapChart.get({
days: '1',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.global_.market_cap_chart.get(
days="1",
)
print(response.model_dump_json(indent=2))
```
# Global
Source: https://docs.coingecko.com/reference/global-overview
Total crypto market cap, volume, DeFi dominance and historical global market cap charts.
| Endpoint | Description |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [/global](/reference/crypto-global) | Query global crypto data (active cryptocurrencies, markets, total market cap, etc.) |
| [/global/decentralized\_finance\_defi](/reference/global-defi) | Query top 100 global DeFi data (market cap, trading volume) |
| 💼 [/global/market\_cap\_chart](/reference/global-market-cap-chart) | Historical global market cap and volume data |
# Coin Insights
Source: https://docs.coingecko.com/reference/insights
openapi-specs/pro-api.json get /insights
To query the latest coin insights on CoinGecko
#### Notes
* Find a coin's API ID on its [CoinGecko](https://www.coingecko.com) page, via [Coins List](/reference/coins-list), or this [Google Sheet](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
* Without `coin_id`, returns all latest insights on any coins on CoinGecko.
* `page` supports up to 20 pages, and `per_page` supports up to 20 results per page.
* Use `from` and `to` to filter insights by date range (ISO date string `YYYY-MM-DD`).
Not on the Enterprise plan? [Submit your interest](https://docs.google.com/forms/d/e/1FAIpQLSdpFCxXSIylFhEgrlj5Dt5gsOMyq_TkPjeV-044Pz3Wy8WuMA/viewform) to access this feature.
# New Pools List
Source: https://docs.coingecko.com/reference/latest-pools-list
openapi-specs/pro-api.json get /onchain/networks/new_pools
To query all the latest pools across all networks on GeckoTerminal
#### Notes
* Returns up to 20 pools per page. Use the `page` param to navigate more results. Pagination beyond 10 pages requires [Analyst plan or above](https://www.coingecko.com/en/api/pricing).
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate.
* Use `include` to return related attributes under the top-level `included` key.
* Equivalent page on [GeckoTerminal New Pools](https://www.geckoterminal.com/explore/new-crypto-pools).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.newPools.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.new_pools.get()
print(response.model_dump_json(indent=2))
```
# New Pools by Network
Source: https://docs.coingecko.com/reference/latest-pools-network
openapi-specs/pro-api.json get /onchain/networks/{network}/new_pools
To query all the latest pools based on the provided network
#### Notes
* Includes pools created within the past 48 hours.
* Returns up to 20 pools per page. Use the `page` param to navigate more results. Pagination beyond 10 pages requires [Analyst plan or above](https://www.coingecko.com/en/api/pricing).
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate.
* Use `include` to return related attributes under the top-level `included` key.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.newPools.getNetwork('eth');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.new_pools.get_network("eth")
print(response.model_dump_json(indent=2))
```
# Networks List
Source: https://docs.coingecko.com/reference/networks-list
openapi-specs/pro-api.json get /onchain/networks
To retrieve a list of all supported networks on GeckoTerminal
Use this endpoint to get network IDs for other endpoints that require a `network` parameter.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.get()
print(response.model_dump_json(indent=2))
```
# Crypto News
Source: https://docs.coingecko.com/reference/news
openapi-specs/pro-api.json get /news
To query the latest crypto news and guides on CoinGecko
#### Notes
* Without `coin_id`, returns all latest news as seen on [CoinGecko News](https://www.coingecko.com/en/news) (news only, no guides).
* With `coin_id`, returns both news and guides by default (`type=all`). Use `type` to filter by news or guides only.
* Pagination: `page` supports up to 20, `per_page` up to 20 — maximum 400 articles total.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.news.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.news.get()
print(response)
```
# News & Insights
Source: https://docs.coingecko.com/reference/news-and-insights-overview
Crypto news, guides and AI-generated coin insights published on CoinGecko.
| Endpoint | Description |
| ----------------------------------- | ---------------------------------------------------- |
| 💼 [/news](/reference/news) | Query the latest crypto news and guides on CoinGecko |
| 👑 [/insights](/reference/insights) | Query the latest coin insights on CoinGecko |
# NFTs Collection Data by Contract Address
Source: https://docs.coingecko.com/reference/nfts-contract-address
openapi-specs/pro-api.json get /nfts/{asset_platform_id}/contract/{contract_address}
To query all the NFT data (name, floor price, 24hr volume, ...) based on the NFT collection contract address and respective asset platform
Get `asset_platform_id` and `contract_address` from [NFTs List](/reference/nfts-list).
Solana NFTs and Art Blocks are not supported for this endpoint. Use [NFTs Collection Data by ID](/reference/nfts-id) instead.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.nfts.contract.getContractAddress('0xBd3531dA5CF5857e7CfAA92426877b022e612cf8', {
asset_platform_id: 'ethereum',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.nfts.contract.get_contract_address(
"0xBd3531dA5CF5857e7CfAA92426877b022e612cf8",
asset_platform_id="ethereum",
)
print(response.model_dump_json(indent=2))
```
# NFTs Collection Historical Chart Data by Contract Address
Source: https://docs.coingecko.com/reference/nfts-contract-address-market-chart
openapi-specs/pro-api.json get /nfts/{asset_platform_id}/contract/{contract_address}/market_chart
To query historical market data of a NFT collection, including floor price, market cap, and 24hr volume, by number of days away from now based on the provided contract address
#### Notes
* Auto-granularity:
* 1–14 days = **5-minutely** data
* 15 days and above = **daily** data (00:00 UTC)
Solana NFTs and Art Blocks are not supported. Use [NFTs Collection Historical Chart Data by ID](/reference/nfts-id-market-chart) instead.
The last completed UTC day (00:00) is available 5 minutes after midnight (00:05 UTC).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.nfts.contract.marketChart.get('0xBd3531dA5CF5857e7CfAA92426877b022e612cf8', {
asset_platform_id: 'ethereum',
days: '1',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.nfts.contract.market_chart.get(
"0xBd3531dA5CF5857e7CfAA92426877b022e612cf8",
asset_platform_id="ethereum",
days="1",
)
print(response.model_dump_json(indent=2))
```
# NFTs Collection Data by ID
Source: https://docs.coingecko.com/reference/nfts-id
openapi-specs/pro-api.json get /nfts/{id}
To query all the NFT data (name, floor price, 24hr volume, ...) based on the NFT collection ID
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.nfts.getID('pudgy-penguins');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.nfts.get_id("pudgy-penguins")
print(response.model_dump_json(indent=2))
```
# NFTs Collection Historical Chart Data by ID
Source: https://docs.coingecko.com/reference/nfts-id-market-chart
openapi-specs/pro-api.json get /nfts/{id}/market_chart
To query historical market data of a NFT collection, including floor price, market cap, and 24hr volume, by number of days away from now
#### Notes
* Auto-granularity:
* 1–14 days = **5-minutely** data
* 15 days and above = **daily** data (00:00 UTC)
The last completed UTC day (00:00) is available 5 minutes after midnight (00:05 UTC).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.nfts.marketChart.get('pudgy-penguins', {
days: '1',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.nfts.market_chart.get(
"pudgy-penguins",
days="1",
)
print(response.model_dump_json(indent=2))
```
# NFTs Collection Tickers by ID
Source: https://docs.coingecko.com/reference/nfts-id-tickers
openapi-specs/pro-api.json get /nfts/{id}/tickers
To query the latest floor price and 24hr volume of a NFT collection, on each NFT marketplace, e.g. OpenSea and Blur
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.nfts.tickers.get('pudgy-penguins');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.nfts.tickers.get("pudgy-penguins")
print(response.model_dump_json(indent=2))
```
# NFTs List
Source: https://docs.coingecko.com/reference/nfts-list
openapi-specs/pro-api.json get /nfts/list
To query all supported NFTs with ID, contract address, name, asset platform ID and symbol on CoinGecko
#### Notes
* Use this endpoint to get NFT collection IDs, `asset_platform_id`, and `contract_address` for other NFT endpoints.
* Results are paginated to 100 items per page.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.nfts.getList();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.nfts.get_list()
print(response)
```
# NFTs List with Market Data
Source: https://docs.coingecko.com/reference/nfts-markets
openapi-specs/pro-api.json get /nfts/markets
To query all the supported NFT collections with floor price, market cap, volume and market related data on CoinGecko
* Collections with low liquidity may not be ranked by Market Cap, [learn more](https://support.coingecko.com/hc/en-us/articles/37226121227545-What-is-NFT-Market-Cap).
* Sorting by MCap ranking prioritizes liquid collections by Market Cap, then illiquid collections by volume.
* Equivalent page on [CoinGecko NFTs](https://www.coingecko.com/en/nft).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.nfts.getMarkets();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.nfts.get_markets()
print(response)
```
# NFTs
Source: https://docs.coingecko.com/reference/nfts-overview
NFT collection floor price, market cap, 24h volume, marketplace tickers and historical charts.
| Endpoint | Description |
| ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| [/nfts/list](/reference/nfts-list) | Query all supported NFTs with ID, contract address, name, asset platform ID and symbol |
| [/nfts/\{id}](/reference/nfts-id) | Query NFT data (name, floor price, 24hr volume, etc.) by collection ID |
| [/nfts/\{asset\_platform\_id}/contract
/\{contract\_address}](/reference/nfts-contract-address) | Query NFT data by collection contract address and asset platform |
| 💼 [/nfts/markets](/reference/nfts-markets) | Query all supported NFT collections with floor price, market cap, volume and market data |
| 💼 [/nfts/\{id}/market\_chart](/reference/nfts-id-market-chart) | Historical NFT market data (floor price, market cap, 24hr volume) by collection ID |
| 💼 [/nfts/\{asset\_platform\_id}/contract
/\{contract\_address}/market\_chart](/reference/nfts-contract-address-market-chart) | Historical NFT market data by contract address |
| 💼 [/nfts/\{id}/tickers](/reference/nfts-id-tickers) | Latest floor price and 24hr volume per NFT marketplace by collection ID |
# Onchain Categories
Source: https://docs.coingecko.com/reference/onchain-categories-overview
GeckoTerminal onchain categories and the DEX pools within each category.
| Endpoint | Description |
| ------------------------------------------------------------------------------- | ----------------------------------------------- |
| 💼 [/onchain/categories](/reference/categories-list) | Query all supported categories on GeckoTerminal |
| 💼 [/onchain/categories/\{category\_id}
/pools](/reference/pools-category) | Query pools by category ID |
# Onchain Charts
Source: https://docs.coingecko.com/reference/onchain-charts-overview
OHLCV candlestick charts for DEX pools and tokens, from second to day timeframes.
| Endpoint | Description |
| ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| [/onchain/networks/\{network}/pools
/\{pool\_address}/ohlcv/\{timeframe}](/reference/pool-ohlcv-contract-address) | Pool OHLCV chart by pool address |
| 💼 [/onchain/networks/\{network}/tokens
/\{token\_address}/ohlcv/\{timeframe}](/reference/token-ohlcv-token-address) | Token OHLCV chart by token address |
# Onchain Holders
Source: https://docs.coingecko.com/reference/onchain-holders-overview
Top token holders and historical holder count for any onchain token.
| Endpoint | Description |
| ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| 💼 [/onchain/networks/\{network}/tokens
/\{address}/top\_holders](/reference/top-token-holders-token-address) | Top token holders by token contract address |
| 💼 [/onchain/networks/\{network}/tokens
/\{token\_address}/holders\_chart](/reference/token-holders-chart-token-address) | Historical token holders chart by token contract address |
# Onchain New & Trending Pools
Source: https://docs.coingecko.com/reference/onchain-new-and-trending-pools-overview
Newly created and trending DEX liquidity pools, across all networks or a single network.
| Endpoint | Description |
| --------------------------------------------------------------------------------------- | ----------------------------------------- |
| [/onchain/networks/new\_pools](/reference/latest-pools-list) | Latest pools across all networks |
| [/onchain/networks/\{network}/new\_pools](/reference/latest-pools-network) | Latest pools by network |
| [/onchain/networks/trending\_pools](/reference/trending-pools-list) | Trending pools across all networks |
| [/onchain/networks/\{network}
/trending\_pools](/reference/trending-pools-network) | Trending pools by network |
| 💼 [/onchain/pools/trending\_search](/reference/trending-search-pools) | Trending search pools across all networks |
# Onchain Pools
Source: https://docs.coingecko.com/reference/onchain-pools-overview
DEX liquidity pool data by network, DEX, pool address or token address, with pool metadata.
| Endpoint | Description |
| ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| [/onchain/networks/\{network}/pools
/\{address}](/reference/pool-address) | Query specific pool by network and pool address |
| [/onchain/networks/\{network}/pools/multi
/\{addresses}](/reference/pools-addresses) | Query multiple pools by network and pool addresses |
| [/onchain/networks/\{network}/pools
/\{pool\_address}/info](/reference/pool-token-info-contract-address) | Pool metadata (token details, socials, etc.) by pool address |
| [/onchain/networks/\{network}/pools](/reference/top-pools-network) | Top pools by network |
| [/onchain/networks/\{network}/dexes/\{dex}
/pools](/reference/top-pools-dex) | Top pools by network and DEX |
| [/onchain/networks/\{network}/tokens
/\{token\_address}/pools](/reference/top-pools-contract-address) | Top pools by token contract address |
| 💼 [/onchain/pools/megafilter](/reference/pools-megafilter) | Query pools by various filters across all networks |
# Onchain Price
Source: https://docs.coingecko.com/reference/onchain-price-overview
Onchain token prices by contract address across every network GeckoTerminal indexes.
| Endpoint | Description |
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
| [/onchain/simple/networks/\{network}
/token\_price/\{addresses}](/reference/onchain-simple-price) | Token price by token contract addresses on a network |
| 👑 [/onchain/simple/token\_price/multi](/reference/onchain-simple-price-multi) | Token price by token contract addresses across networks |
# Onchain Search & ID Map
Source: https://docs.coingecko.com/reference/onchain-search-and-id-map-overview
Search DEX pools and look up the network and DEX identifiers the onchain endpoints require.
| Endpoint | Description |
| ----------------------------------------------------------- | --------------------------------------------------------------------- |
| [/onchain/search/pools](/reference/search-pools) | Search pools by pool address, token name, symbol, or contract address |
| [/onchain/networks](/reference/networks-list) | All supported networks on GeckoTerminal |
| [/onchain/networks/\{network}/dexes](/reference/dexes-list) | All supported DEXs by network |
# Token Price by Token Addresses
Source: https://docs.coingecko.com/reference/onchain-simple-price
openapi-specs/pro-api.json get /onchain/simple/networks/{network}/token_price/{addresses}
To get token price based on the provided token contract address on a network
#### Notes
* Prices are returned in USD. Addresses not found in GeckoTerminal will be ignored.
* Supports up to **100 contract addresses** per request ([Analyst plan or above](https://www.coingecko.com/en/api/pricing)).
* Unverified token market cap returns `null`. Use `mcap_fdv_fallback=true` to return FDV value (as seen on [GeckoTerminal](https://www.geckoterminal.com/)) when market cap data is unavailable.
* GeckoTerminal's routing selects the best pool for pricing based on liquidity and activity. For full control, use [Specific Pool Data](/reference/pool-address) with a specific pool address.
* Set `include_inactive_source=true` to expand the search to recently active pools (up to 1 year) if no top pool is found.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.simple.networks.tokenPrice.getAddresses('0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2', {
network: 'eth',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.simple.networks.token_price.get_addresses(
"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
network="eth",
)
print(response.model_dump_json(indent=2))
```
# Token Price by Token Addresses across Networks
Source: https://docs.coingecko.com/reference/onchain-simple-price-multi
openapi-specs/pro-api.json get /onchain/simple/token_price/multi
To get token prices based on the provided token contract addresses across multiple networks in a single request
#### Notes
* Each `tokens` entry pairs a network ID with a token contract address, separated by `:`
* For example, `eth:0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,solana:6NwarBvDkXhByqVp2Qkq5i9XbtA2B3Bwe8SWGu9vpump`.
* Networks can be mixed freely in one request, up to **50 pairs**.
* Responses are keyed by the same pairs, so a token address that appears on several networks stays unambiguous.
* Unverified token market cap returns `null`. Use `mcap_fdv_fallback=true` to return FDV value (as seen on [GeckoTerminal](https://www.geckoterminal.com/)) when market cap data is unavailable.
* GeckoTerminal's routing selects the best pool for pricing based on liquidity and activity. For full control, use [Specific Pool Data](/reference/pool-address) with a specific pool address.
* Set `include_inactive_source=true` to expand the search to recently active pools (up to 1 year) if no top pool is found.
An unknown network ID fails the whole request, while an unknown token address does not.
* An unsupported `network_id` returns a `400` naming the offending IDs.
* A token address that cannot be resolved on a supported network is omitted from the response.
# Onchain Tokens
Source: https://docs.coingecko.com/reference/onchain-tokens-overview
Onchain token data, metadata and socials by contract address, for one or many tokens.
| Endpoint | Description |
| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| [/onchain/networks/\{network}/tokens
/\{address}](/reference/token-data-contract-address) | Token data by token contract address on a network |
| [/onchain/networks/\{network}/tokens/multi
/\{addresses}](/reference/tokens-data-contract-addresses) | Multiple tokens data by token contract addresses on a network |
| 👑 [/onchain/tokens/multi](/reference/tokens-data-contract-addresses-multi) | Multiple tokens data by token contract addresses across networks |
| [/onchain/networks/\{network}/tokens
/\{address}/info](/reference/token-info-contract-address) | Token metadata (name, symbol, CoinGecko ID, socials, etc.) by token contract address |
| [/onchain/tokens/info\_recently\_updated](/reference/tokens-info-recent-updated) | 100 most recently updated tokens info across all networks |
# Onchain Trades
Source: https://docs.coingecko.com/reference/onchain-trades-overview
DEX trade history for a pool or token, plus a token's top traders.
| Endpoint | Description |
| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| [/onchain/networks/\{network}/pools
/\{pool\_address}/trades](/reference/pool-trades-contract-address) | Trades by pool address |
| 💼 [/onchain/networks/\{network}/pools
/\{pool\_address}/trades/range](/reference/pool-trades-contract-address-range) | Trades within a time range by pool address |
| 💼 [/onchain/networks/\{network}/tokens
/\{token\_address}/trades](/reference/token-trades-contract-address) | Trades across all pools by token address |
| 💼 [/onchain/networks/\{network}/tokens
/\{token\_address}/trades/range](/reference/token-trades-contract-address-range) | Trades within a time range across all pools by token address |
| 💼 [/onchain/networks/\{network}/tokens
/\{token\_address}/top\_traders](/reference/top-token-traders-token-address) | Top token traders by token contract address |
# Onchain Wallets
Source: https://docs.coingecko.com/reference/onchain-wallets-overview
Token balances and raw token transfers for any wallet address, with USD value and liquidity per holding across multiple networks.
| Endpoint | Description |
| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| 💼 [/onchain/wallets/\{address}/balances](/reference/wallet-token-balances) | Query the token balances of a wallet address across networks |
| 💼 [/onchain/networks/\{network}/wallets
/\{address}/transfers](/reference/wallet-token-transfers) | Query the token transfers of a wallet address on a network |
***
### Coming soon
| Endpoint | Description |
| ------------------------------------------------------------ | --------------------------------------------------------------- |
| /onchain/networks/\{network}/wallets
/\{address}/trades | Trade history of a wallet address on a network |
| /onchain/wallets/\{address}/pnl | Realized and unrealized PnL of a wallet address across networks |
# API Server Status
Source: https://docs.coingecko.com/reference/ping-server
openapi-specs/pro-api.json get /ping
To check the API server status
You can also check [status.coingecko.com](https://status.coingecko.com/) for real-time API server status and maintenance notices.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.ping.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.ping.get()
print(response.model_dump_json(indent=2))
```
# Specific Pool Data by Pool Address
Source: https://docs.coingecko.com/reference/pool-address
openapi-specs/pro-api.json get /onchain/networks/{network}/pools/{address}
To query the specific pool based on the provided network and pool address
#### Notes
* Addresses not found in GeckoTerminal will be ignored.
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate. Verified market cap is sourced from CoinGecko and may exceed FDV if it includes tokens on other networks.
* Use `include` to return related attributes under the top-level `included` key.
* `locked_liquidity_percentage` is updated daily.
* Set `include_composition=true` to surface the balance and liquidity value of base and quote tokens.
* Bonding curve pools (e.g. non-graduated launchpad pools) return a `launchpad_details` object with graduation status and migration details.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.pools.getAddress('0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640', {
network: 'eth',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.pools.get_address(
"0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
network="eth",
)
print(response.model_dump_json(indent=2))
```
# Pool OHLCV Chart by Pool Address
Source: https://docs.coingecko.com/reference/pool-ohlcv-contract-address
openapi-specs/pro-api.json get /onchain/networks/{network}/pools/{pool_address}/ohlcv/{timeframe}
To get the OHLCV chart (Open, High, Low, Close, Volume) of a pool based on the provided pool address on a network
#### Notes
* Use `timeframe` with `aggregate` for custom intervals (e.g. `minute?aggregate=15` for 15-minute OHLCV).
* Timestamps use epoch/unix format (e.g. `1708850449`).
* Each call retrieves a **max 6-month range** — use `before_timestamp` for older data.
* Each `ohlcv_list` element:
```
[
timestamp,
open,
high,
low,
close,
volume
]
```
* Intervals with no swaps are skipped by default. Set `include_empty_intervals=true` to fill gaps (OHLC = previous close, volume = 0).
**Historical Access by Plan:**
* **Basic:** past 6 months
* **[Analyst and above](https://www.coingecko.com/en/api/pricing):** September 2021 to present (depending on pool tracking start)
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.pools.ohlcv.getTimeframe('day', {
network: 'eth',
pool_address: '0x06da0fd433c1a5d7a4faa01111c044910a184553',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.pools.ohlcv.get_timeframe(
"day",
network="eth",
pool_address="0x06da0fd433c1a5d7a4faa01111c044910a184553",
)
print(response.model_dump_json(indent=2))
```
# Pool Tokens Info by Pool Address
Source: https://docs.coingecko.com/reference/pool-token-info-contract-address
openapi-specs/pro-api.json get /onchain/networks/{network}/pools/{pool_address}/info
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
#### Notes
* Learn more about [GT Score](https://support.coingecko.com/hc/en-us/articles/38381394237593-What-is-GT-Score-How-is-GT-Score-calculated) and [GT Verified](https://support.coingecko.com/hc/en-us/articles/54413671274649-What-is-GT-Verified-Badge).
* `holders` data is currently in Beta, with ongoing improvements to coverage and update frequency.
| Chain | Network `id` |
| --------- | ------------- |
| Solana | `solana` |
| Ethereum | `eth` |
| Base | `base` |
| BNB Chain | `bsc` |
| Optimism | `optimism` |
| Arbitrum | `arbitrum` |
| Polygon | `polygon_pos` |
| TON | `ton` |
| Sui | `sui-network` |
| Robinhood | `robinhood` |
| Ronin | `ronin` |
| Bittensor | `bittensor` |
* `distribution_percentage` coverage:
* Solana: `top_10`, `11_20`, `21_40`, `rest`
* Other chains: `top_10`, `11_30`, `31_50`, `rest`
* Bonding curve tokens (non-graduated launchpad tokens) include a `launchpad_details` object with graduation status.
- Metadata (image, websites, description, socials) is unvetted unless the token is [GT Verified](https://support.coingecko.com/hc/en-us/articles/54413671274649-What-is-GT-Verified-Badge) (`gt_verified: true`) or reviewed by CoinGecko.
- For CoinGecko-reviewed metadata, use [Coin Data by ID](/reference/coins-id) or [Coin Data by Token Address](/reference/coins-contract-address).
For pool market data (price, transactions, volume), use [Specific Pool Data](/reference/pool-address) instead.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.pools.info.get('8WwcNqdZjCY5Pt7AkhupAFknV2txca9sq6YBkGzLbvdt', {
network: 'solana',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.pools.info.get(
"8WwcNqdZjCY5Pt7AkhupAFknV2txca9sq6YBkGzLbvdt",
network="solana",
)
print(response.model_dump_json(indent=2))
```
# Trades by Pool Address
Source: https://docs.coingecko.com/reference/pool-trades-contract-address
openapi-specs/pro-api.json get /onchain/networks/{network}/pools/{pool_address}/trades
To query the trades based on the provided pool address
#### Notes
* Paginate with `cursor` rather than a page number:
* Pass `meta.next_cursor` back unchanged as `cursor` to fetch the next page.
* `meta.next_cursor` is `null` on the last page.
* For an absolute date window instead of a relative lookback, consider [Trades within Time Range by Pool Address](/reference/pool-trades-contract-address-range) (Analyst & above).
`trading_period`, `cursor` and `per_page` require [Analyst plan & above](https://www.coingecko.com/en/api/pricing). Without them, the endpoint returns the last 300 trades from the past 24 hours.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.pools.trades.get('0x06da0fd433c1a5d7a4faa01111c044910a184553', {
network: 'eth',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.pools.trades.get(
"0x06da0fd433c1a5d7a4faa01111c044910a184553",
network="eth",
)
print(response.model_dump_json(indent=2))
```
# Trades within Time Range by Pool Address
Source: https://docs.coingecko.com/reference/pool-trades-contract-address-range
openapi-specs/pro-api.json get /onchain/networks/{network}/pools/{pool_address}/trades/range
To query the trades within a range of timestamp based on the provided pool address
#### Notes
* Paginate with `cursor` rather than a page number:
* Pass `meta.next_cursor` back unchanged as `cursor` to fetch the next page.
* `meta.next_cursor` is `null` on the last page.
* For a relative lookback instead of an absolute window, use [Trades by Pool Address](/reference/pool-trades-contract-address) with `trading_period`.
`from` and `to` are both required, and the window between them cannot exceed 30 days.
* Both ends are inclusive.
* Neither may be later than the current server time.
# Multiple Pools Data by Pool Addresses
Source: https://docs.coingecko.com/reference/pools-addresses
openapi-specs/pro-api.json get /onchain/networks/{network}/pools/multi/{addresses}
To query multiple pools based on the provided network and pool addresses
#### Notes
* Addresses not found in GeckoTerminal will be ignored.
* Supports up to **50 pool addresses** per request ([Analyst plan or above](https://www.coingecko.com/en/api/pricing)).
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate. Verified market cap is sourced from CoinGecko and may exceed FDV if it includes tokens on other networks.
* Use `include` to return related attributes under the top-level `included` key.
* `locked_liquidity_percentage` is updated daily.
* Set `include_composition=true` to surface balance and liquidity of base and quote tokens.
* Bonding curve pools (non-graduated launchpad pools) return a `launchpad_details` object with graduation status.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.pools.multi.getAddresses('0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640', {
network: 'eth',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.pools.multi.get_addresses(
"0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
network="eth",
)
print(response.model_dump_json(indent=2))
```
# Pools by Category ID
Source: https://docs.coingecko.com/reference/pools-category
openapi-specs/pro-api.json get /onchain/categories/{category_id}/pools
To query all the pools based on the provided category ID
#### Notes
* Get category IDs from [Categories List](/reference/categories-list). Use `include=base_token` to retrieve tokens for a specific category.
* Trending rankings are determined by:
* User engagement on GeckoTerminal
* Market activity (volume, transactions)
* Pool security (liquidity, honeypot checks)
* Returns up to 20 pools per page. Use the `page` param to navigate more results.
* GeckoTerminal categories are different from [CoinGecko categories](/reference/coins-categories-list).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.categories.getPools('pump-fun');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.categories.get_pools("pump-fun")
print(response.model_dump_json(indent=2))
```
# Megafilter for Pools
Source: https://docs.coingecko.com/reference/pools-megafilter
openapi-specs/pro-api.json get /onchain/pools/megafilter
To query pools based on various filters across all networks on GeckoTerminal
#### Notes
* Use `checks` to filter pools:
* `no_honeypot` — exclude honeypot pools (GoPlus & De.Fi Scanner)
* `good_gt_score` — GT Score of at least 75
* `on_coingecko` — tokens listed on CoinGecko
* `has_social` — social links and token info updated
* `dexes` param can only be used when a single `networks` is specified.
* Returns up to 20 pools per page.
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate.
* Use `include` to return related attributes under the top-level `included` key.
* `include_unknown_honeypot_tokens=true` includes tokens with unknown honeypot status (only works with `checks=no_honeypot`).
Honeypot data is not supported for Solana.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.pools.megafilter.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.pools.megafilter.get()
print(response.model_dump_json(indent=2))
```
# Price
Source: https://docs.coingecko.com/reference/price-overview
Current prices for coins and tokens by ID, symbol, name, or contract address.
| Endpoint | Description |
| ----------------------------------------------------------- | -------------------------------------------------------------------- |
| [/simple/price](/reference/simple-price) | Query prices of one or more coins by Coin API IDs, symbols, or names |
| [/simple/token\_price/\{id}](/reference/simple-token-price) | Query one or more token prices by token contract addresses |
# Crypto Treasury Holdings by Entity ID
Source: https://docs.coingecko.com/reference/public-treasury-entity
openapi-specs/pro-api.json get /public_treasury/{entity_id}
To query public companies' and governments' cryptocurrency holdings by entity ID
Equivalent page on [CoinGecko Bitcoin Treasuries](https://www.coingecko.com/en/treasuries/bitcoin).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.publicTreasury.getEntityID('strategy');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.public_treasury.get_entity_id("strategy")
print(response.model_dump_json(indent=2))
```
# Crypto Treasury Holdings Historical Chart Data by ID
Source: https://docs.coingecko.com/reference/public-treasury-entity-chart
openapi-specs/pro-api.json get /public_treasury/{entity_id}/{coin_id}/holding_chart
To query historical cryptocurrency holdings chart of public companies and governments by entity ID and coin ID
#### Notes
* Find entity IDs via [Entities List](/reference/entities-list) and coin IDs via [Coins List](/reference/coins-list).
* Data available from August 2020 onwards.
* Historical access varies by plan:
| Plan | Maximum period | `days` values |
| ------------------ | -------------- | ----------------------------------- |
| Demo / Keyless API | 1 year | `7, 14, 30, 90, 180, 365` |
| Basic | 2 years | `7, 14, 30, 90, 180, 365, 730` |
| Analyst and above | Full | `7, 14, 30, 90, 180, 365, 730, max` |
* `include_empty_intervals=false` (default): only intervals with transactions. Set to `true` to return all intervals, filled with the most recent data.
* Equivalent page on [CoinGecko Strategy Treasury](https://www.coingecko.com/en/treasuries/companies/strategy).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.publicTreasury.getHoldingChart('bitcoin', {
entity_id: 'strategy',
days: '365',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.public_treasury.get_holding_chart(
"bitcoin",
entity_id="strategy",
days="365",
)
print(response.model_dump_json(indent=2))
```
# Public Treasury
Source: https://docs.coingecko.com/reference/public-treasury-overview
Bitcoin and crypto holdings of public companies and governments, with holding charts and transaction history.
| Endpoint | Description |
| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
| [/entities/list](/reference/entities-list) | Query all supported entities with entity ID, name, symbol, and country |
| [/\{entity}/public\_treasury/\{coin\_id}](/reference/companies-public-treasury) | Query public companies' and governments' crypto holdings by coin ID |
| [/public\_treasury/\{entity\_id}](/reference/public-treasury-entity) | Query public companies' and governments' crypto holdings by entity ID |
| [/public\_treasury/\{entity\_id}/\{coin\_id}
/holding\_chart](/reference/public-treasury-entity-chart) | Historical crypto holdings chart by entity ID and coin ID |
| [/public\_treasury/\{entity\_id}
/transaction\_history](/reference/public-treasury-transaction-history) | Crypto transaction history by entity ID |
# Crypto Treasury Transaction History by Entity ID
Source: https://docs.coingecko.com/reference/public-treasury-transaction-history
openapi-specs/pro-api.json get /public_treasury/{entity_id}/transaction_history
To query public companies' and governments' cryptocurrency transaction history by entity ID
#### Notes
* Find entity IDs via [Entities List](/reference/entities-list). Filter by coin using `coin_ids` (comma-separated), with IDs from [Coins List](/reference/coins-list).
* Data available from August 2020 onwards.
* Multi-page access (`page` > `1`) is exclusive to [Analyst plan and above](https://www.coingecko.com/en/api/pricing).
* Equivalent page on [CoinGecko Strategy Treasury](https://www.coingecko.com/en/treasuries/companies/strategy).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.publicTreasury.getTransactionHistory('strategy');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.public_treasury.get_transaction_history("strategy")
print(response.model_dump_json(indent=2))
```
# Real World Assets (RWA)
Source: https://docs.coingecko.com/reference/rwa-overview
Aggregated onchain market data for tokenized stocks, commodities and ETFs, their tokens and issuers.
| Endpoint | Description |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| [/rwas/list](/reference/rwas-list) | Query all supported tokenized real world assets (RWAs) with RWA ID, name and symbol |
| [/rwas/markets](/reference/rwas-markets) | Query all supported RWAs with price, market cap, volume and market data |
| [/rwas/\{id}](/reference/rwas-id) | Query all metadata, market data and tokens of an RWA by RWA ID |
| [/rwas/\{id}/tickers](/reference/rwas-id-tickers) | Query RWA token tickers on centralized and decentralized exchanges by RWA ID |
| [/rwas/\{id}/market\_chart](/reference/rwas-id-market-chart) | Query historical chart data of an RWA including price, market cap and 24hrs volume |
| [/rwas/issuers/list](/reference/rwas-issuers-list) | Query all supported RWA issuers with issuer ID and name |
| [/rwas/issuers/\{id}](/reference/rwas-issuers-id) | Query market data and tokens of an RWA issuer by issuer ID |
# RWA Data by ID
Source: https://docs.coingecko.com/reference/rwas-id
openapi-specs/pro-api.json get /rwas/{id}
To query all the metadata, market data and tokens of a RWA based on a particular RWA ID
#### Notes
* Find an RWA's API ID via [RWA List](/reference/rwas-list).
* Returns metadata only by default — set `tokens` and `tokenized_market_data` to `true` to include those objects.
* Each `tokens.id` is also a coin ID. Use it with [Coin Data by ID](/reference/coins-id) to query the individual token.
`tokenized_market_data` reflects the aggregated onchain tokenized market, not the underlying asset's spot market. All values are in USD.
# RWA Historical Chart Data by ID
Source: https://docs.coingecko.com/reference/rwas-id-market-chart
openapi-specs/pro-api.json get /rwas/{id}/market_chart
To get the historical chart data of a RWA including time in UNIX, price, market cap and 24hrs volume based on a particular RWA ID
#### Notes
* Find an RWA's API ID via [RWA List](/reference/rwas-list).
* Auto-granularity when `interval` is not specified:
| Date range | Granularity |
| ----------------------- | --------------------- |
| 1 day from current time | **5-minutely** |
| 2–90 days | **hourly** |
| Above 90 days | **daily** (00:00 UTC) |
* Override with the `interval` parameter:
| `interval` | Lookback |
| ---------- | ---------------------------------- |
| `daily` | — |
| `hourly` | **Past 100 days** |
| `5m` | **Past 10 days** (Enterprise only) |
* Data available from 1 July 2025 onwards for stocks and ETFs, and 15 September 2019 onwards for commodities.
- The last completed UTC day (00:00) is available 10 minutes after midnight (00:10 UTC).
- Values reflect the aggregated onchain tokenized market, not the underlying asset's spot market. All values are in USD.
Historical data on the **Basic plan** is restricted to the past 2 years. Subscribe to [Analyst plan & above](https://www.coingecko.com/en/api/pricing) for the full range.
# RWA Tickers by ID
Source: https://docs.coingecko.com/reference/rwas-id-tickers
openapi-specs/pro-api.json get /rwas/{id}/tickers
To query the RWA tokens tickers on both centralized exchange (CEX) and decentralized exchange (DEX) based on a particular RWA ID
#### Notes
* Find an RWA's API ID via [RWA List](/reference/rwas-list).
* Returns tickers for every token tracking this RWA. Use `issuer_ids` to filter by issuer — refer to [RWA Issuers List](/reference/rwas-issuers-list) for available values.
* Tickers are paginated to 100 items per page.
* Use `exchange_ids` to filter tickers for a specific exchange.
* When `dex_pair_format=symbol`, DEX pair `base` and `target` display as symbols (e.g. `WETH`, `USDC`) instead of contract addresses.
* When sorting by `volume`, `converted_volume` is used instead of `volume`.
# RWA Issuer Data by ID
Source: https://docs.coingecko.com/reference/rwas-issuers-id
openapi-specs/pro-api.json get /rwas/issuers/{id}
To query the market data (market cap, volume, etc.) and tokens of an issuer based on a particular issuer ID
#### Notes
* Find an issuer's API ID via [RWA Issuers List](/reference/rwas-issuers-list).
* Each `tokens.id` is also a coin ID. Use it with [Coin Data by ID](/reference/coins-id) to query the individual token.
`market_cap`, `market_cap_change_24h`, and `volume_24h` are aggregated across the tokens issued by this issuer. All values are in USD.
# RWA Issuers List
Source: https://docs.coingecko.com/reference/rwas-issuers-list
openapi-specs/pro-api.json get /rwas/issuers/list
To query all the supported RWA issuers on CoinGecko
#### Notes
* Use this endpoint to get issuer IDs for endpoints that require an `issuer` or `issuer_ids` parameter, such as [RWA List with Market Data](/reference/rwas-markets).
* No pagination required — the full list is returned in a single response.
# RWA List
Source: https://docs.coingecko.com/reference/rwas-list
openapi-specs/pro-api.json get /rwas/list
To query all the supported tokenized real world assets (RWAs) on CoinGecko with RWA ID, name and symbol
#### Notes
* Use this endpoint to get RWA IDs for other endpoints that require an `id` parameter.
* Returns all RWAs by default. Use `asset_type` to filter for a single type.
* No pagination required — the full list is returned in a single response.
* Equivalent page on [CoinGecko Real World Assets](https://www.coingecko.com/en/real-world-assets).
# RWA List with Market Data
Source: https://docs.coingecko.com/reference/rwas-markets
openapi-specs/pro-api.json get /rwas/markets
To query all the supported RWAs with price, market cap, volume and market related data
#### Notes
* Filter by `ids`, `names`, or `symbols`. When multiple are provided, priority is: `ids` > `names` > `symbols`.
* URL-encode spaces in `names` (e.g. `Micron%20Technology`).
* Maximum of **250** IDs per request. Wildcard searches are not supported.
* Use `per_page` and `page` to paginate results.
* Equivalent page on [CoinGecko Real World Assets](https://www.coingecko.com/en/real-world-assets).
Filter by issuer using the `issuer` param — refer to [RWA Issuers List](/reference/rwas-issuers-list) for available values.
`tokenized_market_data` reflects the aggregated onchain tokenized market, not the underlying asset's spot market. All values are in USD.
# Search & ID Map
Source: https://docs.coingecko.com/reference/search-and-id-map-overview
Search coins, categories and markets, and look up the coin, asset platform and currency IDs other endpoints require.
| Endpoint | Description |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| [/search](/reference/search-data) | Search for coins, categories and markets on CoinGecko |
| [/coins/list](/reference/coins-list) | Query all supported coins with coin ID, name and symbol |
| [/asset\_platforms](/reference/asset-platforms-list) | Query all supported asset platforms (blockchain networks) |
| [/token\_lists/\{asset\_platform\_id}/all.json](/reference/token-lists) | Full list of tokens on a blockchain network supported by Ethereum token list standard |
| [/simple/supported\_vs\_currencies](/reference/simple-supported-currencies) | Query all supported currencies on CoinGecko |
# Search Queries
Source: https://docs.coingecko.com/reference/search-data
openapi-specs/pro-api.json get /search
To search for coins, categories and markets listed on CoinGecko
Results are sorted by market cap in descending order.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.search.get({
query: 'bitcoin',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.search.get(
query="bitcoin",
)
print(response.model_dump_json(indent=2))
```
# Search Pools & Tokens
Source: https://docs.coingecko.com/reference/search-pools
openapi-specs/pro-api.json get /onchain/search/pools
To search for pools across all networks by pool address, token name, token symbol, or token contract address
#### Notes
* Search by pool address, token name, token symbol, or token contract address.
* Returns up to 20 pools per page. Use the `page` param to navigate more results. Pagination beyond 10 pages requires [Analyst plan or above](https://www.coingecko.com/en/api/pricing).
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate.
* Use `include` to return related attributes under the top-level `included` key.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.search.pools.get({
query: 'weth',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.search.pools.get(
query="weth",
)
print(response.model_dump_json(indent=2))
```
# Coin Price by IDs, Symbols, or Names
Source: https://docs.coingecko.com/reference/simple-price
openapi-specs/pro-api.json get /simple/price
To query the prices of one or more coins by using their unique Coin API IDs, symbols, or names
#### Notes
* You can look up coins by `ids`, `names`, or `symbols`. When multiple are provided, priority is: `ids` > `names` > `symbols`.
* Find a coin's API ID on its [CoinGecko](https://www.coingecko.com) page, via [Coins List](/reference/coins-list), or this [Google Sheet](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
* Use `include_last_updated_at=true` or `include_24hr_change=true` (returns `null` if stale) to verify price freshness.
* `include_tokens=all` only works with `symbols` lookups, limited to 50 symbols per request.
* Maximum of **515** IDs per request. Wildcard searches are not supported.
* URL-encode spaces in `names` (e.g. `Binance%20Coin`).
Cross-check prices on [CoinGecko](https://www.coingecko.com) and learn about the [price methodology](https://www.coingecko.com/en/methodology).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.simple.price.get({
vs_currencies: 'usd',
ids: 'bitcoin',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.simple.price.get(
vs_currencies="usd",
ids="bitcoin",
)
print(response)
```
# Currencies List
Source: https://docs.coingecko.com/reference/simple-supported-currencies
openapi-specs/pro-api.json get /simple/supported_vs_currencies
To query all the supported currencies on CoinGecko
Use this endpoint to get valid values for `vs_currencies` parameters in other endpoints like [Coin Price](/reference/simple-price).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.simple.supportedVsCurrencies.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.simple.supported_vs_currencies.get()
print(response)
```
# Coin Price by Token Addresses
Source: https://docs.coingecko.com/reference/simple-token-price
openapi-specs/pro-api.json get /simple/token_price/{id}
To query one or more token prices by using their token contract addresses
#### Notes
* Returns the global average price aggregated across all active exchanges on CoinGecko.
* Find a token's contract address on its [CoinGecko](https://www.coingecko.com) page or via [Coins List](/reference/coins-list) with `include_platform=true`.
* Maximum of **515** contract addresses per request.
Cross-check prices on [CoinGecko](https://www.coingecko.com) and learn about the [price methodology](https://www.coingecko.com/en/methodology).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.simple.tokenPrice.getID('ethereum', {
contract_addresses: '0x2260fac5e5542a773aa44fbcfedf7c193bc2c599',
vs_currencies: 'usd',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.simple.token_price.get_id(
"ethereum",
contract_addresses="0x2260fac5e5542a773aa44fbcfedf7c193bc2c599",
vs_currencies="usd",
)
print(response)
```
# Token Data by Token Address
Source: https://docs.coingecko.com/reference/token-data-contract-address
openapi-specs/pro-api.json get /onchain/networks/{network}/tokens/{address}
To query specific token data based on the provided token contract address on a network
#### Notes
* Addresses not found in GeckoTerminal will be ignored.
* Returns the top most liquid pool per token, ranked by liquidity (`reserve_in_usd`) and 24-hour volume (`volume_usd`).
* `total_reserve_in_usd` represents the total reserve of the requested token only across all its pools, not both tokens in a pair.
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate. Verified market cap is sourced from CoinGecko and may exceed FDV if it includes tokens on other networks.
* Use `include=top_pools` to include top pools data. Add `include_composition=true` to surface balance and liquidity of base and quote tokens (requires `include=top_pools`).
* Bonding curve tokens (non-graduated launchpad tokens) include a `launchpad_details` object with graduation status.
For token metadata (socials, websites, description), use [Token Info](/reference/token-info-contract-address) instead.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.tokens.getAddress('0xdac17f958d2ee523a2206206994597c13d831ec7', {
network: 'eth',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.tokens.get_address(
"0xdac17f958d2ee523a2206206994597c13d831ec7",
network="eth",
)
print(response.model_dump_json(indent=2))
```
# Historical Token Holders Chart by Token Address
Source: https://docs.coingecko.com/reference/token-holders-chart-token-address
openapi-specs/pro-api.json get /onchain/networks/{network}/tokens/{token_address}/holders_chart
To get the historical token holders chart based on the provided token contract address on a network
#### Notes
* Historical token holders chart data is currently in **Beta**, with ongoing improvements to data quality, coverage, and update frequency.
* Auto-granularity via `days` param:
* `7` = all data (no fixed intervals)
* `30` = daily data (30 intervals)
* `max` = weekly data
| Chain | Network `id` |
| --------- | ------------- |
| Solana | `solana` |
| Ethereum | `eth` |
| Base | `base` |
| BNB Chain | `bsc` |
| Optimism | `optimism` |
| Arbitrum | `arbitrum` |
| Polygon | `polygon_pos` |
| TON | `ton` |
| Sui | `sui-network` |
| Robinhood | `robinhood` |
| Ronin | `ronin` |
| Bittensor | `bittensor` |
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.tokens.holdersChart.get('Dfh5DzRgSvvCFDoYc2ciTkMrbDfRKybA4SoFbPmApump', {
network: 'solana',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.tokens.holders_chart.get(
"Dfh5DzRgSvvCFDoYc2ciTkMrbDfRKybA4SoFbPmApump",
network="solana",
)
print(response.model_dump_json(indent=2))
```
# Token Info by Token Address
Source: https://docs.coingecko.com/reference/token-info-contract-address
openapi-specs/pro-api.json get /onchain/networks/{network}/tokens/{address}/info
To query token metadata (name, symbol, CoinGecko ID, image, socials, websites, description, etc.) based on a provided token contract address on a network
#### Notes
* Learn more about [GT Score](https://support.coingecko.com/hc/en-us/articles/38381394237593-What-is-GT-Score-How-is-GT-Score-calculated) and [GT Verified](https://support.coingecko.com/hc/en-us/articles/54413671274649-What-is-GT-Verified-Badge).
* `holders` data is currently in Beta, with ongoing improvements to coverage and update frequency.
| Chain | Network `id` |
| --------- | ------------- |
| Solana | `solana` |
| Ethereum | `eth` |
| Base | `base` |
| BNB Chain | `bsc` |
| Optimism | `optimism` |
| Arbitrum | `arbitrum` |
| Polygon | `polygon_pos` |
| TON | `ton` |
| Sui | `sui-network` |
| Robinhood | `robinhood` |
| Ronin | `ronin` |
| Bittensor | `bittensor` |
* `distribution_percentage` is based on total supply and includes all wallet types (CEX, treasury, etc.):
* Solana: `top_10`, `11_20`, `21_40`, `rest`
* Other chains: `top_10`, `11_30`, `31_50`, `rest`
* Bonding curve tokens (non-graduated launchpad tokens) include a `launchpad_details` object with graduation status.
- Metadata (image, websites, description, socials) is unvetted unless the token is [GT Verified](https://support.coingecko.com/hc/en-us/articles/54413671274649-What-is-GT-Verified-Badge) (`gt_verified: true`) or reviewed by CoinGecko.
- For CoinGecko-reviewed metadata, use [Coin Data by ID](/reference/coins-id) or [Coin Data by Token Address](/reference/coins-contract-address).
For token market data (price, supply, volume), use [Token Data](/reference/token-data-contract-address) instead.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.tokens.info.get('Dfh5DzRgSvvCFDoYc2ciTkMrbDfRKybA4SoFbPmApump', {
network: 'solana',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.tokens.info.get(
"Dfh5DzRgSvvCFDoYc2ciTkMrbDfRKybA4SoFbPmApump",
network="solana",
)
print(response.model_dump_json(indent=2))
```
# Token Lists by Asset Platform ID
Source: https://docs.coingecko.com/reference/token-lists
openapi-specs/pro-api.json get /token_lists/{asset_platform_id}/all.json
To get full list of tokens of a blockchain network (asset platform) that is supported by [Ethereum token list standard](https://tokenlists.org/)
A token is only included if its contract address has been added by the CoinGecko team. To request a missing token, [submit a request](https://support.coingecko.com/hc/en-us/requests/new).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.tokenLists.getAllJson('ethereum');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.token_lists.get_all_json("ethereum")
print(response.model_dump_json(indent=2))
```
# Token OHLCV Chart by Token Address
Source: https://docs.coingecko.com/reference/token-ohlcv-token-address
openapi-specs/pro-api.json get /onchain/networks/{network}/tokens/{token_address}/ohlcv/{timeframe}
To get the OHLCV chart (Open, High, Low, Close, Volume) of a token based on the provided token address on a network
#### Notes
* Returns OHLCV data from the **most liquid pool** of the token. Use [Top Pools by Token Address](/reference/top-pools-contract-address) to check which pool is used.
* Timestamps use epoch/unix format (e.g. `1708850449`).
* [Analyst plan and above](https://www.coingecko.com/en/api/pricing) can access data from **September 2021 to present** (depending on pool tracking start). Each call retrieves a **max 6-month range** — use `before_timestamp` for older data.
* Each `ohlcv_list` element:
```
[
timestamp,
open,
high,
low,
close,
volume
]
```
* Intervals with no swaps are skipped by default. Set `include_empty_intervals=true` to fill gaps (OHLC = previous close, volume = 0).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.tokens.ohlcv.getTimeframe('day', {
network: 'solana',
token_address: 'So11111111111111111111111111111111111111112',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.tokens.ohlcv.get_timeframe(
"day",
network="solana",
token_address="So11111111111111111111111111111111111111112",
)
print(response.model_dump_json(indent=2))
```
# Trades by Token Address
Source: https://docs.coingecko.com/reference/token-trades-contract-address
openapi-specs/pro-api.json get /onchain/networks/{network}/tokens/{token_address}/trades
To query the trades, across all pools, based on the provided token contract address on a network
#### Notes
* Paginate with `cursor` rather than a page number:
* Pass `meta.next_cursor` back unchanged as `cursor` to fetch the next page.
* `meta.next_cursor` is `null` on the last page.
* For an absolute date window instead of a relative lookback, consider [Trades within Time Range by Token Address](/reference/token-trades-contract-address-range).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.tokens.trades.get('0xdac17f958d2ee523a2206206994597c13d831ec7', {
network: 'eth',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.tokens.trades.get(
"0xdac17f958d2ee523a2206206994597c13d831ec7",
network="eth",
)
print(response.model_dump_json(indent=2))
```
# Trades within Time Range by Token Address
Source: https://docs.coingecko.com/reference/token-trades-contract-address-range
openapi-specs/pro-api.json get /onchain/networks/{network}/tokens/{token_address}/trades/range
To query the trades, across all pools, within a range of timestamp based on the provided token contract address on a network
#### Notes
* Paginate with `cursor` rather than a page number:
* Pass `meta.next_cursor` back unchanged as `cursor` to fetch the next page.
* `meta.next_cursor` is `null` on the last page.
* For a relative lookback instead of an absolute window, use [Trades by Token Address](/reference/token-trades-contract-address) with `trading_period`.
`from` and `to` are both required, and the window between them cannot exceed 30 days.
* Both ends are inclusive.
* Neither may be later than the current server time.
# Tokens Data by Token Addresses
Source: https://docs.coingecko.com/reference/tokens-data-contract-addresses
openapi-specs/pro-api.json get /onchain/networks/{network}/tokens/multi/{addresses}
To query multiple tokens data based on the provided token contract addresses on a network
#### Notes
* Addresses not found in GeckoTerminal will be ignored.
* Supports up to **50 contract addresses** per request ([Analyst plan or above](https://www.coingecko.com/en/api/pricing)).
* Returns the top most liquid pool per token, ranked by liquidity (`reserve_in_usd`) and 24-hour volume (`volume_usd`).
* `total_reserve_in_usd` represents the total reserve of the requested token only across all its pools, not both tokens in a pair.
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate. Verified market cap is sourced from CoinGecko and may exceed FDV if it includes tokens on other networks.
* Use `include=top_pools` to include top pools data. Add `include_composition=true` to surface balance and liquidity of base and quote tokens (requires `include=top_pools`).
* Bonding curve tokens (non-graduated launchpad tokens) include a `launchpad_details` object with graduation status.
For token metadata (socials, websites, description), use [Token Info](/reference/token-info-contract-address) instead.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.tokens.multi.getAddresses('6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN,2g4LS3y2myPe6vj9wTvoBE1wKqxvhnZPoZA9QU9upump', {
network: 'solana',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.tokens.multi.get_addresses(
"6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN,2g4LS3y2myPe6vj9wTvoBE1wKqxvhnZPoZA9QU9upump",
network="solana",
)
print(response.model_dump_json(indent=2))
```
# Tokens Data by Token Addresses across Networks
Source: https://docs.coingecko.com/reference/tokens-data-contract-addresses-multi
openapi-specs/pro-api.json get /onchain/tokens/multi
To query multiple tokens data based on the provided token contract addresses across multiple networks in a single request
#### Notes
* Each `tokens` entry pairs a network ID with a token contract address, separated by `:`
* For example, `eth:0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,polygon_pos:0x0d500b1d8e8ef31e21c99d1db9a6444d3adf1270`.
* Networks can be mixed freely in one request, up to **50 pairs**.
* Each token carries an `attributes.network` field, so a token address that appears on several networks stays unambiguous.
* Returns the top most liquid pool per token, ranked by liquidity (`reserve_in_usd`) and 24-hour volume (`volume_usd`).
* `total_reserve_in_usd` represents the total reserve of the requested token only across all its pools, not both tokens in a pair.
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate. Verified market cap is sourced from CoinGecko and may exceed FDV if it includes tokens on other networks.
* Use `include=top_pools` to include top pools data. Add `include_composition=true` to surface balance and liquidity of base and quote tokens (requires `include=top_pools`).
* Bonding curve tokens (non-graduated launchpad tokens) include a `launchpad_details` object with graduation status.
An unknown network ID fails the whole request, while an unknown token address does not.
* An unsupported `network_id` returns a `400` naming the offending IDs.
* A token address that cannot be resolved on a supported network is omitted from the response.
For token metadata (socials, websites, description), use [Token Info](/reference/token-info-contract-address) instead.
# Most Recently Updated Tokens List
Source: https://docs.coingecko.com/reference/tokens-info-recent-updated
openapi-specs/pro-api.json get /onchain/tokens/info_recently_updated
To query 100 most recently updated tokens info of a specific network or across all networks on GeckoTerminal
#### Notes
* Use `include=network` to include network data alongside the updated tokens list.
* Attributes specified in the `include` param will be returned under the top-level `included` key.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.tokens.infoRecentlyUpdated.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.tokens.info_recently_updated.get()
print(response.model_dump_json(indent=2))
```
# Top Pools by Token Address
Source: https://docs.coingecko.com/reference/top-pools-contract-address
openapi-specs/pro-api.json get /onchain/networks/{network}/tokens/{token_address}/pools
To query top pools based on the provided token contract address on a network
#### Notes
* Top pools are ranked by a combination of liquidity (`reserve_in_usd`) and 24-hour trading volume (`volume_usd`).
* Returns up to 20 pools per page. Pagination beyond 10 pages requires [Analyst plan or above](https://www.coingecko.com/en/api/pricing).
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate.
* Use `include` to return related attributes under the top-level `included` key.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.tokens.pools.get('0xdac17f958d2ee523a2206206994597c13d831ec7', {
network: 'eth',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.tokens.pools.get(
"0xdac17f958d2ee523a2206206994597c13d831ec7",
network="eth",
)
print(response.model_dump_json(indent=2))
```
# Top Pools by DEX
Source: https://docs.coingecko.com/reference/top-pools-dex
openapi-specs/pro-api.json get /onchain/networks/{network}/dexes/{dex}/pools
To query all the top pools based on the provided network and decentralized exchange (DEX)
#### Notes
* Returns up to 20 pools per page. Pagination beyond 10 pages requires [Analyst plan or above](https://www.coingecko.com/en/api/pricing).
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate.
* Use `include` to return related attributes under the top-level `included` key.
For more flexible pool filtering, use [Pools Megafilter](/reference/pools-megafilter).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.dexes.getPools('sushiswap', {
network: 'eth',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.dexes.get_pools(
"sushiswap",
network="eth",
)
print(response.model_dump_json(indent=2))
```
# Top Pools by Network
Source: https://docs.coingecko.com/reference/top-pools-network
openapi-specs/pro-api.json get /onchain/networks/{network}/pools
To query all the top pools based on the provided network
#### Notes
* Returns up to 20 pools per page. Pagination beyond 10 pages requires [Analyst plan or above](https://www.coingecko.com/en/api/pricing).
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate.
* Use `include` to return related attributes under the top-level `included` key.
For more flexible pool filtering, use [Pools Megafilter](/reference/pools-megafilter).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.pools.get('eth');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.pools.get("eth")
print(response.model_dump_json(indent=2))
```
# Top Token Holders by Token Address
Source: https://docs.coingecko.com/reference/top-token-holders-token-address
openapi-specs/pro-api.json get /onchain/networks/{network}/tokens/{address}/top_holders
To query top token holders based on the provided token contract address on a network
#### Notes
* Top holders data is currently in **Beta**, with ongoing improvements to data quality, coverage, and update frequency.
* Max `holders` value: 50 for non-Solana networks, 40 for Solana.
| Chain | Network `id` |
| --------- | ------------- |
| Solana | `solana` |
| Ethereum | `eth` |
| Base | `base` |
| BNB Chain | `bsc` |
| Optimism | `optimism` |
| Arbitrum | `arbitrum` |
| Polygon | `polygon_pos` |
| TON | `ton` |
| Sui | `sui-network` |
| Robinhood | `robinhood` |
| Ronin | `ronin` |
| Bittensor | `bittensor` |
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.tokens.topHolders.get('Dfh5DzRgSvvCFDoYc2ciTkMrbDfRKybA4SoFbPmApump', {
network: 'solana',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.tokens.top_holders.get(
"Dfh5DzRgSvvCFDoYc2ciTkMrbDfRKybA4SoFbPmApump",
network="solana",
)
print(response.model_dump_json(indent=2))
```
# Top Token Traders by Token Address
Source: https://docs.coingecko.com/reference/top-token-traders-token-address
openapi-specs/pro-api.json get /onchain/networks/{network_id}/tokens/{token_address}/top_traders
To query top token traders based on the provided token contract address on a network
#### Notes
* Top traders data is currently in **Beta**, with ongoing improvements to data quality, coverage, and update frequency.
* Only tokens created after 1 September 2023 are supported.
* Stablecoins and wrapped native tokens (e.g. wSOL, wETH) are not supported.
* Use the `traders` param to specify the number of top traders to retrieve (max 50).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.tokens.topTraders.get('Dfh5DzRgSvvCFDoYc2ciTkMrbDfRKybA4SoFbPmApump', {
network_id: 'solana',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.tokens.top_traders.get(
"Dfh5DzRgSvvCFDoYc2ciTkMrbDfRKybA4SoFbPmApump",
network_id="solana",
)
print(response.model_dump_json(indent=2))
```
# Trending
Source: https://docs.coingecko.com/reference/trending-overview
Trending coins, NFTs and categories by search volume on CoinGecko in the last 24 hours.
| Endpoint | Description |
| ---------------------------------------------- | --------------------------------------------------------------------- |
| [/search/trending](/reference/trending-search) | Query trending search coins, NFTs and categories in the last 24 hours |
# Trending Pools List
Source: https://docs.coingecko.com/reference/trending-pools-list
openapi-specs/pro-api.json get /onchain/networks/trending_pools
To query all the trending pools across all networks on GeckoTerminal
#### Notes
* Trending rankings are determined by:
* User engagement on GeckoTerminal
* Market activity (volume, transactions)
* Pool security (liquidity, honeypot checks)
* Returns up to 20 pools per page. Pagination beyond 10 pages requires [Analyst plan or above](https://www.coingecko.com/en/api/pricing).
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate.
* Use `include` to return related attributes under the top-level `included` key.
* Equivalent page on [GeckoTerminal](https://www.geckoterminal.com).
For more flexible pool filtering, use [Pools Megafilter](/reference/pools-megafilter).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.trendingPools.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.trending_pools.get()
print(response.model_dump_json(indent=2))
```
# Trending Pools by Network
Source: https://docs.coingecko.com/reference/trending-pools-network
openapi-specs/pro-api.json get /onchain/networks/{network}/trending_pools
To query the trending pools based on the provided network
#### Notes
* Trending rankings are determined by:
* User engagement on GeckoTerminal
* Market activity (volume, transactions)
* Pool security (liquidity, honeypot checks)
* Returns up to 20 pools per page. Pagination beyond 10 pages requires [Analyst plan or above](https://www.coingecko.com/en/api/pricing).
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate.
* Use `include` to return related attributes under the top-level `included` key.
For more flexible pool filtering, use [Pools Megafilter](/reference/pools-megafilter).
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.trendingPools.getNetwork('eth');
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.trending_pools.get_network("eth")
print(response.model_dump_json(indent=2))
```
# Trending Search List
Source: https://docs.coingecko.com/reference/trending-search
openapi-specs/pro-api.json get /search/trending
To query trending search coins, NFTs and categories on CoinGecko in the last 24 hours
#### Notes
* Default results:
* Top 15 trending coins (by most popular searches)
* Top 7 trending NFTs (by highest floor price change %)
* Top 6 trending categories (by most popular searches)
* [Analyst plan and above](https://www.coingecko.com/en/api/pricing) can use `show_max` to retrieve up to 30 coins, 10 NFTs, and 10 categories.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.search.trending.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.search.trending.get()
print(response.model_dump_json(indent=2))
```
# Trending Search Pools
Source: https://docs.coingecko.com/reference/trending-search-pools
openapi-specs/pro-api.json get /onchain/pools/trending_search
To query all the trending search pools across all networks on GeckoTerminal
#### Notes
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate.
* Use `include` to return related attributes under the top-level `included` key.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.pools.trendingSearch.get();
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.pools.trending_search.get()
print(response.model_dump_json(indent=2))
```
# Utility
Source: https://docs.coingecko.com/reference/utility-overview
BTC exchange rates, API server status, and account credit and rate limit usage.
| Endpoint | Description |
| --------------------------------------------- | ------------------------------------------------------ |
| [/exchange\_rates](/reference/exchange-rates) | Query BTC exchange rates with other currencies |
| [/ping](/reference/ping-server) | Check API server status |
| [/key](/reference/api-usage) | Monitor account API usage (rate limits, credits, etc.) |
# Token Balances by Wallet Address
Source: https://docs.coingecko.com/reference/wallet-token-balances
openapi-specs/pro-api.json get /onchain/wallets/{address}/balances
To query the token balances of a wallet address across networks
#### Notes
* `total_value_usd` and `total_holdings` are scoped to the request, not to the wallet's whole portfolio:
* Only the networks named in `networks` are counted.
* `token_type`, `value_usd_min` and `reserve_in_usd_min` filters are applied first.
* `price_usd` and `value_usd` come back `null` rather than omitted when a token has no price.
* `balance` is full precision and never rounded, but comes back `null` when the token cannot be resolved. `balance_raw` is always present, so fall back to it and convert with `decimals`: `balance_raw / 10^decimals`.
* Filtering by `token_type` returns these `balances.token_type` values:
| `token_type` param | `balances.token_type` field |
| ------------------ | --------------------------- |
| `native` | `native` |
| `non_native` | `erc20`, `spl` |
| omitted | all of the above |
| Chain | Network `id` |
| --------- | ------------- |
| Ethereum | `eth` |
| Base | `base` |
| BNB Chain | `bsc` |
| Polygon | `polygon_pos` |
| Arbitrum | `arbitrum` |
| Optimism | `optimism` |
| Avalanche | `avax` |
| Stable | `stable` |
| Robinhood | `robinhood` |
Every network in one request must belong to the same VM family, or the request returns a `400`.
* For example, `networks=eth,base,arbitrum` is valid because all three are EVM.
* Networks from different VM families must be queried in separate calls.
# Token Transfers by Wallet Address
Source: https://docs.coingecko.com/reference/wallet-token-transfers
openapi-specs/pro-api.json get /onchain/networks/{network}/wallets/{address}/transfers
To query the token transfers of a wallet address on a network
#### Notes
* `direction` is relative to the queried wallet, so the counterparty is whichever of `from_address` and `to_address` is not that wallet:
| `direction` | Queried wallet is | Transfer was |
| ----------- | ----------------- | ------------ |
| `in` | `to_address` | received |
| `out` | `from_address` | sent |
* `amount` is full precision and never rounded, but comes back `null` when the token cannot be resolved. `amount_raw` is always present, so fall back to it and convert with `decimals`: `amount_raw / 10^decimals`.
* Paginate with `cursor` rather than a page number:
* Pass `meta.next_cursor` back unchanged as `cursor` to fetch the next page.
* `meta.next_cursor` is `null` on the last page.
| Chain | Network `id` |
| --------- | ------------- |
| Ethereum | `eth` |
| Base | `base` |
| BNB Chain | `bsc` |
| Polygon | `polygon_pos` |
| Arbitrum | `arbitrum` |
| Optimism | `optimism` |
| Avalanche | `avax` |
| Stable | `stable` |
| Robinhood | `robinhood` |
`from` and `to` must be provided together, and the window between them cannot exceed 30 days.
* Omit both to get the most recent 7 days.
* Providing only one of them returns a `400`.
# cg.coin.info.updated
Source: https://docs.coingecko.com/webhooks/cg-coin-info-updated
Triggered when core coin information is updated on CoinGecko
Dispatched whenever a coin's metadata, links, categories, contract addresses, or images change on [CoinGecko.com](https://www.coingecko.com).
## Use Cases
Update your UI when a token rebrands, changes ticker, or updates its logo.
Detect when a project deploys on a new chain or migrates a contract address.
Act on critical alerts — malicious activity warnings or contract migration notices.
Notify your community when a project updates its whitepaper, GitHub repo, or social links.
## Tracked Fields
The webhook listens for changes in the following fields. Each change is reported as an `addition`, `update`, or `removal` in the payload.
| Field | Description | Example |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `id` | CoinGecko coin ID. Typically immutable — only changes to fix errors. | `bitcoin`, `usd-coin` |
| `symbol` | Ticker symbol. | `btc`, `usdc` |
| `name` | Display name. | `Bitcoin`, `USDC` |
| `web_slug` | URL slug on CoinGecko.com. Can differ from `id`. | `bitcoin`, `usdc` |
| `platforms.{asset_platform_id}` | Token contract address on a given chain. See [Asset Platforms List](/reference/asset-platforms-list). | `platforms.ethereum` → `0x1f98...` |
| `categories` | Category IDs assigned to the coin. | `meme-token`, `artificial-intelligence` |
| `public_notices` | Security breach info and contract migration announcements. | `$MATIC was upgraded 1:1 to $POL...` |
| `additional_notices.{status}` | Flags like `can_mint_new_tokens` or `has_unverified_contract`. | `true`, `false`, or `null` |
| `links.{site}` | Official websites and social media links. | `links.homepage`, `links.whitepaper`, `links.twitter_screen_name` |
| `image` | Image filename (not URL). Use [/coins/\{id}](/reference/coins-id) or [/coins/markets](/reference/coins-markets) to get full URLs. | `uniswap-logo.png` |
When `platforms.{asset_platform_id}` changes its key (e.g. `xdai` → `ethereum`), two changes are sent: a `removal` of the old key and an `addition` of the new key.
For `links.homepage`, `links.official_forum_url`, `links.chat_url`, and `links.announcement_url` — only `update` events are triggered.
* The payload contains the full array of links.
* A removed link returns an empty value.
## Payload
Each payload contains the event type, coin identity, and an array of `changes` describing exactly what was modified.
| Field | Description |
| ---------------------------- | ----------------------------------- |
| `event_type` | `cg.coin.info.updated` |
| `data.id` | CoinGecko coin ID |
| `data.symbol` | Coin symbol |
| `data.name` | Coin name |
| `data.changes` | Array of change objects |
| `data.changes[].field` | Field that changed |
| `data.changes[].change_type` | `addition`, `update`, or `removal` |
| `data.changes[].new_value` | Updated value. `null` if removal. |
| `data.changes[].old_value` | Previous value. `null` if addition. |
### Example
```json expandable theme={null}
{
"event_type": "cg.coin.info.updated",
"data": {
"id": "bitcoin",
"symbol": "btc",
"name": "Bitcoin",
"changes": [
{
"field": "categories",
"change_type": "addition",
"old_value": null,
"new_value": "Store of Value"
},
{
"field": "links.facebook_username",
"change_type": "update",
"old_value": "bitcoins",
"new_value": "bitcoin"
},
{
"field": "platforms.ethereum",
"change_type": "removal",
"old_value": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
"new_value": null
}
]
}
}
```
# cg.coin.listed
Source: https://docs.coingecko.com/webhooks/cg-coin-listed
Triggered when a new token is indexed and listed on CoinGecko
**Early Access (Private Beta)**
`cg.coin.listed` is currently in private preview with a limited number of developers.
Be the first to test low-latency new listing feeds.
## Use Cases
Detect newly listed tokens and execute early positions the moment they go live on CoinGecko.
Keep your asset directories and trading terminals up to date without polling [/coins/list](/reference/coins-list).
Cross-reference new listings against X, Telegram, or Reddit to catch viral momentum early.
Automatically recognize new assets in your multi-chain wallet or custody platform.
![]()
# cg.coin.price.updated
Source: https://docs.coingecko.com/webhooks/cg-coin-price-updated
Triggered when a coin crosses a pre-configured price target or exhibits high volatility
**Early Access (Private Beta)**
`cg.coin.price.updated` is currently in private preview with a limited number of developers.
Secure your spot for real-time price threshold events.
## Use Cases
Send real-time notifications via Discord, Telegram, or email when an asset hits a target price.
Trigger AI agents or automation tools (Zapier, IFTTT) for sentiment analysis or event logging when price barriers are broken.
Automatically execute buy, sell, or rebalancing actions when an asset's weight crosses target boundaries.
Monitor collateral bounds for DeFi lending protocols — trigger liquidation checks when prices cross safety thresholds.
![]()
# Webhooks
Source: https://docs.coingecko.com/webhooks/index
Get notified instantly when events happen on CoinGecko — no polling required
## Why Use Webhooks?
Keep your application synchronized with CoinGecko in real-time — no cron jobs or polling required. Listen to events like `cg.coin.info.updated` and react instantly to changes.
Update your UI when a token rebrands, changes ticker, or updates its logo.
Detect when a project deploys on a new chain or migrates a contract address.
Act immediately on critical alerts — malicious activity warnings or contract migration notices.
CoinGecko Webhooks (Beta) is available for [paid plan](https://www.coingecko.com/en/api/pricing) customers (Basic plan & above).
* Credit charge: **10** credits per event delivery. Retry attempts are **not charged**.
* Maximum webhook endpoints: **1** on Basic plan, **5** on Analyst plan & above.
* **Enterprise** clients who need higher limits — contact your Customer Success Manager.
CoinGecko Webhooks is a supplementary delivery mechanism for real-time notifications. Currently in beta — excluded from the SLA applicable to the CoinGecko API Platform.
Help us improve Webhooks — share your suggestions and use cases.
## Getting Started
Go to the [Developer Dashboard](https://www.coingecko.com/en/developers/dashboard#webhook) and create a new webhook endpoint.
![]()
Use the Signing Secret to verify incoming payloads on your server.
![]()
Your server will receive POST requests whenever relevant coin data changes on [CoinGecko.com](https://www.coingecko.com).
For team accounts, non-owner users invited to a shared dashboard have full access to view, edit, and delete webhooks.
## Event Types
| Event Type | Description |
| -------------------------------------------------------- | ----------------------------------------------------------------- |
| [cg.coin.info.updated](/webhooks/cg-coin-info-updated) | Core coin information updated (metadata, links, categories, etc.) |
| [cg.coin.price.updated](/webhooks/cg-coin-price-updated) | Coin crosses a user-defined price target |
| [cg.coin.listed](/webhooks/cg-coin-listed) | New token indexed and listed on CoinGecko |
| More coming soon! | [Share your suggestions](https://tally.so/r/2EgG4p) |
## HTTP Headers
Every webhook POST request includes these headers:
| Header | Description |
| ---------------- | ---------------------------------------------------------------- |
| `Content-Type` | `application/json` |
| `x-cg-timestamp` | UNIX timestamp of the event. Useful for replay attack prevention |
| `x-cg-signature` | HMAC SHA256 signature to verify authenticity |
| `x-cg-event-id` | Unique identifier for the event |
## Signature Verification
Verify that incoming payloads are genuinely from CoinGecko by computing an HMAC SHA256 hash and comparing it to the `x-cg-signature` header.
**Signing string format:** `{timestamp}:{event_id}:{json_body}`
The `{json_body}` must be the **raw, unparsed request body** — not a re-stringified JSON object.
If your framework auto-parses JSON before verification, the signature will fail.
### Example Code
> Replace `YOUR_SIGNING_SECRET` with the `whsec_...` value from your [Developer Dashboard](https://www.coingecko.com/en/developers/dashboard#webhook).
```js Node.js (Express) expandable theme={null}
const { createHmac } = require('crypto');
const express = require('express');
const app = express();
const SIGNING_SECRET = 'YOUR_SIGNING_SECRET';
function verifySignature(body, headers, secret) {
if (!secret) return null;
const timestamp = headers["x-cg-timestamp"];
const eventId = headers["x-cg-event-id"];
const signature = headers["x-cg-signature"];
if (!timestamp || !eventId || !signature) return null;
const signingString = `${timestamp}:${eventId}:${body}`;
const expected = createHmac("sha256", secret).update(signingString).digest("hex");
return expected === signature;
}
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const rawBodyString = req.body.toString('utf8');
const isValid = verifySignature(rawBodyString, req.headers, SIGNING_SECRET);
if (isValid === null) {
return res.status(400).send('Missing required CoinGecko headers');
}
if (isValid) {
const event = JSON.parse(rawBodyString);
// Process the event...
return res.status(200).send('Webhook received successfully');
} else {
return res.status(401).send('Invalid signature');
}
});
app.listen(3000, () => console.log('Server listening on port 3000'));
```
```python Python (Flask) expandable theme={null}
import hmac
import hashlib
from flask import Flask, request
app = Flask(__name__)
SIGNING_SECRET = 'YOUR_SIGNING_SECRET'
def verify_signature(body_str, headers, secret):
if not secret:
return None
timestamp = headers.get('x-cg-timestamp')
event_id = headers.get('x-cg-event-id')
signature = headers.get('x-cg-signature')
if not timestamp or not event_id or not signature:
return None
signing_string = f"{timestamp}:{event_id}:{body_str}"
expected = hmac.new(
secret.encode('utf-8'),
signing_string.encode('utf-8'),
hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature)
@app.route('/webhook', methods=['POST'])
def webhook_handler():
raw_body_string = request.get_data(as_text=True)
is_valid = verify_signature(raw_body_string, request.headers, SIGNING_SECRET)
if is_valid is None:
return "Missing required CoinGecko headers", 400
if is_valid:
event = request.get_json()
# Process the event...
return "Webhook received successfully", 200
else:
return "Invalid signature", 401
if __name__ == '__main__':
app.run(port=3000)
```
Treat your Signing Secret like a password — never commit it to public repos or expose it in client-side code.
## Managing Webhooks
Navigate to your **Webhook Details** page in the [Developer Dashboard](https://www.coingecko.com/en/developers/dashboard#webhook):
* **Send Test Event** — dispatches a mock `cg.coin.info.updated` payload. Use it to verify your server receives the request and responds with `2xx` before going live.
* **Delivery Logs** — view the latest 100 delivery attempts. Use these to identify if your endpoint is rejecting requests.
## Billing & Credits
* **10 credits** per event delivery. Retries are **not charged**.
* If you run out of credits with Hardcap enabled (Overage disabled):
* Delivery stops immediately and all webhooks are auto-disabled.
* You'll receive an email notification that delivery has stopped.
* You must **manually re-activate** webhooks in the [Developer Dashboard](https://www.coingecko.com/en/developers/dashboard#webhook) after credits are replenished.
### Estimated Usage
Each delivered webhook event consumes **10 credits**. The `cg.coin.info.updated` event listens to all active coins on CoinGecko — volume fluctuates based on market activity and how frequently projects update their metadata.
* **Expected volume:** up to **200 updates/day** based on historical data.
* **Estimated monthly cost:** \~6,000 events/month = **\~60,000 credits**.
* **Plan fit:** comfortably within the [Analyst plan](https://www.coingecko.com/en/api/pricing) and above.
These are approximations. Extreme market volatility or mass migrations could temporarily increase daily volume.
### 24-Hour Baseline Test
If you're concerned about unpredictable credit usage, run a short test before committing:
1. **Enable Hardcap** — turn OFF "Overage" in the Developer Dashboard to avoid unexpected charges.
2. **Run for 24–48 hours** — activate your webhook and let it collect events.
3. **Check consumption** — review credit usage in the dashboard to establish a reliable baseline.
## Retries & Failed Attempts
If your server fails to respond with a `2xx` status code, CoinGecko will retry with exponential backoff. **Retry attempts are not charged.**
A webhook is automatically disabled under either condition:
| Condition | Threshold |
| --------------------- | -------------------------------------- |
| Single event backoff | **14 failed retries** over \~24 hours |
| Aggregate failure cap | **300 failed retries** across 12 hours |
When a webhook is disabled, you'll receive an email notification. To resume:
1. Check your server logs and resolve the issue.
2. Log in to the [Developer Dashboard](https://www.coingecko.com/en/developers/dashboard#webhook).
3. Manually toggle the webhook back to **Active**.
![Pay for your CoinGecko API subscription with crypto]()
# CGSimplePrice
Source: https://docs.coingecko.com/websocket/cgsimpleprice
Real-time coin price updates by CoinGecko coin IDs
### Notes
* Streams real-time prices for one or more coins by their unique Coin API IDs.
* Specify preferred quote currencies via `vs_currencies` in the subscription data. See [Supported Currencies](/reference/simple-supported-currencies) for valid values. Defaults to USD.
* Find a coin's API ID on its [CoinGecko](https://www.coingecko.com) page, via [Coins List](/reference/coins-list), or this [Google Sheet](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).
* Fields may return `null` when data is unavailable. Ensure your application handles null values.
Update Frequency:
As fast as \~10 seconds for large-cap and actively traded coins.
### Data Payload
| Key | Field | Type | Description | Example |
| ------- | ----------------------------- | ------- | ------------------------------------------------------- | ---------------- |
| `c` | `channel_type` | string | Channel type subscribed to. | `C1` |
| `i` | `coin_id` | string | Coin identifier. | `bitcoin` |
| `vs` | `vs_currency` | string | Target quote currency. | `usd` |
| `p` | `price` | number | Current price in the specified `vs_currency`. | 61696.68 |
| `pp` | `price_24h_change_percentage` | number | Price change percentage over the last 24 hours. | 1.42 |
| `pp7d` | `price_7d_change_percentage` | number | Price change percentage over the last 7 days. | 3.8214 |
| `pp30d` | `price_30d_change_percentage` | number | Price change percentage over the last 30 days. | -2.1543 |
| `pp60d` | `price_60d_change_percentage` | number | Price change percentage over the last 60 days. | 12.4512 |
| `pp1y` | `price_1y_change_percentage` | number | Price change percentage over the last 1 year. | 120.8541 |
| `m` | `market_cap` | number | Market capitalization in the specified `vs_currency`. | 1236047139289.68 |
| `cs` | `circulating_supply` | number | Circulating supply of coin. | 19734150 |
| `fdv` | `fully_diluted_value` | number | Fully diluted valuation in the specified `vs_currency`. | 1312500000000 |
| `v` | `24h_vol` | number | 24-hour trading volume in the specified `vs_currency`. | 30595921115.54 |
| `t` | `last_updated_at` | integer | UNIX timestamp in seconds. | 1780839768 |
***
### 1. Establish Connection
```bash theme={null}
wss://stream.coingecko.com/v1?x_cg_pro_api_key=YOUR_KEY
```
You can also pass the key as a header: `x-cg-pro-api-key: YOUR_KEY`
**Output:**
```json theme={null}
{
"code": 3000,
"message": "Connection established",
"uuid": "YOUR_SESSION_ID"
}
```
```json theme={null}
{
"type": "welcome",
"sid": "YOUR_SESSION_ID"
}
```
***
### 2. Subscribe to CGSimplePrice
**Input:**
```json wrap theme={null}
{"command":"subscribe","identifier":"{\"channel\":\"CGSimplePrice\"}"}
```
**Output:**
```json theme={null}
{
"type": "confirm_subscription",
"identifier": "{\"channel\":\"CGSimplePrice\"}"
}
```
***
### 3. Stream Price Data
**Input:**
```json wrap theme={null}
{"command":"message","identifier":"{\"channel\":\"CGSimplePrice\"}","data":"{\"coin_id\":[\"bitcoin\"],\"vs_currencies\":[\"usd\"],\"action\":\"set_tokens\"}"}
```
**Output:**
```json theme={null}
{
"code": 2000,
"message": "Subscribed to bitcoin in usd"
}
```
**Streaming output:**
```json theme={null}
{
"c": "C1",
"i": "bitcoin",
"vs": "usd",
"p": 61696.67928656691,
"pp": 1.4192404041947198,
"pp7d": 3.8214,
"pp30d": -2.1543,
"pp60d": 12.4512,
"pp1y": 120.8541,
"m": 1236047139289.684,
"cs": 19734150,
"fdv": 1312500000000,
"v": 30595921115.53988,
"t": 1780839768
}
```
Output keys may appear in any order.
***
### 4. Unsubscribe
**Unsubscribe from a specific token:**
```json wrap theme={null}
{"command":"message","identifier":"{\"channel\":\"CGSimplePrice\"}","data":"{\"coin_id\":[\"bitcoin\"],\"action\":\"unset_tokens\"}"}
```
```json theme={null}
{
"code": 2000,
"message": "Unsubscription is successful for bitcoin"
}
```
**Unsubscribe from the channel entirely:**
```json wrap theme={null}
{"command":"unsubscribe","identifier":"{\"channel\":\"CGSimplePrice\"}"}
```
```json theme={null}
{
"code": 2000,
"message": "Unsubscription is successful for all tokens"
}
```
***
# WebSocket
Source: https://docs.coingecko.com/websocket/index
Stream real-time crypto data with CoinGecko WebSockets
## Stream Real-Time Crypto Data with CoinGecko WebSockets
CoinGecko WebSocket API provides a persistent connection for real-time data streaming — receive market updates the moment they happen, without polling.
CoinGecko WebSocket is available for [paid plan](https://www.coingecko.com/en/api/pricing) customers (Basic plan & above).
* Basic, Analyst, Lite, Pro, and Pro+ self-serve plans include:
* Max connections: 5 concurrent socket connections on **Basic plan**, 10 on **Analyst plan & above**
* Max subscriptions: 100 token or pool data subscriptions per channel, per socket
* Channel access: all 4 channels
* Credit charge: 0.1 credit per response returned, deducting from monthly API plan credits
* **Enterprise plan** clients who want higher limits (max connections, max subscriptions, lower credit charge) — contact your Customer Success Manager.
CoinGecko WebSocket is a supplementary delivery mechanism for live data streaming. Currently in beta — excluded from the SLA applicable to the CoinGecko API Platform.
Help us improve WebSocket — share your suggestions and feedback.
### Channel & Data Support
| WebSocket Channel | Channel Code | Details |
| ------------------------------------------------------------- | ------------ | ------------------------------------------------------------ |
| [CGSimplePrice](/websocket/cgsimpleprice) | C1 | Real-time coin prices, as seen on CoinGecko.com |
| [OnchainSimpleTokenPrice](/websocket/onchainsimpletokenprice) | G1 | Real-time token prices, as seen on GeckoTerminal.com |
| [OnchainTrade](/websocket/onchaintrade) | G2 | Real-time pool transactions, as seen on GeckoTerminal.com |
| [OnchainOHLCV](/websocket/onchainohlcv) | G3 | Real-time OHLCV data for pools, as seen on GeckoTerminal.com |
| (More coming soon!) | | |
### Connection Handling
1. **Ping/Pong Mechanism:**
* Server sends a ping every 10 seconds.
* If no pong is received within 20 seconds, the connection is automatically closed.
* Ensure your WebSocket client responds to pings with pongs — most libraries handle this automatically, but verify your implementation.
2. **Planned Disconnections (Deployments & Reboots):**
* System reboots or deployments may temporarily disconnect active connections.
* Your application should automatically reconnect on disconnection. Use exponential backoff to avoid overwhelming the server during widespread disconnections.
Subscribe to a Basic plan or above to start streaming real-time data.
![Pay for your CoinGecko API subscription with crypto]()
# OnchainOHLCV
Source: https://docs.coingecko.com/websocket/onchainohlcv
Real-time onchain OHLCV candlestick updates by pool address
### Notes
* Streams real-time OHLCV (Open, High, Low, Close, Volume) candlestick data by network and pool address.
* Lookup format: `network_id:pool_address` (e.g. `bsc:0x172fcd41e0913e95784454622d1c3724f546f849`).
* Interval options: `1s` / `1m` / `5m` / `15m` / `1h` / `2h` / `4h` / `8h` / `12h` / `1d`.
* Stream based on `base` or `quote` token of a pool.
* Find supported network IDs via [Networks List](/reference/networks-list).
* Use [Top Pools by Token Address](/reference/top-pools-contract-address) to find the most liquid pool address.
* Fields may return `null` when data is unavailable. Ensure your application handles null values.
Each unique combination of interval and token for a given pool counts as a distinct subscription towards your max subscription limit.
Update Frequency:
As fast as \~1 second for actively traded pools.
### Data Payload
| Key | Field | Type | Description | Example |
| ---- | -------------- | ------- | ------------------------------------- | -------------------------------------------- |
| `ch` | `channel_type` | string | Channel type subscribed to. | `G3` |
| `n` | `network_id` | string | Blockchain network identifier. | `bsc` |
| `pa` | `pool_address` | string | Pool contract address. | `0x172fcd41e0913e95784454622d1c3724f546f849` |
| `to` | `token` | string | Token side (`base` or `quote`). | `base` |
| `i` | `interval` | string | Candle interval. | `1m` |
| `o` | `open` | number | Open price in USD. | 1.0005 |
| `h` | `high` | number | High price in USD. | 1.0006 |
| `l` | `low` | number | Low price in USD. | 0.9999 |
| `c` | `close` | number | Close price in USD. | 0.9999 |
| `v` | `volume` | number | Volume in USD. | 59672.13 |
| `t` | `timestamp` | integer | Candle open time, UNIX timestamp (s). | 1780841100 |
***
### 1. Establish Connection
```bash theme={null}
wss://stream.coingecko.com/v1?x_cg_pro_api_key=YOUR_KEY
```
You can also pass the key as a header: `x-cg-pro-api-key: YOUR_KEY`
**Output:**
```json theme={null}
{
"code": 3000,
"message": "Connection established",
"uuid": "YOUR_SESSION_ID"
}
```
```json theme={null}
{
"type": "welcome",
"sid": "YOUR_SESSION_ID"
}
```
***
### 2. Subscribe to OnchainOHLCV
**Input:**
```json wrap theme={null}
{"command":"subscribe","identifier":"{\"channel\":\"OnchainOHLCV\"}"}
```
**Output:**
```json theme={null}
{
"type": "confirm_subscription",
"identifier": "{\"channel\":\"OnchainOHLCV\"}"
}
```
***
### 3. Stream OHLCV Data
**Input:**
```json wrap theme={null}
{"command":"message","identifier":"{\"channel\":\"OnchainOHLCV\"}","data":"{\"network_id:pool_addresses\":[\"bsc:0x172fcd41e0913e95784454622d1c3724f546f849\"],\"interval\":\"1m\",\"token\":\"base\",\"action\":\"set_pools\"}"}
```
**Output:**
```json theme={null}
{
"code": 2000,
"message": "Subscription successful for bsc:0x172fcd41e0913e95784454622d1c3724f546f849:1m:base"
}
```
**Streaming output:**
```json theme={null}
{
"ch": "G3",
"n": "bsc",
"pa": "0x172fcd41e0913e95784454622d1c3724f546f849",
"to": "base",
"i": "1m",
"o": 1.00052534269941,
"h": 1.00063525778742,
"l": 0.999952061655863,
"c": 0.999952061655863,
"v": 59672.13452671968,
"t": 1780841100
}
```
Output keys may appear in any order.
***
### 4. Unsubscribe
**Unsubscribe from a specific pool:**
```json wrap theme={null}
{"command":"message","identifier":"{\"channel\":\"OnchainOHLCV\"}","data":"{\"network_id:pool_addresses\":[\"bsc:0x172fcd41e0913e95784454622d1c3724f546f849\"],\"interval\":\"1m\",\"token\":\"base\",\"action\":\"unset_pools\"}"}
```
```json theme={null}
{
"code": 2000,
"message": "Unsubscription is successful for bsc:0x172fcd41e0913e95784454622d1c3724f546f849:1m:base"
}
```
**Unsubscribe from the channel entirely:**
```json wrap theme={null}
{"command":"unsubscribe","identifier":"{\"channel\":\"OnchainOHLCV\"}"}
```
```json theme={null}
{
"code": 2000,
"message": "Unsubscription is successful for all pools"
}
```
***
# OnchainSimpleTokenPrice
Source: https://docs.coingecko.com/websocket/onchainsimpletokenprice
Real-time onchain token price updates by network and token address
### Notes
* Streams real-time price and market data for tokens by network and token address.
* Returns data from the top pool of the specified token.
* Lookup format: `network_id:token_address` (e.g. `bsc:0x55d398326f99059ff775485246999027b3197955`).
* Find supported network IDs via [Networks List](/reference/networks-list).
* Fields may return `null` when data is unavailable. Ensure your application handles null values.
Update Frequency:
As fast as \~1 second for actively traded tokens.
### Data Payload
| Key | Field | Type | Description | Example |
| ---- | --------------------------------- | ------- | ------------------------------ | -------------------------------------------- |
| `c` | `channel_type` | string | Channel type subscribed to. | `G1` |
| `n` | `network_id` | string | Blockchain network identifier. | `bsc` |
| `ta` | `token_address` | string | Token contract address. | `0x55d398326f99059ff775485246999027b3197955` |
| `p` | `usd_price` | number | Current token price in USD. | 1.0002630480973 |
| `pp` | `usd_price_24h_change_percentage` | number | Price change percentage (24h). | 0.05 |
| `m` | `usd_market_cap` | number | Market capitalization in USD. | 9187408426.01 |
| `v` | `usd_24h_vol` | number | 24-hour trading volume in USD. | 1999727791.12 |
| `t` | `last_updated_at` | integer | UNIX timestamp in seconds. | 1780840630 |
***
### 1. Establish Connection
```bash theme={null}
wss://stream.coingecko.com/v1?x_cg_pro_api_key=YOUR_KEY
```
You can also pass the key as a header: `x-cg-pro-api-key: YOUR_KEY`
**Output:**
```json theme={null}
{
"code": 3000,
"message": "Connection established",
"uuid": "YOUR_SESSION_ID"
}
```
```json theme={null}
{
"type": "welcome",
"sid": "YOUR_SESSION_ID"
}
```
***
### 2. Subscribe to OnchainSimpleTokenPrice
**Input:**
```json wrap theme={null}
{"command":"subscribe","identifier":"{\"channel\":\"OnchainSimpleTokenPrice\"}"}
```
**Output:**
```json theme={null}
{
"type": "confirm_subscription",
"identifier": "{\"channel\":\"OnchainSimpleTokenPrice\"}"
}
```
***
### 3. Stream Token Price Data
**Input:**
```json wrap theme={null}
{"command":"message","identifier":"{\"channel\":\"OnchainSimpleTokenPrice\"}","data":"{\"network_id:token_addresses\":[\"bsc:0x55d398326f99059ff775485246999027b3197955\"],\"action\":\"set_tokens\"}"}
```
**Output:**
```json theme={null}
{
"code": 2000,
"message": "Subscription successful for bsc:0x55d398326f99059ff775485246999027b3197955"
}
```
**Streaming output:**
```json theme={null}
{
"c": "G1",
"n": "bsc",
"ta": "0x55d398326f99059ff775485246999027b3197955",
"p": 1.0002630480973,
"pp": 0.04574653488,
"m": 9187408426.010283,
"v": 1999727791.12026,
"t": 1780840630
}
```
Output keys may appear in any order.
***
### 4. Unsubscribe
**Unsubscribe from a specific token:**
```json wrap theme={null}
{"command":"message","identifier":"{\"channel\":\"OnchainSimpleTokenPrice\"}","data":"{\"network_id:token_addresses\":[\"bsc:0x55d398326f99059ff775485246999027b3197955\"],\"action\":\"unset_tokens\"}"}
```
```json theme={null}
{
"code": 2000,
"message": "Unsubscription is successful for bsc:0x55d398326f99059ff775485246999027b3197955"
}
```
**Unsubscribe from the channel entirely:**
```json wrap theme={null}
{"command":"unsubscribe","identifier":"{\"channel\":\"OnchainSimpleTokenPrice\"}"}
```
```json theme={null}
{
"code": 2000,
"message": "Unsubscription is successful for all tokens"
}
```
***
# OnchainTrade
Source: https://docs.coingecko.com/websocket/onchaintrade
Real-time onchain DEX trade updates by pool address
### Notes
* Streams real-time trade/swap updates for pools by network and pool address.
* Returns transaction type (buy/sell), tx hash, token amounts, volume, and price data.
* Lookup format: `network_id:pool_address` (e.g. `bsc:0x172fcd41e0913e95784454622d1c3724f546f849`).
* Find supported network IDs via [Networks List](/reference/networks-list).
* Use [Top Pools by Token Address](/reference/top-pools-contract-address) to find the most liquid pool address.
* Fields may return `null` when data is unavailable. Ensure your application handles null values.
Update Frequency:
As fast as \~0.1 seconds for actively traded pools.
### Data Payload
| Key | Field | Type | Description | Example |
| ----- | -------------------------- | ------- | --------------------------------------- | -------------------------------------------- |
| `c` | `channel_type` | string | Channel type subscribed to. | `G2` |
| `n` | `network_id` | string | Blockchain network identifier. | `bsc` |
| `pa` | `pool_address` | string | Pool contract address. | `0x172fcd41e0913e95784454622d1c3724f546f849` |
| `tx` | `tx_hash` | string | Transaction hash. | `0x743b271e...5adf698` |
| `ty` | `type` | string | Trade type (`b` = buy, `s` = sell). | `b` |
| `to` | `token_amount` | number | Base token amount. | 0.037 |
| `toq` | `quote_token_amount` | number | Quote token amount. | 0.0000626 |
| `vo` | `volume_in_usd` | number | Trade volume in USD. | 0.037 |
| `pc` | `price_in_native_currency` | number | Token price in network native currency. | 0.0017 |
| `pu` | `price_in_usd` | number | Token price in USD. | 0.999 |
| `t` | `last_updated_at` | integer | UNIX timestamp in milliseconds. | 1780840929000 |
***
### 1. Establish Connection
```bash theme={null}
wss://stream.coingecko.com/v1?x_cg_pro_api_key=YOUR_KEY
```
You can also pass the key as a header: `x-cg-pro-api-key: YOUR_KEY`
**Output:**
```json theme={null}
{
"code": 3000,
"message": "Connection established",
"uuid": "YOUR_SESSION_ID"
}
```
```json theme={null}
{
"type": "welcome",
"sid": "YOUR_SESSION_ID"
}
```
***
### 2. Subscribe to OnchainTrade
**Input:**
```json wrap theme={null}
{"command":"subscribe","identifier":"{\"channel\":\"OnchainTrade\"}"}
```
**Output:**
```json theme={null}
{
"type": "confirm_subscription",
"identifier": "{\"channel\":\"OnchainTrade\"}"
}
```
***
### 3. Stream Trade Data
**Input:**
```json wrap theme={null}
{"command":"message","identifier":"{\"channel\":\"OnchainTrade\"}","data":"{\"network_id:pool_addresses\":[\"bsc:0x172fcd41e0913e95784454622d1c3724f546f849\"],\"action\":\"set_pools\"}"}
```
**Output:**
```json theme={null}
{
"code": 2000,
"message": "Subscription successful for bsc:0x172fcd41e0913e95784454622d1c3724f546f849"
}
```
**Streaming output:**
```json theme={null}
{
"c": "G2",
"n": "bsc",
"pa": "0x172fcd41e0913e95784454622d1c3724f546f849",
"tx": "0x3aa702e87ebc87cc4f877ab494afa0ac59f46873c147ee406a546c1e12ab5f57",
"ty": "s",
"to": 0.0369078635593666,
"toq": 0.000062600168318069,
"vo": 0.036858979105679,
"pc": 0.0016961200752619,
"pu": 0.998675500314209,
"t": 1780840929000
}
```
Output keys may appear in any order.
***
### 4. Unsubscribe
**Unsubscribe from a specific pool:**
```json wrap theme={null}
{"command":"message","identifier":"{\"channel\":\"OnchainTrade\"}","data":"{\"network_id:pool_addresses\":[\"bsc:0x172fcd41e0913e95784454622d1c3724f546f849\"],\"action\":\"unset_pools\"}"}
```
```json theme={null}
{
"code": 2000,
"message": "Unsubscription is successful for bsc:0x172fcd41e0913e95784454622d1c3724f546f849"
}
```
**Unsubscribe from the channel entirely:**
```json wrap theme={null}
{"command":"unsubscribe","identifier":"{\"channel\":\"OnchainTrade\"}"}
```
```json theme={null}
{
"code": 2000,
"message": "Unsubscription is successful for all pools"
}
```
***