> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enso.build/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK

> Enso SDK is a JavaScript library for interacting with Enso API.

export const date_0 = "2025-08-07"

The Enso SDK provides a set of tools and methods to interact with the Enso API. It includes functionalities for token approvals, routing, quoting, and balance checking. The Route API is a highly-efficient DeFi aggregation and smart order routing REST API. With it, developers can easily tap into optimized routes for DeFi tokens/positions and multi-token swaps across various chains.

<Card href="https://github.com/EnsoBuild/sdk-ts" icon="github" iconType="solid" title="View on GitHub" target="_blank" />

## Installation

Install the Enso SDK using your preferred package manager:

<CodeGroup dropdown>
  ```bash npm theme={null}
  npm install @ensofinance/sdk
  ```

  ```bash yarn theme={null}
  yarn add @ensofinance/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @ensofinance/sdk
  ```

  ```bash bun theme={null}
  bun add @ensofinance/sdk
  ```
</CodeGroup>

## Quick Start

This example shows how to swap ETH directly to a Yearn vault position:

```typescript theme={null}
import { EnsoClient } from '@ensofinance/sdk';

const enso = new EnsoClient({
  apiKey: 'YOUR_API_KEY',
});

async function enterYearnVault() {
  // First, get the transaction data
  const routeData = await enso.getRouteData({
    fromAddress: '0xYourWalletAddress',
    receiver: '0xYourWalletAddress',
    spender: '0xYourWalletAddress',
    chainId: 1,
    amountIn: ['1000000000000000000'], // 1 ETH
    tokenIn: ['0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee'], // ETH
    tokenOut: ['0xa258C4606Ca8206D8aA700cE2143D7db854D168c'], // yvWETH
    slippage: 50,
    routingStrategy: 'router',
  });
  
  // The routeData.tx object can now be sent using your preferred web3 library
  // Example with ethers.js:
  // const provider = new ethers.providers.Web3Provider(window.ethereum);
  // const signer = provider.getSigner();
  // const tx = await signer.sendTransaction(routeData.tx);
  // await tx.wait();
  
  console.log('Transaction data:', routeData.tx);
  console.log('Expected yvWETH amount:', routeData.amountOut);
}

enterYearnVault();
```

## Core Concepts

The Enso SDK abstracts complex DeFi operations through several key components:

1. **EnsoClient**: The main entry point for all SDK functionalities
2. **Routing Strategies**: Different execution paths for transactions
3. **Bundle Actions**: Compose multiple DeFi operations in a single transaction
4. **Approvals**: Manage token allowances for DeFi interactions
5. **Token Data**: Retrieve detailed information about tokens and protocols

## 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
* **`delegate-legacy`** - Legacy version of delegate routing
* **`router-legacy`** - Legacy version of router routing

## Complete Methods Reference

### Primary Methods

#### getRouteData(params: RouteParams)

Calculates the optimal route for token swaps or entering/exiting DeFi positions.

**Parameters:**

* `fromAddress` (Address): Ethereum address of the wallet to send the transaction from
* `receiver?` (Address): Ethereum address of the receiver of the tokenOut
* `spender?` (Address): Ethereum address of the spender of the tokenIn
* `chainId` (number): Chain ID of the network to execute the transaction on
* `destinationChainId?` (number): Chain ID of the destination network for cross-chain bridging
* `amountIn` (Quantity\[]): Amount of tokenIn to swap in wei
* `slippage?` (Quantity): Slippage in basis points (1/10000)
* `minAmountOut?` (Quantity\[]): Minimum amount out in wei
* `tokenIn` (Address\[]): Ethereum address of the token to swap from
* `tokenOut` (Address\[]): Ethereum address of the token to swap to
* `routingStrategy` (RoutingStrategy): Routing strategy to use
* `fee?` (Quantity\[]): Fee in basis points for each amountIn value
* `feeReceiver?` (Address): Address that will receive the collected fee
* `ignoreAggregators?` (string\[]): List of swap aggregators to ignore
* `ignoreStandards?` (string\[]): List of standards to ignore
* `toEoa?` (boolean): Flag indicating if gained tokenOut should be sent to EOA
* `referralCode?` (string): Referral code included in on-chain event

**Returns:** `Promise<RouteData>`

```typescript theme={null}
const routeData = await enso.getRouteData({
  fromAddress: '0xYourWalletAddress',
  receiver: '0xYourWalletAddress',
  spender: '0xYourWalletAddress',
  chainId: 1,
  amountIn: ['1000000000000000000'], // 1 ETH in wei
  tokenIn: ['0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee'], // ETH
  tokenOut: ['0x6b175474e89094c44da98b954eedeac495271d0f'], // DAI
  slippage: 50, // 0.5%
  routingStrategy: 'router',
});
```

