Defeat Beta API

DefeatBeta Skills are specialized tools designed to enhance an AI agent's financial analysis capabilities. They function as extensions on top of the Defeat Beta API MCP. These skills are compatible with AI platforms that support skill extensions, including Claude Desktop, Manus, Codex, Hermes Agent, and OpenClaw Agent.

Key capabilities include:

• Pre-earnings analysis: Synthesizing consensus estimates, guidance, and bull/base/bear scenarios.
• DCF Modeling: Generating editable Excel files with live formulas for WACC and FCF projections.
• Post-earnings reporting: Producing professional sell-side style DOCX reports with beat/miss analysis and updated valuations.

By using the Model Context Protocol (MCP), you can connect the Defeat Beta API directly to AI models. This allows the models to access real, structured financial data for analysis and reasoning, rather than relying on outdated information or assumptions.

Common use cases for this integration include:

• Analyzing Company Profiles
• Investigating Company Officers
• Tracking Stock Prices and Historical Performance
• Reviewing Earnings Call Transcripts
• Monitoring Financial News
• Examining Financial Statements
• Analyzing Revenue Breakdowns
• Assessing Profitability, Valuation, and Growth metrics.

The Defeat Beta API MCP acts as a bridge between MCP clients (like Claude Desktop or Manus AI) and the defeatbeta-api Python package.

The workflow is as follows:

1. MCP Client sends requests via JSON-RPC over stdio.
2. Defeat Beta API MCP Server (running in an isolated .venv) receives the request, constructs the necessary context, performs windowing/summarization, and shapes the output for the LLM.
3. Defeat Beta API (the PyPI package) is called by the MCP server to access market data, prices, history, and metrics.
4. Financial Data Sources are retrieved via the API and returned to the client.

When deciding between defeatbeta-api and yfinance, consider your requirements for data freshness versus bulk analysis efficiency:

Use defeatbeta-api if:

• You need bulk historical data: It is optimized for large-scale analysis.
• You want to avoid rate limits: It avoids Yahoo Finance's real-time rate limits by fetching data periodically (typically weekly) and hosting it on Hugging Face.
• You need efficient querying: It uses the Parquet format, which allows for flexible SQL queries via DuckDB.
• You need high performance: It uses cache_httpfs for local disk caching of remote data from Hugging Face.
• You need multi-source data: It integrates data from sources beyond just Yahoo Finance.

Use yfinance if:

• You need real-time data: defeatbeta-api is non-real-time and updates on a periodic basis (typically weekly).

The skill uses a Call-Then-Write cache pattern to prevent hallucinating numbers and ensure every cited figure is traceable to a source:

1. Immediate Caching: Every Tier 1 or Tier 2 MCP tool call is immediately followed by a Write of the verbatim return value to a JSON file in ./<TICKER>_<PERIOD>/cache/<tool>.json within the current working directory.
2. Source of Truth: These cache files serve as the report's ground truth.
3. Verified Reading: When drafting sections, the model Reads the relevant cache file to cite numbers rather than relying on its own context memory, which may have been compressed or paraphrased.

This pattern also applies to transcripts; the skill uses grep against on-disk transcripts for guidance quotes rather than pulling massive text blocks into the LLM context.

When using the defeatbeta-analyst APIs, be aware of these critical requirements:

1. Relative Time Queries: Always call get_latest_data_update_date first. This provides the reference "today" date for all relative time queries.
2. Fiscal Periods: Earnings transcripts use fiscal periods which may differ from calendar periods. You must specify both fiscal_year and fiscal_quarter.
3. SEC Filing Access: When accessing SEC URLs, you must use the sec_user_agent field value as the User-Agent header, otherwise the SEC will block the request.
4. Sector Exceptions: ROIC and Equity Multiplier are not applicable to banks or financial institutions. Check the sector in the company profile before calculating these.

The weighted decision model uses 5 to 8 dimensions with explicit weights totaling 100%. Each dimension is scored from -2 to +2:

Formula: Weighted Score = sum(weight × dimension score ÷ 2)

The resulting score ranges from -1.0 to +1.0. Use the following default bands to determine the scenario:

• Bull: score $\ge$ +0.35 and no veto gate triggered
• Base: score between -0.35 and +0.35 and no veto gate triggered
• Bear: score $\le$ -0.35, OR any Bear veto gate triggered.

The DCF analysis follows these mathematical models:

• CAPM (Cost of Equity): Rf + β × (Rm - Rf)
• WACC: Wd × Kd × (1 - Tax Rate) + We × Ke
• CAGR: (Ending Value / Beginning Value)^(1/Years) - 1
• Enterprise Value (NPV): Σ Total Value_i / (1 + WACC)^i for $i=1$ to $10$
• Terminal Value (Gordon Growth Model): FCF₁₀ × (1 + g_terminal) / (WACC - g_terminal)
• Equity Value: Enterprise Value + Cash - Total Debt
• Fair Price: Equity Value / Shares Outstanding