Strategy rules spec

Overview

A Custom strategy is a small JSON object: a group of buy conditions, a group of sell conditions, and two optional exits. The Studio builds it for you; this page is for writing it by hand, from the Public API or the MCP server. The same check runs everywhere, so rules that pass here pass in the Studio too.

Every hour, for each market, the agent checks one group:

• No position: the entry group. If it is met, the agent buys.
• Holding a position: the exit group. If it is met, the agent sells. The stop loss, the take profit and the max holding time are checked as well, whatever the group says.

{
  "entry": { "join": "all" | "any", "conditions": [ condition, ... ] },
  "exit":  { "join": "all" | "any", "conditions": [ condition, ... ] },
  "takeProfitPct": number | null,
  "maxHoldHours": number | null
}

condition = { "left": indicator, "op": operator, "right": indicator | value }
indicator = { "kind": "sma", "hours": 48, "offsetPct": -2 }
value     = { "kind": "value", "value": 30 }

Full example

RSI dip buying with a trend filter. It passes the check as it is, so you can paste it into a validate call.

{
  "entry": {
    "join": "all",
    "conditions": [
      {
        "left": {
          "kind": "rsi",
          "hours": 14
        },
        "op": "below",
        "right": {
          "kind": "value",
          "value": 30
        }
      },
      {
        "left": {
          "kind": "price"
        },
        "op": "above",
        "right": {
          "kind": "sma",
          "hours": 72,
          "offsetPct": -5
        }
      }
    ]
  },
  "exit": {
    "join": "any",
    "conditions": [
      {
        "left": {
          "kind": "rsi",
          "hours": 14
        },
        "op": "crossesAbove",
        "right": {
          "kind": "value",
          "value": 55
        }
      }
    ]
  },
  "takeProfitPct": 6,
  "maxHoldHours": 72
}

1. entry, join "all": both buy conditions must be true in the same hour.
2. Buy condition 1: the 14 hour RSI is under 30, so the market has fallen hard lately.
3. Buy condition 2: the price is still above its 72 hour average minus 5%, so it is a dip and not a crash.
4. exit, join "any": one sell condition is enough.
5. Sell condition: the 14 hour RSI crosses back above 55. True only in the hour it crosses.
6. takeProfitPct 6: sell once the price is 6% above where it was bought.
7. maxHoldHours 72: sell after 3 days whatever happens.

curl -X POST https://zolvaagent.app/api/public/v1/me/rules/validate \
  -H "Authorization: Bearer $ZOLVA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "rules": {"entry":{"join":"all","conditions":[{"left":{"kind":"rsi","hours":14},"op":"below","right":{"kind":"value","value":30}},{"left":{"kind":"price"},"op":"above","right":{"kind":"sma","hours":72,"offsetPct":-5}}]},"exit":{"join":"any","conditions":[{"left":{"kind":"rsi","hours":14},"op":"crossesAbove","right":{"kind":"value","value":55}}]},"takeProfitPct":6,"maxHoldHours":72} }'

The answer is { "valid": true, "rules": {...}, "lookbackHours": 73, "errors": [] }, or valid: false with the list of errors below. lookbackHours is how much history the rules need before the first decision.

Fields

Indicators

The kind of a side. Price lines (unit USD) can only be compared with other price lines; everything else is compared with a value.

Operators

Agent settings next to the rules

Markets, venue, stop loss and position size are not part of the rules object. They are set when the agent is made (POST /me/agents or create_paper_agent) and in a backtest.

The stop loss always applies: a position that falls this far below its entry price is sold that hour. See Guardrails for every other limit.

Limits

Error messages

The check returns every problem at once, in plain words. These are all of them. Through the API they come back in errors (validate) or in the 400 invalid_input message (backtest, create).