# CoinGecko Scraper — Crypto Prices, Market Cap, Volume, Trending (`yadroo/coingecko-markets`) Actor

Crypto market data from CoinGecko for AI agents: top-coin screener with filters and sort, simple prices in 63 currencies, coin profiles, token lookup by contract address, trending, global stats, categories, exchanges, daily history and OHLC candles. No API key.

- **URL**: https://apify.com/yadroo/coingecko-markets.md
- **Developed by:** [Samat Makatov](https://apify.com/yadroo) (community)
- **Categories:** Developer tools, AI, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.70 / 1,000 result items

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## CoinGecko Scraper — Crypto Prices, Market Cap, Volume, Trending, History & OHLC

Live crypto market data from CoinGecko's public API in eleven modes: top-coin screens with filters, simple prices, full coin profiles, token lookup by contract address, trending coins, global market stats, sector (category) rankings, exchanges, daily history, OHLC candles and id search. Built for trading bots, research agents, portfolio dashboards and alerting. No API key, proxy or browser needed (an optional free Demo key raises the rate limit).

### Use cases

- **Momentum / pump screener** — `markets` with `minChange24h: 15`, `minVolume24h: 1000000`, `maxRank: 500` → coins breaking out today.
- **Portfolio valuation** — `price` for your holdings in `eur`/`gbp`/`btc` every hour.
- **Token due diligence** — `contract` on `base` with a token address → name, market cap, FDV, categories, links, exchange listings.
- **Sector rotation** — `categories` ordered by `market_cap_change_24h_desc` → which sectors are hot today.
- **Backtests & charts** — `history` (daily price, market cap, volume) or `ohlc` candles per coin.
- **Exchange risk** — `exchanges` with trust score and `volumeAnomalyRatio` (reported vs normalized volume).

### Input

| Field | Type | Default | Notes |
|---|---|---|---|
| `mode` | string | `markets` | `markets`, `price`, `coins`, `contract`, `trending`, `global`, `categories`, `exchanges`, `history`, `ohlc`, `search` |
| `ids` | array | `[]` | CoinGecko ids (slug in `coingecko.com/en/coins/<id>`), e.g. `bitcoin`, `aerodrome-finance`. Required for `price`, `coins`, `history`, `ohlc`. Unknown ids are reported as warnings. |
| `symbols` | array | `[]` | markets: tickers (`btc`, `eth`) instead of ids. |
| `vsCurrency` | string | `usd` | One of 63 CoinGecko quote currencies (see Reference). Unsupported ones (e.g. `kzt`) fail with the full list. |
| `limit` | integer 1–1000 | `50` | Max rows (markets, coins, contract, trending, categories, exchanges, search). |
| `fields` | array | `[]` | Keep only these output fields. |
| `category` | string | — | markets: category id (`layer-2`, `meme-token`, `artificial-intelligence`, `base-ecosystem`…). Unknown ids fail with suggestions. |
| `order` | string | `market_cap_desc` | markets server order: `market_cap_desc/asc`, `volume_desc/asc`, `id_asc/desc`. |
| `priceChangeWindows` | array | `["1h","24h","7d"]` | Any of `1h, 24h, 7d, 14d, 30d, 200d, 1y`; others stay null. |
| `includeSparkline` | boolean | `false` | Add `sparkline7d` (hourly prices). |
| `minMarketCap` / `maxMarketCap` | integer | — | In `vsCurrency`. `minMarketCap` also filters categories. |
| `minVolume24h` | integer | — | |
| `maxRank` | integer | — | Keep ranks 1..N. |
| `minChange24h` / `maxChange24h` / `minChange7d` / `maxChange7d` | integer | — | % bounds. |
| `minVolumeToMcap` | string (decimal) | — | Turnover, e.g. `0.2`. |
| `search` | string | — | Substring on name/symbol/id (markets, categories, exchanges). |
| `sortBy` / `sortDir` | string | — / `desc` | Client-side sort: `rank, price, marketCap, fdv, volume24h, change1h…change1y, volumeToMcap, athChangePct`. |
| `includeDescription` / `includeTickers` / `includeCommunity` / `includeDeveloper` | boolean | `true` / `false` / `false` / `false` | coins & contract detail options. |
| `platform` / `contractAddresses` | string / array | — | contract: asset platform id + token addresses. |
| `includeNfts` / `includeCategories` | boolean | `false` | trending extras. |
| `categoryOrder` | string | `market_cap_desc` | categories: `market_cap_desc/asc`, `name_desc/asc`, `market_cap_change_24h_desc/asc`. |
| `query` | string | — | search: name or symbol. |
| `days` | integer | 30 (history) / 7 (ohlc) | history: 1–365; ohlc: 1, 7, 14, 30, 90, 180, 365 (others round up with a warning). |
| `from` / `to` | date | — | history window (YYYY-MM-DD), last 365 days on the public API. |
| `dailyOnly` | boolean | `true` | history: one point per UTC day. |
| `coingeckoApiKey` / `apiPlan` | string / string | — / `demo` | Optional key; `pro` switches to the Pro host. |

Legacy inputs (`mode` with `markets/coins/trending/price`, `ids`, `vsCurrency`, `limit`, `category`) keep their names and meaning.

### Reference

**Quote currencies (`vsCurrency`, 63):** usd, eur, gbp, jpy, cny, krw, inr, rub, try, brl, cad, aud, chf, aed, ars, bdt, bhd, bmd, clp, czk, dkk, gel, hkd, huf, idr, ils, kwd, lkr, mmk, mxn, myr, ngn, nok, nzd, php, pkr, pln, sar, sek, sgd, thb, twd, uah, vef, vnd, zar, xdr, xag (silver), xau (gold), btc, eth, ltc, bch, bnb, eos, xrp, xlm, link, dot, yfi, sol, bits, sats.

**Popular category ids:** `layer-1`, `layer-2`, `decentralized-finance-defi`, `meme-token`, `artificial-intelligence`, `ai-agents`, `real-world-assets-rwa`, `stablecoins`, `decentralized-exchange`, `lending-borrowing`, `liquid-staking-tokens`, `gaming`, `base-ecosystem`, `solana-ecosystem`, `ethereum-ecosystem`. CoinGecko has 600+ categories: list them with `{"mode":"categories"}` or see [coingecko.com/en/categories](https://www.coingecko.com/en/categories).

**Popular asset platforms (contract mode):** `ethereum`, `base`, `solana`, `binance-smart-chain`, `arbitrum-one`, `polygon-pos`, `optimistic-ethereum`, `avalanche`, `tron`, `sui`, `hyperevm`. Full list (460+): `api.coingecko.com/api/v3/asset_platforms`.

**OHLC candle size (set by CoinGecko):** 1–2 days → 30 min, 3–30 days → 4 h, 31+ days → 4 days.

### Examples

**Today's breakouts among the top 500**

```json
{ "mode": "markets", "maxRank": 500, "minChange24h": 15, "minVolume24h": 1000000, "sortBy": "change24h", "limit": 25 }
```

**Layer-2 tokens by 30-day performance**

```json
{ "mode": "markets", "category": "layer-2", "priceChangeWindows": ["24h", "7d", "30d"], "sortBy": "change30d", "limit": 20 }
```

**Portfolio valuation in EUR**

```json
{ "mode": "price", "ids": ["bitcoin", "ethereum", "solana", "aerodrome-finance"], "vsCurrency": "eur" }
```

**Token due diligence by contract (AERO on Base)**

```json
{ "mode": "contract", "platform": "base", "contractAddresses": ["0x940181a94A35A4569E4529A3CDfB74e38FD98631"], "includeTickers": true, "includeDeveloper": true }
```

**Hot sectors today + 30-day BTC history**

```json
{ "mode": "categories", "categoryOrder": "market_cap_change_24h_desc", "minMarketCap": 100000000, "limit": 15 }
{ "mode": "history", "ids": ["bitcoin"], "days": 30 }
```

### Output

Example `markets` row (trimmed):

```json
{
  "id": "bitcoin",
  "symbol": "BTC",
  "name": "Bitcoin",
  "rank": 1,
  "price": 77046,
  "change1h": 0,
  "change24h": -0.35,
  "change7d": -3.4,
  "marketCap": 1547359786335,
  "fdv": 1547362405889,
  "volume24h": 14567569382,
  "volumeToMcap": 0.0094,
  "circulatingSupply": 20083000,
  "athChangePct": -38.9,
  "currency": "usd",
  "sourceUrl": "https://www.coingecko.com/en/coins/bitcoin",
  "fetchedAt": "2026-09-13T08:16:50.000Z"
}
```

| Mode | Fields |
|---|---|
| `markets` | id, symbol, name, rank, price, change1h, change24h, change7d, change14d, change30d, change200d, change1y, marketCap, marketCapChange24h, fdv, volume24h, volumeToMcap, high24h, low24h, circulatingSupply, totalSupply, maxSupply, ath, athChangePct, athDate, atl, atlDate, image, lastUpdated, (sparkline7d) |
| `price` | id, price, marketCap, volume24h, change24h, lastUpdated |
| `coins` / `contract` | market fields + change60d, categories, platforms {chain: address}, genesisDate, hashingAlgorithm, countryOrigin, homepage, whitepaper, twitter, telegram, subreddit, github, explorers, sentimentUpPct, sentimentDownPct, watchlistUsers, description, (community, developer, tickers\[], exchangeCount), (contractAddress) |
| `trending` | type (coin/nft/category), trendingRank, id, symbol, name, rank, price, change24h, marketCap, volume24h; NFTs: floorPriceNative, floorPriceChange24h; categories: coinsCount, marketCapChange24h, marketCapChange1h |
| `global` | totalMarketCap, totalVolume24h, marketCapChange24h, volumeChange24h, btcDominance, ethDominance, stablecoinDominance, dominance {}, activeCryptocurrencies, markets, defiMarketCap, defiVolume24h, defiDominance, topDefiCoin, updatedAt |
| `categories` | id, name, marketCap, marketCapChange24h, volume24h, top3Coins, description, updatedAt |
| `exchanges` | id, name, trustScore, trustScoreRank, volume24hBtc, volume24hBtcNormalized, volume24hUsd, volumeAnomalyRatio, yearEstablished, country, url, hasTradingIncentive, description |
| `history` | id, coinId, date, timestamp, price, marketCap, volume24h, changePct |
| `ohlc` | id, coinId, timestamp, date, open, high, low, close, changePct |
| `search` | id, type (coin/exchange/category/nft), name, symbol, rank, query |

Every row also has `currency` (where relevant), `sourceUrl` and `fetchedAt`. A `SUMMARY` record in the key-value store lists matched counts, missing ids, warnings and the number of API requests.

### Use it from code / agents

```bash
curl -X POST "https://api.apify.com/v2/acts/yadroo~coingecko-markets/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"mode":"price","ids":["bitcoin","ethereum"],"vsCurrency":"eur"}'
```

```js
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('yadroo/coingecko-markets').call({ mode: 'markets', maxRank: 500, minChange24h: 15, sortBy: 'change24h' });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

```python
import os
from apify_client import ApifyClient
client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("yadroo/coingecko-markets").call(run_input={"mode": "categories", "categoryOrder": "market_cap_change_24h_desc"})
items = client.dataset(run["defaultDatasetId"]).list_items().items
```

MCP: add `https://mcp.apify.com` to Claude, Cursor or your own agent and call `yadroo/coingecko-markets` with the same JSON input.

### Pricing

Pay per event: **$0.001 per run start + $0.001 per row**. The default run (top 50 coins) costs $0.051; a 4-coin price check $0.005; one global snapshot $0.002; 30 days of history for one coin $0.031. OHLC returns many candles (14 days ≈ 84 rows ≈ $0.085) — use shorter windows if you only need the latest bars.

### Limits & FAQ

- **Rate limit** — without a key CoinGecko allows roughly 5–15 requests/min; the actor paces itself at ~9/min and waits 60 s on HTTP 429 (up to 3 retries). Most modes need 1–2 requests; `coins`/`contract`/`history`/`ohlc` need one request per id. A free Demo key (30 req/min) makes multi-id runs faster.
- **Freshness** — prices update every 1–2 minutes on CoinGecko's side; every run reads live data.
- **History depth** — the public API serves the last 365 days; older `from` dates need a paid key.
- **Missing data** — unknown ids, delisted coins and unsupported currencies are reported as warnings or clear errors, never silently dropped. Some fields (e.g. `maxSupply`, normalized exchange volume) are null when CoinGecko has no value.
- **Terms** — data comes from CoinGecko's public API; attribute CoinGecko when you publish it. Not financial advice.
- **Roadmap** — NFT collection data, derivatives tickers, treasury holdings of public companies.

***

Made by **Yadroo** — more crypto data actors: [defillama-protocols](https://apify.com/yadroo/defillama-protocols) · [crypto-sentiment](https://apify.com/yadroo/crypto-sentiment) · [crypto-news](https://apify.com/yadroo/crypto-news) · [dexscreener-tokens](https://apify.com/yadroo/dexscreener-tokens) · [wallet-intel](https://apify.com/yadroo/wallet-intel) · [x402-endpoints](https://apify.com/yadroo/x402-endpoints)

# Actor input Schema

## `mode` (type: `string`):

What to fetch. Each mode uses only the inputs of its section below.

## `ids` (type: `array`):

CoinGecko coin ids (lowercase slugs from the coin page URL coingecko.com/en/coins/<id>), e.g. bitcoin, ethereum, solana, aerodrome-finance. Required for modes price, coins, history, ohlc; optional filter for markets. Not tickers — use mode search to look ids up.

## `symbols` (type: `array`):

Alternative to ids in mode markets: tickers like btc, eth, sol. Several coins can share a ticker; all are returned.

## `vsCurrency` (type: `string`):

Currency for prices, market caps and volumes (CoinGecko's full supported list). KZT and other currencies not listed are not supported by CoinGecko.

## `limit` (type: `integer`):

Max rows pushed (markets, coins, contract, trending, categories, exchanges, search). History/OHLC return all points in the window; price returns one row per id.

## `fields` (type: `array`):

Keep only these output fields (e.g. id, symbol, price, change24h). Empty = all fields.

## `category` (type: `string`):

CoinGecko category id (slug from coingecko.com/en/categories/<id>), e.g. layer-2, meme-token, decentralized-finance-defi, artificial-intelligence, real-world-assets-rwa, base-ecosystem, solana-ecosystem, stablecoins. Unknown ids fail with suggestions. Use mode categories or search to list ids.

## `order` (type: `string`):

Order in which CoinGecko ranks coins before the limit is applied (decides which coins enter the result).

## `priceChangeWindows` (type: `array`):

Which % change fields to fill: 1h, 24h, 7d, 14d, 30d, 200d, 1y. Unrequested windows stay null.

## `includeSparkline` (type: `boolean`):

Add sparkline7d (≈168 hourly prices) to each row.

## `minMarketCap` (type: `integer`):

In vsCurrency. Also used by mode categories.

## `maxMarketCap` (type: `integer`):

In vsCurrency (e.g. 50000000 to find small caps).

## `minVolume24h` (type: `integer`):

In vsCurrency.

## `maxRank` (type: `integer`):

Keep coins ranked 1..N.

## `minChange24h` (type: `integer`):

e.g. 10 = pumped at least +10%.

## `maxChange24h` (type: `integer`):

e.g. -10 = dropped at least 10%.

## `minChange7d` (type: `integer`):

Needs 7d in priceChangeWindows.

## `maxChange7d` (type: `integer`):

Needs 7d in priceChangeWindows.

## `minVolumeToMcap` (type: `string`):

Turnover ratio, e.g. 0.2 = daily volume ≥ 20% of market cap (unusual activity).

## `search` (type: `string`):

Case-insensitive substring of name/symbol/id. Also filters modes categories and exchanges.

## `sortBy` (type: `string`):

Client-side sort of the matched coins (nulls last). Empty = keep server order.

## `sortDir` (type: `string`):

No description

## `includeDescription` (type: `boolean`):

Coin description (plain text, first 1000 chars).

## `includeTickers` (type: `boolean`):

Top 10 exchange tickers (market, pair, volume, trust score).

## `includeCommunity` (type: `boolean`):

Twitter followers, Reddit subscribers, Telegram users.

## `includeDeveloper` (type: `boolean`):

GitHub stars, forks, commits (4 weeks).

## `platform` (type: `string`):

Mode contract: asset platform id, e.g. ethereum, base, solana, binance-smart-chain, arbitrum-one, polygon-pos, optimistic-ethereum, avalanche, tron. Full list: api.coingecko.com/api/v3/asset\_platforms.

## `contractAddresses` (type: `array`):

Mode contract: token contract addresses on the platform above.

## `includeNfts` (type: `boolean`):

Mode trending: add NFT collections (type = nft).

## `includeCategories` (type: `boolean`):

Mode trending: add categories (type = category).

## `categoryOrder` (type: `string`):

Mode categories.

## `query` (type: `string`):

Mode search: name or symbol, e.g. aerodrome, pepe, binance.

## `days` (type: `integer`):

History: 1–365 (default 30). OHLC: one of 1, 7, 14, 30, 90, 180, 365 (default 7; other values round up). Candle size is set by CoinGecko: 30 min (1–2 days), 4 h (3–30 days), 4 days (31+ days).

## `from` (type: `string`):

History: start date (YYYY-MM-DD). Overrides days. The public API only serves the last 365 days.

## `to` (type: `string`):

History: end date (YYYY-MM-DD), default today.

## `dailyOnly` (type: `boolean`):

History: keep the last point per UTC day.

## `coingeckoApiKey` (type: `string`):

Optional free Demo key (coingecko.com/en/api) raises the rate limit from ~5–15 to 30 requests/min. Pro keys: also set apiPlan = pro. Never required.

## `apiPlan` (type: `string`):

Which CoinGecko plan the key belongs to.

## Actor input object example

```json
{
  "mode": "markets",
  "ids": [
    "bitcoin",
    "ethereum"
  ],
  "vsCurrency": "usd",
  "limit": 50,
  "order": "market_cap_desc",
  "priceChangeWindows": [
    "1h",
    "24h",
    "7d"
  ],
  "includeSparkline": false,
  "sortDir": "desc",
  "includeDescription": true,
  "includeTickers": false,
  "includeCommunity": false,
  "includeDeveloper": false,
  "includeNfts": false,
  "includeCategories": false,
  "categoryOrder": "market_cap_desc",
  "dailyOnly": true,
  "apiPlan": "demo"
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `summary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "ids": [
        "bitcoin",
        "ethereum"
    ],
    "priceChangeWindows": [
        "1h",
        "24h",
        "7d"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("yadroo/coingecko-markets").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "ids": [
        "bitcoin",
        "ethereum",
    ],
    "priceChangeWindows": [
        "1h",
        "24h",
        "7d",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("yadroo/coingecko-markets").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "ids": [
    "bitcoin",
    "ethereum"
  ],
  "priceChangeWindows": [
    "1h",
    "24h",
    "7d"
  ]
}' |
apify call yadroo/coingecko-markets --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,yadroo/coingecko-markets"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/SDxMGtPkx52LRVc3R/builds/eNXfHcehDBHnEnUz0/openapi.json