Route Widget - Enso Developer Documentation

Github

Source code

Route Widget Live Demo

Try it out!

Features

Desired operation: Any-to-any token swaps and position entry/exit across multiple chains (zap-in, deposit, stake, and more)
Automatic route building: Automatically constructs an optimal transaction involving multiple protocols and tokens
Shortcut preview: Previews of token balances, USD values, and price impact preview

Integration

You can integrate the Enso shortcuts widget into your React application.

1. Install the package

npm install @ensofinance/shortcuts-widget wagmi viem @tanstack/react-query

Note: Requires wagmi v2, @tanstack/react-query v5, react and react-dom as peer dependencies.

2. Import and use the component

The widget must be rendered inside WagmiProvider and QueryClientProvider. It reads the connected account from wagmi, so wallet connection is handled by your app.

import SwapWidget from "@ensofinance/shortcuts-widget";
import { WagmiProvider, createConfig, http } from "wagmi";
import { mainnet } from "wagmi/chains";
import { injected } from "wagmi/connectors";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const config = createConfig({
  chains: [mainnet],
  connectors: [injected()],
  transports: {
    [mainnet.id]: http(),
  },
});

const queryClient = new QueryClient();

function App() {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <SwapWidget apiKey="YOUR_API_KEY" />
      </QueryClientProvider>
    </WagmiProvider>
  );
}

export default App;

3. Props & Configuration

Prop	Type	Description	Required
`apiKey`	`string`	Enso API key	Yes
`tokenIn`	`Address`	Input token address	No
`tokenOut`	`Address`	Output token address	No
`chainId`	`number`	Starting position’s chain ID	Required with token addresses
`outChainId`	`number`	Destination chain ID for cross-chain routes	No
`themeConfig`	`SystemConfig`	Chakra UI v3 theme config	No
`enableShare`	`boolean`	Enable route sharing	No
`obligateSelection`	`boolean`	Force token selection	No
`indicateRoute`	`boolean`	Show swap route path	No
`adaptive`	`boolean`	Adapt the UI to the container size	No
`rotateObligated`	`boolean \| ObligatedToken`	Show an arrow to rotate the obligated token selection	No
`outProject`	`string`	Restrict output tokens to a single project	No
`outProjects`	`{ include: string[]; exclude: string[] }`	Filter output tokens by project	No
`inProjects`	`{ include: string[]; exclude: string[] }`	Filter input tokens by project	No
`outTokens`	`{ include: Address[]; exclude: Address[] }`	Filter output tokens	No
`inTokens`	`{ exclude: Address[] }`	Exclude input tokens	No
`onChange`	`(state: WidgetState) => void`	Called when tokens or chains change	No
`onSuccess`	`(hash: string, details?: SuccessDetails) => void`	Called after a successful transaction	No
`notificationPlacement`	`Placement`	Position of transaction notifications	No
`referralCode`	`string`	16-byte string for on-chain request tracking	No
`baseUrl`	`string`	Override the Enso API base URL	No
`fontFamily`	`string`	Font family used by the widget	No

Examples

Pre-selected Tokens

<SwapWidget
  apiKey="YOUR_API_KEY"
  chainId={1}
  tokenIn="0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2" // WETH
  tokenOut="0x6B175474E89094C44Da98b954EedeAC495271d0F" // DAI
/>;

Custom Theme

<SwapWidget
  apiKey="YOUR_API_KEY"
  themeConfig={{
    theme: {
      semanticTokens: {
        colors: {
          primary: { value: "#3498db" },
          bg: { value: "#f8f9fa" },
        },
      },
    },
  }}
  enableShare={true}
  indicateRoute={true}
/>;

APIs used

The Widget uses the following APIs:

GET /api/v1/tokens to fetch the tokens and positions on the selected chain
GET /api/v1/wallet/balances to fetch the user’s token balances and display the exact amount for each position
GET /api/v1/shortcuts/route to get the optimal route for user’s intended operation

Get Your API Key

Updated 2025-07-07

Github

Route Widget Live Demo

​Features

​Integration

​1. Install the package

​2. Import and use the component

​3. Props & Configuration

​Examples

​Pre-selected Tokens

​Custom Theme

​APIs used

​Get Your API Key