data-analyst-mcp 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (292) hide show
  1. package/README.md +286 -262
  2. package/dist/adapters/bjs.d.ts +13 -0
  3. package/dist/adapters/bjs.js +28 -0
  4. package/dist/adapters/bjs.js.map +1 -0
  5. package/dist/adapters/cbp.d.ts +5 -0
  6. package/dist/adapters/cbp.js +64 -0
  7. package/dist/adapters/cbp.js.map +1 -0
  8. package/dist/adapters/cdc-wonder.d.ts +5 -0
  9. package/dist/adapters/cdc-wonder.js +68 -0
  10. package/dist/adapters/cdc-wonder.js.map +1 -0
  11. package/dist/adapters/cpsc.d.ts +4 -0
  12. package/dist/adapters/cpsc.js +125 -0
  13. package/dist/adapters/cpsc.js.map +1 -0
  14. package/dist/adapters/fhwa.d.ts +9 -0
  15. package/dist/adapters/fhwa.js +16 -0
  16. package/dist/adapters/fhwa.js.map +1 -0
  17. package/dist/adapters/foreign-assistance.d.ts +9 -0
  18. package/dist/adapters/foreign-assistance.js +42 -0
  19. package/dist/adapters/foreign-assistance.js.map +1 -0
  20. package/dist/adapters/hud-ahar.d.ts +3 -0
  21. package/dist/adapters/hud-ahar.js +80 -0
  22. package/dist/adapters/hud-ahar.js.map +1 -0
  23. package/dist/adapters/nces.d.ts +10 -0
  24. package/dist/adapters/nces.js +32 -0
  25. package/dist/adapters/nces.js.map +1 -0
  26. package/dist/adapters/nsf.d.ts +11 -0
  27. package/dist/adapters/nsf.js +25 -0
  28. package/dist/adapters/nsf.js.map +1 -0
  29. package/dist/adapters/onrr.d.ts +9 -0
  30. package/dist/adapters/onrr.js +35 -0
  31. package/dist/adapters/onrr.js.map +1 -0
  32. package/dist/adapters/sba.d.ts +10 -0
  33. package/dist/adapters/sba.js +134 -0
  34. package/dist/adapters/sba.js.map +1 -0
  35. package/dist/adapters/treasury-tic.d.ts +30 -0
  36. package/dist/adapters/treasury-tic.js +149 -0
  37. package/dist/adapters/treasury-tic.js.map +1 -0
  38. package/dist/adapters/uscourts.d.ts +8 -0
  39. package/dist/adapters/uscourts.js +8 -0
  40. package/dist/adapters/uscourts.js.map +1 -0
  41. package/dist/analysis/cite.d.ts +9 -1
  42. package/dist/analysis/cite.js +9 -2
  43. package/dist/analysis/cite.js.map +1 -1
  44. package/dist/bin/cli.d.ts +2 -0
  45. package/dist/bin/cli.js +17 -0
  46. package/dist/bin/cli.js.map +1 -1
  47. package/dist/core/generic-rest.js +42 -17
  48. package/dist/core/generic-rest.js.map +1 -1
  49. package/dist/core/guard.d.ts +32 -0
  50. package/dist/core/guard.js +176 -0
  51. package/dist/core/guard.js.map +1 -0
  52. package/dist/core/http.d.ts +10 -0
  53. package/dist/core/http.js +36 -7
  54. package/dist/core/http.js.map +1 -1
  55. package/dist/core/keys.d.ts +13 -3
  56. package/dist/core/keys.js +67 -7
  57. package/dist/core/keys.js.map +1 -1
  58. package/dist/core/package.d.ts +12 -3
  59. package/dist/core/package.js +56 -12
  60. package/dist/core/package.js.map +1 -1
  61. package/dist/core/secret_patterns.d.ts +6 -0
  62. package/dist/core/secret_patterns.js +20 -0
  63. package/dist/core/secret_patterns.js.map +1 -0
  64. package/dist/core/tabular.d.ts +43 -1
  65. package/dist/core/tabular.js +149 -6
  66. package/dist/core/tabular.js.map +1 -1
  67. package/dist/envelope.js +3 -1
  68. package/dist/envelope.js.map +1 -1
  69. package/dist/index.d.ts +29 -22
  70. package/dist/index.js +45 -46
  71. package/dist/index.js.map +1 -1
  72. package/dist/remote/app.js +87 -31
  73. package/dist/remote/app.js.map +1 -1
  74. package/dist/remote/oauth.js +8 -1
  75. package/dist/remote/oauth.js.map +1 -1
  76. package/dist/remote/pages.d.ts +3 -7
  77. package/dist/remote/pages.js +49 -19
  78. package/dist/remote/pages.js.map +1 -1
  79. package/dist/remote/sign.d.ts +7 -1
  80. package/dist/remote/sign.js +33 -7
  81. package/dist/remote/sign.js.map +1 -1
  82. package/dist/remote/store.js +14 -5
  83. package/dist/remote/store.js.map +1 -1
  84. package/dist/report/audit_report.js +29 -7
  85. package/dist/report/audit_report.js.map +1 -1
  86. package/dist/report/build_report.js +34 -4
  87. package/dist/report/build_report.js.map +1 -1
  88. package/dist/report/method_audit.js +10 -1
  89. package/dist/report/method_audit.js.map +1 -1
  90. package/dist/report/scan_secrets.d.ts +4 -1
  91. package/dist/report/scan_secrets.js +38 -18
  92. package/dist/report/scan_secrets.js.map +1 -1
  93. package/dist/server.d.ts +3 -1
  94. package/dist/server.js +46 -13
  95. package/dist/server.js.map +1 -1
  96. package/dist/tools.js +27 -6
  97. package/dist/tools.js.map +1 -1
  98. package/guide/WORKFLOW.md +134 -134
  99. package/guide/assets/disclaimer.txt +1 -1
  100. package/guide/assets/download_data.ps1 +164 -162
  101. package/guide/assets/download_data.sh +8 -2
  102. package/guide/assets/report_template.html +597 -597
  103. package/guide/references/routing.md +198 -171
  104. package/guide/references/style_guide.md +398 -398
  105. package/package.json +56 -56
  106. package/packs/acf/endpoints.json +114 -114
  107. package/packs/acf/policy.json +104 -104
  108. package/packs/actuaries/endpoints.json +82 -82
  109. package/packs/actuaries/policy.json +109 -109
  110. package/packs/bea/assets/download_bea.ps1 +182 -182
  111. package/packs/bea/docs/bea_api.md +461 -461
  112. package/packs/bea/docs/datasets.md +157 -157
  113. package/packs/bea/docs/report_patterns.md +112 -112
  114. package/packs/bea/policy.json +170 -170
  115. package/packs/bea/source.md +152 -152
  116. package/packs/bjs/endpoints.json +150 -0
  117. package/packs/bjs/policy.json +114 -0
  118. package/packs/bjs/source.md +98 -0
  119. package/packs/bls/assets/download_bls.ps1 +152 -152
  120. package/packs/bls/docs/analysis_patterns.md +108 -108
  121. package/packs/bls/docs/bls_api.md +73 -73
  122. package/packs/bls/docs/series_ids.md +149 -149
  123. package/packs/bls/policy.json +238 -238
  124. package/packs/bts/endpoints.json +346 -346
  125. package/packs/bts/policy.json +94 -94
  126. package/packs/cbp/endpoints.json +31 -0
  127. package/packs/cbp/policy.json +85 -0
  128. package/packs/cbp/source.md +57 -0
  129. package/packs/cdc/endpoints.json +197 -197
  130. package/packs/cdc/policy.json +83 -83
  131. package/packs/cdc/source.md +1 -1
  132. package/packs/cdc-wonder/endpoints.json +26 -0
  133. package/packs/cdc-wonder/policy.json +84 -0
  134. package/packs/cdc-wonder/source.md +53 -0
  135. package/packs/census/endpoints.json +99 -99
  136. package/packs/cfpb/endpoints.json +326 -326
  137. package/packs/cfpb/policy.json +119 -119
  138. package/packs/clinical-trials/endpoints.json +166 -166
  139. package/packs/clinical-trials/policy.json +84 -84
  140. package/packs/cms/endpoints.json +69 -69
  141. package/packs/cms/policy.json +96 -96
  142. package/packs/college-scorecard/endpoints.json +252 -252
  143. package/packs/college-scorecard/policy.json +106 -106
  144. package/packs/college-scorecard/source.md +1 -1
  145. package/packs/congress/endpoints.json +1701 -1701
  146. package/packs/congress/policy.json +117 -117
  147. package/packs/cpsc/endpoints.json +91 -0
  148. package/packs/cpsc/policy.json +91 -0
  149. package/packs/cpsc/source.md +76 -0
  150. package/packs/dhs-ohss/endpoints.json +66 -66
  151. package/packs/dhs-ohss/policy.json +107 -107
  152. package/packs/dhs-ohss/source.md +1 -1
  153. package/packs/doj-news/endpoints.json +59 -59
  154. package/packs/doj-news/policy.json +96 -96
  155. package/packs/doj-news/source.md +1 -1
  156. package/packs/dol/endpoints.json +817 -817
  157. package/packs/dol/policy.json +135 -135
  158. package/packs/eia/endpoints.json +717 -717
  159. package/packs/eia/policy.json +112 -112
  160. package/packs/epa/endpoints.json +291 -291
  161. package/packs/epa/policy.json +99 -99
  162. package/packs/epa-aqs/endpoints.json +173 -173
  163. package/packs/epa-aqs/policy.json +96 -96
  164. package/packs/fbi/endpoints.json +1841 -1841
  165. package/packs/fbi/policy.json +118 -118
  166. package/packs/fbi/source.md +3 -3
  167. package/packs/fda/endpoints.json +237 -237
  168. package/packs/fda/policy.json +121 -121
  169. package/packs/fdic/endpoints.json +416 -416
  170. package/packs/fdic/policy.json +83 -83
  171. package/packs/fec/endpoints.json +707 -707
  172. package/packs/fec/policy.json +93 -93
  173. package/packs/fed-board/endpoints.json +89 -89
  174. package/packs/fed-board/policy.json +136 -136
  175. package/packs/federal-register/endpoints.json +143 -143
  176. package/packs/federal-register/policy.json +86 -86
  177. package/packs/fema/endpoints.json +645 -645
  178. package/packs/fema/policy.json +103 -103
  179. package/packs/fhfa/endpoints.json +105 -105
  180. package/packs/fhfa/policy.json +109 -109
  181. package/packs/fhwa/endpoints.json +48 -0
  182. package/packs/fhwa/policy.json +91 -0
  183. package/packs/fhwa/source.md +59 -0
  184. package/packs/foreign-assistance/endpoints.json +166 -0
  185. package/packs/foreign-assistance/policy.json +80 -0
  186. package/packs/foreign-assistance/source.md +76 -0
  187. package/packs/fred/assets/download_fred.ps1 +122 -122
  188. package/packs/fred/docs/analysis_patterns.md +124 -124
  189. package/packs/fred/docs/fred_api.md +94 -94
  190. package/packs/fred/docs/series.md +188 -188
  191. package/packs/fred/policy.json +253 -253
  192. package/packs/fsa/endpoints.json +150 -150
  193. package/packs/fsa/policy.json +99 -99
  194. package/packs/fsa/source.md +1 -1
  195. package/packs/govinfo/endpoints.json +519 -519
  196. package/packs/gsa-calc/endpoints.json +93 -93
  197. package/packs/gsa-calc/policy.json +97 -97
  198. package/packs/hud/endpoints.json +146 -146
  199. package/packs/hud/policy.json +84 -84
  200. package/packs/hud/source.md +1 -1
  201. package/packs/hud-ahar/endpoints.json +92 -0
  202. package/packs/hud-ahar/policy.json +88 -0
  203. package/packs/hud-ahar/source.md +72 -0
  204. package/packs/ipums/docs/report_patterns.md +117 -117
  205. package/packs/irs-soi/endpoints.json +114 -114
  206. package/packs/irs-soi/policy.json +107 -107
  207. package/packs/medicaid/endpoints.json +412 -412
  208. package/packs/medicaid/policy.json +108 -108
  209. package/packs/naep/endpoints.json +217 -217
  210. package/packs/naep/policy.json +100 -100
  211. package/packs/naep/source.md +1 -1
  212. package/packs/nces/endpoints.json +101 -0
  213. package/packs/nces/policy.json +99 -0
  214. package/packs/nces/source.md +75 -0
  215. package/packs/nhtsa/endpoints.json +132 -132
  216. package/packs/nhtsa/policy.json +93 -93
  217. package/packs/nhtsa/source.md +1 -1
  218. package/packs/nih/endpoints.json +452 -452
  219. package/packs/nih/policy.json +86 -86
  220. package/packs/noaa/endpoints.json +431 -431
  221. package/packs/noaa/policy.json +95 -95
  222. package/packs/nrel/endpoints.json +327 -327
  223. package/packs/nrel/policy.json +96 -96
  224. package/packs/nsf/endpoints.json +33 -0
  225. package/packs/nsf/policy.json +83 -0
  226. package/packs/nsf/source.md +59 -0
  227. package/packs/nws/endpoints.json +271 -271
  228. package/packs/nws/policy.json +82 -82
  229. package/packs/nyfed/endpoints.json +80 -80
  230. package/packs/nyfed/policy.json +92 -92
  231. package/packs/omb/endpoints.json +460 -460
  232. package/packs/omb/policy.json +106 -106
  233. package/packs/onrr/endpoints.json +198 -0
  234. package/packs/onrr/policy.json +91 -0
  235. package/packs/onrr/source.md +55 -0
  236. package/packs/open-payments/endpoints.json +297 -297
  237. package/packs/open-payments/policy.json +101 -101
  238. package/packs/opm/assets/download_opm.ps1 +125 -125
  239. package/packs/opm/docs/fields.md +184 -184
  240. package/packs/opm/docs/opm_api.md +71 -71
  241. package/packs/opm/docs/report_patterns.md +83 -83
  242. package/packs/opm/lib/data_dictionary.csv +73 -73
  243. package/packs/pbgc/endpoints.json +483 -483
  244. package/packs/pbgc/policy.json +94 -94
  245. package/packs/philfed/endpoints.json +85 -85
  246. package/packs/philfed/policy.json +94 -94
  247. package/packs/port.json +65 -0
  248. package/packs/regulations/endpoints.json +287 -287
  249. package/packs/regulations/policy.json +86 -86
  250. package/packs/sba/endpoints.json +34 -0
  251. package/packs/sba/policy.json +86 -0
  252. package/packs/sba/source.md +60 -0
  253. package/packs/sec/endpoints.json +236 -236
  254. package/packs/sec/policy.json +86 -86
  255. package/packs/senate-lobbying/endpoints.json +553 -553
  256. package/packs/senate-lobbying/policy.json +99 -99
  257. package/packs/snapqc/endpoints.json +1426 -1426
  258. package/packs/snapqc/policy.json +92 -92
  259. package/packs/treasury/catalog.json +2267 -2267
  260. package/packs/treasury/docs/api_guide.md +245 -245
  261. package/packs/treasury/docs/datasets.md +56 -56
  262. package/packs/treasury/docs/report_patterns.md +126 -126
  263. package/packs/treasury/policy.json +159 -159
  264. package/packs/treasury/source.md +170 -165
  265. package/packs/treasury-tic/endpoints.json +77 -0
  266. package/packs/treasury-tic/policy.json +89 -0
  267. package/packs/treasury-tic/source.md +80 -0
  268. package/packs/treasury-yields/endpoints.json +226 -226
  269. package/packs/treasury-yields/policy.json +86 -86
  270. package/packs/usaspending/endpoints.json +1315 -1315
  271. package/packs/usaspending/policy.json +109 -109
  272. package/packs/uscourts/endpoints.json +22 -0
  273. package/packs/uscourts/policy.json +87 -0
  274. package/packs/uscourts/source.md +56 -0
  275. package/packs/usda-fna/policy.json +133 -133
  276. package/packs/usda-fooddata/endpoints.json +180 -180
  277. package/packs/usda-fooddata/policy.json +94 -94
  278. package/packs/usda-nass/endpoints.json +323 -323
  279. package/packs/usda-nass/policy.json +95 -95
  280. package/packs/usda-outlook/endpoints.json +86 -86
  281. package/packs/usda-outlook/policy.json +109 -109
  282. package/packs/usgs/endpoints.json +313 -313
  283. package/packs/usgs/policy.json +95 -95
  284. package/packs/usitc/endpoints.json +74 -74
  285. package/packs/usitc/policy.json +111 -111
  286. package/packs/uspto/endpoints.json +141 -141
  287. package/packs/uspto/policy.json +95 -95
  288. package/packs/uspto/source.md +1 -1
  289. package/packs/va/endpoints.json +414 -414
  290. package/packs/va/policy.json +101 -101
  291. package/packs/world-bank/endpoints.json +122 -122
  292. package/packs/world-bank/policy.json +101 -101
