Enso SDK

The Enso SDK provides a set of tools and methods to interact with the Enso shortcuts. It includes functionalities for automated swap routing, multichain routing, token approvals, quoting, and balance checking.

Introduction

The Enso API offers two powerful routing components:

1. Route API: Finds the optimal execution path across multiple DeFi protocols including liquidity pools, lending platforms, automated market makers, yield optimizers, and more. It automatically determines the best path between two tokens or positions.

2. Bundle API: Enables building custom route creators for complex multi-step DeFi operations by composing sequences of actions. This is perfect for advanced use cases like yield farming, leveraged positions, and portfolio rebalancing.

Installation

npm install @ensofinance/sdk

or

yarn add @ensofinance/sdk

Quick Start

import { EnsoClient } from "@ensofinance/sdk";

// Initialize the client with your API key
const ensoClient = new EnsoClient({
  apiKey: "YOUR_API_KEY",
});

// Get the best route from one token to another
const routeData = await ensoClient.getRouteData({
  fromAddress: "0xYourAddress",
  chainId: 1,
  amountIn: ["1000000000000000000"],
  tokenIn: ["0xTokenInAddress"],
  tokenOut: ["0xTokenOutAddress"],
  routingStrategy: "router",
});

// Execute the transaction with your web3 provider
// const tx = await web3.eth.sendTransaction(routeData.tx);

Routing Strategies

There are 3 routing strategies available depending on your use case:

• router - Uses a single contract which acts as a universal router
• delegate - Returns calldata in the form of delegateCalls for smart accounts
• ensowallet - Returns calldata for deploying an Enso smart account, and executing all the logic inside of the smart account in the same transaction

Core Features

Token Approvals

Get approval data to allow token spending when using router as routingStrategy (not needed when using delegate):

// Example: Approving USDC for spending
const approvalData = await ensoClient.getApprovalData({
  fromAddress: "0xYourAddress",
  tokenAddress: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", // USDC
  chainId: 1,
  amount: "1000000000", // 1000 USDC (6 decimals)
  routingStrategy: "router",
});

Automated Routing

Get the optimal execution data for a route between tokens:

const routeData = await ensoClient.getRouteData({
  fromAddress: "0xYourAddress",
  receiver: "0xReceiverAddress", // Optional, defaults to fromAddress
  chainId: 1,
  amountIn: ["1000000000000000000"],
  tokenIn: ["0xTokenInAddress"],
  tokenOut: ["0xTokenOutAddress"],
  slippage: "50", // 0.5%
  routingStrategy: "router",
});

Wallet Balances

Get token balances for a wallet:

// Example: Get all token balances for an Ethereum address
const balances = await ensoClient.getBalances({
  eoaAddress: "0xYourAddress",
  chainId: 1, // Ethereum mainnet
  useEoa: true, // Default is true - get balances for the EOA, not the Enso wallet
});

Bundled Transactions

Bundle multiple DeFi actions into a single transaction and use results between transactions.

// Example: Convert ETH to USDC then deposit into Aave V3
const bundleData = await ensoClient.getBundleData(
  {
    fromAddress: "0xYourAddress",
    chainId: 1,
    routingStrategy: "router",
  },
  [
    {
      protocol: "enso",
      action: "route",
      args: {
        tokenIn: "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", // ETH
        tokenOut: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", // USDC
        amountIn: "1000000000000000000", // 1 ETH
        slippage: "100", // 1%
      },
    },
    {
      protocol: "aave-v3",
      action: "deposit",
      args: {
        tokenIn: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", // USDC
        tokenOut: "0xbcca60bb61934080951369a648fb03df4f96263c", // aUSDC v3
        amountIn: {
          useOutputOfCallAt: 0, // Use output from the first action
        },
        primaryAddress: "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2", // Aave V3 pool
      },
    },
  ],
);

Bridging Pool Address

Use getLayerZeroPool to get the correct pool information, and use it as primaryAddress for the bridge action.

const poolInfo = await client.getLayerZeroPool({
  chainId: 42161, // Arbitrum
  destinationChainId: 999, // Zora  
  token: '0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9' // USDT
});

Non-Tokenized Positions

Route to a non-tokenized position:

// Example: Routing to a Morpho Blue USDC vault position
const nonTokenizedRoute = await ensoClient.getRouteNonTokenized({
  fromAddress: "0xYourAddress",
  chainId: 1,
  tokenIn: ["0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"], // ETH
  positionOut: "0xBEeFFF209270748ddd194831b3fa287a5386f5bC", // Morpho USDC vault
  amountIn: ["1000000000000000000"], // 1 ETH
  receiver: "0xYourAddress",
  slippage: "300", // 3%
  routingStrategy: "delegate",
});

Token Data

Get paginated information about tokens:

// Example: Get details about wstETH including metadata
const tokenData = await ensoClient.getTokenData({
  chainId: 1,
  address: "0x7f39c581f595b53c5cb19bd0b3f8da6c935e2ca0", // wstETH
  includeMetadata: true,
  type: "defi", // Filter by token type - can be "defi" or "base"
});

Token Pricing

Get token price data:

// Example: Get current price of WETH
const priceData = await ensoClient.getPriceData({
  chainId: 1,
  address: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
});

// Example: Get prices for multiple tokens
const multiPriceData = await ensoClient.getMultiplePriceData({
  chainId: 1,
  addresses: [
    "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
    "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
  ],
});

Protocol Support

Get information about supported protocols:

// Get all protocols
const protocols = await ensoClient.getProtocolData();

// Get protocols for a specific chain
const ethereumProtocols = await ensoClient.getProtocolData({ chainId: 1 });

// Get a specific protocol
const aaveProtocol = await ensoClient.getProtocolData({ slug: "aave-v3" });

Handling Large Numbers

The SDK properly handles large numbers common in blockchain transactions:

// Using string representation for large numbers (recommended)
const largeAmount = "1000000000000000000000000"; // 1 million tokens with 18 decimals

// You can also use JavaScript numbers for smaller values
const smallAmount = 1000000; // 1 USDC with 6 decimals

Supported Actions

The Bundle API supports a variety of actions for interacting with DeFi protocols.

For an up-to-date reference of all available actions and their parameters, you can call:

// Get all available actions
const actions = await ensoClient.getActions();

// Get actions for a specific protocol
const aaveActions = await ensoClient.getActionsBySlug("aave-v3");

Supported Networks

To get information about supported networks:

// Get all supported networks
const networks = await ensoClient.getNetworks();

// Get a specific network
const ethereumNetwork = await ensoClient.getNetworks({
  chainId: "1",
  name: "Ethereum",
});

API Reference

For detailed information about all available methods and parameters, see our API Reference Documentation.

Main Client Methods

| Method | Description | | -------------------------- | ------------------------------------------------- | | getApprovalData | Get token approval transaction data | | getRouteData | Get optimal routing between tokens | | getBalances | Get wallet token balances | | getTokenData | Get token information | | getPriceData | Get token price data | | getMultiplePriceData | Get prices for multiple tokens | | getProtocolData | Get protocol information | | getBundleData | Bundle multiple actions into a single transaction | | getRouteNonTokenized | Get optimal routing to a non-tokenized position | | getIporShortcut | Get transaction data for IPOR operations | | getStandards | Get available standards for bundling | | getActions | Get actions that can be bundled | | getNonTokenizedPositions | Get non-tokenized positions | | getProjects | Get supported projects | | getProtocolsByProject | Get protocols within a project | | getNetworks | Get supported networks | | getAggregators | Get supported aggregators | | getVolume | Get volume data for a chain |

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.