Developers
Log inStart building
Unpublished — this page is visible on staging only and is not on the public site.
View .mdENIT

Describe the strategy model

POST/api/v1/research/describe_strategy_model

Describes the Fincanva strategy model one section at a time — the Combined level, risk conditions, allocation, the sub-strategies of a Combined, position exits, selection and simulation settings — listing every field with its type, unit, default, bounds and allowed values, and your plan's limit where one applies.

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

Parameters

What parameters does Describe the strategy model take?

  • sectionstringOptionalDefault "overview"

    one of overview, combined, risk_conditions, allocation, sub_strategies, position_exits, selection, user_settings

    The section to describe: overview lists the sections; combined (the Combined level), risk_conditions, allocation, sub_strategies (the sub-strategies of a Combined; a Single carries the same fields at its top), position_exits, selection or user_settings (the simulation settings).

Response

What does Describe the strategy model return?

  • sectionstring

    one of overview, combined, risk_conditions, allocation, sub_strategies, position_exits, selection, user_settings

    The section described.

  • titlestring

    at least 1 characters

    The section's title, in the product's words.

  • summarystring

    at least 1 characters

    What the section controls, in one or two sentences.

  • fieldslist

    Every field of the section, in the order the app shows them; empty for the overview.

    Show the 13 fields
    • pathstring

      The field's public path in a strategy definition, the path creating and editing a strategy use.

    • namestring

      at least 1 characters

      The field's name as the app shows it.

    • typestring

      one of number, integer, boolean, enum, string, list, object

      number, integer, boolean, enum, string, list or object.

    • unitstring

      one of none, number, count, days, weeks, months, quarters, years, reports, bars, fraction, percent, multiple, sharpe_points, sigma, usd, base_currency, date, native

      The unit of the field's value. Convention: fraction

    • defaultnumber / boolean / string

      may be null · unit: the unit of what it describes

      The value used when the field is not given. Convention: native_unit

    • enabledByDefaultboolean

      may be null

      For a field that can be switched on or off, whether it is on by default; null for any other field.

    • minnumber

      may be null · unit: the unit of what it describes

      The smallest value the product allows, or null. Convention: native_unit

    • maxnumber

      may be null · unit: the unit of what it describes

      The largest value the product allows, or null. Convention: native_unit

    • valueslist

      may be null

      The values the app offers for an enum field, or null. Where the app locks a choice, only the locked value is listed: two risk conditions are combined with or, and the rebalance cadence is month.

    • stepslist

      may be null · unit: the unit of what it describes

      The only numbers the field accepts, ascending, such as the starting capital's fixed amounts; null when any number between min and max is accepted. Convention: native_unit

    • boundsByobject

      may be null

      Bounds that depend on another field, one case per value of that field, such as a risk rule's threshold by the metric it reads; null when the bounds are fixed. The field's own unit, default, min and max are those of the other field's default value.

      Show the 2 fields
      • onstring

        The public path of the field whose value decides the bounds.

      • caseslist

        One entry per value of that field.

        Show the 6 fields
        • whenstring

          at least 1 characters

          The value of the deciding field this case applies to.

        • unitstring

          one of none, number, count, days, weeks, months, quarters, years, reports, bars, fraction, percent, multiple, sharpe_points, sigma, usd, base_currency, date, native

          The unit of the field's value in this case. Convention: fraction

        • defaultnumber / boolean / string

          may be null · unit: the unit of what it describes

          The default in this case. Convention: native_unit

        • minnumber

          may be null · unit: the unit of what it describes

          The smallest value allowed in this case, or null. Convention: native_unit

        • maxnumber

          may be null · unit: the unit of what it describes

          The largest value allowed in this case, or null. Convention: native_unit

        • stepslist

          may be null · unit: the unit of what it describes

          The only numbers accepted in this case, ascending; null when any number between this case's min and max is accepted. Convention: native_unit

    • valuePlanslist

      may be null

      The values that need a higher plan than the field itself, such as the advanced covariance estimators; null when every value comes with the field.

      Show the 3 fields
      • valuestring

        at least 1 characters

        One of the field's values.

      • includedInYourPlanboolean

        True when your current plan includes this value.

      • lowestPlanstring

        one of free, starter, advanced, ultimate, professional · may be null

        The lowest plan that includes this value, or null when no plan includes it today.

    • planLimitobject

      may be null

      Your plan's limit on the field, or null when no plan limits it.

      Show the 4 fields
      • includedInYourPlanboolean

        True when your plan lets you use the field.

      • lowestPlanstring

        one of free, starter, advanced, ultimate, professional · may be null

        The lowest plan that lets you use the field, or null when no plan lets you use it today.

      • yourMinnumber

        may be null · unit: the unit of what it describes

        Your plan's floor for a number field, such as the earliest starting year your plan allows, which can be higher than min; null when your plan sets none. Convention: native_unit

      • yourMaxnumber

        may be null · unit: the unit of what it describes

        Your plan's ceiling for a number field, which can be lower than max; null when your plan sets none. Convention: native_unit

  • sectionslist

    Every section of the strategy, to navigate from.

    Show the 2 fields
    • idstring

      one of overview, combined, risk_conditions, allocation, sub_strategies, position_exits, selection, user_settings

      The section's id, to pass as section.

    • titlestring

      at least 1 characters

      The section's title.

