AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

usfiscaldata

Queries the U.S. Treasury Fiscal Data REST API for federal financial data. No API key required. Use for national debt (Debt to the Penny), Daily Treasury Statements, Monthly Treasury Statements, Treasury securities auctions, interest rates, foreign exchange rates, savings bonds, or U.S. government revenue and spending statistics.

Original source
K-Dense-AI
License
MIT
Pinned revision
5f2bc0341354fd5590aef76a533ada1e1e5b4e62

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read k-dense-ai--usfiscaldata at revision 5f2bc0341354fd5590aef76a533ada1e1e5b4e62, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 9

references/examples.md

Code Examples — U.S. Treasury Fiscal Data

Python queries and transformations below were exercised against the public API on 2026-09-30. First define fetch_all() from parameters.md, then run the setup. Historic dates are fixed examples, not claims about the current year.

Setup

from datetime import date
from decimal import Decimal
import requests
import pandas as pd

BASE_URL = "https://api.fiscaldata.treasury.gov/services/api/fiscal_service"

def fetch(endpoint, **params):
    """Fetch one page; callers requesting a complete result use fetch_all."""
    allowed = {"fields", "filter", "sort", "format", "page[size]", "page[number]"}
    if set(params) - allowed:
        raise ValueError(f"Unknown query parameters: {set(params) - allowed}")
    resp = requests.get(BASE_URL + endpoint, params=params, timeout=30)
    resp.raise_for_status()
    result = resp.json()
    if "error" in result:
        raise ValueError(result)
    return result

National Debt Tracker

result = fetch("/v2/accounting/od/debt_to_penny",
               sort="-record_date", **{"page[size]": 1})
d = result["data"][0]
debt = Decimal(d["tot_pub_debt_out_amt"])
print(f"National debt as of {d['record_date']}: ${debt:,.2f}")

# Complete fixed-period series; cents remain in raw strings if needed.
df = fetch_all("/v2/accounting/od/debt_to_penny", {
    "filter": "record_date:gte:2024-01-01,record_date:lte:2024-12-31",
    "sort": "record_date", "page[size]": 100,
})
df["date"] = pd.to_datetime(df["record_date"])
df["debt_trillion"] = pd.to_numeric(df["tot_pub_debt_out_amt"]) / 1e12
print(df[["date", "debt_trillion"]].tail())

Treasury Reporting Exchange Rates

endpoint = "/v1/accounting/od/rates_of_exchange"
quarter = fetch(endpoint, sort="-record_date", **{"page[size]": 1})["data"][0]["record_date"]
rates = fetch_all(endpoint, {
    "filter": f"record_date:eq:{quarter}",
    "sort": "country_currency_desc,effective_date,src_line_nbr",
    "page[size]": 100,
})
rates["exchange_rate"] = pd.to_numeric(rates["exchange_rate"])
# Preserve amendments as separate rows; pick the applicable reporting period first.
rates["usd_1000_in_foreign_currency"] = 1000 * rates["exchange_rate"]
print(rates[["country_currency_desc", "record_date", "effective_date",
             "exchange_rate", "usd_1000_in_foreign_currency"]].head())

These are foreign-currency units per USD. Divide a foreign amount by its applicable rate to obtain USD. Amendments have later effective_date values; quarterly PDF reports omit amendments, so do not collapse rows without the official period rules.

Treasury Securities Auction Analysis

# Nominal fixed-rate 10-year notes. auction_date dates the event.
result = fetch("/v1/accounting/od/auctions_query",
    filter="security_type:eq:Note,original_security_term:eq:10-Year,inflation_index_security:eq:No,floating_rate:eq:No",
    sort="-auction_date,cusip", **{"page[size]": 20})
auctions = pd.DataFrame(result["data"])
for col in ["high_yield", "bid_to_cover_ratio", "total_accepted", "indirect_bidder_accepted"]:
    auctions[col] = pd.to_numeric(auctions[col].replace("null", None), errors="coerce")
auctions["indirect_pct_of_total"] = (
    100 * auctions["indirect_bidder_accepted"] / auctions["total_accepted"].where(auctions["total_accepted"] > 0)
)
print(auctions[["auction_date", "cusip", "security_term", "reopening",
                "high_yield", "indirect_pct_of_total"]].head())

original_security_term includes reopened securities whose remaining security_term is shorter. Name the denominator when reporting bidder shares; total_accepted is not the same as competitive awards. Missing yields can mean an auction has been announced but results are unavailable. Auction yields observed on different dates do not form a same-date yield curve; do not inner-join 2-year and 10-year auctions on publication dates and label the difference a market spread.

Daily Treasury Statement

endpoint = "/v1/accounting/dts/operating_cash_balance"
closing = fetch(endpoint,
    filter="account_type:eq:Treasury General Account (TGA) Closing Balance",
    sort="-record_date", **{"page[size]": 5})
for row in closing["data"]:
    print(row["record_date"], Decimal(row["open_today_bal"]), "million USD, closing TGA")

