us-stock

🇺🇸 us-stock — 米国株式データ

米国株向けのマルチソースフォールバックを備えた単一の Python モジュールです。米国市場向けの cn-stock のミラーです。ユーザーが米国のティッカーについて質問したとき — ファンダメンタルズ、保有者、インサイダー、財務 — はいつでもこれを使用してください。米国ティッカーの純粋な価格/K ラインについては、このスキルは内部的に有料の TwelveData スキルを呼び出すため、一貫した単一のインターフェースが得られます。

アーキテクチャ

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

ほとんどの関数は統一されたエンベロープを返します:

{"ok": bool, "source": str, "data": <payload>, "error": str|None, "ts": int}

例外: get_full_report(symbol) はサブ結果 (quote/company/holders/insiders/earnings/news) を結合した dict を返します。

クイックスタート

推奨 — core.skill_tools を使用してください (インポートの分離を処理します):

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

フォールバック (単一スキルのスクリプトのみ):

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

⚠️ 使用しないでください — sys.path.insert + from exports import ... — cn-stock も exports.py を定義しているため、同じプロセス内で衝突します。

関数マップ

関数	戻り値	ソース
get_realtime_quote(symbol)	価格、OHLC、変化、52 週レンジ、時価総額	twelvedata → yfinance fallback
get_company_info(symbol)	時価総額、shares_outstanding、float_shares、pct_held_insiders、pct_held_institutions、セクター、業種、事業概要、バリュエーション、マージン、配当、アナリスト目標	yfinance.get_info
get_institutional_holders(symbol, top=15)	上位 N 機関保有者 + 価値 + pctChange	yfinance
get_mutualfund_holders(symbol, top=15)	上位 N ミューチュアルファンド保有者	yfinance
get_insider_transactions(symbol, limit=20)	最近の Form 4 売買	yfinance
get_financials(symbol, statement, period, max_periods=5)	損益計算書 / 貸借対照表 / キャッシュフロー、年次または四半期	yfinance
get_earnings(symbol, limit=8)	過去 + 今後の決算日と EPS 予想 vs 実績	yfinance
get_dividends(symbol, limit=20)	過去の配当	yfinance
get_splits(symbol, limit=10)	過去の株式分割	yfinance
get_news(symbol, limit=10)	最近のニュースのタイトル + 要約 + URL	yfinance
get_kline(symbol, interval, outputsize)	OHLCV バー	twelvedata → yfinance fallback
get_recommendations(symbol, limit=12)	期間ごとのアナリスト評価バケット	yfinance
get_options_expirations(symbol)	利用可能なすべてのオプション満期日	yfinance
get_etf_holdings(symbol, top=15)	ETF/ファンドの上位保有銘柄 + セクター/資産ウェイト (例: SPY/QQQ)	yfinance.funds_data
get_full_report(symbol)	quote + company + institutional + insiders + earnings + news の結合	combo

シンボル形式

純粋な米国ティッカー — 取引所のサフィックスなし:

• AAPL、MSFT、NVDA、GOOGL、TSLA
• 二重クラス: BRK.B、BRK-B、GOOG / GOOGL
• どちらの形式も受け付けます。そのまま渡されます

TwelveData の再利用 (重要)

このスキルは別の TwelveData 認証情報を登録しません。既存の TwelveData スキルを明示的なファイルパス (/data/workspace/skills/twelvedata/exports.py) から importlib 経由で読み込み、他のスキルとの exports.py の名前衝突を回避します。 Starchild の TwelveData 課金がこれらの呼び出しをカバーします。TwelveData が失敗した場合、yfinance フォールバックが自動的に作動します。

get_company_info フィールドリファレンス

Telegram の返信に最も役立つフィールド (すべて yfinance 由来):

フィールド	意味	備考
market_cap	総市值 (USD)	divide by 1e9 → 十億, 1e12 → 万億
enterprise_value	EV	時価総額 + 負債 − 現金
shares_outstanding	流通株 (実際は発行済株式数)	divide by 1e9
float_shares	自由流通株 (制限付きを除く)	usually slightly < shares_outstanding
shares_short	現在の空売り残高
short_pct_of_float	空売り比率	すでに比率、×100 で %
pct_held_insiders	インサイダー保有比率	すでに比率
pct_held_institutions	機関保有比率	すでに比率
trailing_pe / forward_pe	実績/予想 PE
price_to_book	株価純資産倍率
dividend_yield	配当利回り	すでに比率 (0.0036 = 0.36%)
beta	ベータ係数	vs SP500
recommendation	'buy' / 'hold' / 'sell'	アナリストのコンセンサス
target_mean_price	アナリストの目標平均株価

注意点

• yfinance のレート制限: Yahoo は頻繁に呼び出すクライアント（約 2000 回/時）を制限します。get_full_report あたり約 6 回の呼び出しになります。バッチ監視では、ティッカー間で time.sleep(0.3) を使用してください。このスキルにはすでに _retry(tries=2) が含まれています。
• get_info() は重い（約 1〜2 秒、120 以上のフィールドを返します）。純粋な価格のみが必要な場合は、代わりに get_realtime_quote() を使用してください（TwelveData 約 150ms）。
• NaN の処理: yfinance は欠損フィールド（例：無配株の配当利回り）に対して NaN を返します。このスキルは NaN → JSON の null に変換します。フォーマットする前に必ず None をチェックしてください。
• 四半期財務の制限: yfinance は約 4 四半期前までしか返しません。より深い履歴が必要な場合は SEC EDGAR 10-Q のパースを使用してください（将来の拡張）。
• リアルタイム vs 遅延: TwelveData は取引所直接（低レイテンシ）です。yfinance は市場時間中に約 1 分の遅延があります。両者が矛盾する場合は TwelveData を信頼してください。
• 機関投資家保有の陳腐化: 13F 提出は四半期末から 45 日遅れます。Date Reported フィールドは基準日を示します。
• ニュースプロバイダーの ID 変更: yfinance の news スキーマは時折フィールドを追加/削除します。このスキルは {title, summary, publisher, pub_date, url, type} に正規化します。
• オプションデータの重さ: get_options_expirations は高速ですが、完全なチェーン（各ストライクの Calls/Puts）を取得するには有効期限ごとの呼び出しが必要です — このスキルを軽量に保つため、まだ公開されていません。

ユーザー向け返信の出力スタイル

Telegram ユーザーはマークダウンなしのプレーンテキストを好みます。以下の規約に従ってください：

• 時価総額: $3.91T（万亿 = T、十亿 = B、百万 = M）
• 株式数: 14.69B 股
• 比率: +2.34%（符号必須）、PE 36.2、Beta 1.07
• 保有者: 贝莱德 (BlackRock) 7.32%
• 末尾に必ず出典を記載: 数据来源：TwelveData + Yahoo Finance (yfinance)，非投资建议

将来の拡張（未実装）

• SEC EDGAR 13F の詳細調査（複数四半期にわたる上位 N ポジション）
• 取引種別を明示した Form 4 の生提出書類（P/S/A/D コード）
• プレ/ポストマーケットのクオート（TwelveData は prepost=True をサポート — 必要に応じて get_realtime_quote 経由で公開）
• オプチェーンのギリシャ値（有効期限ごと × ストライクごとの呼び出しが必要）