{"openapi":"3.1.0","info":{"title":"Api","version":"0.1.0","description":"x402 API Data Tollbooth"},"servers":[{"url":"/api","description":"Base API path"}],"tags":[{"name":"health","description":"Health operations"},{"name":"admin","description":"Admin revenue panel"},{"name":"data-hub","description":"Paywalled data endpoints (x402 Solana USDC, 0.005 USDC/request)"}],"paths":{"/healthz":{"get":{"operationId":"healthCheck","tags":["health"],"summary":"Health check","responses":{"200":{"description":"Healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthStatus"}}}}}}},"/admin/data-hub/wallet-balance":{"get":{"operationId":"getWalletBalance","tags":["admin"],"summary":"Get live USDC balance of the operator wallet","responses":{"200":{"description":"Wallet balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletBalance"}}}}}}},"/admin/data-hub/stats":{"get":{"operationId":"getAdminStats","tags":["admin"],"summary":"Get aggregate revenue stats","responses":{"200":{"description":"Revenue statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminStats"}}}}}}},"/admin/data-hub/ledger":{"get":{"operationId":"getLedgerEntries","tags":["admin"],"summary":"Get recent ledger entries","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Ledger entries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LedgerPage"}}}}}}},"/admin/data-hub/revenue-timeseries":{"get":{"operationId":"getRevenueTimeseries","tags":["admin"],"summary":"Get cumulative revenue over time (hourly buckets)","responses":{"200":{"description":"Revenue timeseries","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RevenuePoint"}}}}}}}},"/v1/data-hub/sample":{"get":{"operationId":"getSampleData","tags":["data-hub"],"summary":"Sample paywalled data (preview)","description":"Requires X-PAYMENT header with valid x402 Solana USDC transaction (0.005 USDC).\nReturns a preview record. See /v1/data-hub/market and /v1/data-hub/trends for full feeds.\n","responses":{"200":{"description":"Structured data payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataPayload"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}},"/v1/data-hub/market":{"get":{"operationId":"getMarketFeed","tags":["data-hub"],"summary":"Live crypto market intelligence feed","description":"Real-time structured market intelligence: top-20 crypto asset quotes, 24h momentum,\nsector summaries, BTC/ETH dominance, and an aggregated market signal (risk-on / risk-off).\nData sourced live from public market APIs. Refreshed on every request.\nRequires X-PAYMENT header with valid x402 Solana USDC transaction (0.005 USDC).\n","responses":{"200":{"description":"Market intelligence payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketFeedPayload"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}},"/v1/data-hub/trends":{"get":{"operationId":"getTrendFeed","tags":["data-hub"],"summary":"Web intelligence & trend feed","description":"Structured web intelligence: trending topics with velocity scores, emerging entities,\nsector heat indices, and anomaly flags. Covers AI, crypto, data, and fintech domains.\nRefreshed hourly. Requires X-PAYMENT header with valid x402 Solana USDC transaction (0.005 USDC).\n","responses":{"200":{"description":"Trend intelligence payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrendFeedPayload"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}},"/v1/data-hub/legal":{"get":{"operationId":"getLegalFeed","tags":["data-hub"],"summary":"Legal & regulatory intelligence feed","description":"Real-time SEC EDGAR filings (8-K material events, S-1 IPO registrations, 10-K annuals,\nSC 13D activist positions), patent applications in AI/fintech/data sectors, and\nregulatory alerts from SEC, CFPB, FTC, and FinCEN. Live EDGAR data refreshed hourly.\nPremium tier: 0.020 USDC per request.\nRequires X-PAYMENT header with valid x402 Solana USDC transaction.\n","responses":{"200":{"description":"Legal intelligence payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegalFeedPayload"}}}},"402":{"description":"Payment required (0.020 USDC)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}},"/v1/data-hub/stocks":{"get":{"operationId":"getStockFeed","tags":["data-hub"],"summary":"Live US equity market intelligence feed","description":"Real-time structured stock data: top-20 US equities (S&P 500 components) with prices,\nP/E ratios, 52-week range, sector performance, market breadth, and index snapshots\n(S&P 500, Dow, NASDAQ, VIX). Includes market status (open/closed/pre-market/after-hours).\nSourced live from public market data. Refreshed on every request.\nRequires X-PAYMENT header with valid x402 Solana USDC transaction (0.005 USDC).\n","responses":{"200":{"description":"Stock intelligence payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockFeedPayload"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}},"/v1/data-hub/entities":{"get":{"operationId":"getEntityFeed","tags":["data-hub"],"summary":"Company & entity intelligence feed","description":"Structured company profiles and funding intelligence across high-growth sectors.\nIncludes headcount, funding history, tech stack, hiring velocity signals, and\ninvestment scores for tracked companies. Covers 4,820+ companies.\nRefreshed daily. Requires X-PAYMENT header with valid x402 Solana USDC transaction (0.005 USDC).\n","responses":{"200":{"description":"Entity intelligence payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityFeedPayload"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}},"/v1/data-hub/real-estate":{"get":{"operationId":"getRealEstateFeed","tags":["data-hub"],"summary":"Real estate intelligence feed","description":"Structured property listings and metro market conditions across 148 US metros.\nIncludes cap rates, gross yields, investment grades, absorption rates, and\nmarket condition signals. Refreshed daily.\nRequires X-PAYMENT header with valid x402 Solana USDC transaction (0.005 USDC).\n","responses":{"200":{"description":"Real estate intelligence payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RealEstateFeedPayload"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}}},"components":{"schemas":{"HealthStatus":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}}},"AdminStats":{"type":"object","required":["totalRevenueUsdc","totalHits","uniqueCrawlers","avgFeeUsdc"],"properties":{"totalRevenueUsdc":{"type":"string"},"totalHits":{"type":"integer"},"uniqueCrawlers":{"type":"integer"},"avgFeeUsdc":{"type":"string"}}},"LedgerEntry":{"type":"object","required":["id","timestamp","transactionSignature","amountUsdc","endpointAccessed"],"properties":{"id":{"type":"integer"},"timestamp":{"type":"string"},"crawlerName":{"type":["string","null"]},"transactionSignature":{"type":"string"},"amountUsdc":{"type":"string"},"endpointAccessed":{"type":"string"}}},"LedgerPage":{"type":"object","required":["entries","total"],"properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/LedgerEntry"}},"total":{"type":"integer"}}},"RevenuePoint":{"type":"object","required":["bucket","cumulativeUsdc"],"properties":{"bucket":{"type":"string"},"cumulativeUsdc":{"type":"string"}}},"DataPayload":{"type":"object","required":["feed","retrievedAt"],"properties":{"feed":{"type":"string"},"retrievedAt":{"type":"string"},"records":{"type":"array","items":{"type":"object"}}}},"MarketFeedPayload":{"type":"object","required":["feed","retrievedAt","marketSignal","dominance","assets","sectorSummary"],"properties":{"feed":{"type":"string"},"retrievedAt":{"type":"string"},"marketSignal":{"type":"string","enum":["risk-on","risk-off","neutral"]},"dominance":{"type":"object","required":["btc","eth","alts"],"properties":{"btc":{"type":"number"},"eth":{"type":"number"},"alts":{"type":"number"}}},"assets":{"type":"array","items":{"type":"object","required":["symbol","name","priceUsd","change24hPct","marketCapUsd","volume24hUsd","momentum"],"properties":{"symbol":{"type":"string"},"name":{"type":"string"},"priceUsd":{"type":"number"},"change24hPct":{"type":"number"},"marketCapUsd":{"type":"number"},"volume24hUsd":{"type":"number"},"ath":{"type":"number"},"athChangePct":{"type":"number"},"momentum":{"type":"string","enum":["bullish","bearish","neutral"]}}}},"sectorSummary":{"type":"array","items":{"type":"object","required":["name","avgChange24hPct"],"properties":{"name":{"type":"string"},"avgChange24hPct":{"type":"number"}}}},"dataSource":{"type":"string"}}},"TrendFeedPayload":{"type":"object","required":["feed","retrievedAt","periodHours","contentHeatIndex","trendingTopics","emergingEntities","sectorVelocity"],"properties":{"feed":{"type":"string"},"retrievedAt":{"type":"string"},"periodHours":{"type":"integer"},"contentHeatIndex":{"type":"string","enum":["low","medium","high","extreme"]},"trendingTopics":{"type":"array","items":{"type":"object","required":["topic","category","velocityScore","searchMomentum","relatedEntities","firstSeen"],"properties":{"topic":{"type":"string"},"category":{"type":"string"},"velocityScore":{"type":"number"},"searchMomentum":{"type":"string","enum":["accelerating","peaking","declining"]},"relatedEntities":{"type":"array","items":{"type":"string"}},"firstSeen":{"type":"string"}}}},"emergingEntities":{"type":"array","items":{"type":"object","required":["name","type","heatScore","sectors","signal"],"properties":{"name":{"type":"string"},"type":{"type":"string"},"heatScore":{"type":"number"},"sectors":{"type":"array","items":{"type":"string"}},"signal":{"type":"string"}}}},"sectorVelocity":{"type":"array","items":{"type":"object","required":["sector","score","direction"],"properties":{"sector":{"type":"string"},"score":{"type":"number"},"direction":{"type":"string","enum":["up","down","flat"]}}}},"anomalyFlags":{"type":"array","items":{"type":"string"}}}},"StockFeedPayload":{"type":"object","required":["feed","retrievedAt","marketStatus","indices","equities","sectorPerformance","breadth"],"properties":{"feed":{"type":"string"},"retrievedAt":{"type":"string"},"marketStatus":{"type":"string","enum":["open","closed","pre-market","after-hours"]},"dataSource":{"type":"string"},"indices":{"type":"array","items":{"type":"object","required":["name","value","change1dPct"],"properties":{"name":{"type":"string"},"value":{"type":"number"},"change1dPct":{"type":"number"}}}},"equities":{"type":"array","items":{"type":"object","required":["symbol","name","exchange","sector","priceUsd","change1dUsd","change1dPct","change52wPct","marketCapUsd","volume","momentum"],"properties":{"symbol":{"type":"string"},"name":{"type":"string"},"exchange":{"type":"string"},"sector":{"type":"string"},"priceUsd":{"type":"number"},"change1dUsd":{"type":"number"},"change1dPct":{"type":"number"},"change52wPct":{"type":"number"},"marketCapUsd":{"type":"number"},"volume":{"type":"number"},"avgVolume30d":{"type":"number"},"peRatio":{"type":["number","null"]},"eps":{"type":["number","null"]},"dividendYieldPct":{"type":["number","null"]},"fiftyTwoWeekHighUsd":{"type":"number"},"fiftyTwoWeekLowUsd":{"type":"number"},"pctFromHigh":{"type":"number"},"momentum":{"type":"string","enum":["bullish","bearish","neutral"]}}}},"sectorPerformance":{"type":"array","items":{"type":"object","required":["sector","change1dPct","leader"],"properties":{"sector":{"type":"string"},"change1dPct":{"type":"number"},"leader":{"type":"string"}}}},"breadth":{"type":"object","required":["advancing","declining","unchanged","bullishRatio"],"properties":{"advancing":{"type":"integer"},"declining":{"type":"integer"},"unchanged":{"type":"integer"},"bullishRatio":{"type":"number"}}}}},"EntityFeedPayload":{"type":"object","required":["feed","retrievedAt","periodDays","totalCompaniesTracked","companies","recentFunding","sectorActivity","marketPulse"],"properties":{"feed":{"type":"string"},"retrievedAt":{"type":"string"},"periodDays":{"type":"integer"},"totalCompaniesTracked":{"type":"integer"},"marketPulse":{"type":"string","enum":["active","cautious","hot"]},"companies":{"type":"array","items":{"type":"object","required":["name","domain","sector","stage","headcount","headcountGrowth90dPct","totalFundingUsd","lastRoundUsd","lastRoundDate","lastRoundType","techStack","hiringSignal","investmentScore"],"properties":{"name":{"type":"string"},"domain":{"type":"string"},"sector":{"type":"string"},"stage":{"type":"string"},"headcount":{"type":"integer"},"headcountGrowth90dPct":{"type":"number"},"totalFundingUsd":{"type":"number"},"lastRoundUsd":{"type":"number"},"lastRoundDate":{"type":"string"},"lastRoundType":{"type":"string"},"techStack":{"type":"array","items":{"type":"string"}},"hiringSignal":{"type":"string","enum":["aggressive","steady","slowing","freeze"]},"investmentScore":{"type":"integer"}}}},"recentFunding":{"type":"array","items":{"type":"object","required":["company","amount_usd","round","lead_investor","date","sector"],"properties":{"company":{"type":"string"},"amount_usd":{"type":"number"},"round":{"type":"string"},"lead_investor":{"type":"string"},"date":{"type":"string"},"sector":{"type":"string"}}}},"sectorActivity":{"type":"array","items":{"type":"object","required":["sector","dealCount","totalUsd","avgRoundUsd"],"properties":{"sector":{"type":"string"},"dealCount":{"type":"integer"},"totalUsd":{"type":"number"},"avgRoundUsd":{"type":"number"}}}}}},"RealEstateFeedPayload":{"type":"object","required":["feed","retrievedAt","coverageMetros","listings","metroMarkets","nationalSummary"],"properties":{"feed":{"type":"string"},"retrievedAt":{"type":"string"},"coverageMetros":{"type":"integer"},"listings":{"type":"array","items":{"type":"object","required":["listingId","address","metro","state","propertyType","sqft","listPriceUsd","pricePerSqft","daysOnMarket","investmentGrade","signals"],"properties":{"listingId":{"type":"string"},"address":{"type":"string"},"metro":{"type":"string"},"state":{"type":"string"},"propertyType":{"type":"string"},"bedrooms":{"type":["integer","null"]},"bathrooms":{"type":["number","null"]},"sqft":{"type":"integer"},"listPriceUsd":{"type":"number"},"pricePerSqft":{"type":"number"},"daysOnMarket":{"type":"integer"},"priceChangePct":{"type":["number","null"]},"capRate":{"type":["number","null"]},"grossYield":{"type":["number","null"]},"investmentGrade":{"type":"string","enum":["A","B","C","D"]},"signals":{"type":"array","items":{"type":"string"}}}}},"metroMarkets":{"type":"array","items":{"type":"object","required":["metro","state","medianPriceUsd","medianPriceChange90dPct","daysOnMarketMedian","inventoryChange90dPct","absorptionRate","marketCondition","investorActivity"],"properties":{"metro":{"type":"string"},"state":{"type":"string"},"medianPriceUsd":{"type":"number"},"medianPriceChange90dPct":{"type":"number"},"daysOnMarketMedian":{"type":"integer"},"inventoryChange90dPct":{"type":"number"},"absorptionRate":{"type":"number"},"marketCondition":{"type":"string","enum":["sellers","balanced","buyers"]},"investorActivity":{"type":"string","enum":["high","moderate","low"]}}}},"nationalSummary":{"type":"object","required":["medianListPriceUsd","medianDaysOnMarket","priceChangeMoMPct","hottest","coolest"],"properties":{"medianListPriceUsd":{"type":"number"},"medianDaysOnMarket":{"type":"integer"},"priceChangeMoMPct":{"type":"number"},"hottest":{"type":"string"},"coolest":{"type":"string"}}}}},"WalletBalance":{"type":"object","required":["walletAddress","balanceUsdc","fetchedAt"],"properties":{"walletAddress":{"type":"string"},"balanceUsdc":{"type":["string","null"]},"fetchedAt":{"type":"string"},"error":{"type":["string","null"]}}},"PaymentRequired":{"type":"object","required":["error","paymentDetails"],"properties":{"error":{"type":"string"},"paymentDetails":{"type":"object","required":["destinationWallet","amountUsdc","token","network"],"properties":{"destinationWallet":{"type":"string"},"amountUsdc":{"type":"string"},"token":{"type":"string"},"network":{"type":"string"}}}}}}}}