# Named totals avoid adding category detail to summary rows.
cash = fetch_all(endpoint, {
    "filter": "record_date:gte:2024-01-01,record_date:lte:2024-01-31",
    "sort": "record_date,src_line_nbr",
})
cash = cash[cash["account_type"].isin([
    "Total TGA Deposits (Table II)", "Total TGA Withdrawals (Table II) (-)",
])].copy()
cash["million_usd"] = pd.to_numeric(cash["open_today_bal"])
print(cash.pivot(index="record_date", columns="account_type", values="million_usd"))

Since April 18, 2022, close_today_bal is null. The closing-balance account row stores its value in open_today_bal. Earlier layouts need separate handling. DTS cash movements include financing and differ from MTS budget receipts/outlays.

Monthly Budget Summary

budget = fetch_all("/v1/accounting/mts/mts_receipts_outlays_deficit_surplus", {
    "filter": "record_fiscal_year:eq:2024",
    "sort": "record_date,src_line_nbr",
})
budget = budget[budget["amt_category"].isin(["Receipts", "Outlays", "Deficit/Surplus (-)"])].copy()
budget["million_usd"] = pd.to_numeric(budget["mil_amt"])
monthly = budget.pivot(index="record_date", columns="amt_category", values="million_usd")
assert len(monthly) == 12, "Fiscal year is incomplete"
# Published values are rounded to millions; allow rounding differences.
residual = monthly["Outlays"] - monthly["Receipts"] - monthly["Deficit/Surplus (-)"]
if (residual.abs() > 1).any():
    print("[WARN] Reconcile source revisions/footnotes before using these months:")
    print(residual[residual.abs() > 1])
print(monthly)

The live FY2024 extract on the review date had a March 2024 reconciliation residual of -270 million USD, beyond rounding. This example exposes that source discrepancy; it does not treat the series as reconciled or overwrite the published values. Check the matching report/revisions before drawing budget conclusions.

This summary has explicit million-dollar units. Tables 1 and 9 have different fields and dollar-scale API values; Table 1 repeats prior months and fiscal-year sections in each publication. Never add all Table 1 rows to obtain monthly totals.

Average Treasury and I Bond Rates

rates = fetch_all("/v2/accounting/od/avg_interest_rates", {
    "filter": "security_type_desc:eq:Marketable,record_date:gte:2024-01-01,record_date:lte:2024-12-31",
    "sort": "record_date,src_line_nbr",
})
rates["rate_pct"] = pd.to_numeric(rates["avg_interest_rate_amt"])
print(rates.pivot(index="record_date", columns="security_desc", values="rate_pct"))

# One issue vintage and a fixed earning-period cutoff, not a universal I Bond rate.
issue_month = "2024-05"
bonds = fetch("/v1/accounting/od/i_bonds_interest_rates",
    filter=f"issue_year_month:eq:{issue_month},earning_period_start:lte:2024-11-01",
    sort="-earning_period_start", **{"page[size]": 1})
print(pd.DataFrame(bonds["data"])[["issue_year_month", "earning_period_start",
                                  "earning_period_end", "fixed_rate", "combined_rate"]])

Average interest rates describe the outstanding debt portfolio, not current market yields. I Bond fixed rates depend on issue vintage; the earning-period columns and issue month must be retained together.

Completed Fiscal-Year Interest Expense

fy = 2024
expenses = fetch_all("/v2/accounting/od/interest_expense", {
    "filter": f"record_fiscal_year:eq:{fy}",
    "sort": "record_date,src_line_nbr",
})
assert expenses["record_date"].nunique() == 12, "Fiscal year is incomplete"
assert expenses["record_date"].max() == f"{fy}-09-30"
assert not expenses.duplicated(["record_date", "src_line_nbr"]).any()
monthly_total = sum(Decimal(x) for x in expenses["month_expense_amt"])
september = expenses[expenses["record_date"] == f"{fy}-09-30"]
fytd_total = sum(Decimal(x) for x in september["fytd_expense_amt"])
assert abs(monthly_total - fytd_total) <= Decimal("0.01"), "Reconcile revisions/components"
print(f"FY{fy} public-debt interest expense: ${fytd_total:,.2f}")

This uses the expense dataset's components and accounting basis, not budget net interest. Sum monthly flows once, or take September FYTD once; never sum FYTD values across months. Preserve category/group/type fields to inspect components.

R example (illustrative; R runtime not exercised)

library(httr)
library(jsonlite)
base <- "https://api.fiscaldata.treasury.gov/services/api/fiscal_service"
response <- GET(paste0(base, "/v1/accounting/mts/mts_table_9"),
                query = list(filter = "line_code_nbr:eq:120",
                             sort = "-record_date", `page[size]` = 1),
                timeout(30))
stop_for_status(response)
result <- fromJSON(rawToChar(response$content))
stopifnot(nrow(result$data) == 1)
print(result$data[c("record_date", "classification_desc", "current_month_rcpt_outly_amt")])

Discovering fields and datasets

result = fetch("/v2/accounting/od/debt_to_penny", **{"page[size]": 1})
for field, label in result["meta"]["labels"].items():
    print(field, result["meta"]["dataTypes"][field], label)

Use the dataset catalog and each API Quick Guide/data dictionary for current paths, table coverage, units and limitations. The API guide documents common filters, pagination and response metadata.