# Crypto Market Scraper — CoinMarketCap & CoinGecko (`brilliant_gum/crypto-market-scraper`) Actor

One actor, two sources. Scrape CoinMarketCap + CoinGecko: top-coin listings, coin details, trending, categories, exchanges, historical/OHLC. Derived analytics + cross-run price monitoring. No API key.

- **URL**: https://apify.com/brilliant\_gum/crypto-market-scraper.md
- **Developed by:** [Yuliia Kulakova](https://apify.com/brilliant_gum) (community)
- **Categories:** Business, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.005 / result record

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Crypto Market Scraper — CoinMarketCap & CoinGecko

![Crypto Market Scraper](https://api.apify.com/v2/key-value-stores/IuFu0Cw6PpOkNkDV7/records/crypto-banner)

One Apify actor that scrapes **both CoinMarketCap and CoinGecko** market data — no API key, no login,
no cookies. Pick a `source` (`cmc`, `coingecko`, or `both`) and a `mode`, and get clean, normalized
records with **derived analytics** and optional **cross-run price monitoring**.

### Modes

| Mode | What you get |
|------|--------------|
| **listings** | Top-N coins market table: rank, price, market cap, FDV, 24h volume, supply, %1h/24h/7d/30d, tags, security audits, badges |
| **coin-details** | Full info for specific coins: description, categories, contract addresses per chain, links, holders, sentiment, security audits |
| **trending** | Trending / gainers / losers / most-visited / recently-added (gainers etc. are CoinMarketCap) |
| **categories** | Sectors ranked by market cap with top coins |
| **exchanges** | Exchange rankings (trust/score, real 24h/7d/30d volume, spot volume, pair & coin counts, country) |
| **historical** | Price/market-cap/volume time series or OHLC candles over N days |

### Quick start

```json
{
  "source": "both",
  "mode": "listings",
  "vsCurrency": "usd",
  "limit": 100,
  "maxItems": 100,
  "includeAnalytics": true
}
```

Coin details for specific coins (symbol, id/slug, or full URL):

```json
{ "source": "both", "mode": "coin-details", "coins": ["BTC", "ethereum", "https://coinmarketcap.com/currencies/solana/"] }
```

Price monitoring for scheduled runs (only outputs coins whose price changed since the last run):

```json
{ "source": "coingecko", "mode": "listings", "limit": 250, "maxItems": 250, "trackChanges": true, "onlyChanged": true }
```

### Derived analytics (on by default)

Each coin gets an `analytics` block: `volumeToMarketCap`, `volatility24h`, `athDistancePct`,
`atlDistancePct`, `supplyIssuedPct`, `circulatingToTotalPct`, `fdvToMarketCap`, `momentumScore`.

### Cross-run monitoring

With `trackChanges`, each coin gets a `monitoring` block comparing it to the previous run: price and
market-cap deltas, `minutesSinceLastRun`, `isNew`. State persists in a named key-value store across runs.

### Security audits & badges (CoinMarketCap)

CoinMarketCap coin records (both **listings** and **coin-details**) carry two security-signal fields
straight from CMC's own data:

- **`auditInfoList`** — array of third-party smart-contract audits, each `{ coinId, auditor,
  auditStatus, auditTime, reportUrl }` (e.g. Tether → CertiK + Fairyproof, BNB → CertiK + Hacken).
  Empty array when a coin has no listed audits. The boolean **`isAudited`** is kept alongside it.
- **`badges`** — CMC's badge id array shown next to a coin (e.g. Bitcoin `[1, 5]`). Empty array when a
  coin carries no badges. This is a listing-side field on CMC's API, so it is populated on **listings**
  and empty on **coin-details** (CMC's detail endpoint doesn't return it).
- **`selfReportedMarketCap`** — emitted on a coin record only when CMC exposes a non-zero self-reported
  market cap (present for some smaller coins; absent for the majors, which report 0).

### Notes & honesty

- Both sources use free public endpoints. If you hit rate limits (HTTP 429) at scale, enable Apify Proxy.
- CoinMarketCap **listings** don't include 24h high/low, ATH/ATL, or 7d/30d volume — CMC's public
  listing endpoint simply doesn't return them (a real endpoint constraint, not a scraper gap). Those
  fields are served by CoinMarketCap **coin-details** (which does return ATH/ATL, 52w hi/lo, 7d/30d
  volume) and by CoinGecko **listings** (24h high/low + ATH/ATL). Consequently the `volatility24h` /
  `athDistancePct` analytics are `null` for CMC listings and populated everywhere else.
- **Exchanges** report CMC's real reported figures: `volume24h` = total 24h volume (`totalVol24h`),
  plus `spotVolume24h`, `volume7d`, `volume30d`, `volumeChangePct24h`, `marketPairCount`, `coinCount`.
- CoinMarketCap **coin-details** statistics are USD-denominated; rich multi-currency detail and
  categories come from CoinGecko; gainers/losers come from CoinMarketCap.
- **coin-details fields vary by source:** description, price, market data, ATH/ATL and links come from
  both; contract addresses, multi-currency prices and sentiment come from CoinGecko; holders, audits and
  badges come from CoinMarketCap. Fields absent for a given source are returned as `null`/empty, not faked.
- Uses each provider's own public endpoints for informational use only. You are responsible for complying
  with CoinMarketCap's and CoinGecko's Terms of Service and your local laws.
- Market data is factual and public. Not affiliated with CoinMarketCap or CoinGecko. Not financial advice.

### Pricing

This actor runs on a **pay-per-event** model:

- **Actor start** — $0.01, charged once when a run starts.
- **Result record** — $0.005 per record delivered (a coin, category, exchange or historical row, including its derived analytics).

There is no monthly rental. You pay only for what a run actually produces, so a 100-coin listing run costs about **$0.01 + $0.50 = $0.51**. Platform usage (compute/proxy) is included in the per-event price — no separate Apify usage bill.

### Support & feedback

Found a rough edge or need another field, source, or mode? Open an issue on the actor's **Issues** tab — requests and bug reports are welcome and shape the roadmap. If this actor saves you time, a rating on the Store page genuinely helps.

# Actor input Schema

## `source` (type: `string`):

Which market to scrape: 'both' (CoinMarketCap + CoinGecko, merged), 'cmc' (CoinMarketCap only) or 'coingecko' (CoinGecko only). Both use free, no-key public endpoints.

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

What to fetch. listings = top-N coins market table; coin-details = full info for specific coins; trending = trending/gainers/losers; categories = sectors/categories; exchanges = exchange rankings; historical = price/OHLC chart for specific coins.

## `coins` (type: `array`):

List of coins for coin-details and historical modes. Accepts symbols (BTC), CoinGecko ids/CMC slugs (bitcoin), numeric CMC ids, or full URLs (coinmarketcap.com/currencies/bitcoin/ or coingecko.com/en/coins/bitcoin). Ignored for listings/trending/categories/exchanges.

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

Fiat/crypto currency prices are quoted in (e.g. usd, eur, gbp, jpy, btc, eth). Applied to all modes.

## `vsCurrencies` (type: `array`):

Optional additional quote currencies for CoinGecko coin-details price block (e.g. eur, btc). Leave empty to use only the main quote currency.

## `limit` (type: `integer`):

How many coins to request per listings page. Combined with maxItems to page through the market table. Ignored in coin-details/historical.

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

Hard cap on the number of records pushed to the dataset for the whole run (across pages and sources).

## `startRank` (type: `integer`):

1-based rank to start the listings table from (e.g. 101 to skip the top 100). Ignored in other modes.

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

Restrict listings to one category/sector. For CoinGecko use the category id (e.g. decentralized-finance-defi, layer-1, meme-token); for CMC a tag slug. Leave empty for all coins.

## `sortBy` (type: `string`):

Sort key for listings. market\_cap, volume\_24h, price, percent\_change\_1h, percent\_change\_24h, percent\_change\_7d, circulating\_supply, date\_added.

## `sortOrder` (type: `string`):

Sort direction for listings: desc (highest first) or asc (lowest first).

## `trendingType` (type: `string`):

Which trending list to return in trending mode. trending = most-searched; gainers/losers = top movers 24h; most\_visited; recently\_added = new listings. CoinGecko only supports 'trending'; the others use CoinMarketCap.

## `days` (type: `integer`):

Historical mode: number of days of price history to fetch (1-3650). CoinGecko free supports up to 365 days; CMC supports longer ranges. Ignored in other modes.

## `ohlc` (type: `boolean`):

Historical mode: return OHLC candles (open/high/low/close per interval) instead of a price/volume/market-cap time series.

## `includeChart` (type: `boolean`):

coin-details mode: also fetch and attach a price history/sparkline (uses the 'days' timeframe) to each coin record.

## `includeDetails` (type: `boolean`):

Attach the full market block (market cap, volume, 24h high/low, supply, % changes) to each record. Turn off for a lean price-only output.

## `includeAnalytics` (type: `boolean`):

Attach a computed analytics block: volume/market-cap ratio, 24h volatility, ATH/ATL distance %, supply-issued %, FDV/market-cap ratio, momentum score.

## `minMarketCap` (type: `integer`):

Keep only coins with market cap >= this value (in the quote currency). Leave empty for no minimum.

## `maxMarketCap` (type: `integer`):

Keep only coins with market cap <= this value. Leave empty for no maximum.

## `minVolume24h` (type: `integer`):

Keep only coins with 24h trading volume >= this value. Leave empty for no minimum.

## `minPrice` (type: `number`):

Keep only coins with price >= this value. Leave empty for no minimum.

## `maxPrice` (type: `number`):

Keep only coins with price <= this value. Leave empty for no maximum.

## `minPercentChange24h` (type: `number`):

Keep only coins whose 24h price change % is >= this value (e.g. 5 for pumps, -100 for all). Leave empty to ignore.

## `maxPercentChange24h` (type: `number`):

Keep only coins whose 24h price change % is <= this value. Leave empty to ignore.

## `trackChanges` (type: `boolean`):

Compare each coin against the previous run stored in the actor's key-value store and attach a monitoring block (price/market-cap delta since last run, minutes since last seen, isNew).

## `onlyChanged` (type: `boolean`):

With cross-run monitoring on, push only coins whose price changed since the previous run (skip unchanged). Great for scheduled price-alert runs.

## `dedup` (type: `boolean`):

Remove duplicate coins (same source + id) within a run. Useful when merging both sources or paging.

## `flat` (type: `boolean`):

Emit flat/denormalized rows (nested price-change, supply and analytics fields hoisted to top level) for easy CSV/spreadsheet export.

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

Optional proxy. The public endpoints work directly; enable Apify Proxy (datacenter, or residential US) if you hit rate limits (HTTP 429) at scale.

## Actor input object example

```json
{
  "source": "both",
  "mode": "listings",
  "coins": [
    "BTC",
    "ETH"
  ],
  "vsCurrency": "usd",
  "limit": 100,
  "maxItems": 100,
  "startRank": 1,
  "sortBy": "market_cap",
  "sortOrder": "desc",
  "trendingType": "trending",
  "days": 7,
  "ohlc": false,
  "includeChart": false,
  "includeDetails": true,
  "includeAnalytics": true,
  "trackChanges": false,
  "onlyChanged": false,
  "dedup": true,
  "flat": false,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

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

All scraped market records.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

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

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "coins": [
        "BTC",
        "ETH"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("brilliant_gum/crypto-market-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "coins": [
        "BTC",
        "ETH",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("brilliant_gum/crypto-market-scraper").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "coins": [
    "BTC",
    "ETH"
  ]
}' |
apify call brilliant_gum/crypto-market-scraper --silent --output-dataset

```

## MCP server setup

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

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/pJE1WPoEbLYe8NaNi/builds/9b96w6vP7YgcK30jB/openapi.json