#### getApprovalData(params: ApproveParams)

Generates transaction data for approving tokens to be spent by Enso contracts.

**Parameters:**

* `fromAddress` (Address): Ethereum address of the wallet to send the transaction from
* `tokenAddress` (Address): ERC20 token address of the token to approve
* `chainId` (number): Chain ID of the network to execute the transaction on
* `amount` (Quantity): Amount of tokens to approve in wei

**Returns:** `Promise<ApproveData>`

```typescript theme={null}
const approvalData = await enso.getApprovalData({
  fromAddress: '0xYourWalletAddress',
  tokenAddress: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2', // WETH
  chainId: 1,
  amount: '1000000000000000000', // 1 WETH in wei
});
```

#### getBundleData(params: BundleParams, actions: BundleAction\[])

Constructs bundled transaction data for multiple DeFi operations in a single transaction.

**Parameters:**

* `chainId` (number): Chain ID of the network to execute the transaction on
* `fromAddress` (Address): Ethereum address of the wallet to send the transaction from
* `routingStrategy` (RoutingStrategy): Routing strategy to use
* `receiver?` (Address): Ethereum address of the receiver of the tokenOut
* `spender?` (Address): Ethereum address of the spender of the tokenIn
* `ignoreAggregators?` (string\[]): List of swap aggregators to ignore
* `referralCode?` (string): Referral code included in on-chain event
* `ignoreStandards?` (string\[]): List of standards to ignore
* `actions` (BundleAction\[]): Array of actions to bundle

**Returns:** `Promise<BundleData>`

```typescript theme={null}
const bundle = await enso.getBundleData(
  {
    chainId: 1,
    fromAddress: '0x123...',
    routingStrategy: 'delegate',
  },
  [
    {
      protocol: 'enso',
      action: 'route',
      args: {
        tokenIn: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
        tokenOut: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
        amountIn: '1000000000',
        receiver: '0x123...'
      }
    }
  ]
);
```

### Data Retrieval Methods

#### getBalances(params: BalanceParams)

Retrieves token balances for a given wallet address.

**Parameters:**

* `chainId?` (number): Chain ID of the network to execute the transaction on
* `eoaAddress` (Address): Address of the EOA to associate with the ensoWallet for balances
* `useEoa?` (boolean): If true, returns balances for the provided eoaAddress instead of the associated ensoWallet

**Returns:** `Promise<WalletBalance[]>`

```typescript theme={null}
const balances = await enso.getBalances({
  chainId: 1,
  eoaAddress: '0xYourWalletAddress',
  useEoa: true,
});
```

#### getTokenData(params: TokenParams)

Fetches detailed information about tokens, including DeFi tokens and their underlying assets.

**Parameters:**

* `project?` (string): The overarching project or platform associated with the DeFi token
* `protocolSlug?` (string): The specific standard integration or version of the DeFi project
* `underlyingTokens?` (MultiAddress): Underlying tokens of defi token
* `underlyingTokensExact?` (MultiAddress): Exact composition of underlying tokens
* `primaryAddress?` (MultiAddress): Ethereum addresses for contract interaction
* `address?` (MultiAddress): Ethereum addresses of the tokens
* `chainId?` (number): Chain ID of the network of the token
* `type?` (TokenType): Type of token ('defi' | 'base')
* `apyFrom?` (Quantity): Only include tokens with APY over this value
* `apyTo?` (Quantity): Only include tokens with APY below this value
* `tvlFrom?` (Quantity): Only include tokens with TVL over this value
* `tvlTo?` (Quantity): Only include tokens with TVL below this value
* `page?` (number): Pagination page number (pages are of length 1000)
* `cursor?` (number): Cursor for pagination
* `includeMetadata?` (boolean): Whether to include token metadata
* `name?` (string\[]): Names of the tokens
* `symbol?` (string\[]): Symbols of the tokens

**Returns:** `Promise<PaginatedTokenData>`

```typescript theme={null}
const tokens = await enso.getTokenData({
  chainId: 1,
  type: 'defi',
  includeMetadata: true,
  page: 1
});
```

#### getPriceData(params: PriceParams)

Gets the current price data for a specific token.

**Parameters:**

* `chainId` (number): Chain ID of the network to search for
* `address` (Address): Address of the token to search for

