# CoinGecko Scraper (`publicmoney/coingecko-scraper`) Actor

Extract CoinGecko market data for any coin with no API key: price in any currency, market cap and rank, 24h volume, circulating and max supply, all-time high and low, and multi-window change. Export data, run via API, schedule and monitor runs, or integrate with other tools.

- **URL**: https://apify.com/publicmoney/coingecko-scraper.md
- **Developed by:** [Public Money](https://apify.com/publicmoney) (Apify)
- **Categories:** Business
- **Stats:** 4 total users, 3 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $1.00 / 1,000 records

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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

CoinGecko's free API is rate limited hard enough that a watchlist sweep trips it, and the Pro plan starts where hobby projects stop. This Actor reads CoinGecko market data for any coin and returns one structured record: price in the currency you ask for, market cap and rank, 24h volume, supply, all-time high and low, and percent change across several windows. Leave the coin list empty and it sweeps the top of the market by cap instead.

### What it does

- Returns **one record per coin**, in order. A coin id CoinGecko does not know comes back with `status: "failed"` and a reason.
- Sweeps the market when you **leave the coin list empty**, ordered by market cap, volume or id, so you do not need to know the ids in advance.
- Filters by **category** (`layer-1`, `decentralized-finance-defi`, `meme-token` and the rest), which is the fastest way to price a sector.
- Prices in **any currency CoinGecko supports**, not just USD, so `eur`, `gbp`, `jpy`, `btc` and `eth` all work as the quote.
- Carries the **all-time high and low with the percent change from each**, which is the context a bare price is missing.
- Optional **price history** (up to the days you ask for) and a **coin profile** with links, categories and descriptions.
- Takes an optional **Pro API key**. Supply one and the run switches to the Pro endpoint with its higher limit; leave it empty and the public API is used.

### Use cases

| You need to | How this Actor does it |
| --- | --- |
| Price a whole portfolio in EUR | Pass your coin ids and set the quote currency to `eur` |
| Rank a sector | Set a category and order by market cap, then read `marketCapRank` |
| Find how far a coin is off its high | Read `ath` and `athChangePercentage` in the same record |
| Screen for supply scarcity | Compare `circulatingSupply` against `maxSupply` |
| Feed a crypto research agent | Call the Actor over MCP and let the model ask for the coin or category it needs |
| Track a market every hour | Schedule the run and let the dataset accumulate a row per coin per run |

### Quick start

1. Click **Try for free**.
2. Add CoinGecko coin ids, one per line: `bitcoin`, `ethereum`, `solana`. These are ids, not tickers, so it is `bitcoin` rather than `BTC`. Leave the field empty to sweep the top of the market instead.
3. Set **Quote currency** if you want something other than `usd`.
4. Optionally set a **Category** to price one sector, and raise or lower **Max items**.
5. Click **Start**. Rows appear within seconds.
6. Export as JSON, CSV, Excel or XML, or read the dataset over the API.

### Input

| Field | Type | Default | What it controls |
| --- | --- | --- | --- |
| `coinIds` | array | empty | CoinGecko coin ids to read. Empty sweeps the market by the chosen order |
| `vsCurrency` | string | `usd` | The quote currency. Any CoinGecko-supported code, including `btc` and `eth` |
| `category` | string | empty | Restricts a market sweep to one CoinGecko category |
| `order` | string | `market_cap_desc` | Sweep order: market cap, volume or id, ascending or descending |
| `includeCoinProfile` | boolean | `false` | Adds links, categories and the project description |
| `includeHistory` | boolean | `false` | Adds a price series for the trailing window |
| `historyDays` | integer | `30` | How many days of history to include |
| `maxItems` | integer | `100` | Caps how many coins are read |
| `apiKey` | string | empty | Optional CoinGecko Pro key. Raises the rate limit and switches to the Pro endpoint |

```json
{
    "coinIds": [
        "bitcoin",
        "ethereum",
        "solana"
    ],
    "vsCurrency": "usd",
    "maxItems": 100
}
```

### Output

One dataset item per coin. Fields CoinGecko does not publish for a coin are dropped rather than returned as `null`, and profile and history fields appear only when you ask for them.

| Field group | Fields |
| --- | --- |
| Identity | `status`, `coinId`, `symbol`, `name`, `marketCapRank`, `url` |
| Price | `value`, `vsCurrency`, `priceChangePercentage24h`, `priceChangePercentage7d`, `priceChangePercentage30d` |
| Market | `marketCap`, `volume24h`, `fullyDilutedValuation` |
| Supply | `circulatingSupply`, `totalSupply`, `maxSupply` |
| Extremes | `ath`, `athDate`, `athChangePercentage`, `atl`, `atlDate`, `atlChangePercentage` |
| Optional | `profile`, `priceHistory` |
| Timing | `validFrom`, `scrapedAt` |

```json
{
    "status": "ok",
    "coinId": "bitcoin",
    "symbol": "BTC",
    "name": "Bitcoin",
    "marketCapRank": 1,
    "value": 104238.61,
    "vsCurrency": "usd",
    "priceChangePercentage24h": -1.84,
    "marketCap": 2068442110394,
    "volume24h": 41220118844,
    "circulatingSupply": 19842193.0,
    "maxSupply": 21000000.0,
    "ath": 126198.0,
    "athChangePercentage": -17.4,
    "validFrom": "2026-09-04T20:00:01.000Z",
    "url": "https://www.coingecko.com/en/coins/bitcoin"
}
```

### Integrations

Run it over the API and get the rows back in one call:

```bash
curl -X POST "https://api.apify.com/v2/acts/publicmoney~coingecko-scraper/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"coinIds": ["bitcoin", "ethereum", "solana"], "vsCurrency": "usd", "maxItems": 100}'
```

From Python:

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_TOKEN")
run = client.actor("publicmoney/coingecko-scraper").call(run_input={"coinIds": ["bitcoin", "ethereum", "solana"], "vsCurrency": "usd", "maxItems": 100})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["symbol"], item["name"], item["value"])
```

Give an AI agent the Actor over MCP:

```json
{
    "mcpServers": {
        "apify": {
            "url": "https://mcp.apify.com/?actors=publicmoney/coingecko-scraper"
        }
    }
}
```

Schedules run it on any cron, webhooks fire when a run finishes, and platform integrations push the
dataset to Google Sheets, Slack, Airtable, Zapier or your own endpoint.

### Cost

Pay per event, so you pay for records rather than compute time.

| Event | Free tier | Top volume tier |
| --- | --- | --- |
| Record with data | $0.002 | $0.0007 |
| Actor start | $0.00005 per GB | Same |

A record that returned no data is published as a failure row and is **never charged**. Six volume tiers apply, so the per-record price falls with monthly volume.

### Troubleshooting

| Issue | Solution |
| --- | --- |
| A coin returns `failed` | You sent a ticker instead of a CoinGecko id. It is `bitcoin`, not `BTC`. The id is in the coin's CoinGecko URL. |
| I get far more rows than I expected | The coin list was left empty, so the Actor swept the market. Set **Max items** or name the coins. |
| `maxSupply` is missing | CoinGecko publishes no max supply for coins that have none, such as Ethereum. That is the source, not a gap. |
| The run is rate limited | The public CoinGecko API has a low limit. Supply a Pro key to switch to the Pro endpoint, or lower **Max items**. |
| A category returns nothing | Category ids are CoinGecko's own slugs, such as `decentralized-finance-defi`. Check the spelling on their categories page. |

### FAQ

#### Is the CoinGecko API free?

CoinGecko has a free public tier with a low rate limit and a paid Pro tier. This Actor works against the public tier with no key, and if you have a Pro key you can supply it to raise the limit. The Actor itself is charged per record.

#### What is a CoinGecko coin id?

CoinGecko's own slug for a coin, which is not the ticker. Bitcoin is `bitcoin`, Polygon is `matic-network`. You can read it off the end of the coin's CoinGecko URL.

#### Can I price in something other than USD?

Yes. Set the quote currency to any code CoinGecko supports, fiat or crypto, so `eur`, `jpy`, `btc` and `eth` all work.

#### Does it return historical prices?

Yes, if you turn on history and set the number of days. Without it each record is the current market snapshot stamped with `validFrom`.

#### Can I get the whole market instead of a list?

Yes. Leave the coin list empty and the Actor sweeps the market in the order you choose, capped by **Max items**. Add a category to sweep one sector.

#### Do I need a CoinGecko API key?

No. You need an Apify token to call the Actor over the API. No CoinGecko credential is involved anywhere.

#### Can I get this data in Python?

Yes, with the `apify-client` package as shown above. It returns parsed JSON, so there is no HTML or response handling on your side.

#### Can I get the data into Excel or Google Sheets?

Yes. Export the dataset as XLSX or CSV, or connect the Google Sheets integration so each run appends to a sheet.

#### Can an AI agent call this Actor?

Yes. Add it to an MCP client with the config above and the model can request what it needs on its own. Every record is flat JSON with named fields, so no post-processing is needed.

#### Is it legal to scrape CoinGecko?

This Actor reads public CoinGecko data that needs no login and collects no personal data. Scraping public data is generally lawful, and how you store, redistribute or act on market data is governed by your own agreements and local rules. Take your own legal advice for your use case.

### Changelog

- **0.0.2** Added optional price history, the coin profile and category sweeps.
- **0.0.1** First release. Market data for any coin or the top of the market.

### Feedback

Found a field CoinGecko publishes that this Actor misses, or an input it rejects? Open an issue on the Issues tab with the input and what you expected. A daily test runs every Actor in the fleet against live sources, so parser fixes ship fast.

# Actor input Schema

## `coinIds` (type: `array`):

CoinGecko coin ids to read, one per line. These are CoinGecko's own slugs and not tickers, so Bitcoin is 'bitcoin' and Polygon is 'matic-network'; the id is the last part of the coin's CoinGecko URL. Leave the field empty to sweep the top of the market in the order you chose instead of naming coins. Examples: 'bitcoin', 'ethereum', 'solana'.

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

The currency every price, market cap and volume is quoted in. Any code CoinGecko supports works, crypto as well as fiat, so you can price a portfolio in euros or denominate it in BTC. Examples: 'usd', 'eur', 'jpy', 'btc'. Default is 'usd'.

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

Restrict the ranking to one CoinGecko category ID. Examples: 'layer-1', 'decentralized-finance-defi', 'meme-token'. Ignored when Coin IDs are given.

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

How a market sweep is ordered when the coin list is left empty. Ignored when you name coins, because named coins come back in the order you listed them. Examples: 'market\_cap\_desc', 'volume\_desc', 'id\_asc'. Default is 'market\_cap\_desc'.

## `includeCoinProfile` (type: `boolean`):

Adds the project profile to each record: links, categories and the description CoinGecko carries. It costs an extra request per coin, so leave it off for a price-only run. Examples: true for research, false for prices. Default is off.

## `maxItems` (type: `integer`):

Maximum number of coins to read, counted from the top of the list. Use it to cap spend on a long list without editing the list itself. Examples: 10, 50, 200.

## `apiKey` (type: `string`):

CoinGecko Pro API key. The public API works with no key but is rate limited hard enough that a large sweep can trip it; supplying a key raises the limit and switches the run to the Pro endpoint. Stored as a secret and never written to the dataset.

## `includeHistory` (type: `boolean`):

Adds a price series for the trailing window set by History days. It costs an extra request per coin, so leave it off unless you need the series. Examples: true for a chart, false for a snapshot. Default is off.

## `historyDays` (type: `integer`):

How many days of price history to include when history is on. Longer windows return more points and take longer to fetch. Examples: 7, 30, 365. Default is 30.

## Actor input object example

```json
{
  "coinIds": [
    "bitcoin",
    "ethereum",
    "https://www.coingecko.com/en/coins/solana"
  ],
  "vsCurrency": "usd",
  "order": "market_cap_desc",
  "includeCoinProfile": false,
  "maxItems": 100,
  "includeHistory": false,
  "historyDays": 30
}
```

# Actor output Schema

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

One item per coin scraped by the run, in the default dataset.

# 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 = {
    "coinIds": [
        "bitcoin",
        "ethereum",
        "https://www.coingecko.com/en/coins/solana"
    ],
    "vsCurrency": "usd",
    "order": "market_cap_desc",
    "includeCoinProfile": false,
    "maxItems": 100,
    "includeHistory": false,
    "historyDays": 30
};

// Run the Actor and wait for it to finish
const run = await client.actor("publicmoney/coingecko-scraper").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 = {
    "coinIds": [
        "bitcoin",
        "ethereum",
        "https://www.coingecko.com/en/coins/solana",
    ],
    "vsCurrency": "usd",
    "order": "market_cap_desc",
    "includeCoinProfile": False,
    "maxItems": 100,
    "includeHistory": False,
    "historyDays": 30,
}

# Run the Actor and wait for it to finish
run = client.actor("publicmoney/coingecko-scraper").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 '{
  "coinIds": [
    "bitcoin",
    "ethereum",
    "https://www.coingecko.com/en/coins/solana"
  ],
  "vsCurrency": "usd",
  "order": "market_cap_desc",
  "includeCoinProfile": false,
  "maxItems": 100,
  "includeHistory": false,
  "historyDays": 30
}' |
apify call publicmoney/coingecko-scraper --silent --output-dataset

```

## MCP server setup

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

```

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/qewOuv6pe5h8nI2CA/builds/8l1tTHUMr5adPqUD9/openapi.json