Hyperliquid Swing & Breakout Scanner

Unofficial community project. This Actor is not affiliated with, sponsored by, or endorsed by Hyperliquid. Hyperliquid is a third-party data source accessed through its public API.

List active Hyperliquid perpetual symbols, scan a watchlist of up to 20 markets, or scan every active standard perpetual in one run for confirmed swing levels and fresh close-based breakouts. Results include both deterministic level events and a decision-ready summary with grouped breakout candles, direction counts, active levels, volume context, and candle metrics.

The Actor uses public Hyperliquid data. It requires no wallet, private exchange API key, proxy, database, or always-on server.

This is an analytical data tool, not financial advice. It does not place trades, predict future prices, or guarantee outcomes.

Why use this Actor?

Breakout charts are easy to inspect one at a time, but harder to turn into a repeatable data workflow. Open candles can create premature signals, pivots can appear earlier than they were actually confirmable, and one candle crossing several older levels can make a market look busier than it was.

This Actor handles those edge cases and returns transparent measurements rather than an opaque signal score:

• scan a small watchlist or the complete active standard-perpetual universe;
• distinguish broken levels from unique breakout candles;
• compare breakout volume and candle structure without extra data calls;
• inspect nearby unbroken swing levels and deterministic event IDs;
• keep successful markets when another symbol returns a temporary data error.

The structured output is suited to research, alerts, dashboards, scheduled monitoring, webhooks, and other automation where reproducible event rules matter.

Operations

The Actor uses the standard Apify input and default dataset. There is no custom HTTP endpoint.

• listSymbols returns active standard perpetual names from Hyperliquid's first perpetual DEX. Delisted, spot, and HIP-3 markets are excluded.
• scanBreakouts returns one result row per requested symbol. It is the default operation. Set scanAllSymbols: true to resolve and scan the complete active first-DEX perpetual universe automatically.

List symbols:

{
  "operation": "listSymbols"
}

Scan breakouts:

{
  "operation": "scanBreakouts",
  "scanAllSymbols": false,
  "symbols": ["BTC", "ETH", "SOL"],
  "interval": "1h",
  "candleCount": 300,
  "pivotStrength": 3,
  "breakoutLookbackCandles": 20,
  "direction": "both"
}

Scan all active symbols without preparing or batching a symbol list:

{
  "operation": "scanBreakouts",
  "scanAllSymbols": true,
  "interval": "1h",
  "candleCount": 300,
  "pivotStrength": 3,
  "breakoutLookbackCandles": 20,
  "direction": "both"
}

Complete-market runs pace candle requests according to Hyperliquid's documented IP-based request weights. This trades a few minutes of runtime for materially fewer rate-limit errors; a manual watchlist is not given this additional delay.

API example

For a synchronous watchlist request that returns dataset items directly:

curl -X POST \
  -H 'Authorization: Bearer YOUR_APIFY_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "operation": "scanBreakouts",
    "symbols": ["BTC", "ETH", "SOL"],
    "interval": "1h",
    "candleCount": 300,
    "pivotStrength": 3,
    "breakoutLookbackCandles": 20,
    "direction": "both"
  }' \
  'https://api.apify.com/v2/acts/bb-tradetec~hyperliquid-swing-breakout-scanner/run-sync-get-dataset-items'

Use the asynchronous /runs endpoint for workflows that should not keep the client connection open while a complete-market scan is running.

Detection rules

A swing uses a strict, symmetric pivot rule. With pivotStrength = 3, a swing high must be strictly above the three candles on each side; a swing low must be strictly below them. Equal highs or lows disqualify the pivot.

The pivot becomes usable only after its full right-side window has closed. pivotTime identifies the central candle, while confirmedAt or pivotConfirmedAt identifies when the level actually became observable.

A bullish breakout requires a later closed candle with close > swingHighLevel. A bearish breakout requires close < swingLowLevel. Wick-only moves and closes exactly on the level do not count. Each level creates at most one event. One candle may break several older levels.

Only candles closed by the captured run time are analysed. The Actor uses exact decimal comparisons and does not move confirmations backward in time.

Input

