{"openapi":"3.1.0","info":{"title":"Murmurr API","version":"0.1.0","description":"Murmurr HTTP API. **Every data route requires `x-api-key`** (same value as `API_SECRET_KEY`). Landing, `/docs`, `/openapi.json`, `/health`, and GitHub `/hooks/*` are exempt."},"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Product","description":"App hub + vault detail - Lagoon GraphQL and Morpho vaultV2 GraphQL."},{"name":"Metrics","description":"Live Lagoon vault TVL and APR for the Murmurr meta-vault."},{"name":"Morpho","description":"Morpho Blue market data for Murmurr allocation research."},{"name":"Pharos","description":"Stablecoin peg, liquidity, and safety data from pharos.watch."},{"name":"Ops","description":"Operational data from Postgres collectors (NAV, drift, freshness)."}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"VaultRef":{"type":"object","properties":{"address":{"type":"string"},"chainId":{"type":"integer"},"name":{"type":"string","nullable":true},"symbol":{"type":"string","nullable":true},"assetSymbol":{"type":"string"}},"required":["address","chainId","name","symbol","assetSymbol"]},"VaultMetricsResponse":{"type":"object","properties":{"totalDeposits":{"type":"number","description":"Current vault TVL in asset units (e.g. USDC)","example":111617.14},"totalDepositsUsd":{"type":"number","nullable":true,"description":"Current vault TVL in USD when provided by Lagoon","example":111585.89},"currentApy":{"type":"number","nullable":true,"description":"Current APY: trailing 7D linear net APR, falling back to 30D then inception","example":4.8},"apy30d":{"type":"number","nullable":true},"apy7d":{"type":"number","nullable":true},"apyInception":{"type":"number","nullable":true},"vault":{"$ref":"#/components/schemas/VaultRef"},"updatedAt":{"type":"string","format":"date-time"}},"required":["totalDeposits","totalDepositsUsd","currentApy","apy30d","apy7d","apyInception","vault","updatedAt"]},"MetricsErrorResponse":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"ProductVaultOverview":{"type":"object","properties":{"vaultKey":{"type":"string"},"address":{"type":"string"},"chainId":{"type":"integer"},"provider":{"type":"string"},"displayName":{"type":"string"},"network":{"type":"string"},"assetSymbol":{"type":"string"},"depositsUsd":{"type":"number","nullable":true},"liquidityUsd":{"type":"number","nullable":true},"apy":{"type":"number","nullable":true},"apy30d":{"type":"number","nullable":true},"apy7d":{"type":"number","nullable":true},"curatorName":{"type":"string","nullable":true},"curatorImage":{"type":"string","nullable":true},"collaterals":{"type":"array","items":{"type":"string"}},"found":{"type":"boolean"},"error":{"type":"string"}},"required":["vaultKey","address","chainId","provider","displayName","network","assetSymbol","depositsUsd","liquidityUsd","apy","apy30d","apy7d","curatorName","curatorImage","collaterals","found"]},"ProductVaultOverviewResponse":{"type":"object","properties":{"updatedAt":{"type":"string","format":"date-time"},"vaults":{"type":"array","items":{"$ref":"#/components/schemas/ProductVaultOverview"}}},"required":["updatedAt","vaults"]},"MarketPharosSummary":{"type":"object","nullable":true,"properties":{"marketScore":{"type":"number","nullable":true},"investable":{"type":"boolean"},"detail":{"type":"string"},"loanScore":{"type":"number","nullable":true},"collateralScore":{"type":"number","nullable":true}},"required":["marketScore","investable","detail","loanScore","collateralScore"]},"CuratorRisk":{"type":"object","properties":{"marketScore":{"type":"number"},"investable":{"type":"boolean"},"qualityScore":{"type":"number"},"qualitySource":{"type":"string"},"qualityDetail":{"type":"string"},"pharosLoanScore":{"type":"number","nullable":true},"pharosCollateralScore":{"type":"number","nullable":true},"underlyingScore":{"type":"number","nullable":true},"mcapBonus":{"type":"number"},"mcapUsd":{"type":"number","nullable":true},"mcapKind":{"type":"string","nullable":true},"depthBonus":{"type":"number"},"maxSingleMarketPct":{"type":"number"}},"required":["marketScore","investable","qualityScore","qualitySource","qualityDetail","pharosLoanScore","pharosCollateralScore","underlyingScore","mcapBonus","mcapUsd","mcapKind","depthBonus","maxSingleMarketPct"]},"MorphoMarket":{"type":"object","properties":{"marketId":{"type":"string"},"chainId":{"type":"number"},"loanSymbol":{"type":"string"},"loanAddress":{"type":"string"},"loanDecimals":{"type":"number"},"collateralSymbol":{"type":"string"},"collateralAddress":{"type":"string"},"irmAddress":{"type":"string"},"oracleAddress":{"type":"string"},"oracleType":{"type":"string"},"lltv":{"type":"number"},"lltvWad":{"type":"string"},"baseSupplyApy":{"type":"number"},"baseBorrowApy":{"type":"number"},"rewardsApr":{"type":"number"},"totalSupplyApy":{"type":"number"},"supplyApyAtTarget":{"type":"number","nullable":true},"tvl":{"type":"number"},"tvlUsd":{"type":"number"},"totalBorrowed":{"type":"number"},"liquidityAvailable":{"type":"number"},"liquidityUsd":{"type":"number"},"utilization":{"type":"number"},"weeklySupplyApy":{"type":"number","nullable":true},"monthlySupplyApy":{"type":"number","nullable":true},"warnings":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"level":{"type":"string"}},"required":["type","level"]}},"badDebtUsd":{"type":"number"},"realizedBadDebtUsd":{"type":"number"}},"required":["marketId","chainId","loanSymbol","loanAddress","loanDecimals","collateralSymbol","collateralAddress","irmAddress","oracleAddress","lltv","lltvWad","baseSupplyApy","baseBorrowApy","rewardsApr","totalSupplyApy","supplyApyAtTarget","tvl","tvlUsd","totalBorrowed","liquidityAvailable","liquidityUsd","utilization","weeklySupplyApy","monthlySupplyApy","warnings","badDebtUsd","realizedBadDebtUsd"]},"ResearchMarket":{"allOf":[{"$ref":"#/components/schemas/MorphoMarket"},{"type":"object","properties":{"pharos":{"$ref":"#/components/schemas/MarketPharosSummary"},"curator":{"$ref":"#/components/schemas/CuratorRisk"}},"required":["pharos","curator"]}]},"LoanAssetFilter":{"type":"object","properties":{"symbol":{"type":"string"},"address":{"type":"string"}},"required":["symbol","address"]},"MarketFilters":{"type":"object","properties":{"chainId":{"type":"number","example":1},"chainLabel":{"type":"string","example":"Ethereum"},"loanSymbol":{"type":"string","example":"USDC"},"loanAssets":{"type":"array","items":{"$ref":"#/components/schemas/LoanAssetFilter"}},"minTvlUsd":{"type":"number","example":1000000},"minLiquidityUsd":{"type":"number","example":100000},"minSupplyApyPct":{"type":"number","example":6},"watchMinSupplyApyPct":{"type":"number","example":4},"hardFilter":{"type":"boolean","enum":[true]}},"required":["chainId","chainLabel","loanSymbol","loanAssets","minTvlUsd","minLiquidityUsd","minSupplyApyPct","watchMinSupplyApyPct","hardFilter"]},"MorphoMarketsResponse":{"type":"object","properties":{"markets":{"type":"array","items":{"$ref":"#/components/schemas/ResearchMarket"}},"count":{"type":"number"},"watchMarkets":{"type":"array","items":{"$ref":"#/components/schemas/ResearchMarket"}},"watchCount":{"type":"number"},"chainId":{"type":"number"},"filters":{"$ref":"#/components/schemas/MarketFilters"},"availableLoanSymbols":{"type":"array","items":{"type":"string"}},"updatedAt":{"type":"string","format":"date-time"},"pharosEnabled":{"type":"boolean"},"pharosError":{"type":"string"},"pharosEligibleCount":{"type":"number"},"pharosIneligibleCount":{"type":"number"},"curatorEligibleCount":{"type":"number"},"curatorIneligibleCount":{"type":"number"}},"required":["markets","count","watchMarkets","watchCount","chainId","filters","availableLoanSymbols","updatedAt","pharosEnabled","pharosEligibleCount","pharosIneligibleCount","curatorEligibleCount","curatorIneligibleCount"]},"MorphoErrorResponse":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}},"parameters":{}},"paths":{"/metrics":{"get":{"tags":["Metrics"],"summary":"Current APY and total deposits for the Murmurr vault","description":"Returns live vault metrics from the Lagoon GraphQL API for the configured Murmurr vault\n(Ethereum, `0x7d2c2f54792ad72cb834d298f542145b06b703cb`).\n\n**Total deposits** maps to Lagoon `state.totalAssets` (current TVL, not cumulative deposit history).\n**Current APY** uses the 30-day linear net APR, with fallbacks to inception then 7-day APR.","responses":{"200":{"description":"Vault metrics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VaultMetricsResponse"}}}},"502":{"description":"Lagoon API query failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsErrorResponse"}}}}}}},"/metrics/{chainId}/{address}":{"get":{"tags":["Metrics"],"summary":"Current APY and total deposits for a Lagoon vault","parameters":[{"schema":{"type":"string","description":"Chain ID (1 = Ethereum)","example":"1"},"required":true,"name":"chainId","in":"path"},{"schema":{"type":"string","description":"Vault contract address","example":"0x7d2c2f54792ad72cb834d298f542145b06b703cb"},"required":true,"name":"address","in":"path"}],"responses":{"200":{"description":"Vault metrics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VaultMetricsResponse"}}}},"400":{"description":"Invalid chainId or address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsErrorResponse"}}}},"404":{"description":"Unknown vault","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsErrorResponse"}}}},"502":{"description":"Lagoon API query failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsErrorResponse"}}}}}}},"/overview":{"get":{"tags":["Product"],"summary":"Hub overview for all visible product vaults","description":"Batch TVL / APY for Lagoon + Morpho product vaults (Lagoon GraphQL + Morpho vaultV2 GraphQL).","responses":{"200":{"description":"Overview rows","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductVaultOverviewResponse"}}}}}}},"/morpho/markets":{"get":{"tags":["Morpho"],"summary":"Filtered Morpho Blue markets (Innovation)","description":"Fetches live market data from the Morpho Blue GraphQL API.\n\n**Defaults:** Ethereum, USDC loan.\n\n**Hard filters:** stablecoin loan asset(s), market size ≥ $1M, liquidity ≥ $100k, total supply APY ≥ 6%.\n\nUse `chainId` (1 / 8453 / 42161 / 999 / 143) to scope opportunities.\nOverride size filters via `minTvlUsd` and `minLiquidityUsd` (set to `0` to disable).","parameters":[{"schema":{"type":"string","example":"1"},"required":false,"name":"chainId","in":"query"},{"schema":{"type":"string","example":"1000000"},"required":false,"name":"minTvlUsd","in":"query"},{"schema":{"type":"string","example":"100000"},"required":false,"name":"minLiquidityUsd","in":"query"}],"responses":{"200":{"description":"Morpho markets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MorphoMarketsResponse"}}}},"502":{"description":"Morpho API query failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MorphoErrorResponse"}}}}}}},"/morpho/markets/{marketId}":{"get":{"tags":["Morpho"],"summary":"Single Morpho market","parameters":[{"schema":{"type":"string","description":"Morpho market unique key (0x + 64 hex)"},"required":true,"name":"marketId","in":"path"}],"responses":{"200":{"description":"Market","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MorphoMarket"}}}},"404":{"description":"Market not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MorphoErrorResponse"}}}},"502":{"description":"Morpho API query failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MorphoErrorResponse"}}}}}}}}}