Skip to content

Docs

Execution spec v0#

A sentence such as "buy when the close crosses above the 24-hour average" leaves out the bar size, the fill price, the exit and the costs. An execution spec v0 is one JSON object that fixes them. Check yours for free before you attach it: the MCP tool strategy_spec_validate (on this profile) or POST /strategy/spec/validate (no key). The reply is {ok, spec_hash, normalized, errors[{path, rule, message}], warnings, edge_check}. spec_hash is the sha256 of the canonical JSON of the normalized spec, so one strategy has one hash however it is written. Pass context.nav_usd (the account value in USD) when the size is a share of NAV, so the order size is known.

FieldMeaning
spec_version0. Any other version is refused.
name, asset, venue, marketUp to 80 characters; ticker such as BTC; hl_main, hl_xyz or paper; main:BTC or xyz:SKHX (must match the asset and venue).
directionlong, short or both (both is reserved in v0: rules are not mirrored, write one spec per side).
sizemode nav_weight (share of NAV, 0 to 1), fixed_usd, or risk_per_stop (risk_bps_of_nav, needs a stop in exit); plus max_nav_weight_per_asset and max_gross_nav (both default 1).
leverageAbove 0, at most 50.
schedulebar (1m 5m 15m 1h 4h 1d), evaluate on_bar_close, fill next_bar_open or on_close, session (days, from_utc, to_utc), warmup_bars (default: what the rules read).
entry.all, exit.anyRules from a closed list; every entry rule must hold, any exit rule closes.
max_positions, risk_halts1 to 20; optional daily_loss_bps_of_nav and drawdown_bps_from_peak.
costsfee_bps_per_fill; slippage as a size table [[order_usd_up_to, bps], ...] with above_table refuse or last_row; funding observed or fixed (fixed_bps_per_day).
editableUp to 16 {path, type, min, max} that point at numbers in the spec, for tuning without rewriting.

The rule list is closed. Conditions: cross_above, cross_below (series, ref), close_above, close_below (ref), drawdown_from_high (lookback_bars, min_bps), range_bound (bars, max_width_bps), sequence (steps, within_bars). Exit only: stop_from_entry (bps), trailing_atr (mult, length), time_in_trade (max_bars). Values for a ref: {"sma": 24}, {"ema": 200}, {"atr": 14}, {"highest": {"field": "high", "length": 20, "exclude_current": true}}, {"lowest": {...}}. An unknown rule or field is refused with spec_rule_unknown or spec_field_unknown and its path; nothing is guessed.

Cost-to-edge rule: a spec gets a warning (spec_cost_exceeds_edge, edge_check.status warn, ok stays true) when one round trip (2 x fee + 2 x slippage at the spec's order size) is more than 0.5 x the median bar move (|close - open| / open) of its bar over the last 90 days. It is advice, not a refusal: a spec can net a profit after costs, so read the paper report card's net return, or use a smaller order or a longer bar. With no readable candles, or a NAV-based size and no context.nav_usd, edge_check.status is not_evaluated with the reason.

Worked example, the hourly rule "enter a 5% NAV long at 1x when the close crosses above its 24-hour simple moving average; exit on a close below it or a 2% decline from entry; hold one position":

{"spec_version": 0, "name": "BTC 1h above 24h SMA", "asset": "BTC", "venue": "paper", "market": "main:BTC", "direction": "long",
 "size": {"mode": "nav_weight", "nav_weight": 0.05, "max_nav_weight_per_asset": 0.05, "max_gross_nav": 0.05},
 "leverage": 1,
 "schedule": {"bar": "1h", "fill": "next_bar_open", "warmup_bars": 24},
 "entry": {"all": [{"rule": "cross_above", "series": "close", "ref": {"sma": 24}}]},
 "exit": {"any": [{"rule": "close_below", "ref": {"sma": 24}}, {"rule": "stop_from_entry", "bps": 200}]},
 "max_positions": 1,
 "costs": {"fee_bps_per_fill": 4.5,
           "slippage": {"model": "size_table", "table": [[1000, 2], [10000, 5], [100000, 15]], "above_table": "refuse"},
           "funding": {"model": "observed"}}}

"Previous high" is one reading among several, so the spec names it: {"rule": "close_above", "ref": {"highest": {"field": "high", "length": 20, "exclude_current": true}}} is a close above the highest high of the 20 bars before it. "A 30% drop, then 7 weeks sideways" on daily bars is {"rule": "sequence", "within_bars": 60, "steps": [{"rule": "drawdown_from_high", "lookback_bars": 180, "min_bps": 3000}, {"rule": "range_bound", "bars": 49, "max_width_bps": 1500}]}.

Paper report card#

Run a spec bar by bar over real Hyperliquid candles before any money moves: POST /strategy/spec/paper (free, no key, 6 calls a minute) or the MCP tool strategy_spec_paper, with {spec, days (default 90, at most 180), context.nav_usd (default 10,000), sizes}. It validates first, then returns {ok, spec_hash, card}.

Fixed rules, so two readers get one answer: rules read on a bar close from bars up to it (no look-ahead); next_bar_open fills at the following open; stops are checked inside the bar and a gap through the stop fills at the worse open; trailing_atr moves only after a close and never loosens; each fill pays the fee plus the slippage of the size-table row of its order size (above a refuse table the entry is refused and counted); each hour held pays funding (fixed, or the observed rate; with no history funding.basis is not_applied and the net leaves it out). Sizes use the starting NAV. Candles are capped at 5000 bars.

The headline is card.summary.net_return_bps, basis points of NAV after fees, slippage and funding. Also there: trades, win_rate_pct, gross and each cost, max_drawdown_bps, exposure_pct, cost_to_edge (round trip over the median bar move; above 0.5 it says costs may eat the edge at this size), and size_sweep, the same spec at the rows of its slippage table (or your sizes) so you can see the order size where the edge is gone (edge_gone_at_usd). It never prints an annualised return.

The server recomputes the card daily for every stored spec (a mandate's, a gallery template's or a signal's) and keeps one row per UTC day; read the newest with GET /strategy/spec/{spec_hash}/report (status is pending until the first row exists).

Where a spec attaches (store only)#

Every attach validates first and refuses an invalid spec with the validator's errors (invalid_parameter, field exec_spec, errors[{path, rule, message}]). Nothing here trades a spec; the paper evaluator reads what is stored.

WhereHowWhat is stored
A mandateexec_spec on POST /torii/mandates (and the draft edit PUT /torii/mandates/{id}), alone or with listing_idspec and spec_hash inside the mandate's strategy block. Descriptive, never part of the signed terms. A host without the strategy column answers 503 and names the apply command
A gallery strategy templateexec_spec on POST /torii/gallery (only for strategy_template)The spec beside the listing; the listing shows exec_spec_hash, and the single-listing read also shows exec_spec. A mandate hired from the listing copies spec and spec_hash
A Forge signalexec_spec on a signal publishThe spec beside the signal, spec_hash in the reply. The signal's market, side (on open), target_weight and target_leverage must fit the spec

The spec tables are applied once by hand (python -m svc.db.schema.apply_exec_spec_schema); until then a publish or listing that names an exec_spec answers 503 and writes nothing.

Next#

Operators publish signals, House strategy.