Triggers (Conditions + Indicators)

In Auto, a trigger is a condition tree that evaluates continuously. When the tree resolves to true, configured actions run.

Market Coverage

Auto monitors symbols across connected exchanges — crypto perp markets (Hyperliquid, GMX, Binance), plus tokenised equities, indices, commodities, FX, and pre-IPO names listed as HIP-3 markets (xyz:NVDA, xyz:SP500, xyz:GOLD). Those trade 24/7, even when the underlying cash market is closed — see Catalyst Triggers. See Symbols for asset classes, examples, and how to verify a specific ticker.

price and ta conditions select their data venue via the required exchange arg (hyperliquid, gmx, or binance). See Exchange Argument (price / ta).

The funding and liquidation sources read a wider set of venues (including Binance and Bybit) and select the venue differently — via a composite SYMBOL:EXCHANGE ticker rather than an exchange arg. See Funding and Liquidations.

Trigger Shape

All triggers are expressed as conditions with a root boolean group:

{
  "conditions": {
    "AND": [
      {
        "source": "ta",
        "method": "rsi",
        "args": { "symbol": "BTC", "timeframe": "1h", "period": 14 },
        "operator": "<",
        "value": 30
      }
    ]
  }
}

Rules:

Root group must be AND or OR.
Groups can be nested.
Max condition tree depth: 3.
Max leaf conditions per query: 10.

Supported Condition Sources

Price Source (`price`)

Method	Arguments	Returns	Description
`current`	`symbol`, `exchange`	`number`	Current market price
`change`	`symbol`, `period`, `exchange`	`number`	Percent price change over period
`high`	`symbol`, `period`, `exchange`	`number`	Highest price in period
`low`	`symbol`, `period`, `exchange`	`number`	Lowest price in period
`volume`	`symbol`, `period`, `exchange`	`number`	Volume in USD over period. Not available on `gmx`.

exchange is required on all price methods — see Exchange Argument (price / ta).

TA Source (`ta`) - Indicator Methods

Indicator method	Arguments	Returns	Description
`rsi`	`symbol`, `timeframe`, `period?`, `exchange`	`number`	RSI (0-100), default `period=14`
`macd_value`	`symbol`, `timeframe`, `exchange`	`number`	MACD line value
`macd_signal`	`symbol`, `timeframe`, `exchange`	`number`	MACD signal line
`macd_histogram`	`symbol`, `timeframe`, `exchange`	`number`	MACD histogram
`bbands_upper`	`symbol`, `timeframe`, `period?`, `exchange`	`number`	Upper Bollinger Band
`bbands_middle`	`symbol`, `timeframe`, `period?`, `exchange`	`number`	Middle Bollinger Band
`bbands_lower`	`symbol`, `timeframe`, `period?`, `exchange`	`number`	Lower Bollinger Band
`ema`	`symbol`, `timeframe`, `period`, `exchange`	`number`	Exponential moving average
`sma`	`symbol`, `timeframe`, `period`, `exchange`	`number`	Simple moving average
`atr`	`symbol`, `timeframe`, `period?`, `exchange`	`number`	Average true range
`stoch_k`	`symbol`, `timeframe`, `exchange`	`number`	Stochastic %K
`stoch_d`	`symbol`, `timeframe`, `exchange`	`number`	Stochastic %D
`cci`	`symbol`, `timeframe`, `period?`, `exchange`	`number`	Commodity Channel Index
`willr`	`symbol`, `timeframe`, `period?`, `exchange`	`number`	Williams %R

exchange is required on all ta methods — see Exchange Argument (price / ta).

Signal Source: X/Twitter Post (`tweet`)

In the builder catalog, this appears in the Signal category as X/Twitter Post.

Method	Arguments	Returns	Description
`semantic`	`username`, `text`, `minConfidence`	`boolean`	Matches posts from a specific X/Twitter account when semantic confidence meets threshold

Notes:

username should be passed without @ (for example cz_binance).
username must resolve to an active monitored account, otherwise validation/create fails.
minConfidence must be an integer from 0 to 100.

Default condition shape:

{
  "source": "tweet",
  "args": {
    "username": "cz_binance",
    "text": "Binance Alpha is listing a new token",
    "minConfidence": 80
  }
}

Signal Source: Event (`news`)

In the builder catalog, this appears in the Signal category as Event.

Method	Arguments	Returns	Description
`semantic`	`text`, `minConfidence`	`boolean`	Matches event-like mentions from news-tagged sources when semantic confidence meets threshold

Notes:

Event matching is based on news-tagged sources.
minConfidence must be an integer from 0 to 100.

