Funding and Liquidations

Two condition sources let an Auto query trigger on perp market structure rather than on price:

• Funding (source: "funding") — trigger on a perp's funding rate: an overheated long bias, a flip to negative, a cross-venue divergence.
• Liquidation (source: "liquidation") — trigger on liquidation flow: a cascade crossing a USD threshold in a trailing window, a one-sided long flush, or liquidations measured as a share of open interest.

Both are useful precisely when spot price hasn't moved yet — funding and liquidation flow often lead the price reaction.

Both sources use the full EQL condition form and obey the standard limits: they combine with other sources inside AND/OR groups, up to depth 3 and 10 leaf conditions. See Triggers.

Composite Tickers

Unlike price and ta — which take a symbol plus a separate exchange arg — these two sources take a single composite ticker that carries the venue:

{SYMBOL}:{EXCHANGE}

For example BTC:BINANCE, ETH:HYPERLIQUID, SOL:BYBIT. The venue rides in the ticker because each venue's readings are tracked independently; a bare symbol would let two venues overwrite each other.

Rules:

• SYMBOL is the base asset (BTC, not BTCUSDT).
• Tickers are case-insensitive on input and normalized to uppercase.
• Use each venue's own base-symbol convention. The multiplied-ticker variants differ: 1000PEPE on Binance and Bybit, but KPEPE on Hyperliquid.

Ticker validation

At Validate and Create time, Athena checks the ticker in three steps:

1. Shape — must be SYMBOL:EXCHANGE.
2. Venue — must be one of the venues supported by that source (below).
3. Symbol existence — the symbol must be listed on that venue's perp catalog. A typo'd symbol is rejected rather than accepted into a plan that could never fire.

If the market catalog is temporarily unavailable, validation fails closed with a 503 — it does not let an unchecked ticker through. Retry the request.

HIP-3 symbols are not supported here

HIP-3 (dex-prefixed) symbols such as xyz:PLTR are rejected for funding and liquidation, with EQL_INVALID_ARG_VALUE and details.hip3: true.

This is worth stating plainly because it is genuinely surprising: HIP-3 assets are real Hyperliquid perps and they do appear in the market catalog — but the funding and liquidation feeds never publish keys for them, so a condition on one could never fire. Athena rejects them up front instead of accepting a dead plan.

The contrast with the rest of Auto is the confusing part:

Source	HIP-3 symbols (e.g. xyz:PLTR)
price / ta	Supported — see Symbols
Trade actions (market_order / limit_order)	Supported
funding / liquidation	Rejected

Funding (funding)

Perp funding-rate readings, published on change per market.

Venues: binance, hyperliquid.

Methods

Method	Arguments	Returns	Operators	Description
annualized_rate	ticker	number	All 8	Canonical. Funding rate as annualized percent (APR): 32.85 means 32.85% APR. Positive = longs pay shorts.
interval_rate	ticker	number	All 8	Percent per settlement interval.
interval_hours	ticker	number	Level only	Settlement interval in hours: 8 (Binance) or 1 (Hyperliquid). Venue metadata, not a time series.
exchange	ticker	enum	== / !=	The venue: "binance" or "hyperliquid".

"All 8" means the full operator set including crosses_above / crosses_below. "Level only" means >, <, >=, <=, ==, != — no crosses.

Prefer annualized_rate

annualized_rate is the method to reach for by default. It is venue-comparable: Binance settles funding every 8 hours and Hyperliquid every hour, so the same interval_rate threshold means very different things on the two venues. Annualizing removes that trap. Use interval_rate only when you specifically care about the per-settlement charge.

Because each reading is a fresh observation, crosses carry real meaning here — "funding flips negative" is exactly annualized_rate crosses_below 0.

Examples

Funding flips negative on Binance BTC (shorts start paying longs):

{
  "title": "BTC funding flips negative",
  "description": "Shorts are now paying longs on Binance BTC — crowded-short signal worth a look.",
  "conditions": {
    "AND": [
      {
        "source": "funding",
        "method": "annualized_rate",
        "args": { "ticker": "BTC:BINANCE" },
        "operator": "crosses_below",
        "value": 0
      }
    ]
  },
  "actions": [
    {
      "stepId": "step_1",
      "type": "notify",
      "params": { "message": "BTC funding on Binance flipped negative" }
    }
  ],
  "expiresIn": "7d"
}

Overheated funding on Hyperliquid ETH — longs paying more than 30% APR:

{
  "source": "funding",
  "method": "annualized_rate",
  "args": { "ticker": "ETH:HYPERLIQUID" },
  "operator": ">",
  "value": 30
}

