# Crypto Calendar Scraper (`egsand/crypto-calendar-scraper`) Actor

- **URL**: https://apify.com/egsand/crypto-calendar-scraper.md
- **Developed by:** [Enrique G.](https://apify.com/egsand) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.50 / 1,000 results

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

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

## What's an Apify Actor?

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 Calendar Scraper

A high-performance data extraction engine for cryptocurrency market catalysts, scheduled token unlocks, protocol upgrades, exchange listings, and historical price impact analysis.

***

### Overview

Crypto Calendar Scraper aggregates scheduled and historical market-moving events across decentralized protocols and centralized exchanges. It leverages structured data pipelines from verified industry sources (**DeFiLlama** and **Coindar**) to deliver normalized, production-grade JSON datasets suitable for quantitative trading systems, portfolio risk monitors, and automated market intelligence workflows.

#### Key Capabilities

- **Dual-Horizon Event Tracking**:
  - **Forward Analysis (`daysAhead`)**: Extracts upcoming token unlocks, hard forks, testnet/mainnet launches, and governance votes within a customizable time window.
  - **Historical Audit (`daysBack`)**: Retrieves past catalyst executions to evaluate post-event market performance and circulating supply expansion.
- **Quantitative Price Impact Engine**:
  - For historical token unlocks, the scraper computes:
    - Spot price at the exact execution timestamp (`priceAtEvent`).
    - Current spot market price (`currentPrice`).
    - Percentage price delta: `((currentPrice - priceAtEvent) / priceAtEvent) * 100`.
    - Nominal token unlock volume and aggregate USD value unlocked at execution.
    - Distribution category classification (`ecosystem`, `insiders`, `privatesale`, `community`, `publicsale`).
- **Multi-Source Coverage**:
  - **DeFiLlama Feed**: Tokenomics schedules, cliff releases, and linear vesting contracts across 370+ tracked protocols.
  - **Coindar Feed**: Protocol releases, hard forks, network upgrades, conferences, and exchange listings.
- **Deterministic Filtering**:
  - Filter by specific coin tickers (e.g. `["TIA", "SOL", "ARB"]`). If omitted, returns global events sorted chronologically by proximity.
  - Filter by category classification. If omitted, extracts catalysts across all operational sectors.

***

### Input Parameters

| Parameter | Type | Default | Required | Description |
| :--- | :--- | :--- | :--- | :--- |
| `source` | `String` | `"all"` | No | Target data source: `"all"`, `"defillama"`, or `"coindar"`. |
| `coins` | `Array<String>` | `[]` | No | List of asset symbols to filter (e.g. `["BTC", "ETH", "TIA"]`). When empty, queries all tracked assets. |
| `categories` | `Array<String>` | `[]` | No | Catalyst categories to include (e.g. `["tokenomics", "fork", "release", "listing"]`). Empty matches all categories. |
| `daysAhead` | `Integer` | `60` | No | Number of future days to search for upcoming events (relative to UTC execution time). |
| `daysBack` | `Integer` | `0` | No | Number of past days to inspect for historical events and calculate price impact metrics. |
| `maxEvents` | `Integer` | `50` | No | Maximum number of records returned and pushed to the dataset. |
| `coindarApiToken`| `String` | `""` | No | Optional Coindar API v2 access token for high-rate direct querying. |
| `proxyConfiguration` | `Object` | `{}` | No | Optional proxy configuration object. Defaults to direct connection. |

#### Example Input Payload

```json
{
  "source": "all",
  "coins": ["TIA", "SOL", "SUI"],
  "categories": ["tokenomics", "release"],
  "daysAhead": 30,
  "daysBack": 14,
  "maxEvents": 50
}
```

***

### Output Dataset Schema

Each item written to the default dataset contains normalized fields adhering to the following structure:

```json
{
  "id": "defillama-past-TIA-1792945069",
  "source": "defillama",
  "status": "past",
  "isPast": true,
  "title": "[PAST] Celestia (TIA) CLIFF Unlock (insiders)",
  "coinSymbol": "TIA",
  "coinName": "Celestia",
  "coinDisplay": "Celestia (TIA)",
  "eventType": "Past Token Unlock",
  "category": "insiders",
  "eventDate": "2026-10-25T16:00:00.000Z",
  "dateAdded": "2026-10-01T12:00:00.000Z",
  "daysUntil": -7,
  "daysAgo": 7,
  "description": "Cliff unlock of 175,560,000 TIA allocated to Core Contributors and Early Investors.",
  "sourceUrl": "https://defillama.com/unlocks/celestia",
  "impactAnalysis": {
    "outcome": "Price declined -3.20% since unlock ($5.8000 → $5.6144)",
    "priceAtEvent": 5.80,
    "currentPrice": 5.6144,
    "priceChangeSinceEventPct": -3.20,
    "tokensUnlocked": 175560000,
    "unlockValueUsd": 1018248000,
    "unlockType": "cliff",
    "category": "insiders"
  },
  "extraMetadata": {
    "unlockType": "cliff",
    "tokensToUnlock": 175560000,
    "unlockValueUsd": 1018248000,
    "tokenPriceUsd": 5.6144,
    "marketCapUsd": 2350000000
  }
}
```

#### Field Definitions

- **`id`** (`string`): Unique deterministic identifier for the event.
- **`source`** (`string`): Originating platform (`defillama` or `coindar`).
- **`status`** (`string`): Temporal status (`upcoming` or `past`).
- **`isPast`** (`boolean`): Convenience flag for filtering historical vs. scheduled events.
- **`title`** (`string`): Canonical event title with asset identifier and classification.
- **`coinSymbol`** (`string`): Standard uppercase ticker symbol.
- **`coinName`** (`string`): Project or network name.
- **`coinDisplay`** (`string`): Formatted label combining name and ticker.
- **`eventType`** (`string`): Specific catalyst typology (`Token Unlock`, `Hard Fork`, `Listing`, `Milestone`).
- **`category`** (`string`): Sector category (`tokenomics`, `ecosystem`, `insiders`, `fork`, `release`).
- **`eventDate`** (`string`): ISO 8601 UTC timestamp of scheduled or completed execution.
- **`dateAdded`** (`string`): ISO 8601 UTC timestamp when the event was recorded.
- **`daysUntil`** (`integer`): Relative days from execution time (positive for future, negative for past).
- **`daysAgo`** (`integer`): Absolute days elapsed for historical records.
- **`description`** (`string`): Contextual technical summary of the catalyst.
- **`sourceUrl`** (`string`): Canonical reference or proof URL.
- **`impactAnalysis`** (`object`, optional): Computed quantitative metrics for past events.
- **`extraMetadata`** (`object`, optional): Source-specific telemetry (market cap, tokenomics volume, dilution metrics).

***

### Programmatic Integration

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

## Trigger Actor execution
run = client.actor("egsand/crypto-calendar-scraper").call(
    run_input={
        "source": "all",
        "coins": ["TIA", "SOL"],
        "daysAhead": 30,
        "daysBack": 7,
        "maxEvents": 100
    }
)

## Stream dataset items
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(f"[{item['status'].upper()}] {item['eventDate']} | {item['title']}")
    if item.get("impactAnalysis"):
        print(f"  Impact: {item['impactAnalysis']['outcome']}")
```

#### Node.js / TypeScript

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

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

const run = await client.actor('egsand/crypto-calendar-scraper').call({
    source: 'defillama',
    daysAhead: 14,
    maxEvents: 50,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(`Retrieved ${items.length} catalysts:`);
items.forEach((item) => {
    console.log(`${item.eventDate} - ${item.title}`);
});
```

#### cURL (Synchronous REST API)

```bash
curl --request POST \
  --url 'https://api.apify.com/v2/acts/egsand~crypto-calendar-scraper/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "source": "all",
    "daysAhead": 30,
    "maxEvents": 50
  }'
```

# Actor input Schema

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

Select the crypto calendar and catalyst platform to extract from.

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

List of tickers or coin names to filter by (e.g., TIA, BTC, SOL, ETH). If left empty, returns the nearest events for ANY cryptocurrency sorted by date.

## `daysAhead` (type: `integer`):

Include upcoming events happening within the next N days. Set to 0 if only extracting past events.

## `daysBack` (type: `integer`):

Include past events that occurred in the last N days (with price impact analysis, volume, and outcome). Set to 0 to only extract future events.

## `maxEvents` (type: `integer`):

Maximum number of events to return in the dataset.

## `categories` (type: `array`):

Filter by event categories (e.g., tokenomics, fork, release, listing, airdrop). If left empty, returns events from all categories.

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

Optional proxy configuration for Cloudflare-protected routes.

## Actor input object example

```json
{
  "source": "all",
  "coins": [],
  "daysAhead": 60,
  "daysBack": 0,
  "maxEvents": 50,
  "categories": [],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

Direct API link to the dataset containing upcoming catalysts, past events, and price impact analysis.

# 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("egsand/crypto-calendar-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("egsand/crypto-calendar-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 '{}' |
apify call egsand/crypto-calendar-scraper --silent --output-dataset

```

## MCP server setup

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