Vaults
Vault browse/detail/APY-history reads and the ranked allocation preview.
/v1/vaultsVault list (browse)
Every approved vault with the nine windowed APYs, TVL, liquidity and
capacity from the latest snapshot. For a capital-aware allocation
preview, use GET /v1/vaults/rankings.
Auth: apikey header
Parameters
| Parameter | Type | Description |
|---|---|---|
chainsquery | string | CSV of chain ids. Defaults to all enabled chains. |
windowquery | integer | Minutes for the headline apy, snapped to the nearest precomputed
column. The nine windowed APYs are always returned in windows. |
minTvlquery | number | Minimum vault TVL in decimal dollars. |
minLiquidityquery | number | Minimum withdrawable liquidity in decimal dollars. |
includeCoveredquery | boolean | Opt in to OpenCover covered fee-wrapper rows (covered: true).
Omitted or any value other than true, the list contains plain
vaults only, so existing integrations never see wrapper rows
unexpectedly. |
Responses
| Status | Type | Description |
|---|---|---|
200 | VaultsBrowseResponse | The browse vault list. |
400 | ApiError | Malformed request (bad/missing params). |
429 | ApiError | Rate limit exceeded. Retry-After (seconds) tells you when to retry.
Reads, feedback, and push writes are keyed per IP; create/update/delete
are keyed per wallet+IP; deposit/withdraw/claim calldata is keyed per
strategy+IP. |
500 | ApiError | Vault data is temporarily unavailable. |
/v1/vaults/cover-capacityLive remaining OpenCover coverage capacity
The LIVE remaining OpenCover underwriting capacity, read from OpenCover's endpoint at request time.
Capacity is ONE POOL shared by every covered wrapper, so this is a single figure, not a per-vault list.
Prefer this over the cached coverCapacity on vault rows whenever you
are sizing an amount a user will actually deposit: the covered deposit
gate re-reads the same endpoint when it builds the plan and requires
remaining - deposit >= 0, so a figure from the ~5-minute sweep cache
can disagree with the verdict. The cached field remains fine for
display.
remainingUsd: null means the capacity feed is not configured or no
wrapper answered. Render it as unknown; do NOT treat it as zero (the
deposit gate fails closed on its own).
Auth: apikey header
Responses
| Status | Type | Description |
|---|---|---|
200 | LiveCoverCapacity | Live shared-pool capacity. |
429 | ApiError | Rate limit exceeded. Retry-After (seconds) tells you when to retry.
Reads, feedback, and push writes are keyed per IP; create/update/delete
are keyed per wallet+IP; deposit/withdraw/claim calldata is keyed per
strategy+IP. |
500 | ApiError | Internal server error. |
/v1/vaults/rankingsRanked allocation preview
The vaults a strategy with these settings would target, ranked by the
same pipeline that plans deposits, enriched with liquidity/capacity
from the latest snapshot. capital and maxPositions drive the
ranking; the remaining params filter.
Auth: apikey header
Parameters
| Parameter | Type | Description |
|---|---|---|
capitalqueryrequired | number | Capital to allocate, in USDC decimal dollars (> 0). |
maxPositionsqueryrequired | integer | Maximum number of vault positions (positive integer). |
chainsquery | string | CSV of chain ids. Defaults to all enabled chains. |
minTvlquery | number | Minimum vault TVL in decimal dollars. |
minLiquidityquery | number | Minimum withdrawable liquidity in decimal dollars. |
minLiquidityMultiplierquery | number | Entry liquidity threshold multiplier: a vault must have this multiple of the intended position size in withdrawable liquidity to qualify. The deposit calldata path uses a looser default of 1. |
apySmoothingMinutesquery | integer | APY smoothing window in minutes; snaps to the nearest precomputed column (5/10/30/60/120/240/360/720/1440). |
hiddenVaultKeysquery | string | CSV of chainId:0xaddress vault keys to exclude. |
walletquery | Address | If present, merges this wallet's saved global hide list into the exclusions. |
coveredquery | "true" | "false" | RANKED mode only. Coverage partition to rank within: true = OpenCover
fee-wrappers only, false = plain vaults only. Omit for an unscoped
ranking across both partitions. Any other value is a 400. Threaded into
the ranking pipeline's strategyCovered (the covered/uncovered wizard
toggle drives it). |
Responses
| Status | Type | Description |
|---|---|---|
200 | VaultRankingsResponse | The ranked vault list. |
400 | ApiError | Malformed request (bad/missing params). |
429 | ApiError | Rate limit exceeded. Retry-After (seconds) tells you when to retry.
Reads, feedback, and push writes are keyed per IP; create/update/delete
are keyed per wallet+IP; deposit/withdraw/claim calldata is keyed per
strategy+IP. |
500 | ApiError | Vault ranking data is temporarily unavailable. |
503 | ApiError | Wallet hide-list lookup failed (only when wallet is supplied). Fails closed. |
/v1/vaults/{chainId}/{address}Single approved-vault detail
The latest snapshot for one approved vault: the nine windowed APYs, a
headline apy at the requested window, TVL, liquidity and capacity.
Same row shape as one element of the browse list. An unknown or
delisted vault is a 404.
include=liveLiquidity adds a fresh on-chain read of the vault's
withdrawable liquidity (liveLiquidity). This is a live number and
can differ from the snapshot availableLiquidityUsd. If the on-chain
read fails, the snapshot detail still returns 200 with
liveLiquidity: null and liveLiquidityError: "rpc_error".
Auth: apikey header
Parameters
| Parameter | Type | Description |
|---|---|---|
chainIdpathrequired | integer | Chain id the vault lives on. |
addresspathrequired | Address | Vault (ERC-4626 share token) address. |
windowquery | integer | Minutes for the headline apy, snapped to the nearest precomputed column. The nine windows are returned regardless. |
includequery | "liveLiquidity" | CSV of extras. Supported value: liveLiquidity. |
Responses
| Status | Type | Description |
|---|---|---|
200 | VaultDetailResponse | The vault's latest snapshot. |
400 | ApiError | Bad path (chain id not a positive integer, or address not a 0x address) or a bad window. |
404 | ApiError | No such approved vault (unknown or delisted). |
429 | ApiError | Rate limit exceeded. Retry-After (seconds) tells you when to retry.
Reads, feedback, and push writes are keyed per IP; create/update/delete
are keyed per wallet+IP; deposit/withdraw/claim calldata is keyed per
strategy+IP. |
500 | ApiError | Internal server error. |
/v1/vaults/{chainId}/{address}/apyVault APY over a caller-chosen time interval
The 5-minute snapshot series over [from, to], plus intervalApy: the
annualized share-price return between the first and last snapshot in the
range, (last/first)^(year/elapsed) - 1, in percent.
Retention is 7 days: an earlier from is pulled forward and clamped is
set true. resolution downsamples by keeping the last snapshot per
bucket (real snapshots, never averages) and never changes intervalApy.
Auth: apikey header
Parameters
| Parameter | Type | Description |
|---|---|---|
chainIdpathrequired | integer | Chain id the vault lives on. |
addresspathrequired | Address | Vault (ERC-4626 share token) address. |
fromquery | string (date-time) | Start instant (ISO-8601). Default the trailing 24h before to. Clamped forward to the 7-day retention floor. |
toquery | string (date-time) | End instant (ISO-8601). Defaults to now. |
resolutionquery | integer | Downsample bucket in minutes (5-1440). Omit for the full 5-minute series. |
Responses
| Status | Type | Description |
|---|---|---|
200 | VaultApySeriesResponse | The (optionally downsampled) snapshot series and the interval APY. |
400 | ApiError | A malformed from/to, from >= to, a range entirely outside the
7-day retention, a bad resolution, or a bad path
(invalid_request). |
429 | ApiError | Rate limit exceeded. Retry-After (seconds) tells you when to retry.
Reads, feedback, and push writes are keyed per IP; create/update/delete
are keyed per wallet+IP; deposit/withdraw/claim calldata is keyed per
strategy+IP. |
500 | ApiError | Internal server error. |