Liquidation (liquidation)

Trailing-window liquidation aggregates. The feed publishes decaying snapshots roughly every 10 seconds while a window is active, plus a final all-zero snapshot once the trailing hour drains.

Venues: binance, bybit, hyperliquid.

Methods

All USD methods are USD notional sums over a trailing window.

Method	Arguments	Returns	Operators	Description
total_usd_1m / total_usd_5m / total_usd_1h	ticker	number	All 8	Total USD liquidated in the trailing window.
long_usd_1m / long_usd_5m / long_usd_1h	ticker	number	All 8	Longs liquidated (forced selling).
short_usd_1m / short_usd_5m / short_usd_1h	ticker	number	All 8	Shorts liquidated (forced buying).
largest_order_usd_1h	ticker	number	All 8	Single biggest liquidation order in the trailing hour, USD.
count_1h	ticker	number	Level only	Number of liquidation orders in the trailing hour.
total_pct_oi_1m / total_pct_oi_5m / total_pct_oi_1h	ticker	number	All 8	Total liquidated in the window as a percent of open interest.
exchange	ticker	enum	== / !=	The venue: "binance", "bybit", or "hyperliquid".

Feed quality differs by venue — read thresholds accordingly

This is the most important thing to understand about liquidation data, and it is not a detail you can safely skip:

Venue	Feed	What the numbers mean
BINANCE	Sampled — at most one liquidation per symbol per second is published	Values are a lower bound on true flow, and undercount most during exactly the cascades you care about
BYBIT	Complete — every liquidation	Exact per-venue totals
HYPERLIQUID	Complete — every liquidation fill	Exact per-venue totals

Binance thresholds still order correctly — if you observe $500k, at least $500k really happened — so a crosses_above threshold remains a valid trigger. Just never read a Binance value as an exact total, and expect to set a lower threshold than you would on Bybit for the same real-world event.

Normalized metrics (total_pct_oi_*)

These divide the window's USD total by the venue's open interest for that symbol. Two reasons to prefer them over raw USD:

• They compare across symbols. 1% of open interest is a violent flush whether the symbol is BTC or a small cap. A $10m USD threshold is meaningless on one and apocalyptic on the other.
• They stay meaningful as coverage grows. Raw USD baselines inflate as more venues are added, silently loosening a total_usd_* threshold you set months ago.

Typical magnitudes are small — calibrate accordingly. Roughly 0.1% of open interest liquidated in an hour is already heavy for a major; small caps can reach several percent during a cascade. Starting at 1 (i.e. 1%) will almost never fire on BTC.

On Binance these values are biased low (the numerator is sampled, the denominator is exact).

Decay semantics: one fire per cascade

Snapshots decay as events age out of the trailing window, and the final all-zero snapshot un-meets >-style conditions and re-arms crosses. This has a useful consequence: a repeat plan on a liquidation condition fires once per cascade, not once ever and not once per snapshot — the condition naturally resets when the cascade subsides.

Examples

Liquidation cascade — re-fires on each new cascade:

{
  "title": "BTC liquidation cascade (5m > $100k)",
  "description": "Alert each time BTC liquidations cross $100k in a 5-minute window on Binance.",
  "conditions": {
    "AND": [
      {
        "source": "liquidation",
        "method": "total_usd_5m",
        "args": { "ticker": "BTC:BINANCE" },
        "operator": "crosses_above",
        "value": 100000
      }
    ]
  },
  "actions": [
    {
      "stepId": "step_1",
      "type": "notify",
      "params": { "message": "BTC liquidations crossed $100k in 5m on Binance" }
    }
  ],
  "expiresIn": "7d",
  "repeat": { "cooldown": "1h", "maxTriggers": 10 }
}

One-sided long flush on Hyperliquid ETH (complete feed, so this is an exact total):

{
  "source": "liquidation",
  "method": "long_usd_1h",
  "args": { "ticker": "ETH:HYPERLIQUID" },
  "operator": ">",
  "value": 1000000
}

Normalized: more than 0.5% of open interest liquidated in an hour:

{
  "source": "liquidation",
  "method": "total_pct_oi_1h",
  "args": { "ticker": "SOL:BYBIT" },
  "operator": "crosses_above",
  "value": 0.5
}

Limitations

• Neither source supports dynamic values (comparing one field against another live field). Use a literal value.
• Funding is streamed for Binance and Hyperliquid only. Other venues' funding is not conditionable.

Related Docs

• Triggers (Conditions + Indicators)
• Symbols
• Query Model and Templates
• Prediction Markets