# Fed SOMA Holdings: Federal Reserve Balance Sheet by CUSIP (`darthdimus/nyfed-soma-holdings`) Actor

Official NY Fed System Open Market Account (SOMA) holdings: weekly totals (bills, notes/bonds, TIPS, FRNs, MBS, CMBS, agencies) since 2003, every Treasury and agency MBS CUSIP the Fed holds on any as-of date, or one CUSIP's history. QT tracking, no API key.

- **URL**: https://apify.com/darthdimus/nyfed-soma-holdings.md
- **Developed by:** [Dmitry Ostrovsky](https://apify.com/darthdimus) (community)
- **Categories:** Business
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Fed SOMA Holdings: Federal Reserve Balance Sheet by CUSIP

Apify Actor that pulls the **Federal Reserve's System Open Market Account (SOMA) holdings** from the official New York Fed Markets Data API (https://markets.newyorkfed.org/static/docs/markets-api.html) and returns clean, typed rows. No API key needed, no scraping.

SOMA is the Fed's portfolio of Treasury and agency securities, the asset side behind quantitative easing (QE) and quantitative tightening (QT). The NY Fed publishes it weekly, as of each Wednesday.

### Modes

- **summary** (default): weekly totals by asset class since July 2003: bills, notes & bonds, TIPS (plus inflation compensation), FRNs, agency MBS, CMBS, agency debt, and the total, with the week-over-week change in the total. Good for charting QT runoff.
- **treasury**: every Treasury CUSIP the Fed holds on one as-of date (about 430 securities): maturity, coupon or FRN spread, par value, share of the issue outstanding held, and the change from the prior week and year.
- **agency**: every agency debt, agency MBS and CMBS CUSIP on one as-of date (about 9,000 securities): description (e.g. `UMBS MORTPASS 2% 10/51`), term, and current face value.
- **cusip**: the full weekly history of one or more CUSIPs (Treasury or agency), e.g. to see when the Fed bought a security and how its holding ran off.

### Input

- `mode`: `summary`, `treasury`, `agency`, or `cusip`.
- `securityTypes` (treasury/agency): `Bills, NotesBonds, TIPS, FRNs` or `MBS, CMBS, Agency Debts`. Empty = all.
- `asOfDate` (treasury/agency): `2026-10-07`. Empty = latest. A non-Wednesday date snaps to the latest published date on or before it.
- `cusips` (cusip mode): comma-separated, e.g. `3132DVGB5,912828YK0`.
- `startDate` / `endDate` (summary/cusip): optional date filters.
- `lastN` (summary): latest N weeks when no start date is set (default 12).
- `minParValue`: skip holdings smaller than this (USD).
- `sortBy` (treasury/agency): `value_desc` (default), `maturity_asc`, `as_published`.
- `maxRows`: total row cap (1-20000, default 1000).

Example: the 20 largest MBS pools the Fed holds right now

```json
{ "mode": "agency", "securityTypes": "MBS", "maxRows": 20 }
```

### Output

Summary row:

```json
{
  "asOfDate": "2026-10-07",
  "total": 6360519997880.2,
  "totalChangeFromPriorWeek": 1946000000,
  "bills": 562156926700,
  "notesBonds": 3597915855200,
  "tips": 279965204500,
  "tipsInflationCompensation": 106300118348.37,
  "frn": 20045553800,
  "mbs": 1890705863534.6,
  "cmbs": 7383594145.6,
  "agencies": 2347000000,
  "totalInBillions": 6360.52,
  "source": "Federal Reserve Bank of New York Markets Data API (SOMA)"
}
```

Holding row (treasury/agency/cusip modes):

```json
{
  "asOfDate": "2026-10-07",
  "cusip": "912797SK4",
  "assetClass": "Treasury",
  "securityType": "Bills",
  "securityDescription": null,
  "issuer": null,
  "maturityDate": "2026-10-29",
  "coupon": null,
  "spread": null,
  "term": null,
  "parValue": 29005617900,
  "currentFaceValue": null,
  "value": 29005617900,
  "inflationCompensation": null,
  "percentOutstanding": 0.0919952532500852,
  "changeFromPriorWeek": 0,
  "changeFromPriorYear": null,
  "isAggregated": null,
  "source": "Federal Reserve Bank of New York Markets Data API (SOMA)"
}
```

`value` is par value for Treasury and agency debt, and current face value for MBS/CMBS, so you can sort or sum across asset classes. `percentOutstanding` is published by the NY Fed as a fraction of the issue outstanding (0.092 = 9.2%). Summary `total` excludes TIPS inflation compensation, matching the NY Fed.

### Notes

- Published weekly (Thursday afternoon ET, as of Wednesday). Amounts in USD.
- Public data only. Limited-permission Actor; standby off. Not affiliated with the Federal Reserve Bank of New York or the Federal Reserve System.
- Pairs well with the NY Fed SOFR & reference rates, FINRA short interest and SEC filing Actors from the same author.
- Charges: one `actor-start` event per run and one `summary-row` / `holding-row` event per dataset item if pay-per-event pricing is enabled.

# Actor input Schema

## `mode` (type: `string`):

summary = weekly totals by asset class (since 2003). treasury = every Treasury CUSIP held on one as-of date. agency = every agency debt / MBS / CMBS CUSIP held on one as-of date. cusip = full weekly history of the CUSIPs listed below.

## `securityTypes` (type: `string`):

Optional comma-separated filter. Treasury: Bills, NotesBonds, TIPS, FRNs. Agency: MBS, CMBS, Agency Debts. Empty = all types for the chosen mode.

## `asOfDate` (type: `string`):

Optional. YYYY-MM-DD. SOMA is published weekly as of Wednesday. Empty = latest published date. A non-Wednesday date snaps to the latest published as-of date on or before it.

## `cusips` (type: `string`):

Comma-separated CUSIPs, e.g. 912828YK0 (Treasury) or 3132DVGB5 (UMBS). The Actor checks both Treasury and agency holdings.

## `startDate` (type: `string`):

Optional. YYYY-MM-DD. Keep rows with as-of date on or after this date.

## `endDate` (type: `string`):

Optional. YYYY-MM-DD. Keep rows with as-of date on or before this date.

## `lastN` (type: `integer`):

Used in summary mode when no start date is set: latest N weekly as-of dates (1-2000).

## `minParValue` (type: `integer`):

Optional. Holdings modes only: skip CUSIPs with par value (Treasury/agency debt) or current face value (MBS/CMBS) below this amount.

## `sortBy` (type: `string`):

Order of CUSIP rows in treasury / agency modes. Summary and cusip modes sort by date, newest first.

## `maxRows` (type: `integer`):

Maximum total rows to push (1-20000). Agency mode on one date has about 9,000 CUSIPs.

## Actor input object example

```json
{
  "mode": "summary",
  "securityTypes": "",
  "asOfDate": "",
  "cusips": "",
  "startDate": "",
  "endDate": "",
  "lastN": 12,
  "minParValue": 0,
  "sortBy": "value_desc",
  "maxRows": 1000
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "summary",
    "securityTypes": "",
    "asOfDate": "",
    "cusips": "",
    "startDate": "",
    "endDate": "",
    "lastN": 12
};

// Run the Actor and wait for it to finish
const run = await client.actor("darthdimus/nyfed-soma-holdings").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "summary",
    "securityTypes": "",
    "asOfDate": "",
    "cusips": "",
    "startDate": "",
    "endDate": "",
    "lastN": 12,
}

# Run the Actor and wait for it to finish
run = client.actor("darthdimus/nyfed-soma-holdings").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "summary",
  "securityTypes": "",
  "asOfDate": "",
  "cusips": "",
  "startDate": "",
  "endDate": "",
  "lastN": 12
}' |
apify call darthdimus/nyfed-soma-holdings --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,darthdimus/nyfed-soma-holdings"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/qRQXvyJU1yYuakyto/builds/JwbORFQ84rwsWLpOj/openapi.json
