[Feature] Add Central Bank Holdings (Federal Reserve) (#6469)

* add central bank holdings

* codespell

* actually commit the standard model

---------

Co-authored-by: Igor Radovanovic <74266147+IgorWounds@users.noreply.github.com>

16 files changed, 1791 insertions, 44 deletions

diff --git a/openbb_platform/core/openbb_core/provider/standard_models/central_bank_holdings.py b/openbb_platform/core/openbb_core/provider/standard_models/central_bank_holdings.py
new file mode 100644
index 00000000000..b84d1ecaf3a
--- /dev/null
+++ b/openbb_platform/core/openbb_core/provider/standard_models/central_bank_holdings.py
@@ -0,0 +1,30 @@
+"""Central Bank Holdings Standard Model."""
+
+from datetime import (
+    date as dateType,
+)
+from typing import Optional
+
+from pydantic import Field
+
+from openbb_core.provider.abstract.data import Data
+from openbb_core.provider.abstract.query_params import QueryParams
+from openbb_core.provider.utils.descriptions import (
+    DATA_DESCRIPTIONS,
+    QUERY_DESCRIPTIONS,
+)
+
+
+class CentralBankHoldingsQueryParams(QueryParams):
+    """Central Bank Holdings Query."""
+
+    date: Optional[dateType] = Field(
+        default=None,
+        description=QUERY_DESCRIPTIONS.get("date", ""),
+    )
+
+
+class CentralBankHoldingsData(Data):
+    """Central Bank Holdings Data."""
+
+    date: dateType = Field(description=DATA_DESCRIPTIONS.get("date", ""))
diff --git a/openbb_platform/extensions/economy/integration/test_economy_api.py b/openbb_platform/extensions/economy/integration/test_economy_api.py
index 3f7998c14de..b06ac4937e6 100644
--- a/openbb_platform/extensions/economy/integration/test_economy_api.py
+++ b/openbb_platform/extensions/economy/integration/test_economy_api.py
@@ -657,3 +657,42 @@ def test_economy_country_profile(params, headers):
     result = requests.get(url, headers=headers, timeout=30)
     assert isinstance(result, requests.Response)
     assert result.status_code == 200
+
+
+@parametrize(
+    "params",
+    [
+        (
+            {
+                "date": None,
+                "provider": "federal_reserve",
+                "holding_type": "all_treasury",
+                "summary": False,
+                "monthly": False,
+                "cusip": None,
+                "wam": False,
+            }
+        ),
+        (
+            {
+                "date": None,
+                "provider": "federal_reserve",
+                "holding_type": "all_agency",
+                "summary": False,
+                "monthly": False,
+                "cusip": None,
+                "wam": True,
+            }
+        ),
+    ],
+)
+@pytest.mark.integration
+def test_economy_central_bank_holdings(params, headers):
+    """Test the economy central bank holdings."""
+    params = {p: v for p, v in params.items() if v}
+
+    query_str = get_querystring(params, [])
+    url = f"http://0.0.0.0:8000/api/v1/economy/central_bank_holdings?{query_str}"
+    result = requests.get(url, headers=headers, timeout=5)
+    assert isinstance(result, requests.Response)
+    assert result.status_code == 200
diff --git a/openbb_platform/extensions/economy/integration/test_economy_python.py b/openbb_platform/extensions/economy/integration/test_economy_python.py
index 75a01123c7b..4825b504949 100644
--- a/openbb_platform/extensions/economy/integration/test_economy_python.py
+++ b/openbb_platform/extensions/economy/integration/test_economy_python.py
@@ -606,3 +606,41 @@ def test_economy_indicators(params, obb):
     assert result
     assert isinstance(result, OBBject)
     assert len(result.results) > 0
+
+
+@parametrize(
+    "params",
+    [
+        (
+            {
+                "date": None,
+                "provider": "federal_reserve",
+                "holding_type": "all_treasury",
+                "summary": False,
+                "monthly": False,
+                "cusip": None,
+                "wam": False,
+            }
+        ),
+        (
+            {
+                "date": None,
+                "provider": "federal_reserve",
+                "holding_type": "all_agency",
+                "summary": False,
+                "monthly": False,
+                "cusip": None,
+                "wam": True,
+            }
+        ),
+    ],
+)
+@pytest.mark.integration
+def test_economy_central_bank_holdings(params, obb):
+    """Test economy central bank holdings."""
+    params = {p: v for p, v in params.items() if v}
+
+    result = obb.economy.central_bank_holdings(**params)
+    assert result
+    assert isinstance(result, OBBject)
+    assert len(result.results) > 0
diff --git a/openbb_platform/extensions/economy/openbb_economy/economy_router.py b/openbb_platform/extensions/economy/openbb_economy/economy_router.py
index 6adeaeea1ea..b318d1183e6 100644
--- a/openbb_platform/extensions/economy/openbb_economy/economy_router.py
+++ b/openbb_platform/extensions/economy/openbb_economy/economy_router.py
@@ -378,3 +378,35 @@ async def indicators(
 ) -> OBBject:
     """Get economic indicators by country and indicator."""
     return await OBBject.from_query(Query(**locals()))
+
+
+@router.command(
+    model="CentralBankHoldings",
+    examples=[
+        APIEx(
+            description="The default is the latest Treasury securities held by the Federal Reserve.",
+            parameters={"provider": "federal_reserve"},
+        ),
+        APIEx(
+            description="Get historical summaries of the Fed's holdings.",
+            parameters={"provider": "federal_reserve", "summary": True},
+        ),
+        APIEx(
+            description="Get the balance sheet holdings as-of a historical date.",
+            parameters={"provider": "federal_reserve", "date": "2019-05-21"},
+        ),
+        APIEx(
+            description="Use the `holding_type` parameter to select Agency securities,"
+            + " or specific categories or Treasury securities.",
+            parameters={"provider": "federal_reserve", "holding_type": "agency_debts"},
+        ),
+    ],
+)
+async def central_bank_holdings(
+    cc: CommandContext,
+    provider_choices: ProviderChoices,
+    standard_params: StandardParams,
+    extra_params: ExtraParams,
+) -> OBBject:
+    """Get the balance sheet holdings of a central bank."""
+    return await OBBject.from_query(Query(**locals()))
diff --git a/openbb_platform/openbb/assets/reference.json b/openbb_platform/openbb/assets/reference.json
index 7fcaea8ee60..aae0334f071 100644
--- a/openbb_platform/openbb/assets/reference.json
+++ b/openbb_platform/openbb/assets/reference.json
@@ -5202,6 +5202,313 @@
             },
             "model": "EconomicIndicators"
         },
