Euler SDK

The Euler V2 SDK is the recommended TypeScript entry point for applications, bots, scripts, and operational tooling built on Euler V2. It reads protocol data, composes Ethereum Vault Connector (EVC) batches, simulates transactions, resolves approvals, and executes plans from frontend or backend clients.

The SDK package lives in the euler-sdks monorepo. Use this page as the high-level entry point, then follow the package docs and runnable examples for implementation details.

What the SDK Provides

Fetching account, vault, wallet, and market data
Planning and composing EVC transaction batches
Resolving approvals (standard approve and Permit2 paths)
Simulating and estimating transaction plans with optional state overrides
Swaps, pricing, rewards, labels, FeeFlow, and deployed address resolution
Oracle adapter metadata and checks (provider, methodology, validation)

The SDK is built with dependency injection: use buildEulerSDK() for the default setup, run individual services in isolation, or plug in custom implementations.

Installation

Use the latest stable release:

npm install @eulerxyz/euler-v2-sdk

Minimal Setup

import { buildEulerSDK } from "@eulerxyz/euler-v2-sdk";
import { mainnet } from "viem/chains";
 
const sdk = await buildEulerSDK({
  config: {
    rpcUrls: {
      [mainnet.id]: "https://your-mainnet-rpc",
    },
  },
});

You can also configure RPC URLs with environment variables:

EULER_SDK_RPC_URL_1=https://your-mainnet-rpc

Subgraph Sources for Forks

A fork can supply direct per-chain GraphQL URLs or use an optional catalog. Direct URLs do not require catalog publication or catalog deployment identity checks; they must support the relevant account-discovery or factory-lookup schema. Use SDK 4.4.0 or a compatible newer release for catalog integration, including imported records with optional sourceCommit and startBlock. SDK 4.3.0 introduced the catalog and resolver APIs, but its parser requires both provenance fields. Endpoint/deployment identity checks remain mandatory for catalog reads. The SDK configuration guide describes the complete contract.

For each chain and purpose, selection follows this priority:

config.accountVaultsSubgraphUrls or config.vaultTypeSubgraphUrls entry.
accountVaultsAdapterConfig.subgraphURLs or vaultTypeAdapterConfig.subgraphURLs entry.
EULER_SDK_ACCOUNT_VAULTS_SUBGRAPH_URL_<chainId> or EULER_SDK_VAULT_TYPE_SUBGRAPH_URL_<chainId> entry.
The purpose-specific resolver, otherwise the shared catalog/resolver; without either, a bundled subgraph URL.

Maps merge per chain: {} does not clear lower-priority entries. A false entry disables that purpose for that chain. Omitting subgraphCatalog or setting it to false retains bundled defaults for unmapped chains. Explicit URLs, including environment entries, win over resolvers and retain supported relative, HTTP, and authenticated transports.

The examples select accountServiceAdapter: "onchain" and vaultTypeAdapter: "subgraph" to use the built-in subgraph adapters directly. V3-only services do not use them; a "fallback" service tries V3 first. Custom services remain authoritative. A purpose-specific account resolver overrides the shared resolver; a purpose-specific vault resolver uses vaultTypeAdapterConfig: { subgraphURLs: {}, resolver }, where subgraphURLs selects the subgraph adapter variant.

Direct URLs Only, Without Bundled Subgraph Defaults

import {
  buildEulerSDK,
  SubgraphUnavailableError,
  type SubgraphResolver,
} from "@eulerxyz/euler-v2-sdk";
 
const rejectUnmapped: SubgraphResolver = {
  async resolve(chainId) {
    throw new SubgraphUnavailableError("missing", chainId);
  },
};
 
const sdk = await buildEulerSDK({
  config: {
    rpcUrls: { 1: "https://rpc.operator.example" },
    accountServiceAdapter: "onchain",
    vaultTypeAdapter: "subgraph",
    accountVaultsSubgraphUrls: { 1: "https://subgraph.operator.example/accounts" },
    vaultTypeSubgraphUrls: { 1: "https://subgraph.operator.example/factories" },
    subgraphCatalog: { resolver: rejectUnmapped },
  },
});

This resolver makes no catalog HTTP request and rejects unmapped chains instead of using bundled endpoints. Provide both purpose maps for the chains you use. Remove inherited adapter-map and subgraph environment entries, or make them fork-owned: those entries bypass the rejecting resolver because they are explicit URLs.

Your Own Catalog With Optional Direct Overrides

import { buildEulerSDK } from "@eulerxyz/euler-v2-sdk";
 
const sdk = await buildEulerSDK({
  config: {
    rpcUrls: { 1: "https://rpc.operator.example" },
    accountServiceAdapter: "onchain",
    vaultTypeAdapter: "subgraph",
    subgraphCatalog: { url: "https://operator.example/catalog.json" },
    // Omit per-chain maps unless an endpoint should override the catalog.
  },
});

