Monitor vault share price with subgraph and Stats

Use Forge subgraph VaultDayData and the /stats dashboard to track NAV, 24h volume, and adapter state — without fake APY constants.

Last updated: May 26, 2026 · Published 2026-05-26

Autonomous treasury agents need a canonical NAV signal for Forge vault shares — not a static APY constant from MCP defaults. The Forge subgraph indexes Core and Middle vault events on Base, rolling daily aggregates into `VaultDayData` entities with `sharePrice`, `totalAssets`, `totalSupply`, and 24h deposit/withdraw volume. The public Stats dashboard reads this data alongside live RPC fallbacks. This guide shows how to monitor vault share price, interpret subgraph fields, handle indexing lag, and wire alerts without inventing TVL or yield numbers.

Why VaultDayData exists

Raw ERC-4626 `Deposit` and `Withdraw` events are immutable facts, but agents plotting NAV over time need daily snapshots. `VaultDayData` stores one row per vault per UTC day with end-of-day style aggregates: `totalAssets`, `totalSupply`, computed `sharePrice`, `depositVolume`, `withdrawVolume`, and `txCount`. Portfolio pages combine `VaultDayData` with `AccountVaultDayData` (per-address `shares` and `assetsUsdc`) for holder-level charts. Schema reference: `subgraph/schema.graphql` in the Forge monorepo.

Stats dashboard — what humans and agents read

Stats is the first-party UI for vault monitoring. It shows live adapter allocation (from RPC), share price, TVL, recent deposit/withdraw events, and 24h volume when subgraph rows exist. Toggle between Base mainnet and Sepolia testnet where configured. Stats explicitly labels subgraph sourcing for volume KPIs — when indexing is down, volume may fall back to RPC log scans with narrower lookback windows.

• Adapter table — live bps, per-adapter TVL share, APY display labels (variable, often projected).
• Share price — ERC-4626 `convertToAssets(1e18)` style read; basis for honest APY derivation.
• 24h volume — today's `VaultDayData.depositVolume + withdrawVolume` when subgraph healthy.
• Recent events — deposits/withdraws from subgraph or paginated RPC logs.
• Network toggle — mainnet Core/Middle vs Sepolia test vaults.

Deriving APY from share price (honest method)

Do not advertise MCP `BASE_APY_BPS` or marketing constants as guaranteed yield. Instead, sample `sharePrice` at day boundaries from `VaultDayData` and compute: `apy ≈ (price_end / price_start)^(365/days) - 1`. Short windows are noisy — smoke-test TVL (~$10 on mainnet as of May 2026) means single deposits move price artifacts. Disclose sample size and unaudited status. Read FORGE emissions vs vault yield before mixing inflationary FORGE subsidies with adapter yield in user copy.

Example agent policy: "Report trailing 30d vault yield only if ≥14 `VaultDayData` rows exist and no adapter timelock executed mid-window." Pair with 48-hour timelock guide to exclude periods where adapter books changed.

GraphQL query patterns

Integrators query the deployed subgraph endpoint (see site Docs for current URL). Typical queries fetch latest `VaultDayData` ordered by `date desc`, or a time series for charts. `Vault` entities link to `adapters` via `AdapterUpdated` handlers. Immutable `Deposit` and `Withdraw` entities support audit trails; daily snapshots power KPI cards.

Indexing lag and failure modes

Subgraphs trail chain head by seconds to minutes under normal load — re-syncs after schema upgrades can take hours. Stats surfaces "subgraph unavailable" fallbacks. Agents making large deposit decisions should read contracts directly via viem/ethers when subgraph age exceeds policy threshold (e.g. >50 blocks). Public Base RPC endpoints also rate-limit wide `eth_getLogs` scans — Stats caps log pagination for Sepolia compatibility.

• Check subgraph `_meta.block.number` vs chain head before trusting volume KPIs.
• After vault deploy or manifest change, expect empty `VaultDayData` until first daily handler runs.
• Middle vault with `adapterCount = 0` shows zero adapter TVL — not a subgraph bug.
• Share price is still valid with zero volume — yield accrues silently via adapters.

Multi-vault monitoring (Core + Middle)

Forge ships separate `Vault` entities per bucket. Conservative strategy maps to Core fUSDC; Balanced adds Middle fmUSDC. Query each vault's `VaultDayData` independently — do not sum share prices across vaults. Strategy-level reporting weights Core and Middle allocations per Balanced strategy. Infra vault is planned; subgraph manifest will add handlers on deploy.

Portfolio page and AccountVaultDayData

