🇺🇸 us-stock — US Equities Data
Single Python module with multi-source fallback for US stocks. Mirror of cn-stock for the US market. Use whenever the user asks about a US ticker — fundamentals, holders, insiders, financials. For pure price/K-line on US tickers, this skill internally calls the paid TwelveData skill, so you get one consistent interface.
Architecture
your call → exports.py
├─ twelvedata (paid, primary) → realtime quote, time series
└─ yfinance (free, primary for fundamentals)
→ info, holders, insiders,
financials, news, options,
dividends, splits, earnings
Most functions return a uniform envelope:
{"ok": bool, "source": str, "data": <payload>, "error": str|None, "ts": int}
Exception: get_full_report(symbol) returns a combined dict of sub-results (quote/company/holders/insiders/earnings/news).
Quick Start
Preferred — use core.skill_tools (handles import isolation):
python3 - <<'EOF'
from core.skill_tools import _modules
us = _modules["us-stock"]
q = us.get_realtime_quote("AAPL")
print(q["data"]["last"], q["data"]["pct_change"], "%")
c = us.get_company_info("NVDA")
d = c["data"]
print(f"{d['name']} | mcap ${d['market_cap']/1e12:.2f}T | shares {d['shares_outstanding']/1e9:.2f}B")
full = us.get_full_report("MSFT")
print(full["company"]["data"]["sector"])
EOF
Fallback (single-skill scripts only):
python3 - <<'EOF'
import importlib.util as ilu
spec = ilu.spec_from_file_location("us_stock_mod", "/data/workspace/skills/us-stock/exports.py")
us = ilu.module_from_spec(spec); spec.loader.exec_module(us)
print(us.get_realtime_quote("AAPL")["data"])
EOF
⚠️ Do NOT use sys.path.insert + from exports import ... — cn-stock also defines exports.py and they will collide in the same process.
Function Map
| Function |
Returns |
Source |
get_realtime_quote(symbol) |
price, OHLC, change, 52w range, mcap |
twelvedata → yfinance fallback |
get_company_info(symbol) |
mcap, shares_outstanding, float_shares, pct_held_insiders, pct_held_institutions, sector, industry, business summary, valuation, margins, dividend, analyst targets |
yfinance.get_info |
get_institutional_holders(symbol, top=15) |
Top N institutional holders + value + pctChange |
yfinance |
get_mutualfund_holders(symbol, top=15) |
Top N mutual fund holders |
yfinance |
get_insider_transactions(symbol, limit=20) |
Recent Form 4 buys/sells |
yfinance |
get_financials(symbol, statement, period, max_periods=5) |
Income / Balance / Cashflow, annual or quarterly |
yfinance |
get_earnings(symbol, limit=8) |
Past + upcoming earnings dates with EPS est. vs actual |
yfinance |
get_dividends(symbol, limit=20) |
Historical dividends |
yfinance |
get_splits(symbol, limit=10) |
Historical splits |
yfinance |
get_news(symbol, limit=10) |
Recent news titles + summaries + URLs |
yfinance |
get_kline(symbol, interval, outputsize) |
OHLCV bars |
twelvedata → yfinance fallback |
get_recommendations(symbol, limit=12) |
Analyst rating buckets per period |
yfinance |
get_options_expirations(symbol) |
All available option expiry dates |
yfinance |
get_etf_holdings(symbol, top=15) |
ETF/fund top holdings + sector/asset weights (e.g. SPY/QQQ) |
yfinance.funds_data |
get_full_report(symbol) |
quote + company + institutional + insiders + earnings + news combined |
combo |
Symbol Format
Pure US ticker — no exchange suffix:
AAPL, MSFT, NVDA, GOOGL, TSLA
- Dual-class:
BRK.B, BRK-B, GOOG / GOOGL
- Both formats accepted; pass through as-is
TwelveData Reuse (important)
This skill does not register a separate TwelveData credential. It loads the existing TwelveData skill by explicit file path (/data/workspace/skills/twelvedata/exports.py) via importlib, avoiding exports.py name collisions with other skills.
Starchild's TwelveData billing covers these calls. If TwelveData fails, yfinance fallback kicks in automatically.
get_company_info Field Reference
Fields most useful for Telegram replies (all from yfinance):
| Field |
Meaning |
Notes |
market_cap |
总市值 (USD) |
divide by 1e9 → 十亿, 1e12 → 万亿 |
enterprise_value |
EV |
mcap + debt − cash |
shares_outstanding |
流通股 (实际为已发行股数) |
divide by 1e9 |
float_shares |
自由流通股 (排除限售) |
usually slightly < shares_outstanding |
shares_short |
当前空头持仓 |
|
short_pct_of_float |
空头占流通比 |
already ratio, ×100 for % |
pct_held_insiders |
内部人持股比例 |
already ratio |
pct_held_institutions |
机构持股比例 |
already ratio |
trailing_pe / forward_pe |
静态/动态 PE |
|
price_to_book |
市净率 |
|
dividend_yield |
股息率 |
already ratio (0.0036 = 0.36%) |
beta |
贝塔系数 |
vs SP500 |
recommendation |
'buy' / 'hold' / 'sell' |
analyst consensus |
target_mean_price |
分析师目标均价 |
|
Gotchas
- yfinance rate limits: Yahoo throttles aggressive callers (~2000/hour). Per
get_full_report is ~6 calls. For batch monitoring use time.sleep(0.3) between tickers. The skill already has _retry(tries=2).
get_info() is heavy (~1-2s, returns 120+ fields). For pure price use get_realtime_quote() instead (TwelveData ~150ms).
- NaN handling: yfinance returns NaN for missing fields (e.g. dividend yield for non-dividend payers). The skill converts NaN →
null in JSON. Always check for None before formatting.
- Quarterly financials limit: yfinance returns ~4 quarters back. For deeper history use SEC EDGAR 10-Q parsing (future enhancement).
- Real-time vs delayed: TwelveData is exchange-direct (low latency). yfinance has ~1 min lag during market hours. When they conflict, trust TwelveData.
- Institutional holders staleness: 13F filings lag 45 days after quarter-end.
Date Reported field tells you the as-of date.
- News provider IDs change: yfinance's
news schema occasionally adds/removes fields. The skill normalizes to {title, summary, publisher, pub_date, url, type}.
- Options data weight:
get_options_expirations is fast but fetching the full chain (Calls/Puts at each strike) requires per-expiry calls — not exposed yet to keep this skill light.
Output Style for User-Facing Replies
Telegram users want plain text, no markdown. Follow these conventions:
- Market cap:
$3.91T (万亿 = T, 十亿 = B, 百万 = M)
- Shares:
14.69B 股
- Ratios:
+2.34% (sign required), PE 36.2, Beta 1.07
- Holders:
贝莱德 (BlackRock) 7.32%
- Always cite source at end:
数据来源:TwelveData + Yahoo Finance (yfinance),非投资建议
Future Enhancements (not implemented)
- SEC EDGAR 13F deep dive (top N positions over multiple quarters)
- Form 4 raw filings with explicit transaction type (P/S/A/D codes)
- Pre/post-market quote (TwelveData supports
prepost=True — exposed via get_realtime_quote if needed)
- Options chain greeks (requires per-expiry × per-strike calls)
1---
2name: us-stock
3version: 1.0.2
4description: |
5 US stock fundamentals: financials, holders, insiders, earnings, dividends, splits.
6
7 Use for any US ticker beyond price (e.g. AAPL financials, NVDA top holders, MSFT insider trades, TSLA earnings calendar).
8metadata:
9 source: https://skillmd.com/skills/starchild-ai-agent/us-stock
10 starchild:
11 emoji: "🇺🇸"
12 skillKey: us-stock
13 requires:
14 bins: [python]
15 install:
16 - kind: pip
17 package: yfinance
18user-invocable: false
19disable-model-invocation: false
20
21---
22
23# 🇺🇸 us-stock — US Equities Data
24
25Single Python module with **multi-source fallback** for US stocks. Mirror of `cn-stock` for the US market. Use whenever the user asks about a US ticker — fundamentals, holders, insiders, financials. For pure price/K-line on US tickers, this skill internally calls the paid TwelveData skill, so you get one consistent interface.
26
27## Architecture
28
29```
30your call → exports.py
31 ├─ twelvedata (paid, primary) → realtime quote, time series
32 └─ yfinance (free, primary for fundamentals)
33 → info, holders, insiders,
34 financials, news, options,
35 dividends, splits, earnings
36```
37
38Most functions return a uniform envelope:
39```python
40{"ok": bool, "source": str, "data": <payload>, "error": str|None, "ts": int}
41```
42Exception: `get_full_report(symbol)` returns a combined dict of sub-results (quote/company/holders/insiders/earnings/news).
43
44## Quick Start
45
46**Preferred** — use `core.skill_tools` (handles import isolation):
47
48```bash
49python3 - <<'EOF'
50from core.skill_tools import _modules
51us = _modules["us-stock"]
52
53q = us.get_realtime_quote("AAPL")
54print(q["data"]["last"], q["data"]["pct_change"], "%")
55
56c = us.get_company_info("NVDA")
57d = c["data"]
58print(f"{d['name']} | mcap ${d['market_cap']/1e12:.2f}T | shares {d['shares_outstanding']/1e9:.2f}B")
59
60full = us.get_full_report("MSFT")
61print(full["company"]["data"]["sector"])
62EOF
63```
64
65**Fallback** (single-skill scripts only):
66
67```bash
68python3 - <<'EOF'
69import importlib.util as ilu
70spec = ilu.spec_from_file_location("us_stock_mod", "/data/workspace/skills/us-stock/exports.py")
71us = ilu.module_from_spec(spec); spec.loader.exec_module(us)
72print(us.get_realtime_quote("AAPL")["data"])
73EOF
74```
75
76⚠️ **Do NOT use** `sys.path.insert + from exports import ...` — `cn-stock` also defines `exports.py` and they will collide in the same process.
77
78## Function Map
79
80| Function | Returns | Source |
81|---|---|---|
82| `get_realtime_quote(symbol)` | price, OHLC, change, 52w range, mcap | twelvedata → yfinance fallback |
83| `get_company_info(symbol)` | mcap, **shares_outstanding**, **float_shares**, **pct_held_insiders**, **pct_held_institutions**, sector, industry, business summary, valuation, margins, dividend, analyst targets | yfinance.get_info |
84| `get_institutional_holders(symbol, top=15)` | Top N institutional holders + value + pctChange | yfinance |
85| `get_mutualfund_holders(symbol, top=15)` | Top N mutual fund holders | yfinance |
86| `get_insider_transactions(symbol, limit=20)` | Recent Form 4 buys/sells | yfinance |
87| `get_financials(symbol, statement, period, max_periods=5)` | Income / Balance / Cashflow, annual or quarterly | yfinance |
88| `get_earnings(symbol, limit=8)` | Past + upcoming earnings dates with EPS est. vs actual | yfinance |
89| `get_dividends(symbol, limit=20)` | Historical dividends | yfinance |
90| `get_splits(symbol, limit=10)` | Historical splits | yfinance |
91| `get_news(symbol, limit=10)` | Recent news titles + summaries + URLs | yfinance |
92| `get_kline(symbol, interval, outputsize)` | OHLCV bars | twelvedata → yfinance fallback |
93| `get_recommendations(symbol, limit=12)` | Analyst rating buckets per period | yfinance |
94| `get_options_expirations(symbol)` | All available option expiry dates | yfinance |
95| `get_etf_holdings(symbol, top=15)` | ETF/fund top holdings + sector/asset weights (e.g. SPY/QQQ) | yfinance.funds_data |
96| `get_full_report(symbol)` | quote + company + institutional + insiders + earnings + news combined | combo |
97
98## Symbol Format
99
100Pure US ticker — no exchange suffix:
101- `AAPL`, `MSFT`, `NVDA`, `GOOGL`, `TSLA`
102- Dual-class: `BRK.B`, `BRK-B`, `GOOG` / `GOOGL`
103- Both formats accepted; pass through as-is
104
105## TwelveData Reuse (important)
106
107This skill **does not register a separate TwelveData credential**. It loads the existing TwelveData skill by explicit file path (`/data/workspace/skills/twelvedata/exports.py`) via `importlib`, avoiding `exports.py` name collisions with other skills.
108Starchild's TwelveData billing covers these calls. If TwelveData fails, yfinance fallback kicks in automatically.
109
110## get_company_info Field Reference
111
112Fields most useful for Telegram replies (all from yfinance):
113
114| Field | Meaning | Notes |
115|---|---|---|
116| `market_cap` | 总市值 (USD) | divide by 1e9 → 十亿, 1e12 → 万亿 |
117| `enterprise_value` | EV | mcap + debt − cash |
118| `shares_outstanding` | 流通股 (实际为已发行股数) | divide by 1e9 |
119| `float_shares` | 自由流通股 (排除限售) | usually slightly < shares_outstanding |
120| `shares_short` | 当前空头持仓 | |
121| `short_pct_of_float` | 空头占流通比 | already ratio, ×100 for % |
122| `pct_held_insiders` | 内部人持股比例 | already ratio |
123| `pct_held_institutions` | 机构持股比例 | already ratio |
124| `trailing_pe` / `forward_pe` | 静态/动态 PE | |
125| `price_to_book` | 市净率 | |
126| `dividend_yield` | 股息率 | already ratio (0.0036 = 0.36%) |
127| `beta` | 贝塔系数 | vs SP500 |
128| `recommendation` | 'buy' / 'hold' / 'sell' | analyst consensus |
129| `target_mean_price` | 分析师目标均价 | |
130
131## Gotchas
132
133- **yfinance rate limits**: Yahoo throttles aggressive callers (~2000/hour). Per `get_full_report` is ~6 calls. For batch monitoring use `time.sleep(0.3)` between tickers. The skill already has `_retry(tries=2)`.
134- **`get_info()` is heavy** (~1-2s, returns 120+ fields). For pure price use `get_realtime_quote()` instead (TwelveData ~150ms).
135- **NaN handling**: yfinance returns NaN for missing fields (e.g. dividend yield for non-dividend payers). The skill converts NaN → `null` in JSON. Always check for `None` before formatting.
136- **Quarterly financials limit**: yfinance returns ~4 quarters back. For deeper history use SEC EDGAR 10-Q parsing (future enhancement).
137- **Real-time vs delayed**: TwelveData is exchange-direct (low latency). yfinance has ~1 min lag during market hours. When they conflict, trust TwelveData.
138- **Institutional holders staleness**: 13F filings lag 45 days after quarter-end. `Date Reported` field tells you the as-of date.
139- **News provider IDs change**: yfinance's `news` schema occasionally adds/removes fields. The skill normalizes to `{title, summary, publisher, pub_date, url, type}`.
140- **Options data weight**: `get_options_expirations` is fast but fetching the full chain (Calls/Puts at each strike) requires per-expiry calls — not exposed yet to keep this skill light.
141
142## Output Style for User-Facing Replies
143
144Telegram users want plain text, no markdown. Follow these conventions:
145
146- Market cap: `$3.91T` (万亿 = T, 十亿 = B, 百万 = M)
147- Shares: `14.69B 股`
148- Ratios: `+2.34%` (sign required), `PE 36.2`, `Beta 1.07`
149- Holders: `贝莱德 (BlackRock) 7.32%`
150- Always cite source at end: `数据来源:TwelveData + Yahoo Finance (yfinance),非投资建议`
151
152## Future Enhancements (not implemented)
153
154- SEC EDGAR 13F deep dive (top N positions over multiple quarters)
155- Form 4 raw filings with explicit transaction type (P/S/A/D codes)
156- Pre/post-market quote (TwelveData supports `prepost=True` — exposed via `get_realtime_quote` if needed)
157- Options chain greeks (requires per-expiry × per-strike calls)