Default condition shape:

{
  "source": "news",
  "args": {
    "text": "SEC approves a spot ETH ETF",
    "minConfidence": 80
  }
}

TA Args Contract

This is the exact args contract validated by Athena for TA methods.

Every method below also requires an exchange:string arg (hyperliquid, gmx, or binance). It is listed under required args for each method — see Exchange Argument (price / ta).

Method	Required args	Optional args	Notes
`rsi`	`symbol:string`, `timeframe:string`, `exchange:string`	`period:number` (default `14`)	`period` is optional.
`macd_value`	`symbol:string`, `timeframe:string`, `exchange:string`	None	Uses MACD defaults internally.
`macd_signal`	`symbol:string`, `timeframe:string`, `exchange:string`	None	Uses MACD defaults internally.
`macd_histogram`	`symbol:string`, `timeframe:string`, `exchange:string`	None	Uses MACD defaults internally.
`bbands_upper`	`symbol:string`, `timeframe:string`, `exchange:string`	`period:number` (default `20`)	`period` is optional.
`bbands_middle`	`symbol:string`, `timeframe:string`, `exchange:string`	`period:number` (default `20`)	`period` is optional.
`bbands_lower`	`symbol:string`, `timeframe:string`, `exchange:string`	`period:number` (default `20`)	`period` is optional.
`ema`	`symbol:string`, `timeframe:string`, `period:number`, `exchange:string`	None	`period` is required.
`sma`	`symbol:string`, `timeframe:string`, `period:number`, `exchange:string`	None	`period` is required.
`atr`	`symbol:string`, `timeframe:string`, `exchange:string`	`period:number` (default `14`)	`period` is optional.
`stoch_k`	`symbol:string`, `timeframe:string`, `exchange:string`	None	No period argument in EQL.
`stoch_d`	`symbol:string`, `timeframe:string`, `exchange:string`	None	No period argument in EQL.
`cci`	`symbol:string`, `timeframe:string`, `exchange:string`	`period:number` (default `20`)	`period` is optional.
`willr`	`symbol:string`, `timeframe:string`, `exchange:string`	`period:number` (default `14`)	`period` is optional.

Exchange Argument (`price` / `ta`)

Both price and ta conditions require an exchange arg that selects which venue's market data backs the condition.

Property	Value
Arg name	`exchange`
Type	`string`
Required	Yes
Allowed values	`hyperliquid`, `gmx`, `binance`

Use it to read the same indicator from a different venue — for example, evaluate RSI on gmx rather than hyperliquid.

Per-venue notes:

binance reads its USD-M perp markets, and uses Binance's own base-symbol convention — 1000PEPE, not kPEPE. Symbols are validated against Binance's live perp catalog at create time.
price.volume is not available on gmx — GMX bars carry no per-bar volume. Use hyperliquid or binance for volume conditions.
pacifica is not a data venue — it is execution-only. See Supported Venues.

{
  "source": "price",
  "method": "low",
  "args": { "symbol": "BTC", "period": "1h", "exchange": "gmx" },
  "operator": "<",
  "value": 98000
}

{
  "source": "ta",
  "method": "rsi",
  "args": { "symbol": "BTC", "timeframe": "1h", "period": 14, "exchange": "hyperliquid" },
  "operator": "<",
  "value": 30
}

Notes:

exchange only affects the data source of a price/ta condition. It is independent of where market_order / limit_order actions execute (those carry their own required exchange param — see Trading Execution).
Use the exact lowercase enum values (hyperliquid, gmx, or binance).

Validation Errors → Next Action

When Validate Query or Create rejects a query, the error is almost always a phrasing issue — not a capability gap. Iterate on Validate instead of abandoning the query.

