# Financial Analyst
> Deterministic financial-analysis toolkit — data + compute operations behind x402 micropayments, with a machine-readable analyst persona.

A neutral, deterministic financial-analysis backend usable by any agentic AI. It exposes granular tool operations (data fetchers and compute engines) for use inside an agent's own reasoning loop, plus a single-call /fa/ask orchestration endpoint. Every computed number comes from the deterministic engine; the persona's hard rule is that no LLM arithmetic ever substitutes for it.

## Adopting the persona
GET `/persona` to retrieve the machine-readable SOUL and adopt it as a temporary role/skill. Authored SOUL shipped at /persona; the deterministic rules below are the machine-readable mirror of its hard-rule section.

## Pricing
- `basic` tier — **$0.006125** on Base: `/fa/quote`, `/fa/prices`, `/fa/benchmark`, `/fa/rates`, `/fa/news`, `/fa/screen`, `/fa/filings`, `/fa/risk`, `/fa/statements`, `/fa/multiples`, `/fa/factor`, `/fa/validate`, `/fa/knowledge`, `/fa/snapshot`, `/fa/dcf`, `/fa/cross_verify`, `/fa/sources`
- `exclusive` tier — **$0.256125** on Base: `/fa/ask`
- Chains: Base, Arbitrum, Polygon, Avalanche, Ethereum, Robinhood, Arc. Per-chain prices in `/.well-known/x402.json`.

## Operations
### data
- **POST /fa/quote** — Fetch a fundamentals snapshot for a symbol (price, shares, mcap, debt, EPS, growth). — params: `symbol` (string)*, `sector` (string) (tier: `basic`)
- **POST /fa/prices** — Fetch price history for a symbol as a canonical series (dates + prices). — params: `symbol` (string)*, `interval` (string), `range_` (string), `adjusted` (boolean) (tier: `basic`)
- **POST /fa/benchmark** — Fetch the matching index series (^NSEI for Indian names, ^GSPC otherwise). — params: `symbol` (string)*, `benchmark` (string) (tier: `basic`)
- **POST /fa/rates** — Fetch a risk-free rate snapshot (US 10y/3m or INR 10y G-sec). — params: `rf` (string)*, `tenor` (string) (tier: `basic`)
- **POST /fa/news** — Fetch recent headlines for a ticker / pair / topic. — params: `query` (string)*, `days` (integer), `limit` (integer) (tier: `basic`)
- **POST /fa/screen** — Resolve a company name to its screener tickers/slugs. — params: `query` (string)*, `limit` (integer) (tier: `basic`)
- **POST /fa/filings** — Fetch recent exchange filings for an NSE symbol (primary evidence). — params: `symbol` (string)*, `limit` (integer) (tier: `basic`)

### compute
- **POST /fa/risk** — Return/risk metrics from a series (CAGR, vol, Sharpe, Sortino, MDD, beta, alpha…). — params: `series` (object)*, `benchmark` (object), `assumptions` (object) (tier: `basic`)
- **POST /fa/statements** — Financial-statement engine: common-size, ratios, DuPont 5-way, FCF, CCC. — params: `statements` (object)*, `prior` (object) (tier: `basic`)
- **POST /fa/multiples** — EV assembly + valuation multiples with market-cap reconciliation. — params: `fundamentals` (object)*, `assumptions` (object) (tier: `basic`)
- **POST /fa/factor** — Correlation, covariance, single-factor OLS, z-scores, rolling stats. — params: `series` (object)*, `assumptions` (object), `benchmark` (object), `rolling` (integer) (tier: `basic`)
- **POST /fa/dcf** — Deterministic DCF / reverse-DCF from caller-supplied fundamentals + assumptions. 10y explicit FCFF path, PV-vs-terminal split, WACC x g sensitivity grid; reverse mode returns the market-implied terminal FCFF / revenue and breakeven capex ratio. — params: `fundamentals` (object)*, `assumptions` (object)* (tier: `basic`)
- **POST /fa/cross_verify** — Run deterministic cross-verification checks (market_cap, dupont_roe, ebitda_bridge, eps_bridge) with the contract's hard-fail thresholds. Each check: {name, a, b, [threshold]}. — params: `checks` (array)* (tier: `basic`)

### validate
- **POST /fa/validate** — Validate an input document against the canonical schema (correct the request before paying for compute). — params: `document` (object)*, `kind` (string) (tier: `basic`)

### assembly
- **POST /fa/snapshot** — One structured packet: quote + 1y prices + news + valuation multiples for a fast read. — params: `symbol` (string)*, `sector` (string) (tier: `basic`)
- **POST /fa/ask** — One-call structured financial analysis. DeepSeek orchestrates the tool operations and returns a structured report (snapshot, valuation, statements, flags, caveats, bottom line). — params: `question` (string)*, `mode` (string) (tier: `exclusive`)

### helper
- **POST /fa/knowledge** — Retrieve the service's methodology corpus (source registry, conventions, workflows, verification rules). — params: `query` (string)*, `limit` (integer) (tier: `basic`)
- **POST /fa/sources** — List the service's data sources and their reliability ratings. (tier: `basic`)

## Workflows
- **snapshot** (why is X moving): `quote -> prices -> news -> multiples` — cross-verify market cap vs price × shares
- **valuation** (peer-compare valuation): `quote -> multiples` — batch quote per ticker, table ratios between names
- **dcf** (discounted cash flow / fair value): `quote -> statements -> dcf -> knowledge` — decompose via statements, anchor to latest actuals, always include WACC x g grid
- **risk** (return/risk metrics): `prices -> benchmark -> risk`
- **fundamentals** (fundamental deep-dive): `quote -> filings -> screen -> statements -> multiples -> cross_verify`
- **forensic** (governance / diligence): `filings -> news -> knowledge` — tag every claim VERIFIED / REPORTED / UNVERIFIED

## Deterministic contract
- No LLM arithmetic: every computed number comes from a compute operation.
- Cross-verify assembled market cap vs price × shares (hard-fail >10.0%).
- Cross-verify DuPont product vs ROE (hard-fail >0.1%).
- Cross-verify EBITDA vs EBIT + D&A (hard-fail >5.0%).
- Cross-verify EPS × shares vs net income (hard-fail >10.0%).

## Data sources
- Yahoo v8 chart API (Yahoo Finance) — keyless; set a desktop User-Agent
- Yahoo quoteSummary (Yahoo Finance) — needs cookie+crumb flow
- Google News RSS (Google News) — prefer when:ND filter
- RBI G-sec yield curve (Reserve Bank of India) — INR risk-free
- NSE corporate announcements (NSE India) — primary evidence; best-effort (headline in attchmntText)
- screener.in search API (screener.in) — name → ticker resolution

## Free endpoints
- GET `/`, `/health`, `/about`, `/.well-known/x402.json`, `/llms.txt`, `/openapi.json` (standard)
- GET `/fa/tools` — list all operations with input schemas
- GET `/fa/feedback` — 50 most recent feedback entries
- POST `/fa/feedback` — submit feedback

## Examples
- `snapshot` — quick read on a name: `{"question": "Give me a snapshot of TSLA and why it moved this week", "mode": "snapshot"}`
- `quote` — fundamentals for valuation: `{"symbol": "TSLA", "sector": "non_financials"}`
- `risk` — return/risk profile: `{"series": {"symbol": "TSLA", "periodicity": "daily", "dates": ["2026-01-02", "2026-01-03"], "prices": [400.0, 402.5]}}`