概述

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 和 maxPositions drive the ranking; the remaining params filter.

Endpoint

GET https://earn-api.quicknode.dev/functions/v1/api/v1/vaults/rankings

Authorization

Include the published apikey header. This read request is public and does not require a SIWE signature.

参数

Parameter	Location	类型	Required	描述
capital	query	数字	是	Capital to allocate, in USDC decimal dollars (> 0).
maxPositions	query	整数	是	Maximum number of vault positions (positive integer).
链条	query	字符串	不	CSV of chain ids. Defaults to all enabled chains.
minTvl	query	数字	不	Minimum vault TVL in decimal US dollars. Defaults to 0.
minLiquidity	query	数字	不	Minimum withdrawable liquidity in decimal US dollars. Defaults to 0.
minLiquidityMultiplier	query	数字	不	Entry liquidity threshold multiplier: a vault must have this multiple of the intended position size in withdrawable liquidity to qualify. Defaults to 2. The deposit calldata path uses a looser default of 1.
apySmoothingMinutes	query	整数	不	APY smoothing window in minutes; snaps to the nearest precomputed column (5/10/30/60/120/240/360). Defaults to 30.
hiddenVaultKeys	query	字符串	不	CSV of `chainId:0xaddress` vault keys to exclude.
wallet	query	字符串	不	If present, merges this wallet's saved global hide list into the exclusions.
covered	query	string (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).

Example request

curl --request GET \
  --url 'https://earn-api.quicknode.dev/functions/v1/api/v1/vaults/rankings?capital=1000&maxPositions=5' \
  --header 'Accept: application/json' \
  --header 'apikey: <EARN_PUBLIC_API_KEY>'

回复

Field	类型	Required	描述
mode	string (ranked)	是	Identifies the response as a ranked vault allocation preview.
vaults	array<object>	是	Eligible vaults ordered by the ranking pipeline.
vaults[].chainId	整数	是	Numeric identifier of the chain where the vault is deployed.
vaults[].vaultAddress	字符串	是	Lowercase address of the ERC-4626 vault share token.
vaults[].name	字符串	是	Human-readable name of the vault.
vaults[].apy	number (decimal)	是	Ranking APY expressed as a percentage to three decimal places. For example, `15.294` represents 15.294% APY.
vaults[].tvlUsd	整数	是	Vault TVL in whole US dollars, rounded to the nearest dollar.
vaults[].availableLiquidityUsd	integer | null	是	Withdrawable liquidity in whole US dollars, or null when unknown.
vaults[].maxDepositUsd	integer | null	是	Deposit capacity in whole US dollars. Null means the vault is uncapped.
vaults[].atCapacity	布尔型	是	True when the vault has no remaining deposit capacity.
excludedChains	array<object>	是	Chains excluded from the allocation and the reason for each exclusion.
excludedChains[].chainId	整数	是	Numeric identifier of the excluded chain.
excludedChains[].reason	字符串	是	Reason the chain did not produce an eligible vault.
eligibleCount	整数	是	Number of eligible vaults before the maxPositions cut.
estimatedApy	number (decimal) | null	是	Mean of the selected vaults' positive APYs, as a percentage; null when none.

Example response

{
	"mode": "ranked",
	"vaults": [
		{
			"chainId": 42161,
			"vaultAddress": "0x55a2b207b0074e13adcb858950a81b7a04775e0f",
			"name": "Gauntlet USDC Balanced",
			"apy": 15.294,
			"tvlUsd": 217817,
			"availableLiquidityUsd": 1701,
			"maxDepositUsd": null,
			"atCapacity": false
		},
		{
			"chainId": 42161,
			"vaultAddress": "0x7e97fa6893871a2751b5fe961978dccb2c201e65",
			"name": "Gauntlet USDC Core",
			"apy": 13.771,
			"tvlUsd": 682955,
			"availableLiquidityUsd": 1701,
			"maxDepositUsd": null,
			"atCapacity": false
		},
		{
			"chainId": 143,
			"vaultAddress": "0x78999cc96d2ba0341588c60ccb0e91c6c33cf371",
			"name": "Hyperithm USDC Apex",
			"apy": 7.704,
			"tvlUsd": 51560093,
			"availableLiquidityUsd": 50763,
			"maxDepositUsd": null,
			"atCapacity": false
		},
		{
			"chainId": 143,
			"vaultAddress": "0x80017bf0f793ebbe9679cd61ff0e395b62cabb59",
			"name": "August USDC V2",
			"apy": 5.358,
			"tvlUsd": 4930373,
			"availableLiquidityUsd": 470821,
			"maxDepositUsd": null,
			"atCapacity": false
		},
		{
			"chainId": 8453,
			"vaultAddress": "0x1deefabee758aabdc29a542b24ca3b75afd56765",
			"name": "Gauntlet USDC Frontier",
			"apy": 5.305,
			"tvlUsd": 2960443,
			"availableLiquidityUsd": 744240,
			"maxDepositUsd": null,
			"atCapacity": false
		}
	],
	"excludedChains": [
		{
			"chainId": 1,
			"reason": "Strategy capital $1000 < $5000 minimum"
		}
	],
	"eligibleCount": 45,
	"estimatedApy": 9.4864
}

HTTP responses

状态	描述
200	The ranked vault list.
400	Required parameters are missing, malformed, or outside their accepted range.
429	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	Vault ranking data is temporarily unavailable.
503	Wallet hide-list lookup failed (only when `wallet` is supplied). Fails closed.

OpenAPI source

This page is based on operation getVaultRankings in the Earn OpenAPI 3.1 specification.