Carteiras e análises

Rodar uma análise de carteira

Calcula métricas de risco, correlações, backtest, otimização, atribuição ou Monte Carlo. Informe os ativos (instruments) ou uma carteira (portfolio: salva, por slug, ou com items na própria chamada).

POSThttps://api.fintay.com.br/v1/analytics/{tool}

Cada ferramenta aceita campos próprios além destes: backtest recebe portfolios (até 3), initial e rebalance; optimize recebe o objetivo; montecarlo, o horizonte em anos.

Os ativos precisam ter histórico de preços conferido; caso contrário a resposta é 422.

Autorização

X-API-Keystringheaderobrigatório

Chave de API criada em API Keys. Veja Chaves e limites.

Parâmetros de rota

toolstringobrigatório

backtest, metrics, correlation, optimize, attribution ou montecarlo.

Corpo (JSON)

instrumentsarray

Tickers ou códigos de série (ex.: PETR4, bacen/12, CDI). Use isto ou portfolio.

portfolioobject

Carteira: {"slug": "minha-carteira"} para uma salva, ou {"items": [{"instrument": "PETR4", "weight": 60}, ...]} com pesos em %.

startstring · date

Início da janela.

endstring · date

Fim da janela. Padrão: o último dia com dado.

frequencystringpadrão: daily

Frequência dos retornos.

Valores aceitos:dailymonthly

benchmarkstring

Referência para beta e retorno relativo (ex.: CDI, IBOV).

Resposta

Envelope { success, data, meta }. Campos de data:

conventionsobject

benchmarkobject

seriesobject[]

growthobject

drawdownobject

rollingobject

calendarobject

drawdownsobject[]

correlationobject

portfolionull

warningsstring[]

attributionsstring[]

POSTRodar uma análise de carteira

curl -X POST "https://api.fintay.com.br/v1/analytics/metrics" \
  -H "X-API-Key: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"instruments":["BTAG11","CDI"],"start":"2026-01-02","end":"2026-09-30","benchmark":"CDI"}'

Resposta

