# CoinGecko Crypto Market Data Scraper (`automation-lab/coingecko-crypto-market-data`) Actor

Export current and bounded historical CoinGecko prices, ranks, market caps, volume, changes, supply, and timestamps for portfolio monitoring.

- **URL**: https://apify.com/automation-lab/coingecko-crypto-market-data.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.96 / 1,000 item extracteds

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 Crypto Market Data Scraper

Export current and bounded historical cryptocurrency market data from CoinGecko for portfolio monitoring, research, dashboards, and scheduled comparisons.

The Actor uses CoinGecko's anonymous public JSON endpoints. It needs no CoinGecko API key and no browser. Supply exact coin IDs such as `bitcoin`, `ethereum`, and `solana`, or retrieve a ranked market/category snapshot.

### What does this CoinGecko scraper do?

The Actor supports two focused workflows:

- **Current market snapshots** — one normalized row per coin with identity, price, rank, market cap, volume, change, supply, all-time-high/low, and update timestamps.
- **Bounded historical observations** — daily price, market-cap, and volume points for up to 10 supplied coin IDs over 1, 7, 14, 30, or 90 days.

Current mode can target exact CoinGecko IDs or browse ranked market rows. It also supports quote currency, category ID, ordering, and an output limit.

Historical mode intentionally stays bounded. It is designed for recurring portfolio comparisons, not tick-level trading or unlimited archive downloads.

### Who is this Actor for?

- Portfolio analysts scheduling daily cryptocurrency snapshots.
- Data teams feeding market dashboards or spreadsheets.
- Researchers comparing price, capitalization, and volume over time.
- Developers who want CoinGecko API data without maintaining retry, normalization, schema, and export code.
- Finance and fintech teams monitoring a fixed watchlist.
- Automation builders connecting CoinGecko data to Make, Zapier, n8n, webhooks, or Apify integrations.

### Why use this Actor?

- No CoinGecko API key is required for the implemented public scope.
- Stable, typed fields replace raw endpoint-specific snake\_case payloads.
- Exact coin-ID and ranked-market workflows use one consistent dataset schema.
- Bounded retries handle temporary timeouts, throttling, and upstream server errors.
- Historical requests are serialized to respect anonymous API limits.
- `maxItems` gives every run a clear output boundary.
- Dataset results export directly as JSON, CSV, Excel, XML, RSS, or through the Apify API.

### What CoinGecko data can I extract?

| Field | Meaning |
|---|---|
| `recordType` | `current` or `historical` |
| `coinId`, `symbol`, `name` | CoinGecko identity fields |
| `image` | Coin image URL when available |
| `currency` | Quote currency used for monetary values |
| `price` | Current or observed price |
| `marketCap`, `marketCapRank` | Capitalization and current rank |
| `totalVolume` | Current or observed trading volume |
| `high24h`, `low24h` | Current 24-hour range |
| `priceChange24h` | Absolute 24-hour price movement |
| `priceChangePercentage1h` | One-hour percentage movement |
| `priceChangePercentage24h` | 24-hour percentage movement |
| `priceChangePercentage7d` | Seven-day percentage movement |
| `priceChangePercentage30d` | 30-day percentage movement |
| `circulatingSupply` | Current circulating supply |
| `totalSupply`, `maxSupply` | Supply totals when CoinGecko reports them |
| `ath`, `athDate` | All-time high and timestamp |
| `atl`, `atlDate` | All-time low and timestamp |
| `observedAt` | Timestamp represented by the row |
| `lastUpdated` | CoinGecko's update timestamp for current rows |
| `sourceUrl` | Public CoinGecko page for the coin/data |
| `scrapedAt` | Timestamp when the Actor fetched the row |

Historical rows do not invent fields unavailable from the public chart endpoint. Identity beyond `coinId`, rank, supply, change, and ATH/ATL fields are `null` in those rows.

### How to get started

1. Open the Actor in Apify Console.
2. Keep **Current market snapshot** for current data, or choose **Historical daily observations**.
3. Enter CoinGecko coin IDs such as `bitcoin` and `ethereum`. Clear the list to browse the ranked market in current mode.
4. Select the quote currency and output limit.
5. For current market discovery, optionally add a CoinGecko category ID and ordering.
6. For historical mode, choose a supported lookback and supply no more than 10 coin IDs.
7. Click **Start**.
8. Open the **Dataset** tab or export the rows through an integration.

### Input parameters

| Input | Type | Default | Notes |
|---|---|---:|---|
| `mode` | string | `current` | `current` or `historical` |
| `coinIds` | string\[] | Bitcoin, Ethereum, Solana | Up to 250 current IDs; 1–10 required for history |
| `vsCurrency` | string | `usd` | CoinGecko quote currency code |
| `category` | string | empty | CoinGecko category ID; current mode only |
| `order` | string | `market_cap_desc` | Market cap, volume, or ID ordering |
| `maxItems` | integer | `100` | Maximum dataset rows, from 1 to 2,500 |
| `historyDays` | integer | `7` | One of 1, 7, 14, 30, or 90 |