**Returns:** `Promise<PriceData>`

```typescript theme={null}
const price = await enso.getPriceData({
  chainId: 1,
  address: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2', // WETH
});
```

#### getMultiplePriceData(params: MultiPriceParams)

Gets price data for multiple tokens.

**Parameters:**

* `chainId` (number): Chain ID of the network to search for
* `addresses` (Address\[]): Addresses of tokens to check prices for

**Returns:** `Promise<PriceData[]>`

```typescript theme={null}
const prices = await enso.getMultiplePriceData({
  chainId: 1,
  addresses: [
    '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH
    '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'  // USDC
  ]
});
```

### Protocol and Standard Methods

#### getProtocolData(params?: ProtocolParams)

Retrieves information about DeFi protocols supported by Enso.

**Parameters:**

* `chainId?` (number | string): Chain ID of the network to search for
* `slug?` (string): Slug of the project to search for

**Returns:** `Promise<ProtocolData[]>`

```typescript theme={null}
// Get all protocols
const allProtocols = await enso.getProtocolData();

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

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

#### getStandards()

Returns standards available for bundling with protocol information and supported actions.

**Returns:** `Promise<StandardData[]>`

```typescript theme={null}
const standards = await enso.getStandards();
```

#### getStandardBySlug(slug: string)

Returns a standard matching the given slug with supported actions and chains.

**Parameters:**

* `slug` (string): The protocol slug

**Returns:** `Promise<StandardData[]>`

```typescript theme={null}
const aaveStandard = await enso.getStandardBySlug('aave-v3');
```

#### getActions()

Returns all actions that can be bundled with the `/shortcuts/bundle` endpoint.

**Returns:** `Promise<ActionData[]>`

```typescript theme={null}
const actions = await enso.getActions();
```

#### getActionsBySlug(slug: string)

Gets actions for a specific protocol.

**Parameters:**

* `slug` (string): The protocol slug

**Returns:** `Promise<ActionData[]>`

```typescript theme={null}
const aaveActions = await enso.getActionsBySlug('aave-v3');
```

### Specialized Methods

#### getRouteNonTokenized(params: RouteNonTokenizedParams)

Gets execution data for best route to non-tokenized positions.

**Parameters:**

* `chainId` (number): Chain ID of the network to execute the transaction on
* `fromAddress` (Address): Ethereum address of the wallet to send the transaction from
* `routingStrategy` ('delegate' | 'delegate-legacy'): Routing strategy to use
* `tokenIn` (Address\[]): Input tokens
* `positionOut` (Address): Non-tokenized position to receive
* `slippage?` (Quantity): Slippage in basis points
* `fee?` (Quantity\[]): Fee in basis points
* `feeReceiver?` (Address): Fee receiver address
* `amountIn` (Quantity\[]): Amount to send
* `receiver` (Address): Receiver address
* `spender?` (Address): Spender address
* `referralCode?` (string): Referral code

**Returns:** `Promise<RouteData>`

```typescript theme={null}
const route = await enso.getRouteNonTokenized({
  fromAddress: '0x123...',
  chainId: 1,
  routingStrategy: 'delegate',
  tokenIn: ['0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'],
  positionOut: '0xPositionAddress',
  amountIn: ['1000000000'],
  receiver: '0x123...',
  slippage: 50,
});
```

#### getIporShortcut(params, data: IporShortcutInputData)

Returns a transaction for IPOR shortcut operations.

**Parameters:**

* `chainId?` (number): Chain ID (optional)
* `fromAddress` (string): Ethereum address of the wallet
* `data` (IporShortcutInputData): IPOR shortcut input data

**Returns:** `Promise<IporShortcutData>`

```typescript theme={null}
const iporShortcut = await enso.getIporShortcut(
  { chainId: 1, fromAddress: '0x123...' },
  {
    amountIn: '1000000000000000000',
    tokenIn: '0xTokenAddress',
    tokenBToBuy: '0xTokenBAddress',
    percentageForTokenB: 5000, // 50%
    slippage: 50,
    simulate: true
  }
);
```

#### getNonTokenizedPositions(params?: NonTokenizedParams)

Gets all non-tokenized positions with details.

**Parameters:**

* `project?` (string): The overarching project or platform
* `protocolSlug?` (string): The specific standard integration
* `chainId?` (number): Chain ID of the network
* `destinationChainId?` (number): Destination chain ID for cross-chain bridging
* `address?` (Address\[]): Ethereum addresses of positions
* `primaryAddress?` (Address\[]): Ethereum addresses for contract interaction
* `page?` (number): Pagination page number
* `cursor?` (number): Cursor for pagination

**Returns:** `Promise<PaginatedNonTokenizedPositionData>`

```typescript theme={null}
const nonTokenizedPositions = await enso.getNonTokenizedPositions({
  chainId: 1,
  project: 'aave'
});
```

### Network and Utility Methods

#### getNetworks(params?: NetworkParams)

Returns networks supported by Enso.

**Parameters:**

* `name?` (string): Name of the network to search for
* `chainId?` (string): Chain ID of the network to search for

**Returns:** `Promise<ConnectedNetwork[]>`

```typescript theme={null}
const networks = await enso.getNetworks();
const ethereum = await enso.getNetworks({ chainId: "1" });
```

#### getProjects()

Returns supported projects or platforms associated with available protocols.

**Returns:** `Promise<Project[]>`

```typescript theme={null}
const projects = await enso.getProjects();
```

#### getProtocolsByProject(project: string)

Returns all protocols available within the given project.

**Parameters:**

* `project` (string): The project name

**Returns:** `Promise<ProtocolData[]>`

```typescript theme={null}
const aaveProtocols = await enso.getProtocolsByProject('aave');
```

#### getAggregators(chainId?: number)

Fetches aggregators supported by Enso.

**Parameters:**

* `chainId?` (number): Chain ID to filter aggregators for

**Returns:** `Promise<string[]>`

```typescript theme={null}
const aggregators = await enso.getAggregators(1);
```

#### getVolume(chainId: number)

Returns total USD and transactions volume for the given chainId.

**Parameters:**

* `chainId` (number): Chain ID to get volume for

**Returns:** `Promise<unknown>`

```typescript theme={null}
const volume = await enso.getVolume(1);
```

#### getAccountId()

Gets the account ID associated with the API key.

**Returns:** `Promise<string>`

```typescript theme={null}
const accountId = await enso.getAccountId();
```

## Working with Large Numbers

The SDK properly handles large numbers common in blockchain transactions:

```typescript theme={null}
// 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
```

## Bundle 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:

```typescript theme={null}
// Get all available actions
const actions = await enso.getActions();

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

