Browse all documentation

Country credit rating API reference

The sovereign credit rating of a country on Moody's scale, and its default spread

Overview

The long-term sovereign credit rating of a country on Moody's scale, from Aswath Damodaran's country risk table (NYU Stern), with the default spread he sets for it. Every request needs a Bearer key, and REST and MCP draw on one credit balance.

A country is its ISO 3166 alpha-3 code, such as USA or IDN. The rating is one of Aaa, Aa1 to Aa3, A1 to A3, Baa1 to Baa3, Ba1 to Ba3, B1 to B3, Caa1 to Caa3, Ca or C. The default spread is a percent as a decimal string with four places, the table's own spread for the country. It equals country_default_spread in the equity risk premium routes only where that route's basis is table: for the United States and the euro-area countries those routes use our own spread, so the two differ there.

The table is updated about once a year. Every answer carries table_update, the month of the table it was read from, so a rating is never read as live. The scale is named "Moody's scale" and not "Moody's" because, where Moody's has no rating of a country, the table uses the Moody's equivalent of the S&P rating.

Base URL: https://api.narwhalapi.com. Each route below is an MCP tool of its own, with the same parameters.

What every account gets

WhatEvery account
One countryOne Economics call
Every countryOne Economics call

See pricing for what a call costs. A request is charged at the price of its API unless a route says otherwise.

  • The table lists one rating per country, for its local-currency sovereign debt. There is no rating history and no outlook.
  • A country the table lists as not rated (NR), such as Russia, has rating null and still has its default spread. The call is charged, because the spread is an answer.
  • A country the table does not list is 404 not_found and is not charged.
  • The ratings are republished from a public table, not read from Moody's. They are for analysis, not financial, investment, legal or tax advice.

Endpoints

Every route is a GET and needs your key in the Authorization: Bearer header. The examples show the shape of an answer, not live data.

Get a country's credit rating

GET /v1/economics/{country}/credit-rating

The long-term sovereign credit rating of one country on Moody's scale, with its default spread in percent, from Aswath Damodaran's country risk table. table_update names the month the table was last updated.

MCP: tool economics_get_credit_rating.

Parameters

ParameterWhereRequiredTypeMeaning
countrypathYesstring

Response fields

FieldTypeSentMeaning
countrystringAlways
scalealways "Moody's scale"Optional
ratingstringAlways
default_spreadstringAlways
table_updatestringAlways
sourcealways "Aswath Damodaran, NYU Stern, country risk table (Moody's scale)"Optional
Request
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/economics/IDN/credit-rating"
Example response
{
  "country": "IDN",
  "scale": "Moody's scale",
  "rating": "Baa2",
  "default_spread": "1.6200",
  "table_update": "January 2026",
  "source": "Aswath Damodaran, NYU Stern, country risk table (Moody's scale)"
}

List credit ratings for all countries

GET /v1/economics/credit-rating

The credit rating and default spread of every country in the table, sorted by country code, with the month the table was updated.

MCP: tool economics_list_credit_ratings.

Parameters

This route takes no parameters.

Response fields

FieldTypeSentMeaning
countrieslist of objectAlways
countries[].countrystringAlways
countries[].scalealways "Moody's scale"Optional
countries[].ratingstringAlways
countries[].default_spreadstringAlways
countries[].table_updatestringAlways
countries[].sourcealways "Aswath Damodaran, NYU Stern, country risk table (Moody's scale)"Optional
Request
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/economics/credit-rating"
Example response
{
  "countries": [
    {
      "country": "DEU",
      "scale": "Moody's scale",
      "rating": "Aaa",
      "default_spread": "0.0000",
      "table_update": "January 2026",
      "source": "Aswath Damodaran, NYU Stern, country risk table (Moody's scale)"
    },
    {
      "country": "IDN",
      "scale": "Moody's scale",
      "rating": "Baa2",
      "default_spread": "1.6200",
      "table_update": "January 2026",
      "source": "Aswath Damodaran, NYU Stern, country risk table (Moody's scale)"
    },
    {
      "country": "RUS",
      "scale": "Moody's scale",
      "rating": null,
      "default_spread": "2.5600",
      "table_update": "January 2026",
      "source": "Aswath Damodaran, NYU Stern, country risk table (Moody's scale)"
    }
  ]
}

Errors

Errors use the shared problem shape with a request_id. See Errors and credits for the shape and the credit headers. Failed requests are not charged.

CodeStatusMeaning
invalid_query400A parameter is missing, unknown, repeated or outside its range.
not_found404The country risk table does not list this country. Not charged.
insufficient_credits402Your credit balance is less than the request costs.
economics_unavailable503The stored table cannot answer right now, or it was stored before ratings were kept. Not charged.

Was this page helpful?