The Portfolio route (when enabled) stitches `AccountVaultDayData` with `VaultDayData.sharePrice` to chart holder NAV without replaying every transfer. Daily `handleBlock` snapshots accounts with `shares > 0`. Until re-sync completes after upgrades, portfolio may fall back to deposit/withdraw replay plus live RPC — document fallback mode in agent UX.

Alerting thresholds for production agents

Suggested monitoring rules (tune to your risk appetite): (1) share price drop >5% in 24h without known market event → pause auto-deposits; (2) `adapterCount` change vs cached value → require human approval; (3) subgraph lag >100 blocks → switch to RPC reads; (4) withdraw volume spike >2× 7d median → liquidity review. None of these are enforced on-chain — agent policy only.

• Webhook on `AdapterUpdated` subgraph event → Slack/PagerDuty.
• Cron every 15m: compare RPC share price vs latest VaultDayData.
• Pre-deposit gate: MCP vault info + Stats adapter table must match.
• Post-withdraw reconcile: `PerformanceFeeCollected` + USDC received.

MCP vs subgraph vs Stats

MCP tools return point-in-time vault metadata and calldata — optimized for transaction building, not historical analytics. Stats/subgraph optimized for charts and KPIs. Use MCP for `forge_deposit` / `forge_withdraw` calldata (MCP guide); use subgraph for NAV time series and volume. Avoid duplicating APY in MCP responses and dashboard — one derived number from share price delta.

Sepolia testnet subgraph

Base Sepolia uses separate subgraph manifest (`subgraph.yaml` vs `subgraph.mainnet.yaml`). Testnet vault addresses differ; USDC is Circle test token `0x036CbD53842c5426634e7929541eC2318f3dCF7e`. Sepolia has zero timelock — adapter books can change instantly. Do not use Sepolia share price trends to predict mainnet behavior.

Frequently asked questions

Why is 24h volume zero on Stats?

Either no deposits/withdraws occurred today, subgraph daily row not yet written, or indexing is catching up. Check recent events table and RPC head.

Does share price include unclaimed FORGE?

No. Share price reflects USDC vault assets via adapters. FORGE Merkle rewards are external to ERC-4626 NAV until claimed and deposited elsewhere.

Can I use Stats API programmatically?

Stats is a Next.js page reading server-side lib helpers — not a public REST API. Query the subgraph GraphQL endpoint directly for automation, or read RPC for authoritative latest price.

How often is VaultDayData updated?

Daily snapshot handlers run per UTC day boundary in subgraph mapping, plus event-driven updates on deposits/withdraws for volume fields. Exact block of snapshot depends on indexer `handleBlock` configuration.

Building a minimal monitoring stack

A production-grade but minimal stack: (1) cron job queries subgraph for latest `VaultDayData` per vault; (2) parallel RPC `eth_call` to `totalAssets` and `totalSupply`; (3) alert if relative delta >0.1%; (4) weekly human review of Stats adapter table vs Basescan. Store receipt logs for deposit/withdraw gasUsed to refine gas limits guide. Avoid duplicating subgraph infrastructure until TVL justifies self-hosting — use deployed Forge endpoint from docs.

TvlChart and empty subgraph states

The site `TvlChart` component shows a placeholder when no `VaultDayData` rows exist yet — common immediately after mainnet deploy or subgraph re-sync. Empty chart ≠ zero TVL; read live RPC TVL on Stats header. First daily snapshot appears after subgraph `handleBlock` crosses UTC midnight with indexed events. Agents should not block deposits solely because charts are empty if RPC TVL and adapters look correct.

Cross-checking MCP APY strings

MCP tools may return illustrative `apyBps` constants for agent planning — these are not realised yield. Always override with share-price-derived APY from `VaultDayData` when writing user reports. CTO brief documents ~3.7% vs 6.5% mismatch risk when marketing copy drifts from on-chain reality. Document your derivation method in agent audit logs for compliance review and revalidate after every adapter timelock execute.

Should agents poll Stats or subgraph directly?

High-frequency trading policies should use subgraph GraphQL with `_meta` block checks. Human weekly reviews can use Stats UI. Neither replaces pre-deposit RPC reads of `adapterCount` during active timelock windows. Cache subgraph responses ≤15 minutes unless head lag exceeds policy threshold. Archive daily CSV exports of `VaultDayData` for long-horizon backtesting.

Summary for agents

Monitor Forge vault health via `VaultDayData.sharePrice` on the subgraph and the Stats dashboard — derive APY from price deltas, not MCP constants. Verify adapter state on RPC before deposits; expect subgraph lag. Core and Middle vaults are separate entities. Contracts unaudited; TVL is early-stage smoke testing. Pair with Conservative strategy, performance fee guide, and Risks & Disclosures. Refresh monitoring runbooks after subgraph manifest upgrades.