+        "/economy/central_bank_holdings": {
+            "deprecated": {
+                "flag": null,
+                "message": null
+            },
+            "description": "Get the balance sheet holdings of a central bank.",
+            "examples": "\nExamples\n--------\n\n```python\nfrom openbb import obb\n# The default is the latest Treasury securities held by the Federal Reserve.\nobb.economy.central_bank_holdings(provider='federal_reserve')\n# Get historical summaries of the Fed's holdings.\nobb.economy.central_bank_holdings(provider='federal_reserve', summary=True)\n# Get the balance sheet holdings as-of a historical date.\nobb.economy.central_bank_holdings(provider='federal_reserve', date='2019-05-21')\n# Use the `holding_type` parameter to select Agency securities, or specific categories or Treasury securities.\nobb.economy.central_bank_holdings(provider='federal_reserve', holding_type=agency_debts)\n```\n\n",
+            "parameters": {
+                "standard": [
+                    {
+                        "name": "date",
+                        "type": "Union[date, str]",
+                        "description": "A specific date to get data for.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "provider",
+                        "type": "Literal['federal_reserve']",
+                        "description": "The provider to use for the query, by default None. If None, the provider specified in defaults is selected or 'federal_reserve' if there is no default.",
+                        "default": "federal_reserve",
+                        "optional": true
+                    }
+                ],
+                "federal_reserve": [
+                    {
+                        "name": "holding_type",
+                        "type": "Literal['all_agency', 'agency_debts', 'mbs', 'cmbs', 'all_treasury', 'bills', 'notesbonds', 'frn', 'tips']",
+                        "description": "Type of holdings to return.",
+                        "default": "all_treasury",
+                        "optional": true,
+                        "choices": [
+                            "all_agency",
+                            "agency_debts",
+                            "mbs",
+                            "cmbs",
+                            "all_treasury",
+                            "bills",
+                            "notesbonds",
+                            "frn",
+                            "tips"
+                        ]
+                    },
+                    {
+                        "name": "summary",
+                        "type": "bool",
+                        "description": "If True, returns historical weekly summary by holding type. This parameter takes priority over other parameters.",
+                        "default": false,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "cusip",
+                        "type": "Union[str, List[str]]",
+                        "description": " Multiple items allowed for provider(s): federal_reserve.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "wam",
+                        "type": "bool",
+                        "description": "If True, returns weighted average maturity aggregated by agency or treasury securities. This parameter takes priority over `holding_type`, `cusip`, and `monthly`.",
+                        "default": false,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "monthly",
+                        "type": "bool",
+                        "description": "If True, returns historical data for all Treasury securities at a monthly interval. This parameter takes priority over other parameters, except `wam`. Only valid when `holding_type` is set to: 'all_treasury', 'bills', 'notesbonds', 'frn', 'tips'.",
+                        "default": false,
+                        "optional": true,
+                        "choices": null
+                    }
+                ]
+            },
+            "returns": {
+                "OBBject": [
+                    {
+                        "name": "results",
+                        "type": "List[CentralBankHoldings]",
+                        "description": "Serializable results."
+                    },
+                    {
+                        "name": "provider",
+                        "type": "Optional[Literal['federal_reserve']]",
+                        "description": "Provider name."
+                    },
+                    {
+                        "name": "warnings",
+                        "type": "Optional[List[Warning_]]",
+                        "description": "List of warnings."
+                    },
+                    {
+                        "name": "chart",
+                        "type": "Optional[Chart]",
+                        "description": "Chart object."
+                    },
+                    {
+                        "name": "extra",
+                        "type": "Dict[str, Any]",
+                        "description": "Extra info."
+                    }
+                ]
+            },
+            "data": {
+                "standard": [
+                    {
+                        "name": "date",
+                        "type": "date",
+                        "description": "The date of the data.",
+                        "default": "",
+                        "optional": false,
+                        "choices": null
+                    }
+                ],
+                "federal_reserve": [
+                    {
+                        "name": "security_type",
+                        "type": "str",
+                        "description": "Type of security - i.e. TIPs, FRNs, etc.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "description",
+                        "type": "str",
+                        "description": "Description of the security. Only returned for Agency securities.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "is_aggreated",
+                        "type": "Literal['Y']",
+                        "description": "Whether the security is aggregated. Only returned for Agency securities.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "cusip",
+                        "type": "str",
+                        "description": "",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "issuer",
+                        "type": "str",
+                        "description": "Issuer of the security.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "maturity_date",
+                        "type": "date",
+                        "description": "Maturity date of the security.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "term",
+                        "type": "str",
+                        "description": "Term of the security. Only returned for Agency securities.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "face_value",
+                        "type": "float",
+                        "description": "Current face value of the security (Thousands). Current face value of the securities, which is the remaining principal balance of the securities.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "par_value",
+                        "type": "float",
+                        "description": "Par value of the security (Thousands). Changes in par may reflect primary and secondary market transactions and/or custodial account activity.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "coupon",
+                        "type": "float",
+                        "description": "Coupon rate of the security.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "spread",
+                        "type": "float",
+                        "description": "Spread to the current reference rate, as determined at each security's initial auction.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "percent_outstanding",
+                        "type": "float",
+                        "description": "Total percent of the outstanding CUSIP issuance.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "bills",
+                        "type": "float",
+                        "description": "Treasury bills amount (Thousands). Only returned when 'summary' is True.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "frn",
+                        "type": "float",
+                        "description": "Floating rate Treasury notes amount (Thousands). Only returned when 'summary' is True.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "notes_and_bonds",
+                        "type": "float",
+                        "description": "Treasuy Notes and bonds amount (Thousands). Only returned when 'summary' is True.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "tips",
+                        "type": "float",
+                        "description": "Treasury inflation-protected securities amount (Thousands). Only returned when 'summary' is True.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "mbs",
+                        "type": "float",
+                        "description": "Mortgage-backed securities amount (Thousands). Only returned when 'summary' is True.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "cmbs",
+                        "type": "float",
+                        "description": "Commercial mortgage-backed securities amount (Thousands). Only returned when 'summary' is True.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "agencies",
+                        "type": "float",
+                        "description": "Agency securities amount (Thousands). Only returned when 'summary' is True.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "total",
+                        "type": "float",
+                        "description": "Total SOMA holdings amount (Thousands). Only returned when 'summary' is True.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "tips_inflation_compensation",
+                        "type": "float",
+                        "description": "Treasury inflation-protected securities inflation compensation amount (Thousands). Only returned when 'summary' is True.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "change_prior_week",
+                        "type": "float",
+                        "description": "Change in SOMA holdings from the prior week (Thousands).",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "change_prior_year",
+                        "type": "float",
+                        "description": "Change in SOMA holdings from the prior year (Thousands).",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    }
+                ]
+            },
+            "model": "CentralBankHoldings"
+        },
         "/equity/calendar/ipo": {
             "deprecated": {
                 "flag": null,
diff --git a/openbb_platform/openbb/package/economy.py b/openbb_platform/openbb/package/economy.py
index b3e5f7cb231..19191e3f4da 100644
--- a/openbb_platform/openbb/package/economy.py
+++ b/openbb_platform/openbb/package/economy.py
@@ -16,6 +16,7 @@ class ROUTER_economy(Container):
     available_indicators
     balance_of_payments
     calendar
+    central_bank_holdings
     composite_leading_indicator
     country_profile
     cpi
@@ -368,6 +369,139 @@ class ROUTER_economy(Container):
 
     @exception_handler
     @validate
+    def central_bank_holdings(
+        self,
+        date: Annotated[
+            Union[datetime.date, None, str],
+            OpenBBField(description="A specific date to get data for."),
+        ] = None,
+        provider: Annotated[
+            Optional[Literal["federal_reserve"]],
+            OpenBBField(
+                description="The provider to use for the query, by default None.\n    If None, the provider specified in defaults is selected or 'federal_reserve' if there is\n    no default."
+            ),
+        ] = None,
+        **kwargs
+    ) -> OBBject:
+        """Get the balance sheet holdings of a central bank.
+
+        Parameters
+        ----------
+        date : Union[datetime.date, None, str]
+            A specific date to get data for.
+        provider : Optional[Literal['federal_reserve']]
+            The provider to use for the query, by default None.
+            If None, the provider specified in defaults is selected or 'federal_reserve' if there is
+            no default.
+        holding_type : Literal['all_agency', 'agency_debts', 'mbs', 'cmbs', 'all_treasury', 'bills', 'notesbonds', 'frn', 'tips']
+            Type of holdings to return. (provider: federal_reserve)
+        summary : bool
+            If True, returns historical weekly summary by holding type. This parameter takes priority over other parameters. (provider: federal_reserve)
+        cusip : Optional[str]
+             Multiple comma separated items allowed.
+        wam : bool
+            If True, returns weighted average maturity aggregated by agency or treasury securities. This parameter takes priority over `holding_type`, `cusip`, and `monthly`. (provider: federal_reserve)
+        monthly : bool
+            If True, returns historical data for all Treasury securities at a monthly interval. This parameter takes priority over other parameters, except `wam`. Only valid when `holding_type` is set to: 'all_treasury', 'bills', 'notesbonds', 'frn', 'tips'. (provider: federal_reserve)
+
+        Returns
+        -------
+        OBBject
+            results : List[CentralBankHoldings]
+                Serializable results.
+            provider : Optional[Literal['federal_reserve']]
+                Provider name.
+            warnings : Optional[List[Warning_]]
+                List of warnings.
+            chart : Optional[Chart]
+                Chart object.
+            extra : Dict[str, Any]
+                Extra info.
+
+        CentralBankHoldings
+        -------------------
+        date : date
+            The date of the data.
+        security_type : Optional[str]
+            Type of security - i.e. TIPs, FRNs, etc. (provider: federal_reserve)
+        description : Optional[str]
+            Description of the security. Only returned for Agency securities. (provider: federal_reserve)
+        is_aggreated : Optional[Literal['Y']]
+            Whether the security is aggregated. Only returned for Agency securities. (provider: federal_reserve)
+        cusip : Optional[str]
+
+        issuer : Optional[str]
+            Issue