Every response arrives inside the result envelope every operation shares.

Errors

Which error codes can Describe the strategy model return?

Describe the strategy model 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 Describe the strategy model?

  • Before creating or editing a strategy, to know every field it can set and the limits of the user's plan.
  • The user asks what a setting means, what its default is, or how far it can go.

What does a call to Describe the strategy model look like?

The position exits of a strategy, for a caller whose plan caps positions

How low can I set a stop loss?

Position exits: 5 fields. Max positions is on by default and capped at 10 by your plan; the other four are off until you set them.
Full response · 200
{
  "status": true,
  "data": {
    "result": {
      "section": "position_exits",
      "title": "Position exits",
      "summary": "Rules that close positions inside each strategy: a maximum holding time, a delay before reinvesting, a cap on open positions, a take profit and a stop loss. Each can be switched on or off.",
      "fields": [
        {
          "path": "subStrategies[].positionExits.maxHoldMonths",
          "name": "Max hold months",
          "type": "integer",
          "unit": "months",
          "default": 12,
          "enabledByDefault": false,
          "min": 1,
          "max": 120,
          "values": null,
          "steps": null,
          "boundsBy": null,
          "valuePlans": null,
          "planLimit": null
        },
        {
          "path": "subStrategies[].positionExits.reinvestDelayMonths",
          "name": "Reinvest delay",
          "type": "integer",
          "unit": "months",
          "default": 12,
          "enabledByDefault": false,
          "min": 1,
          "max": 120,
          "values": null,
          "steps": null,
          "boundsBy": null,
          "valuePlans": null,
          "planLimit": null
        },
        {
          "path": "subStrategies[].positionExits.maxPositions",
          "name": "Max positions",
          "type": "integer",
          "unit": "count",
          "default": 10,
          "enabledByDefault": true,
          "min": 1,
          "max": 50,
          "values": null,
          "steps": null,
          "boundsBy": null,
          "valuePlans": null,
          "planLimit": {
            "includedInYourPlan": true,
            "lowestPlan": "free",
            "yourMin": null,
            "yourMax": 10
          }
        },
        {
          "path": "subStrategies[].positionExits.takeProfit",
          "name": "Take profit",
          "type": "number",
          "unit": "fraction",
          "default": 1.5,
          "enabledByDefault": false,
          "min": 0.05,
          "max": 10,
          "values": null,
          "steps": null,
          "boundsBy": null,
          "valuePlans": null,
          "planLimit": null
        },
        {
          "path": "subStrategies[].positionExits.stopLoss",
          "name": "Stop loss",
          "type": "number",
          "unit": "fraction",
          "default": -0.3,
          "enabledByDefault": false,
          "min": -1,
          "max": -0.05,
          "values": null,
          "steps": null,
          "boundsBy": null,
          "valuePlans": null,
          "planLimit": null
        }
      ],
      "sections": [
        {
          "id": "overview",
          "title": "Overview"
        },
        {
          "id": "combined",
          "title": "Combined level"
        },
        {
          "id": "risk_conditions",
          "title": "Risk conditions"
        },
        {
          "id": "allocation",
          "title": "Allocation"
        },
        {
          "id": "sub_strategies",
          "title": "Sub-strategies"
        },
        {
          "id": "position_exits",
          "title": "Position exits"
        },
        {
          "id": "selection",
          "title": "Selection"
        },
        {
          "id": "user_settings",
          "title": "Simulation settings"
        }
      ]
    },
    "summary": "Position exits: 5 fields. Max positions is on by default and capped at 10 by your plan; the other four are off until you set them.",
    "assumed": [],
    "dataVersion": null
  }
}

What goes wrong most often with Describe the strategy model?

  • Take profit and stop loss are fractions: 1.5 is +150% and -0.3 is -30%, while the app shows them as percentages.
  • A number field can have two ceilings and two floors: max and min are the product's, planLimit.yourMax and planLimit.yourMin your plan's; the tighter one applies. A field with steps accepts those numbers only, and a field with boundsBy takes the bounds of the case its deciding field selects.
  • Position exits apply inside each strategy of a Combined, not to the Combined as a whole.

Which plans include Describe the strategy model?

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