> For the complete documentation index, see [llms.txt](https://docs.lagoon.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lagoon.finance/developer-hub/lagoon-api/common-queries.md).

# Common queries

Every recipe below shows the query itself in a `graphql` block, a one-click link that opens [Apollo Sandbox](https://api.lagoon.finance/query) with the query pre-loaded, and the equivalent `curl` call. Replace the example vault address, chain ID, or user address with your own and the queries will return live data.

## Recipes

| # | Recipe                                                                            | What it returns                                                            |
| - | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| 1 | [List vaults on a chain](#list-vaults-on-a-chain)                                 | Paginated vaults filtered by chain & visibility, with state and APR.       |
| 2 | [Get a single vault by address](#get-a-single-vault-by-address)                   | One vault with full current state, asset, and chain.                       |
| 3 | [Get a user's positions across vaults](#get-a-users-positions-across-vaults)      | A user's share balance and pending/claimable deposits and redeems.         |
| 4 | [Stream vault events](#stream-vault-events)                                       | Recent on-chain events for a vault, typed via the `TransactionData` union. |
| 5 | [Historical vault state at a timestamp](#historical-vault-state-at-a-timestamp)   | Point-in-time reconstruction via `stateAt`.                                |
| 6 | [Global Lagoon TVL](#global-lagoon-tvl)                                           | Aggregate USD TVL across all Lagoon vaults.                                |
| — | [How the Lagoon dApp uses these queries](#how-the-lagoon-dapp-uses-these-queries) | Patterns from the production frontend worth copying.                       |

## List vaults on a chain

Top vaults on Ethereum by USD TVL, paginated, only those visible on the Lagoon frontend:

```graphql
query ListVaults {
  vaults(
    first: 10
    skip: 0
    orderBy: totalAssetsUsd
    orderDirection: desc
    where: { chainId_eq: 1, isVisible_eq: true }
  ) {
    items {
      address
      name
      symbol
      state {
        totalAssetsUsd
        pricePerShareUsd
        yearlyApr { linearNetApr twrrNetApr }
      }
    }
    pageInfo { hasNextPage totalCount }
  }
}
```

[**Try in Apollo Sandbox →**](https://api.lagoon.finance/query?document=query%20ListVaults%20%7B%0A%20%20vaults%28%0A%20%20%20%20first%3A%2010%0A%20%20%20%20skip%3A%200%0A%20%20%20%20orderBy%3A%20totalAssetsUsd%0A%20%20%20%20orderDirection%3A%20desc%0A%20%20%20%20where%3A%20%7B%20chainId_eq%3A%201%2C%20isVisible_eq%3A%20true%20%7D%0A%20%20%29%20%7B%0A%20%20%20%20items%20%7B%0A%20%20%20%20%20%20address%0A%20%20%20%20%20%20name%0A%20%20%20%20%20%20symbol%0A%20%20%20%20%20%20state%20%7B%0A%20%20%20%20%20%20%20%20totalAssetsUsd%0A%20%20%20%20%20%20%20%20pricePerShareUsd%0A%20%20%20%20%20%20%20%20yearlyApr%20%7B%20linearNetApr%20twrrNetApr%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%20%20pageInfo%20%7B%20hasNextPage%20totalCount%20%7D%0A%20%20%7D%0A%7D)

```bash
curl -sS -X POST https://api.lagoon.finance/query \
  -H "Content-Type: application/json" \
  -d '{"query":"query ListVaults { vaults(first: 10, skip: 0, orderBy: totalAssetsUsd, orderDirection: desc, where: { chainId_eq: 1, isVisible_eq: true }) { items { address name symbol state { totalAssetsUsd pricePerShareUsd yearlyApr { linearNetApr twrrNetApr } } } pageInfo { hasNextPage totalCount } } }"}'
```

Returns `items` (the vaults) plus `pageInfo.totalCount` for total match count and `pageInfo.hasNextPage` for paging.

## Get a single vault by address

Fetch one vault with its current state, underlying asset, and chain:

```graphql
query GetVault {
  vaultByAddress(
    address: "0x936facdf10c8c36294e7b9d28345255539d81bc7"
    chainId: 1
  ) {
    address
    name
    symbol
    creationDate
    asset { address symbol decimals }
    chain { id name }
    state {
      totalAssets
      totalSupply
      pricePerShare
      pricePerShareUsd
      totalAssetsUsd
      managementFee
      performanceFee
      syncMode
    }
  }
}
```

[**Try in Apollo Sandbox →**](https://api.lagoon.finance/query?document=query%20GetVault%20%7B%0A%20%20vaultByAddress%28%0A%20%20%20%20address%3A%20%220x936facdf10c8c36294e7b9d28345255539d81bc7%22%0A%20%20%20%20chainId%3A%201%0A%20%20%29%20%7B%0A%20%20%20%20address%0A%20%20%20%20name%0A%20%20%20%20symbol%0A%20%20%20%20creationDate%0A%20%20%20%20asset%20%7B%20address%20symbol%20decimals%20%7D%0A%20%20%20%20chain%20%7B%20id%20name%20%7D%0A%20%20%20%20state%20%7B%0A%20%20%20%20%20%20totalAssets%0A%20%20%20%20%20%20totalSupply%0A%20%20%20%20%20%20pricePerShare%0A%20%20%20%20%20%20pricePerShareUsd%0A%20%20%20%20%20%20totalAssetsUsd%0A%20%20%20%20%20%20managementFee%0A%20%20%20%20%20%20performanceFee%0A%20%20%20%20%20%20syncMode%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D)

```bash
curl -sS -X POST https://api.lagoon.finance/query \
  -H "Content-Type: application/json" \
  -d '{"query":"query GetVault { vaultByAddress(address: \"0x936facdf10c8c36294e7b9d28345255539d81bc7\", chainId: 1) { address name symbol creationDate asset { address symbol decimals } chain { id name } state { totalAssets totalSupply pricePerShare pricePerShareUsd totalAssetsUsd managementFee performanceFee syncMode } } }"}'
```

`state` carries every live metric (TVL, supply, price-per-share, fees, sync mode, guardrails, roles). Pick only the fields you need.

## Get a user's positions across vaults

A user's full position on a given chain — share balance, pending and claimable deposits, pending and claimable redeems — in one round trip:

```graphql
query GetUserPositions($address: Address!, $chainId: Int!) {
  userByAddress(address: $address, chainId: $chainId) {
    address
    vaultPositions {
      vault { address name symbol }
      state {
        balance
        usd
        pendingDeposit { assets shares }
        pendingRedeem { assets shares isCancelable }
        claimableDeposit { assets shares assetsActualized }
        claimableRedeem { assets shares }
      }
    }
  }
}
```

[**Try in Apollo Sandbox →**](https://api.lagoon.finance/query?document=query%20GetUserPositions%28%24address%3A%20Address%21%2C%20%24chainId%3A%20Int%21%29%20%7B%0A%20%20userByAddress%28address%3A%20%24address%2C%20chainId%3A%20%24chainId%29%20%7B%0A%20%20%20%20address%0A%20%20%20%20vaultPositions%20%7B%0A%20%20%20%20%20%20vault%20%7B%20address%20name%20symbol%20%7D%0A%20%20%20%20%20%20state%20%7B%0A%20%20%20%20%20%20%20%20balance%0A%20%20%20%20%20%20%20%20usd%0A%20%20%20%20%20%20%20%20pendingDeposit%20%7B%20assets%20shares%20%7D%0A%20%20%20%20%20%20%20%20pendingRedeem%20%7B%20assets%20shares%20isCancelable%20%7D%0A%20%20%20%20%20%20%20%20claimableDeposit%20%7B%20assets%20shares%20assetsActualized%20%7D%0A%20%20%20%20%20%20%20%20claimableRedeem%20%7B%20assets%20shares%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D)

```bash
curl -sS -X POST https://api.lagoon.finance/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetUserPositions($address: Address!, $chainId: Int!) { userByAddress(address: $address, chainId: $chainId) { address vaultPositions { vault { address name symbol } state { balance usd pendingDeposit { assets shares } pendingRedeem { assets shares isCancelable } claimableDeposit { assets shares assetsActualized } claimableRedeem { assets shares } } } } }",
    "variables": { "address": "0xUSER", "chainId": 1 }
  }'
```

This is the off-chain equivalent of the three on-chain calls described in [Get a user position](/developer-hub/integration/get-a-user-position.md) (`balanceOf` + `maxMint` + `pendingRedeemRequest`), plus the dollar value and the claimable-deposit current-price actualization.

## Stream vault events

Most recent settlement events for a vault, with the event payload pulled from the `TransactionData` union via inline fragments:

```graphql
query StreamVaultEvents {
  transactions(
    first: 20
    skip: 0
    orderBy: timestamp
    orderDirection: desc
    where: {
      vault_in: ["0x936facdf10c8c36294e7b9d28345255539d81bc7"]
      type_in: [TotalAssetsUpdated, SettleDeposit, SettleRedeem, FeeTaken]
    }
  ) {
    items {
      timestamp
      blockNumber
      hash
      type
      data {
        __typename
        ... on TotalAssetsUpdated { totalAssets }
        ... on SettleDeposit { totalAssets totalSupply }
        ... on SettleRedeem { totalAssets totalSupply }
        ... on FeeTaken { feeType totalShares }
      }
    }
    pageInfo { hasNextPage totalCount }
  }
}
```

[**Try in Apollo Sandbox →**](https://api.lagoon.finance/query?document=query%20StreamVaultEvents%20%7B%0A%20%20transactions%28%0A%20%20%20%20first%3A%2020%0A%20%20%20%20skip%3A%200%0A%20%20%20%20orderBy%3A%20timestamp%0A%20%20%20%20orderDirection%3A%20desc%0A%20%20%20%20where%3A%20%7B%0A%20%20%20%20%20%20vault_in%3A%20%5B%220x936facdf10c8c36294e7b9d28345255539d81bc7%22%5D%0A%20%20%20%20%20%20type_in%3A%20%5BTotalAssetsUpdated%2C%20SettleDeposit%2C%20SettleRedeem%2C%20FeeTaken%5D%0A%20%20%20%20%7D%0A%20%20%29%20%7B%0A%20%20%20%20items%20%7B%0A%20%20%20%20%20%20timestamp%0A%20%20%20%20%20%20blockNumber%0A%20%20%20%20%20%20hash%0A%20%20%20%20%20%20type%0A%20%20%20%20%20%20data%20%7B%0A%20%20%20%20%20%20%20%20__typename%0A%20%20%20%20%20%20%20%20...%20on%20TotalAssetsUpdated%20%7B%20totalAssets%20%7D%0A%20%20%20%20%20%20%20%20...%20on%20SettleDeposit%20%7B%20totalAssets%20totalSupply%20%7D%0A%20%20%20%20%20%20%20%20...%20on%20SettleRedeem%20%7B%20totalAssets%20totalSupply%20%7D%0A%20%20%20%20%20%20%20%20...%20on%20FeeTaken%20%7B%20feeType%20totalShares%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%20%20pageInfo%20%7B%20hasNextPage%20totalCount%20%7D%0A%20%20%7D%0A%7D)

```bash
curl -sS -X POST https://api.lagoon.finance/query \
  -H "Content-Type: application/json" \
  -d '{"query":"query StreamVaultEvents { transactions(first: 20, skip: 0, orderBy: timestamp, orderDirection: desc, where: { vault_in: [\"0x936facdf10c8c36294e7b9d28345255539d81bc7\"], type_in: [TotalAssetsUpdated, SettleDeposit, SettleRedeem, FeeTaken] }) { items { timestamp blockNumber hash type data { __typename ... on TotalAssetsUpdated { totalAssets } ... on SettleDeposit { totalAssets totalSupply } ... on SettleRedeem { totalAssets totalSupply } ... on FeeTaken { feeType totalShares } } } pageInfo { hasNextPage totalCount } } }"}'
```

`TransactionData` is a union — request only the variants you care about with `... on EventName` fragments. The full list of event types is in the `TransactionType` enum (browsable in Sandbox). See [Key data structures and epoch mechanism](/developer-hub/key-data-structures-and-epoch-mechanism.md) for the semantics of each event.

## Historical vault state at a timestamp

Reconstruct a vault as it existed at a past Unix timestamp:

```graphql
query HistoricalVaultState {
  vaultByAddress(
    address: "0x936facdf10c8c36294e7b9d28345255539d81bc7"
    chainId: 1
  ) {
    stateAt(timestamp: 1780000000) {
      totalAssets
      totalSupply
      pricePerShare
      pricePerShareUsd
      totalAssetsUsd
      managementFee
      performanceFee
      state
    }
  }
}
```

[**Try in Apollo Sandbox →**](https://api.lagoon.finance/query?document=query%20HistoricalVaultState%20%7B%0A%20%20vaultByAddress%28%0A%20%20%20%20address%3A%20%220x936facdf10c8c36294e7b9d28345255539d81bc7%22%0A%20%20%20%20chainId%3A%201%0A%20%20%29%20%7B%0A%20%20%20%20stateAt%28timestamp%3A%201780000000%29%20%7B%0A%20%20%20%20%20%20totalAssets%0A%20%20%20%20%20%20totalSupply%0A%20%20%20%20%20%20pricePerShare%0A%20%20%20%20%20%20pricePerShareUsd%0A%20%20%20%20%20%20totalAssetsUsd%0A%20%20%20%20%20%20managementFee%0A%20%20%20%20%20%20performanceFee%0A%20%20%20%20%20%20state%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D)

```bash
curl -sS -X POST https://api.lagoon.finance/query \
  -H "Content-Type: application/json" \
  -d '{"query":"query HistoricalVaultState { vaultByAddress(address: \"0x936facdf10c8c36294e7b9d28345255539d81bc7\", chainId: 1) { stateAt(timestamp: 1780000000) { totalAssets totalSupply pricePerShare pricePerShareUsd totalAssetsUsd managementFee performanceFee state } } }"}'
```

`stateAt` returns `null` (or a `BAD_USER_INPUT` error) for timestamps before the vault's first indexed state. For a time series of any of these fields, use `stateHistory` instead — see [Conventions → Historical data](/developer-hub/lagoon-api/conventions.md#historical-data).

## Global Lagoon TVL

```graphql
{
  getGlobalTVL
}
```

[**Try in Apollo Sandbox →**](https://api.lagoon.finance/query?document=%7B%0A%20%20getGlobalTVL%0A%7D)

```bash
curl -sS -X POST https://api.lagoon.finance/query \
  -H "Content-Type: application/json" \
  -d '{"query":"{ getGlobalTVL }"}'
```

Returns a single `Float` — the aggregate USD TVL across all Lagoon vaults, sourced from DeFiLlama.

## How the Lagoon dApp uses these queries

The production [app.lagoon.finance](https://app.lagoon.finance) frontend is built on exactly this API. A few patterns from that integration that are worth copying:

* **Server-side fetch, no client library.** The dApp uses plain `fetch` with `cache: 'no-store'` from Next.js route handlers — no Apollo or urql. Letting the framework handle revalidation (ISR / `revalidate` directives) is simpler than maintaining a normalized cache, and the API returns whole entities anyway.
* **Compose queries from fragments.** Vault listing pages and vault detail pages share a `VaultFields` fragment but pick different sub-fragments (`VaultFieldsListLight` skips APR data for fast homepage rendering; `VaultFieldsDetail` adds composition, fees, and roles). Define one fragment per logical view and interpolate into multiple queries.
* **`isVisible_eq: true` for frontend listings.** Vaults flagged as not visible are still indexed and queryable, but should be filtered out of any list shown to end users.
* **Page with `pageInfo.totalCount` and `hasNextPage`.** The dApp's transaction-history view does offset pagination with a small `first` value (e.g. 10) and uses `totalCount` to render the page count up-front.
* **Health-check on every request batch.** Route handlers that fan out to multiple queries include `_meta { lastIndexedBlocks { chainId number } }` so the UI can surface "data may be stale" when a chain is more than \~1 hour behind.
* **Lowercased addresses in filters.** Always normalize address inputs (e.g. with viem's `getAddress` / `.toLowerCase()`) before passing them to `_eq` / `_in` filters.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.lagoon.finance/developer-hub/lagoon-api/common-queries.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.