Skip to main content
V-Lab
V-Lab
API reference

V-Lab MCP server

Programmatic access to V-Lab's risk research from any MCP-compatible client. This page lists every tool the server exposes — names, parameters, return shapes, and worked examples. For connection setup, see /setup-mcp.

v0.7.16
Streamable HTTP·OAuth 2.1·Last verified 2026-04-28·Setup guide →
Pre-release (v0.7.16). Schemas are pre-1.0 and may evolve as we stabilize the contract. During pre-1.0, a minor-version bump signals possible additions or breaking changes; a major-version bump (post-1.0) signals possible breaking changes.

38

Tools

8

Domains

116

Countries

39,000+

Active firms

860,000+

Active analyses

Daily

Refresh

Endpoint

The server speaks Streamable HTTP at the URL below. Most clients reach it through the mcp-remote stdio bridge until they support remote-OAuth MCP natively.

https://vlab.stern.nyu.edu/mcp

01

Discovery & metadata

Resolve tickers, find datasets, list available analyses, and inspect server capabilities. Start here when you do not yet know what V-Lab covers for an asset, dataset, or topic.

get_server_info

READ

Get information about the V-Lab MCP server including capabilities, status, and available features

Parameters

NameTypeRequiredDescription
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • server — { name, version, description }
  • status — operational | degraded | maintenance
  • capabilities.tools — list of tool names this server exposes (flat string array)
  • tool_hierarchies — domain groupings with recommended call flows
  • coming_soon — tools planned but not yet implemented
  • citation — how to cite V-Lab in published work
  • legal — disclaimer, not_advice, limitation_of_liability, full_provisions URL
  • support — feedback URL and contact message

Example — Inspect server capabilities

ARGUMENTS
{}
RESPONSE (ABBREVIATED)
{
  "server": {
    "name": "vlab-mcp",
    "version": "0.7.0"
  },
  "status": "operational",
  "capabilities": {
    "tools": [
      "get_server_info",
      "search_assets",
      "..."
    ]
  },
  "tool_hierarchies": {
    "systemic_risk_srisk": {
      "description": "...",
      "flow": [
        "..."
      ]
    }
  }
}
Call this once at the start of a session to discover what the server can do. The tool_hierarchies field documents recommended drill-down patterns. Note: capabilities.tools, coming_soon, and tool_hierarchies.<x>.flow are flat string arrays — they are not pivoted.

search_assets

READ

Resolve a financial asset by ticker, name, FIGI, SEDOL, or GVKEY. Returns compact results (ticker, name, active, last_result_date). Pass include_analyses:true for the full analyses catalog.

Parameters

NameTypeRequiredDescription
tickerstringoptionalTicker symbol (e.g., AAPL, GOOGL). Fuzzy matching for typos.
namestringoptionalAsset name (e.g., Apple, S&P 500). Fuzzy matching.
figistringoptionalOpenFIGI identifier. Exact match.
sedolstringoptionalSEDOL identifier. Exact match.
gvkeystringoptionalCompustat GVKEY. Exact match. Combine with iid if needed.
iidstringoptionalCompustat issue ID. Only used with gvkey.
include_analysesbooleanoptionalIf true, include the full applications/models/datasets catalog per asset. Default false (compact response) to save tokens — then drill in via search_analyses or get_* tools.
limitnumberoptionalMax assets returned (default 10, max 50)
application_filterstringoptionalFilter by application (e.g., "Volatility Analysis")
model_filterstringoptionalFilter by model (e.g., "GARCH")
profilestring (enum)optionalResponse profile. "minimal" strips related_tools, notes, units, and query echoes to save tokens. Default "standard".
Allowed values:
  • standard,
  • minimal

Returns

  • results — array of records: { ticker, name, asset_class, active, last_result_date, total_analyses }
  • results[].applications — only when include_analyses=true; nested per row

Example — Look up JPMorgan

ARGUMENTS
{
  "ticker": "JPM"
}
RESPONSE (ABBREVIATED)
{
  "results": [
    {
      "ticker": "JPM:US",
      "name": "JPMorgan Chase & Co",
      "asset_class": "Equities",
      "active": true,
      "last_result_date": "2026-04-24",
      "total_analyses": 21
    },
    {
      "ticker": "JPME:US",
      "name": "JPMorgan Diversified Return US Mid Cap Equity ETF",
      "asset_class": "ETFs",
      "active": true,
      "last_result_date": "2026-04-24",
      "total_analyses": 13
    },
    {
      "ticker": "JPMB:US",
      "name": "JPMorgan USD Emerging Markets Sovereign Bond ETF",
      "asset_class": "ETFs",
      "active": true,
      "last_result_date": "2026-04-24",
      "total_analyses": 13
    },
    {
      "ticker": "JPY:FOREX",
      "name": "Japanese Yen",
      "asset_class": "Currencies",
      "active": true,
      "last_result_date": "2026-04-24",
      "total_analyses": 10
    }
  ]
}
Default response is compact (no per-asset analyses catalog) to save tokens. Set include_analyses=true only when you need the full applications/models list. Fuzzy matching on ticker and name handles common typos. Tickers are returned with exchange suffix (e.g., "JPM:US", "HSBA:LN").

search_datasets

READ

Search for datasets and discover their constituent assets and available analyses. Returns datasets matching the query along with paginated asset lists and analysis information.

Parameters

NameTypeRequiredDescription
memostringoptionalSearch by dataset memo/identifier (e.g., "AAPL:US-R", "SPX-R"). Supports fuzzy matching for typos.
namestringoptionalSearch by dataset name (e.g., "Return Series", "Liquidity Dataset"). Supports fuzzy matching.
limitnumberoptionalMaximum number of datasets to return (default: 10, max: 50)
asset_pagenumberoptionalPage number for constituent assets (default: 1)
asset_page_sizenumberoptionalNumber of assets per page (default: 20, max: 100)
application_filterstringoptionalFilter analyses by application (e.g., "Volatility Analysis")
model_filterstringoptionalFilter analyses by model (e.g., "GARCH", "GJR-GARCH")
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • results — array of dataset records: { memo, name, asset_classes[], total_assets, has_active_assets, last_result_date, constituent_assets[], analyses[], assets_page, assets_page_size, has_more_assets, total_analyses }
  • results[].constituent_assets — array of records: { ticker, name, asset_class }
  • results[].analyses — array of records: { application, model, analysis_memo }

Example — Find the World Financials dataset

ARGUMENTS
{
  "memo": "WORLDFIN-MR"
}
RESPONSE (ABBREVIATED)
{
  "results": [
    {
      "memo": "WORLDFIN-MR",
      "name": "World Financials",
      "asset_classes": [
        "Closed-end Funds",
        "Depositary Receipts",
        "Equities",
        "International Equities",
        "Real Estate",
        "Units"
      ],
      "total_assets": 2190,
      "has_active_assets": true,
      "last_result_date": "2026-04-23",
      "constituent_assets": [
        {
          "ticker": "000001:CH",
          "name": "Ping An Bank Co Ltd",
          "asset_class": "International Equities"
        },
        "..."
      ],
      "analyses": [
        {
          "application": "Climate Risk Analysis",
          "model": "CMES",
          "analysis_memo": "CLIM.WORLDFIN-MR.CMES"
        },
        {
          "application": "Systemic Risk Analysis",
          "model": "GMES",
          "analysis_memo": "RISK.WORLDFIN-MR.GMES"
        }
      ],
      "total_analyses": 2
    }
  ]
}

asset_in_dataset

READ

Check if a specific asset is a constituent of a dataset and retrieve available analyses for that combination.

Parameters

NameTypeRequiredDescription
tickerstringrequiredAsset ticker with exchange suffix (e.g., "AAPL:US", "SPX:IND", "FTSE:LN"). The exchange suffix is required — use search_assets to find the correct format.
dataset_memostringrequiredDataset memo/identifier to check membership in (e.g., "WORLDFIN-MR", "SPX-R")
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • is_member — boolean
  • ticker, asset_name, asset_class — scalars
  • dataset_memo, dataset_name — scalars
  • analyses[] — { application, model, analysis_memo }
  • total_analyses — scalar

Example — Check whether JPMorgan Chase is in the World Financials dataset

ARGUMENTS
{
  "ticker": "JPM:US",
  "dataset_memo": "WORLDFIN-MR"
}
RESPONSE (ABBREVIATED)
{
  "is_member": true,
  "ticker": "JPM:US",
  "asset_name": "JPMorgan Chase & Co",
  "asset_class": "Equities",
  "dataset_memo": "WORLDFIN-MR",
  "dataset_name": "World Financials",
  "analyses": [
    {
      "application": "Climate Risk Analysis",
      "model": "CMES",
      "analysis_memo": "CLIM.WORLDFIN-MR.CMES"
    },
    {
      "application": "Systemic Risk Analysis",
      "model": "GMES",
      "analysis_memo": "RISK.WORLDFIN-MR.GMES"
    }
  ],
  "total_analyses": 2
}

search_analyses

READ

Search for analyses by application, model, or memo. Returns flat results with full context for each analysis instance.

Parameters

NameTypeRequiredDescription
applicationstringoptionalSearch by application name (e.g., "Volatility Analysis", "Risk Metrics")
modelstringoptionalSearch by model name (e.g., "GARCH", "GJR-GARCH", "EGARCH")
memostringoptionalSearch by analysis memo pattern (e.g., "AAPL-GARCH")
limitnumberoptionalMaximum number of results to return (default: 20, max: 100)
pagenumberoptionalPage number for pagination (default: 1)
ticker_filterstringoptionalFilter by specific ticker
dataset_filterstringoptionalFilter by specific dataset memo
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • results — array of records: { ticker, name, asset_class, application, model, dataset, dataset_memo, analysis_memo }
  • page, page_size, has_more — pagination scalars

Example — Find JPMorgan systemic risk analyses

ARGUMENTS
{
  "ticker_filter": "JPM:US",
  "application": "Systemic Risk Analysis"
}
RESPONSE (ABBREVIATED)
{
  "results": [
    {
      "ticker": "JPM:US",
      "name": "JPMorgan Chase & Co",
      "application": "Systemic Risk Analysis",
      "model": "GMES",
      "dataset": "World Financials",
      "dataset_memo": "WORLDFIN-MR",
      "analysis_memo": "RISK.WORLDFIN-MR.GMES"
    },
    {
      "ticker": "JPM:US",
      "name": "JPMorgan Chase & Co",
      "application": "Systemic Risk Analysis",
      "model": "MES",
      "dataset": "U.S. Financials",
      "dataset_memo": "USFIN-MR",
      "analysis_memo": "RISK.USFIN-MR.MES"
    },
    {
      "ticker": "JPM:US",
      "name": "JPMorgan Chase & Co",
      "application": "Systemic Risk Analysis",
      "model": "MESSIM",
      "dataset": "U.S. Financials",
      "dataset_memo": "USFIN-MR",
      "analysis_memo": "RISK.USFIN-MR.MESSIM"
    }
  ],
  "page": 1,
  "has_more": false
}