{
  "success": true,
  "data": {
    "conventions": {
      "frequency": "diaria",
      "periods_per_year": 252,
      "returns": "simples, a partir de preco ajustado, cota, PU ou indice",
      "return_basis": {
        "BTAG11": "fechamento ajustado por proventos e eventos (retorno total)",
        "CDI": "taxa diária capitalizada"
      },
      "risk_free": "CDI do mesmo período",
      "start": "2026-01-02",
      "end": "2026-09-30",
      "observations": 186,
      "start_limited_by": "BTAG11",
      "end_limited_by": "BTAG11",
      "gap_rule": "lacunas de ate 10 períodos repetem o ultimo valor; acima disso, erro",
      "suspicious_rule": "saltos de +300%/-75% revertidos no período seguinte, ou 10x no ultimo ponto, ficam fora; mudanças persistentes acima de 10x impedem a análise",
      "excluded_points": {},
      "filled_points": {}
    },
    "benchmark": {
      "code": "CDI",
      "name": "Taxa de juros - CDI",
      "metrics": {
        "periods": 186,
        "years": 0.7380952380952381,
        "total_return": 0.10445586364906156,
        "annualized_return": null,
        "annualized_return_note": "Periodo menor que 1 ano: sem anualizacao",
        "arithmetic_mean": 0.1346429767742056,
        "geometric_mean": 0.14408706494073598,
        "risk_free_return": 0.10445586364906156,
        "excess_return": null,
        "volatility": 0.0002202436742182057,
        "downside_deviation": 0,
        "max_drawdown": {
          "depth": 0,
          "peak": null,
          "trough": null,
          "recovery": null,
          "length": 0,
          "recovery_periods": null
        },
        "ulcer_index": 0,
        "skewness": -0.20909797019089638,
        "excess_kurtosis": -1.1881790684399227,
        "sharpe": null,
        "sortino": null,
        "calmar": null,
        "omega": null,
        "gain_loss": null,
        "positive_periods": 1,
        "best_period": 0.0005513100000000826,
        "worst_period": 0.0005078800000000161,
        "best_month": 0.012152202899923692,
        "worst_month": 0.009970220253081363,
        "best_year": 0.1044558636490609,
        "worst_year": 0.1044558636490609,
        "var": {
          "95": {
            "historical": -0.0005100600000000345,
            "parametric": -0.0005114767497338986,
            "cornish_fisher": -0.0005103308264557911,
            "cvar_historical": -0.0005078800000000161,
            "cvar_parametric": -0.0005056793516661251
          },
          "99": {
            "historical": -0.0005078800000000161,
            "parametric": -0.0005020216662629118,
            "cornish_fisher": -0.0005039707324133836,
            "cvar_historical": -0.0005078800000000161,
            "cvar_parametric": -0.000497320218519947
          }
        },
        "var_month": {
          "95": {
            "historical": -0.010889409274033148,
            "parametric": -0.010855261580949967,
            "cornish_fisher": -0.010842520327421492,
            "cvar_historical": -0.010851965835266184,
            "cvar_parametric": -0.010744937577491034
          },
          "99": {
            "historical": -0.010831262026893275,
            "parametric": -0.01067533212822597,
            "cornish_fisher": -0.010740827709024424,
            "cvar_historical": -0.010821130652355855,
            "cvar_parametric": -0.01058586396837335
          }
        }
      }
    },
    "series": [
      {
        "code": "BTAG11",
        "name": "BTG Pactual Credito Agricola Fiagro Responsabilidade Limitada",
        "asset_class": "fundo_listado",
        "series_id": "28da4fef-5740-4d3a-87f6-6500d0457739",
        "metrics": {
          "periods": 186,
          "years": 0.7380952380952381,
          "total_return": -0.060935158444359816,
          "annualized_return": null,
          "annualized_return_note": "Periodo menor que 1 ano: sem anualizacao",
          "arithmetic_mean": -0.04594636986389745,
          "geometric_mean": -0.08165277903325019,
          "risk_free_return": 0.10445586364906156,
          "excess_return": null,
          "volatility": 0.28172402826131154,
          "downside_deviation": 0.1920686938553699,
          "max_drawdown": {
            "depth": -0.1394345421581662,
            "peak": "2026-05-05",
            "trough": "2026-09-29",
            "recovery": null,
            "length": 103,
            "recovery_periods": null
          },
          "ulcer_index": 0.07799128910080629,
          "skewness": 0.640572377236587,
          "excess_kurtosis": 4.049416034461698,
          "sharpe": -0.6410185487684482,
          "sortino": -0.9402331166686074,
          "calmar": null,
          "omega": 0.8870697072918328,
          "gain_loss": 1.1758741423133139,
          "positive_periods": 0.43010752688172044,
          "best_period": 0.08715607338700959,
          "worst_period": -0.061097467877082146,
          "best_month": 0.07486530618043918,
          "worst_month": -0.07896594786846789,
          "best_year": -0.06093515844436048,
          "worst_year": -0.06093515844436048,
          "var": {
            "95": {
              "historical": 0.025715297623328248,
              "parametric": 0.02937345477762456,
              "cornish_fisher": 0.02455489737325725,
              "cvar_historical": 0.038211724816165527,
              "cvar_parametric": 0.03678917894262086
            },
            "99": {
              "historical": 0.04453939283954842,
              "parametric": 0.0414678961387612,
              "cornish_fisher": 0.0471692273744329,
              "cvar_historical": 0.05582647178881045,
              "cvar_parametric": 0.047481738767884044
            }
          },
          "var_month": {
            "95": {
              "historical": 0.09008240772502724,
              "parametric": 0.0825469397260313,
              "cornish_fisher": 0.08526793076306394,
              "cvar_historical": 0.09799103443340368,
              "cvar_parametric": 0.10199931247413
            },
            "99": {
              "historical": 0.10252437816620089,
              "parametric": 0.11427217333805703,
              "cornish_fisher": 0.12007431872030302,
              "cvar_historical": 0.11170912260708658,
              "cvar_parametric": 0.13004723533703064
            }
          },
          "relative": {
            "beta": 9.389215680485698,
            "alpha": -0.18058934663810305,
            "correlation": 0.0073402164957661244,
            "r_squared": 0.000053878778204717126,
            "active_return": -0.22573984397398617,
            "tracking_error": 0.28172249771096164,
            "information_ratio": -0.641018548768448,
            "upside_capture": -0.632527194792988,
            "downside_capture": null,
            "batting_average": 0.40860215053763443,
            "treynor": -0.01923369882890594
          }
        }
      },
      {
        "code": "CDI",
        "name": "Taxa de juros - CDI",
        "asset_class": "caixa",
        "series_id": "911a1e56-fb1b-4c30-8dc5-950612072e91",
        "metrics": {
          "periods": 186,
          "years": 0.7380952380952381,
          "total_return": 0.10445586364906156,
          "annualized_return": null,
          "annualized_return_note": "Periodo menor que 1 ano: sem anualizacao",
          "arithmetic_mean": 0.1346429767742056,
          "geometric_mean": 0.14408706494073598,
          "risk_free_return": 0.10445586364906156,
          "excess_return": null,
          "volatility": 0.0002202436742182057,
          "downside_deviation": 0,
          "max_drawdown": {
            "depth": 0,
            "peak": null,
            "trough": null,
            "recovery": null,
            "length": 0,
            "recovery_periods": null
          },
          "ulcer_index": 0,
          "skewness": -0.20909797019089638,
          "excess_kurtosis": -1.1881790684399227,
          "sharpe": null,
          "sortino": null,
          "calmar": null,
          "omega": null,
          "gain_loss": null,
          "positive_periods": 1,
          "best_period": 0.0005513100000000826,
          "worst_period": 0.0005078800000000161,
          "best_month": 0.012152202899923692,
          "worst_month": 0.009970220253081363,
          "best_year": 0.1044558636490609,
          "worst_year": 0.1044558636490609,
          "var": {
            "95": {
              "historical": -0.0005100600000000345,
              "parametric": -0.0005114767497338986,
              "cornish_fisher": -0.0005103308264557911,
              "cvar_historical": -0.0005078800000000161,
              "cvar_parametric": -0.0005056793516661251
            },
            "99": {
              "historical": -0.0005078800000000161,
              "parametric": -0.0005020216662629118,
              "cornish_fisher": -0.0005039707324133836,
              "cvar_historical": -0.0005078800000000161,
              "cvar_parametric": -0.000497320218519947
            }
          },
          "var_month": {
            "95": {
              "historical": -0.010889409274033148,
              "parametric": -0.010855261580949967,
              "cornish_fisher": -0.010842520327421492,
              "cvar_historical": -0.010851965835266184,
              "cvar_parametric": -0.010744937577491034
            },
            "99": {
              "historical": -0.010831262026893275,
              "parametric": -0.01067533212822597,
              "cornish_fisher": -0.010740827709024424,
              "cvar_historical": -0.010821130652355855,
              "cvar_parametric": -0.01058586396837335
            }
          },
          "relative": {
            "beta": 1.0000000000000002,
            "alpha": 0,
            "correlation": 1,
            "r_squared": 1,
            "active_return": 0,
            "tracking_error": 0,
            "information_ratio": null,
            "upside_capture": 1,
            "downside_capture": null,
            "batting_average": 0,
            "treynor": 0
          }
        }
      }
    ],
    "growth": {
      "BTAG11": [
        [
          "2026-01-02",
          100
        ],
        [
          "2026-01-05",
          100.0428032143958
        ],
        [
          "2026-01-06",
          100.89780466854566
        ]
      ],
      "CDI": [
        [
          "2026-01-02",
          100
        ],
        [
          "2026-01-05",
          100.055131
        ],
        [
          "2026-01-06",
          100.11029239427162
        ]
      ]
    },
    "drawdown": {
      "BTAG11": [
        [
          "2026-01-05",
          0
        ],
        [
          "2026-01-06",
          0
        ],
        [
          "2026-01-07",
          -0.0075421757587423865
        ]
      ],
      "CDI": [
        [
          "2026-01-05",
          0
        ],
        [
          "2026-01-06",
          0
        ],
        [
          "2026-01-07",
          0
        ]
      ]
    },
    "rolling": {
      "window": 252,
      "series": "BTAG11",
      "points": []
    },
    "calendar": {
      "monthly": {
        "2026": [
          -0.03605421998146752,
          -0.012299855460911613,
          0.07486530618043918
        ]
      },
      "annual": {
        "2026": -0.06093515844436048
      }
    },
    "drawdowns": [
      {
        "peak": "2026-05-05",
        "depth": -0.1394345421581662,
        "trough": "2026-09-29",
        "recovery": null,
        "recovery_periods": null
      },
      {
        "peak": "2026-01-19",
        "depth": -0.10924344513053408,
        "trough": "2026-01-28",
        "recovery": "2026-03-27",
        "recovery_periods": 40
      },
      {
        "peak": "2026-03-27",
        "depth": -0.0662858824719702,
        "trough": "2026-04-29",
        "recovery": "2026-05-05",
        "recovery_periods": 3
      }
    ],
    "correlation": {
      "labels": [
        "BTAG11",
        "CDI"
      ],
      "matrix": [
        [
          1,
          0.0073402164957661244
        ],
        [
          0.007340216495766125,
          1
        ]
      ]
    },
    "portfolio": null,
    "warnings": [],
    "attributions": []
  },
  "error": null,
  "meta": {
    "request_id": null,
    "format": "json"
  }
}