Common bundle actions include:

* **Route**: Token swaps and conversions
* **Deposit**: Deposit tokens into DeFi protocols
* **Redeem**: Withdraw tokens from DeFi protocols
* **Approve**: Token approvals
* **Borrow**: Borrow tokens from lending protocols
* **Repay**: Repay loans to lending protocols
* **Transfer**: Transfer tokens between addresses
* **Bridge**: Cross-chain token transfers

## Error Handling

The SDK includes proper error handling with custom error types:

```typescript theme={null}
import { EnsoClient, EnsoApiError } from '@ensofinance/sdk';

try {
  const routeData = await enso.getRouteData(params);
} catch (error) {
  if (error instanceof EnsoApiError) {
    console.error('API Error:', error.statusCode, error.responseData);
  } else {
    console.error('Request Error:', error.message);
  }
}
```

## Best Practices

1. **Use String Representations**: Always use string representations for token amounts to avoid precision issues with large numbers
2. **Handle Slippage**: Set appropriate slippage values (in basis points) to protect against price movements
3. **Gas Estimation**: Use the returned `gas` estimate to set appropriate gas limits
4. **Error Handling**: Implement proper error handling for network issues and API errors
5. **Rate Limiting**: Be mindful of API rate limits when making multiple requests

## Next Steps

Explore these resources to fully leverage the Enso SDK:

* [Routing Strategies](/pages/build/reference/routing-strategies) - Learn about the different routing options and when to use each one
* [Available Actions for Bundle API](/pages/build/reference/actions) - Explore all supported DeFi actions like swaps, deposits, borrows, and more
* [Shortcuts](/pages/build/examples/shortcuts) - See practical examples of common DeFi operations implemented with the SDK
* [Non-tokenized Positions](/pages/build/examples/route-nontokenized) - Discover how to interact with non-tokenized DeFi positions like Aave borrows or Liquity CDPs
* [GitHub Repository](https://github.com/EnsoBuild/sdk-ts) - Access the source code, report issues, or contribute to the SDK
* [Developer Chat](https://t.me/enso_shortcuts) - Join our Telegram group for technical support and discussions

<div className="text-right text-xs gray-200 font-semibold w-full" style={{marginTop: '0'}}>
  <p style={{
        color: "#b2b2b2"  
    }}>Updated {date_0}</p>
</div>