Error signal	What it means	Next action
`EQL_MISSING_ARG`	A required arg is absent (e.g. `period` on `ema`/`sma`).	Check TA Args Contract, add the missing arg, re-validate.
`EQL_INVALID_ARG` / type errors	Wrong type (e.g. `"14"` instead of `14`) or unrecognized key (e.g. `length` vs `period`).	Use the exact key names and JSON numeric types from the contract table.
Unknown `method`	Indicator name not supported.	Pick the nearest supported method from TA Source; ask Builder Chat to substitute.
Unsupported `timeframe` / `period`	Value outside the enum.	Snap to the nearest allowed value — see Timeframe and Period Enums.
Unsupported `symbol` / source	Asset not indexed or DEX pair unsupported.	Skip that symbol and report it; proceed with the supported subset (see capabilities prompt pack for the "skip unsupported" pattern).
Unmonitored `tweet` username	`tweet.semantic` account is not in the monitored active account set. Rejected at both Validate and Create.	Replace with a monitored active handle and re-validate.
`kalshi` ticker not open (`EQL_INVALID_ARG_VALUE`)	`args.ticker` is not a currently-open Kalshi market (closed/settled/unknown).	Use a currently-open full ticker — see Prediction Markets: Open Markets Only. Don't guess tickers.
`kalshi` invalid enum / operator	Enum `value` outside its set, or operator not in the method's allowlist (e.g. `crosses_above` on `trade_size`).	Use the per-method allowlists in Prediction Markets → Kalshi.
`polymarket` ticker not found / not active	`args.ticker` is not a live Polymarket outcome token (`asset_id`).	Use a currently-active outcome-token id — see Prediction Markets → Polymarket. Don't guess ids.
`polymarket` invalid operator / dynamic value	Operator not in the method's allowlist, or a dynamic (field-vs-field) `value` was used.	Use the per-method allowlists in Polymarket Operators; use a literal `value` (dynamic values are unsupported for `polymarket`).
Invalid `minConfidence` (`tweet`/`news`)	Confidence is non-integer or outside `0..100`.	Use an integer between `0` and `100` (start with `80`).
Depth / leaf-count exceeded	More than depth 3 or 10 leaves.	Split into two queries joined by your runner, or factor shared conditions out.
`cron` / `llm` period too short	Below 1h minimum.	Raise to `1h` or higher — see Scheduling Period.
`cron.schedule` cadence too fast	Minute field isn't a single fixed value (e.g. `/15 * * *`), or a sub-hour cadence.	Use a single fixed minute — see Cron Source allowed/not-allowed examples.
`EQL_INVALID_REPEAT`	`repeat` was combined with a recurring cron condition (`cron.every` / `cron.schedule`).	Both provide recurrence — remove `repeat` (cron already recurs), or drop the cron condition. `repeat` is allowed on trade actions. See Repeat.
`SYMBOL_CATALOG_UNAVAILABLE` (HTTP `503`)	The market catalog was temporarily unreachable, so the symbol could not be checked. Validation fails closed rather than letting an unverified symbol through.	Retry after the interval in the `Retry-After` header. This is transient — do not reshape the query.
HIP-3 ticker on `funding` / `liquidation` (`EQL_INVALID_ARG_VALUE`, `details.hip3: true`)	Dex-prefixed HIP-3 symbols are not published by the funding/liquidation feeds, so the condition could never fire.	Use a plain base symbol (e.g. `BTC:BINANCE`). HIP-3 remains supported on `price`/`ta` — see HIP-3 symbols.
Unknown symbol in a composite ticker	The symbol is not listed on that venue's perp catalog (often a naming mismatch).	Check the venue's own base-symbol convention — `1000PEPE` on Binance/Bybit vs `KPEPE` on Hyperliquid.
Dynamic value in action params	Dynamic values only allowed in condition `value`.	Move the dynamic reference into a condition; keep action params literal.

General rule: if Validate returns an error, reshape and re-validate in a loop — do not create your own monitoring stack. See also If /auto doesn't fit.

Common TA Arg Errors

ema and sma require period; length is not a recognized alias.
period must be a JSON number (for example 14), not a string ("14").
timeframe is required for all TA methods.

Invalid EMA example (length used, period missing):

{
  "source": "ta",
  "method": "ema",
  "args": { "symbol": "BTC", "timeframe": "1h", "length": 20 },
  "operator": ">",
  "value": 100000
}

Expected validation failure:

EQL_MISSING_ARG for period on method ema

Valid EMA example:

{
  "source": "ta",
  "method": "ema",
  "args": { "symbol": "BTC", "timeframe": "1h", "period": 20 },
  "operator": ">",
  "value": 100000
}

Cron Source (`cron`)

Method	Arguments	Returns	Description
`once`	`period`	`boolean`	True on first due evaluation at/after `createdAt + period`
`onceRemainTrue`	`period`	`boolean`	True on first due evaluation and remains true afterward
`every`	`period`	`boolean`	True at each period interval from query creation
`schedule`	`expression`, `timezone?`	`boolean`	True whenever the 5-field cron `expression` matches in `timezone`

once, onceRemainTrue, and every are interval methods measured from query creation (see Scheduling Period). schedule is a calendar/wall-clock method:

