# Lifestok

> Autonomous and human financial intelligence platform providing institutional-grade, multi-dimensional quantitative and qualitative asset research reports. Every report synthesizes real-time market data, technical indicators, fundamental valuation, official SEC Edgar filings, and an objective weighted rating model.

## Purpose

Lifestok is designed for dual navigation: human investors via a web dashboard and autonomous AI agents via standardized machine protocols (x402 HTTP micropayments, Model Context Protocol [MCP], OpenAPI 3.1, and llms.txt). The platform eliminates subjective editorial commentary and analyst bias by relying exclusively on primary data sources: Yahoo Finance and SEC Edgar.

Reports evaluate assets through automated quantitative scoring and produce a decisive rating: **Strong Buy**, **Buy**, **Hold**, **Sell**, or **Strong Sell**. Users and autonomous agents can inspect free report previews and unlock complete institutional reports via USDT on Base network or rewarded advertisement verification.

## Supported Asset Classes

Lifestok covers five distinct asset classes with tailored analytical pipelines:

- **Stocks (`stock`)**: US and global equities (e.g., `AAPL`, `NVDA`, `MSFT`, `TSLA`). Analyzed with fundamental valuation metrics, full technical indicator suites, and regulatory SEC Edgar filings (10-K, 10-Q, 8-K).
- **ETFs (`etf`)**: Exchange-Traded Funds (e.g., `SPY`, `QQQ`, `IWM`). Analyzed with technical indicator suites, price action trends, and SEC investment company filings.
- **Cryptocurrencies (`crypto`)**: Crypto pairs against USD/USDT/USDC (e.g., `BTC-USD`, `ETH-USD`, `SOL-USD`). Analyzed with momentum, trend, and volatility technical models. SEC filings are classified as not applicable.
- **Forex (`forex`)**: Currency pairs denoted with `=X` (e.g., `EURUSD=X`, `GBPUSD=X`, `USDJPY=X`). Evaluated using technical indicators and volatility measures. SEC filings are classified as not applicable.
- **Commodities (`commodity`)**: Commodity futures denoted with `=F` (e.g., `GC=F` Gold, `CL=F` Crude Oil, `SI=F` Silver). Evaluated through moving average trends, ATR volatility, and oscillators. SEC filings are classified as not applicable.

## Primary API Endpoints

All endpoints operate under strict fail-hard semantics with no synthetic fallbacks.

- `GET /api/assets/search?q={query}&limit={limit}&assetClass={class}&trending={boolean}`: Multi-asset search and trending asset catalog across stocks, ETFs, crypto, forex, and commodities. Backed by Upstash Redis 5-minute caching and sliding-window rate limiting.
- `GET /api/reports/{ticker}/preview`: Public report preview containing summary statistics, composite rating badge, teaser strengths/weaknesses, and unlock parameters.
- `GET /api/reports/{ticker}/full`: Full institutional report payload in JSON. Gated by x402 payment protocol (issues HTTP 402 with `WWW-Authenticate` and `X-402-*` challenge headers when unauthenticated) or signed purchase JWT access token.
- `GET /api/reports/{ticker}/download?format={pdf|json}`: Token-authenticated download route streaming vector PDF reports (`application/pdf`) or full JSON datasets (`application/json`). Authentication accepted via `Authorization: Bearer <token>`, `x-access-token: <token>`, or `accessToken` parameter.
- `POST /api/payments/verify-usdt`: Verifies Base on-chain USDT transaction hash and issues a signed purchase JWT token.
- `POST /api/payments/verify-ad`: Verifies rewarded ad completion signatures and issues a signed purchase JWT token.
- `GET /api/openapi.json`: Complete OpenAPI 3.1 schema specification.
- `GET /api/mcp`: Model Context Protocol Server-Sent Events (SSE) remote transport endpoint.

## x402 Payment Protocol Requirements

Autonomous AI agents can purchase full asset reports without human intervention using the HTTP 402 Payment Required standard on the Base blockchain:

- **Network**: Base Mainnet
- **Chain ID**: `8453`
- **Settlement Token**: USDT (ERC-20)
- **Token Contract Address**: `0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2`
- **Price**: `1.00` USDT (`1000000` base units, 6 decimals)
- **Payment Recipient**: Treasury address designated in `X-402-Recipient` challenge header
- **Challenge Headers**: Emitted on HTTP 402 from `GET /api/reports/{ticker}/full`:
  - `WWW-Authenticate: x402 network="base", chain_id="8453", token_address="0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2", amount="1000000", recipient="<PAYMENT_RECIPIENT_ADDRESS>", asset="<ticker>"`
  - `X-402-Payment-Required: true`
  - `X-402-Network: base`
  - `X-402-Chain-Id: 8453`
  - `X-402-Token-Address: 0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2`
  - `X-402-Amount: 1000000`
  - `X-402-Recipient: <PAYMENT_RECIPIENT_ADDRESS>`
  - `X-402-Asset: <ticker>`
  - `X-402-Report-Id: <reportId>`
- **Fulfillment**: Send on-chain transfer on Base, then retry request with transaction hash in header:
  - `X-402-Payment-Signature: <0x-tx-hash>` or
  - `Authorization: Bearer <0x-tx-hash>` or
  - `x-access-token: <jwt-token>`

## Model Context Protocol (MCP) Connection

AI agents and LLM clients (such as Claude Desktop, Cursor, and autonomous daemons) can connect to Lifestok via the Model Context Protocol:

- **Remote SSE Endpoint**: `GET /api/mcp`
- **Local Stdio Transport**: `npx tsx scripts/mcp-server.ts`
- **Available MCP Tools**:
  - `search_assets`: Search supported tickers by symbol or company name.
  - `get_report_preview`: Retrieve free high-level summary, metrics, and rating badge.
  - `get_x402_quote`: Obtain exact on-chain USDT payment parameters for a ticker.
  - `submit_x402_payment`: Submit Base transaction hash to verify payment and receive an unlock token.
  - `get_full_report`: Retrieve complete institutional report JSON snapshot.

## Detailed Documentation

For exhaustive endpoint schemas, JSON specifications, mathematical scoring formulas, SEC Edgar XBRL mappings, and x402 header lifecycle details, see:

- [Full LLM Documentation](llms-full.txt)
- [OpenAPI Specification](/api/openapi.json)