---
title: "More than vaults: Lagoon's open data layer"
description: "Lagoon vaults are onchain. On top sits a data layer: an SDK that reads contracts directly, a public GraphQL API with no key, and an MCP server."
date: "2026-05-28"
author: "Lagoon"
category: "Product"
tags: ["API", "SDK", "MCP", "GraphQL", "developers", "vaults"]
url: "https://lagoon.finance/blog/lagoon-api-sdk-mcp"
readingTime: "8 min read"
---
Lagoon vaults are ERC-7540 contracts onchain: that is the source of truth. On top sits a data layer with three ways to read it: an SDK that reads the contracts directly, a public GraphQL API (no key) that indexes and enriches them, and a Model Context Protocol (MCP) server that answers in plain English.
## Introduction
Ask most people what Lagoon is and they will say vaults: [ERC-7540 contracts](/blog/erc-7540-explained) that hold deposits and run a strategy. That is the foundation, and it is deliberately onchain. Balances, shares, fees, and valuations live in the contracts themselves, which makes the vault the source of truth. Nothing about a Lagoon vault depends on a server staying up.
On top of that foundation, we built a data layer. Across 18+ chains and 120+ vaults, reading every contract by hand is not how anyone wants to work, so Lagoon offers three ways into the same data, each at a different level. One reads the contracts directly. One indexes and enriches them. One answers questions about them in plain English. You pick the level that matches how you build.
## A data layer on top of the vaults
A Lagoon vault is a smart contract, so the data about it ultimately comes from the chain. The question is how you get at it. Reading raw contract storage works, but it is low-level, and some of the most useful views are not a single onchain read. A vault's performance over time, where its assets are actually deployed, an address's positions across every chain: those have to be indexed and computed.
So the data layer has three surfaces, stacked from closest to the chain to furthest from it.
_Figure 1: the vaults are the onchain foundation. The SDK reads them directly, the API indexes and enriches them, and the MCP server reads the API._
Because all three trace back to the same onchain vaults, the numbers reconcile. The state a developer reads from a contract, the history the API computes, and the answer an AI assistant gives all derive from the same source.
## Read the vaults directly: the SDK
Closest to the chain is the SDK, an [open-source TypeScript library](https://github.com/hopperlabsxyz/sdk-v0) published on npm (the MIT-licensed `@lagoon-protocol` packages, built on [viem](https://viem.sh)). It does not call a Lagoon server at all. It reads the vault contracts directly onchain and hands back typed objects.
Fetching a vault's complete state is a single call. Under the hood the SDK uses a stateless query contract to batch the reads, so one request returns the whole picture:
```ts
import { Vault } from "@lagoon-protocol/v0-core";
const vault = await Vault.fetch(vaultAddress, client);
vault.totalAssets; // balances and share supply
vault.feeRates; // management and performance rates
```
Because it talks to the chain and nothing else, the data is as live and as trustless as the contract itself. The SDK mirrors the Lagoon contracts closely, so the vault, fee, and [governance](/blog/vault-governance-roles) concepts you find onchain are the ones you find in the types. It also simulates fees and price per share locally, so you can show a user exactly what they will pay before they sign. Our own backend reads vaults through this same SDK: it is the foundation the rest of the data layer is built on.
None of it needs permission. Run `npm install` and you are reading live vault data straight from the chain.
## Indexed and enriched: the public API
Reading a contract gives you its current state. It does not give you last month's performance, a breakdown of where a vault's assets are deployed, or one investor's positions across every chain at once. Those views require indexing onchain history and pulling in data from the wider DeFi ecosystem. That is what the API does.
Lagoon runs a backend that indexes vault events across every supported chain, computes analytics on top, and serves the result from a single public GraphQL endpoint at `api.lagoon.finance/query`. It is public: no key, no sign-up.
The simplest possible request asks for the protocol's total value locked (TVL) across every vault and chain:
```graphql
{
getGlobalTVL
}
```
That one line returns a single number, the same aggregate that feeds the headline figure on the site. Because the schema is introspectable, you do not have to guess what else is there. Point any GraphQL client at the endpoint and it lists every type and field. What is on offer is the enriched, indexed view that a single contract read cannot give you:
| Data | What the API adds on top of the chain |
| ------------ | ------------------------------------------------------------------ |
| Performance | Weekly, monthly, and annualized APR; net asset value (NAV) over time |
| Composition | Where each vault's assets sit, protocol by protocol, token by token |
| Portfolios | One address's positions across every vault and chain, in one query |
| Transactions | The full indexed deposit, redemption, and settlement history |
| Reference | Chains, assets, curators, and protocol-wide aggregates |
The composition data is worth calling out, because it is the kind of transparency [traditional fund reporting](/blog/onchain-vaults-vs-traditional-funds) cannot match. The API breaks each vault's balance down into the underlying protocols and token positions it holds, each with a dollar value and a share of the whole. You can see exactly where the money is, live.
There is no key to leak and no quota to request. The endpoint caps query depth and complexity so a single request cannot overload it, but for most dashboards, indexers, and research scripts that is the only constraint you will meet.
## Plain English: the MCP server
The SDK and the API both assume you write code. Plenty of the people who care about vault data do not, and should not have to: fund managers running due diligence, analysts comparing strategies, allocators monitoring positions. The MCP server is for them.
Lagoon publishes an [MCP server](https://github.com/hopperlabsxyz/lagoon-mcp), also open-source on npm. The Model Context Protocol is the emerging standard for connecting AI assistants to live data and tools, supported by clients like Claude and Cursor. It sits on top of the public API: connect it once and your assistant can answer questions about any vault in everyday language, fetching real data through the API instead of guessing.
The questions look like the ones you would actually ask:
- "Find every USDC vault on Arbitrum with more than $1M total value locked."
- "Compare these three vaults and tell me which has the best risk-adjusted return."
- "How has this vault performed over the last 30 days, and where are its assets allocated?"
Behind that conversational surface, the server calls the same GraphQL API as everything else, then adds analysis on top. It can score a vault's risk across several factors, compare a set of vaults side by side, or export a vault's transaction history to a spreadsheet for accounting. A fund manager can run a first pass of due diligence, or pull the numbers for a monthly report, without filing a single engineering ticket.
It stays strictly informational. Every answer the server returns carries a reminder that it is data, not financial advice.
## Which surface should you reach for?
The three surfaces are levels, not competing options, and most teams end up using more than one. Reach for the one that matches the job in front of you: the SDK when you are building an app and want to read or act on a vault directly, the API when you need history or a cross-chain view, the MCP server when you would rather ask a question than write a query.
_Figure 2: the same vaults, read three ways. The right level depends on whether you write TypeScript, GraphQL, or plain English._
- **Vaults are the foundation:** Lagoon vaults are ERC-7540 contracts onchain, where balances, shares, and valuations live. The data layer sits on top of them.
- **Read the chain directly:** the open-source TypeScript SDK (built on viem) reads vault contracts straight onchain and returns typed objects, with local fee simulation. Our own backend is built on it.
- **Indexed and enriched:** the public GraphQL API at `api.lagoon.finance/query` adds what a single contract read cannot, including performance history, composition, and cross-chain portfolios, with no key.
- **Plain English:** the MCP server sits on the API so fund managers and AI assistants can query and compare vaults conversationally, with no code.
- **An ecosystem, not just contracts:** the data layer is what turns Lagoon vaults into something you can build products, dashboards, and reports on top of.
Explore the Lagoon docs to start building on the SDK, API, and MCP, or query api.lagoon.finance/query directly to see the data for yourself.
## Going further
- **The code:** the [Lagoon SDK](https://github.com/hopperlabsxyz/sdk-v0) and the [Lagoon MCP server](https://github.com/hopperlabsxyz/lagoon-mcp), both open source on GitHub.
- [Lagoon v0.6 is live: security, autonomy, and modularity](/blog/lagoon-smart-contracts-v0-6-preview): the latest contract capabilities the data layer reads from.
- [Vault governance roles: who does what in an onchain fund](/blog/vault-governance-roles): the four-role model exposed through every surface.
- [What is onchain asset management?](/blog/what-is-onchain-asset-management): the bigger picture the vaults and data layer fit into.