Unpublished — this page is visible on staging only and is not on the public site.

List risk condition presets

Q: What parameters does List risk condition presets take?

group (optional; string; one of volatility, yield_curve, inflation, sp500) — Only the presets of this group: volatility, yield_curve, inflation or sp500. Left out, every preset is listed. includeRuleTypes (optional; boolean; default false) — When true, the result also lists the rule types a custom risk condition can use.

Q: What does a call to List risk condition presets look like?

The presets that watch volatility Asked as: Which risk-off signals based on volatility does Fincanva have? The answer: The summary it returns: 2 risk condition presets in the volatility group: VIX ratio and VIX. The values it assumed, because the request left them out: /includeRuleTypes = false — the rule types were not asked for, so they are not listed

Q: Which plans include List risk condition presets?

List risk condition presets belongs to the Strategy authoring family of operations and counts as one research call against your plan's monthly allowance. Which plans include the MCP server and the Open API, and how large their allowances are, is set out in Plans, quotas and limits.

POST/api/v1/research/list_risk_rule_presets

Lists the ready-made risk conditions a strategy can switch on — the VIX, the VIX ratio, TIPS, the yield-curve rules, the S&P 500 against its 200-day average and its 12-month momentum — each with the rule it applies: the indicator, the risk-off and risk-on thresholds, the weeks of delay and which values you may change.

Authentication: REST: an API key or an OAuth access token. MCP: an OAuth access token.
MCP tool: list_risk_rule_presets
Cost: one research call

Parameters

What parameters does List risk condition presets take?

groupstringOptional
one of volatility, yield_curve, inflation, sp500
Only the presets of this group: volatility, yield_curve, inflation or sp500. Left out, every preset is listed.
includeRuleTypesbooleanOptionalDefault false
When true, the result also lists the rule types a custom risk condition can use.

Show the code

Request

curl -X POST https://app.fincanva.com/api/v1/research/\
list_risk_rule_presets \
  -H "Authorization: Bearer $FINCANVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group":"volatility"}'

import os

import requests

response = requests.post(
    "https://app.fincanva.com/api/v1/research/list_risk_rule_presets",
    headers={"Authorization": f"Bearer {os.environ['FINCANVA_API_KEY']}"},
    json={
        "group": "volatility",
    },
)
body = response.json()

const response = await fetch("https://app.fincanva.com/api/v1/research/list_risk_rule_presets", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.FINCANVA_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "group": "volatility"
  }),
});
const body = await response.json();

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_risk_rule_presets",
    "arguments": {
      "group": "volatility"
    }
  }
}

Response

{
  "status": true,
  "data": {
    "result": {
      "presets": [
        {
          "id": "vix_ratio",
          "name": "VIX ratio",
          "group": "volatility",
          …
        },
        …
      ],
      "ruleTypes": null
    },
    "summary": "2 risk condition presets in the vol…",
    "assumed": [ … ],
    "dataVersion": null
  }
}

{
  "type": "object",
  "properties": {
    "presets": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"
          },
          "name": {
            "type": "string",
            "minLength": 1
          },
          "group": {
            "type": "string",
            "enum": [
              "volatility",
              "yield_curve",
              "inflation",
              "sp500"
            ]
          },
          "description": {
            "type": "string",
            "minLength": 1
          },
          "ruleType": {
            "type": "string",
            "enum": [
              "single_series",
              "double_series"
            ]
          },
          "indicator": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "none",
                  "sma",
                  "change",
                  "average_momentum"
                ]
              },
              "value": {
                "type": [
                  "number",
                  "null"
                ]
              }
            },
            "required": [
              "kind",
              "value"
            ],
            "additionalProperties": false
          },
          "riskOff": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "operator": {
                    "type": "string",
                    "enum": [
                      "above",
                      "below"
                    ]
                  },
                  "value": {
                    "type": "number"
                  }
                },
                "required": [
                  "operator",
                  "value"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "riskOn": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "operator": {
                    "type": "string",
                    "enum": [
                      "above",
                      "below"
                    ]
                  },
                  "value": {
                    "type": "number"
                  }
                },
                "required": [
                  "operator",
                  "value"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "crossing": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "operator": {
                    "type": "string",
                    "enum": [
                      "above",
                      "below"
                    ]
                  },
                  "against": {
                    "type": "object",
                    "properties": {
                      "kind": {
                        "type": "string",
                        "enum": [
                          "none",
                          "sma",
                          "change",
                          "average_momentum"
                        ]
                      },
                      "value": {
                        "type": [
                          "number",
                          "null"
                        ]
                      }
                    },
                    "required": [
                      "kind",
                      "value"
                    ],
                    "additionalProperties": false
                  }
                },
                "required": [
                  "operator",
                  "against"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "weeksOfDelay": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "switchRebalances": {
            "type": "boolean"
          },
          "editable": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "riskOffOperator",
                "riskOffValue",
                "riskOnOperator",
                "riskOnValue",
                "indicatorValue"
              ]
            }
          }
        },
        "required": [
          "id",
          "name",
          "group",
          "description",
          "ruleType",
          "indicator",
          "riskOff",
          "riskOn",
          "crossing",
          "weeksOfDelay",
          "switchRebalances",
          "editable"
        ],
        "additionalProperties": false
      }
    },
    "ruleTypes": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "enum": [
                  "single_series",
                  "double_series",
                  "hidden_markov",
                  "clustering",
                  "strategy_based"
                ]
              },
              "name": {
                "type": "string",
                "minLength": 1
              },
              "detects": {
                "type": "string",
                "minLength": 1
              }
            },
            "required": [
              "id",
              "name",
              "detects"
            ],
            "additionalProperties": false
          }
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "presets",
    "ruleTypes"
  ],
  "additionalProperties": false
}

