# AI Elliott Wave Counter (`egsand/ai-elliott-wave-counter`) Actor

- **URL**: https://apify.com/egsand/ai-elliott-wave-counter.md
- **Developed by:** [Enrique G.](https://apify.com/egsand) (community)
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $50.00 / 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

## AI Elliott Wave Counter

An ultra-high-speed quantitative engine for automated **Elliott Wave Theory** decomposition, pattern recognition, and probabilistic scenario ranking.

Designed for quantitative analysts, algorithmic traders, hedge funds, and technical chartists who need rigorous, rule-based Elliott Wave analysis delivered with sub-second execution.

***

### What It Does

The **AI Elliott Wave Counter** scans financial market candlestick data, identifies critical price swings, and systematically evaluates multi-degree fractal wave counts according to classical Elliott Wave rules and modern quantitative extensions.

- **Multi-Degree Recursive Decomposition**: Deconstructs complex price trends into hierarchical wave structures across degrees (Supercycle, Cycle, Primary, Intermediate, Minor, Minute, Minuette, Sub-Minuette).
- **Comprehensive Pattern Recognition**:
  - **Motive Structures**: 5-wave Impulses, Contracting Diagonals, and Expanding Diagonals.
  - **Corrective Structures**: Zig-Zags (5-3-5), Flats (3-3-5), Contracting & Expanding Triangles (3-3-3-3-3), and Complex Combinations (Double/Triple Zigzags, W-X-Y).
- **Alternative Counts & Probabilistic Ranking**: Instead of presenting a single subjective interpretation, the engine generates all mathematically valid alternative counts and ranks them using continuous Gaussian Fibonacci tolerances and machine learning conviction scores.
- **Incomplete / Developing Wave Projections**: Identifies developing waves in real time to project continuation targets, wave 3 extensions, and corrective terminal zones.
- **Interactive Visualizer**: Generates a self-contained interactive web chart that lets you visually inspect and step through every detected wave scenario directly in your browser.

***

### Processing Capacity & Limits

> \[!IMPORTANT]
> **Maximum Bar Limit**: The analyzer accepts up to **2,000 Japanese candlesticks (bars)** per execution.
>
> To ensure ultra-fast processing and deterministic execution times, input datasets exceeding 2,000 bars must be trimmed to the most recent 2,000 bars.

***

### Inputs

Configure the analysis using simple JSON parameters in the actor input:

| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `candles` | `Array<Object>` | *Optional* | Array of Japanese candlestick objects (`open`, `high`, `low`, `close`, `time`). Maximum 2,000 bars. |
| `symbol` | `String` | `"BTCUSDT"` | *Optional*: If direct candles are omitted, specify a crypto pair to auto-fetch the latest market candles. |
| `timeframe` | `String` | `"1h"` | Candlestick interval when auto-fetching (`1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d`). |
| `topCounts` | `Integer` | `50` | Maximum number of top alternative wave counts to return (1 to 200). If fewer alternative counts are detected, all available counts are returned. |
| `swingSize` | `Integer` | `1` | Pivot detection sensitivity window. Smaller values (1–2) detect micro-swings; higher values (3+) isolate major macro pivots. |
| `maxDepth` | `Integer` | `4` | Maximum depth for recursive wave decomposition (e.g., Primary down to Sub-Minuette). |
| `analysisMode` | `String` | `"Both"` | Analysis scope: `"Both"` (Complete & Developing), `"Complete"` (only finished structures), or `"Incomplete"` (only active waves). |
| `scoreFormula` | `String` | `"ml_calibrated"` | Scoring model: `"ml_calibrated"` (Gaussian + Machine Learning probability), `"average"`, or `"bayesian"`. |
| `allowTriangleOverlap` | `Boolean` | `false` | Enables structural sub-wave overlap flexibility in triangle patterns. |
| `renderInteractiveHtml`| `Boolean` | `true` | Generates a standalone interactive chart stored in the Key-Value store under `CHART_HTML`. |

#### Candlestick Format Example

You can pass standard OHLCV objects or compact arrays:

```json
{
  "topCounts": 50,
  "swingSize": 1,
  "maxDepth": 4,
  "candles": [
    { "time": 1700000000, "open": 64200.5, "high": 64850.0, "low": 63900.0, "close": 64600.0, "volume": 1420.5 },
    { "time": 1700003600, "open": 64600.0, "high": 65300.0, "low": 64450.0, "close": 65150.0, "volume": 1890.2 },
    { "time": 1700007200, "open": 65150.0, "high": 65400.0, "low": 64700.0, "close": 64800.0, "volume": 1210.8 }
  ]
}
```

*Note: Compact arrays `[timestamp, open, high, low, close]` or `[open, high, low, close]` are also supported.*

***

### Outputs

Every execution produces clean, structured outputs across both the **Default Dataset** and the **Default Key-Value Store**:

#### 1. Default Dataset (Tabular Scenarios)

Each alternative wave scenario is stored as an individual record in the dataset, perfectly formatted for export to JSON, CSV, or Excel:

```json
{
  "rank": 1,
  "pattern": "Impulse",
  "degree": "Primary",
  "direction": "bullish",
  "total_score": 14.85,
  "ml_probability_pct": 82.4,
  "start_bar_index": 12,
  "end_bar_index": 118,
  "start_price": 58200.0,
  "end_price": 68450.0,
  "source": "full",
  "summary": {
    "idx": 0,
    "pattern": "Impulse",
    "degree": "Primary",
    "score": 14.85,
    "direction": "bullish",
    "c_ratio_a": 0.0,
    "y_ratio_w": 0.0,
    "ml_prob": 82.4
  },
  "tree": {
    "pt": "Impulse",
    "role": "root",
    "deg": 2,
    "si": 0,
    "ei": 8,
    "sp": 58200.0,
    "ep": 68450.0,
    "dir": "bullish",
    "sc": 5.2,
    "ts": 14.85,
    "ch": [
      { "pt": "Impulse", "role": "1", "deg": 3, "sp": 58200.0, "ep": 61000.0, "dir": "bullish" },
      { "pt": "Zig-Zag", "role": "2", "deg": 3, "sp": 61000.0, "ep": 59300.0, "dir": "bearish" },
      { "pt": "Impulse", "role": "3", "deg": 3, "sp": 59300.0, "ep": 66200.0, "dir": "bullish" },
      { "pt": "Flat",    "role": "4", "deg": 3, "sp": 66200.0, "ep": 64100.0, "dir": "bearish" },
      { "pt": "Impulse", "role": "5", "deg": 3, "sp": 64100.0, "ep": 68450.0, "dir": "bullish" }
    ]
  }
}
```

#### 2. Key-Value Store Records

- **`SUMMARY`**: A concise executive summary containing analysis performance statistics, total counts discovered, and top pattern metrics.
- **`OUTPUT`**: The complete hierarchical analysis payload, including full wave trees and index-to-bar mappings.
- **`CHART_HTML`**: An interactive, standalone visualization dashboard. Open the URL to inspect candlesticks, view degree color-coded wave labels, toggle between alternative counts, and examine sub-wave trees in real time.

***

### Practical Applications

- **Algorithmic Trading**: Ingest structured wave counts directly into automated execution systems for high-probability trend entries and invalidation stop-loss placement.
- **TradingView & Chart Integration**: Feed detected wave labels and pivot coordinates into custom indicators or chart overlays via webhook.
- **Consensus Analysis**: Measure structural consensus across multiple timeframes to determine whether the market is in an impulsive trend or complex corrective chop.
- **Backtesting**: Rigorously validate Elliott Wave trading strategies against historical market data without subjective manual charting bias.

# Actor input Schema

## `candles` (type: `array`):

Array of Japanese candlestick objects (\[{"open": 100, "high": 105, "low": 98, "close": 104, "time": 1700000000}, ...]) or arrays (\[time, open, high, low, close]). Maximum 2,000 bars.

## `symbol` (type: `string`):

Optional: If candles array is not provided, specify a crypto pair (e.g., BTCUSDT, ETHUSDT, SOLUSDT) to automatically fetch latest market bars.

## `timeframe` (type: `string`):

Timeframe interval when using auto-fetch symbol.

## `topCounts` (type: `integer`):

Maximum number of top alternative Elliott Wave counts to return (1 to 200). If the software finds fewer counts, it returns all available counts.

## `swingSize` (type: `integer`):

Sensitivity window for detecting swing highs and swing lows. Smaller values (1-2) detect finer sub-waves; higher values (3+) isolate major structural swings.

## `maxDepth` (type: `integer`):

Maximum recursive wave hierarchy depth (from Primary/Intermediate down to Minuette/Sub-Minuette).

## `analysisMode` (type: `string`):

Select whether to analyze only fully completed wave structures, in-progress incomplete waves, or both.

## `scoreFormula` (type: `string`):

Confidence scoring algorithm used to rank wave alternatives. 'ml_calibrated' utilizes continuous Gaussian scoring combined with trained Machine Learning probabilities.

## `allowTriangleOverlap` (type: `boolean`):

Allows sub-wave overlap flexibility in contracting/expanding triangle structures.

## `renderInteractiveHtml` (type: `boolean`):

Generates a complete standalone interactive Plotly chart saved to the default Key-Value Store under record 'CHART_HTML'.

## Actor input object example

```json
{
  "symbol": "BTCUSDT",
  "timeframe": "1h",
  "topCounts": 50,
  "swingSize": 1,
  "maxDepth": 4,
  "analysisMode": "Both",
  "scoreFormula": "ml_calibrated",
  "allowTriangleOverlap": false,
  "renderInteractiveHtml": true
}
```

# Actor output Schema

## `scenariosDataset` (type: `string`):

Dataset containing all alternative Elliott Wave counts ranked by quantitative total score and machine learning conviction.

## `executiveSummary` (type: `string`):

Key-Value store record containing key pattern metrics, detected Fibonacci wave ratios, degrees, and directions.

## `fullOutput` (type: `string`):

Complete JSON tree containing all serialized WaveNode structures, swing-to-candle mapping, and engine execution statistics.

## `chartVisualizer` (type: `string`):

Standalone interactive chart rendering the candlesticks, pivot swings, and wave decompositions with degree color-coding.

# 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 = {
    "symbol": "BTCUSDT"
};

// Run the Actor and wait for it to finish
const run = await client.actor("egsand/ai-elliott-wave-counter").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 = { "symbol": "BTCUSDT" }

# Run the Actor and wait for it to finish
run = client.actor("egsand/ai-elliott-wave-counter").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 '{
  "symbol": "BTCUSDT"
}' |
apify call egsand/ai-elliott-wave-counter --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,egsand/ai-elliott-wave-counter"
        }
    }
}
```

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/aQw7FC26oXHoL2ldX/builds/5cxZRWmgUo6xd5och/openapi.json