expression is a classic 5-field cron string (minute hour day-of-month month day-of-week) — for example 0 9 * * 1-5 (weekdays at 09:00).
timezone is optional and defaults to UTC. When set it must be a valid IANA name (e.g. America/New_York, Europe/London, Asia/Singapore) so daylight-saving transitions are handled correctly. Fixed-offset strings like +02:00 are not accepted.
schedule enforces the same 1h-minimum cadence as the other cron methods: the minute field must be a single fixed value (0–59). Wildcards, steps, lists, or ranges in the minute field (which fire multiple times per hour) are rejected. You choose which minute past the hour a run lands on.
- Allowed: 7 * * * * (hourly at minute 7), 0 9 * * 1-5 (weekdays 09:00), 30 8 * * * (daily 08:30).
- Not allowed: * * * * * (every minute), */15 * * * * (every 15 min), 0,30 * * * * (twice per hour).
schedule takes no period arg.

Builder Chat support pending

cron.schedule is available on the direct EQL/API path (Validate / Create). Builder Chat does not yet reliably generate cron.schedule — if you need a calendar/wall-clock schedule today, author the condition directly and confirm it with Validate Query.

LLM Source (`llm`)

Method	Arguments	Returns	Description
`athena_condition`	`query`, `period`, `speed?`	`boolean`	LLM-evaluated condition

Note:

cron, llm, tweet, and news support shorthand forms and are expanded server-side.
period for cron and llm sources has a minimum of 1h. See Scheduling Period (cron / llm) for the allowed set.
For clearer runtime semantics and easier debugging, prefer separate queries for event-driven Signal intents (tweet/news) and recurring schedule intents (cron.every).

Prediction Markets Source (`kalshi`)

Trigger on Kalshi prediction-market activity. Each method takes a single ticker arg (a full open Kalshi market ticker, e.g. KXBTC-26APR0803-T77799.99).

Trade-backed: yes_price, no_price, trade_size, taker_outcome_side, taker_book_side, is_block_trade
Market-backed: status, result, settlement_value

A plan can only be created against a market that is currently open — closed/settled tickers are rejected at validation. Operators are restricted per method (price methods support crosses_above/crosses_below; enum/boolean methods are equality-only).

Full method tables, operator allowlists, value enums, and example automations: Prediction Markets → Kalshi.

Prediction Markets Source (`polymarket`)

Trigger on Polymarket outcome-token activity. Each method takes a single ticker arg — the outcome token asset_id (a long numeric id), not the top-level market id.

Methods: price, bid, ask (number), size (number), side (enum "BUY"/"SELL")

A plan can only be created against a live outcome token — unknown/inactive tokens are rejected at validation. Operators are restricted per method (price/bid/ask support crosses_above/crosses_below; size is level-only; side is equality-only). Polymarket does not support dynamic (field-vs-field) values.

Full method tables, operator allowlists, value enums, and example automations: Prediction Markets → Polymarket.

Funding Source (`funding`)

Trigger on perp funding rates — an overheated long bias, a flip to negative, or a cross-venue divergence. Each method takes a single composite ticker of the form SYMBOL:EXCHANGE (e.g. BTC:BINANCE, ETH:HYPERLIQUID).

Venues: binance, hyperliquid
Methods: annualized_rate (canonical — percent APR, venue-comparable), interval_rate, interval_hours, exchange

Prefer annualized_rate: Binance settles funding every 8h and Hyperliquid every 1h, so the same interval_rate threshold means different things per venue. "Funding flips negative" is annualized_rate crosses_below 0.

Full method tables, operator allowlists, ticker rules, and examples: Funding and Liquidations → Funding.

Liquidation Source (`liquidation`)

Trigger on liquidation flow in a trailing window — a cascade crossing a USD threshold, a one-sided flush, or liquidations as a share of open interest. Same composite SYMBOL:EXCHANGE ticker as funding.

Venues: binance, bybit, hyperliquid
USD methods: total_usd_1m/5m/1h, long_usd_1m/5m/1h, short_usd_1m/5m/1h, largest_order_usd_1h
Other methods: count_1h (level operators only), total_pct_oi_1m/5m/1h (percent of open interest), exchange

Two things to know before setting a threshold: feed quality differs by venue (Binance is sampled, so its values are a lower bound; Bybit and Hyperliquid are complete), and windows decay to zero, so a repeat plan fires once per cascade rather than once ever.

Full method tables, the per-venue feed-quality table, and examples: Funding and Liquidations → Liquidation.

Fear & Greed Source (`fear_greed`)

Trigger on the market-wide Crypto Fear & Greed Index.

This is a keyless source — the index is one global reading with no per-market identity, so its methods take no ticker. Pass an empty args: {}.

Method	Arguments	Returns	Description
`value`	(none)	`number`	The index score, an integer `0`–`100` (0 = extreme fear, 100 = extreme greed)
`classification`	(none)	`enum`	The bucket label — see below