Response

unauthorized

{
  "type": "object",
  "required": [
    "status",
    "message",
    "code"
  ],
  "properties": {
    "status": {
      "const": false
    },
    "message": {
      "type": "string",
      "description": "Written for an AI or a developer to act on."
    },
    "code": {
      "type": "string",
      "enum": [
        "unauthorized"
      ]
    },
    "details": {
      "description": "What the code needs to be acted on, such as the fields of an invalid input."
    }
  }
}

Response

plan_limit

{
  "type": "object",
  "required": [
    "status",
    "message",
    "code"
  ],
  "properties": {
    "status": {
      "const": false
    },
    "message": {
      "type": "string",
      "description": "Written for an AI or a developer to act on."
    },
    "code": {
      "type": "string",
      "enum": [
        "plan_limit"
      ]
    },
    "details": {
      "description": "What the code needs to be acted on, such as the fields of an invalid input."
    }
  }
}

Response

invalid_input

{
  "type": "object",
  "required": [
    "status",
    "message",
    "code"
  ],
  "properties": {
    "status": {
      "const": false
    },
    "message": {
      "type": "string",
      "description": "Written for an AI or a developer to act on."
    },
    "code": {
      "type": "string",
      "enum": [
        "invalid_input"
      ]
    },
    "details": {
      "description": "What the code needs to be acted on, such as the fields of an invalid input."
    }
  }
}

Response

quota_exhausted · rate_limited

{
  "type": "object",
  "required": [
    "status",
    "message",
    "code"
  ],
  "properties": {
    "status": {
      "const": false
    },
    "message": {
      "type": "string",
      "description": "Written for an AI or a developer to act on."
    },
    "code": {
      "type": "string",
      "enum": [
        "quota_exhausted",
        "rate_limited"
      ]
    },
    "details": {
      "description": "What the code needs to be acted on, such as the fields of an invalid input."
    }
  }
}

Full response →

Response

What does List risk condition presets return?

presetslist
The matching presets, in the order the app lists them.
Show the 12 fields
- idstring
  The preset's stable public id, in snake_case.
- namestring
  at least 1 characters
  The preset's name as the app shows it.
- groupstring
  one of volatility, yield_curve, inflation, sp500
  The preset's group: volatility, yield_curve, inflation or sp500.
- descriptionstring
  at least 1 characters
  The app's description of what the preset watches and when it turns risk-off.
- ruleTypestring
  one of single_series, double_series
  single_series compares one series with thresholds; double_series compares a series with another series or with its own indicator.
- indicatorobject
  The indicator applied to the series before it is compared.
  Show the 2 fields
  kindstring
  one of none, sma, change, average_momentum
  none (the series as it is), sma (a simple moving average), change (the change over a number of months) or average_momentum.
  valuenumber
  may be null · unit: the unit of what it describes
  The indicator's window: trading days for sma, months for change and average_momentum, null for none. Convention: native_unit
- riskOffobject
  may be null
  When the condition turns risk-off, or null for a crossing rule.
  Show the 2 fields
  operatorstring
  one of above, below
  above or below: the regime holds while the series is above or below the threshold.
  valuenumber
  unit: the unit of what it describes
  The risk-off threshold, in the unit of the series the preset reads. Convention: native_unit
- riskOnobject
  may be null
  When the condition turns back risk-on, or null for a crossing rule.
  Show the 2 fields
  operatorstring
  one of above, below
  above or below: the regime holds while the series is above or below the threshold.
  valuenumber
  unit: the unit of what it describes
  The risk-on threshold, in the unit of the series the preset reads. Convention: native_unit
