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 | 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 |
| Bundle | Your product specifies an ordered list of actions and Enso turns them 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 |
| 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 vs Bundle
| Use case | Use Route | Use Bundle |
|---|---|---|
| Token swap | Yes | Rarely |
| Deposit into one tokenized position | Yes | Only if custom actions are required |
| Withdraw or redeem from one position | Yes | Only if follow-up actions are required |
| Position migration | Yes | Use Bundle when fixed action order matters |
| Harvest, borrow, repay, leverage, or claim | No | Yes |
| Cross-chain route into a destination token or position | Yes | Use Bundle only for custom post-bridge logic |
| Multiple checks, dynamic outputs, or custom callbacks | No | Yes |
tx for the path Enso selected. Bundle returns a signer-ready transaction built from the actions your product specified.
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