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

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):

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)