# CoinGecko Scraper - Crypto Prices & Market Rankings (`dami_studio/coingecko-scraper`) Actor

Scrape CoinGecko crypto prices and rankings. Get top coins by market cap, or pass your own ids. Each coin has price, market cap, rank and supply. Plus 24h volume, 24h and 7d change, ATH and ATL. Coin keys are slugs, not tickers: BNB is binancecoin. Name search gives ids only. $2.00 per 1,000 coins.

- **URL**: https://apify.com/dami\_studio/coingecko-scraper.md
- **Developed by:** [Dami's Studio](https://apify.com/dami_studio) (community)
- **Categories:** Integrations, AI, Other
- **Stats:** 4 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

$2.00 / 1,000 coin returneds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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 Scraper

On CoinGecko a coin's key is a slug, not its ticker. BNB is `binancecoin`; XRP is `ripple`. Get the id right and the rest of the public API is straightforward: top coins by market cap, a name or symbol lookup, or a specific list of coins, one row each, no API key.

### Three modes

| `mode` | What it does |
|---|---|
| `markets` | Top coins ranked by market cap. Pages 250 at a time up to your `maxItems`. This is the default. |
| `coins` | Exactly the coins you name in `coinIds`. Same full row shape as `markets`. |
| `search` | Name or symbol lookup. **Lighter rows** — see the warning below. |

### What you get per coin

In `markets` and `coins` mode:

```json
{
  "ok": true,
  "id": "bitcoin",
  "symbol": "BTC",
  "name": "Bitcoin",
  "price": 76971,
  "marketCap": 1544943714252,
  "marketCapRank": 1,
  "volume24h": 67826956480,
  "change24hPct": 7.2,
  "change7dPct": 23.4,
  "circulatingSupply": 20071518,
  "ath": 126080,
  "athDate": "2025-10-06T10:57:42.000Z",
  "atl": 67.81,
  "image": "https://coin-images.coingecko.com/coins/images/1/large/bitcoin.png",
  "url": "https://www.coingecko.com/en/coins/bitcoin"
}
```

**`search` mode returns only `id`, `name`, `symbol`, `marketCapRank`, `image` and `url`.** No price, no market cap, no volume, no change. It costs the same per row, so use it to find a coin's id and then run `coins` mode with that id if you want the numbers.

### Input

```json
{ "mode": "markets", "vsCurrency": "usd", "maxItems": 250 }
```

```json
{ "mode": "coins", "vsCurrency": "eur", "coinIds": ["bitcoin", "ethereum", "solana"] }
```

```json
{ "mode": "search", "query": "solana" }
```

| Field | Default | Notes |
|---|---|---|
| `mode` | `markets` | `markets`, `search` or `coins`. |
| `vsCurrency` | `usd` | What prices, market cap and volume are quoted in. Any currency CoinGecko supports: `usd`, `eur`, `gbp`, `jpy`, `btc`, `eth` and the rest of its list. Used by `markets` and `coins`. |
| `query` | — | Search term. `search` mode only. |
| `coinIds` | — | CoinGecko ids — the slug from a coin's page URL. `coins` mode only. |
| `maxItems` | 100 | `markets` mode only, up to 5,000. |
| `proxyConfiguration` | off | Optional. The public API needs no proxy; it only helps if you're repeatedly hitting 429s on bulk runs, and it spends metered credit. |
| `notionConnector` / `notionParentId` | — | Optional delivery into Notion via an Apify MCP connector. |

### Limits worth knowing

- **The free public API is rate-limited**, roughly 10 to 30 requests a minute. On a 429 the actor honours `Retry-After` and backs off up to about a minute rather than failing. That costs run time on big sweeps, so space large runs out.
- **This is a snapshot, not a feed.** One row per coin at the moment of the run. There's no historical series and no candles.
- **`change7dPct` is only requested in `markets` and `coins` mode**, and CoinGecko doesn't report every metric for every coin. Any numeric field can be `null`.
- **`atl` has no date field.** `ath` has `athDate`; the all-time low doesn't get one from this endpoint.
- **Rows are deduplicated by `id`.**

### Billing

**$2.00 per 1,000 coins** ($0.002 each). Flat on every plan.

One charge per coin row, and that's the only line on the bill. Diagnostic rows (`NO_RESULTS`, `BAD_INPUT`, `RATE_LIMITED`) are never charged, so a throttled run costs $0.00 even though the back-off burns wall clock.

One thing to watch: a `search` row costs the same $0.002 as a full market row and carries six fields instead of fifteen. If you're after prices, use `markets` or `coins`.

### When something comes back empty

Read the `errorCode` on the diagnostic row. `BAD_INPUT` means a mode, query or id was missing or wrong. `RATE_LIMITED` means CoinGecko throttled the run — wait a bit and try again, or turn the proxy on.

# Actor input Schema

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

What to fetch: "markets" = top coins ranked by market cap (full ~15-field rows); "search" = look up coins by name/symbol (lighter 6-field rows: id, name, symbol, marketCapRank, image, url — no price/marketCap/volume); "coins" = fetch specific coins by their CoinGecko id (full rows).

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

The fiat or crypto currency that prices, market cap and volume are quoted in, e.g. usd, eur, gbp, btc, eth. Used by Markets and Coins modes.

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

Coin name or symbol to search for (only used in Search mode), e.g. "solana", "doge", "bitcoin".

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

List of CoinGecko coin ids to fetch (only used in Coins mode), e.g. \["bitcoin", "ethereum", "solana"]. The id is the slug from a coin's CoinGecko URL.

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

Maximum number of coins to return in Markets mode. The actor paginates 250 per request as needed.

## `notionConnector` (type: `string`):

Optional. Write each coin as a page into your Notion when the run finishes. Authorize a Notion connector once in Settings → API & Integrations → MCP connectors, then pick it here. Leave empty to skip (default) — results are always saved to the dataset regardless.

## `notionParentId` (type: `string`):

Optional. The Notion data source ID of the database to write into (only used if a Notion connector is set). Leave empty to create the pages privately in your workspace instead.

## `proxyConfiguration` (type: `object`):

Optional. CoinGecko's public API needs no proxy, so leave this off by default. Only enable Apify Proxy if you hit IP-based rate limits (HTTP 429) on bulk runs — spreading requests across IPs can help, at the cost of metered proxy credit.

## Actor input object example

```json
{
  "mode": "markets",
  "vsCurrency": "usd",
  "query": "solana",
  "coinIds": [
    "bitcoin",
    "ethereum"
  ],
  "maxItems": 100,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

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

Scraped rows are stored in the default dataset (one row per result). Blocked/empty/error runs return a single uncharged diagnostic row instead.

# 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 = {
    "query": "solana",
    "coinIds": [
        "bitcoin",
        "ethereum"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("dami_studio/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 = {
    "query": "solana",
    "coinIds": [
        "bitcoin",
        "ethereum",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("dami_studio/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 '{
  "query": "solana",
  "coinIds": [
    "bitcoin",
    "ethereum"
  ]
}' |
apify call dami_studio/coingecko-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,dami_studio/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/wHIE3RLZXqTzMe8ic/builds/ZTNgNbYXrhtfMRahK/openapi.json