Use CoinGecko IDs, not ticker symbols. For example, use `bitcoin`, not `BTC`.

#### Current portfolio snapshot input

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

#### Ranked category input

```json
{
  "mode": "current",
  "coinIds": [],
  "vsCurrency": "usd",
  "category": "decentralized-finance-defi",
  "order": "market_cap_desc",
  "maxItems": 25
}
```

#### Historical input

```json
{
  "mode": "historical",
  "coinIds": ["bitcoin", "ethereum"],
  "vsCurrency": "usd",
  "historyDays": 7,
  "maxItems": 20
}
```

### Output example

A current run returns rows like this:

```json
{
  "recordType": "current",
  "coinId": "bitcoin",
  "symbol": "btc",
  "name": "Bitcoin",
  "currency": "USD",
  "price": 80525,
  "marketCap": 1615857166835,
  "marketCapRank": 1,
  "totalVolume": 56887421442,
  "priceChangePercentage24h": 3.96721,
  "observedAt": "2026-08-25T06:46:20.000Z",
  "lastUpdated": "2026-08-25T06:46:20.000Z",
  "sourceUrl": "https://www.coingecko.com/en/coins/bitcoin",
  "scrapedAt": "2026-08-25T06:47:00.000Z"
}
```

Values change with the market. Nullable schema fields remain explicit so downstream pipelines can distinguish missing source data from zero.

### How much does it cost to extract CoinGecko market data?

This Actor uses pay-per-event pricing: one small **Run started** event per run plus one **Item extracted** event for each saved dataset row. Failed, rejected, or duplicate rows are not item events.

The exact plan-specific event prices are displayed in Apify Console before a run. At the initial FREE-tier configuration, a run costs **$0.00005 plus $0.00184 per saved row**. That is approximately:

- 3 portfolio rows: **$0.00557**
- 25 market rows: **$0.04605**
- 100 market or historical rows: **$0.18405**

Paid Apify plans receive lower per-item tier prices. Compute usage is included in platform run billing separately where applicable. Check the live pricing panel for the authoritative total before running large schedules.

### Schedule portfolio monitoring

Apify schedules can run the same input hourly, daily, or weekly. A practical workflow is:

1. Save a Task with fixed `coinIds`.
2. Schedule it once per day.
3. Send the completed dataset to a webhook, cloud storage, Google Sheets, or your database.
4. Compare `price`, `marketCap`, `totalVolume`, and `observedAt` against the previous run.
5. Trigger your own alert only when a business threshold is crossed.

The Actor exports observations; it does not claim to provide investment advice or execute trades.

### Integrations and exports

Use the dataset with:

- Apify webhooks for run-completed automation.
- Google Sheets for lightweight portfolio reports.
- Make, Zapier, and n8n for no-code workflows.
- Python, JavaScript, R, or BI tools through the dataset API.
- CSV or Excel exports for one-time analysis.
- Cloud storage or data warehouses for longitudinal monitoring.

Use `coinId` plus `observedAt` as a practical observation key. Use `scrapedAt` to audit when your collection job ran.

### Use the Actor through the API

Replace `YOUR_TOKEN` with your Apify API token.

#### cURL

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~coingecko-crypto-market-data/runs?token=YOUR_TOKEN&waitForFinish=120" \
  -H "Content-Type: application/json" \
  -d '{"mode":"current","coinIds":["bitcoin","ethereum"],"vsCurrency":"usd","maxItems":2}'
```

#### JavaScript

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/coingecko-crypto-market-data').call({
  mode: 'current',
  coinIds: ['bitcoin', 'ethereum'],
  vsCurrency: 'usd',
  maxItems: 2,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

#### Python

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("automation-lab/coingecko-crypto-market-data").call(run_input={
    "mode": "historical",
    "coinIds": ["bitcoin", "ethereum"],
    "vsCurrency": "usd",
    "historyDays": 7,
    "maxItems": 20,
})
items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)
```

### Use with MCP and AI assistants

Add the Actor to Claude Code:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/coingecko-crypto-market-data"
```

#### Claude Desktop

Add this JSON under `mcpServers` in Claude Desktop's MCP configuration:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/coingecko-crypto-market-data"
    }
  }
}
```

#### Cursor

Add the same `mcpServers.apify.url` entry to your Cursor MCP settings.

#### VS Code

Add the HTTP server URL to your VS Code MCP configuration, using the `apify` server name shown above.

Example prompts:

- "Fetch current USD market rows for bitcoin, ethereum, and solana."
- "Export seven days of daily Bitcoin and Ethereum market history."
- "Get the top 25 cryptocurrencies by market cap for a spreadsheet."

### Limits and responsible operation

