Euler V2 SDK

NOTE this is an alpha version, proceed with caution.

Installation

npm install euler-v2-sdk

Example Usage (Multiply + Simulation)

import { buildEulerSDK, getSubAccountAddress } from "euler-v2-sdk";
import { mainnet } from "viem/chains";
import { parseUnits } from "viem";

const sdk = await buildEulerSDK({
  rpcUrls: {
    [mainnet.id]: "https://your-rpc-url",
  },
});

const owner = "0xYourEOA";
const subAccount = getSubAccountAddress(owner, 1);

const account = await sdk.accountService.fetchAccount(mainnet.id, owner, {
  populateVaults: false,
});

const quotes = await sdk.swapService.getDepositQuote({
  chainId: mainnet.id,
  fromVault: "0xLiabilityVault",
  toVault: "0xLongVault",
  fromAccount: subAccount,
  toAccount: subAccount,
  fromAsset: "0xLiabilityAsset",
  toAsset: "0xLongAsset",
  amount: parseUnits("50", 6),
  origin: owner,
  slippage: 0.5,
  deadline: Math.floor(Date.now() / 1000) + 1800,
});

const plan = sdk.executionService.planMultiplyWithSwap({
  account,
  collateralVault: "0xCollateralVault",
  collateralAmount: parseUnits("100", 6),
  collateralAsset: "0xCollateralAsset",
  swapQuote: quotes[0]!,
});

const simulation = await sdk.simulationService.simulateTransactionPlan(
  mainnet.id,
  owner,
  plan,
  { stateOverrides: true }
);

// Use simulated account and vaults state in the UI.
// Use simulation.canExecute or errors to decide whether and how to execute this plan in your app.

What This SDK Is For

euler-v2-sdk provides everything needed to interact with Euler V2 lending contracts:

• fetching account, vault, wallet, and market data
• planning and composing EVC transaction batches
• resolving approvals (approve/Permit2 paths)
• simulating transactions before execution
• handling swaps, pricing, rewards, labels, and deployed addresses
• fetching oracle adapter metadata/checks (provider, methodology, checks)

The SDK is built with dependency injection, so you can use buildEulerSDK() for a default setup, run individual services in isolation, or modify the behavior with your custom implementations.

Configuration

Only rpcUrls is required. All other options (pricing backend, swap API, rewards, subgraphs, plugins, etc.) have sensible defaults or are optional. See the full Configuration Reference for all options and defaults.

Docs Table of Contents

All docs are in ./docs.

1. Configuration - All buildEulerSDK() options, defaults, and service overrides.
2. Basic Usage - Fast setup and common account/vault usage patterns.
3. SDK Architecture Overview - High-level architecture, dependency injection model, and composition options.
4. Services - Service map, top-level entry points, and lower-level support services.
5. Execution Service - encodeX vs planX, approvals flow, mergePlans, and describeBatch.
6. Simulations and State Overrides - Plan simulation flow, validation output, and state override utilities.
7. Swaps - Swap quote APIs and how swap payloads fit into plans.
8. Pricing System - Price data pipeline, fallback behavior, and pricing integration points.
9. Data Architecture - Entities/adapters/services layering, population model, and data flow.
10. Cross-Service Data Population - How services enrich entities with prices, rewards, labels, and nested vaults.
11. Account Computed Properties - Health factor/LTV/net-value computed fields and data prerequisites.
12. Caching External Data Queries - query* decoration pattern for caching/logging/profiling.
13. Plugins - Plugin system for read-path and plan-path extensions.
14. Labels - Label metadata model and usage.
15. Decoding Smart Contract Errors - Revert decoding utilities for better error handling.
16. Entity Diagnostics - Sidecar metadata for data normalization, fallbacks, and per-field warnings.

Examples

Runnable examples are in ./examples, including end-to-end execution flows and simulations against a fork.

Release Process

This package is published via GitHub Actions, not by running npm publish locally.

1. Open a PR targeting main that bumps the version in package.json.
2. Update CHANGELOG.md and refresh RELEASE_NOTES.md in the same PR.
3. Let the Validate euler-v2-sdk PR workflow pass. It enforces that the package version changed and runs release:check.
4. Merge the PR. The Release euler-v2-sdk workflow runs automatically on the merge commit, publishes the package to npm, creates the euler-v2-sdk-v<version> tag, and creates a GitHub release.