02

Volatility

Conditional volatility estimates from GARCH-family models for individual assets, country aggregates, and global cross-sections. Coverage: 90 countries. Underlying methodology: ARCH (Engle, 1982), GARCH (Bollerslev, 1986), GJR-GARCH (Glosten, Jagannathan, Runkle, 1993). More on this methodology →

get_volatility

READ

Annualized volatility time series for an asset (GARCH-family models).

Parameters

NameTypeRequiredDescription
tickerstringoptionalAsset ticker with exchange suffix (e.g., "AAPL:US", "SPX:IND", "FTSE:LN"). The exchange suffix is required — use search_assets to find the correct format. Either ticker or analysis_memo is required.
analysis_memostringoptionalDirect analysis memo (e.g., "VOL.AAPL:US-R.GJR-GARCH"). Either ticker or analysis_memo is required.
modelstringoptionalModel name (e.g., "GJR-GARCH", "GARCH", "EGARCH"). Default: GJR-GARCH
dataset_memostringoptionalPass alongside ticker if you already have a dataset memo from search_assets or search_datasets. For this application, ticker alone uniquely identifies the analysis, so this parameter is for convenience and consistency with V-Lab's universal lookup convention rather than disambiguation. Cannot be used without ticker.
start_datestringoptionalFilter from date (YYYY-MM-DD format)
end_datestringoptionalFilter to date (YYYY-MM-DD format)
limitnumberoptionalMaximum data points to return (default: 252, ~1 year of trading days)
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • ticker, asset_name, model, dataset, analysis_memo, result_date — scalars
  • data — parallel arrays: date[], volatility[]
  • unit — typically "decimal (0.20 = 20% annualized)"
  • data_note — flags forward-looking forecast rows vs. historical filtered estimates

Example — Citigroup conditional volatility (latest 3 days)

ARGUMENTS
{
  "ticker": "C:US",
  "limit": 3
}
RESPONSE (ABBREVIATED)
{
  "ticker": "C:US",
  "asset_name": "Citigroup Inc",
  "model": "GJR-GARCH",
  "dataset": "Citigroup Inc Return Series",
  "analysis_memo": "VOL.C:US-R.GJR-GARCH",
  "result_date": "2026-04-24",
  "data": {
    "date": [
      "2026-04-22",
      "2026-04-23",
      "2026-04-24"
    ],
    "volatility": [
      0.3212,
      0.3155,
      0.3074
    ]
  },
  "unit": "decimal (0.20 = 20% annualized)"
}
Defaults to `GJR-GARCH` if available for the asset; falls back to `GARCH` otherwise. Volatility is reported as a decimal — multiply by 100 to display as percent. Use `search_analyses` to pin a specific model.

get_global_volatility_map

READ

Get relative volatility percentiles for all countries. Supports single-date snapshots OR time series with start_date/end_date. Data available from 1990 to present. Drill down: get_country_volatility (sectors) or get_country_market_summary (key indices).

Parameters

NameTypeRequiredDescription
datestringoptionalSingle date snapshot (YYYY-MM-DD). Defaults to latest. Ignored if start_date/end_date provided.
start_datestringoptionalStart date for time series (YYYY-MM-DD). Use with end_date for historical data.
end_datestringoptionalEnd date for time series (YYYY-MM-DD). Use with start_date for historical data.
countriesarray<string>optionalList of ISO3 country codes to filter (e.g., ["USA", "GBR", "JPN"]). Returns all countries if not specified.
limitnumberoptionalMax number of dates to return in time-series mode (default 252 ≈ one trading year, max 2500). Ignored for single-date mode.
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • date — observation date
  • countries — array of records: { iso3, name, percentile }
  • unit, total_countries — scalars

Example — Global volatility snapshot (latest)

ARGUMENTS
{}
RESPONSE (ABBREVIATED)
{
  "date": "2026-04-25",
  "countries": [
    {
      "iso3": "ARG",
      "name": "Argentina",
      "percentile": 0.1598
    },
    {
      "iso3": "AUS",
      "name": "Australia",
      "percentile": 0.6126
    },
    {
      "iso3": "USA",
      "name": "United States",
      "percentile": 0.4292
    },
    "..."
  ],
  "total_countries": 90,
  "unit": "percentile (0-1 scale, relative volatility)"
}
Coverage is 90 countries. `percentile` compares the country's current volatility level against its own history; `0.5` is median, `1.0` is the most volatile period on record.

get_country_volatility

READ

Get GICS sector/industry volatility breakdown for a specific country. Without industry param: returns sectors. With industry param (e.g. "20"): returns sub-industries. Drill down: get_country_industry_assets (individual assets within an industry).

Parameters

NameTypeRequiredDescription
countrystringrequiredISO3 country code (e.g., "USA", "GBR", "JPN")
industrystringoptionalGICS sector code to get sub-industries (e.g., "10" for Energy, "20" for Industrials)
datestringoptionalDate for snapshot (YYYY-MM-DD format). Defaults to latest available.
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • country, country_name, date — scalars
  • sectors — array of records: { code, name, relative_volatility, volatility, asset_count }
  • With industry param: sub_industries returned similarly

Example — US sector volatility breakdown

ARGUMENTS
{
  "country": "USA"
}
RESPONSE (ABBREVIATED)
{
  "country": "USA",
  "country_name": "United States",
  "date": "2026-04-25",
  "sectors": [
    {
      "code": "40",
      "name": "Financials",
      "relative_volatility": 0.4386,
      "volatility": 0.3238,
      "asset_count": 567
    },
    {
      "code": "45",
      "name": "Information Technology",
      "relative_volatility": 0.6124,
      "volatility": 0.6572,
      "asset_count": 331
    },
    "..."
  ]
}
Sector codes are 2-digit GICS sectors (10 Energy, 15 Materials, … 60 Real Estate). Pass the 2-digit code as `industry` to drill down to 6-digit sub-industries.

get_country_market_summary

READ

Get market summary for a country showing key indices with current volatility levels and changes, grouped by market type (Equities, Currencies, etc.). Drill down: get_volatility (full time series for any asset).

Parameters

NameTypeRequiredDescription
countrystringrequiredISO3 country code (e.g., "USA", "GBR", "JPN")
market_typestringoptionalFilter by market type (e.g., "Equities", "Fixed Income", "Commodities")
datestringoptionalDate for snapshot (YYYY-MM-DD format). Defaults to latest available.
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • country, country_name, date — scalars
  • markets — object grouped by market type (snake_case keys: equities, currencies, fixed_income, commodities, ...)
  • markets.<group> — array of records, each: { ticker, name, volatility, vol_change, analysis_memo }
  • units — scalar object describing volatility and vol_change units

Example — Key US indices snapshot

ARGUMENTS
{
  "country": "USA"
}
RESPONSE (ABBREVIATED)
{
  "country": "USA",
  "date": "2026-04-24",
  "markets": {
    "equities": [
      {
        "ticker": "SPX:IND",
        "name": "S&P 500 Index",
        "volatility": 0.1146,
        "vol_change": -0.0036,
        "analysis_memo": "VOL.SPX:IND-R.GJR-GARCH"
      },
      {
        "ticker": "INDU:IND",
        "name": "Dow Jones Industrial Average",
        "volatility": 0.1116,
        "vol_change": -0.0034,
        "analysis_memo": "VOL.INDU:IND-R.GJR-GARCH"
      },
      {
        "ticker": "CCMP:IND",
        "name": "NASDAQ Composite Index",
        "volatility": 0.1678,
        "vol_change": -0.0016,
        "analysis_memo": "VOL.CCMP:IND-R.GJR-GARCH"
      },
      {
        "ticker": "W5000:IND",
        "name": "Wilshire 5000 Total Market Index",
        "volatility": 0.1188,
        "vol_change": -0.0009,
        "analysis_memo": "VOL.W5000:IND-R.GJR-GARCH"
      },
      {
        "ticker": "RTY:IND",
        "name": "Russell 2000 Index",
        "volatility": 0.162,
        "vol_change": -0.0068,
        "analysis_memo": "VOL.RTY:IND-R.GJR-GARCH"
      }
    ],
    "currencies": [
      {
        "ticker": "DXY:FOREX",
        "name": "United States Dollar Index",
        "volatility": 0.0596,
        "vol_change": -0.0008,
        "analysis_memo": "VOL.DXY:FOREX-R.GJR-GARCH"
      }
    ]
  }
}
Up to 5 instruments per market group. Groups are keyed by snake_case market type — e.g., "equities", "currencies", "fixed_income". To restrict to one group, pass market_type=Equities (Title Case in the parameter); the response then contains only that single group.

get_country_industry_assets

READ

Get individual assets within a GICS industry for a country, with relative volatility percentiles and levels. Use after get_country_volatility to drill down from sector/industry to individual assets. Part of the volatility hierarchy.

Parameters

NameTypeRequiredDescription
countrystringrequiredISO3 country code (e.g., "USA", "GBR", "JPN")
industrystringrequiredGICS industry code (e.g., "201030" for Construction & Engineering). Get these from get_country_volatility with an industry parameter.
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • country, country_name, industry, industry_name — scalars
  • assets — array of records: { ticker, name, relative_volatility, volatility }
  • total_assets — scalar

Example — US Commercial Banks ranked by relative volatility

ARGUMENTS
{
  "country": "USA",
  "industry": "401010"
}
RESPONSE (ABBREVIATED)
{
  "country": "USA",
  "industry": "401010",
  "industry_name": "Commercial Banks",
  "assets": [
    {
      "ticker": "WASH:US",
      "name": "Washington Trust Bancorp Inc",
      "relative_volatility": 0.9897,
      "volatility": 0.9171
    },
    {
      "ticker": "JPM:US",
      "name": "JPMorgan Chase & Co",
      "relative_volatility": 0.3433,
      "volatility": 0.2229
    },
    "..."
  ],
  "total_assets": 269
}
Industry codes are 6-digit GICS (e.g., `401010` Commercial Banks, `402010` Financial Services, `403010` Insurance). Get them from `get_country_volatility` with a 2-digit `industry` parameter.

03

Long-Run Value at Risk

Loss estimates over 30-day and 365-day horizons across multiple percentiles and model families. Forward-looking risk measure derived from V-Lab's volatility forecasts. More on this methodology →

get_lrvar_summary

READ

Current Long-Run VaR across all horizons and percentiles (decimals, e.g., -0.1435 = 14.35% loss). Returns LRGJRF (return-series) and/or LRGJROF (options-augmented) where available.

Parameters

NameTypeRequiredDescription
tickerstringrequiredAsset ticker with exchange suffix (e.g., "SPY:US", "SPX:IND", "FTSE:LN"). The exchange suffix is required — use search_assets to find the correct format.
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • ticker, name, result_date — scalars
  • models — array of records: { model, model_name, analysis_memo, result_date, last_data_date, var_30d_p1, var_30d_p5, var_365d_p1, var_365d_p5 }
  • unit — scalar

