# CoinGecko Crypto — Data, Signals & Market Events (`ryanclinton/coingecko-crypto-data`) Actor

Generate crypto market intelligence from CoinGecko: live prices, relative strength, market regime, sector rotation, and automation-ready events across 15,000+ coins and 60+ currencies. Classifies what changed and what's leading, as stable enums. Export JSON, CSV, Excel.

- **URL**: https://apify.com/ryanclinton/coingecko-crypto-data.md
- **Developed by:** [Ryan Clinton](https://apify.com/ryanclinton) (community)
- **Categories:** Developer tools, Automation
- **Stats:** 9 total users, 3 monthly users, 87.7% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 coin fetcheds

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use 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 Data

![CoinGecko Crypto Market Intelligence](https://apifyforge.com/readme-assets/ryanclinton-coingecko-crypto-data/hero.png)

**CoinGecko gives you prices. This actor tells your automation what changed.**

Monitor the entire crypto market, detect regime changes, track sector rotation, identify emerging leaders, and generate automation-ready events from CoinGecko data. Instead of building formulas, thresholds, and alert logic yourself, you get stable classifications, signals, and events that tell your workflows exactly what changed and what deserves attention.

- **What's moving** -- relative strength, composite scores, leaders, performance vs Bitcoin
- **What changed** -- events, alerts, state transitions, regime changes
- **What deserves attention** -- opportunities, sector rotation, anomalies
- **What's happened over time** -- watchlists, lifetime stats, leadership history

No spreadsheets. No formulas. No custom alert logic. 15,000+ cryptocurrencies, 60+ currencies, one free API key. (Descriptive classification of observed data, not financial advice.)

**Built for:** Apify • Make • Zapier • Dify • n8n • Google Sheets • Airtable • Slack

---

### Why not just call CoinGecko directly?

CoinGecko returns raw numbers you still have to interpret:

```json
{ "priceChange24h": 6.4, "priceChange7d": 18.2, "priceChange30d": 41.7 }
````

This actor returns something your automation can act on:

```json
{
    "marketState": "strong-uptrend",
    "signalQuality": "high",
    "relativeStrength": { "rating": "elite" },
    "benchmarkComparison": { "context": "outperforming-both" },
    "leadershipStage": "accelerating",
    "scoreDrivers": ["elite-relative-strength", "aligned-uptrend", "outperforming-both"],
    "events": ["relative-strength-upgrade", "entered-top-25"]
}
```

CoinGecko gives you data. This actor gives your workflow something to branch on -- so you no longer need CoinGecko API + Google Sheets + 20 formulas + Zapier filters + custom logic. The actor already did that work.

***

![What you get: events, strength vs Bitcoin, sector rotation, watchlist memory](https://apifyforge.com/readme-assets/ryanclinton-coingecko-crypto-data/feature-callouts.png)

### How does it compare?

| Capability | CoinGecko API | Typical CoinGecko actor | This actor |
|---|:---:|:---:|:---:|
| Prices + market rankings | Yes | Yes | Yes |
| Relative strength + composite scoring | No | No | Yes |
| Benchmark vs Bitcoin + market | No | No | Yes |
| Market regime + health detection | No | No | Yes |
| Sector rotation | No | No | Yes |
| Watchlist memory + lifetime stats | No | No | Yes |
| Event + alert generation | No | No | Yes |
| Opportunity + anomaly detection | No | No | Yes |
| Automation-ready stable enums | No | No | Yes |

***

### Who is this for?

- Make / Zapier / n8n users building crypto workflows without spreadsheet formulas
- Dify and AI agents that need stable enums to branch on, not raw percentages to recalculate
- Analysts monitoring market-regime changes and sector rotation
- Portfolio dashboards that need change detection across scheduled runs

**Not for** users who only need a single current price. If you just want BTC's price right now, call CoinGecko directly. If you need to know **what changed and why it matters**, use this actor.

***

### What this replaces

Without this actor, the typical crypto-monitoring stack is:

```text
CoinGecko API -> Google Sheets -> ranking formulas -> relative-strength math
            -> breadth calculations -> Zapier filters -> custom alert logic
```

With this actor:

```text
CoinGecko API -> This actor -> your automation
```

The ranking, relative strength, breadth, regime detection, and alert logic already ran inside the actor. You wire the output straight into Slack, a sheet, or an agent.

***

### Questions this actor answers

- **Can I find coins outperforming Bitcoin?** Yes -- filter `benchmarkComparison.context = 'outperforming-btc'` (or `outperforming-both`).
- **Can I detect market regime changes?** Yes -- branch on `WHERE event = 'market-regime-change'`.
- **Can I monitor sector rotation?** Yes -- `sectors` mode emits a `recordType: rotation` record naming what capital is moving into and out of.
- **Can I identify emerging leaders?** Yes -- filter `WHERE opportunityType = 'emerging-leader'`.
- **Can I see which market state a coin is in?** Yes -- `marketSignals.marketState` (`strong-uptrend | downtrend | volatile | ...`), with `signalQuality` confidence.
- **Can I detect watchlist changes automatically?** Yes -- schedule with a `watchlistName`; each coin then carries a `change` block plus events like `entered-top-25` and `leadership-transition`.
- **Can I track a coin's history over time?** Yes -- `lifetimeStats` accumulates rank, leadership, and composite history across runs.
- **Can I do all this without building formulas or alert thresholds?** Yes -- every signal is a stable enum your workflow branches on directly.

***

### What can you build?

Each of these is a scheduled run plus one filter -- no formulas, no threshold logic:

| Build this | How |
|---|---|
| **Market health monitor** | `mode: market`, `watchlistName: top100` -> alert on `WHERE event = 'market-regime-change'` |
| **Emerging leader scanner** | alert on `WHERE recordType = 'opportunity' AND opportunityType = 'emerging-leader'` |
| **Sector rotation dashboard** | `mode: sectors` -> track `WHERE recordType = 'rotation'` |
| **Relative-strength screener** | filter `WHERE relativeStrength.rating = 'elite' AND benchmarkComparison.context = 'outperforming-both'` |
| **Portfolio change detection** | schedule hourly with a `watchlistName` -> receive `entered-uptrend`, `leadership-transition`, `entered-top-25` events automatically |

#### Example: detect an emerging leader

Input:

```json
{ "mode": "market", "maxResults": 100 }
```

The actor surfaces an opportunity record:

```json
{
    "recordType": "opportunity",
    "coinId": "render-token",
    "symbol": "RNDR",
    "opportunityType": "emerging-leader",
    "relativeStrengthRating": "elite",
    "compositeScore": 88,
    "reason": "Smaller-cap (rank 73) with elite relative strength and up momentum"
}
```

Your automation:

```text
IF opportunityType = emerging-leader THEN send Slack alert
```

No spreadsheets. No formulas. No thresholds. No custom code.

***

### Built for automation: stable enums

Every classification is a **stable enum** -- additive within a major version, never renamed -- so your workflows branch on fixed values instead of recalculating percentages:

- `marketState`: `strong-uptrend | uptrend | consolidating | downtrend | strong-downtrend | volatile`
- `marketRegime`: `risk-on | risk-off | broad-rally | broad-selloff | large-cap-led | neutral`
- `benchmarkComparison.context`: `outperforming-both | outperforming-market | outperforming-btc | underperforming-...`
- `opportunityType`: `emerging-leader | momentum-reversal | strong-recovery | low-vol-breakout`
- `event`: `market-regime-change | leadership-transition | entered-top-25 | signal-strengthened | ...`

`WHERE event = 'market-regime-change'` beats `IF breadthScore > 62 AND marketHealth > 71 AND ...` in every automation tool.

***

### What the output looks like

![Sample output: decision-shaped records with composite score, benchmark context, leadership stage, and events](https://apifyforge.com/readme-assets/ryanclinton-coingecko-crypto-data/output-table.png)

**Market Leaders** (market mode, sorted by composite score):

| Coin | Score | Context | Stage | vs BTC 24h |
|---|---|---|---|---|
| SOL | 92 | outperforming-both | leader | +4.8 |
| TAO | 89 | outperforming-both | accelerating | +6.1 |
| RNDR | 81 | outperforming-market | emerging | -0.4 |

**Watchlist Monitor** (scheduled watchlist run -- what changed since last run):

| Coin | Event | Rank change |
|---|---|---|
| SOL | entered-top-25 | +6 |
| TAO | leadership-transition | +2 |
| RNDR | signal-strengthened | +14 |

**Market Health** (one `market-summary` record):

| Metric | Value |
|---|---|
| Regime | risk-on |
| Health | 72 |
| Participation | broad |
| Breadth | 64 |

***

### Key features

Under the hood it's **four systems** on top of CoinGecko data, plus the raw data modes. Every signal is a stable enum or number you can branch on, and it's all descriptive classification of observed data -- never financial advice.

![Intelligence stack: CoinGecko data through signals, strength, composite, internals, discovery, and watchlist memory to automation-ready output](https://apifyforge.com/readme-assets/ryanclinton-coingecko-crypto-data/intelligence-layers.png)

**Data foundation**

- **Seven modes** -- market rankings, price lookups, trending coins, global stats, search, historical charts, and sector overview, across 15,000+ coins and 60+ currencies.
- **Full coverage** -- supply + ATH/ATL metrics, BTC/ETH market dominance, 5-minute-to-daily historical time series, a `category` filter (e.g. `artificial-intelligence`), and a no-key dry-run mode.

#### 1. Intelligence -- turn numbers into classifications

- **Market signals** -- per coin: `marketState` (`strong-uptrend | downtrend | volatile | ...`), momentum band per timeframe, trend alignment, volatility level, liquidity tier, drawdown from ATH.
- **Relative strength** -- `relativeStrength` percentile within the cohort + a `rating` (`elite | strong | average | weak | lagging`).
- **Composite score** -- one sortable `compositeScore` (0-100) + `compositeRating` (`A+..D`) blending strength, momentum, trend, and ATH positioning.
- **Benchmark context** -- `benchmarkComparison` (vs Bitcoin and vs the market) collapsed into one branchable `context` enum (`outperforming-both | outperforming-market | outperforming-btc | underperforming-...`). The question pros ask: "did it beat BTC?"
- **Leadership stage** -- `leadershipStage` (`emerging → accelerating → leader → exhausting → declining`) adds *direction* to the rating.
- **Market internals** -- the `market-summary` carries `marketRegime`, `breadthScore`, `marketHealth`, and `leadershipConcentration` + `participationQuality` (`broad | healthy | narrow | fragile`) -- is the rally real, or just the top 10?

#### 2. Monitoring -- alert on the change, not the snapshot

- **Cross-run state** -- set a `watchlistName`, schedule the actor, and each coin gets a `change` block (status, % move since last run, momentum shift) with no external state.
- **State machine** -- `stateTransition` (`consolidating-to-uptrend`) so you alert on the transition.
- **Events + alerts** -- a stable per-coin `events` array and separate `recordType: alert` records, so automation fires on `WHERE recordType = 'alert'` instead of `IF a AND b AND c`.
- **Market events** -- run-level `recordType: event` records (`market-regime-change`, `breadth-expansion`, `market-health-declined`) for `WHERE event = 'market-regime-change'`.

#### 3. Discovery -- surface what to look at

- **Opportunities** -- `recordType: opportunity` records (`emerging-leader`, `momentum-reversal`, `strong-recovery`, `low-vol-breakout`) with the driving metric + reason.
- **Screens** -- the `market-summary` bundles eight ready-made screens over the cohort (near-ATH, high-momentum, deep-value, volume-leaders, and the four above).
- **Sector rotation** -- `sectors` mode on a watchlist emits a `recordType: rotation` record (`rotatingInto` / `rotatingOutOf` + `strengthDelta`) and per-sector `sectorStatus` (`persistent-leader | new-leader | improving | deteriorating`).
- **Anomalies** -- an `anomalies` array flags cross-signal divergences (`momentum-strength-divergence`, `benchmark-split`) -- what's *unusual*, not just what's strong.
- **History analytics** -- per-coin `trendStrength`, `trendQuality` (`smooth | explosive | choppy | unstable`), `realizedVolatility`, and `maxDrawdown`.

#### 4. Persistent intelligence -- gets smarter every run (the moat)

The first run gives you a snapshot. The hundredth run gives you history. Competitors can copy today's calculations in a weekend, but they cannot copy six months of accumulated watchlist intelligence -- because that requires state, run after run.

- **Lifetime stats** -- watchlist coins carry `lifetimeStats` (first seen, runs/days tracked, best/worst rank ever, highest/average composite score, leadership consistency) that gets richer every run.
- **Rank movement** -- `change.rankChange` plus `entered-top-100 / 50 / 25 / 10` events.
- **Leadership history** -- `leaderRuns` + `leadership-transition` events track how long a coin has led.

Every record carries a `recordType` discriminator and `schemaVersion`, and the dataset ships decision-first views (Market Signals, Market Leaders, Recovery, Watchlist Monitor).

***

### How to use CoinGecko Crypto Data

1. **Get a free CoinGecko API key.** Sign up at [coingecko.com/en/api](https://www.coingecko.com/en/api) for a free Demo account. Copy your API key from the dashboard.
2. **Open the actor on Apify.** Navigate to [CoinGecko Crypto Data](https://apify.com/ryanclinton/coingecko-crypto-data) on the Apify platform and click "Try for free".
3. **Enter your API key.** Paste the CoinGecko Demo API key into the "CoinGecko API Key" field.
4. **Select a data mode.** Choose one of seven modes: Market Rankings, Price Lookup, Trending Coins, Global Market Stats, Search Coins, Historical Price Chart, or Sector Overview.
5. **Configure mode-specific options.** For price lookups and historical data, enter coin IDs (e.g., `bitcoin`, `ethereum`). For search, enter a search term. For history, set the number of days.
6. **Run the actor.** Click "Start" or trigger a run via the Apify API. Most modes complete in under 30 seconds.
7. **Download or integrate results.** Export the dataset as JSON, CSV, or Excel. Use the Apify API, webhooks, or integrations to automate data collection on a schedule.

***

### Input parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `apiKey` | String | No | -- | Free CoinGecko Demo API key from [coingecko.com/en/api](https://www.coingecko.com/en/api). Without a key, the actor runs in dry-run mode. |
| `mode` | String | No | `market` | Data mode: `market` (top coins by market cap), `price` (specific coin prices), `trending` (24h trending), `global` (market-wide stats), `search` (find coins), `history` (historical charts), `sectors` (top categories by market cap, ranked by 24h move). |
| `coinIds` | String\[] | No | -- | CoinGecko coin IDs for `price` and `history` modes (e.g., `bitcoin`, `ethereum`, `solana`). |
| `searchQuery` | String | No | -- | Search term for `search` mode (e.g., "bitcoin", "defi", "layer 2"). |
| `vsCurrency` | String | No | `usd` | Price currency. Supports 60+ fiat currencies (`usd`, `eur`, `gbp`, `jpy`) and crypto pairs (`btc`, `eth`). |
| `days` | String | No | `30` | Number of days for `history` mode. Accepted: `1`, `7`, `14`, `30`, `90`, `180`, `365`, `max`. |
| `maxResults` | Integer | No | `100` | Maximum coins to return in `market`/`search` modes, or sectors in `sectors` mode (top N by market cap; 1-250). |
| `category` | String | No | -- | Optional CoinGecko category id to filter `market` mode to one sector (e.g. `artificial-intelligence`, `layer-2`, `meme-token`, `gaming`). Find ids at [coingecko.com/en/categories](https://www.coingecko.com/en/categories). |
| `watchlistName` | String | No | -- | Optional. Set a name to track changes across runs in `market`/`price`/`trending` mode. Each coin then gets a `change` block comparing it to the previous run on the same watchlist. Leave blank for a one-off snapshot. |

#### Input example

```json
{
    "apiKey": "CG-xxxxxxxxxxxxxxxxxxxx",
    "mode": "market",
    "vsCurrency": "usd",
    "maxResults": 50
}
```

#### Tips for best results

- **Use "search" mode first to find coin IDs.** CoinGecko uses unique lowercase IDs (e.g., `bitcoin`, `binancecoin`, `matic-network`). If you are unsure of the exact ID, run a search first.
- **Start with 30-day history and expand.** The default 30-day range returns daily data points and is fast to retrieve. Only request `365` or `max` when you specifically need long-term data.
- **Choose currencies wisely.** If you report in EUR or GBP, set `vsCurrency` accordingly instead of converting USD values manually.
- **Combine market and trending modes.** Run `market` for fundamentals, then `trending` for momentum. Cross-reference to find coins with both strong market position and rising interest.

***

### Output

#### Schema highlights

Every record carries a `recordType` discriminator and a `schemaVersion`. The record types are:

`coin` · `market-summary` · `history-summary` · `watchlist-summary` · `sector` · `sector-summary` · `opportunity` · `event` · `rotation` · `alert` · `global` · `error`

Apify renders the full field-by-field descriptions in the dataset's **Output** tab (from `dataset_schema.json`), and the dataset ships decision-first views: Market Signals, Market Leaders, Recovery, Watchlist Monitor. The examples below show each record shape; skip to [How to use](#how-to-use-coingecko-crypto-data) if you just want to run it.

#### Output example

**Market mode (default):**

```json
{
    "recordType": "coin",
    "schemaVersion": "1.1.0",
    "coinId": "bitcoin",
    "name": "Bitcoin",
    "symbol": "BTC",
    "currentPrice": 97432.18,
    "marketCap": 1932845672310,
    "marketCapRank": 1,
    "volume24h": 28456789012,
    "priceChange24h": 2.34,
    "priceChange7d": -1.87,
    "priceChange30d": 12.56,
    "circulatingSupply": 19832456,
    "totalSupply": 21000000,
    "maxSupply": 21000000,
    "allTimeHigh": 108135.82,
    "allTimeHighDate": "2025-01-20T09:15:42.123Z",
    "allTimeLow": 67.81,
    "allTimeLowDate": "2013-07-06T00:00:00.000Z",
    "imageUrl": "https://assets.coingecko.com/coins/images/1/large/bitcoin.png",
    "currency": "usd",
    "extractedAt": "2025-05-12T10:30:00.000Z",
    "marketSignals": {
        "marketState": "uptrend",
        "momentum24h": "flat",
        "momentum7d": "flat",
        "momentum30d": "rising",
        "trendAlignment": "mixed",
        "volatilityLevel": "moderate",
        "volumeToMarketCap": 0.0147,
        "liquidityTier": "low",
        "drawdownFromAth": 0.0989,
        "athProximity": "below-ath",
        "recoveryFromAtl": 1436.84,
        "signalQuality": "medium",
        "signalSummary": "+2.3% in 24h (flat); mixed across timeframes; 10% below all-time high."
    },
    "relativeStrength": {
        "strength24hPercentile": 64,
        "strength7dPercentile": 41,
        "strength30dPercentile": 78,
        "rating": "strong"
    },
    "benchmarkComparison": {
        "vsBitcoin24h": 1.9,
        "vsBitcoin7d": -0.6,
        "vsBitcoin30d": 8.4,
        "vsMarket24h": 0.9,
        "vsMarket7d": -3.2,
        "vsMarket30d": 5.1,
        "relativeLeader": true,
        "context": "outperforming-both"
    },
    "compositeScore": 71,
    "compositeRating": "B",
    "leadershipStage": "accelerating",
    "anomalies": [],
    "scoreDrivers": ["strong-relative-strength", "up-momentum", "outperforming-both", "leadership-accelerating"]
}
```

**Market summary record (appended once per market / multi-coin price run):**

```json
{
    "recordType": "market-summary",
    "schemaVersion": "1.1.0",
    "coinsAnalyzed": 100,
    "advancers": 63,
    "decliners": 34,
    "unchanged": 3,
    "breadthSignal": "advance",
    "breadthScore": 61,
    "above30dTrend": 58,
    "below30dTrend": 42,
    "nearAthCount": 7,
    "deepDrawdownCount": 19,
    "marketRegime": "risk-on",
    "regimeReason": "63% of coins advancing.",
    "marketHealth": 64,
    "marketHealthState": "healthy",
    "leadershipConcentration": 38,
    "participationQuality": "broad",
    "strongestCoin": { "coinId": "examplecoin", "symbol": "EXA", "compositeScore": 94 },
    "largestRankMover": { "coinId": "samplecoin", "symbol": "SMP", "rankChange": 16 },
    "avgChange24h": 1.42,
    "medianChange24h": 0.88,
    "momentumDistribution": { "surging": 4, "rising": 22, "flat": 41, "falling": 28, "plunging": 5, "unknown": 0 },
    "topGainers": [{ "coinId": "examplecoin", "symbol": "EXA", "priceChange24h": 34.2 }],
    "topLosers": [{ "coinId": "samplecoin", "symbol": "SMP", "priceChange24h": -21.7 }],
    "screens": {
        "nearAth": [{ "coinId": "examplecoin", "symbol": "EXA", "metric": 0.02 }],
        "highMomentum": [{ "coinId": "examplecoin", "symbol": "EXA", "metric": 41.8 }],
        "deepValue": [{ "coinId": "samplecoin", "symbol": "SMP", "metric": 0.94 }],
        "volumeLeaders": [{ "coinId": "examplecoin", "symbol": "EXA", "metric": 0.31 }],
        "emergingLeaders": [{ "coinId": "examplecoin", "symbol": "EXA", "metric": 12.4 }],
        "momentumReversals": [{ "coinId": "samplecoin", "symbol": "SMP", "metric": 4.6 }],
        "strongRecoveries": [{ "coinId": "samplecoin", "symbol": "SMP", "metric": 9.1 }],
        "lowVolBreakouts": [{ "coinId": "examplecoin", "symbol": "EXA", "metric": 6.2 }]
    },
    "summary": "100 coins: 63 up / 34 down (advance, regime risk-on, health 64/healthy), avg 24h 1.42%.",
    "currency": "usd",
    "extractedAt": "2025-05-12T10:30:00.000Z"
}
```

**Global mode:**

```json
{
    "recordType": "global",
    "schemaVersion": "1.1.0",
    "activeCryptocurrencies": 15832,
    "markets": 1143,
    "totalMarketCap": 3245678901234,
    "totalVolume24h": 98765432100,
    "btcDominance": 58.42,
    "ethDominance": 11.23,
    "marketCapChangePercentage24h": 1.87,
    "marketCapTrend": "flat",
    "summary": "Total market cap +1.87% in 24h (flat); BTC dominance 58.4%, ETH 11.2%.",
    "extractedAt": "2025-05-12T10:30:00.000Z"
}
```

**History mode** (one `history-summary` per coin, then the raw points):

```json
{
    "recordType": "history-summary",
    "schemaVersion": "1.1.0",
    "coinId": "ethereum",
    "periodDays": "30",
    "dataPoints": 30,
    "startPrice": 2980.11,
    "endPrice": 3245.67,
    "changePct": 8.91,
    "high": 3401.22,
    "low": 2890.45,
    "rangePct": 16.4,
    "volatilityLevel": "moderate",
    "realizedVolatility": 2.13,
    "trendStrength": 74,
    "trendQuality": "smooth",
    "maxDrawdown": 14.8,
    "trendConsistency": 68,
    "direction": "up",
    "summary": "ethereum +8.91% over 30d (up), trend strength 74/100 (smooth), max drawdown 14.8%, moderate volatility.",
    "currency": "usd",
    "extractedAt": "2025-05-12T10:30:00.000Z"
}
```

**Sector overview** (`sectors` mode -- one `sector` record per category, then a `sector-summary`):

```json
{
    "recordType": "sector",
    "schemaVersion": "1.1.0",
    "sectorId": "artificial-intelligence",
    "name": "Artificial Intelligence (AI)",
    "marketCap": 38450000000,
    "volume24h": 4120000000,
    "marketCapChange24h": 6.84,
    "sectorState": "rising",
    "sectorMomentumRank": 1,
    "sectorStatus": "persistent-leader",
    "topCoins": ["https://.../render.png", "https://.../fet.png", "https://.../tao.png"],
    "extractedAt": "2025-05-12T10:30:00.000Z"
}
```

```json
{
    "recordType": "sector-summary",
    "schemaVersion": "1.1.0",
    "sectorsAnalyzed": 312,
    "advancingSectors": 188,
    "decliningSectors": 124,
    "avgChange24h": 1.12,
    "topSector": { "name": "Artificial Intelligence (AI)", "marketCapChange24h": 6.84 },
    "weakestSector": { "name": "Gaming (GameFi)", "marketCapChange24h": -4.31 },
    "summary": "312 sectors: 188 up / 124 down. Strongest Artificial Intelligence (AI) (+6.84%), weakest Gaming (GameFi) (-4.31%).",
    "extractedAt": "2025-05-12T10:30:00.000Z"
}
```

**Alert record** (`recordType: alert`, watchlist mode -- one per coin with a triggered event, for `WHERE recordType = 'alert'` routing):

```json
{
    "recordType": "alert",
    "schemaVersion": "1.1.0",
    "coinId": "solana",
    "name": "Solana",
    "symbol": "SOL",
    "alertType": "entered-uptrend",
    "events": ["entered-uptrend", "sharp-gain"],
    "currentPrice": 168.42,
    "priceChangePctVsLast": 11.3,
    "marketState": "strong-uptrend",
    "message": "SOL entered an uptrend",
    "watchlistName": "daily-top50",
    "currency": "usd",
    "extractedAt": "2025-05-12T10:30:00.000Z"
}
```

**Opportunity record** (`recordType: opportunity`, market mode -- the "discover" surface):

```json
{
    "recordType": "opportunity",
    "schemaVersion": "1.1.0",
    "coinId": "examplecoin",
    "name": "Example Coin",
    "symbol": "EXA",
    "opportunityType": "emerging-leader",
    "metric": 12.4,
    "currentPrice": 3.42,
    "marketState": "strong-uptrend",
    "compositeScore": 88,
    "relativeStrengthRating": "elite",
    "reason": "Smaller-cap (rank 73) with elite relative strength and up momentum",
    "currency": "usd",
    "extractedAt": "2025-05-12T10:30:00.000Z"
}
```

**Market event record** (`recordType: event`, market + watchlist -- run-level state changes for `WHERE event = '...'` routing):

```json
{
    "recordType": "event",
    "schemaVersion": "1.1.0",
    "event": "market-regime-change",
    "from": "risk-off",
    "to": "risk-on",
    "delta": null,
    "message": "Market regime changed: risk-off → risk-on",
    "currency": "usd",
    "extractedAt": "2025-05-12T10:30:00.000Z"
}
```

**Sector rotation record** (`recordType: rotation`, `sectors` mode + watchlist):

```json
{
    "recordType": "rotation",
    "schemaVersion": "1.1.0",
    "rotatingInto": { "name": "Artificial Intelligence (AI)", "strengthDelta": 5.2 },
    "rotatingOutOf": { "name": "Gaming (GameFi)", "strengthDelta": -3.8 },
    "topMovers": [
        { "name": "Artificial Intelligence (AI)", "strengthDelta": 5.2 },
        { "name": "Gaming (GameFi)", "strengthDelta": -3.8 }
    ],
    "message": "Capital rotating into Artificial Intelligence (AI) (+5.2) and out of Gaming (GameFi) (-3.8) since last run.",
    "extractedAt": "2025-05-12T10:30:00.000Z"
}
```

```json
{
    "coinId": "ethereum",
    "date": "2025-05-01T00:00:00.000Z",
    "price": 3245.67,
    "marketCap": 390123456789,
    "volume": 12345678901,
    "currency": "usd"
}
```

**Cross-run `change` block** (added to each coin when `watchlistName` is set):

```json
{
    "status": "up",
    "priceChangePctVsLast": 2.81,
    "momentumShift": true,
    "shift": "flat-to-rising",
    "events": ["entered-uptrend", "entered-top-25"],
    "rankChange": 6,
    "upRuns": 3,
    "downRuns": 0,
    "previousPrice": 94772.40,
    "previousMomentum": "flat",
    "lastSeenAt": "2025-05-11T10:30:00.000Z"
}
```

Each watchlist coin also carries a `lifetimeStats` block (accumulates across runs) and a `stateTransition` block:

```json
{
    "lifetimeStats": {
        "firstSeenAt": "2025-04-20T10:30:00.000Z",
        "runsSeen": 22,
        "daysTracked": 22,
        "highestObservedPrice": 109840.00,
        "pctFromObservedHigh": -11.3,
        "bestObservedRank": 1,
        "worstObservedRank": 1,
        "leaderRuns": 22,
        "leadershipConsistency": 100,
        "highestCompositeScore": 96,
        "averageCompositeScore": 81
    },
    "stateTransition": {
        "currentState": "uptrend",
        "previousState": "consolidating",
        "transition": "consolidating-to-uptrend"
    }
}
```

**Watchlist summary record** (`recordType: watchlist-summary`) -- one per watchlist run, a portfolio-style read of the tracked set:

```json
{
    "recordType": "watchlist-summary",
    "schemaVersion": "1.1.0",
    "watchlistName": "daily-top50",
    "coinsTracked": 50,
    "newCoins": 0,
    "gainers": 31,
    "losers": 17,
    "averageMove": 1.84,
    "strongest": { "coinId": "examplecoin", "symbol": "EXA", "priceChangePctVsLast": 12.4 },
    "weakest": { "coinId": "samplecoin", "symbol": "SMP", "priceChangePctVsLast": -8.9 },
    "longestUpStreak": { "coinId": "examplecoin", "symbol": "EXA", "upRuns": 6 },
    "summary": "Watchlist \"daily-top50\": 31 up / 17 down since last run, avg move 1.84%, strongest EXA +12.4%.",
    "currency": "usd",
    "extractedAt": "2025-05-12T10:30:00.000Z"
}
```

**Error record** (`recordType: error`) -- the run still exits successfully so a CoinGecko outage or a bad input never counts against the actor's success rate. Branch on `failureType` to tell "no data" from "the request failed":

```json
{
    "recordType": "error",
    "error": true,
    "failureType": "invalid-input",
    "message": "Coin IDs are required for price mode (e.g. [\"bitcoin\",\"ethereum\"])",
    "timestamp": "2025-05-12T10:30:00.000Z"
}
```

`failureType` is a stable enum: `invalid-input` | `timeout` | `parse-error` | `api-error` | `no-data`.

**Run summary in the key-value store.** Every run also writes a `SUMMARY` record to the default key-value store with `{ mode, vsCurrency, resultCount, watchlistName, schemaVersion, completedAt }` -- a one-glance run stat for dashboards without parsing the dataset.

#### Monitoring behaviour (watchlist runs)

- **First run on a new `watchlistName`** marks every coin `change.status: "new"` with null deltas (logged explicitly). Diffs activate from the second run onward.
- **Second run and later** compare against the previous run on the same watchlist and populate the full `change` block.
- State is stored in a named key-value store (`coingecko-watchlist-<name>`), bounded to 5,000 coins (FIFO), so scheduled runs never grow it without limit.

#### Output fields

**Market / Price / Trending / Search modes (CoinOutput):**

| Field | Type | Description |
|---|---|---|
| `coinId` | String | CoinGecko unique identifier (e.g., `bitcoin`) |
| `name` | String | Full coin name (e.g., `Bitcoin`) |
| `symbol` | String | Ticker symbol in uppercase (e.g., `BTC`) |
| `currentPrice` | Number | Current price in the selected currency |
| `marketCap` | Number | Total market capitalization |
| `marketCapRank` | Number | Rank by market cap (1 = largest) |
| `volume24h` | Number | 24-hour trading volume |
| `priceChange24h` | Number | 24-hour price change percentage |
| `priceChange7d` | Number | 7-day price change percentage (market mode only) |
| `priceChange30d` | Number | 30-day price change percentage (market mode only) |
| `circulatingSupply` | Number | Coins currently in circulation |
| `totalSupply` | Number | Total coins that exist (including locked) |
| `maxSupply` | Number | Maximum coins that will ever exist |
| `allTimeHigh` | Number | All-time high price |
| `allTimeHighDate` | String | ISO date of all-time high |
| `allTimeLow` | Number | All-time low price |
| `allTimeLowDate` | String | ISO date of all-time low |
| `imageUrl` | String | URL to the coin logo image |
| `currency` | String | Currency code used for prices |
| `extractedAt` | String | ISO timestamp of data extraction |
| `recordType` | String | Always `coin` for these records. Discriminator for filtering/views. |
| `schemaVersion` | String | Output schema version of the interpretation layer (semver). |
| `marketSignals` | Object | Descriptive market-signal block (see below). Present on `market`/`price`/`trending` records; absent on `search` (no price data). |
| `relativeStrength` | Object | Cohort-relative percentile ranking (`strength24h/7d/30dPercentile` + `rating`: elite/strong/average/weak/lagging). Present on market / multi-coin price runs of >=5 coins. |
| `benchmarkComparison` | Object | Performance vs Bitcoin and vs the cohort (`vsBitcoin24h/7d/30d`, `vsMarket24h/7d/30d`, `relativeLeader`, `context` enum). Present on market / multi-coin price runs. |
| `compositeScore` | Number | 0-100 descriptive composite of relative strength + momentum + trend + ATH positioning. Not a buy signal. |
| `compositeRating` | String | Letter grade of `compositeScore`: `A+ \| A \| B \| C \| D`. Descriptive strength grade. |
| `leadershipStage` | String | Leadership-lifecycle stage: `emerging \| accelerating \| leader \| exhausting \| declining \| none`. |
| `anomalies` | Array | Cross-signal divergence flags (`momentum-strength-divergence`, `benchmark-split`). Empty when none. |
| `scoreDrivers` | Array | Plain-enum explanation of the classification (`elite-relative-strength`, `aligned-uptrend`, `outperforming-both`, `leadership-accelerating`, ...). Explains the score without an LLM. |
| `lifetimeStats` | Object | Accumulated per-coin watchlist memory (`firstSeenAt`, `runsSeen`, `daysTracked`, `highestObservedPrice`, `pctFromObservedHigh`, `bestObservedRank`, `worstObservedRank`, `leaderRuns`, `leadershipConsistency`, `highestCompositeScore`, `averageCompositeScore`). Present in watchlist mode. |
| `stateTransition` | Object | Market-state machine (`currentState`, `previousState`, `transition`). Present in watchlist mode. |
| `change` | Object | Cross-run change block. Present only when `watchlistName` is set. |

**`marketSignals` sub-fields (descriptive, never advice):** `marketState` (`strong-uptrend` | `uptrend` | `consolidating` | `downtrend` | `strong-downtrend` | `volatile`), `momentum24h/7d/30d` (`surging` >=20% | `rising` >=5% | `flat` | `falling` <=-5% | `plunging` <=-20%), `trendAlignment` (`aligned-up` | `aligned-down` | `mixed` | `insufficient-data`), `volatilityLevel` (`low` | `moderate` | `high` | `extreme`), `volumeToMarketCap` (Number) + `liquidityTier` (`very-high`..`low`), `drawdownFromAth` (0-1) + `athProximity` (`at-or-near-ath` | `below-ath` | `well-below-ath` | `far-below-ath`), `recoveryFromAtl` (Number), `signalQuality` (`high` | `medium` | `low`, timeframe-agreement confidence), `signalSummary` (paste-ready String). See the dataset's Output tab for the full per-field descriptions.

**`change` sub-fields (watchlist mode only):** `status` (`new` | `up` | `down` | `stable`), `priceChangePctVsLast` (Number), `momentumShift` (Boolean), `shift` (String, e.g. `flat-to-rising`, or null), `events` (Array of stable enums: `entered-uptrend` | `entered-downtrend` | `momentum-surge` | `sharp-gain` | `sharp-drop` | `new-observed-high` | `relative-strength-upgrade` | `relative-strength-downgrade` | `entered-top-10/25/50/100` | `exited-top-10` | `leadership-transition` | `signal-strengthened` | `signal-weakened`), `rankChange` (Number, prior rank minus current rank), `upRuns` / `downRuns` (Number, consecutive same-direction runs), `previousPrice` (Number), `previousMomentum` (String), `lastSeenAt` (String).

**Market summary record (`recordType: market-summary`):** `coinsAnalyzed`, `advancers`, `decliners`, `unchanged` (Number); `breadthSignal` (`broad-advance` | `advance` | `mixed` | `decline` | `broad-decline`); `breadthScore` (0-100); `above30dTrend`, `below30dTrend`, `nearAthCount`, `deepDrawdownCount` (Number); `marketRegime` (`broad-rally` | `risk-on` | `large-cap-led` | `neutral` | `risk-off` | `broad-selloff`); `regimeReason` (String); `marketHealth` (0-100); `marketHealthState` (`very-weak` | `weak` | `neutral` | `healthy` | `strong`); `leadershipConcentration` (0-100, % of up-move from top 10); `participationQuality` (`broad` | `healthy` | `narrow` | `fragile`); `strongestCoin`, `largestRankMover` (Object or null); `avgChange24h`, `medianChange24h` (Number); `momentumDistribution` (Object); `topGainers`, `topLosers` (Array); `screens` (Object: `nearAth` / `highMomentum` / `deepValue` / `volumeLeaders` / `emergingLeaders` / `momentumReversals` / `strongRecoveries` / `lowVolBreakouts`, each top-5 `{coinId, symbol, metric}`); `summary` (String).

**History summary record (`recordType: history-summary`):** `coinId`, `periodDays`; `dataPoints`, `startPrice`, `endPrice`, `changePct`, `high`, `low`, `rangePct` (Number); `volatilityLevel` (String); `realizedVolatility` (Number, std of per-interval log returns %); `trendStrength` (0-100, linear-fit R²); `trendQuality` (`smooth` | `explosive` | `choppy` | `unstable`); `maxDrawdown` (Number, worst peak-to-trough %); `trendConsistency` (0-100, share of intervals moving with the overall direction); `direction` (`up` | `down` | `flat`); `summary` (String).

**Watchlist summary record (`recordType: watchlist-summary`):** `watchlistName`, `coinsTracked`, `newCoins`, `gainers`, `losers` (Number); `averageMove` (Number); `strongest`, `weakest`, `longestUpStreak` (Object or null); `summary` (String). Emitted once per watchlist run.

**Sector records (`sectors` mode):** `sector` records carry `sectorId`, `name`, `marketCap`, `volume24h`, `marketCapChange24h`, `sectorState` (momentum band), `sectorMomentumRank` (1 = strongest), `sectorStatus` (`persistent-leader` | `new-leader` | `improving` | `deteriorating` | `stable`, watchlist mode), `topCoins` (Array). The `sector-summary` carries `sectorsAnalyzed`, `advancingSectors`, `decliningSectors`, `avgChange24h`, `topSector`, `weakestSector`, `summary`.

**Alert records (`recordType: alert`, watchlist mode):** `coinId`, `name`, `symbol`, `alertType` (the primary triggered event), `events` (Array), `currentPrice`, `priceChangePctVsLast`, `marketState`, `message` (paste-ready), `watchlistName`.

**Opportunity records (`recordType: opportunity`, market mode):** `coinId`, `name`, `symbol`, `opportunityType` (`emerging-leader` | `momentum-reversal` | `strong-recovery` | `low-vol-breakout`), `metric`, `currentPrice`, `marketState`, `compositeScore`, `relativeStrengthRating`, `reason` (plain-English).

**Market event records (`recordType: event`, market + watchlist):** `event` (`market-regime-change` | `market-health-improved` | `market-health-declined` | `breadth-expansion` | `breadth-contraction`), `from`, `to`, `delta`, `message`.

**Sector rotation record (`recordType: rotation`, `sectors` mode + watchlist):** `rotatingInto`, `rotatingOutOf` (`{name, strengthDelta}` or null), `topMovers` (Array), `message`.

**Global mode (GlobalData):**

| Field | Type | Description |
|---|---|---|
| `activeCryptocurrencies` | Number | Total active cryptocurrencies tracked |
| `markets` | Number | Number of exchanges tracked |
| `totalMarketCap` | Number | Total crypto market capitalization |
| `totalVolume24h` | Number | 24-hour total trading volume |
| `btcDominance` | Number | Bitcoin market cap dominance percentage |
| `ethDominance` | Number | Ethereum market cap dominance percentage |
| `marketCapChangePercentage24h` | Number | 24-hour market cap change percentage |
| `marketCapTrend` | String | Momentum band of the 24h market-cap move (`surging` ... `plunging`). |
| `summary` | String | Factual one-line description of the global state. |
| `extractedAt` | String | ISO timestamp of data extraction |

**History mode (HistoryPoint):**

| Field | Type | Description |
|---|---|---|
| `coinId` | String | CoinGecko identifier for the coin |
| `date` | String | ISO timestamp of the data point |
| `price` | Number | Price at the given timestamp |
| `marketCap` | Number | Market cap at the given timestamp |
| `volume` | Number | Trading volume at the given timestamp |
| `currency` | String | Currency code used for values |

***

### Use cases

- **Portfolio tracking and alerting** -- Schedule hourly runs in `price` mode for your watchlist coins. Pipe results to Google Sheets or trigger Slack alerts when prices cross thresholds.
- **Market research and reporting** -- Pull top 100 coins by market cap with 7-day and 30-day change data for weekly crypto market reports, newsletters, or client briefings.
- **Trading strategy backtesting** -- Download historical price and volume series in `history` mode to backtest quantitative strategies or train machine learning models on crypto market data.
- **Trend detection** -- Monitor `trending` mode daily to spot coins gaining traction before mainstream attention. Cross-reference with `market` mode to filter by fundamentals.
- **Market dashboard data feeds** -- Use `global` mode to power overview dashboards showing total market cap, BTC/ETH dominance, and 24-hour volume without pulling individual coin data.
- **DeFi and Web3 application price feeds** -- Integrate real-time price lookups into decentralized applications, portfolio trackers, or custom trading dashboards via the Apify API.

***

### API & Integration

**Python:**

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run = client.actor("OHTDT0XcSziuWLin7").call(run_input={
    "apiKey": "CG-xxxxxxxxxxxxxxxxxxxx",
    "mode": "market",
    "vsCurrency": "usd",
    "maxResults": 50,
})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(f"{item['name']} ({item['symbol']}): ${item['currentPrice']}")
```

**JavaScript:**

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

const client = new ApifyClient({ token: "YOUR_APIFY_TOKEN" });

const run = await client.actor("OHTDT0XcSziuWLin7").call({
    apiKey: "CG-xxxxxxxxxxxxxxxxxxxx",
    mode: "price",
    coinIds: ["bitcoin", "ethereum", "solana"],
    vsCurrency: "usd",
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => console.log(`${item.coinId}: $${item.currentPrice}`));
```

**cURL:**

```bash
curl "https://api.apify.com/v2/acts/OHTDT0XcSziuWLin7/runs" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_APIFY_TOKEN" \
  -d '{
    "apiKey": "CG-xxxxxxxxxxxxxxxxxxxx",
    "mode": "global"
  }'
```

#### Integrations

- **Zapier** -- Build price alert workflows that run the actor on a schedule, check thresholds, and send notifications to Slack, email, or SMS.
- **Make (Integromat)** -- Create multi-step workflows that filter results by price change or volume and push data to Google Sheets, Airtable, or Notion.
- **Google Sheets** -- Export market data directly to a spreadsheet for collaborative portfolio tracking and charting using the Apify Google Sheets integration.
- **Webhooks** -- Configure Apify webhooks to POST the full dataset to any HTTP endpoint when a run completes for real-time database ingestion.

***

### Use in Dify

Drop this actor into [Dify](https://docs.apify.com/platform/integrations/dify) workflows via the Apify plugin's Run Actor node. Each coin returns classified, not raw: a `marketSignals` block whose stable enums (`marketState`, `momentum24h`, `trendAlignment`, `volatilityLevel`) your downstream if/else node branches on directly. A plain CoinGecko wrapper pointed at the same endpoint returns raw percentages you have to threshold yourself; this returns the classification. (Classification of observed price action, not investment advice.)

- **Actor ID:** `ryanclinton/coingecko-crypto-data`
- **Sample input** (classify the top market and route the movers):

```json
{
    "apiKey": "CG-xxxxxxxxxxxxxxxxxxxx",
    "mode": "market",
    "vsCurrency": "usd",
    "maxResults": 50,
    "watchlistName": "daily-top50"
}
```

A Dify **if/else** node routes on the stable enums without parsing numbers:

- `marketSignals.marketState == "strong-downtrend"` or `momentum24h == "plunging"` → alert / review branch
- `marketSignals.marketState == "strong-uptrend"` → momentum-watch branch
- `marketSignals.volatilityLevel == "extreme"` → flag-for-attention branch
- `change.status == "down"` (watchlist mode) → "moved against us since last run" branch
- `recordType == "market-summary"` → read `breadthSignal` for the one-row market overview

The `market-summary` record's `breadthSignal` (`broad-advance` to `broad-decline`) and the global record's `marketCapTrend` are single-value enums a workflow can branch on for the whole-market view. With `watchlistName` set on a scheduled Dify run, the per-coin `change.status` enum is what a "what moved since last run" branch reads -- no diffing logic in the workflow.

***

### How it works

```
                        +------------------+
                        |   Actor Input    |
                        | (mode, apiKey,   |
                        |  coinIds, etc.)  |
                        +--------+---------+
                                 |
                     +-----------+-----------+
                     |    Mode Selection     |
                     +-----------+-----------+
                                 |
          +----------+-----------+-----------+-----------+----------+
          |          |           |           |           |          |
       market     price      trending    global      search    history
          |          |           |           |           |          |
    /coins/    /simple/    /search/     /global    /search    /coins/
    markets     price      trending                          {id}/
                                                            market_
                                                             chart
          |          |           |           |           |          |
          +----------+-----------+-----------+-----------+----------+
                                 |
                     +-----------+-----------+
                     |  Normalize Response   |
                     |  to Typed Objects     |
                     +-----------+-----------+
                                 |
                     +-----------+-----------+
                     |  Push to Apify        |
                     |  Dataset (JSON/CSV)   |
                     +---------------------- +
```

1. The actor reads input parameters and validates the selected mode.
2. If no API key is provided, it enters dry-run mode and outputs setup instructions.
3. Based on the mode, it calls the appropriate CoinGecko API v3 endpoint with the `x_cg_demo_api_key` parameter.
4. Raw API responses are normalized into typed output objects with consistent field names.
5. For history mode, the actor iterates through each coin ID and fetches chart data sequentially.
6. All results are pushed to the Apify dataset for download or API access.

***

### Performance & cost

| Scenario | API calls | Compute units | Est. duration |
|---|---|---|---|
| Market rankings (top 100 coins) | 1 | ~0.01 CU | 3-5 seconds |
| Price lookup (5-10 coins) | 1 | ~0.01 CU | 2-4 seconds |
| Trending coins | 1 | ~0.01 CU | 2-4 seconds |
| Global market stats | 1 | ~0.01 CU | 2-3 seconds |
| Coin search | 1 | ~0.01 CU | 2-4 seconds |
| History (1 coin, 30 days) | 1 | ~0.02 CU | 3-5 seconds |
| History (5 coins, 365 days) | 5 | ~0.05 CU | 10-15 seconds |

The actor uses 256 MB of memory. On the Apify Free plan (~$5/month of compute), you can run roughly 500 market or price lookups per month. The CoinGecko Demo API key is free and allows 10,000 calls/month with approximately 30 calls/minute rate limiting. Each actor run uses 1-6 API calls depending on the mode and number of coins.

***

### Limitations

- **CoinGecko API key required.** The actor requires a free Demo API key from CoinGecko. Without it, the actor only outputs setup instructions.
- **Rate limits on free tier.** The CoinGecko Demo key allows approximately 10,000 API calls per month and 30 calls per minute. High-frequency runs may hit these limits.
- **250 coins maximum per market run.** The CoinGecko API returns a maximum of 250 coins per page in market mode. For the full 15,000+ coin list, use search mode.
- **History mode is sequential.** When requesting historical data for multiple coins, each coin requires a separate API call, which increases both run time and API usage.
- **Price mode returns fewer fields.** The simple price endpoint provides only current price, market cap, volume, and 24-hour change. For full metrics including supply and ATH/ATL, use market mode.
- **Data granularity depends on range.** History ranges of 1-2 days return 5-minute intervals. Ranges of 3-90 days return hourly data. Ranges over 90 days return daily data. This is controlled by CoinGecko, not the actor.

***

### Responsible use

This actor accesses the CoinGecko API, which has published rate limits and terms of service. Please respect the following guidelines:

- Stay within your CoinGecko API key rate limits (30 calls/minute, 10,000 calls/month on the free tier).
- Do not use this actor to redistribute CoinGecko data in ways that violate their terms of service.
- Space out scheduled runs appropriately. Hourly runs for price monitoring are reasonable; running every minute is excessive and may trigger rate limiting.
- If your usage requires higher throughput, consider upgrading to a paid CoinGecko API plan.

***

### FAQ

**Do I need a CoinGecko API key?**
Yes. The actor requires a free CoinGecko Demo API key to fetch live data. Sign up at [coingecko.com/en/api](https://www.coingecko.com/en/api) -- it takes about 30 seconds. Without a key, the actor runs in dry-run mode and outputs instructions.

**How many coins can I retrieve per run?**
In market mode, up to 250 coins per run ranked by market cap. In price mode, you can look up any number of specific coins by ID. In search mode, up to 250 results. CoinGecko tracks over 15,000 cryptocurrencies total.

**How fresh is the data?**
CoinGecko updates prices approximately every 1-2 minutes for actively traded coins. Historical data uses daily closing prices for ranges over 90 days, hourly prices for 3-90 day ranges, and 5-minute intervals for 1-2 day ranges.

**What is the difference between market mode and price mode?**
Market mode returns the top coins ranked by market cap with comprehensive data including supply metrics, ATH/ATL, and 7d/30d price changes. Price mode is a lightweight lookup for specific coins by ID, returning only current price, market cap, volume, and 24-hour change. Use market mode for broad analysis and price mode for targeted monitoring.

**Can I get historical data for multiple coins at once?**
Yes. In history mode, provide multiple coin IDs in the `coinIds` field. The actor fetches chart data for each coin sequentially and combines all data points into a single dataset. Each coin uses one API call.

**Does the actor support stablecoins and meme coins?**
Yes. CoinGecko tracks all types of cryptocurrencies including stablecoins (USDT, USDC, DAI), meme coins (DOGE, SHIB, PEPE), DeFi tokens, Layer 2 tokens, and NFT-related tokens. If a coin is listed on CoinGecko, this actor can retrieve its data.

**What happens if I run the actor without an API key?**
The actor enters dry-run mode and outputs a single record with step-by-step instructions for obtaining a free CoinGecko Demo API key. No API calls are made and no cryptocurrency data is returned. This lets you test the actor setup before creating an account.

***

### Related actors

| Actor | Description |
|---|---|
| [Finnhub Stock Market Data](https://apify.com/ryanclinton/finnhub-stock-data) | Stock prices, company profiles, and financial data from traditional markets for cross-asset analysis. |
| [FRED Economic Data Search](https://apify.com/ryanclinton/fred-economic-data) | Federal Reserve economic indicators like interest rates and inflation that influence crypto markets. |
| [Currency Exchange Rate Tracker](https://apify.com/ryanclinton/exchange-rate-tracker) | Real-time fiat exchange rates to understand how currency strength affects crypto pricing. |
| [Historical Exchange Rate Data](https://apify.com/ryanclinton/exchange-rate-history) | Historical fiat rates to normalize crypto prices across currencies for multi-region analysis. |
| [Hacker News Search](https://apify.com/ryanclinton/hackernews-search) | Monitor crypto discussions and sentiment signals on Hacker News that often precede price movements. |
| [Website Change Monitor](https://apify.com/ryanclinton/website-change-monitor) | Track changes on crypto project websites or regulatory pages to catch important updates early. |

# Actor input Schema

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

Free Demo API key from coingecko.com (sign up at https://www.coingecko.com/en/api)

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

What data to retrieve

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

CoinGecko coin IDs for price/history mode (e.g. bitcoin, ethereum, solana). Find IDs at coingecko.com.

## `searchQuery` (type: `string`):

Search term for 'search' mode (e.g. 'bitcoin', 'defi')

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

Price currency (e.g. usd, eur, btc)

## `days` (type: `string`):

Number of days for historical chart data (1, 7, 30, 90, 365, max)

## `maxResults` (type: `integer`):

Maximum number of coins to return in market mode, or sectors to return in sectors mode (top N by market cap). CoinGecko has 700+ categories, most tiny niche ones, so sectors is capped to the meaningful top N.

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

Optional CoinGecko category id to filter market mode to one sector, e.g. 'artificial-intelligence', 'layer-2', 'meme-token', 'decentralized-finance-defi', 'gaming'. Returns only coins in that category, ranked by market cap. Find category ids at coingecko.com/en/categories. Leave blank for the whole market.

## `watchlistName` (type: `string`):

Set a name to track changes across runs. Leave blank for a one-off snapshot (default). When set, each coin in market/price/trending mode gets a 'change' block comparing it to the previous run on the same watchlist (status new/up/down/stable + % move + momentum shift). Run the actor on a schedule with the same watchlist name to monitor moves. First run on a new name marks every coin 'new'.

## Actor input object example

```json
{
  "mode": "market",
  "vsCurrency": "usd",
  "days": "30",
  "maxResults": 100
}
```

# Actor output Schema

## `results` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("ryanclinton/coingecko-crypto-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 = {}

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

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

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

```

## CLI example

```bash
echo '{}' |
apify call ryanclinton/coingecko-crypto-data --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=ryanclinton/coingecko-crypto-data",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "CoinGecko Crypto — Data, Signals & Market Events",
        "description": "Generate crypto market intelligence from CoinGecko: live prices, relative strength, market regime, sector rotation, and automation-ready events across 15,000+ coins and 60+ currencies. Classifies what changed and what's leading, as stable enums. Export JSON, CSV, Excel.",
        "version": "1.1",
        "x-build-id": "kEox0G6Qk2arVAK2D"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/ryanclinton~coingecko-crypto-data/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-ryanclinton-coingecko-crypto-data",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/ryanclinton~coingecko-crypto-data/runs": {
            "post": {
                "operationId": "runs-sync-ryanclinton-coingecko-crypto-data",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/ryanclinton~coingecko-crypto-data/run-sync": {
            "post": {
                "operationId": "run-sync-ryanclinton-coingecko-crypto-data",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "apiKey": {
                        "title": "CoinGecko API Key",
                        "type": "string",
                        "description": "Free Demo API key from coingecko.com (sign up at https://www.coingecko.com/en/api)"
                    },
                    "mode": {
                        "title": "Data Mode",
                        "enum": [
                            "market",
                            "price",
                            "trending",
                            "global",
                            "search",
                            "history",
                            "sectors"
                        ],
                        "type": "string",
                        "description": "What data to retrieve",
                        "default": "market"
                    },
                    "coinIds": {
                        "title": "Coin IDs",
                        "type": "array",
                        "description": "CoinGecko coin IDs for price/history mode (e.g. bitcoin, ethereum, solana). Find IDs at coingecko.com.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "searchQuery": {
                        "title": "Search Query",
                        "type": "string",
                        "description": "Search term for 'search' mode (e.g. 'bitcoin', 'defi')"
                    },
                    "vsCurrency": {
                        "title": "Currency",
                        "type": "string",
                        "description": "Price currency (e.g. usd, eur, btc)",
                        "default": "usd"
                    },
                    "days": {
                        "title": "History Days",
                        "type": "string",
                        "description": "Number of days for historical chart data (1, 7, 30, 90, 365, max)",
                        "default": "30"
                    },
                    "maxResults": {
                        "title": "Max Results",
                        "minimum": 1,
                        "maximum": 250,
                        "type": "integer",
                        "description": "Maximum number of coins to return in market mode, or sectors to return in sectors mode (top N by market cap). CoinGecko has 700+ categories, most tiny niche ones, so sectors is capped to the meaningful top N.",
                        "default": 100
                    },
                    "category": {
                        "title": "Category Filter (market mode)",
                        "type": "string",
                        "description": "Optional CoinGecko category id to filter market mode to one sector, e.g. 'artificial-intelligence', 'layer-2', 'meme-token', 'decentralized-finance-defi', 'gaming'. Returns only coins in that category, ranked by market cap. Find category ids at coingecko.com/en/categories. Leave blank for the whole market."
                    },
                    "watchlistName": {
                        "title": "Watchlist Name (optional)",
                        "type": "string",
                        "description": "Set a name to track changes across runs. Leave blank for a one-off snapshot (default). When set, each coin in market/price/trending mode gets a 'change' block comparing it to the previous run on the same watchlist (status new/up/down/stable + % move + momentum shift). Run the actor on a schedule with the same watchlist name to monitor moves. First run on a new name marks every coin 'new'."
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```