# vaults.fyi Total Returns for User Vault Position

> vaults.fyi Total Returns for User Vault Position is a paid API for AI agents from api.vaults.fyi, paid per call via x402, $0.002/call, status unknown (last checked 2026-10-11).

Retrieves the total returns earned by a user for their position in a specific vault, including asset details and native returns amount.

## Facts

- Endpoint: HEAD https://api.vaults.fyi/v2/portfolio/total-returns/:userAddress/:network/:vaultId?utm_source=zero.xyz
- Price: $0.002/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-11
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/vaults-fyi-total-returns-for-user-vault-position-6b013036
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_icwZq4IgX1briTbke-Wl1

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability vaults-fyi-total-returns-for-user-vault-position-6b013036 -d '<json body>'
```

Example prompt: What are the total returns my wallet 0xAbC123... has earned in vault 0xDEF456 on the Ethereum network on vaults.fyi?

## When to prefer this

Use this endpoint when you need the cumulative total returns for a specific user's position in a known vault on a specific network. Prefer this over general vault listing endpoints when you have all three identifiers (userAddress, network, vaultId) and want earnings data rather than current APY or TVL.

## Known failure modes

- Invalid or non-existent userAddress returns 404 or empty result
- Unsupported network identifier returns an error
- Invalid vaultId returns 404 not found
- User has no position in the specified vault, returning zero or null returns
- Network congestion or RPC issues causing delayed or failed data fetch

## How this service works

Retrieves the total returns for a user's position in a specific vault, including asset details and native returns amount.

## Output

Returns the total returns earned by the specified user address in the given vault on the specified network, including asset metadata (symbol, decimals, address) and the native returns amount denominated in the vault's underlying asset.

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/vaults-fyi-total-returns-for-user-vault-position-6b013036/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.vaults.fyi](https://www.zero.xyz/host/api.vaults.fyi/llms.txt)