- CoinGecko controls anonymous API availability and rate limits.
- Temporary HTTP 429, timeout, and server failures are retried with bounded backoff.
- Deterministic input or upstream client errors fail clearly instead of silently returning fabricated data.
- Current mode accepts up to 250 supplied IDs; historical mode accepts up to 10.
- Historical lookback is limited to 90 days and daily observations.
- `maxItems` limits saved rows, not the number of upstream points CoinGecko may calculate.
- This Actor does not provide tick data, order books, exchange execution, wallet data, alerts, or investment recommendations.
- No residential proxy or browser fallback is used.

For stable recurring jobs, avoid running many identical Tasks at the same second. Stagger schedules to reduce anonymous API throttling.

### Legality and responsible use

CoinGecko data is provided by CoinGecko under its own terms and policies. You are responsible for reviewing those terms, choosing an appropriate request frequency, honoring attribution or licensing requirements, and ensuring that your downstream use is lawful.

Do not present delayed or aggregated observations as guaranteed real-time trading data. Validate important financial decisions against authoritative sources. This Actor is an independent automation tool and is not affiliated with or endorsed by CoinGecko.

### Troubleshooting

#### Why did my run return no rows?

Check that every `coinIds` value is a CoinGecko ID rather than a ticker. `bitcoin` is valid; `BTC` is not an ID. For category discovery, verify the exact CoinGecko category ID.

#### Why did the run fail with HTTP 429?

CoinGecko throttled the anonymous API. The Actor retries with backoff, but sustained limits can still fail a run. Wait before retrying, reduce historical coin count, and stagger scheduled Tasks.

#### Why are fields null in historical rows?

The bounded chart endpoint returns timestamped price, market cap, and volume. It does not return rank, supply, changes, or ATH/ATL per historical point, so the Actor leaves those fields null rather than mixing current values into historical observations.

#### Why are there eight points for a seven-day request?

CoinGecko may include both boundary observations in a requested window. `maxItems` remains the final saved-row cap.

### FAQ

#### Does this Actor need a CoinGecko API key?

No. The implemented current and bounded historical workflows use anonymously available public endpoints.

#### Can I search by ticker symbol?

No. CoinGecko IDs are unambiguous and stable for the API workflow. Use IDs such as `bitcoin`, `ethereum`, or `solana`.

#### Can I change the quote currency?

Yes. Set `vsCurrency` to a currency supported by CoinGecko, such as `usd`, `eur`, `gbp`, or `btc`.

#### Can I retrieve a category?

Yes in current mode. Supply an exact CoinGecko category ID such as `decentralized-finance-defi` and optionally choose an order.

#### Can I use the output in a commercial product?

Your downstream rights depend on CoinGecko's terms and your use case. Review the source terms and seek professional advice where appropriate.

#### Does the Actor detect changes between runs?

It produces timestamped snapshots suitable for comparison. Your Task, database, spreadsheet, or automation should compare runs and apply your own thresholds.

### Related automation-lab Actors

- [CoinMarketCap Scraper](https://apify.com/automation-lab/coinmarketcap-scraper) — use a different cryptocurrency market source when your workflow specifically requires CoinMarketCap data.

Choose one source consistently for longitudinal comparisons because provider rankings, methodologies, and timestamps can differ.

# Actor input Schema

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

Current returns one market row per coin. Historical returns daily price, market-cap, and volume observations and requires coin IDs.

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

Optional IDs such as bitcoin, ethereum, or solana. Leave empty in current mode to retrieve the ranked market. Historical mode requires 1–10 IDs.

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

CoinGecko quote currency code, for example usd, eur, gbp, or btc.

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

Optional market filter such as decentralized-finance-defi or layer-1. Used only in current mode.

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

Order used by the current market endpoint.

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

Maximum current rows or historical daily observations saved to the dataset.

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

Number of days requested in historical mode. Daily observations are bounded to 90 days.

## Actor input object example

```json
{
  "mode": "current",
  "coinIds": [
    "bitcoin",
    "ethereum",
    "solana"
  ],
  "vsCurrency": "usd",
  "order": "market_cap_desc",
  "maxItems": 20,
  "historyDays": 7
}
```

# Actor output Schema

## `overview` (type: `string`):

Typed current or historical cryptocurrency market records.

# 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 = {
    "mode": "current",
    "coinIds": [
        "bitcoin",
        "ethereum",
        "solana"
    ],
    "vsCurrency": "usd",
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/coingecko-crypto-market-data").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 = {
    "mode": "current",
    "coinIds": [
        "bitcoin",
        "ethereum",
        "solana",
    ],
    "vsCurrency": "usd",
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/coingecko-crypto-market-data").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 '{
  "mode": "current",
  "coinIds": [
    "bitcoin",
    "ethereum",
    "solana"
  ],
  "vsCurrency": "usd",
  "maxItems": 20
}' |
apify call automation-lab/coingecko-crypto-market-data --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/coingecko-crypto-market-data"
        }
    }
}

```

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/qHSNo5xB5GWbDZkki/builds/0iAak1Aw3aVnUGXxy/openapi.json