{ "openapi": "3.1.0", "info": { "title": "Lifestok Financial Intelligence API", "version": "1.0.0", "description": "Institutional-grade quantitative financial intelligence platform for autonomous AI agents and human investors. Built strictly on Yahoo Finance and SEC Edgar primary data sources with fail-hard semantics, zero synthetic fallbacks, and native x402 on-chain micropayments on Base network.", "contact": { "name": "Lifestok Support", "url": "https://lifestok.com" } }, "servers": [ { "url": "/", "description": "Current environment base URL" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Standard HTTP Bearer JWT purchase access token" }, "X402Signature": { "type": "apiKey", "in": "header", "name": "X-402-Payment-Signature", "description": "Base network 64-hex transaction hash proving 1.00 USDT settlement" }, "XAccessToken": { "type": "apiKey", "in": "header", "name": "x-access-token", "description": "Alternative HTTP header containing signed JWT purchase access token" } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "example": "An error occurred processing the request" } }, "required": [ "error" ] }, "AssetSearchResult": { "type": "object", "properties": { "ticker": { "type": "string", "example": "AAPL" }, "name": { "type": "string", "example": "Apple Inc." }, "assetClass": { "type": "string", "enum": [ "stock", "etf", "crypto", "forex", "commodity" ], "example": "stock" }, "exchange": { "type": "string", "example": "NMS" }, "quoteType": { "type": "string", "example": "EQUITY" }, "price": { "type": "number", "example": 224.23 }, "currency": { "type": "string", "example": "USD" }, "change24h": { "type": "number", "example": 1.45 }, "changePercent24h": { "type": "number", "example": 0.65 }, "marketCap": { "type": [ "number", "null" ], "example": 3410000000000 } }, "required": [ "ticker", "name", "assetClass", "exchange", "quoteType", "price", "currency", "change24h", "changePercent24h", "marketCap" ] }, "AssetSearchResponse": { "type": "object", "properties": { "query": { "type": "string", "example": "AAPL" }, "count": { "type": "integer", "example": 1 }, "results": { "type": "array", "items": { "type": "object", "properties": { "ticker": { "type": "string", "example": "AAPL" }, "name": { "type": "string", "example": "Apple Inc." }, "assetClass": { "type": "string", "enum": [ "stock", "etf", "crypto", "forex", "commodity" ], "example": "stock" }, "exchange": { "type": "string", "example": "NMS" }, "quoteType": { "type": "string", "example": "EQUITY" }, "price": { "type": "number", "example": 224.23 }, "currency": { "type": "string", "example": "USD" }, "change24h": { "type": "number", "example": 1.45 }, "changePercent24h": { "type": "number", "example": 0.65 }, "marketCap": { "type": [ "number", "null" ], "example": 3410000000000 } }, "required": [ "ticker", "name", "assetClass", "exchange", "quoteType", "price", "currency", "change24h", "changePercent24h", "marketCap" ] } } }, "required": [ "query", "count", "results" ] }, "RatingBadge": { "type": "object", "properties": { "rating": { "type": "string", "enum": [ "strong_buy", "buy", "hold", "sell", "strong_sell" ], "example": "buy" }, "grade": { "type": "string", "enum": [ "Strong Buy", "Buy", "Hold", "Sell", "Strong Sell" ], "example": "Buy" }, "score": { "type": "number", "minimum": 0, "maximum": 100, "example": 72 } }, "required": [ "rating", "grade", "score" ] }, "SummaryStats": { "type": "object", "properties": { "ticker": { "type": "string", "example": "AAPL" }, "name": { "type": "string", "example": "Apple Inc." }, "assetClass": { "type": "string", "enum": [ "stock", "etf", "crypto", "forex", "commodity" ], "example": "stock" }, "price": { "type": "number", "example": 224.23 }, "currency": { "type": "string", "example": "USD" }, "marketCap": { "type": [ "number", "null" ], "example": 3410000000000 }, "change24h": { "type": "number", "example": 1.45 }, "changePercent24h": { "type": "number", "example": 0.65 }, "peRatio": { "type": [ "number", "null" ], "example": 33.8 }, "rsi": { "type": "number", "example": 56.4 }, "rsiStatus": { "type": "string", "enum": [ "overbought", "oversold", "neutral" ], "example": "neutral" }, "sma50": { "type": "number", "example": 218.4 }, "sma200": { "type": "number", "example": 198.1 }, "trend": { "type": "string", "enum": [ "bullish", "bearish", "neutral" ], "example": "bullish" }, "isSecApplicable": { "type": "boolean", "example": true } }, "required": [ "ticker", "name", "assetClass", "price", "currency", "marketCap", "change24h", "changePercent24h", "peRatio", "rsi", "rsiStatus", "sma50", "sma200", "trend", "isSecApplicable" ] }, "GatedSectionTeaser": { "type": "object", "properties": { "id": { "type": "string", "example": "fundamentals" }, "title": { "type": "string", "example": "Institutional Fundamental Valuation Breakdown" }, "description": { "type": "string", "example": "Comprehensive solvency, ROE, PEG ratio, and discounted cash flow valuation tables." }, "blurredSampleText": { "type": "string", "example": "Full financial facts with audited balance sheet ratios..." } }, "required": [ "id", "title", "description", "blurredSampleText" ] }, "BlurredPreviewPoints": { "type": "object", "properties": { "previewStrengths": { "type": "array", "items": { "type": "string" }, "example": [ "Superior capital efficiency with robust return on equity (ROE) and strong profit margins", "Strong bullish market structure with price trading above key 50-day and 200-day moving averages" ] }, "previewWeaknesses": { "type": "array", "items": { "type": "string" }, "example": [ "Elevated valuation multiples with P/E ratio exceeding standard benchmarks" ] }, "hiddenStrengthsCount": { "type": "integer", "example": 3 }, "hiddenWeaknessesCount": { "type": "integer", "example": 1 }, "gatedSections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "fundamentals" }, "title": { "type": "string", "example": "Institutional Fundamental Valuation Breakdown" }, "description": { "type": "string", "example": "Comprehensive solvency, ROE, PEG ratio, and discounted cash flow valuation tables." }, "blurredSampleText": { "type": "string", "example": "Full financial facts with audited balance sheet ratios..." } }, "required": [ "id", "title", "description", "blurredSampleText" ] } } }, "required": [ "previewStrengths", "previewWeaknesses", "hiddenStrengthsCount", "hiddenWeaknessesCount", "gatedSections" ] }, "UnlockOptions": { "type": "object", "properties": { "usdtAmount": { "type": "string", "example": "1.00" }, "network": { "type": "string", "example": "Base" }, "chainId": { "type": "integer", "example": 8453 }, "tokenAddress": { "type": "string", "example": "0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2" }, "recipientAddress": { "type": "string", "example": "0x1234567890123456789012345678901234567890" }, "rewardedAdAvailable": { "type": "boolean", "example": true } }, "required": [ "usdtAmount", "network", "chainId", "tokenAddress", "recipientAddress", "rewardedAdAvailable" ] }, "PublicReportPreview": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "b18b4827-0240-4d56-8fb5-48b488ba30d2" }, "assetId": { "type": "string", "format": "uuid", "example": "91a83748-0249-4d91-8bb2-892471928374" }, "ticker": { "type": "string", "example": "AAPL" }, "companyName": { "type": "string", "example": "Apple Inc." }, "assetClass": { "type": "string", "enum": [ "stock", "etf", "crypto", "forex", "commodity" ], "example": "stock" }, "asOfDate": { "type": "string", "example": "2026-11-03" }, "generatedAt": { "type": "string", "example": "2026-11-03T07:00:00.000Z" }, "expiresAt": { "type": "string", "example": "2026-11-04T07:00:00.000Z" }, "summary": { "type": "string", "example": "Apple Inc. (AAPL) is rated Buy with a composite score of 72/100. Robust balance sheet productivity and constructive momentum are tempered by valuation expansion." }, "ratingBadge": { "type": "object", "properties": { "rating": { "type": "string", "enum": [ "strong_buy", "buy", "hold", "sell", "strong_sell" ], "example": "buy" }, "grade": { "type": "string", "enum": [ "Strong Buy", "Buy", "Hold", "Sell", "Strong Sell" ], "example": "Buy" }, "score": { "type": "number", "minimum": 0, "maximum": 100, "example": 72 } }, "required": [ "rating", "grade", "score" ] }, "summaryStats": { "type": "object", "properties": { "ticker": { "type": "string", "example": "AAPL" }, "name": { "type": "string", "example": "Apple Inc." }, "assetClass": { "type": "string", "enum": [ "stock", "etf", "crypto", "forex", "commodity" ], "example": "stock" }, "price": { "type": "number", "example": 224.23 }, "currency": { "type": "string", "example": "USD" }, "marketCap": { "type": [ "number", "null" ], "example": 3410000000000 }, "change24h": { "type": "number", "example": 1.45 }, "changePercent24h": { "type": "number", "example": 0.65 }, "peRatio": { "type": [ "number", "null" ], "example": 33.8 }, "rsi": { "type": "number", "example": 56.4 }, "rsiStatus": { "type": "string", "enum": [ "overbought", "oversold", "neutral" ], "example": "neutral" }, "sma50": { "type": "number", "example": 218.4 }, "sma200": { "type": "number", "example": 198.1 }, "trend": { "type": "string", "enum": [ "bullish", "bearish", "neutral" ], "example": "bullish" }, "isSecApplicable": { "type": "boolean", "example": true } }, "required": [ "ticker", "name", "assetClass", "price", "currency", "marketCap", "change24h", "changePercent24h", "peRatio", "rsi", "rsiStatus", "sma50", "sma200", "trend", "isSecApplicable" ] }, "previewPoints": { "type": "object", "properties": { "previewStrengths": { "type": "array", "items": { "type": "string" }, "example": [ "Superior capital efficiency with robust return on equity (ROE) and strong profit margins", "Strong bullish market structure with price trading above key 50-day and 200-day moving averages" ] }, "previewWeaknesses": { "type": "array", "items": { "type": "string" }, "example": [ "Elevated valuation multiples with P/E ratio exceeding standard benchmarks" ] }, "hiddenStrengthsCount": { "type": "integer", "example": 3 }, "hiddenWeaknessesCount": { "type": "integer", "example": 1 }, "gatedSections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "fundamentals" }, "title": { "type": "string", "example": "Institutional Fundamental Valuation Breakdown" }, "description": { "type": "string", "example": "Comprehensive solvency, ROE, PEG ratio, and discounted cash flow valuation tables." }, "blurredSampleText": { "type": "string", "example": "Full financial facts with audited balance sheet ratios..." } }, "required": [ "id", "title", "description", "blurredSampleText" ] } } }, "required": [ "previewStrengths", "previewWeaknesses", "hiddenStrengthsCount", "hiddenWeaknessesCount", "gatedSections" ] }, "disclaimer": { "type": "string", "example": "Disclaimer: This report is generated automatically by Lifestok for informational and educational purposes only. It does not constitute financial, investment, legal, or tax advice." }, "unlockOptions": { "type": "object", "properties": { "usdtAmount": { "type": "string", "example": "1.00" }, "network": { "type": "string", "example": "Base" }, "chainId": { "type": "integer", "example": 8453 }, "tokenAddress": { "type": "string", "example": "0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2" }, "recipientAddress": { "type": "string", "example": "0x1234567890123456789012345678901234567890" }, "rewardedAdAvailable": { "type": "boolean", "example": true } }, "required": [ "usdtAmount", "network", "chainId", "tokenAddress", "recipientAddress", "rewardedAdAvailable" ] } }, "required": [ "id", "assetId", "ticker", "companyName", "assetClass", "asOfDate", "generatedAt", "expiresAt", "summary", "ratingBadge", "summaryStats", "previewPoints", "disclaimer", "unlockOptions" ] }, "FullReportSnapshot": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "b18b4827-0240-4d56-8fb5-48b488ba30d2" }, "assetId": { "type": "string", "format": "uuid", "example": "91a83748-0249-4d91-8bb2-892471928374" }, "ticker": { "type": "string", "example": "AAPL" }, "companyName": { "type": "string", "example": "Apple Inc." }, "assetClass": { "type": "string", "enum": [ "stock", "etf", "crypto", "forex", "commodity" ], "example": "stock" }, "asOfDate": { "type": "string", "example": "2026-11-03" }, "generatedAt": { "type": "string", "example": "2026-11-03T07:00:00.000Z" }, "expiresAt": { "type": "string", "example": "2026-11-04T07:00:00.000Z" }, "summary": { "type": "string" }, "quote": { "type": "object", "additionalProperties": {}, "description": "Raw and normalized Yahoo Finance market quote data" }, "fundamentals": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Comprehensive financial statement and valuation metrics" }, "technicals": { "type": "object", "additionalProperties": {}, "description": "Multi-oscillator technical indicator matrix (SMA, EMA, RSI, MACD, Bollinger, ATR)" }, "secEdgar": { "type": "object", "additionalProperties": {}, "description": "SEC Edgar regulatory filings, audited disclosures, and XBRL facts" }, "sec": { "type": "object", "additionalProperties": {} }, "rating": { "type": "object", "additionalProperties": {}, "description": "Decisive quantitative composite scoring breakdown and weights" }, "disclaimer": { "type": "string" } }, "required": [ "id", "assetId", "ticker", "companyName", "assetClass", "asOfDate", "generatedAt", "expiresAt", "summary", "quote", "fundamentals", "technicals", "rating", "disclaimer" ] }, "X402Challenge": { "type": "object", "properties": { "network": { "type": "string", "example": "base" }, "chainId": { "type": "integer", "example": 8453 }, "tokenAddress": { "type": "string", "example": "0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2" }, "tokenSymbol": { "type": "string", "example": "USDT" }, "decimals": { "type": "integer", "example": 6 }, "amount": { "type": "string", "example": "1000000" }, "amountFormatted": { "type": "string", "example": "1.00 USDT" }, "recipientAddress": { "type": "string", "example": "0x1234567890123456789012345678901234567890" }, "ticker": { "type": "string", "example": "AAPL" }, "reportId": { "type": [ "string", "null" ], "format": "uuid", "example": "b18b4827-0240-4d56-8fb5-48b488ba30d2" } }, "required": [ "network", "chainId", "tokenAddress", "tokenSymbol", "decimals", "amount", "amountFormatted", "recipientAddress", "ticker" ] }, "X402ChallengeResponse": { "type": "object", "properties": { "error": { "type": "string", "example": "Payment Required" }, "status": { "type": "integer", "example": 402 }, "message": { "type": "string", "example": "Full institutional report is locked. Settle micropayment on Base network or submit purchase token." }, "challenge": { "type": "object", "properties": { "network": { "type": "string", "example": "base" }, "chainId": { "type": "integer", "example": 8453 }, "tokenAddress": { "type": "string", "example": "0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2" }, "tokenSymbol": { "type": "string", "example": "USDT" }, "decimals": { "type": "integer", "example": 6 }, "amount": { "type": "string", "example": "1000000" }, "amountFormatted": { "type": "string", "example": "1.00 USDT" }, "recipientAddress": { "type": "string", "example": "0x1234567890123456789012345678901234567890" }, "ticker": { "type": "string", "example": "AAPL" }, "reportId": { "type": [ "string", "null" ], "format": "uuid", "example": "b18b4827-0240-4d56-8fb5-48b488ba30d2" } }, "required": [ "network", "chainId", "tokenAddress", "tokenSymbol", "decimals", "amount", "amountFormatted", "recipientAddress", "ticker" ] }, "instructions": { "type": "string", "example": "Execute an ERC-20 transfer of 1,000,000 units (1.00 USDT) to recipientAddress on Base (Chain ID 8453). Then re-request this endpoint with header 'X-402-Payment-Signature: '." } }, "required": [ "error", "status", "message", "challenge", "instructions" ] }, "VerifyUsdtRequest": { "type": "object", "properties": { "txHash": { "type": "string", "minLength": 1, "pattern": "^0x[a-fA-F0-9]{64}$", "description": "Base network transaction hash confirming the 1.00 USDT transfer", "example": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" }, "ticker": { "type": "string", "minLength": 1, "description": "Target asset ticker symbol", "example": "AAPL" }, "reportId": { "type": "string", "format": "uuid", "description": "Optional specific report snapshot UUID", "example": "b18b4827-0240-4d56-8fb5-48b488ba30d2" }, "minConfirmations": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1, "description": "Optional minimum required block confirmations", "example": 1 } }, "required": [ "txHash" ] }, "VerifyUsdtResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "purchaseId": { "type": "string", "format": "uuid", "example": "c9284249-1123-4a11-8173-982348571290" }, "reportId": { "type": "string", "format": "uuid", "example": "b18b4827-0240-4d56-8fb5-48b488ba30d2" }, "ticker": { "type": "string", "example": "AAPL" }, "paymentMethod": { "type": "string", "enum": [ "usdt" ], "example": "usdt" }, "txHash": { "type": "string", "example": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" }, "payerAddress": { "type": "string", "example": "0x5678901234567890123456789012345678901234" }, "recipientAddress": { "type": "string", "example": "0x1234567890123456789012345678901234567890" }, "amountPaid": { "type": "number", "example": 1 }, "accessToken": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "blockNumber": { "type": "string", "example": "22918234" } }, "required": [ "success", "purchaseId", "reportId", "ticker", "paymentMethod", "txHash", "payerAddress", "recipientAddress", "amountPaid", "accessToken", "blockNumber" ] }, "VerifyAdRequest": { "type": "object", "properties": { "adSessionId": { "type": "string", "minLength": 16, "maxLength": 128, "pattern": "^[a-zA-Z0-9_\\-.:]{16,128}$", "description": "Unique ad session identifier from the rewarded ad SDK", "example": "sess_892348571290" }, "clientId": { "type": "string", "minLength": 1, "description": "Configured publisher client ID", "example": "pub_lifestok_main" }, "rewardToken": { "type": "string", "description": "Verification reward token issued upon completed playback", "example": "rew_token_7182937491" }, "signature": { "type": "string", "description": "HMAC or cryptographic callback signature", "example": "hmac_signature_hex" }, "timestamp": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "description": "Unix epoch millisecond timestamp of ad completion", "example": 1762155600000 }, "ticker": { "type": "string", "minLength": 1, "description": "Target asset ticker symbol", "example": "AAPL" }, "reportId": { "type": "string", "format": "uuid", "description": "Optional target report UUID", "example": "b18b4827-0240-4d56-8fb5-48b488ba30d2" } }, "required": [ "adSessionId", "clientId" ] }, "VerifyAdResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "purchaseId": { "type": "string", "format": "uuid", "example": "e1903847-5819-4820-bca1-928475819203" }, "reportId": { "type": "string", "format": "uuid", "example": "b18b4827-0240-4d56-8fb5-48b488ba30d2" }, "ticker": { "type": "string", "example": "AAPL" }, "paymentMethod": { "type": "string", "enum": [ "ad" ], "example": "ad" }, "adSessionId": { "type": "string", "example": "sess_892348571290" }, "accessToken": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "verifiedAt": { "type": "string", "example": "2026-11-03T07:40:00.000Z" } }, "required": [ "success", "purchaseId", "reportId", "ticker", "paymentMethod", "adSessionId", "accessToken", "verifiedAt" ] } }, "parameters": {} }, "paths": { "/api/assets/search": { "get": { "tags": [ "Assets" ], "summary": "Search assets across stock, ETF, crypto, forex, commodity", "description": "Performs real-time ticker and symbol search across all 5 asset classes (stock, etf, crypto, forex, commodity) using primary market data from Yahoo Finance.", "operationId": "searchAssets", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Search query string (ticker symbol or entity name, e.g. 'AAPL', 'BTC', 'Crude')", "example": "AAPL" }, "required": true, "description": "Search query string (ticker symbol or entity name, e.g. 'AAPL', 'BTC', 'Crude')", "name": "q", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10, "description": "Maximum number of search results to return (1 to 50, default: 10)", "example": 10 }, "required": false, "description": "Maximum number of search results to return (1 to 50, default: 10)", "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "stock", "etf", "crypto", "forex", "commodity" ], "description": "Filter results to a specific asset class", "example": "stock" }, "required": false, "description": "Filter results to a specific asset class", "name": "assetClass", "in": "query" } ], "responses": { "200": { "description": "Successful search match across assets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetSearchResponse" } } } }, "400": { "description": "Missing or invalid search query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal service error during asset search", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/reports/{ticker}/preview": { "get": { "tags": [ "Reports" ], "summary": "Get free blurred teaser preview for an asset report", "description": "Generates or retrieves a free unauthenticated teaser snapshot of the comprehensive institutional intelligence report. The preview provides the top-level quantitative composite rating score, current summary metrics, and unblurred strengths/weaknesses teaser bullets while blurring full valuation matrices, forensic SEC Edgar XBRL facts, and technical indicator models.", "operationId": "getReportPreview", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Target asset ticker symbol (e.g. 'AAPL', 'BTC-USD', 'EURUSD=X', 'GC=F')", "example": "AAPL" }, "required": true, "description": "Target asset ticker symbol (e.g. 'AAPL', 'BTC-USD', 'EURUSD=X', 'GC=F')", "name": "ticker", "in": "path" } ], "responses": { "200": { "description": "Teaser report preview successfully generated or retrieved from cache", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicReportPreview" } } } }, "400": { "description": "Malformed or invalid asset ticker format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Asset ticker was not recognized or found in primary market catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Upstream failure fetching market or regulatory filing data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/reports/{ticker}/full": { "get": { "tags": [ "Reports" ], "summary": "Get complete institutional financial report", "description": "Retrieves the full institutional-grade intelligence report including complete DCF valuation, multi-oscillator technical indicator arrays, full SEC Edgar XBRL forensic disclosures, and the composite rating breakdown. Access requires either a valid signed JWT purchase access token or an on-chain x402 settlement.", "operationId": "getFullReport", "security": [ { "BearerAuth": [] }, { "X402Signature": [] }, { "XAccessToken": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Target asset ticker symbol (e.g. 'AAPL', 'BTC-USD', 'EURUSD=X', 'GC=F')", "example": "AAPL" }, "required": true, "description": "Target asset ticker symbol (e.g. 'AAPL', 'BTC-USD', 'EURUSD=X', 'GC=F')", "name": "ticker", "in": "path" }, { "schema": { "type": "string", "description": "Bearer JWT purchase access token", "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "required": false, "description": "Bearer JWT purchase access token", "name": "Authorization", "in": "header" }, { "schema": { "type": "string", "description": "Base network 64-hex transaction hash proving 1.00 USDT settlement", "example": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" }, "required": false, "description": "Base network 64-hex transaction hash proving 1.00 USDT settlement", "name": "X-402-Payment-Signature", "in": "header" }, { "schema": { "type": "string", "description": "Signed JWT purchase access token header", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "required": false, "description": "Signed JWT purchase access token header", "name": "x-access-token", "in": "header" } ], "responses": { "200": { "description": "Full report successfully unlocked and retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FullReportSnapshot" } } } }, "400": { "description": "Invalid ticker symbol parameter format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Invalid or malformed purchase access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Micropayment required. Settle 1.00 USDT on Base network per x402 challenge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402ChallengeResponse" } } } }, "404": { "description": "Asset ticker not found or report generation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal intelligence pipeline failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/reports/{ticker}/download": { "get": { "tags": [ "Reports" ], "summary": "Download unlocked report as PDF or JSON", "description": "Downloads an unlocked institutional report as either a structured JSON document or an institutional-quality binary PDF document with embedded charts and tables.", "operationId": "downloadReport", "security": [ { "BearerAuth": [] }, { "XAccessToken": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Target asset ticker symbol", "example": "AAPL" }, "required": true, "description": "Target asset ticker symbol", "name": "ticker", "in": "path" }, { "schema": { "type": "string", "enum": [ "pdf", "json" ], "default": "pdf", "description": "Requested export format", "example": "pdf" }, "required": false, "description": "Requested export format", "name": "format", "in": "query" }, { "schema": { "type": "string", "description": "Signed JWT purchase access token query parameter" }, "required": false, "description": "Signed JWT purchase access token query parameter", "name": "accessToken", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Specific report snapshot UUID to download" }, "required": false, "description": "Specific report snapshot UUID to download", "name": "reportId", "in": "query" }, { "schema": { "type": "string", "description": "Bearer JWT purchase access token", "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "required": false, "description": "Bearer JWT purchase access token", "name": "Authorization", "in": "header" }, { "schema": { "type": "string", "description": "Signed JWT purchase access token header" }, "required": false, "description": "Signed JWT purchase access token header", "name": "x-access-token", "in": "header" } ], "responses": { "200": { "description": "Binary PDF stream or structured JSON document", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/FullReportSnapshot" } } } }, "400": { "description": "Invalid format parameter or malformed ticker symbol", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, expired, or invalid purchase access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Token was issued for a different ticker or report ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Report record does not exist in database", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "PDF compilation failure or internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/payments/verify-usdt": { "post": { "tags": [ "Payments" ], "summary": "Verify Base USDT transfer and issue access token", "description": "Verifies an on-chain ERC-20 transfer of 1.00 USDT on Base network to the designated recipient wallet address. Upon successful verification, records the purchase, issues a signed JWT access token, and unlocks the complete report.", "operationId": "verifyUsdtPayment", "requestBody": { "description": "On-chain transaction hash and target ticker to verify", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyUsdtRequest" } } } }, "responses": { "200": { "description": "Transfer successfully verified and JWT purchase access token issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyUsdtResponse" } } } }, "400": { "description": "Invalid transaction hash format, missing payload fields, or wrong recipient/token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Target asset ticker or report does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Transaction hash has already been redeemed for an active report purchase", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Transfer amount is insufficient (< 1.00 USDT) or transaction has not achieved minimum confirmations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "RPC communication error or internal verification failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/payments/verify-ad": { "post": { "tags": [ "Payments" ], "summary": "Verify rewarded ad completion and issue access token", "description": "Validates a cryptographic rewarded video ad completion callback from the client ad SDK. Verifies the publisher signature and idempotency of the session ID, records the purchase, and issues a signed JWT access token.", "operationId": "verifyAdPayment", "requestBody": { "description": "Rewarded ad session proof and cryptographic verification payload", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyAdRequest" } } } }, "responses": { "200": { "description": "Rewarded ad verified and JWT purchase access token issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyAdResponse" } } } }, "400": { "description": "Missing required verification fields or timestamp expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Invalid cryptographic signature on rewarded ad token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Unrecognized publisher client identifier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Target asset ticker or report does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Ad session ID has already been redeemed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Database failure or internal verification error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "webhooks": {} }