Notes:

value accepts all eight operators. classification accepts only == / !=, and its value must be one of: "Extreme fear", "Fear", "Neutral", "Greed", "Extreme greed".
The labels map to fixed value bands — Extreme fear 0–19, Fear 20–39, Neutral 40–59, Greed 60–79, Extreme greed 80–100 — so a numeric threshold and the matching classification are interchangeable. Prefer value when you want a precise threshold.
The index updates roughly every 15 minutes, so conditions react at that cadence. A newly created condition has no observed value until the first reading arrives, and a crosses_above / crosses_below leaf needs a prior reading to compare against — so it can only fire on the second reading after activation.
fear_greed does not support dynamic values.

{
  "source": "fear_greed",
  "method": "value",
  "args": {},
  "operator": "crosses_below",
  "value": 20
}

Supported Operators

>
<
>=
<=
==
!=
crosses_above
crosses_below

Cross operators use previous-state tracking and evaluate transitions:

crosses_above: previous < threshold and current >= threshold
crosses_below: previous > threshold and current <= threshold

Dynamic Comparisons (Dynamic Values)

value does not need to be a static literal. It can also reference another data source result at evaluation time.

This lets you compare one live metric against another live metric, for example current price vs. an indicator band.

Example: trigger when ETH price crosses above the current 4h upper Bollinger Band.

{
  "conditions": {
    "AND": [
      {
        "source": "price",
        "method": "current",
        "args": { "symbol": "ETH" },
        "operator": "crosses_above",
        "value": {
          "source": "ta",
          "method": "bbands_upper",
          "args": { "symbol": "ETH", "timeframe": "4h" }
        }
      }
    ]
  }
}

Important:

Dynamic values are supported only in condition value.
Dynamic values are not supported in action parameters.

Timeframe and Period Enums

TA timeframe values:

1m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 12h, 1d

period values for price args and TA indicator lookbacks:

1h, 2h, 4h, 8h, 12h, 24h, 1d, 7d

Scheduling Period (`cron` / `llm`)

For cron interval methods (once, onceRemainTrue, every) and llm sources, period is a scheduling interval with a minimum of 1h.

Allowed values:

1h, 2h, 4h, 8h, 12h, 24h, 1d, 7d

cron.schedule does not take a period — it is driven by its 5-field cron expression and follows the same 1h-minimum cadence (at most one fire per hour). See Cron Source.

Signal Match-Description Guidance

For X/Twitter Post and Event, write args.text as a short factual claim.

X/Twitter Post examples:

bad: Bearish vibes -> good: Opens a short position on oil
bad: Something bullish -> good: Announces a new stake in TSLA
bad: Bullish on a coin -> good: Posts that they're bullish on $HYPE and $SOL

Event examples:

bad: Market crash -> good: Major DeFi protocol suffers a $200M exploit
bad: War conflict -> good: US imposes new sanctions on Russia
bad: Big news -> good: SEC approves a spot ETH ETF

Market Coverage​

Trigger Shape​

Supported Condition Sources​

Price Source (price)​

TA Source (ta) - Indicator Methods​

Signal Source: X/Twitter Post (tweet)​

Signal Source: Event (news)​

TA Args Contract​

Exchange Argument (price / ta)​

Validation Errors → Next Action​

Common TA Arg Errors​

Cron Source (cron)​

LLM Source (llm)​

Prediction Markets Source (kalshi)​

Prediction Markets Source (polymarket)​

Funding Source (funding)​

Liquidation Source (liquidation)​

Fear & Greed Source (fear_greed)​

Supported Operators​

Dynamic Comparisons (Dynamic Values)​

Timeframe and Period Enums​

Scheduling Period (cron / llm)​

Signal Match-Description Guidance​

Related Docs​

Market Coverage

Trigger Shape

Supported Condition Sources

Price Source (`price`)

TA Source (`ta`) - Indicator Methods

Signal Source: X/Twitter Post (`tweet`)

Signal Source: Event (`news`)

TA Args Contract

Exchange Argument (`price` / `ta`)

Validation Errors → Next Action

Common TA Arg Errors

Cron Source (`cron`)

LLM Source (`llm`)

Prediction Markets Source (`kalshi`)

Prediction Markets Source (`polymarket`)

Funding Source (`funding`)

Liquidation Source (`liquidation`)

Fear & Greed Source (`fear_greed`)

Supported Operators

Dynamic Comparisons (Dynamic Values)

Timeframe and Period Enums

Scheduling Period (`cron` / `llm`)

Signal Match-Description Guidance

Related Docs