finance_query/models/economic/
auctions.rs

1//! US Treasury securities auction models.
2//!
3//! Served through the [`Capability::ECONOMIC`](crate::Capability::ECONOMIC)
4//! route from US Treasury FiscalData. [`TreasuryAuction`] covers auctions that
5//! have been announced or settled; [`UpcomingAuction`] covers the announced
6//! schedule ahead of the auction date.
7
8use serde::{Deserialize, Serialize};
9
10/// One US Treasury securities auction.
11///
12/// Rows exist from announcement onwards, so an auction whose date has not
13/// passed carries its terms (offering amount, maturity) with every result
14/// field still `None`.
15///
16/// Bills and coupon securities report their price differently: a bill prices
17/// off [`high_discnt_rate`](Self::high_discnt_rate) and
18/// [`high_investment_rate`](Self::high_investment_rate) and leaves
19/// [`high_yield`](Self::high_yield) unset, while notes and bonds do the
20/// reverse.
21#[derive(Debug, Clone, Default, Serialize, Deserialize)]
22#[non_exhaustive]
23pub struct TreasuryAuction {
24    /// Date the row was published (`YYYY-MM-DD`).
25    pub record_date: String,
26    /// CUSIP of the security offered.
27    pub cusip: String,
28    /// Security class (`"Bill"`, `"Note"`, `"Bond"`, …).
29    pub security_type: String,
30    /// Term as Treasury states it (e.g. `"13-Week"`, `"29-Year 11-Month"`).
31    pub security_term: String,
32    /// Date the auction was held (`YYYY-MM-DD`).
33    pub auction_date: String,
34    /// Date the security settles (`YYYY-MM-DD`).
35    pub issue_date: String,
36    /// Date the security matures (`YYYY-MM-DD`).
37    pub maturity_date: String,
38    /// Whether the auction reopens an existing security rather than issuing a
39    /// new one.
40    pub reopening: Option<bool>,
41    /// Auction pricing method (e.g. `"Single-Price"`).
42    pub auction_format: Option<String>,
43    /// Coupon rate (%), for coupon-bearing securities.
44    pub int_rate: Option<f64>,
45    /// Par amount offered (US dollars).
46    pub offering_amt: Option<f64>,
47    /// Par amount bid across all bidders (US dollars).
48    pub total_tendered: Option<f64>,
49    /// Par amount awarded across all bidders (US dollars).
50    pub total_accepted: Option<f64>,
51    /// Total tendered divided by total accepted, the standard demand gauge.
52    pub bid_to_cover_ratio: Option<f64>,
53    /// Highest accepted yield (%), for notes and bonds.
54    pub high_yield: Option<f64>,
55    /// Highest accepted discount rate (%), for bills.
56    pub high_discnt_rate: Option<f64>,
57    /// Coupon-equivalent yield of the high discount rate (%), for bills.
58    pub high_investment_rate: Option<f64>,
59    /// Price per $100 par at the highest accepted bid.
60    pub high_price: Option<f64>,
61    /// Par amount awarded to primary dealers (US dollars).
62    pub primary_dealer_accepted: Option<f64>,
63    /// Par amount awarded to direct bidders (US dollars).
64    pub direct_bidder_accepted: Option<f64>,
65    /// Par amount awarded to indirect bidders (US dollars).
66    pub indirect_bidder_accepted: Option<f64>,
67    /// Par amount awarded on competitive bids (US dollars).
68    pub comp_accepted: Option<f64>,
69    /// Par amount awarded on non-competitive bids (US dollars).
70    pub noncomp_accepted: Option<f64>,
71    /// Par amount awarded to the Federal Reserve's System Open Market Account
72    /// (US dollars).
73    pub soma_accepted: Option<f64>,
74}
75
76/// A US Treasury auction that has been scheduled but not yet held.
77///
78/// Treasury announces terms in stages, so [`offering_amt`](Self::offering_amt)
79/// is unset until the formal announcement lands.
80#[derive(Debug, Clone, Default, Serialize, Deserialize)]
81#[non_exhaustive]
82pub struct UpcomingAuction {
83    /// Date the schedule was published (`YYYY-MM-DD`).
84    pub record_date: String,
85    /// Security class (`"Bill"`, `"Note"`, `"Bond"`, …).
86    pub security_type: String,
87    /// Term as Treasury states it (e.g. `"13-Week"`).
88    pub security_term: String,
89    /// CUSIP of the security to be offered.
90    pub cusip: String,
91    /// Whether the auction reopens an existing security.
92    pub reopening: Option<bool>,
93    /// Par amount to be offered (US dollars), once announced.
94    pub offering_amt: Option<f64>,
95    /// Date Treasury announces the auction's terms (`YYYY-MM-DD`).
96    pub announcement_date: String,
97    /// Date the auction will be held (`YYYY-MM-DD`).
98    pub auction_date: String,
99    /// Date the security will settle (`YYYY-MM-DD`).
100    pub issue_date: String,
101}
102
103/// Which auctions [`EconomicCatalog::treasury_auctions`] should return.
104///
105/// Every field is optional; the default asks for the most recent auctions of
106/// every type. Build one with [`TreasuryAuctionQuery::new`] and the chainable
107/// setters.
108///
109/// [`EconomicCatalog::treasury_auctions`]: crate::domains::EconomicCatalog::treasury_auctions
110#[derive(Debug, Clone, Default, PartialEq, Eq)]
111#[non_exhaustive]
112pub struct TreasuryAuctionQuery {
113    /// Restrict to one security class (`"Bill"`, `"Note"`, `"Bond"`, …).
114    pub security_type: Option<String>,
115    /// Restrict to one term, spelled as Treasury spells it (e.g. `"13-Week"`).
116    pub security_term: Option<String>,
117    /// Earliest auction date to include (`YYYY-MM-DD`).
118    pub from: Option<String>,
119    /// Latest auction date to include (`YYYY-MM-DD`).
120    pub to: Option<String>,
121    /// Maximum auctions to return, newest first.
122    pub limit: Option<u32>,
123}
124
125impl TreasuryAuctionQuery {
126    /// An unrestricted query — the most recent auctions of every type.
127    pub fn new() -> Self {
128        Self::default()
129    }
130
131    /// Restrict to one security class.
132    pub fn security_type(mut self, security_type: impl Into<String>) -> Self {
133        self.security_type = Some(security_type.into());
134        self
135    }
136
137    /// Restrict to one security term.
138    pub fn security_term(mut self, security_term: impl Into<String>) -> Self {
139        self.security_term = Some(security_term.into());
140        self
141    }
142
143    /// Restrict auction dates to `[from, to]` (`YYYY-MM-DD`).
144    pub fn dates(mut self, from: Option<&str>, to: Option<&str>) -> Self {
145        self.from = from.map(str::to_string);
146        self.to = to.map(str::to_string);
147        self
148    }
149
150    /// Return at most `limit` auctions, newest first.
151    pub fn limit(mut self, limit: u32) -> Self {
152        self.limit = Some(limit);
153        self
154    }
155}
finance_query/models/economic/auctions.rs

finance_query/models/economic/
auctions.rs
