Skip to main content
GET
/
vaults
/
{address}
/
tvl-history
Get Vault TVL History
curl --request GET \
  --url https://api.webacy.com/vaults/{address}/tvl-history \
  --header 'x-api-key: <api-key>'
{
  "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"
    }
  ]
}

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
address
string
required

Vault contract address

Pattern: ^0x[a-fA-F0-9]{40}$

Query Parameters

​
chain
enum<string>
required

Blockchain network where the vault is deployed

Available options:
eth,
arb,
base,
opt,
pol,
bsc
​
range
enum<string>
default:30d

Window length to return. Defaults to 30d when omitted.

Available options:
7d,
30d,
60d,
3m
​
includeFlagged
boolean
default:false

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.

Response

Daily TVL series with envelope and hoisted latest aggregate

​
schema_version
string
required

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
boolean
required

Back-compat alias: true iff stale_reason !== 'fresh'. Prefer stale_reason for new integrations.

​
stale_reason
enum<string>
required

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.

Available options:
fresh,
pipeline_lag,
all_filtered,
no_samples_yet
​
days
integer
required

Resolved value of the range query parameter expressed in days (7 / 30 / 60 / 90).

​
count
integer
required

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
integer
required

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
string<date-time> | null
required

UTC-midnight timestamp of the first point in series. null when series is empty.

​
to
string<date-time> | null
required

UTC-midnight timestamp of the last point in series. null when series is empty.

​
latest
object
required

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.

​
series
object[]
required

Per-point time series, ordered by ascending ts.