CoinGecko Crypto Data

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:

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

This actor returns something your automation can act on:

{
    "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.

---

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:

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

With this actor:

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:

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

The actor surfaces an opportunity record:

{
    "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:

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

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.

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 for a free Demo account. Copy your API key from the dashboard.
2. Open the actor on Apify. Navigate to 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. 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.
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

{
    "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 if you just want to run it.

Output example

Market mode (default):

{
    "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):

{
    "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:

{
    "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):

{
    "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):

{
    "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"
}

{
    "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):

{
    "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):

{
    "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):

{
    "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):

{
    "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"
}

{
    "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):

{
    "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:

{
    "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:

{
    "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":

{
    "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:

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:

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:

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 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):

{
    "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 -- 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	Stock prices, company profiles, and financial data from traditional markets for cross-asset analysis.
FRED Economic Data Search	Federal Reserve economic indicators like interest rates and inflation that influence crypto markets.
Currency Exchange Rate Tracker	Real-time fiat exchange rates to understand how currency strength affects crypto pricing.
Historical Exchange Rate Data	Historical fiat rates to normalize crypto prices across currencies for multi-region analysis.
Hacker News Search	Monitor crypto discussions and sentiment signals on Hacker News that often precede price movements.
Website Change Monitor	Track changes on crypto project websites or regulatory pages to catch important updates early.