> ## Documentation Index > Fetch the complete documentation index at: https://docs.webacy.com/llms.txt > Use this file to discover all available pages before exploring further. # Get Vault TVL History > Returns a daily time series of total value locked (USD) for a single ERC-4626 vault. Each point is a UTC-midnight sample and carries a `quality_flag` describing whether the producer marked the underlying TVL reading as trustworthy. The response also hoists the most recent passing point to a top-level `latest` aggregate so stat-tile consumers can render the current value without paging the full series. **Quality filtering (default):** Samples flagged as `capped`, `diverged`, or `spike` are dropped from the response by default, so the chart line stays clean against producer-side data-quality issues. When this happens, `count` will be smaller than `days` and `filtered_count` reports how many points were excluded — a visible kink in the chart line is expected and does not indicate a missed cron tick. Set `includeFlagged=true` to bypass the filter and receive the raw series with every sample's `quality_flag` populated. **Envelope semantics:** `stale_reason` disambiguates the four post-filter states (`fresh`, `pipeline_lag`, `all_filtered`, `no_samples_yet`); `stale: boolean` is preserved for back-compat (`true` iff `stale_reason !== 'fresh'`). `schema_version` is bumped any time the response shape changes — pin it if you're building a regression harness. Returns 404 when the vault is not in the verified-vaults catalog; tracked vaults with no samples yet still return 200 with `count: 0`, `latest: null`, and `stale_reason: 'no_samples_yet'`. Cached for 5 minutes; the `includeFlagged=true` and default responses are cached in partitioned namespaces so they never cross-pollinate. ## OpenAPI ````yaml GET /vaults/{address}/tvl-history openapi: 3.0.1 info: title: Risk Score API description: API definition for Webacy Risk Scores version: 1.2.0 servers: - url: https://api.webacy.com description: Webacy Risk Score API (Production) - url: https://api-development.webacy.com description: Webacy Risk Score API (Development) - url: http://0.0.0.0:3030/api/v1/risk-score description: Webacy Risk Score API - Local security: - api_key: [] tags: - name: Threat Risks description: Analyze addresses for security threats and malicious activity - name: Sanction Checks description: Check addresses against OFAC and other sanction lists - name: Approval Risks description: Analyze token approvals and associated risks - name: Transaction Risks description: Assess risk details for blockchain transactions - name: Exposure Risk description: Understand risk profile and exposure of addresses - name: Contract Risk description: Real-time smart contract security analysis - name: URL Risks description: Analyze URLs for phishing and security threats - name: API Usage description: Monitor and manage API consumption - name: Holder Analysis description: Token holder distribution and sniper detection - name: Address Poisoning description: Detect address poisoning attack patterns - name: Token Analysis description: Comprehensive token security and market analysis - name: Pool Analysis description: Liquidity pool data and analysis - name: Transaction Scanning description: Scan and simulate transactions for risks - name: trading-lite description: Lightweight trading risk assessment - name: RWA & Pegged Tokens description: >- Real-world asset and pegged-token analytics (supply flows, mint/burn velocity) - name: Vault Risk v3 description: >- Webacy-native v3 vault risk surface — composite grade, categories, coverage, and the framework taxonomy (RFC-019). - name: RWA Risk v3 description: >- Webacy-native v3 RWA / stablecoin risk surface — composite grade, structural-health criteria, and batch (RFC-019). paths: /vaults/{address}/tvl-history: get: tags: - Vault Risk summary: Get Vault TVL History description: >- Returns a daily time series of total value locked (USD) for a single ERC-4626 vault. Each point is a UTC-midnight sample and carries a `quality_flag` describing whether the producer marked the underlying TVL reading as trustworthy. The response also hoists the most recent passing point to a top-level `latest` aggregate so stat-tile consumers can render the current value without paging the full series. **Quality filtering (default):** Samples flagged as `capped`, `diverged`, or `spike` are dropped from the response by default, so the chart line stays clean against producer-side data-quality issues. When this happens, `count` will be smaller than `days` and `filtered_count` reports how many points were excluded — a visible kink in the chart line is expected and does not indicate a missed cron tick. Set `includeFlagged=true` to bypass the filter and receive the raw series with every sample's `quality_flag` populated. **Envelope semantics:** `stale_reason` disambiguates the four post-filter states (`fresh`, `pipeline_lag`, `all_filtered`, `no_samples_yet`); `stale: boolean` is preserved for back-compat (`true` iff `stale_reason !== 'fresh'`). `schema_version` is bumped any time the response shape changes — pin it if you're building a regression harness. Returns 404 when the vault is not in the verified-vaults catalog; tracked vaults with no samples yet still return 200 with `count: 0`, `latest: null`, and `stale_reason: 'no_samples_yet'`. Cached for 5 minutes; the `includeFlagged=true` and default responses are cached in partitioned namespaces so they never cross-pollinate. operationId: getVaultTvlHistory parameters: - name: address in: path required: true description: Vault contract address schema: type: string pattern: ^0x[a-fA-F0-9]{40}$ example: '0x9d39a5de30e57443bff2a8307a4256c8797a3497' - name: chain in: query required: true description: Blockchain network where the vault is deployed schema: type: string enum: - eth - arb - base - opt - pol - bsc example: eth - name: range in: query required: false description: Window length to return. Defaults to `30d` when omitted. schema: type: string enum: - 7d - 30d - 60d - 3m default: 30d example: 30d - name: includeFlagged in: query required: false description: >- When `true`, bypasses the default `quality_flag` allowlist filter and returns the full raw series including `capped`, `diverged`, and `spike` samples. Intended for power users and researchers — the default chart-friendly behavior (`false`) drops those samples so single-day pricing artifacts and divergence events do not show up as misleading peaks or troughs in the line. `filtered_count` is always `0` when this flag is `true`. The hoisted `latest` aggregate tracks the same filter: when `false`, `latest` is the most recent passing sample (`quality_flag` ∈ {`ok`, `unknown`}); when `true`, `latest` is the most recent sample in the raw series and may carry any `quality_flag` value. schema: type: boolean default: false example: false responses: '200': description: Daily TVL series with envelope and hoisted `latest` aggregate content: application/json: schema: type: object required: - schema_version - stale - stale_reason - days - count - filtered_count - from - to - latest - series properties: schema_version: type: string description: >- Response-shape version token. Bumped any time the wire payload shape changes — pin if you are building a regression harness against this endpoint. example: s3 stale: type: boolean description: >- Back-compat alias: `true` iff `stale_reason !== 'fresh'`. Prefer `stale_reason` for new integrations. stale_reason: type: string enum: - fresh - pipeline_lag - all_filtered - no_samples_yet description: >- Disambiguates the four post-filter states. `fresh`: latest passing sample is within 48 hours. `pipeline_lag`: latest passing sample is older than 48 hours. `all_filtered`: every sample in the window was dropped by the quality filter (see `filtered_count`). `no_samples_yet`: the vault is tracked but has no samples in the window. days: type: integer description: >- Resolved value of the `range` query parameter expressed in days (7 / 30 / 60 / 90). count: type: integer description: >- Number of points returned in `series`. May be less than `days` after the quality filter drops flagged points; `count + filtered_count` reconciles to the raw window size. filtered_count: type: integer description: >- Number of samples in the window that were excluded by the default `quality_flag` filter. Always `0` when `includeFlagged=true` or when no flagged samples were present. example: 0 from: type: string format: date-time nullable: true description: >- UTC-midnight timestamp of the first point in `series`. `null` when `series` is empty. to: type: string format: date-time nullable: true description: >- UTC-midnight timestamp of the last point in `series`. `null` when `series` is empty. latest: type: object nullable: true description: >- Most recent point in the returned `series`, hoisted for stat-tile rendering. Tracks the same filter as `series`: when `includeFlagged=false` (default), this is the most recent **passing** sample, and `latest.quality_flag` is always `ok` or `unknown`; when `includeFlagged=true`, this is the most recent sample in the raw series and may carry any `quality_flag` value (including `capped`, `diverged`, or `spike`) if the absolute newest sample was flagged. `null` when no samples were available after filtering. required: - ts - tvl_usd - quality_flag properties: ts: type: string format: date-time tvl_usd: type: number quality_flag: $ref: '#/components/schemas/VaultQualityFlag' series: type: array description: Per-point time series, ordered by ascending `ts`. items: type: object required: - ts - tvl_usd - quality_flag properties: ts: type: string format: date-time tvl_usd: type: number quality_flag: $ref: '#/components/schemas/VaultQualityFlag' example: schema_version: s3 stale: false stale_reason: fresh days: 30 count: 23 filtered_count: 6 from: '2026-04-08T00:00:00.000Z' to: '2026-05-06T00:00:00.000Z' latest: ts: '2026-05-06T00:00:00.000Z' tvl_usd: 2179522513.31 quality_flag: ok series: - ts: '2026-04-08T00:00:00.000Z' tvl_usd: 2122465748.18 quality_flag: ok - ts: '2026-05-06T00:00:00.000Z' tvl_usd: 2179522513.31 quality_flag: ok '400': description: >- Invalid address format, missing chain parameter, or unsupported `range` value '401': $ref: '#/components/responses/UnauthorizedError' '404': description: >- Vault not in the verified-vaults catalog for the given address and chain security: - api_key: [] components: schemas: VaultQualityFlag: type: string enum: - ok - capped - diverged - spike - unknown description: >- Producer-stamped quality classification of a vault TVL or share-price sample. `ok` — clean reading. `capped` — value clamped at a hard ceiling, treat as a lower bound. `diverged` — multi-source readings disagreed materially. `spike` — single-sample jump exceeded the 5× day-over-day threshold and likely reflects a pricing artifact. `unknown` — legacy row or sample that predates flag derivation (kept in the read-side allowlist until backfill rollout completes). The default response only ever carries `ok` / `unknown`; `capped` / `diverged` / `spike` rows surface only when `includeFlagged=true`. responses: UnauthorizedError: description: Authorization information is missing or invalid content: application/json: example: message: Unauthorized securitySchemes: api_key: type: apiKey in: header name: x-api-key ````