- crossingobject
  may be null
  For a double_series preset, the comparison with the second series; null otherwise.
  Show the 2 fields
  operatorstring
  one of above, below
  above or below: the regime holds while the series is above or below the comparison indicator.
  againstobject
  The indicator the series is compared against.
  Show the 2 fields
  kindstring
  one of none, sma, change, average_momentum
  The comparison indicator's kind, as in indicator.kind.
  valuenumber
  may be null · unit: the unit of what it describes
  The comparison indicator's window, as in indicator.value. Convention: native_unit
- weeksOfDelayinteger
  at least 0 · unit: weeks
  How many weeks the condition waits before acting on a switch.
- switchRebalancesboolean
  True when a switch triggers a rebalance at once.
- editablelist
  The values you may change while keeping the preset: riskOffOperator, riskOffValue, riskOnOperator, riskOnValue, indicatorValue.
ruleTypeslist
may be null
The rule types a custom risk condition can use, or null unless includeRuleTypes was true.
Show the 3 fields
- idstring
  one of single_series, double_series, hidden_markov, clustering, strategy_based
  single_series, double_series, hidden_markov, clustering or strategy_based.
- namestring
  at least 1 characters
  The rule type's name as the app shows it.
- detectsstring
  at least 1 characters
  What the rule type detects, in one sentence.

Every response arrives inside the result envelope every operation shares.

Errors

Which error codes can List risk condition presets return?

List risk condition presets has no error codes of its own beyond the common ones.

Common to every operation

unauthorized HTTP 401
plan_limit HTTP 403
invalid_input HTTP 422
quota_exhausted HTTP 429
rate_limited HTTP 429

Every error code

When should you use List risk condition presets?

The user asks which risk-off signals Fincanva has, or how a named one decides.
Before setting a risk condition on a strategy, to start from a preset.

You need the bounds of every risk-condition field to write a custom condition — Use instead describe_strategy_model

What does a call to List risk condition presets look like?

The presets that watch volatility

Which risk-off signals based on volatility does Fincanva have?

2 risk condition presets in the volatility group: VIX ratio and VIX.

Full response · 200

{
  "status": true,
  "data": {
    "result": {
      "presets": [
        {
          "id": "vix_ratio",
          "name": "VIX ratio",
          "group": "volatility",
          "description": "Ratio of short-term (VIX) to medium-term (VXV) implied volatility. Risk-Off when the short term exceeds the medium term.",
          "ruleType": "single_series",
          "indicator": {
            "kind": "none",
            "value": null
          },
          "riskOff": {
            "operator": "above",
            "value": 1
          },
          "riskOn": {
            "operator": "below",
            "value": 0.95
          },
          "crossing": null,
          "weeksOfDelay": 0,
          "switchRebalances": false,
          "editable": [
            "riskOffOperator",
            "riskOffValue",
            "riskOnOperator",
            "riskOnValue"
          ]
        },
        {
          "id": "vix",
          "name": "VIX",
          "group": "volatility",
          "description": "CBOE volatility index level. Risk-Off when volatility exceeds the threshold.",
          "ruleType": "single_series",
          "indicator": {
            "kind": "none",
            "value": null
          },
          "riskOff": {
            "operator": "above",
            "value": 25
          },
          "riskOn": {
            "operator": "below",
            "value": 20
          },
          "crossing": null,
          "weeksOfDelay": 0,
          "switchRebalances": false,
          "editable": [
            "riskOffOperator",
            "riskOffValue",
            "riskOnOperator",
            "riskOnValue"
          ]
        }
      ],
      "ruleTypes": null
    },
    "summary": "2 risk condition presets in the volatility group: VIX ratio and VIX.",
    "assumed": [
      {
        "field": "/includeRuleTypes",
        "value": false,
        "reason": "the rule types were not asked for, so they are not listed"
      }
    ],
    "dataVersion": null
  }
}

What goes wrong most often with List risk condition presets?

A preset's thresholds are in the unit of the series it reads — index points for the VIX, a plain ratio for the VIX ratio — not fractions.
riskOff and riskOn are two thresholds, not one: the gap between them keeps the condition from flipping back and forth around a single level.
Only the values listed in editable can change while the preset stays a preset; the rest of its rule is fixed.

Which plans include List risk condition presets?

Family: Strategy authoring · Quota cost: one research call — Availability

Fincanva is for education and illustration only. It is not personalised financial advice, and past or simulated results do not predict future ones. Read the Terms Addendum

DOCS · EN — IT