Example — Long-Run VaR snapshot for SPY

ARGUMENTS
{
  "ticker": "SPY:US"
}
RESPONSE (ABBREVIATED)
{
  "ticker": "SPY:US",
  "name": "State Street SPDR S&P 500 ETF Trust",
  "result_date": "2026-04-24",
  "models": [
    {
      "model": "LRGJRF",
      "model_name": "Long-Run GJR-GARCH Forecast",
      "analysis_memo": "LTR.SPY:US-R.LRGJRF",
      "var_30d_p1": -0.1148,
      "var_30d_p5": -0.0659,
      "var_365d_p1": -0.4753,
      "var_365d_p5": -0.2814
    }
  ]
}
Returns LRGJRF (return-series) and/or LRGJROF (options-augmented) where available. VaR values are decimals — −0.1148 means a 1% chance of losing ≥ 11.48% over 30 days.

get_lrvar

READ

Long-Run VaR time series for an analysis (decimals, e.g., -0.1435 = 14.35% loss). Horizons: 30d (tactical) or 365d (strategic). Percentiles: 1 or 5.

Parameters

NameTypeRequiredDescription
tickerstringoptionalAsset ticker with exchange suffix (e.g., "SPY:US", "SPX:IND", "FTSE:LN"). The exchange suffix is required — use search_assets to find the correct format. Either ticker or analysis_memo is required.
analysis_memostringoptionalAnalysis memo (e.g., 'LTR.SPX:IND-R.LRGJRF'). Either ticker or analysis_memo is required.
modelstringoptionalModel memo (LRGJRF or LRGJROF)
dataset_memostringoptionalPass alongside ticker if you already have a dataset memo from search_assets or search_datasets. For this application, ticker alone uniquely identifies the analysis, so this parameter is for convenience and consistency with V-Lab's universal lookup convention rather than disambiguation. Cannot be used without ticker.
horizonnumber (enum)optionalVaR horizon in calendar days: 30 (≈1 month, tactical) or 365 (1 year, strategic). Default 30.
Allowed values:
  • 30,
  • 365
percentilenumber (enum)optionalVaR percentile (default 1)
Allowed values:
  • 1,
  • 5
start_datestringoptionalStart date (YYYY-MM-DD)
end_datestringoptionalEnd date (YYYY-MM-DD)
limitnumberoptionalMax data points (default 252, max 10000)
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • ticker, asset_name, model, model_name, analysis_memo — scalars
  • horizon_days, percentile — scalars
  • data — parallel arrays: date[], var_value[]
  • unit — scalar

Example — SPY 30-day, 1% VaR time series

ARGUMENTS
{
  "ticker": "SPY:US",
  "horizon": 30,
  "percentile": 1,
  "limit": 3
}
RESPONSE (ABBREVIATED)
{
  "ticker": "SPY:US",
  "model": "LRGJRF",
  "analysis_memo": "LTR.SPY:US-R.LRGJRF",
  "horizon_days": 30,
  "percentile": 1,
  "data": {
    "date": [
      "2026-04-22",
      "2026-04-23",
      "2026-04-24"
    ],
    "var_value": [
      -0.117,
      -0.1172,
      -0.1148
    ]
  },
  "unit": "decimal (-0.1435 = 14.35% potential loss)"
}

04

Systemic risk (SRISK)

Capital shortfall a financial firm would face in a 40% market decline over six months. SRISK aggregates by country and globally to measure systemic exposure. Coverage: 22 country and regional analyses; 2,189 firms in the World Financials universe. Underlying methodology: Acharya, Engle, Richardson (2012); Brownlees and Engle (Review of Financial Studies, 2017). More on this methodology →

list_srisk_analyses

READ

List available SRISK (systemic risk) analyses with regions and coverage. Part of the SRISK hierarchy: list_srisk_analyses → get_srisk_ranking → get_country_srisk → get_firm_srisk.

Parameters

NameTypeRequiredDescription
region_filterstringoptionalFilter by region using a 3-letter ISO 3166-1 country code (e.g., "USA", "JPN", "DEU", "GBR") or "WORLD" for the global aggregate.
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • analyses — array of records: { memo, name, region, firm_count, date_range }
  • analyses[].region — 3-letter ISO 3166-1 country code (e.g., "USA", "JPN") or "WORLD" for the global aggregate
  • analyses[].date_range — nested object { start, end }
  • total_count, region_filter — scalars

Example — All SRISK analyses available

ARGUMENTS
{}
RESPONSE (ABBREVIATED)
{
  "analyses": [
    {
      "memo": "RISK.WORLDFIN-MR.GMES",
      "name": "World Financials",
      "region": "WORLD",
      "firm_count": 2189,
      "date_range": {
        "start": "2000-06-30",
        "end": "2026-04-23"
      }
    },
    {
      "memo": "RISK.USFIN-MR.MES",
      "name": "U.S. Financials",
      "region": "USA",
      "firm_count": 1010,
      "date_range": {
        "start": "2000-01-31",
        "end": "2026-04-23"
      }
    },
    {
      "memo": "RISK.JPFIN-MR.DMES",
      "name": "Japan Financials",
      "region": "JPN",
      "firm_count": 66,
      "date_range": {
        "start": "2000-01-31",
        "end": "2026-04-23"
      }
    },
    "..."
  ],
  "total_count": 22
}
region_filter accepts a 3-letter ISO 3166-1 country code (e.g., "USA", "JPN", "DEU", "GBR") or "WORLD" for the global aggregate. Downstream SRISK tools (get_srisk_ranking, get_country_srisk, get_firm_srisk, get_srisk_movers) report monetary values in the currency of the chosen analysis. USD analyses (.GMES, .MES, .MESSIM) report in USD billions; per-country .DMES analyses report in the country's local currency (JPY, EUR, GBP, AUD, CAD, CHF, CNY, DKK, NZD). Each downstream response carries a top-level currency (ISO 4217) and unit field.

get_srisk_ranking

READ

Get top entities ranked by SRISK (systemic risk). Can rank firms (default), countries, regions (continents), or markets. Includes concentration metrics (HHI, top-N share). Part of the SRISK hierarchy: list_srisk_analyses → get_srisk_ranking → get_country_srisk → get_firm_srisk. Data note: SRISK relies on balance sheet data which may arrive with a lag; values for recent quarters may be revised as updates are received from data providers.

Parameters

NameTypeRequiredDescription
aggregate_bystring (enum)optionalAggregation level: "firm" (default), "country", "region" (continent: Africa, Americas, Asia, Europe), or "market" (Developed, Emerging, Frontier, EAFE)
Allowed values:
  • firm,
  • country,
  • region,
  • market
datestringoptionalDate (YYYY-MM-DD). Defaults to latest available.
analysis_memostringoptionalAnalysis memo to use (e.g., "RISK.WORLDFIN-MR.GMES", "RISK.USFIN-MR.MES"). Default: RISK.WORLDFIN-MR.GMES
countrystringoptionalISO3 country code to filter by (e.g., "USA", "CHN", "GBR"). Only applies when aggregate_by=firm.
limitnumberoptionalMaximum number of results to return (default: 10, max: 50)
rank_bystringoptionalMetric to rank by: "srisk" (capital shortfall), "lrmes" (long-run marginal expected shortfall), or "leverage". Default: srisk. Note: lrmes and leverage only apply to firm aggregation.
include_changebooleanoptionalInclude period-over-period change data with attribution breakdown (debt/equity/risk/composition). Works with all aggregation levels. Default: false
change_periodstring (enum)optionalComparison period for change calculation: "1m" through "12m" (months), or "1y" (= 12m). Default: "1m". SRISK data is available at monthly frequency. The response shows both the current date and comparison_date used.
Allowed values:
  • 1m
  • 2m
  • 3m
  • 4m
  • 5m
  • 6m
  • 7m
  • 8m
  • 9m
  • 10m
  • 11m
  • 12m
  • 1y
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • date, analysis, analysis_name, aggregate_by, rank_by — scalars
  • rankings — array of records: { rank, ticker, name, country, srisk, marginal_srisk, lrmes, beta, leverage, stressed_leverage, size_percentile }
  • total_srisk, currency, unit — scalars
  • concentration — nested object: { hhi, hhi_interpretation, top_5_share, top_10_share, top_20_share }

Example — Top 5 systemic firms globally