Keep adapter maps and environment entries unset or fork-owned in this mode too. A missing, retired, invalid, or incompatible catalog record is unavailable, never a reason to use a bundled URL or report an empty portfolio. A supplied catalog snapshot avoids metadata HTTP; injected fetch or resolver implementations support custom transports. Stable is the default channel; candidates require explicit selection. An empty catalog config {} selects the official Euler catalog, not a fork-owned source.

Both modes control subgraph selection, not all SDK traffic. Configure V3, RPC, pricing, swaps, deployments and ABIs independently. For fork-owned labels, use the custom labels service contract; a labels file URL is not an SDK configuration option. See the other service defaults when isolating a fork.

URL metadata is fresh for 60 seconds, with last-good data allowed for at most five minutes and failed refreshes backed off for ten seconds. Failures do not extend the last-good age. Catalog-backed reads validate deployment identity on every page within one read. Ordinary fetchAccountVaults and fetchVaultFactories calls provide an adapter-wide advisory source-changed notice that an unrelated reader can receive first; this notice does not protect a baseline held by a separate polling operation.

For multi-read operations, use the optional AccountVaultsSubgraphAdapter.fetchAccountVaultsWithSource or VaultTypeSubgraphAdapter.fetchVaultFactoriesWithSource methods. They return { value, source? }. Keep the baseline and its source together, require a source, and pass { expectedSource: baseline.source } on each subsequent read. If the resolver selects a different endpoint or deployment, each expected-source read rejects before querying, independently of other readers. On source-changed, discard the baseline and restart the complete operation; retrying the same expectation keeps rejecting. See the source-aware example in the SDK configuration guide.

These methods verify source identity, not indexing freshness, transaction inclusion, or finality. Applications own post-transaction polling. Direct URL maps and custom query overrides return no provenance; supplying an expectation when the source cannot be verified rejects. These endpoints support account-vault discovery and vault-factory lookup, not Activity, pricing, or APYs. Catalog membership does not enable RPC chains or change lifecycle, V3, labels, ABI, or deployment sources. See Subgraphs for publication and network onboarding.

Common Workflows

Read Accounts And Vaults

Use accountService, portfolioService, and vaultMetaService for user and market data.

const { result: account } = await sdk.accountService.fetchAccount(
  mainnet.id,
  "0xOwner...",
  {
    populateAll: true,
  },
);
 
const { result: portfolio } = await sdk.portfolioService.fetchPortfolio(
  mainnet.id,
  "0xOwner...",
);
 
const { result: vault } = await sdk.vaultMetaService.fetchVault(
  mainnet.id,
  "0xVault...",
);

Use vaultMetaService when you do not know whether an address is an EVault, EulerEarn vault, or another supported vault type.

Services can enrich (populate) their own entities with data from other services. For example, the account service can fetch vault details, token prices, rewards, and other data for user positions.

Plan, Simulate, And Execute Transactions

The executionService builds transaction plans for common Euler actions such as deposit, borrow, repay, withdraw, redeem, multiply, liquidation, debt transfer, and swap-driven flows. Plans separate required approvals from executable EVC batch items.

import { parseUnits } from "viem";
 
const { result: account } = await sdk.accountService.fetchAccount(
  mainnet.id,
  "0xOwner...",
);
 
const plan = sdk.executionService.planDeposit({
  account,
  vault: "0xVault...",
  asset: "0xAsset...",
  receiver: "0xReceiverOrSubAccount...",
  amount: parseUnits("100", 6),
  enableCollateral: true,
});
 
const simulation = await sdk.executionService.simulateTransactionPlan(
  mainnet.id,
  account,
  plan,
  { stateOverrides: true },
);
 
if (simulation.canExecute) {
  await sdk.executionService.executeTransactionPlan({
    plan,
    chainId: mainnet.id,
    account,
    sendTransaction: walletClient.sendTransaction,
    signTypedData: walletClient.signTypedData,
  });
}

executeTransactionPlan processes configured plugins, resolves approvals, requests Permit2 signatures when needed, sends direct contract calls, and submits the final EVC batch.

Use Swaps, Rewards, Plugins, And FeeFlow

Use swapService for quote-backed operations such as repay-with-swap, deposit-with-swap, wallet-to-wallet swaps, wallet swap-and-borrow, wallet swap-and-repay, withdraw-and-swap, redeem-and-swap, swap collateral, and swap debt.

Use rewardsService to fetch campaign data, populate account and vault rewards, and build provider-specific reward claim plans.

Use feeFlowService to fetch FeeFlow state, filter eligible vaults, and build FeeFlow buy plans.

Use plugins for flows that need extra read-path or plan-path behavior, such as pull-based oracle updates.

Examples

The repository ships with runnable examples:

TypeScript script examples - deposits, borrows, swaps, swap-and-borrow, swap-and-repay, withdraw-and-swap, redeem-and-swap, liquidations, wallet reads, simulations, FeeFlow, and end-to-end execution flows.
React app example - full frontend using React Query and Wagmi.