| name | earnings-analyst |
| version | 1.0.2 |
| description | Research upcoming earnings events, analyze historical beat/miss patterns, and estimate post-earnings price reactions using the Finskills API. |
| author | finskills |
| metadata | {"openclaw":{"requires":{"env":["FINSKILLS_API_KEY"]},"primaryEnv":"FINSKILLS_API_KEY"},"homepage":"https://github.com/finskills/earnings-analyst"} |
Earnings Analyst
Track upcoming earnings events, analyze EPS beat/miss history, assess options-
implied earnings move expectations, and monitor analyst estimate revisions — all
powered by the Finskills API earnings calendar and company earnings endpoints.
Setup
API Key required — Register at https://finskills.net to get your free key.
Header: X-API-Key: <your_api_key>
Get your API key: Register at https://finskills.net — free tier available, Pro plan unlocks real-time quotes, history, and financials.
When to Activate This Skill
Activate when the user:
- Asks when a specific company reports earnings
- Wants to know historical earnings beat/miss rate for a stock
- Asks about analyst EPS/revenue estimates for an upcoming quarter
- Wants to understand the "earnings move" priced into options
- Asks which major companies are reporting this week
- Wants pre-earnings research before a binary event
Use Cases
Mode A — Market Earnings Calendar
"What major companies are reporting earnings this week?"
Mode B — Per-Stock Earnings Deep Dive
"Analyze NVDA's upcoming earnings — what should I expect?"
Mode C — Pre-Earnings Trade Setup
"Set up a pre-earnings analysis for AAPL with options context"
Data Retrieval — Finskills API Calls
Mode A — Earnings Calendar
GET https://finskills.net/v1/free/market/earnings-calendar
(Optional query params: from=YYYY-MM-DD&to=YYYY-MM-DD)
Extract: company name, ticker, report date, timing (before market / after market), EPS estimate
Filter and group by day. Sort by market cap or analyst attention.
Mode B — Per-Stock Earnings Analysis
Earnings History & Next Quarter Estimate:
GET https://finskills.net/v1/stocks/earnings/{SYMBOL}
Extract:
- Last 4–8 quarters:
date, epsActual, epsEstimate, epsSurprise, epsSurprisePercent
- Last 4–8 quarters:
revenueActual, revenueEstimate, revenueSurprise
- Next quarter:
epsEstimate, revenueEstimate
- Next report date, timing (AMC/BMO)
Analyst Estimates (revision trend):
GET https://finskills.net/v1/free/stocks/estimates/{SYMBOL}
Extract: current quarter EPS estimate, next quarter, current year, next year consensus
Note upward vs. downward revision trend (compare to 30-day-ago estimates if available)
Latest News (pre-earnings catalyst check):
GET https://finskills.net/v1/news/by-symbol/{SYMBOL}
Extract: recent headlines, sentiment signals, any pre-announcements or guidance updates
Options Chain (for implied move):
GET https://finskills.net/v1/stocks/options/{SYMBOL}
Extract near-term ATM straddle price to calculate implied earnings move.
Analysis Workflow
Step 1 — Earnings Calendar View (Mode A)
Group events by day (Mon–Fri this week):
- Show pre-market (BMO) and after-close (AMC) separately
- Flag mega-caps (market cap > $100B) with ★
- Include consensus EPS estimate for context
- Highlight sector clusters (earnings tend to move entire sectors)
Step 2 — Earnings History Analysis (Mode B)
Build a beat/miss scorecard:
| Quarter | EPS Est | EPS Actual | Surprise | Rev Est | Rev Actual | Rev Surprise |
|---|
| Q1 2025 | $X.XX | $X.XX | +X% | $XB | $XB | +X% |
| ... | | | | | | |
Compute:
- EPS Beat Rate: % of quarters beating EPS estimate
- Avg EPS Surprise: Mean % beat magnitude (positive = bullish quality)
- Revenue Beat Rate: % of quarters beating revenue estimate
- Consistency Score: 5/5 beats vs 3/5 vs 2/5 — flag inconsistency
- Trend: Is beat magnitude growing or shrinking? (quality signal)
Step 3 — Estimate Revision Momentum
Classify revision trend:
- Positive momentum: Estimates revised UP in last 30–90 days → analyst conviction rising
- Negative momentum: Estimates revised DOWN → potential guidance cut risk
- Stable: No significant revisions
This is a leading indicator — stocks with positive estimate revisions tend to outperform.
Step 4 — Implied Earnings Move (if options data available)
Calculate using ATM straddle at nearest expiration AFTER earnings date:
ATM Straddle Price = ATM Call Mid + ATM Put Mid
Implied Move % = Straddle Price / Current Stock Price × 100
Expected Range = [Current Price × (1 − implied_move%), Current Price × (1 + implied_move%)]
Compare to historical earnings moves (from earnings history — abs value of price change on earnings day):
- If implied move > average historical move: options are pricing in extra uncertainty → consider neutral strategies
- If implied move < average historical move: options may be cheap for directional play
Step 5 — Pre-Earnings Assessment
Summarize the opportunity:
Bull Case (if expecting beat):
- Revenue acceleration + margin expansion signals?
- Positive estimate revisions?
- Strong sector tailwinds?
Bear Case (if expecting miss or disappointment):
- Slowing beat magnitude trend?
- Recent negative estimate revisions?
- Macro headwinds for the sector?
Key Watch Items:
- Management guidance language (forward-looking statements)
- Segment breakdowns to watch (e.g., Cloud for MSFT, iPhone for AAPL)
- Margin trajectory (gross margin, operating margin vs estimates)
Output Format — Mode A (Calendar)
📅 EARNINGS CALENDAR — Week of {DATE}
MONDAY {Date}
⭐ {CompanyName} ({TICKER}) — AMC | EPS Est: ${est}
{CompanyName} ({TICKER}) — BMO | EPS Est: ${est}
TUESDAY {Date}
⭐ {CompanyName} ({TICKER}) — BMO | EPS Est: ${est}
...
[⚠️ Sector note: {sector} reports in concentration — expect spillover moves]
Output Format — Mode B (Per-Stock Deep Dive)
╔══════════════════════════════════════════════════════╗
║ EARNINGS ANALYSIS — {TICKER} ({DATE}) ║
╚══════════════════════════════════════════════════════╝
📅 NEXT EARNINGS
Expected Date: {date} | Timing: {BMO/AMC}
EPS Estimate: ${eps} | Revenue Estimate: ${rev}B
📊 EARNINGS TRACK RECORD (Last {N} Quarters)
EPS Beat Rate: {%} ({n}/{total})
Avg EPS Surprise: +{%}
Rev Beat Rate: {%} ({n}/{total})
Consistency: {All beats / Mostly beats / Mixed}
Quarter EPS Est Actual EPS Surp Rev Est Actual Rev Surp
Q4 2024 $X.XX $X.XX +X.X% $XB $XB +X.X%
Q3 2024 ...
📈 ESTIMATE REVISION TREND
Current FY EPS Estimate: ${est} ({+/-}% from 90 days ago)
Revision Trend: {Positive / Stable / Negative Momentum}
Implications: {one-line interpretation}
📐 IMPLIED EARNINGS MOVE (Options)
ATM Straddle Price: ${price} → Implied Move: ±{%}
Expected Range: ${low} — ${high}
Historical Avg Move: ±{%}
Options Assessment: {Cheap/Rich/Fair relative to history}
📰 PRE-EARNINGS SIGNALS
Recent News Sentiment: {Positive/Neutral/Negative}
Key Headlines:
• {headline 1}
• {headline 2}
⚠️ KEY WATCH ITEMS FOR THIS EARNINGS
1. {metric/segment to watch}
2. {metric/segment to watch}
3. {guidance language to watch}
🎯 EARNINGS SETUP SUMMARY
Bull Case: {2 sentences}
Bear Case: {2 sentences}
Strategy: {Directional bet / Neutral straddle / Avoid — with reasoning}
Limitations
- Earnings dates can shift by 1–2 weeks; always verify directly with the company's IR page.
- Implied move is based on options chain snapshot; liquidity affects pricing accuracy.
- EPS surprise history may not account for non-GAAP vs. GAAP differences.