Field	Default	Limits	Meaning
operation	scanBreakouts	scanBreakouts, listSymbols	Selects the operation. Scan fields are ignored by listSymbols.
scanAllSymbols	false	true, false	For scanBreakouts, fetches and scans every currently active standard perpetual. When true, symbols is ignored.
symbols	BTC, ETH, SOL	1–20	Manual watchlist used when scanAllSymbols is false.
interval	1h	5m, 15m, 30m, 1h, 4h, 1d	One timeframe per run.
candleCount	300	50–500	Recent closed candles requested per symbol.
pivotStrength	3	1–10	Strict candles required on both sides of a pivot.
breakoutLookbackCandles	20	1–200, no greater than candleCount	Maximum returned breakout age. 1 means the newest closed candle only.
direction	both	both, bullish, bearish	Filters returned events and grouped breakout summaries.

Common symbol names are trimmed and uppercased. Hyperliquid names with a lowercase k prefix retain that prefix. If fewer usable candles than requested are available, the result contains a warning. After a data gap, only the newest contiguous candle segment is analysed.

Output

The output contract is schemaVersion: "1.1". Breakout detection remains engineVersion: "swing-breakout-v1".

A successful scanBreakouts row contains:

• latest closed candle and latest confirmed swing high and low;
• breakouts: one detailed event per broken level;
• summary: grouped and contextual views derived from the same data;
• counts, warnings, and scan metadata.

The eight summary views are:

1. broken level count, unique breakout candle count, and maximum levels broken by one candle;
2. latest grouped breakout;
3. bullish and bearish totals for both levels and unique candles;
4. nearest unbroken swing high and swing low, with distance and age;
5. pivot age when each breakout occurred;
6. breakout volume and trades versus median volume of up to 20 prior candles;
7. candle range, body share, and close position;
8. one chronological group per breakout candle with all crossed levels.

These summaries require no additional network call. The detailed breakouts array remains available for granular event processing and deterministic deduplication.

Important field semantics

• ageCandles: closed candles since the breakout; 0 is the newest candle.
• pivotAgeAtBreakoutCandles: candles from pivot confirmation to breakout; the first eligible candle is 1.
• distancePct: absolute close-to-level distance; it is not a quality score.
• volumeRatio: breakout volume divided by median volume of up to 20 immediately preceding candles. The breakout candle is excluded.
• rangePct: candle range divided by open price.
• bodyPctOfRange: absolute candle body divided by range.
• closePositionPct: close position from low (0) to high (100).
• nearestActiveSwingHigh and nearestActiveSwingLow: closest unbroken levels to the latest close, independent of the breakout direction filter.

Prices, volumes, ratios, and percentages are serialized as decimal strings to preserve precision. Percentages are rounded to six decimal places and rendered without unnecessary trailing zeroes.

The Actor's Input, API, and Dataset tabs expose the complete machine-readable contracts. The Dataset tab also provides separate table views for scan results and available symbols.

Errors

A symbol-level failure uses status: "error", summary: null, and a structured error object without removing successful rows for other symbols. Stable codes include http_error, rate_limited, network_error, invalid_response, no_candles, insufficient_closed_data, insufficient_contiguous_data, and conflicting_duplicate_candle.

The run fails only if no requested symbol produces a successful result; the error rows are stored first.

Using the results

Read results from the default dataset through the Apify Console, Actor API, client libraries, integrations, or export endpoints. Typical uses include:

• watchlists and monitoring dashboards;
• notification and webhook workflows;
• reproducible research datasets;
• scheduled cross-market scans;
• downstream ranking with user-defined criteria.

The Actor deliberately provides transparent measurements rather than an opaque signal-quality or profitability score.

Local development

Python 3.13 is required.

python3.13 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
python -m pytest --cov=hyperliquid_scanner --cov-report=term-missing
ruff check .
ruff format --check .
mypy src
apify validate-schema
apify run

The release container installs the hash-locked third-party Python 3.13 Linux dependency set from pylock.toml, then installs the local package without re-resolving dependencies. pyproject.toml retains compatible version ranges for editable development installs.

The normal test suite is offline. The separate public API smoke test is opt-in:

$RUN_LIVE_TESTS=1 python -m pytest -m live

Local Actor input is read from storage/key_value_stores/default/INPUT.json. Runtime dataset files are ignored project artifacts.

Contracts and versioning

Actor 0.4 adds automatic all-symbol scanning while preserving the manual watchlist mode. Actor 0.3 added derived summaries and context. Both retain the swing-breakout-v1 detection rule; symbol discovery was introduced in Actor 0.2.