us-stock

🇺🇸 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)