---
title: "Money supply history API Reference | Narwhal API"
description: "Retrieve the monthly broad money history for one country, in its own currency, oldest first. Parameters, examples, errors, freshness, and coverage."
url: "https://narwhalapi.com/docs/api/economics/money-supply-history"
---

# Money supply history API

Retrieve the monthly broad money history for one country, in its own currency, oldest first.

`economics_get_money_supply_history` is available through REST and the `economics_get_money_supply_history` MCP tool. Both return the same data shape and use the same credit.

## Endpoint and request

REST endpoint

```
GET /v1/economics/{country}/money-supply/observations
```

Example request

```
curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/KWT/money-supply/observations?start=2026-01&limit=2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
```

MCP uses tool `economics_get_money_supply_history` with the corresponding arguments below.

## Parameters

The accepted period format for this operation is `YYYY-MM`.

| Name | Required | Type | Meaning |
| --- | --- | --- | --- |
| `country` | Yes | path · ISO alpha-3 | One supported uppercase country code; see this operation’s coverage list. |
| `start` | No | query · YYYY-MM | Inclusive first observation period. |
| `end` | No | query · YYYY-MM | Inclusive last observation period. |
| `limit` | No | query · integer, 1–1000 | Maximum number of periods returned. Defaults to 100. A page may contain fewer periods; follow next_cursor. |
| `cursor` | No | query · opaque string | The next_cursor from the previous page. |
| `series_id` | No | query · UUID | Optional. The `series_id` of one series, taken from an earlier answer. Omit it to read the country's default series. |

## Response

Example response

```
{
  "source": {
    "publisher": "Country authorities; National Summary Data Pages; European Central Bank; IMF Staff Calculations",
    "distributor": "International Monetary Fund"
  },
  "seasonal_adjustment": "not_seasonally_adjusted",
  "aggregate": "broad_money",
  "definition_label": "Broad Money",
  "country": "KWT",
  "series_id": "94322188-0436-47b7-b127-01f3f73cfab9",
  "unit": "currency",
  "currency": "KWD",
  "observations": [
    {
      "period": "2026-01",
      "value": "42179995400"
    },
    {
      "period": "2026-02",
      "value": "42605920000"
    }
  ],
  "next_cursor": "eyJhZnRlciI6IjIwMjYtMDIi…"
}
```

The history example asks for `limit=2`, so it holds two rows. `next_cursor` is shortened here. A real one is a longer opaque string.

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `source` | object | Yes | Who published the figure. `publisher` is the original publisher that the IMF's series metadata names, and `distributor` is the IMF, which Narwhal reads it from. One source per series, for its whole history. There is no `released_on`. |
| `seasonal_adjustment` | string | Yes | Always `not_seasonally_adjusted`. |
| `aggregate` | string | Yes | Always `broad_money`. |
| `definition_label` | string | Yes | The aggregate's name in the IMF's dataset: `Broad Money`. |
| `country` | string | Yes | The requested uppercase ISO alpha-3 country code. |
| `series_id` | string | Yes | The series the figure comes from. Pass it as `series_id` to read the same series again. |
| `unit` | string | Yes | Always `currency`. |
| `currency` | ISO 4217 string | Yes | The country's national currency, for example `KWD`. |
| `observations` | array | Yes | Oldest-first observations, one per period. A page can hold fewer observations than `limit`. Follow `next_cursor` until it is null. |
| `observations[].period` | string | Yes | The official month, quarter or year represented by the observation. |
| `observations[].value` | decimal string | Yes | Broad money at the end of the month, in whole units of the national currency in `currency`. |
| `observations[].status` | string | No | Present only for a figure the publisher flags: `estimated`, `break_in_series`, `definition_differs` or `break_in_series_and_definition_differs`. Left out otherwise. |
| `observations[].release_status` | string | No | `preliminary` when the publisher marks the figure provisional. Left out otherwise. |
| `next_cursor` | string or null | Yes | Pass this unchanged as cursor to read the next page. It is null on the last page. |

## Errors and credits

- `400 invalid_query`: A query parameter is unknown or repeated, `country` is not three uppercase letters, `series_id` is not a UUID, `start` or `end` is not a month in `YYYY-MM` format, `start` and `end` differ in format or `start` is after `end`, or `limit` is outside 1 to 1000. `version_id`, `version` and `as_of` are not accepted on this route.
- `400 invalid_cursor`: The cursor is malformed, or was issued for other filters.
- `409 snapshot_unavailable`: The cursor is more than 24 hours old and has expired. Start again without `cursor`.
- `401 invalid_api_key`: The Bearer key is missing or rejected.
- `402 insufficient_credits`: Your balance does not cover the call.
- `404 series_not_found`: The country is not in the coverage list on this page, `series_id` is not a series of that country, or the range holds no observation. A country outside the list gets a detail that says the family is not available for it. A 404 is not charged.
- `429 rate_limit_exceeded`: The network or account short-window limit was reached. Retry after `Retry-After`.
- `503 economics_unavailable`: Narwhal cannot safely serve the stored series.

Only a successful data response costs credit. See [all errors, headers, and retry rules](https://narwhalapi.com/docs/errors.md).

## Freshness

This route returns Narwhal's current stored series, oldest first. Without `start` it begins at the oldest stored period, so pass `start` to read recent periods. It does not take `as_of` or `version`, so an earlier vintage cannot be read. Narwhal omits missing observations rather than filling them.

Read [how source checks, validation, stored releases, and failed checks work](https://narwhalapi.com/docs/freshness.md).

## Current public-beta coverage

4 Countries

`DOM, KAZ, KWT, MUS`

Monthly, in whole units of the country's own currency, not seasonally adjusted. Countries define broad money differently, so compare levels within one country only. The International Monetary Fund (IMF) distributes the series, and `source.publisher` names the original publisher. A period is a month in `YYYY-MM` format. Any other country returns `404 not_found` and is not charged.

Daily FX is available through the [FX API](https://narwhalapi.com/api/fx.md).

Return to [all Economics operations](https://narwhalapi.com/docs/api/economics.md).

## Start with a free key

Free $10 credits every month, no card.Free $10 credits a month, no card.

[Get a free API key](https://narwhalapi.com/signup)

Was this page helpful?
