At CountryRisk.io, our mission is simple: Assessing country risks, simplified. Over the years, we've built a comprehensive suite of tools to support professionals working in government debt management offices, investment management or credit risk departments in making sound sovereign risk decisions. Our Insights Platform provides access to:

• A full-featured sovereign rating model
• Quantitative sovereign and ESG risk scores
• An early warning system for currency crises
• Curated research and data from authoritative sources
• Deep integration with our data platform, CountryData.io (Link), enabling robust workflows with versioning, audit trails, and API-based data access

With the upcoming platform update, we’re introducing AI-powered research automation across the workflow—from data ingestion to report generation. But one essential tool has been missing from our arsenal: Debt Sustainability Analysis (DSA).

Why Build a DSA Toolkit Now?

DSA is a structured analytical framework used to assess whether a sovereign can meet its current and future debt obligations without requiring unrealistic fiscal adjustments or falling into distress.

If DSA is so critical, why haven’t we built one before? The answer is simple: It is complex. While the deterministic debt dynamics equation (see Fig. 1) is conceptually straightforward, meaningful implementation demands flexibility, detailed data handling, and the ability to simulate alternative scenarios—including stochastic ones that generate fan charts to assess risk distributions.

Existing tools—such as the IMF/World Bank Excel-based templates (see Fig. 2) for LIC and MAC countries—are powerful but not user-friendly and require significant training. We believe there's a better way.

What We Set Out to Build

Our goal was to develop a DSA tool that is:

·       Capable of both deterministic and stochastic simulations

·       Scenario-driven (e.g., study the impact of a growth slowdown or natural disasters on debt sustainability)

·       Flexible in using either aggregated or bond-level debt input data

·       Fully programmable (Python-based) and API-accessible

·       Seamlessly integrated with the CountryData.io platform

To achieve this, we have partnered with Lennard Welslau (Link), an economist and data scientist who has worked and published extensively on debt sustainability and its analysis, to co-develop the CountryRisk.io DSA Toolkit.

The remainder of this post introduces the overall structure, modeling steps, and showcases preliminary outputs of the DSA using Mexico as an example. In follow up posts, we will dive deeper into DSA and the CountryRisk.io DSA Toolkit. To incorporate any feedback before we publicly launch this exciting new feature, we would love to hear from you.

Step 1: Preparing Input Data with the CountryData.io API

Setting up any DSA model requires information on the composition of sovereign debt, as well as key debt drivers. If no bond-level data s available, the debt composition is approximated using the following user-supplied parameters:

• D_share_st: Share of short-term debt
• D_share_dom, D_share_usd, D_share_eur: Debt composition by domestic and foreign currencies
• avg_mat: Average (residual) maturity

If needed, users can change key economic assumptions, like the size and persistence of fiscal multiplier effects, or the sensitivity of the budget to cyclical fluctuations.

Additional annual time series data needed to initialize the DSA model include:

• Real and nominal GDP growth (g, ng), and levels (gdp, ngdp)
• Potential output and growth (pgdp, pg)
• Inflation (infl)
• Fiscal metrics: Primary balance (pb), fiscal balance (fb), structural balances (spb, sb)
• Stock-flow adjustment (sf)
• Public debt (d)
• Interest rates (ir_st, ir_lt), implicit interest rate (iir)
• Exchange rates (exr_usd, exr_eur)

For stochastic modeling, additional historical depth is required for data on debt drivers like pb, ng, iir, and exchange rates. We leverage the CountryData.io API to fetch most timeseries data from the IMF’s WEO and IFS databases. Alternative growth projections, as well as interest rate and inflation outlooks must be provided by the user.

Step 2: Deterministic DSA Modeling

Once input data are prepared, they are passed to the CountryRiskDSA class as a simple dictionary, after which users can use the .project() method to simulate debt trajectories over the defined projection horizon.

By default (if no fiscal path is specified), the model assumes a constant primary balance equal to the starting value. Alternatively, users can simulate linear adjustment towards a specified primary balance target (pb_target) or custom, non-linear fiscal scenarios (pb_path) for varying durations.

Deterministic Optimization

To judge the sustainability of public debt deterministically, we can compare current primary balances with levels that stabilize the debt burden. To facilitate this, the toolkit offers a deterministic optimizer that finds the primary compliant with one or more debt sustainability criteria, including:

• debt_reduction: Debt ratio must decline over a defined number of years
• debt_below: Debt ratio must fall below a specified threshold
• deficit_below: Deficit must remain above a negative threshold (i.e., not too deep)
• interest_below: Interest payments must remain below a defined ceiling

For example, to bring Mexico’s debt below 60% of GDP by 2035, it would need to reach a primary balance of 2.42% of GDP by 2030.

Scenario Analysis

To conduct stress tests and counterfactuals, users can define scenarios that alter baseline model assumptions. New scenario timeseries can either be passed to the .project() method as a dictionary or, more simply, be initiated via the .call_scenario() method with predefined templates:

• "rg": Reduces real GDP growth and increases market rates
• "r": Interest rate shock (short- and long-term)
• Custom attribute-level shocks (e.g., "pb", "infl")

We can simulate and optimize fiscal paths under these scenarios. For example, a one percentage point shock to market rates and growth in 2030 would increase the primary balance needed to to bring debt below 60% of GDP by 2035 from 2.42% to 3.11%.

Step 3: Stochastic DSA Modeling

To quantify the uncertainty that baseline projections are subject to, the CountryRiskSDSA class extends the deterministic model and introduces stochastic simulations using a VAR framework.

• Historical first differences are used to estimate the VAR model
• Users define the stochastic projection start year and duration
• Estimated coefficients and a large number of shock draws (e.g., 10,000) combine to generate a probability distribution for outcomes

We visualize the results with fanchart() and can drill into specific years—e.g., the debt distribution in 2035—and compute the probability of meeting certain debt thresholds.

Stochastic Optimization

Stochastic optimization identifies a primary balance target that meets defined probability thresholds  for selected criteria, such as:

• stable: Debt ratio is non-increasing in the final 3 years of the projection
• decline: Debt ratio declines between adjustment and projection end
• below: Debt ratio falls below a specified threshold with given probability

The optimizer returns the minimum primary balance that satisfies all selected criteria at the defined probability level. Ensuring debt falls below 60% of GDP by 2035 with a 75% probability, for example, implies a 2030 primary balance target of 3.06%.

Next Steps & Feedback

This first release of the CountryRisk.io DSA Toolkit lays the foundation for integrated, programmable sovereign debt analysis. We are now preparing to:

• Make the toolkit available via the CountryData.io API
• Integrate it into the CountryRisk.io Insights platform as a web-based application

We are eager to incorporate feedback before the general release. If you are working on DSA in a sovereign risk, policy, or investment context, we would love to hear from you.

Contact us at [email protected]