Language structure

LiSA Script is Hey-LiSA’s machine-readable strategy language. AI agents use it to turn a trader’s natural-language instructions into structured strategies. It is not intended for traders to write by hand. This reference documents the contract agents generate and Hey-LiSA validates, backtests, and executes.

LiSA Script strategies are JSON documents made of ordered rules. DCA currently uses version 2 and Trading uses version 8. Both require an explicit category and use separate validated contracts.

Shared fields

Field	Purpose
`version`	Category contract version: `2` for DCA and `8` for Trading.
`type`	Must be `"strategy"`.
`category`	Must be `"dca"` or `"trading"`. It is authored and not inferred from labels or actions.
`name`	Human-readable strategy name.
`compact_description`	Short card summary.
`description`	Longer report description.
`labels`	Authored strategy classification IDs used on cards and by filters. DCA requires its category-specific labels; Trading permits an empty array.
`market`	Current market, currently `"BTC"`.
`timeframe`	Strategy timeframe. DCA uses `"1d"`; Trading accepts `"1d"` or `"4h"`.
`execution`	Simulated fill timing and cost assumptions.
`indicators`	Built-in technical indicator declarations.
`rules`	Ordered decision and action rules.
`constraints`	Backtest start and end bounds.

Names are the readable labels shown in reports. Hey-LiSA generates internal structural IDs for evaluation, traces, reports, and graph layout. LiSA Script does not accept authored rule, branch, IF, action, or condition IDs.

DCA category

A DCA strategy uses:

category: "dca"
portfolio with USDC starting cash
optional external_series
DCA actions such as cashflow, buy, sell, and set
direct actions, ordered actions, condition gates, branches, and nested IF rules

Every current DCA strategy includes the authored btc label and exactly one authored style label, dca or special. Optional study and technical labels use stable IDs such as fear-greed-study and indicator:ma. Cards and filters expose only labels present in the strategy’s labels array; indicator declarations and rule expressions do not generate labels.

"labels": ["btc", "dca", "fear-greed-study"]

Trading category

A Trading strategy uses:

category: "trading"
an explicit timeframe of "1d" or "4h"
account with a positive USDC starting balance
open_position with a required authored lifecycle_description, and close_position
optional authored marker_template text on each chartable Trading instruction, with typed entry-notional and event-local exit-PnL placeholders; omission means that event has no chart marker
simple ordered rules containing named conditions and one named action
optional ordered, named exit_conditions groups written inline on an open_position
position_state() in Trading rules and position-bound exits to identify the current flat, long, or short state
percent_equity sizing with explicit leverage: 1, or risk_percent_equity_at_stop sizing with leverage derived from the resolved stop

Trading requires a labels array but permits it to be empty. Collection members author their collection explicitly: the stop-loss review strategies use stop-loss-suite, and the article-selected family strategies use stop-loss-families-study. Cards and filters expose only labels present in the strategy’s array; market, direction, indicators, rules, and other strategy content do not generate labels.

Trading does not currently accept DCA portfolio fields, cashflows, external series, state variables, branches, or nested IF rules.

See Actions and execution for the category-specific action shapes.

DCA rule forms

Form	Shape
Direct action	`{ "name", "action": { ... } }`
Ordered actions	`{ "name", "actions": [{ ... }, ...] }`
Condition gate	`{ "name", "conditions": [...], "action" or "actions" or "branches" }`
IF tree	`{ "name", "if": { "name", "conditions", "then", "else" } }`
Branch list	`{ "name", "branches": [{ "name", "when", ... }, { "name", "else": true, ... }] }`

Rule-level conditions can gate one action, ordered actions, or a branch list. IF targets can contain a nested IF, one action, or ordered actions. Branch lists execute the first matching branch. An else branch must be last.

Minimal DCA rule

{
  "name": "Add daily contribution",
  "action": {
    "name": "Add daily contribution",
    "type": "cashflow",
    "amount": 50
  }
}