Alpha Vantage for Financial & Economic Fact Evidence

Motivation

Business, finance, technology, and economics facts frequently claim specific market caps, IPO dates, revenue figures, GDP growth, inflation rates, and commodity prices. The evidence pipeline currently has zero financial data APIs — these claims are verified only against Wikipedia text and Wikidata triples, which are often stale or lack the specificity to confirm exact figures.

Alpha Vantage provides authoritative financial data: company fundamentals, economic indicators, commodity prices, and 20+ years of market history across 100K+ global symbols.

Service Overview

Category	Function	Key Data
Company Fundamentals	`OVERVIEW`	Market cap, IPO date, sector, employees, description
Income Statement	`INCOME_STATEMENT`	Revenue, net income, EBITDA (annual + quarterly)
Earnings	`EARNINGS`	EPS actual vs estimated, surprise %, quarterly history
Stock Prices	`TIME_SERIES_DAILY`	OHLCV, 20+ years daily history
Economic Indicators	`REAL_GDP`, `CPI`, `INFLATION`, `UNEMPLOYMENT`	US macro data, quarterly/annual
Commodities	`WTI`, `BRENT`, `NATURAL_GAS`, `GOLD`, `SILVER`	Daily/monthly price history
Forex	`CURRENCY_EXCHANGE_RATE`	Real-time and historical FX rates
Crypto	`DIGITAL_CURRENCY_DAILY`	BTC, ETH, etc. daily OHLCV
IPO Calendar	`IPO_CALENDAR`	Upcoming and historical IPOs

Base URL: https://www.alphavantage.co/query?function={FUNCTION}&apikey={KEY} Auth: apikey query parameter (ALPHA_VANTAGE_API_KEY env var, already in .env.local) Free tier: 25 requests/day, 5 requests/minute Format: JSON (default), CSV

What It Verifies

Fact Claim Type	Example	API Function	Evidence
Market cap	"Apple is worth $3 trillion"	`OVERVIEW`	`MarketCapitalization` (current)
IPO date	"Tesla went public in 2010"	`OVERVIEW`	`IPODate` field
Revenue	"Amazon revenue exceeded $500B"	`INCOME_STATEMENT`	`totalRevenue` per year
Stock milestone	"Bitcoin hit $69K in Nov 2021"	`DIGITAL_CURRENCY_DAILY`	Actual daily high
GDP growth	"US GDP grew 5.7% in 2021"	`REAL_GDP`	Actual GDP values
Inflation	"Inflation hit 9.1% in June 2022"	`CPI`	Actual CPI reading
Commodity price	"Gold surpassed $2,000/oz"	`GOLD`	Daily price history
Forex	"Euro reached parity with USD in 2022"	`CURRENCY_EXCHANGE_RATE`	Actual exchange rate
Earnings	"Tesla beat earnings estimates"	`EARNINGS`	`surprise` and `surprisePercentage`

Implementation

Challenge 1: Alpha Vantage Client

File: packages/ai/src/alphavantage-client.ts (new)

Base URL: https://www.alphavantage.co/query
Auth: apikey query param from ALPHA_VANTAGE_API_KEY env var
In-memory cache: 1h TTL for fundamentals, 15min for prices, 5K max entries
Rate tracking: log daily usage, warn at 20/25 requests (free tier is tight)
10s timeout, abort controller
Metrics: alphavantage.api_calls, alphavantage.cache_hit, alphavantage.rate_limited

Key methods:

// Company fundamentals
getCompanyOverview(symbol: string): Promise<CompanyOverview | null>
getIncomeStatement(symbol: string): Promise<IncomeStatement | null>
getEarnings(symbol: string): Promise<EarningsHistory | null>

// Symbol resolution (name → ticker)
searchSymbol(name: string): Promise<SymbolMatch | null>
// Uses SYMBOL_SEARCH function: "Apple" → "AAPL"

// Economic indicators
getRealGDP(interval?: 'annual' | 'quarterly'): Promise<EconomicDataPoint[]>
getCPI(interval?: 'monthly' | 'semiannual'): Promise<EconomicDataPoint[]>
getInflation(): Promise<EconomicDataPoint[]>
getUnemployment(): Promise<EconomicDataPoint[]>
getFederalFundsRate(): Promise<EconomicDataPoint[]>

// Commodities & forex
getCommodityPrice(commodity: 'WTI' | 'BRENT' | 'GOLD' | 'SILVER' | 'NATURAL_GAS'): Promise<PriceHistory | null>
getForexRate(from: string, to: string): Promise<ForexRate | null>
getCryptoDaily(symbol: string): Promise<PriceHistory | null>

// Formatting
formatCompanyContext(overview: CompanyOverview): string
formatEconomicContext(indicator: string, data: EconomicDataPoint[]): string