ARGUMENTS
{
  "limit": 5
}
RESPONSE (ABBREVIATED)
{
  "date": "2026-04-23",
  "analysis": "RISK.WORLDFIN-MR.GMES",
  "rankings": [
    {
      "rank": 1,
      "ticker": "601398:CH",
      "name": "Industrial & Commercial Bank of China Ltd",
      "country": "CHN",
      "srisk": 248,
      "lrmes": 0.0975,
      "leverage": 19.56
    },
    {
      "rank": 2,
      "ticker": "939:HK",
      "name": "China Construction Bank Corp",
      "country": "CHN",
      "srisk": 246.2,
      "lrmes": 0.267,
      "leverage": 18.31
    },
    {
      "rank": 3,
      "ticker": "601288:CH",
      "name": "Agricultural Bank of China Ltd",
      "country": "CHN",
      "srisk": 238,
      "lrmes": 0.1288,
      "leverage": 19.45
    },
    {
      "rank": 4,
      "ticker": "3988:HK",
      "name": "Bank of China Ltd",
      "country": "CHN",
      "srisk": 223.2,
      "lrmes": 0.2533,
      "leverage": 20.3
    },
    {
      "rank": 5,
      "ticker": "1658:HK",
      "name": "Postal Savings Bank of China Co Ltd",
      "country": "CHN",
      "srisk": 132.7,
      "lrmes": 0.1857,
      "leverage": 28.72
    }
  ],
  "total_srisk": 4288.2,
  "currency": "USD",
  "unit": "USD B",
  "concentration": {
    "hhi": 0.0215,
    "top_5_share": 25.4,
    "top_10_share": 37.8
  }
}
Monetary values are reported in the currency of the underlying analysis (see the response's `currency` and `unit` fields). USD analyses (.GMES, .MES, .MESSIM) report in USD billions; per-country .DMES analyses report in the country's local currency (e.g., JPY B for Japan, EUR B for Eurozone countries). Concentration uses the Herfindahl-Hirschman Index on firm shares of total SRISK; top_N_share is the cumulative percent of total held by the top N firms.

get_country_srisk

READ

Get SRISK data for a specific country. Returns either firm rankings (default) or country-level time series with time_series=true. Part of the SRISK hierarchy: list_srisk_analyses → get_srisk_ranking → get_country_srisk → get_firm_srisk.

Parameters

NameTypeRequiredDescription
countrystringrequiredISO3 country code (e.g., "USA", "CHN", "GBR", "JPN")
analysis_memostringoptionalAnalysis memo to use (e.g., "RISK.WORLDFIN-MR.GMES", "RISK.JPFIN-MR.DMES"). Default: RISK.WORLDFIN-MR.GMES
time_seriesbooleanoptionalReturn time series instead of firm list. Includes total SRISK, capacity, and probability of crisis. Default: false
frequencystring (enum)optionalTime series sampling frequency (only used with time_series=true). M=monthly (default), Q=quarterly, Y=yearly.
Allowed values:
  • M,
  • Q,
  • Y
datestringoptionalDate for firm rankings (YYYY-MM-DD). Ignored if time_series=true. Defaults to latest.
start_datestringoptionalStart date for time series (YYYY-MM-DD). Only used with time_series=true.
end_datestringoptionalEnd date for time series (YYYY-MM-DD). Only used with time_series=true.
limitnumberoptionalMax firms (1-100, default: 20) or data points for time series (1-10000, default: 252)
sort_bystringoptionalSort metric for firm rankings: "srisk", "lrmes", or "leverage". Default: srisk
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • country, country_name, date, total_srisk, currency, unit — scalars
  • firms — array of records: { rank, ticker, name, srisk, marginal_srisk, lrmes, leverage, stressed_leverage, size_percentile }
  • With time_series=true: data parallel arrays of date[], total_srisk[], capacity[], prob_of_crisis[] instead of firms

Example — Top 5 US systemic firms

ARGUMENTS
{
  "country": "USA",
  "limit": 5
}
RESPONSE (ABBREVIATED)
{
  "country": "USA",
  "date": "2026-04-23",
  "total_srisk": 368.8,
  "firms": [
    {
      "rank": 1,
      "ticker": "C:US",
      "name": "Citigroup Inc",
      "srisk": 93.2,
      "lrmes": 0.4928,
      "leverage": 12.15
    },
    {
      "rank": 2,
      "ticker": "PRU:US",
      "name": "Prudential Financial Inc",
      "srisk": 35.5,
      "lrmes": 0.5354,
      "leverage": 19.8
    },
    {
      "rank": 3,
      "ticker": "BAC:US",
      "name": "Bank of America Corp",
      "srisk": 34.1,
      "lrmes": 0.3765,
      "leverage": 9.31
    },
    {
      "rank": 4,
      "ticker": "WFC:US",
      "name": "Wells Fargo & Co",
      "srisk": 23.3,
      "lrmes": 0.4099,
      "leverage": 8.97
    },
    {
      "rank": 5,
      "ticker": "MET:US",
      "name": "MetLife Inc",
      "srisk": 22.8,
      "lrmes": 0.4032,
      "leverage": 13.6
    }
  ],
  "currency": "USD",
  "unit": "USD B"
}
Monetary values are reported in the currency of the underlying analysis (see the response's `currency` and `unit` fields). USD analyses (.GMES, .MES, .MESSIM) report in USD billions; per-country .DMES analyses report in the country's local currency. With `time_series=true`, the response carries the same `currency` and `unit` fields and applies them to every value in the series block.

get_firm_srisk

READ

Get SRISK time series for a specific firm. Part of the SRISK hierarchy: list_srisk_analyses → get_srisk_ranking → get_country_srisk → get_firm_srisk.

Parameters

NameTypeRequiredDescription
tickerstringrequiredFirm ticker with exchange suffix (e.g., "JPM:US", "HSBA:LN", "1398:HK"). The exchange suffix is required — use search_assets to find the correct format.
analysis_memostringoptionalAnalysis memo (e.g., "RISK.USFIN-MR.MES"). Auto-detected from ticker if not specified.
start_datestringoptionalStart date (YYYY-MM-DD)
end_datestringoptionalEnd date (YYYY-MM-DD)
limitnumberoptionalMaximum data points to return (default: 252, max: 10000)
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • ticker, asset_name, analysis_memo, result_date — scalars
  • data — parallel arrays: date[], srisk[], marginal_srisk[], lrmes[], beta[], correlation[], volatility[], leverage[], stressed_leverage[]
  • current_values — nested object (not pivoted; single snapshot, not a list)
  • currency, unit, data_note — scalars

Example — Citigroup SRISK time series

ARGUMENTS
{
  "ticker": "C:US",
  "limit": 3
}
RESPONSE (ABBREVIATED)
{
  "ticker": "C:US",
  "asset_name": "Citigroup Inc",
  "analysis_memo": "RISK.WORLDFIN-MR.GMES",
  "result_date": "2026-04-23",
  "data": {
    "date": [
      "2026-04-21",
      "2026-04-22",
      "2026-04-23"
    ],
    "srisk": [
      97.2,
      92.2,
      93.2
    ],
    "lrmes": [
      0.5246,
      0.4928,
      0.4928
    ],
    "leverage": [
      11.88,
      12.04,
      12.15
    ]
  },
  "current_values": {
    "srisk": 93.2,
    "marginal_srisk": 99.4,
    "lrmes": 0.4928,
    "leverage": 12.15,
    "size_percentile": 99
  },
  "currency": "USD",
  "unit": "USD B"
}
Monetary values are reported in the currency of the underlying analysis (see the response's `currency` and `unit` fields). USD analyses (.GMES, .MES, .MESSIM) report in USD billions; per-country .DMES analyses report in the country's local currency. To compare values across firms, ensure the firms come from the same analysis — values from different analyses may be in different currencies.

get_srisk_movers

READ

Get firms with largest SRISK changes over a period. Returns top increases and/or decreases with change attribution (debt/equity/risk breakdown). Part of the SRISK hierarchy for identifying risk trends.

Parameters

NameTypeRequiredDescription
periodstring (enum)optionalComparison period: "1m" through "12m" (months), or "1y" (= 12m). Default: "1m". SRISK data is available at monthly frequency.
Allowed values:
  • 1m
  • 2m
  • 3m
  • 4m
  • 5m
  • 6m
  • 7m
  • 8m
  • 9m
  • 10m
  • 11m
  • 12m
  • 1y
directionstring (enum)optionalFilter direction: "up" (increases only), "down" (decreases only), "both" (default)
Allowed values:
  • up,
  • down,
  • both
analysis_memostringoptionalAnalysis memo to use (e.g., "RISK.WORLDFIN-MR.GMES"). Default: RISK.WORLDFIN-MR.GMES
countrystringoptionalISO3 country code to filter by (e.g., "USA", "CHN", "GBR")
limitnumberoptionalMaximum results per direction (default: 10, max: 25)
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • date, comparison_date, period, analysis, analysis_name — scalars
  • top_increases, top_decreases — array of records: { rank, ticker, name, country, srisk_current, srisk_previous, change_absolute, change_percent, attribution, current_rank, previous_rank }
  • top_*[].attribution — nested object: { debt, equity, risk }
  • summary — nested object: { firms_increased, firms_decreased, total_change, total_change_pct }
  • currency, unit — scalars

Example — Largest 1-month SRISK changes globally

ARGUMENTS
{
  "period": "1m",
  "limit": 3
}
RESPONSE (ABBREVIATED)
{
  "date": "2026-04-23",
  "comparison_date": "2026-02-27",
  "period": "1m",
  "top_increases": [
    {
      "rank": 1,
      "ticker": "UCG:IM",
      "name": "UniCredit SpA",
      "country": "ITA",
      "srisk_current": 12.8,
      "srisk_previous": -5,
      "change_absolute": 17.8,
      "attribution": {
        "debt": 0,
        "equity": 5.8,
        "risk": 12
      }
    },
    {
      "rank": 2,
      "ticker": "NAB:AU",
      "name": "National Australia Bank Ltd",
      "country": "AUS",
      "srisk_current": 9.4,
      "srisk_previous": -6.7,
      "change_absolute": 16.1,
      "attribution": {
        "debt": 0,
        "equity": 9.8,
        "risk": 6.3
      }
    },
    {
      "rank": 3,
      "ticker": "BNP:FP",
      "name": "BNP Paribas SA",
      "country": "FRA",
      "srisk_current": 119.7,
      "srisk_previous": 104,
      "change_absolute": 15.8,
      "attribution": {
        "debt": 0,
        "equity": 3.7,
        "risk": 12
      }
    }
  ],
  "top_decreases": [
    {
      "rank": 1,
      "ticker": "MS:US",
      "name": "Morgan Stanley",
      "country": "USA",
      "srisk_current": -31.1,
      "srisk_previous": 4.9,
      "change_absolute": -36,
      "attribution": {
        "debt": 0,
        "equity": -14.1,
        "risk": -21.9
      }
    },
    {
      "rank": 2,
      "ticker": "939:HK",
      "name": "China Construction Bank Corp",
      "country": "CHN",
      "srisk_current": 246.2,
      "srisk_previous": 281.8,
      "change_absolute": -35.6,
      "attribution": {
        "debt": 0,
        "equity": -23.6,
        "risk": -12
      }
    },
    {
      "rank": 3,
      "ticker": "C:US",
      "name": "Citigroup Inc",
      "country": "USA",
      "srisk_current": 93.2,
      "srisk_previous": 126.6,
      "change_absolute": -33.5,
      "attribution": {
        "debt": 0,
        "equity": -10.9,
        "risk": -22.6
      }
    }
  ],
  "summary": {
    "firms_increased": 290,
    "firms_decreased": 196,
    "total_change": -82.1,
    "total_change_pct": -1.9
  }
}
Monetary values are reported in the currency of the underlying analysis (see the response's `currency` and `unit` fields). USD analyses (.GMES, .MES, .MESSIM) report in USD billions; per-country .DMES analyses report in the country's local currency. Negative SRISK means the firm is over-capitalized for the modeled stress scenario — a capital surplus rather than a shortfall.

05

Climate risk (CRISK)

Expected capital shortfall for financial institutions under a climate-risk factor shock — the climate-conditioned analog of SRISK. Includes per-firm climate beta. Coverage: 2,189 firms in the World Financials universe. Underlying methodology: Jung, Engle, Berner (NBER Working Paper, 2023). More on this methodology →

list_crisk_analyses

READ

List available CRISK (climate risk) analyses with coverage. CRISK is the climate-stress analog of SRISK, measuring expected capital shortfall under a climate-risk factor shock. Part of the CRISK hierarchy: list_crisk_analyses → get_crisk_ranking → get_country_crisk → get_firm_crisk.

Parameters

NameTypeRequiredDescription
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • analyses — array of records: { memo, name, region, firm_count, date_range }
  • analyses[].region — "WORLD" for the global aggregate
  • analyses[].date_range — nested object { start, end }
  • total_count, note — scalars

Example — Available CRISK analyses

ARGUMENTS
{}
RESPONSE (ABBREVIATED)
{
  "analyses": [
    {
      "memo": "CLIM.WORLDFIN-MR.CMES",
      "name": "World Financials",
      "region": "WORLD",
      "firm_count": 2189,
      "date_range": {
        "start": "2000-06-30",
        "end": "2026-04-23"
      }
    }
  ],
  "total_count": 1,
  "note": "CRISK uses climate stress (50% shock to climate beta) instead of market stress."
}
CRISK has a single global analysis (`CLIM.WORLDFIN-MR.CMES`), reported in USD billions. Downstream CRISK tools (get_crisk_ranking, get_country_crisk, get_firm_crisk, get_crisk_movers) carry top-level currency (ISO 4217) and unit fields on every response.

get_crisk_ranking

READ

Get top entities ranked by CRISK (climate-stress capital shortfall). Can rank firms (default), countries, regions (continents), or markets. Includes concentration metrics (HHI, top-N share). Part of the CRISK hierarchy: list_crisk_analyses → get_crisk_ranking → get_country_crisk → get_firm_crisk. Data note: CRISK relies on balance sheet data which may arrive with a lag; values for recent quarters may be revised as updates are received from data providers.

Parameters

NameTypeRequiredDescription
aggregate_bystring (enum)optionalAggregation level: "firm" (default), "country", "region" (continent: Africa, Americas, Asia, Europe), or "market" (Developed, Emerging, Frontier, EAFE)
Allowed values:
  • firm,
  • country,
  • region,
  • market
datestringoptionalDate (YYYY-MM-DD). Defaults to latest available.
analysis_memostringoptionalAnalysis memo to use (e.g., "CLIM.WORLDFIN-MR.CMES"). Default: CLIM.WORLDFIN-MR.CMES
countrystringoptionalISO3 country code to filter by (e.g., "USA", "CHN", "GBR"). Only applies when aggregate_by=firm.
limitnumberoptionalMaximum number of results to return (default: 10, max: 50)
rank_bystringoptionalMetric to rank by: "crisk" (climate capital shortfall), "climate_lrmes" (long-run marginal expected shortfall under climate stress), or "leverage". Default: crisk. Note: climate_lrmes and leverage only apply to firm aggregation.
include_changebooleanoptionalInclude period-over-period change data with attribution breakdown (debt/equity/risk/composition). Works with all aggregation levels. Default: false
change_periodstring (enum)optionalComparison period for change calculation: "1m" through "12m" (months), or "1y" (= 12m). Default: "1m". CRISK data is available at monthly frequency. The response shows both the current date and comparison_date used.
Allowed values:
  • 1m
  • 2m
  • 3m
  • 4m
  • 5m
  • 6m
  • 7m
  • 8m
  • 9m
  • 10m
  • 11m
  • 12m
  • 1y
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • date, analysis, analysis_name, aggregate_by, rank_by — scalars
  • rankings — array of records: { rank, ticker, name, country, crisk, marginal_crisk, climate_lrmes, beta, cbeta, volatility, leverage, stressed_leverage, size_percentile }
  • total_crisk, currency, unit, concentration — scalars / nested object

Example — Top firms by climate-stress capital shortfall

ARGUMENTS
{
  "limit": 5
}
RESPONSE (ABBREVIATED)
{
  "date": "2026-04-23",
  "analysis": "CLIM.WORLDFIN-MR.CMES",
  "rankings": [
    {
      "rank": 1,
      "ticker": "601398:CH",
      "name": "Industrial & Commercial Bank of China Ltd",
      "country": "CHN",
      "crisk": 218.3,
      "climate_lrmes": 0.0123,
      "cbeta": 0.02
    },
    {
      "rank": 2,
      "ticker": "939:HK",
      "name": "China Construction Bank Corp",
      "country": "CHN",
      "crisk": 216.6,
      "climate_lrmes": 0.1742,
      "cbeta": 0.28
    },
    {
      "rank": 3,
      "ticker": "3988:HK",
      "name": "Bank of China Ltd",
      "country": "CHN",
      "crisk": 214.7,
      "climate_lrmes": 0.2177,
      "cbeta": 0.35
    },
    {
      "rank": 4,
      "ticker": "601288:CH",
      "name": "Agricultural Bank of China Ltd",
      "country": "CHN",
      "crisk": 188.7,
      "climate_lrmes": -0.0228,
      "cbeta": -0.03
    },
    {
      "rank": 5,
      "ticker": "1658:HK",
      "name": "Postal Savings Bank of China Co Ltd",
      "country": "CHN",
      "crisk": 126.3,
      "climate_lrmes": 0.1094,
      "cbeta": 0.17
    }
  ],
  "total_crisk": 2929.2,
  "currency": "USD",
  "unit": "USD B"
}
Monetary values are reported in the currency of the underlying analysis (see the response's `currency` and `unit` fields). CRISK has a single global analysis (`CLIM.WORLDFIN-MR.CMES`), reported in USD billions. cbeta is the firm's climate beta — sensitivity to the climate-risk factor. Negative cbeta firms can have negative CRISK (climate-conditioned capital surplus).

get_country_crisk

READ

Get CRISK data for a specific country. Returns either firm rankings (default) or country-level time series with time_series=true. Part of the CRISK hierarchy: list_crisk_analyses → get_crisk_ranking → get_country_crisk → get_firm_crisk.

Parameters

NameTypeRequiredDescription
countrystringrequiredISO3 country code (e.g., "USA", "CHN", "GBR", "JPN")
analysis_memostringoptionalAnalysis memo to use (e.g., "CLIM.WORLDFIN-MR.CMES"). Default: CLIM.WORLDFIN-MR.CMES (global financials in USD)
time_seriesbooleanoptionalReturn time series instead of firm list. Includes total CRISK and marginal CRISK. Default: false
frequencystring (enum)optionalTime series sampling frequency (only used with time_series=true). M=monthly (default), Q=quarterly, Y=yearly.
Allowed values:
  • M,
  • Q,
  • Y
datestringoptionalDate for firm rankings (YYYY-MM-DD). Ignored if time_series=true. Defaults to latest.
start_datestringoptionalStart date for time series (YYYY-MM-DD). Only used with time_series=true.
end_datestringoptionalEnd date for time series (YYYY-MM-DD). Only used with time_series=true.
limitnumberoptionalMax firms (1-100, default: 20) or data points for time series (1-10000, default: 252)
sort_bystringoptionalSort metric for firm rankings: "crisk", "climate_lrmes", or "leverage". Default: crisk
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • country, country_name, date, total_crisk, currency, unit — scalars
  • firms[] — { rank, ticker, name, crisk, marginal_crisk, climate_lrmes, beta, cbeta, leverage, stressed_leverage, size_percentile }
  • With time_series=true: data parallel arrays of date[], total_crisk[], marginal_crisk[]

Example — Top 5 US firms by CRISK

ARGUMENTS
{
  "country": "USA",
  "limit": 5
}
RESPONSE (ABBREVIATED)
{
  "country": "USA",
  "date": "2026-04-23",
  "total_crisk": 99,
  "firms": [
    {
      "rank": 1,
      "ticker": "LNC:US",
      "name": "Lincoln National Corp",
      "crisk": 17,
      "climate_lrmes": -0.0703,
      "cbeta": -0.1
    },
    {
      "rank": 2,
      "ticker": "EQH:US",
      "name": "Equitable Holdings Inc",
      "crisk": 14,
      "climate_lrmes": -0.0514,
      "cbeta": -0.07
    },
    {
      "rank": 3,
      "ticker": "CRBG:US",
      "name": "Corebridge Financial Inc",
      "crisk": 13.9,
      "climate_lrmes": -0.2088,
      "cbeta": -0.27
    },
    {
      "rank": 4,
      "ticker": "PRU:US",
      "name": "Prudential Financial Inc",
      "crisk": 13.7,
      "climate_lrmes": -0.1845,
      "cbeta": -0.24
    },
    {
      "rank": 5,
      "ticker": "BHF:US",
      "name": "Brighthouse Financial Inc",
      "crisk": 12.1,
      "climate_lrmes": 0.2112,
      "cbeta": 0.34
    }
  ],
  "currency": "USD",
  "unit": "USD B"
}
Monetary values are reported in the currency of the underlying analysis (see the response's `currency` and `unit` fields). CRISK has a single global analysis (`CLIM.WORLDFIN-MR.CMES`), reported in USD billions.

get_firm_crisk

READ

Get CRISK time series for a specific firm. CRISK is computed from components (climate beta, market cap, book assets, book equity) using a 50% climate stress shock. Part of the CRISK hierarchy: list_crisk_analyses → get_crisk_ranking → get_country_crisk → get_firm_crisk.

Parameters

NameTypeRequiredDescription
tickerstringrequiredFirm ticker with exchange suffix (e.g., "JPM:US", "HSBA:LN", "1398:HK"). The exchange suffix is required — use search_assets to find the correct format.
analysis_memostringoptionalAnalysis memo (e.g., "CLIM.WORLDFIN-MR.CMES"). Auto-detected from ticker if not specified.
start_datestringoptionalStart date (YYYY-MM-DD)
end_datestringoptionalEnd date (YYYY-MM-DD)
limitnumberoptionalMaximum data points to return (default: 252, max: 10000)
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • ticker, asset_name, analysis_memo, result_date — scalars
  • data — parallel arrays: date[], crisk[], marginal_crisk[], climate_lrmes[], cbeta[], beta[], correlation[], volatility[], leverage[], stressed_leverage[]
  • current_values, currency, unit, data_note — scalars / nested object

Example — Citigroup CRISK time series

ARGUMENTS
{
  "ticker": "C:US",
  "limit": 3
}
RESPONSE (ABBREVIATED)
{
  "ticker": "C:US",
  "asset_name": "Citigroup Inc",
  "analysis_memo": "CLIM.WORLDFIN-MR.CMES",
  "result_date": "2026-04-23",
  "data": {
    "date": [
      "2026-04-21",
      "2026-04-22",
      "2026-04-23"
    ],
    "crisk": [
      -52.6,
      -47.1,
      -59.2
    ],
    "climate_lrmes": [
      -0.2007,
      -0.1918,
      -0.2628
    ],
    "cbeta": [
      -0.26,
      -0.25,
      -0.34
    ],
    "leverage": [
      11.88,
      12.04,
      12.15
    ]
  },
  "current_values": {
    "crisk": -59.2,
    "climate_lrmes": -0.2628,
    "cbeta": -0.34,
    "size_percentile": 99
  },
  "currency": "USD",
  "unit": "USD B"
}
Monetary values are reported in the currency of the underlying analysis (see the response's `currency` and `unit` fields). CRISK has a single global analysis (`CLIM.WORLDFIN-MR.CMES`), reported in USD billions. CRISK can be negative — a firm with negative climate beta benefits from the climate-stress scenario rather than suffers, and shows as a capital surplus.

get_crisk_movers

READ

Get firms with largest CRISK changes over a period. Returns top increases and/or decreases with change attribution (debt/equity/risk breakdown). Part of the CRISK hierarchy for identifying climate risk trends.

Parameters

NameTypeRequiredDescription
periodstring (enum)optionalComparison period: "1m" through "12m" (months), or "1y" (= 12m). Default: "1m". CRISK data is available at monthly frequency.
Allowed values:
  • 1m
  • 2m
  • 3m
  • 4m
  • 5m
  • 6m
  • 7m
  • 8m
  • 9m
  • 10m
  • 11m
  • 12m
  • 1y
directionstring (enum)optionalFilter direction: "up" (increases only), "down" (decreases only), "both" (default)
Allowed values:
  • up,
  • down,
  • both
analysis_memostringoptionalAnalysis memo to use (e.g., "CLIM.WORLDFIN-MR.CMES"). Default: CLIM.WORLDFIN-MR.CMES
countrystringoptionalISO3 country code to filter by (e.g., "USA", "CHN", "GBR")
limitnumberoptionalMaximum results per direction (default: 10, max: 25)
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • date, comparison_date, period, analysis — scalars
  • top_increases[], top_decreases[] — { ticker, name, country, crisk_current, crisk_previous, change_absolute, change_percent, attribution }
  • summary — nested object
  • currency, unit — scalars

Example — 1-month CRISK movers

ARGUMENTS
{
  "period": "1m",
  "limit": 3
}
RESPONSE (ABBREVIATED)
{
  "date": "2026-04-23",
  "period": "1m",
  "top_increases": [
    {
      "ticker": "7182:JP",
      "name": "Japan Post Bank Co Ltd",
      "crisk_current": 84.5,
      "crisk_previous": 80.1,
      "change_absolute": 4.4,
      "attribution": {
        "debt": 0,
        "equity": 8.1,
        "risk": -3.7
      }
    },
    {
      "ticker": "EQH:US",
      "name": "Equitable Holdings Inc",
      "crisk_current": 14,
      "crisk_previous": 10.5,
      "change_absolute": 3.5,
      "attribution": {
        "debt": 0,
        "equity": -0.5,
        "risk": 4
      }
    },
    {
      "ticker": "8750:JP",
      "name": "Daiichi Life Group Inc",
      "crisk_current": 9.6,
      "crisk_previous": 8.1,
      "change_absolute": 1.6,
      "attribution": {
        "debt": 0,
        "equity": 4.5,
        "risk": -2.9
      }
    }
  ],
  "top_decreases": [
    {
      "ticker": "C:US",
      "name": "Citigroup Inc",
      "crisk_current": -59.2,
      "crisk_previous": 2.9,
      "change_absolute": -62.1,
      "attribution": {
        "debt": 0,
        "equity": -28.6,
        "risk": -33.5
      }
    },
    {
      "ticker": "601288:CH",
      "name": "Agricultural Bank of China Ltd",
      "crisk_current": 188.7,
      "crisk_previous": 245.3,
      "change_absolute": -56.6,
      "attribution": {
        "debt": 0,
        "equity": -30.9,
        "risk": -25.7
      }
    },
    {
      "ticker": "939:HK",
      "name": "China Construction Bank Corp",
      "crisk_current": 216.6,
      "crisk_previous": 272.7,
      "change_absolute": -56.1,
      "attribution": {
        "debt": 0,
        "equity": -25.7,
        "risk": -30.4
      }
    }
  ],
  "summary": {
    "firms_increased": 96,
    "firms_decreased": 210,
    "total_change": -376.4
  },
  "currency": "USD",
  "unit": "USD B"
}
Monetary values are reported in the currency of the underlying analysis (see the response's `currency` and `unit` fields). CRISK has a single global analysis (`CLIM.WORLDFIN-MR.CMES`), reported in USD billions.

06

Common Volatility (COVOL)

A common volatility factor extracted from the cross-section of daily returns — synchronized stress across global assets. Use COVOL to identify dates when worldwide volatility moved together rather than asset-by-asset. Underlying methodology: Engle and Campos-Martins (Journal of Financial Economics, 2023). More on this methodology →

list_covol_analyses

READ

List available COVOL (common volatility) analyses with coverage. COVOL extracts a synchronized-stress factor from the cross-section of daily returns within each dataset. Each analysis covers a different universe (e.g., country ETFs, asset classes, commodities). Part of the COVOL hierarchy: list_covol_analyses → get_covol_summary → get_covol.

Parameters

NameTypeRequiredDescription
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • analyses — array of records: { memo, name, data_points, date_range }
  • analyses[].date_range — nested object { start, end }
  • total_count, note — scalars

Example — Available COVOL analyses

ARGUMENTS
{}
RESPONSE (ABBREVIATED)
{
  "analyses": [
    {
      "memo": "COVOL.AC-CVD.COVOL",
      "name": "Asset Class COVOL Dataset",
      "data_points": 290,
      "date_range": {
        "start": "2002-02-28",
        "end": "2026-04-24"
      }
    },
    {
      "memo": "COVOL.COUNTRY-CVD.COVOL",
      "name": "Country-Level ETF COVOL Dataset",
      "data_points": 255,
      "date_range": {
        "start": "2005-01-31",
        "end": "2026-04-24"
      }
    },
    {
      "memo": "COVOL.OILGAS-CVD.COVOL",
      "name": "Oil and Gas COVOL Dataset",
      "data_points": 255,
      "date_range": {
        "start": "2005-01-31",
        "end": "2026-04-24"
      }
    },
    {
      "memo": "COVOL.COMM-CVD.COVOL",
      "name": "Commodities COVOL Dataset",
      "data_points": 255,
      "date_range": {
        "start": "2005-01-31",
        "end": "2026-04-24"
      }
    }
  ],
  "total_count": 4,
  "note": "COVOL is a synchronized-stress factor extracted from the cross-section of daily returns within each dataset (Engle and Campos-Martins, 2023)."
}
Use this tool to discover the available COVOL analyses and their `memo` strings, then drill into a specific analysis with `get_covol`. Each analysis covers a different universe (asset classes, country ETFs, commodities, oil & gas, etc.).

get_covol_summary

READ

COVOL stress snapshot: composite PC1 plus per-analysis levels across every available COVOL analysis.

Parameters

NameTypeRequiredDescription
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • date — scalar
  • composite — nested object: { systematic, systematic_rank, acav, acav_rank, pc1_variance_explained, pc1_loadings: { country, asset_class, oil_gas, commodities } }
  • analyses[] — { memo, name, covol, covol_rank, covol_change, stress_level }

Example — Global COVOL stress dashboard (latest)

ARGUMENTS
{}
RESPONSE (ABBREVIATED)
{
  "date": "2026-04-24",
  "composite": {
    "systematic": 41.125,
    "systematic_rank": 0.7298,
    "acav": 11.959,
    "pc1_variance_explained": 0.6431
  },
  "analyses": [
    {
      "memo": "COVOL.AC-CVD.COVOL",
      "name": "Asset Class",
      "covol": 0.7955,
      "covol_rank": 0.8131,
      "stress_level": "high"
    },
    {
      "memo": "COVOL.OILGAS-CVD.COVOL",
      "name": "Oil and Gas",
      "covol": 0.4929,
      "covol_rank": 0.4349,
      "stress_level": "moderate"
    },
    {
      "memo": "COVOL.COMM-CVD.COVOL",
      "name": "Commodities",
      "covol": 0.5124,
      "covol_rank": 0.3083,
      "stress_level": "low"
    },
    {
      "memo": "COVOL.COUNTRY-CVD.COVOL",
      "name": "Country-Level ETF",
      "covol": 0.2996,
      "covol_rank": 0.0931,
      "stress_level": "low"
    }
  ]
}
composite.systematic is the PC1 score; stress_level values are low / moderate / high thresholds based on percentile rank.

get_covol_composite

READ

Get Composite COVOL Index time series. Returns the systematic stress component (PC1) with daily factor loadings showing how each analysis contributes to market-wide stress.

Parameters

NameTypeRequiredDescription
start_datestringoptionalStart date (YYYY-MM-DD)
end_datestringoptionalEnd date (YYYY-MM-DD)
limitnumberoptionalMax data points (default 252, max 10000)
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • result_date, pc1_variance_explained — scalars
  • data — parallel arrays: date[], systematic[], country_loading[], asset_class_loading[], oil_gas_loading[], commodities_loading[]

Example — Composite COVOL time series (latest 3 days)

ARGUMENTS
{
  "limit": 3
}
RESPONSE (ABBREVIATED)
{
  "result_date": "2026-04-24",
  "pc1_variance_explained": 0.6431,
  "data": {
    "date": [
      "2026-04-22",
      "2026-04-23",
      "2026-04-24"
    ],
    "systematic": [
      40.968,
      40.941,
      41.125
    ],
    "country_loading": [
      0.407,
      0.4073,
      0.4274
    ],
    "asset_class_loading": [
      0.3476,
      0.327,
      0.3194
    ],
    "oil_gas_loading": [
      0.7833,
      0.7818,
      0.7451
    ],
    "commodities_loading": [
      0.3163,
      0.3405,
      0.4001
    ]
  }
}

get_covol_cav

READ

Get COVOL-Adjusted Volatility (CAV) time series for each analysis and aggregate (ACAV). CAV is the annualized risk of the common factor within each analysis. ACAV combines all four into a single portfolio-level risk metric.

Parameters

NameTypeRequiredDescription
start_datestringoptionalStart date (YYYY-MM-DD)
end_datestringoptionalEnd date (YYYY-MM-DD)
limitnumberoptionalMax data points (default 252, max 10000)
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • result_date — scalar
  • data — parallel arrays: date[], country_cav[], asset_class_cav[], oil_gas_cav[], commodities_cav[], acav[]

Example — COVOL-Adjusted Volatility per analysis + aggregate (ACAV)

ARGUMENTS
{
  "limit": 3
}
RESPONSE (ABBREVIATED)
{
  "result_date": "2026-04-24",
  "data": {
    "date": [
      "2026-04-22",
      "2026-04-23",
      "2026-04-24"
    ],
    "country_cav": [
      20.234,
      18.349,
      18.226
    ],
    "asset_class_cav": [
      9.78,
      12.778,
      9.932
    ],
    "oil_gas_cav": [
      29.766,
      29.138,
      30.462
    ],
    "commodities_cav": [
      19.033,
      19.115,
      18.656
    ],
    "acav": [
      12.188,
      13.212,
      11.959
    ]
  }
}

get_covol

READ

Get COVOL Index time series for a specific analysis. Use list_covol_analyses to discover the available analyses and their memo strings.

Parameters

NameTypeRequiredDescription
analysis_memostringrequiredCOVOL analysis memo. Use list_covol_analyses to discover valid values.
start_datestringoptionalStart date (YYYY-MM-DD)
end_datestringoptionalEnd date (YYYY-MM-DD)
limitnumberoptionalMax data points (default 252, max 10000)
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • analysis, name, covol_current, covol_rank — scalars
  • data — parallel arrays: date[], covol_index[]

Example — COVOL index for the Asset Class analysis

ARGUMENTS
{
  "analysis_memo": "COVOL.AC-CVD.COVOL",
  "limit": 3
}
RESPONSE (ABBREVIATED)
{
  "analysis": "COVOL.AC-CVD.COVOL",
  "name": "Asset Class",
  "covol_current": 0.7955,
  "covol_rank": 0.8131,
  "data": {
    "date": [
      "2026-04-22",
      "2026-04-23",
      "2026-04-24"
    ],
    "covol_index": [
      0.7803,
      0.7953,
      0.7955
    ]
  }
}
Use `list_covol_analyses` to discover the available COVOL analyses and their `memo` strings.

get_covol_loadings

READ

Get asset loadings (factor sensitivities) for a COVOL analysis. Shows how much each asset contributes to common volatility, both equal-weighted and variance-weighted.

Parameters

NameTypeRequiredDescription
analysis_memostringrequiredCOVOL analysis memo
datestringoptionalMonth-end date for loadings (YYYY-MM-DD). Defaults to latest.
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • analysis, date — scalars
  • equal_weighted[] — { ticker, name, loading }
  • variance_weighted[] — { ticker, name, loading }

Example — Asset loadings on the Asset Class COVOL factor

ARGUMENTS
{
  "analysis_memo": "COVOL.AC-CVD.COVOL"
}
RESPONSE (ABBREVIATED)
{
  "analysis": "COVOL.AC-CVD.COVOL",
  "date": "2026-04-24",
  "equal_weighted": [
    {
      "ticker": "IWF:US",
      "name": "iShares Russell 1000 Growth ETF",
      "loading": 0.2745
    },
    {
      "ticker": "XLK:US",
      "name": "State Street Technology Select Sector SPDR ETF",
      "loading": 0.2575
    }
  ],
  "variance_weighted": [
    {
      "ticker": "CRUDEOIL:COM",
      "name": "Crude Oil",
      "loading": 1.3473
    },
    {
      "ticker": "XLE:US",
      "name": "State Street Energy Select Sector SPDR ETF",
      "loading": 0.8389
    }
  ]
}

get_covol_events

READ

Get top COVOL events (highest stress dates) for an analysis with z-scores and event descriptions. Events include major market crashes, geopolitical events, and policy shocks.

Parameters

NameTypeRequiredDescription
analysis_memostringrequiredCOVOL analysis memo
datestringoptionalMonth-end date (YYYY-MM-DD). Defaults to latest.
limitnumberoptionalMax events to return (default 10, max 50)
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • analysis, date — scalars
  • events[] — { date, xhat, description }
  • total_events — scalar

Example — Top stress events for the Commodities factor

ARGUMENTS
{
  "analysis_memo": "COVOL.COMM-CVD.COVOL",
  "limit": 3
}
RESPONSE (ABBREVIATED)
{
  "analysis": "COVOL.COMM-CVD.COVOL",
  "date": "2026-04-24",
  "events": [
    {
      "date": "2020-03-09",
      "xhat": 43.74,
      "description": "COVID — All of Italy is locked down, Saudi Arabia / Russia oil price war"
    },
    {
      "date": "2001-09-17",
      "xhat": 24.6,
      "description": "Market reopens after Sept 11th"
    },
    {
      "date": "2008-03-17",
      "xhat": 23.95,
      "description": "Bear Stearns collapses, sold to JPMorgan Chase for $2/share; Fed facilitates emergency rescue to prevent systemic collapse"
    }
  ],
  "total_events": 3
}

07

Liquidity (ILLIQ)

Daily illiquidity measures derived from price impact per dollar of volume, aggregated to country and sector composites. Coverage: 31 countries, 26,289 assets. Underlying methodology: Amihud (Journal of Financial Markets, 2002). More on this methodology →

get_illiq_composite

READ

Get the ILLIQ Composite market-wide liquidity index. This time series shows aggregate market liquidity conditions based on market-cap weighted average of individual ILLIQ measures. Higher values indicate less liquid markets.

Parameters

NameTypeRequiredDescription
start_datestringoptionalFilter from date (YYYY-MM-DD format)
end_datestringoptionalFilter to date (YYYY-MM-DD format)
limitnumberoptionalMaximum data points to return (default: 252, ~1 year of trading days)
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • result_date, description, base_date, unit — scalars
  • data — parallel arrays: date[], illiq_composite[]

Example — Market-wide ILLIQ Composite (latest 3 days)

ARGUMENTS
{
  "limit": 3
}
RESPONSE (ABBREVIATED)
{
  "result_date": "2026-04-24",
  "base_date": "1998-04-01",
  "unit": "index (relative to base_date; higher = less liquid)",
  "data": {
    "date": [
      "2026-04-22",
      "2026-04-23",
      "2026-04-24"
    ],
    "illiq_composite": [
      11.71129,
      11.8388,
      11.70383
    ]
  }
}

list_liquidity_change_countries

READ

List countries that have aggregated sector-change data — the input universe for get_liquidity_changes. Returns each country with its asset count. Note: this is not the universe of every country with ILLIQ coverage; per-asset tools like get_liquidity and get_liquidity_movers work on a broader universe.

Parameters

NameTypeRequiredDescription
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • description — scalar
  • countries[] — { code, name, asset_count }
  • total_countries — scalar

Example — Countries with aggregated sector-change data

ARGUMENTS
{}
RESPONSE (ABBREVIATED)
{
  "countries": [
    {
      "code": "CHN",
      "name": "China",
      "asset_count": 5949
    },
    {
      "code": "USA",
      "name": "United States",
      "asset_count": 3404
    },
    {
      "code": "JPN",
      "name": "Japan",
      "asset_count": 3403
    },
    {
      "code": "IND",
      "name": "India",
      "asset_count": 3092
    }
  ],
  "total_countries": 31
}
This is the input universe for `get_liquidity_changes` — countries that have aggregated per-sector liquidity-change data. It is NOT the universe of every country with ILLIQ coverage; per-asset tools like `get_liquidity` and `get_liquidity_movers` work on a broader universe.

get_liquidity_changes

READ

Get sector-level liquidity statistics for a country. Shows which GICS sectors are experiencing liquidity stress (deteriorating) or improvement.

Parameters

NameTypeRequiredDescription
countrystringoptionalISO3 country code (e.g., "USA", "JPN", "GBR"). Default: USA. Use "ALL" for global aggregate.
sort_bystringoptionalSort metric: "change" (avg illiquidity change), "level" (avg illiquidity level), or "pct_deteriorating" (% assets with worsening liquidity). Default: change
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • country, date, sorted_by — scalars
  • sectors[] — { sector, asset_count, avg_illiq_level, avg_illiq_change, pct_deteriorating, pct_improving, breakdown }
  • breakdown — nested object { pct_down_gte_10, pct_down_lt_10, pct_up_lt_10, pct_up_gte_10 } per sector
  • total_sectors — scalar

Example — US sector liquidity changes

ARGUMENTS
{
  "country": "USA"
}
RESPONSE (ABBREVIATED)
{
  "country": "USA",
  "date": "2026-04-25",
  "sorted_by": "change",
  "sectors": [
    {
      "sector": "Telecommunication Services",
      "asset_count": 131,
      "avg_illiq_level": 27212,
      "avg_illiq_change": 150.86,
      "pct_deteriorating": 46
    },
    {
      "sector": "Utilities",
      "asset_count": 78,
      "avg_illiq_level": 4522.63,
      "avg_illiq_change": 130.65,
      "pct_deteriorating": 40
    }
  ],
  "total_sectors": 11
}

get_liquidity_movers

READ

Get assets with highest illiquidity ("hot") or fastest deteriorating liquidity ("heating"). Use to identify liquidity-stressed assets.

Parameters

NameTypeRequiredDescription
typestring (enum)required"hot" = most illiquid assets (highest current ILLIQ level), "heating" = fastest deteriorating (largest increase in ILLIQ)
Allowed values:
  • hot,
  • heating
countrystringoptionalISO3 country code to filter (e.g., "USA", "JPN")
sectorstringoptionalGICS sector to filter (e.g., "Financials", "Energy", "Health Care", "Information Technology", "Industrials")
limitnumberoptionalMaximum results to return (default: 20, max: 50)
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • type, description, date — scalars
  • assets[] — { ticker, name, illiq_level, illiq_change, model, analysis_memo, country, sector }
  • total_returned, country_filter — scalars

Example — Most illiquid US assets

ARGUMENTS
{
  "type": "hot",
  "country": "USA",
  "limit": 3
}
RESPONSE (ABBREVIATED)
{
  "type": "hot",
  "date": "2026-04-24",
  "assets": [
    {
      "ticker": "DMRA:US",
      "name": "Damora Therapeutics Inc",
      "illiq_level": 4967.6,
      "sector": "Health Care"
    },
    {
      "ticker": "BFS:US",
      "name": "Saul Centers Inc",
      "illiq_level": 4966.02,
      "sector": "Real Estate"
    },
    {
      "ticker": "NGS:US",
      "name": "Natural Gas Services Group Inc",
      "illiq_level": 4950.8,
      "sector": "Energy"
    }
  ],
  "country_filter": "USA"
}
"hot" = most illiquid currently, "heating" = fastest deteriorating.

get_liquidity

READ

Get liquidity time series data for an asset. Returns illiquidity measures from ILLIQ models. SMEM and MFMEM models also include long-term trend data.

Parameters

NameTypeRequiredDescription
tickerstringoptionalAsset ticker with exchange suffix (e.g., "AAPL:US", "SPX:IND", "FTSE:LN"). The exchange suffix is required — use search_assets to find the correct format. Either ticker or analysis_memo is required.
analysis_memostringoptionalDirect analysis memo (e.g., "LIQ.AAPL:US-LD.ILLIQ-AMEM"). Either ticker or analysis_memo is required.
modelstringoptionalModel name (e.g., "ILLIQ-AMEM", "ILLIQ-SMEM", "ILLIQ-MFMEM"). Default: ILLIQ-AMEM
dataset_memostringoptionalPass alongside ticker if you already have a dataset memo from search_assets or search_datasets. For this application, ticker alone uniquely identifies the analysis, so this parameter is for convenience and consistency with V-Lab's universal lookup convention rather than disambiguation. Cannot be used without ticker.
start_datestringoptionalFilter from date (YYYY-MM-DD format)
end_datestringoptionalFilter to date (YYYY-MM-DD format)
limitnumberoptionalMaximum data points to return (default: 252)
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • ticker, asset_name, model, dataset, analysis_memo, result_date — scalars
  • data — parallel arrays: date[], illiquidity[]
  • unit, data_note — scalars

Example — Citigroup ILLIQ time series

ARGUMENTS
{
  "ticker": "C:US",
  "limit": 3
}
RESPONSE (ABBREVIATED)
{
  "ticker": "C:US",
  "asset_name": "Citigroup Inc",
  "model": "ILLIQ-AMEM",
  "analysis_memo": "LIQ.C:US-LD.ILLIQ-AMEM",
  "result_date": "2026-04-24",
  "data": {
    "date": [
      "2026-04-22",
      "2026-04-23",
      "2026-04-24"
    ],
    "illiquidity": [
      9.94109,
      10.13137,
      10.0272
    ]
  },
  "unit": "ILLIQ (higher = less liquid; compare across time or assets, not as an absolute level)"
}

08

Climate benchmarks

Returns, volatility, and correlations for climate risk factor portfolios used as building blocks in climate finance research. More on this methodology →

list_climate_benchmarks

READ

List available climate risk benchmarks. These are V-Lab's proprietary climate factor portfolios including Stranded Assets, Emissions Factor, Oil Beta Factor, and Subsidy Factor.

Parameters

NameTypeRequiredDescription
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • benchmarks[] — { id, name, description, data_years }
  • count, data_range — scalar / nested object

Example — Available climate benchmarks

ARGUMENTS
{}
RESPONSE (ABBREVIATED)
{
  "benchmarks": [
    {
      "id": "Stranded Assets",
      "name": "SA",
      "description": "Long-short portfolio capturing fossil fuel transition risk…",
      "data_years": 27.34
    },
    {
      "id": "Emissions Factor",
      "name": "EMIT",
      "description": "Long-short portfolio capturing the return spread between low- and high-emissions firms…",
      "data_years": 18.31
    },
    {
      "id": "Oil Beta Factor",
      "name": "OIL",
      "description": "Long-short portfolio sorted on equity sensitivity to oil-price shocks…",
      "data_years": 26.31
    },
    {
      "id": "Subsidy Factor",
      "name": "SUB",
      "description": "Long-short portfolio capturing exposure to fossil-fuel subsidy policy risk…",
      "data_years": 17.83
    },
    {
      "id": "SPY:US - XLE:US",
      "name": "SPY-XLE",
      "description": "Difference between broad market (SPY) and the energy sector (XLE)…",
      "data_years": 27.34
    }
  ],
  "count": 5,
  "data_range": {
    "start": "2008-06-25",
    "end": "2026-04-24"
  }
}

get_climate_benchmark_returns

READ

Get returns time series for a climate benchmark. Returns cumulative returns by default (base 100), or daily returns if cumulative=false.

Parameters

NameTypeRequiredDescription
benchmarkstringrequiredBenchmark name or display code (e.g., "Stranded Assets", "SA", "Emissions Factor", "EMIT")
start_datestringoptionalStart date for time series (YYYY-MM-DD format)
end_datestringoptionalEnd date for time series (YYYY-MM-DD format)
cumulativebooleanoptionalReturn cumulative returns (base 100) if true, daily returns if false. Default: true
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • benchmark, name, description, data_type, base_value (cumulative mode), start_date, end_date — scalars
  • data — array of [date, value] tuples
  • NOTE: this tool emits tuple-arrays directly (already maximally compact) and is not pivoted to parallel arrays.

Example — Stranded Assets cumulative returns (3-day window)

ARGUMENTS
{
  "benchmark": "Stranded Assets",
  "start_date": "2026-04-22",
  "end_date": "2026-04-24"
}
RESPONSE (ABBREVIATED)
{
  "benchmark": "Stranded Assets",
  "name": "SA",
  "data_type": "cumulative_returns",
  "base_value": 100,
  "data": [
    [
      "2026-04-22",
      99.25
    ],
    [
      "2026-04-23",
      97.47
    ],
    [
      "2026-04-24",
      98.28
    ]
  ]
}
Default is cumulative returns (base 100). Pass cumulative=false for daily returns. Data tuples are [date, value], not objects — this tool predates the parallel-array convention and stays in tuple form because tuples are even more compact than parallel arrays for two-column data.

get_climate_benchmark_volatility

READ

Get annualized volatility time series for a climate benchmark.

Parameters

NameTypeRequiredDescription
benchmarkstringrequiredBenchmark name or display code (e.g., "Stranded Assets", "SA", "Emissions Factor", "EMIT")
start_datestringoptionalStart date for time series (YYYY-MM-DD format)
end_datestringoptionalEnd date for time series (YYYY-MM-DD format)
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • benchmark, name, data_type, unit, start_date, end_date — scalars
  • data — array of [date, value] tuples (annualized vol in percent)
  • NOTE: tuple-array shape (see get_climate_benchmark_returns note).

Example — Stranded Assets annualized volatility

ARGUMENTS
{
  "benchmark": "Stranded Assets",
  "start_date": "2026-04-22",
  "end_date": "2026-04-24"
}
RESPONSE (ABBREVIATED)
{
  "benchmark": "Stranded Assets",
  "data_type": "annualized_volatility",
  "unit": "percent",
  "data": [
    [
      "2026-04-22",
      17.09
    ],
    [
      "2026-04-23",
      16.87
    ],
    [
      "2026-04-24",
      17.46
    ]
  ]
}

get_climate_benchmark_correlations

READ

Get correlation matrix between all available climate benchmarks.

Parameters

NameTypeRequiredDescription
windowstringoptionalCorrelation window: "1Y" (1 year), "3Y" (3 years), "5Y" (5 years), "EW" (exponentially weighted), or "Max" (full history). Default: 1Y
profilestring (enum)optionalResponse verbosity. "minimal" strips related_tools, interpretive notes, units, and query echoes — keeps data_note (staleness warnings) and core identifiers. Default "standard" preserves all current behavior.
Allowed values:
  • standard,
  • minimal

Returns

  • window, window_description — scalars
  • benchmarks — list of benchmark short names (flat string array)
  • matrix — square 2-D correlation matrix indexed in benchmark order
  • last_updated — scalar

Example — 1-year correlation matrix across all climate benchmarks

ARGUMENTS
{}
RESPONSE (ABBREVIATED)
{
  "window": "1Y",
  "benchmarks": [
    "SA",
    "SPY-XLE",
    "EMIT",
    "OIL",
    "SUB"
  ],
  "matrix": [
    [
      1,
      0.55,
      0.31,
      -0.07,
      0.53
    ],
    [
      0.55,
      1,
      0.33,
      -0.1,
      0.39
    ],
    [
      0.31,
      0.33,
      1,
      0.18,
      0.07
    ],
    [
      -0.07,
      -0.1,
      0.18,
      1,
      -0.07
    ],
    [
      0.53,
      0.39,
      0.07,
      -0.07,
      1
    ]
  ],
  "last_updated": "2026-04-25"
}
Window options: 1Y, 3Y, 5Y, EW (exponentially weighted), Max (full history). The matrix is a 2-D array (not pivoted to parallel arrays) since it's already columnar.

Conventions

Response shape
V-Lab MCP tools return list-shaped data in two formats, depending on what the data is:
  • Time series (the data block on get_volatility, get_firm_srisk, get_covol_composite, etc.) — one array per column. Loads directly with pd.DataFrame(response['data']).
  • Everything else ( rankings, firms, assets, countries, sectors, analyses, search results, list_*) — an array of records, [{ key: value, ... }, ...]. Each row stands on its own.
Other fields in a response — single objects like current_values or concentration, flat string arrays like capabilities.tools, and a few tuple-shaped arrays in the climate-benchmark tools — appear in their own natural shape.
Date format
All dates are YYYY-MM-DD (ISO 8601). Date inputs accept this format only.
Ticker format
Tickers are case-insensitive and use a <symbol>:<exchange> format — JPM:US, HSBA:LN, 7203:JP, DBK:GR, 939:HK. This matches the Bloomberg convention with : substituted for the space ( 7203 JP Equity → 7203:JP). When in doubt about the exact form for an asset, call search_assets — it returns the form get_* tools accept.
Currency
SRISK and CRISK monetary values are reported in the currency of the underlying analysis. Every response carries a top-level currency ISO field (e.g., USD, JPY, EUR) and a unit label (e.g., USD B).
The profile parameter
Every read tool accepts profile: 'standard' (default) or profile: 'minimal'. Minimal strips related-tools hints, interpretive notes, units, and query echoes — useful when the assistant has a tight context budget.
Errors
Errors return as content with isError: true and a JSON payload of { error, message, tip }. Driver-level details (database hosts, schema names) are sanitized.
Data freshness
Most tools refresh daily. When data is stale or otherwise notable, the response carries a data_note field describing the caveat.

Feedback

The server exposes one write tool, submit_feedback, that LLMs and end users can call to report a tool that was helpful or unhelpful, request a feature, request data coverage, or file a bug. Feedback is read by the V-Lab team and informs what we ship next.

submit_feedback

WRITE

Report feedback on V-Lab MCP to help improve the server. TWO SHAPES ARE SUPPORTED: 1. Tool rating — pass tool_name + helpful (+ optional message): { tool_name: "get_volatility", helpful: true, message: "Data was clear and correct" } { tool_name: "get_srisk_ranking", helpful: false, message: "aggregate_by=firm returned a DB error" } 2. General feedback — pass category + message (no tool_name required): { category: "bug_report", message: "get_covol_cav is listed in server_info but has no tool schema" } { category: "feature_request", message: "Add a tool that compares volatility across multiple assets" } { category: "data_request", message: "Need coverage of Brazilian small-cap banks" } { category: "general", message: "Overall very useful for market-state summaries" } WHEN TO USE: - After completing a task, if you have meaningful input on a specific tool (helpful=true/false). - Any time to file a bug, request a feature, request data coverage, or share general feedback — no tool name required.

Parameters

NameTypeRequiredDescription
tool_namestringoptionalName of the V-Lab tool being rated (e.g., "get_volatility"). Omit for general feedback, feature requests, or bug reports not tied to a specific tool.
helpfulbooleanoptionalDid the tool help accomplish the task? Only meaningful when tool_name is provided.
categorystring (enum)optionalCategory of general feedback. Use when tool_name is not applicable.
Allowed values:
  • bug_report
  • feature_request
  • data_request
  • rating
  • general
messagestringoptionalFree-form feedback: error details, unexpected behavior, feature requests, or general comments.
commentstringoptionalLegacy alias for message. Prefer message in new calls.

Citing V-Lab

V-Lab data is produced by academic research at the Volatility and Risk Institute, NYU Stern. If you use this data in published work or public-facing content, please cite V-Lab. Citation information and academic references are available at https://vlab.stern.nyu.edu.

All data and information provided by V-Lab is offered on an "as is" basis for informational and academic research purposes only. New York University and the Volatility and Risk Institute make no representations or warranties of any kind, express or implied, regarding the accuracy, completeness, reliability, suitability, or availability of any data. This includes, without limitation, any implied warranties of merchantability or fitness for a particular purpose. V-Lab data does not constitute investment advice, trading recommendations, or professional financial consultation. Users should not make financial decisions based solely on V-Lab data without consulting qualified professionals. Full legal provisions →

Generated against vlab-mcp v0.7.16 · as of 2026-04-28 · from tools/list + get_server_info. Visit the methodology docs for the underlying research. Report security issues to vlab@stern.nyu.edu.