ContextQMD
Back to Claude Scientific Skills

U.S. Treasury Fiscal Data API

scientific-skills/usfiscaldata/SKILL.md

2.38.05.7 KB
Original Source

U.S. Treasury Fiscal Data API

Free, open REST API from the U.S. Department of the Treasury for federal financial data. No API key or registration required.

Base URL: https://api.fiscaldata.treasury.gov/services/api/fiscal_service

Quick Start

python
import requests
import pandas as pd

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

# Get the current national debt (Debt to the Penny)
resp = requests.get(f"{BASE_URL}/v2/accounting/od/debt_to_penny", params={
    "sort": "-record_date",
    "page[size]": 1
})
data = resp.json()["data"][0]
print(f"Total public debt as of {data['record_date']}: ${float(data['tot_pub_debt_out_amt']):,.0f}")
python
# Get Treasury exchange rates for recent quarters
resp = requests.get(f"{BASE_URL}/v1/accounting/od/rates_of_exchange", params={
    "fields": "country_currency_desc,exchange_rate,record_date",
    "filter": "record_date:gte:2024-01-01",
    "sort": "-record_date",
    "page[size]": 100
})
df = pd.DataFrame(resp.json()["data"])

Authentication

None required. The API is fully open and free.

Core Parameters

ParameterExampleDescription
fields=fields=record_date,tot_pub_debt_out_amtSelect specific columns
filter=filter=record_date:gte:2024-01-01Filter records
sort=sort=-record_dateSort (prefix - for descending)
format=format=jsonOutput format: json, csv, xml
page[size]=page[size]=100Records per page (default 100)
page[number]=page[number]=2Page index (starts at 1)

Filter operators: lt, lte, gt, gte, eq, in

python
# Multiple filters separated by comma
"filter=country_currency_desc:in:(Canada-Dollar,Mexico-Peso),record_date:gte:2024-01-01"

Key Datasets & Endpoints

Debt

DatasetEndpointFrequency
Debt to the Penny/v2/accounting/od/debt_to_pennyDaily
Historical Debt Outstanding/v2/accounting/od/historical_debt_outstandingAnnual
Schedules of Federal Debt/v1/accounting/od/schedules_fed_debtMonthly

Daily & Monthly Statements

DatasetEndpointFrequency
DTS Operating Cash Balance/v1/accounting/dts/operating_cash_balanceDaily
DTS Deposits & Withdrawals/v1/accounting/dts/deposits_withdrawals_operating_cashDaily
Monthly Treasury Statement (MTS)/v1/accounting/mts/mts_table_1 (16 tables)Monthly

Interest Rates & Exchange

DatasetEndpointFrequency
Average Interest Rates on Treasury Securities/v2/accounting/od/avg_interest_ratesMonthly
Treasury Reporting Rates of Exchange/v1/accounting/od/rates_of_exchangeQuarterly
Interest Expense on Public Debt/v2/accounting/od/interest_expenseMonthly

Securities & Auctions

DatasetEndpointFrequency
Treasury Securities Auctions Data/v1/accounting/od/auctions_queryAs Needed
Treasury Securities Upcoming Auctions/v1/accounting/od/upcoming_auctionsAs Needed
Average Interest Rates/v2/accounting/od/avg_interest_ratesMonthly

Savings Bonds

DatasetEndpointFrequency
I Bonds Interest Rates/v2/accounting/od/i_bond_interest_ratesSemi-Annual
U.S. Treasury Savings Bonds: Issues, Redemptions & Maturities/v1/accounting/od/sb_issues_redemptionsMonthly

Response Structure

json
{
  "data": [...],
  "meta": {
    "count": 100,
    "total-count": 3790,
    "total-pages": 38,
    "labels": {"field_name": "Human Readable Label"},
    "dataTypes": {"field_name": "STRING|NUMBER|DATE|CURRENCY"},
    "dataFormats": {"field_name": "String|10.2|YYYY-MM-DD"}
  },
  "links": {"self": "...", "first": "...", "prev": null, "next": "...", "last": "..."}
}

Note: All values are returned as strings. Convert as needed (e.g., float(), pd.to_datetime()). Null values appear as the string "null".

Common Patterns

Load all pages into a DataFrame

python
def fetch_all_pages(endpoint, params=None):
    params = params or {}
    params["page[size]"] = 10000  # max size to minimize requests
    resp = requests.get(f"{BASE_URL}{endpoint}", params=params)
    result = resp.json()
    df = pd.DataFrame(result["data"])
    return df

Aggregation (automatic sum)

Omitting grouping fields triggers automatic aggregation:

python
# Sum all deposits/withdrawals by record_date and transaction type
resp = requests.get(f"{BASE_URL}/v1/accounting/dts/deposits_withdrawals_operating_cash", params={
    "fields": "record_date,transaction_type,transaction_today_amt"
})

Reference Files