Symbol resolution is critical — fact context says "Apple" or "Tesla", not "AAPL" or "TSLA". The SYMBOL_SEARCH function handles this: ?function=SYMBOL_SEARCH&keywords=Tesla → {bestMatches: [{symbol: "TSLA", ...}]}.

Acceptance: Can look up "Apple" → AAPL → company overview with market cap, IPO date, sector. Can query US GDP for 2021 → actual growth figure.

Challenge 2: Evidence Pipeline Integration

File: packages/ai/src/validation/evidence.ts

Wire into Phase 4b with topic gating for business/finance/economics:

const financialTopics = ['business', 'finance', 'economics', 'technology', 'crypto']
if (financialTopics.some(t => topicPath.includes(t)) && alphaVantageKey) {

  // Company-specific claims
  if (hasCompanyClaim(factTitle, factContext)) {
    const symbol = await searchSymbol(extractCompanyName(factContext))
    if (symbol) {
      const overview = await getCompanyOverview(symbol.symbol)
      if (overview) {
        findings.push(`Alpha Vantage: ${overview.Name}, IPO ${overview.IPODate}, Market Cap $${overview.MarketCapitalization}`)
      }
      // Revenue/earnings claims
      if (hasRevenueClaim(factContext)) {
        const income = await getIncomeStatement(symbol.symbol)
        if (income) {
          findings.push(`Alpha Vantage: FY revenue ${income.annualReports[0]?.totalRevenue}`)
        }
      }
    }
  }

  // Economic indicator claims
  if (hasEconomicClaim(factContext)) {
    // GDP, inflation, unemployment — match claim to indicator
    const indicator = detectEconomicIndicator(factContext)
    if (indicator) {
      const data = await getEconomicData(indicator)
      findings.push(`Alpha Vantage: ${indicator} = ${data[0]?.value} (${data[0]?.date})`)
    }
  }

  // Commodity/crypto price claims
  if (hasPriceClaim(factContext)) {
    const asset = detectAsset(factContext) // "gold", "bitcoin", "oil"
    if (asset) {
      const prices = await getAssetPrice(asset)
      findings.push(`Alpha Vantage: ${asset} price history available`)
    }
  }
}

Rate budget strategy: 25 req/day is tight. Prioritize:

SYMBOL_SEARCH + OVERVIEW (2 calls — highest value, covers IPO dates, market cap)
INCOME_STATEMENT only when revenue/earnings claimed (1 call)
Economic indicators only when GDP/CPI/inflation claimed (1 call)
Skip price history lookups on free tier (expensive, lower verification value)

Acceptance: "Tesla went public in 2010" → SYMBOL_SEARCH("Tesla") → OVERVIEW("TSLA") → IPODate: 2010-06-29 → corroborated.

Challenge 3: Tests

File: packages/ai/src/__tests__/alphavantage-client.test.ts (new)

Symbol search response parsing
Company overview parsing (market cap, IPO date, sector)
Economic indicator parsing
Cache behavior (especially TTL differences: 1h fundamentals vs 15min prices)
Rate limit tracking and warning
Financial topic detection in fact context
Graceful degradation when API key missing or rate limited

Acceptance: bun run test passes.

Evidence Confidence Impact

Company overview found with matching IPO date → boost apiConfidence by 0.15 (authoritative)
Revenue figure matches within 5% → boost apiConfidence by 0.1
Economic indicator matches claim → boost apiConfidence by 0.15
Company found but data contradicts claim → flag as critical
No results or rate limited → fall through to existing sources (no penalty)

Cost

Free tier: 25 requests/day. Sufficient for validation pipeline (not bulk ingestion). Premium: $49.99/month for 75 req/min if needed at scale.

Dependencies

ALPHA_VANTAGE_API_KEY in .env.local (already done)
Add to packages/config/src/index.ts env schema
Add to .env.example

Rate Budget

Validation Scenario	Calls	Notes
Company fact (IPO, market cap)	2	SYMBOL_SEARCH + OVERVIEW
Company + revenue claim	3	+ INCOME_STATEMENT
Economic indicator (GDP, CPI)	1	Single indicator lookup
Commodity/crypto price	1	Single price lookup
Daily budget	25	~8-12 financial facts/day on free tier

Relationship to Other Evidence Plans

Plan	Domain	Data
API-Sports	Sports	Match results, player stats, game data
OpenAlex + Nobel Prize	Science, academia	Authors, papers, institutions, prize attribution
Alpha Vantage	Finance, business, economics	Fundamentals, revenue, GDP, inflation, commodities
DBpedia	General-purpose fallback	Structured Wikipedia infobox properties

#Alpha Vantage for Financial & Economic Fact Evidence

#Motivation

#Service Overview

#What It Verifies

#Implementation

#Challenge 1: Alpha Vantage Client

#Challenge 2: Evidence Pipeline Integration

#Challenge 3: Tests

#Evidence Confidence Impact

#Cost

#Dependencies

#Rate Budget

#Relationship to Other Evidence Plans