Core Concepts - Enso Developer Documentation

Enso turns product intent into executable transaction data. Most integrations combine a small set of primitives: discover what can be shown, read what the user owns, request a route or bundle, submit the returned transaction, and refresh balances after execution.

The Enso Mental Model

Primitive	What it means	Primary endpoint or guide
Tokens and protocol data	What your product can show, compare, or route into. Use this for APY, TVL, protocol, chain, decimals, logos, and underlying assets.	`GET /v1/tokens`, Protocol Data
Balances	What the user owns before and after execution, including wallet assets and DeFi position tokens.	`GET /v1/wallet/balances`, Balances
Route API	Enso chooses the path from one source asset or position into one final destination. Use this for swaps, zaps, deposits, withdrawals, migrations, and simple cross-chain routes.	`POST /v1/shortcuts/route`, Route API
Bundle API	Your product specifies an ordered list of actions and Enso turns the same-chain sequence into one transaction. Use this when the workflow needs custom sequencing, dynamic outputs, checks, or actions Route does not cover.	`POST /v1/shortcuts/bundle`, Bundle API
Approval	An ERC-20 approval transaction required only when the user spends through the Enso router and allowance is not already high enough.	`GET /v1/wallet/approve`
Bridge status	Status tracking for async cross-chain execution after the source-chain transaction is submitted.	Bridge Status
Quoter	Validation for transactions generated outside Enso. Enso route and action responses are already simulated as part of the Enso flow.	Quoter

Standard Build Flow

Discover supported chains, tokens, protocols, actions, and yield destinations.
Read the user’s balances and current DeFi positions.
Build a Route request when Enso should find the path, or a Bundle request when your product controls the action sequence.
Ask for approval only when the route or bundle spends an ERC-20 through the router and allowance is insufficient.
Submit the returned transaction as-is.
Track bridge status only for async cross-chain routes.
Refresh balances and position metadata after confirmation.

Route API, Bundle API, and `enso:route`

Use the canonical Route API vs Bundle API comparison to choose an endpoint. Route API lets Enso choose the path. Bundle API lets your product submit an ordered action array. The enso:route action is one action available inside that array. Actions executed in one same-chain transaction are atomic. Cross-chain delivery and destination callbacks are asynchronous; monitor them through Bridge Status.

Product Entry Points

Product	Start here	Essential surface
Earn tab or yield marketplace	Enso Earn	Token catalog, balances, route, conditional approval, refreshed balances
Wallet swaps and zaps	Route	Token discovery, route, returned `tx`, refreshed balances
Cross-chain deposit	Crosschain Routing	Source-chain route, bridge callback, bridge status, destination balance
Custom multi-action workflow	Bundle	Action list, dynamic outputs, checks, returned transaction
Third-party transaction validation	Quoter	Simulate and validate calldata generated outside Enso

UI Fields To Plan For

Screen	Data to show	Source
Catalog	APY, TVL, protocol, chain, token symbol, decimals, underlying assets, logo	`GET /v1/tokens`
Portfolio	Asset amount, USD value, token metadata, current DeFi position tokens	`GET /v1/wallet/balances` plus `GET /v1/tokens`
Quote review	Expected output, minimum output, gas, price impact, selected route, transaction target	`POST /v1/shortcuts/route`
Approval	Token, spender, amount, chain, approval transaction	`GET /v1/wallet/approve`
Post-execution	New source balance, new destination position, any dust, current APY and metadata	`GET /v1/wallet/balances` plus `GET /v1/tokens`

Updated

​The Enso Mental Model

​Standard Build Flow

​Route API, Bundle API, and enso:route

​Product Entry Points

​UI Fields To Plan For

The Enso Mental Model

Standard Build Flow

Route API, Bundle API, and `enso:route`

Product Entry Points

UI Fields To Plan For