finance_query/models/filings/ownership.rs
1//! Ownership models parsed from primary-source SEC filings, plus two
2//! secondary-source models (congressional trades, fails-to-deliver) served
3//! through the same [`Capability::FILINGS`](crate::Capability::FILINGS)
4//! route. Unlike the aggregated holder summaries on
5//! [`Ticker`](crate::Ticker), [`InsiderTrade`] and [`InstitutionalHolding`]
6//! come straight from the filed XML — Forms 3/4/5 for insider activity and
7//! 13F-HR information tables for institutional positions. EDGAR is the only
8//! source for [`InstitutionalHolding`]; [`InsiderTrade`] also has Alpha
9//! Vantage and FMP fallbacks. Congressional trades has a keyless House +
10//! Senate fallback (features `housetrades` and `senatetrades`, merged into
11//! one combined provider — each row's `office` field says which chamber it
12//! came from); fails-to-deliver also has a keyless EDGAR fallback (feature
13//! `secftd`).
14
15use serde::{Deserialize, Serialize};
16
17/// One transaction line from a Form 3, 4, or 5.
18#[derive(Debug, Clone, Default, Serialize, Deserialize)]
19#[non_exhaustive]
20pub struct InsiderTrade {
21 /// Issuer's trading symbol, as filed.
22 pub symbol: Option<String>,
23 /// Issuer name, as filed.
24 pub issuer_name: Option<String>,
25 /// Reporting insider's name.
26 pub insider_name: Option<String>,
27 /// Reporting insider's CIK.
28 pub insider_cik: Option<String>,
29 /// Whether the insider is a director of the issuer.
30 pub is_director: bool,
31 /// Whether the insider is an officer of the issuer.
32 pub is_officer: bool,
33 /// Whether the insider holds 10% or more of a class of equity.
34 pub is_ten_percent_owner: bool,
35 /// Officer title, when one was filed.
36 pub officer_title: Option<String>,
37 /// Form the transaction was reported on (`"3"`, `"4"`, `"5"`).
38 pub form_type: Option<String>,
39 /// Accession number of the source filing.
40 pub accession_number: Option<String>,
41 /// URL of the source XML document.
42 pub url: Option<String>,
43 /// Security traded (e.g. `"Common Stock"`).
44 pub security_title: Option<String>,
45 /// Transaction date (`YYYY-MM-DD`).
46 pub transaction_date: Option<String>,
47 /// SEC transaction code (`"P"` purchase, `"S"` sale, `"M"` option exercise…).
48 pub transaction_code: Option<String>,
49 /// `"A"` if shares were acquired, `"D"` if disposed.
50 pub acquired_disposed: Option<String>,
51 /// Number of shares (or derivative units) transacted.
52 pub shares: Option<f64>,
53 /// Price per share, when reported.
54 pub price_per_share: Option<f64>,
55 /// Shares beneficially owned after the transaction.
56 pub shares_owned_after: Option<f64>,
57 /// Whether the line came from the derivative rather than non-derivative table.
58 pub is_derivative: bool,
59}
60
61/// One position from a 13F-HR information table.
62#[derive(Debug, Clone, Default, Serialize, Deserialize)]
63#[non_exhaustive]
64pub struct InstitutionalHolding {
65 /// Issuer name, as filed.
66 pub issuer_name: Option<String>,
67 /// Class of security (e.g. `"COM"`).
68 pub title_of_class: Option<String>,
69 /// CUSIP of the security.
70 pub cusip: Option<String>,
71 /// Market value as filed. Filings before 2023 report thousands of dollars;
72 /// later ones report whole dollars. The value is passed through unscaled.
73 pub value: Option<f64>,
74 /// Share or principal amount held.
75 pub shares: Option<f64>,
76 /// Whether `shares` is a share count (`"SH"`) or principal amount (`"PRN"`).
77 pub share_type: Option<String>,
78 /// `"CALL"` or `"PUT"` when the position is an option.
79 pub put_call: Option<String>,
80 /// Investment discretion (`"SOLE"`, `"DFND"`, `"OTR"`).
81 pub investment_discretion: Option<String>,
82 /// Shares over which the filer has sole voting authority.
83 pub voting_sole: Option<f64>,
84 /// Shares over which voting authority is shared.
85 pub voting_shared: Option<f64>,
86 /// Shares over which the filer has no voting authority.
87 pub voting_none: Option<f64>,
88 /// Accession number of the source filing.
89 pub accession_number: Option<String>,
90 /// Period the holdings are reported as of (`YYYY-MM-DD`).
91 pub report_date: Option<String>,
92}
93
94/// One legislator stock-trade disclosure filed under the STOCK Act.
95#[derive(Debug, Clone, Default, Serialize, Deserialize)]
96#[non_exhaustive]
97pub struct CongressionalTrade {
98 /// Ticker symbol traded.
99 pub symbol: Option<String>,
100 /// Legislator's first name.
101 pub first_name: Option<String>,
102 /// Legislator's last name.
103 pub last_name: Option<String>,
104 /// Office held (e.g. a House seat's office name).
105 pub office: Option<String>,
106 /// District, for House members.
107 pub district: Option<String>,
108 /// Transaction type (e.g. `"Purchase"`, `"Sale"`).
109 pub trade_type: Option<String>,
110 /// Reported transaction amount range (e.g. `"$1,001 - $15,000"`).
111 pub amount: Option<String>,
112 /// Description of the asset traded.
113 pub asset_description: Option<String>,
114 /// Date the transaction occurred (`YYYY-MM-DD`).
115 pub transaction_date: Option<String>,
116 /// Date the transaction was publicly disclosed (`YYYY-MM-DD`).
117 pub disclosure_date: Option<String>,
118 /// Link to the source disclosure filing.
119 pub link: Option<String>,
120}
121
122/// One SEC fails-to-deliver record for a settlement date.
123#[derive(Debug, Clone, Default, Serialize, Deserialize)]
124#[non_exhaustive]
125pub struct FailToDeliver {
126 /// Ticker symbol.
127 pub symbol: Option<String>,
128 /// Settlement date (`YYYY-MM-DD`).
129 pub date: Option<String>,
130 /// Number of shares that failed to deliver.
131 pub quantity: Option<f64>,
132 /// Closing price on the settlement date.
133 pub price: Option<f64>,
134 /// Security name.
135 pub name: Option<String>,
136 /// Additional description, when reported.
137 pub description: Option<String>,
138}