@@ -1,165 +1,170 @@
1
- # U.S. Treasury Fiscal Data (fiscaldata.treasury.gov)
2
- Depth: deep. Key: none. Official federal finance statistics from the Bureau of the Fiscal Service: debt,
3
- deficits, receipts and outlays (Monthly Treasury Statement), Treasury cash (Daily Treasury Statement),
4
- interest expense and average rates on the debt, the debt limit, auctions, exchange rates; 185 endpoints.
5
-
6
- ## When to use
7
- - National debt (total, held by the public, intragovernmental; daily since 1993, yearly since 1790), debt by
8
- security type, debt subject to the limit; monthly and fiscal-year receipts, outlays and deficits; receipts
9
- by source, outlays by function and by agency; gross interest expense, net interest, average interest rates
10
- on outstanding debt; the TGA cash balance and daily deposits and withdrawals; auction results; exchange
11
- rates for federal reporting; gifts to reduce the debt; savings bonds; buybacks.
12
- - Not here: market yields and the daily par yield curve (treasury-yields); GDP and CPI (bea, bls, fred; or
13
- the spec's `context` field here, for real dollars and "% of GDP"); budget projections (CBO); historical tables in
14
- % of GDP and the President's budget (OMB); who holds the debt by country (Treasury TIC, not Fiscal Data);
15
- state and local finances (Census).
16
- - Deliver data plus a short answer by default; a report only when asked (see `guide`).
17
-
18
- ## Endpoints and datasets
19
- Base `https://api.fiscaldata.treasury.gov/services/api/fiscal_service/` + a path with a fixed version (v1 or
20
- v2: the other returns 404). `request_schema` with `search: "interest expense"` searches the live catalog
21
- (falls back to the bundled `catalog.json`: a snapshot of the live catalog plus this guidance); `search:
22
- "<endpoint>"` gives fields, types, units, row count, first and last row; `search: "<endpoint> {"record_date":
23
- "2026-09-30"} values"` shows which values each code and description column holds; `request_schema` with
24
- `names: ["dataset"]` lists the curated rows below. Full question-to-endpoint table: `docs/datasets.md`; API rules,
25
- field meanings and the numbered gotchas: `docs/api_guide.md`; framing and conventions: `docs/report_patterns.md`.
26
-
27
- | Question | Endpoint | Rows to use | Stock/flow | Units |
28
- |---|---|---|---|---|
29
- | Total debt, held by the public, intragovernmental (daily) | `v2/accounting/od/debt_to_penny` | one row per business day | stock | $ |
30
- | Debt at fiscal year end since 1790 | `v2/accounting/od/debt_outstanding` | one row per year | stock | $ |
31
- | Debt by security type (monthly) | `v1/debt/mspd/mspd_table_1` | `security_type_desc`, `security_class_desc`; skip "Total" rows | stock | $M |
32
- | Debt subject to the limit | `v1/debt/mspd/mspd_table_2`, `v1/accounting/dts/debt_subject_to_limit` | `debt_catg_desc` | stock | $M |
33
- | Monthly receipts, outlays, deficit since FY1981 | `v1/accounting/mts/mts_receipts_outlays_deficit_surplus` | `amt_category` | flow | $M |
34
- | Receipts, outlays, deficit since FY2015 | `v1/accounting/mts/mts_table_1` | months: latest `record_date`, `record_type_cd` MTH; full FY: the September release's "Year-to-Date" row (`record_type_cd` SL, `data_type_cd` T) in the current-year block (`sequence_number_cd` 2.13; 1.13 is the prior year) | flow | $ |
35
- | Receipts by source, outlays by function | `v1/accounting/mts/mts_table_9` | September `record_date`; `data_type_cd` D components, T "Total" | flow | $ |
36
- | Outlays by agency, bureau, program | `v1/accounting/mts/mts_table_5` | `record_type_cd` A agency totals; D rows sum to "Total Outlays". A program account is a `classification_desc` line under its agency (Medicaid: "Grants to States for Medicaid" under HHS, `record_type_cd` P; FY2019 $409.4 billion = OMB Table 8.5): fetch the agency's rows and match the line by name (`--values` lists up to 200 lines per column under a narrow filter) | flow | $ |
37
- | Gross interest expense | `v2/accounting/od/interest_expense` | all rows (detail only) sum to the total; MTS leaves out the GAS "Restoration of Interest" line (FY2025 on); TIPS lines include inflation compensation, a separate GAS "Inflation Compensation" line is not TIPS (docs/datasets.md) | flow | $ |
38
- | Outlays by budget function (Social Security 650, Medicare 570, defense 050, net interest 900 ...) | MTS Table 9 (`v1/accounting/mts/mts_table_9`) | function rows add to total outlays; a function is not CBO's program measure (Social Security 650 includes administration; CBO reports benefits; Medicare 570 is gross of some offsetting receipts CBO nets) | flow | $M |
39
- | Individual income tax refunds | DTS Table V `v1/accounting/dts/income_tax_refunds_issued` (cash, checks + EFT, refundable credits included, Treasury Offset Program offsets excluded); MTS Table 4 refunds (budget basis: refundable credits above liability are outlays) | the two differ by tens of billions a year and peak in different months (DTS February, MTS April): name the basis | flow | $M |
40
- | Savings bond (Series I) rates | `v1/accounting/od/i_bonds_interest_rates` | one row per earning period and issue month back to 1998: the rate announced for new bonds is the row whose issue month falls in its own earning period; the composite rate has a 0% floor (May 2009, May 2015), so the published formula does not reproduce those rows; dates are `earning_period_start` (no `record_date`) | stock (a rate) | % |
41
- | Average interest rate on the debt | `v2/accounting/od/avg_interest_rates` | `security_desc` "Total Interest-bearing Debt", "Total Marketable" (these totals leave out TIPS and FRNs: weighting the component rates by MSPD amounts reproduces them only without those two [derived 2026-10-21]); the TIPS rate is the real coupon, without inflation compensation: not comparable with nominal rates | stock | % |
42
- | Treasury cash (TGA) | `v1/accounting/dts/operating_cash_balance` | see trap on 2022-04-18 | stock | $M |
43
- | Daily deposits and withdrawals | `v1/accounting/dts/deposits_withdrawals_operating_cash` | `transaction_type`, `transaction_catg` | flow | $M |
44
- | Auction results | `v1/accounting/od/auctions_query` | completed auctions (non-null `high_yield`); `original_security_term` to include reopenings; `inflation_index_security` No for nominal notes and bonds (TIPS are `security_type` Note too); use `bid_to_cover_ratio` as published (excludes SOMA) | event | mixed |
45
- | Exchange rates | `v1/accounting/od/rates_of_exchange` | latest `effective_date` per quarter | stock | foreign units per USD |
46
-
47
- ## Spec examples
48
- ```json
49
- {"description": "Net interest and average rates, FY2015-FY2025",
50
- "as_of": "2025-09-30",
51
- "datasets": [
52
- {"name": "mts9", "endpoint": "v1/accounting/mts/mts_table_9",
53
- "filter": {"record_date": {"gte": "2014-09-30"}, "record_calendar_month": "09"}},
54
- {"name": "rates", "endpoint": "v2/accounting/od/avg_interest_rates",
55
- "filter": {"record_date": {"gte": "2014-10-01"}, "security_desc": ["Total Interest-bearing Debt", "Total Marketable"]}}]}
56
- ```
57
- ```json
58
- {"description": "Debt to the penny, fiscal year ends 2015-2025", "as_of": "2025-09-30",
59
- "datasets": [{"name": "debt", "endpoint": "v2/accounting/od/debt_to_penny",
60
- "filter": {"record_date": {"gte": "2014-09-01"}}}]}
61
- ```
62
- Per dataset: `name` (file `<name>.csv`), `endpoint`, `filter` (bare value = eq, list = in, or
63
- `{"gte": ...}`; a string is raw API syntax), optional `fields`, `date_field` (some endpoints use
64
- `operation_date`, `effective_date` ...), `sort`, `allow_empty`. `as_of` adds `<date_field> <= as_of` to
65
- every dataset so reruns are reproducible; leave it out only for "latest" lookups.
66
-
67
- ## Data format and traps
68
- `fetch` writes `data/treasury/`: `<name>.csv` (API field names, values exactly as published, "null" ->
69
- empty), `fetch_spec.json` (query URLs, row counts, first and last date, labels, types, unit hints, SHA-256,
70
- route) and `README.md` (data dictionary with every code column's values). Codes stay text in the CSV, but a
71
- reader may turn them into numbers: `compute` keeps codes with a leading zero ("09") as text, but reads a
72
- column whose codes all look like numbers ("1.10", "2.13") as numbers (1.1, 2.13): check such a column before
73
- filtering. The API's own CSV downloads put an apostrophe before negative amounts; `fetch` and `ingest` write
74
- them without it.
75
- - **Units differ:** MTS tables 1-9, Debt to the Penny, interest expense are dollars; DTS, MSPD (`*_mil_amt`)
76
- and the long MTS series (`mts_receipts_outlays_deficit_surplus.mil_amt`) millions: read the field name;
77
- percentage fields are already percent. **Signs:** MTS Table 1 shows a deficit as positive, Table 5 negative.
78
- - **Stocks vs flows:** debt, cash, rates take the end-of-period value or the average (`compute` `to_fiscal`
79
- with `how` "last" or "mean"); receipts, outlays, deficits, interest sum months (`how` "sum", check
80
- `complete`) or read the September fiscal-year-to-date value. Never sum year-to-date values or stock levels.
81
- - **Hierarchies double count:** MTS mixes headers (S), details (D) and totals (T); choose one level and prove
82
- it: one row per key, and the rows add to the published total. Table 4's D rows do not sum to the
83
- total (use Table 9). The same letter can be a value of two code columns: filter on the column it is in.
84
- - **One release, several periods:** MTS Table 1 holds the prior and current fiscal year blocks
85
- (`sequence_number_cd` 1.x and 2.x), each with its months and a "Year-to-Date" row; its only amount columns
86
- are `current_month_gross_rcpt_amt`, `_gross_outly_amt`, `_dfct_sur_amt` (positive = deficit). Tables 9
87
- and others carry `current_fytd_*` / `prior_fytd_*` columns instead.
88
- - **Dates without a record:** Debt to the Penny and DTS have rows only on business days. For a requested
89
- weekend or holiday (January 20, 2025 was both Inauguration Day and a federal holiday), use the last record
90
- before it (its close equals the next statement's opening balance) and say so; count calendar days from
91
- the requested date and business days from the records, and name which one a per-day figure uses.
92
- - **Net vs gross receipts:** MTS receipts are net of refunds. When refunds are large the two can move in
93
- opposite directions (FY2026 customs: gross up 57 percent, net down 11 percent after $145 billion of tariff
94
- refunds): show gross, refunds and net (Table 4) and say which one the headline uses.
95
- - **Latest release wins:** MTS releases repeat and revise earlier months: build monthly series from the latest
96
- `record_date`, full years from September releases; the next September restates the year (FY2024's deficit
97
- moved by $16 billion).
98
- - **`fields=` that drops row-identity columns makes the API group and sum rows**; `fetch` compares row
99
- counts with and without it and stops.
100
- - **Filter values:** exact text, case-sensitive; a malformed date returns no rows, not an error; values with
101
- `&` or `,` (and parentheses inside an `in` list; `eq` with parentheses works, verified 2026-10) are
102
- mishandled by the API, so `fetch` applies those conditions locally (recorded as
103
- `local_filter`). A filter matching nothing is an `invalid_request` error unless `allow_empty`.
104
- - **Format changes:** DTS operating cash changed on 2022-04-18 (before: the TGA/FRA row's `close_today_bal`;
105
- after: the "Closing Balance" row's `open_today_bal`); DTS categories are renamed over time. Debt to the
106
- Penny's held-by-public and intragovernmental fields are null before 2005-03-31.
107
- - **Fiscal years** run October 1 to September 30, named for the year they end (`compute` `fiscal_year`); the
108
- September MTS comes out mid-October. Find the latest complete period from the data (`request_schema` search
109
- on the endpoint gives its last row), not from memory;
110
- label partial years and compare them with the same months a year earlier.
111
- - **Real dollars and GDP:** the spec field `"context": [{"kind": "cpi", "start": 2016}]` (or `"gdp"`; `start`
112
- is the first fiscal year) writes `context_cpi.csv` / `context_gdp.csv` and `context_sources.json` (FRED, then
113
- BLS or World Bank). Make a fiscal-year CPI with `compute` `to_fiscal` (`how` "mean") and apply it with
114
- `deflate`; fiscal-year GDP is the average of four quarterly SAARs, Oct-Sep (`to_fiscal`, `freq` "Q", `how`
115
- "mean"); the World Bank fallback is calendar years only and cannot give fiscal-year GDP. Incomplete periods
116
- are flagged: say provisional.
117
- - **Volume vs rate questions** ("more debt or higher rates?"): split the change exactly with the midpoint
118
- method: debt effect = (debt1 - debt0) x (rate0 + rate1) / 2, rate effect = (rate1 - rate0) x (debt0 + debt1)
119
- / 2; the two add up to the change (`compute` `derive`).
120
- - Analysis: build fiscal-year sums, growth and decompositions with `compute` on the CSVs in `data/treasury/`.
121
- - **Benchmark** each headline against the official statement for the same date (MTS, MSPD, DTS, Treasury's
122
- press release, CBO's Monthly Budget Review; for auctions, TreasuryDirect's results files
123
- `https://www.treasurydirect.gov/xml/R_YYYYMMDD_n.xml`, keyless, a separate system from Fiscal Data); when the table is the statement itself, check its identities
124
- (components add to the total; receipts - outlays = -deficit). Statement PDFs:
125
- `https://fiscaldata.treasury.gov/static-data/published-reports/mts/MonthlyTreasuryStatement_YYYYMM.pdf` and
126
- `.../dts/DailyTreasuryStatement_YYYYMMDD.pdf`; MSPD: `.../mspd-entire/MonthlyStatementPublicDebt_Entire_YYYYMM.pdf`. The fiscaldata.treasury.gov dataset pages draw their tables
127
- with JavaScript: a fetch tool sees no values there (use the API or the PDFs). The PDFs are compressed:
128
- a web fetch tool cannot read them; save the file and extract its text locally (pypdf). The API rows are
129
- the statement's own figures, so an API value equal to the PDF's is a transcription check, not an
130
- independent one. cbo.gov refuses scripted downloads (HTTP 403), and a browser pane may only download its
131
- PDF: when no one can open it, record CBO's Monthly Budget Review as "not checked" in benchmark.csv (with a
132
- data_needs entry), or ask the user to upload the PDF.
133
- - **Identity gaps:** in `mts_receipts_outlays_deficit_surplus`, receipts minus outlays misses the deficit line by
134
- a few million in some months (Sep 2022 by $10 million, Mar 2024 by $270 million, as published): use the
135
- deficit line for deficits, check an identity with a tolerance of a few hundred million, and tie fiscal-year
136
- totals to the September MTS.
137
- - **Coverage:** MTS Tables 1 to 9 start in March 2015, so FY2015 is their first full year; a filter from an
138
- earlier date returns rows from 2015 on without an error. For earlier years use
139
- `mts_receipts_outlays_deficit_surplus` (totals from FY1981) or OMB's Historical Tables through FRED
140
- (`FYOINT` net interest, `FYFSD` deficit, `FYONET` outlays, in millions), and say where the series join.
141
- FRED carries only those totals: a receipt or outlay line before FY2015 (customs duties, a function) comes from
142
- OMB's Historical Tables (Table 2.5 receipts by source, 3.2 outlays by function, 10.1 GDP; FY1940 on) through
143
- the omb pack (`historical_table`, any budget edition); each edition revises history, so name the edition.
144
-
145
- ## Access
146
- - No key, no registration, GET only, no documented rate limit (the client keeps 4 requests a second and
147
- backs off on 429/5xx). Pages of up to 10,000 rows; `fetch` pages and checks the row count against
148
- `total-count`.
149
- - `fetch` reuses `data/treasury/` when it already holds the same spec (`force: true` refetches). A filter that
150
- matches no rows or names an unknown field comes back as `invalid_request` (check values with `request_schema`
151
- search `"<endpoint> <filter> values"`); a bad endpoint or aggregation the API refuses, as `agency_rejected`.
152
- When the API cannot be reached (`agency_unavailable`: internet, VPN, proxy `HTTPS_PROXY`, a host that blocks
153
- `api.fiscaldata.treasury.gov`), tell the user, offer `manual_bundle`, and never invent or recall numbers.
154
- - Manual download: `manual_bundle` writes `manual_download/INSTRUCTIONS.md` with one CSV link per dataset
155
- (10,000 rows each; more pages with `page%5Bnumber%5D=2` saved as `<name>_2.csv` ...), curl and PowerShell
156
- scripts, and the dataset page whose Download button gives the whole table. Upload the CSV or ZIP files
157
- unchanged (not re-saved in Excel); `ingest` with the uploaded files or their folder applies the spec's
158
- filter locally, strips the apostrophe guard, drops duplicate rows and warns about a missing page.
159
-
160
- ## Citation and terms
161
- "U.S. Department of the Treasury, Bureau of the Fiscal Service, Fiscal Data (https://fiscaldata.treasury.gov),
162
- <endpoints>; retrieved <date> through the Fiscal Data API." (exact line in `data/treasury/README.md`). Source
163
- line: "Analyst calculations using data from the Department of the Treasury, Bureau of the Fiscal Service,
164
- Monthly Treasury Statement (retrieved <date>)." Public domain: redistribution allowed; cite the retrieval
165
- date because Treasury revises some series.
1
+ # U.S. Treasury Fiscal Data (fiscaldata.treasury.gov)
2
+ Depth: deep. Key: none. Official federal finance statistics from the Bureau of the Fiscal Service: debt,
3
+ deficits, receipts and outlays (Monthly Treasury Statement), Treasury cash (Daily Treasury Statement),
4
+ interest expense and average rates on the debt, the debt limit, auctions, exchange rates; 185 endpoints.
5
+
6
+ ## When to use
7
+ - National debt (total, held by the public, intragovernmental; daily since 1993, yearly since 1790), debt by
8
+ security type, debt subject to the limit; monthly and fiscal-year receipts, outlays and deficits; receipts
9
+ by source, outlays by function and by agency; gross interest expense, net interest, average interest rates
10
+ on outstanding debt; the TGA cash balance and daily deposits and withdrawals; auction results; exchange
11
+ rates for federal reporting; gifts to reduce the debt; savings bonds; buybacks.
12
+ - Not here: market yields and the daily par yield curve (treasury-yields); GDP and CPI (bea, bls, fred; or
13
+ the spec's `context` field here, for real dollars and "% of GDP"); budget projections (CBO); historical tables in
14
+ % of GDP and the President's budget (OMB); who holds the debt by country (treasury-tic, not Fiscal Data);
15
+ state and local finances (Census).
16
+ - Deliver data plus a short answer by default; a report only when asked (see `guide`).
17
+
18
+ ## Endpoints and datasets
19
+ Base `https://api.fiscaldata.treasury.gov/services/api/fiscal_service/` + a path with a fixed version (v1 or
20
+ v2: the other returns 404). `request_schema` with `search: "interest expense"` searches the live catalog
21
+ (falls back to the bundled `catalog.json`: a snapshot of the live catalog plus this guidance); `search:
22
+ "<endpoint>"` gives fields, types, units, row count, first and last row; `search: "<endpoint> {"record_date":
23
+ "2026-09-30"} values"` shows which values each code and description column holds; `request_schema` with
24
+ `names: ["dataset"]` lists the curated rows below. Full question-to-endpoint table: `docs/datasets.md`; API rules,
25
+ field meanings and the numbered gotchas: `docs/api_guide.md`; framing and conventions: `docs/report_patterns.md`.
26
+
27
+ | Question | Endpoint | Rows to use | Stock/flow | Units |
28
+ |---|---|---|---|---|
29
+ | Total debt, held by the public, intragovernmental (daily) | `v2/accounting/od/debt_to_penny` | one row per business day | stock | $ |
30
+ | Debt at fiscal year end since 1790 | `v2/accounting/od/debt_outstanding` | one row per year | stock | $ |
31
+ | Debt by security type (monthly) | `v1/debt/mspd/mspd_table_1` | `security_type_desc`, `security_class_desc`; skip "Total" rows | stock | $M |
32
+ | Debt subject to the limit | `v1/debt/mspd/mspd_table_2`, `v1/accounting/dts/debt_subject_to_limit` | `debt_catg_desc` | stock | $M |
33
+ | Monthly receipts, outlays, deficit since FY1981 | `v1/accounting/mts/mts_receipts_outlays_deficit_surplus` | `amt_category` | flow | $M |
34
+ | Receipts, outlays, deficit since FY2015 | `v1/accounting/mts/mts_table_1` | months: latest `record_date`, `record_type_cd` MTH; full FY: the September release's "Year-to-Date" row (`record_type_cd` SL, `data_type_cd` T) in the current-year block (`sequence_number_cd` 2.13; 1.13 is the prior year) | flow | $ |
35
+ | Receipts by source, outlays by function | `v1/accounting/mts/mts_table_9` | September `record_date`; `data_type_cd` D components, T "Total" | flow | $ |
36
+ | Outlays by agency, bureau, program | `v1/accounting/mts/mts_table_5` | `record_type_cd` A agency totals; D rows sum to "Total Outlays". A program account is a `classification_desc` line under its agency (Medicaid: "Grants to States for Medicaid" under HHS, `record_type_cd` P; FY2019 $409.4 billion = OMB Table 8.5): fetch the agency's rows and match the line by name (`--values` lists up to 200 lines per column under a narrow filter) | flow | $ |
37
+ | Gross interest expense | `v2/accounting/od/interest_expense` | all rows (detail only) sum to the total; MTS leaves out the GAS "Restoration of Interest" line (FY2025 on); TIPS lines include inflation compensation, a separate GAS "Inflation Compensation" line is not TIPS (docs/datasets.md) | flow | $ |
38
+ | Outlays by budget function (Social Security 650, Medicare 570, defense 050, net interest 900 ...) | MTS Table 9 (`v1/accounting/mts/mts_table_9`) | function rows add to total outlays; a function is not CBO's program measure (Social Security 650 includes administration; CBO reports benefits; Medicare 570 is already net of the premiums and other offsetting receipts credited to it, and CBO's "net Medicare" also nets a few receipts outside the function) | flow | $M |
39
+ | Individual income tax refunds | DTS Table V `v1/accounting/dts/income_tax_refunds_issued` (cash, checks + EFT, refundable credits included, Treasury Offset Program offsets excluded); MTS Table 4 refunds (budget basis: refundable credits above liability are outlays) | the two differ by tens of billions a year and peak in different months (DTS February, MTS April): name the basis | flow | $M |
40
+ | Savings bond (Series I) rates | `v1/accounting/od/i_bonds_interest_rates` | one row per earning period and issue month back to 1998: the rate announced for new bonds is the row whose issue month falls in its own earning period; the composite rate has a 0% floor (May 2009, May 2015), so the published formula does not reproduce those rows; dates are `earning_period_start` (no `record_date`) | stock (a rate) | % |
41
+ | Average interest rate on the debt | `v2/accounting/od/avg_interest_rates` | `security_desc` "Total Interest-bearing Debt", "Total Marketable" (these totals leave out TIPS and FRNs: weighting the component rates by MSPD amounts reproduces them only without those two [derived 2026-10-21]); the TIPS rate is the real coupon, without inflation compensation: not comparable with nominal rates | stock | % |
42
+ | Treasury cash (TGA) | `v1/accounting/dts/operating_cash_balance` | see trap on 2022-04-18 | stock | $M |
43
+ | Daily deposits and withdrawals | `v1/accounting/dts/deposits_withdrawals_operating_cash` | `transaction_type`, `transaction_catg` | flow | $M |
44
+ | Auction results | `v1/accounting/od/auctions_query` | completed auctions (non-null `high_yield`); `original_security_term` to include reopenings; `inflation_index_security` No for nominal notes and bonds (TIPS are `security_type` Note too); use `bid_to_cover_ratio` as published (excludes SOMA) | event | mixed |
45
+ | Exchange rates | `v1/accounting/od/rates_of_exchange` | latest `effective_date` per quarter | stock | foreign units per USD |
46
+
47
+ ## Spec examples
48
+ ```json
49
+ {"description": "Net interest and average rates, FY2015-FY2025",
50
+ "as_of": "2025-09-30",
51
+ "datasets": [
52
+ {"name": "mts9", "endpoint": "v1/accounting/mts/mts_table_9",
53
+ "filter": {"record_date": {"gte": "2014-09-30"}, "record_calendar_month": "09"}},
54
+ {"name": "rates", "endpoint": "v2/accounting/od/avg_interest_rates",
55
+ "filter": {"record_date": {"gte": "2014-10-01"}, "security_desc": ["Total Interest-bearing Debt", "Total Marketable"]}}]}
56
+ ```
57
+ ```json
58
+ {"description": "Debt to the penny, fiscal year ends 2015-2025", "as_of": "2025-09-30",
59
+ "datasets": [{"name": "debt", "endpoint": "v2/accounting/od/debt_to_penny",
60
+ "filter": {"record_date": {"gte": "2014-09-01"}}}]}
61
+ ```
62
+ Per dataset: `name` (file `<name>.csv`), `endpoint`, `filter` (bare value = eq, list = in, or
63
+ `{"gte": ...}`; a string is raw API syntax), optional `fields`, `date_field` (some endpoints use
64
+ `operation_date`, `effective_date` ...), `sort`, `allow_empty`. `as_of` adds `<date_field> <= as_of` to
65
+ every dataset so reruns are reproducible; leave it out only for "latest" lookups.
66
+
67
+ ## Data format and traps
68
+ `fetch` writes `data/treasury/`: `<name>.csv` (API field names, values exactly as published, "null" ->
69
+ empty), `fetch_spec.json` (query URLs, row counts, first and last date, labels, types, unit hints, SHA-256,
70
+ route) and `README.md` (data dictionary with every code column's values). Codes stay text in the CSV, but a
71
+ reader may turn them into numbers: `compute` keeps codes with a leading zero ("09") as text, but reads a
72
+ column whose codes all look like numbers ("1.10", "2.13") as numbers (1.1, 2.13): check such a column before
73
+ filtering. The API's own CSV downloads put an apostrophe before negative amounts; `fetch` and `ingest` write
74
+ them without it.
75
+ - **Units differ:** MTS tables 1-9, Debt to the Penny, interest expense are dollars; DTS, MSPD (`*_mil_amt`)
76
+ and the long MTS series (`mts_receipts_outlays_deficit_surplus.mil_amt`) millions: read the field name;
77
+ percentage fields are already percent. **Signs:** MTS Table 1 shows a deficit as positive, Table 5 negative.
78
+ - **Stocks vs flows:** debt, cash, rates take the end-of-period value or the average (`compute` `to_fiscal`
79
+ with `how` "last" or "mean"); receipts, outlays, deficits, interest sum months (`how` "sum", check
80
+ `complete`) or read the September fiscal-year-to-date value. Never sum year-to-date values or stock levels.
81
+ - **Hierarchies double count:** MTS mixes headers (S), details (D) and totals (T); choose one level and prove
82
+ it: one row per key, and the rows add to the published total. Table 4's D rows do not sum to the
83
+ total (use Table 9). The same letter can be a value of two code columns: filter on the column it is in.
84
+ - **One release, several periods:** MTS Table 1 holds the prior and current fiscal year blocks
85
+ (`sequence_number_cd` 1.x and 2.x), each with its months and a "Year-to-Date" row; its only amount columns
86
+ are `current_month_gross_rcpt_amt`, `_gross_outly_amt`, `_dfct_sur_amt` (positive = deficit). Tables 9
87
+ and others carry `current_fytd_*` / `prior_fytd_*` columns instead.
88
+ - **Dates without a record:** Debt to the Penny and DTS have rows only on business days. For a requested
89
+ weekend or holiday (January 20, 2025 was both Inauguration Day and a federal holiday), use the last record
90
+ before it (its close equals the next statement's opening balance) and say so; count calendar days from
91
+ the requested date and business days from the records, and name which one a per-day figure uses.
92
+ - **Net vs gross receipts:** MTS receipts are net of refunds. When refunds are large the two can move in
93
+ opposite directions (FY2026 customs: gross up 57 percent, net down 11 percent after $145 billion of tariff
94
+ refunds): show gross, refunds and net (Table 4) and say which one the headline uses.
95
+ - **Payment timing shifts:** when the first day of a month falls on a weekend or holiday, payments due that day
96
+ (Medicare Advantage and Part D plans, SSI, veterans' benefits, military pay) are made in the prior month. When
97
+ that day is October 1 they move into the prior fiscal year, by tens of billions of dollars.
98
+ Check October 1 at both ends of a year-over-year or multi-year comparison; if either year gained or lost
99
+ payments, adjust with the monthly rows (or say so) and name the shift in the answer, as CBO does.
100
+ - **Latest release wins:** MTS releases repeat and revise earlier months: build monthly series from the latest
101
+ `record_date`, full years from September releases; the next September restates the year (FY2024's deficit
102
+ moved by $16 billion).
103
+ - **`fields=` that drops row-identity columns makes the API group and sum rows**; `fetch` compares row
104
+ counts with and without it and stops.
105
+ - **Filter values:** exact text, case-sensitive; a malformed date returns no rows, not an error; values with
106
+ `&` or `,` (and parentheses inside an `in` list; `eq` with parentheses works, verified 2026-10) are
107
+ mishandled by the API, so `fetch` applies those conditions locally (recorded as
108
+ `local_filter`). A filter matching nothing is an `invalid_request` error unless `allow_empty`.
109
+ - **Format changes:** DTS operating cash changed on 2022-04-18 (before: the TGA/FRA row's `close_today_bal`;
110
+ after: the "Closing Balance" row's `open_today_bal`); DTS categories are renamed over time. Debt to the
111
+ Penny's held-by-public and intragovernmental fields are null before 2005-03-31.
112
+ - **Fiscal years** run October 1 to September 30, named for the year they end (`compute` `fiscal_year`); the
113
+ September MTS comes out mid-October. Find the latest complete period from the data (`request_schema` search
114
+ on the endpoint gives its last row), not from memory;
115
+ label partial years and compare them with the same months a year earlier.
116
+ - **Real dollars and GDP:** the spec field `"context": [{"kind": "cpi", "start": 2016}]` (or `"gdp"`; `start`
117
+ is the first fiscal year) writes `context_cpi.csv` / `context_gdp.csv` and `context_sources.json` (FRED, then
118
+ BLS or World Bank). Make a fiscal-year CPI with `compute` `to_fiscal` (`how` "mean") and apply it with
119
+ `deflate`; fiscal-year GDP is the average of four quarterly SAARs, Oct-Sep (`to_fiscal`, `freq` "Q", `how`
120
+ "mean"); the World Bank fallback is calendar years only and cannot give fiscal-year GDP. Incomplete periods
121
+ are flagged: say provisional.
122
+ - **Volume vs rate questions** ("more debt or higher rates?"): split the change exactly with the midpoint
123
+ method: debt effect = (debt1 - debt0) x (rate0 + rate1) / 2, rate effect = (rate1 - rate0) x (debt0 + debt1)
124
+ / 2; the two add up to the change (`compute` `derive`).
125
+ - Analysis: build fiscal-year sums, growth and decompositions with `compute` on the CSVs in `data/treasury/`.
126
+ - **Benchmark** each headline against the official statement for the same date (MTS, MSPD, DTS, Treasury's
127
+ press release, CBO's Monthly Budget Review; for auctions, TreasuryDirect's results files
128
+ `https://www.treasurydirect.gov/xml/R_YYYYMMDD_n.xml`, keyless, a separate system from Fiscal Data); when the table is the statement itself, check its identities
129
+ (components add to the total; receipts - outlays = -deficit). Statement PDFs:
130
+ `https://fiscaldata.treasury.gov/static-data/published-reports/mts/MonthlyTreasuryStatement_YYYYMM.pdf` and
131
+ `.../dts/DailyTreasuryStatement_YYYYMMDD.pdf`; MSPD: `.../mspd-entire/MonthlyStatementPublicDebt_Entire_YYYYMM.pdf`. The fiscaldata.treasury.gov dataset pages draw their tables
132
+ with JavaScript: a fetch tool sees no values there (use the API or the PDFs). The PDFs are compressed:
133
+ a web fetch tool cannot read them; save the file and extract its text locally (pypdf). The API rows are
134
+ the statement's own figures, so an API value equal to the PDF's is a transcription check, not an
135
+ independent one. cbo.gov refuses scripted downloads (HTTP 403), and a browser pane may only download its
136
+ PDF: when no one can open it, record CBO's Monthly Budget Review as "not checked" in benchmark.csv (with a
137
+ data_needs entry), or ask the user to upload the PDF.
138
+ - **Identity gaps:** in `mts_receipts_outlays_deficit_surplus`, receipts minus outlays misses the deficit line by
139
+ a few million in some months (Sep 2022 by $10 million, Mar 2024 by $270 million, as published): use the
140
+ deficit line for deficits, check an identity with a tolerance of a few hundred million, and tie fiscal-year
141
+ totals to the September MTS.
142
+ - **Coverage:** MTS Tables 1 to 9 start in March 2015, so FY2015 is their first full year; a filter from an
143
+ earlier date returns rows from 2015 on without an error. For earlier years use
144
+ `mts_receipts_outlays_deficit_surplus` (totals from FY1981) or OMB's Historical Tables through FRED
145
+ (`FYOINT` net interest, `FYFSD` deficit, `FYONET` outlays, in millions), and say where the series join.
146
+ FRED carries only those totals: a receipt or outlay line before FY2015 (customs duties, a function) comes from
147
+ OMB's Historical Tables (Table 2.5 receipts by source, 3.2 outlays by function, 10.1 GDP; FY1940 on) through
148
+ the omb pack (`historical_table`, any budget edition); each edition revises history, so name the edition.
149
+
150
+ ## Access
151
+ - No key, no registration, GET only, no documented rate limit (the client keeps 4 requests a second and
152
+ backs off on 429/5xx). Pages of up to 10,000 rows; `fetch` pages and checks the row count against
153
+ `total-count`.
154
+ - `fetch` reuses `data/treasury/` when it already holds the same spec (`force: true` refetches). A filter that
155
+ matches no rows or names an unknown field comes back as `invalid_request` (check values with `request_schema`
156
+ search `"<endpoint> <filter> values"`); a bad endpoint or aggregation the API refuses, as `agency_rejected`.
157
+ When the API cannot be reached (`agency_unavailable`: internet, VPN, proxy `HTTPS_PROXY`, a host that blocks
158
+ `api.fiscaldata.treasury.gov`), tell the user, offer `manual_bundle`, and never invent or recall numbers.
159
+ - Manual download: `manual_bundle` writes `manual_download/INSTRUCTIONS.md` with one CSV link per dataset
160
+ (10,000 rows each; more pages with `page%5Bnumber%5D=2` saved as `<name>_2.csv` ...), curl and PowerShell
161
+ scripts, and the dataset page whose Download button gives the whole table. Upload the CSV or ZIP files
162
+ unchanged (not re-saved in Excel); `ingest` with the uploaded files or their folder applies the spec's
163
+ filter locally, strips the apostrophe guard, drops duplicate rows and warns about a missing page.
164
+
165
+ ## Citation and terms
166
+ "U.S. Department of the Treasury, Bureau of the Fiscal Service, Fiscal Data (https://fiscaldata.treasury.gov),
167
+ <endpoints>; retrieved <date> through the Fiscal Data API." (exact line in `data/treasury/README.md`). Source
168
+ line: "Analyst calculations using data from the Department of the Treasury, Bureau of the Fiscal Service,
169
+ Monthly Treasury Statement (retrieved <date>)." Public domain: redistribution allowed; cite the retrieval
170
+ date because Treasury revises some series.
@@ -0,0 +1,77 @@
1
+ {
2
+ "base_url": "https://ticdata.treasury.gov/resource-center/data-chart-center/tic/Documents",
3
+ "timeout": 60,
4
+ "endpoints": {
5
+ "major_foreign_holders": {
6
+ "path": "/slt_table5.txt",
7
+ "method": "GET",
8
+ "description": "Major Foreign Holders of Treasury Securities (SLT Table 5): holdings by country, the latest 13 months, billions of dollars, plus All Other, Grand Total and the foreign-official split (bills, bonds and notes). One row per country and month.",
9
+ "params": {
10
+ "country": {
11
+ "in": "spec",
12
+ "desc": "keep only these rows: a country name as published (Japan; China, Mainland; Korea, South), or a list; case-insensitive. Omit for every row."
13
+ }
14
+ },
15
+ "records": "$tsv",
16
+ "header_row": 6,
17
+ "paging": {
18
+ "type": "none"
19
+ },
20
+ "max_rows": 10000
21
+ },
22
+ "major_foreign_holders_history": {
23
+ "path": "/mfhhis01.txt",
24
+ "method": "GET",
25
+ "description": "Major Foreign Holders history (mfhhis01.txt): the same table for every month from March 2000 through the last completed year, billions of dollars, one row per country and month. Series breaks are marked by footnotes in the file.",
26
+ "params": {
27
+ "country": {
28
+ "in": "spec",
29
+ "desc": "keep only these rows (a name as published, or a list; case-insensitive)"
30
+ },
31
+ "from": {
32
+ "in": "spec",
33
+ "desc": "first month to keep, YYYY-MM"
34
+ },
35
+ "to": {
36
+ "in": "spec",
37
+ "desc": "last month to keep, YYYY-MM"
38
+ },
39
+ "include_comparison": {
40
+ "in": "spec",
41
+ "desc": "true keeps the previous-series value of a series-break month (June 2002-2011, March 2000), marked comparison_only; default false"
42
+ }
43
+ },
44
+ "records": "$tsv",
45
+ "header_row": 0,
46
+ "paging": {
47
+ "type": "none"
48
+ },
49
+ "max_rows": 100000
50
+ },
51
+ "holdings_by_country": {
52
+ "path": "/slt_table1.txt",
53
+ "method": "GET",
54
+ "description": "SLT Table 1: U.S. long-term securities held by foreign residents, by country and month (from September 2011), millions of dollars: holdings, net U.S. sales and valuation change for Treasuries, agency bonds, corporate and other bonds, and equities.",
55
+ "params": {
56
+ "country": {
57
+ "in": "spec",
58
+ "desc": "keep only these countries (name as published, or the 5-digit TIC country code; a list works); case-insensitive"
59
+ },
60
+ "from": {
61
+ "in": "spec",
62
+ "desc": "first month to keep, YYYY-MM"
63
+ },
64
+ "to": {
65
+ "in": "spec",
66
+ "desc": "last month to keep, YYYY-MM"
67
+ }
68
+ },
69
+ "records": "$tsv",
70
+ "header_row": 9,
71
+ "paging": {
72
+ "type": "none"
73
+ },
74
+ "max_rows": 200000
75
+ }
76
+ }
77
+ }
@@ -0,0 +1,89 @@
1
+ {
2
+ "id": "treasury-tic",
3
+ "title": "Treasury International Capital (TIC): foreign holdings of U.S. Treasury and other securities",
4
+ "agency": "U.S. Department of the Treasury and Federal Reserve Board",
5
+ "depth": "standard",
6
+ "domains": [
7
+ "federal debt",
8
+ "international finance",
9
+ "capital flows"
10
+ ],
11
+ "keywords": [
12
+ "tic",
13
+ "treasury international capital",
14
+ "foreign holders",
15
+ "major foreign holders",
16
+ "foreign holdings of treasuries",
17
+ "who owns the debt",
18
+ "who holds the debt",
19
+ "china holdings",
20
+ "japan holdings",
21
+ "foreign official",
22
+ "foreign central banks",
23
+ "slt",
24
+ "cross-border securities",
25
+ "foreign purchases of u.s. securities",
26
+ "net foreign sales",
27
+ "capital flows",
28
+ "foreign-held debt"
29
+ ],
30
+ "questions": [
31
+ "how much U.S. Treasury debt does China hold",
32
+ "largest foreign holders of Treasury securities",
33
+ "Japan's Treasury holdings over time",
34
+ "foreign official holdings of Treasury bills and bonds",
35
+ "foreign holdings of U.S. corporate bonds and stocks by country",
36
+ "net foreign purchases of Treasuries by country"
37
+ ],
38
+ "homepage": "https://home.treasury.gov/data/treasury-international-capital-tic-system",
39
+ "terms_url": "https://home.treasury.gov/subfooter/site-policies-and-notices",
40
+ "auth": {
41
+ "env": null,
42
+ "required": "none",
43
+ "placement": "none",
44
+ "signup_url": null,
45
+ "echoes_key": false
46
+ },
47
+ "limits": {
48
+ "rps": 2,
49
+ "burst": 4,
50
+ "max_rows": 200000
51
+ },
52
+ "routes": {
53
+ "api": {
54
+ "base": "https://ticdata.treasury.gov/resource-center/data-chart-center/tic/Documents",
55
+ "probe": "https://ticdata.treasury.gov/resource-center/data-chart-center/tic/Documents/slt_table5.txt",
56
+ "hosts": [
57
+ "ticdata.treasury.gov"
58
+ ]
59
+ },
60
+ "manual": {
61
+ "how": "Open the text files in a browser and save them: https://ticdata.treasury.gov/resource-center/data-chart-center/tic/Documents/slt_table5.txt (latest 13 months), .../mfhhis01.txt (history from 2000) or .../slt_table1.txt (long-term securities by country). Upload the saved .txt file with ingest."
62
+ }
63
+ },
64
+ "cache": {
65
+ "mode": "run_only",
66
+ "ttl_hours": null,
67
+ "why": "Monthly releases revise the last months; data/ is reused within a run."
68
+ },
69
+ "redistribution": {
70
+ "mode": "allowed",
71
+ "why": "U.S. government work in the public domain (17 U.S.C. 105)."
72
+ },
73
+ "notices": [],
74
+ "retention": null,
75
+ "citation": "U.S. Department of the Treasury, Treasury International Capital (TIC) System, {dataset}, ticdata.treasury.gov, retrieved {retrieved_long}.",
76
+ "audit_hooks": [],
77
+ "clarify": [
78
+ "Which measure? Major Foreign Holders counts all Treasury securities (bills, bonds and notes) in billions; SLT Table 1 counts long-term securities only (no bills), in millions, and also covers agency, corporate bonds and stocks. Default: Major Foreign Holders for 'how much debt does X hold'.",
79
+ "Which months? slt_table5 has the latest 13 months; mfhhis01 has March 2000 through the last full year. Default: the latest month, with the year-earlier month for comparison."
80
+ ],
81
+ "formats": [
82
+ "txt"
83
+ ],
84
+ "aliases": [
85
+ "TIC",
86
+ "Treasury International Capital",
87
+ "Major Foreign Holders"
88
+ ]
89
+ }