> 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/conventions.md). # Conventions The same shape applies to every paginated query in the API. Once you've used one, the others read the same way. {% hint style="warning" %} **The schema is the source of truth.** This page documents conventions, not every field. For exhaustive type and field listings, use [Apollo Sandbox](https://api.lagoon.finance/query) — introspection is enabled. {% endhint %} ## Pagination All list queries are offset-paginated with two required arguments: | Argument | Type | Description | | -------- | ------ | ---------------------------------------- | | `first` | `Int!` | Page size. Keep ≤ 100. | | `skip` | `Int!` | Offset from the start of the result set. | The response is wrapped in a `Page` type — for example `VaultPage`, `TransactionPage`, `UserPage` — with two fields: | Field | Type | Description | | ---------- | ------------ | ----------------------------- | | `items` | `[Entity!]!` | The current page of entities. | | `pageInfo` | `PageInfo!` | Pagination metadata. | `PageInfo` exposes `count`, `limit`, `skip`, `totalCount`, `hasNextPage`, `hasPreviousPage`. Always request `pageInfo { hasNextPage totalCount }` if you need to know when to stop. ## Filtering Each list query accepts a typed `where: EntityFilterInput`. Filter fields follow a `_` naming convention: | Suffix | Meaning | Example | | ------------------------------- | ------------------------------ | ----------------------------------------- | | `_eq` | equals | `chainId_eq: 1` | | `_not_eq` | not equals | `state_not_eq: Closed` | | `_in` | in array | `address_in: ["0x…", "0x…"]` | | `_not_in` | not in array | `chainId_not_in: [137, 10]` | | `_contains` | array contains value | `curatorIds_contains: "0x…"` | | `_contains_any` | array contains any of | `curatorIds_contains_any: ["0x…", "0x…"]` | | `_gt` / `_gte` / `_lt` / `_lte` | numeric / timestamp comparison | `timestamp_gt: 1780000000` | Not every field on every entity supports every operator — Apollo Sandbox lists exactly which `_` keys exist per filter input. Example: visible Ethereum vaults with a specific symbol whitelist: ```graphql query FilterExample { vaults( first: 50 skip: 0 orderBy: totalAssetsUsd orderDirection: desc where: { chainId_eq: 1 isVisible_eq: true symbol_in: ["T9cbBTC", "T9USDC"] } ) { items { address name symbol } } } ``` [**Try in Apollo Sandbox →**](https://api.lagoon.finance/query?document=query%20FilterExample%20%7B%0A%20%20vaults%28%0A%20%20%20%20first%3A%2050%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%0A%20%20%20%20%20%20chainId_eq%3A%201%0A%20%20%20%20%20%20isVisible_eq%3A%20true%0A%20%20%20%20%20%20symbol_in%3A%20%5B%22T9cbBTC%22%2C%20%22T9USDC%22%5D%0A%20%20%20%20%7D%0A%20%20%29%20%7B%0A%20%20%20%20items%20%7B%20address%20name%20symbol%20%7D%0A%20%20%7D%0A%7D) ## Ordering Two arguments, both with safe defaults: | Argument | Type | Description | | ---------------- | ------------------ | -------------------------------------------------------------------------------------------------- | | `orderBy` | `OrderBy!` | Typed enum, per-entity. For example `VaultOrderBy.totalAssetsUsd`, `TransactionOrderBy.timestamp`. | | `orderDirection` | `OrderDirection` | `asc` or `desc`. Defaults to `asc`. | ## Scalars | Scalar | Format | Notes | | ------------ | ---------------------------------------- | -------------------------------------------------------------------------------- | | `Address` | `0x`-prefixed lowercase hex string | Returned lowercase; accepted in either case. | | `BigInt` | Decimal string | Used for token amounts, block numbers, Unix timestamps, basis points. JSON-safe. | | `HexString` | `0x`-prefixed hex string | Transaction hashes, block hashes. | | `JSONObject` | Arbitrary JSON object | Free-form metadata. | | `Float` | IEEE-754 double | USD values, APRs, percentages. | | Timestamps | Unix **seconds**, as `Float` or `BigInt` | Not milliseconds. | ## Historical data Every vault exposes its own history without a separate query: ### `vault.stateAt(timestamp: Int!)` Point-in-time reconstruction of the vault from indexed onchain history. Returns a `HistoricalVaultState` with the same metric fields as `state` (totalAssets, pricePerShare, fees, roles, access mode, guardrails, APRs, …). Returns `null` (or `BAD_USER_INPUT`) for timestamps before the vault's first state row. ### `vault.stateHistory` Time series of every field in `state` that has a recorded history (price per share, total assets, supply, fees, etc.). Each field returns an ascending list of data points within an optional `TimeRangeOptions` window (default: from vault creation to now). **Capped at the 1000 most recent events per underlying table** — for full backfills, page through `transactions` directly. `stateHistory` is the building block for rolling your own APR or PnL — see [APR computations](/developer-hub/integration/apr-computations.md) for the formulas used by the indexer. ## Request limits | Limit | If exceeded | | -------------- | --------------------------------------------------------------------------------------------------------------------------- | | Query depth | Restructure into shallower queries. | | Max complexity | Trim fields from the selection set, or lower `first`. | | Rate limit | You'll receive `HTTP 429`. Back off and retry with exponential backoff; contact the Lagoon team if you need a higher limit. | ## Indexing health `_meta.lastIndexedBlocks` returns the most recent block per chain that produced a tracked event. Pass `chainIds` to scope the response: ```graphql query IndexingHealth { _meta(chainIds: [1, 8453]) { lastIndexedBlocks { chainId number hash chain { name } } } } ``` [**Try in Apollo Sandbox →**](https://api.lagoon.finance/query?document=query%20IndexingHealth%20%7B%0A%20%20_meta%28chainIds%3A%20%5B1%2C%208453%5D%29%20%7B%0A%20%20%20%20lastIndexedBlocks%20%7B%0A%20%20%20%20%20%20chainId%0A%20%20%20%20%20%20number%0A%20%20%20%20%20%20hash%0A%20%20%20%20%20%20chain%20%7B%20name%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D) This value can trail the chain head on low-activity chains, but lag is bounded to \~1 hour. If a chain reports a number more than \~1 hour behind, treat its data as stale. --- # 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/conventions.md?ask=&goal= ``` `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.