> ## 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.
# Optimal route between two tokens
> Calculates optimal transaction with the best route between two tokens, which may involve several actions that interact with various DeFi protocols. This single call already quotes internally and returns executable calldata along with `amountOut` and `gas`, so there is no separate quote step to call beforehand. To enter a non-tokenized position, use the GET `/shortcuts/route/nontokenized`.
## OpenAPI
````yaml /public/openapi.json post /api/v1/shortcuts/route
openapi: 3.0.0
info:
title: Enso API
description: >-
#### Enso API
- Find detailed documentation on
[docs.enso.finance](https://docs.enso.finance).
- To use the API, **you must include your API Key in the Authorization
header** (Bearer format).
- For testing, Swagger pre-authorizes you using the key:
`1e02632d-6feb-4a75-a157-documentation` (1rps).
- Get your own API Key at
[enso.finance/developers](https://enso.finance/developers).
version: 1.0.1
contact: {}
servers:
- url: https://api.enso.build
security:
- {}
tags:
- name: shortcuts
description: ''
paths:
/api/v1/shortcuts/route:
post:
tags:
- DeFi Shortcuts
summary: Optimal route between two tokens
description: >-
Calculates optimal transaction with the best route between two tokens,
which may involve several actions that interact with various DeFi
protocols. This single call already quotes internally and returns
executable calldata along with `amountOut` and `gas`, so there is no
separate quote step to call beforehand. To enter a non-tokenized
position, use the GET `/shortcuts/route/nontokenized`.
operationId: RouterController_postRouteShortcutTransaction
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RouteShortcutVariableInputs'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/RouteShortcutTransaction'
'400':
description: ''
components:
schemas:
RouteShortcutVariableInputs:
type: object
properties:
chainId:
type: number
description: Chain ID of the network to execute the transaction on
default: 1
fromAddress:
type: string
description: Ethereum address of the wallet to send the transaction from
example: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045'
amountIn:
description: Amount of tokenIn to swap in wei
example:
- '1000000000000000000'
type: array
items:
type: string
tokenIn:
description: >-
Ethereum address of the token to swap from. For ETH, use
0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
example:
- '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee'
type: array
items:
type: string
tokenOut:
description: >-
Ethereum address of the token to swap to. For ETH, use
0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
example:
- '0x6b175474e89094c44da98b954eedeac495271d0f'
type: array
items:
type: string
routingStrategy:
type: string
description: >-
Routing strategy to use. In majority of cases you can use `router`.
Use `delegate` with EOA when you want to specify a `spender`
nullable: true
enum:
- router
- delegate
- router-legacy
- delegate-legacy
- ensowallet
toEoa:
type: boolean
description: Flag that indicates if gained tokenOut should be sent to EOA
nullable: true
deprecated: true
includeTransactionCost:
type: boolean
description: >-
Include point-in-time source-chain transaction cost estimates in
native units and USD, plus USD values for reported bridge fees
default: false
receiver:
type: string
description: Ethereum address of the receiver of the tokenOut
example: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045'
spender:
type: string
description: >-
Ethereum address of the spender of the tokenOut. **Note**: you must
use the `delegate` strategy when specifying a spender, otherwise it
will be ignored.
example: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045'
minAmountOut:
description: >-
Minimum amount out in wei. If specified, `slippage` should not be
specified
default: null
type: array
items:
type: string
slippage:
type: string
description: >-
Slippage in basis points (1/10000), e.g. 50 = 0.50%. Takes
precedence over minAmountOut argument.
example: '300'
default: '50'
fee:
description: >-
Fee in basis points (1/10000) for each amountIn value. Must be in
range 1-100. By default the fee is collected from amountIn on the
source chain. When destinationFeeReceiver is selected for
destination execution, it is collected from the delivered bridge
asset instead.
example:
- '100'
type: array
items:
type: string
feeReceiver:
type: string
description: >-
The Ethereum address that receives the source-chain fee and remains
the fallback when destination collection does not apply. Required if
fee is provided.
example: '0x220866B1A2219f40e72f5c628B65D54268cA3A9D'
destinationFeeReceiver:
type: string
description: >-
Optional destination-chain fee receiver. For a cross-chain route
with destination execution, the requested fee is collected
atomically from the delivered bridge asset on the destination chain.
Otherwise feeReceiver remains the source-chain receiver.
example: '0x220866B1A2219f40e72f5c628B65D54268cA3A9D'
ignoreAggregators:
description: A list of swap aggregators to be ignored from consideration
nullable: true
type: array
items:
type: string
ignoreStandards:
description: A list of standards to be ignored from consideration
nullable: true
type: array
items:
type: string
ignoreBridges:
description: >-
A list of bridges to be ignored from consideration for crosschain
routes. Supported values: `relay`, `stargate`, `ccip`, `cctp`
nullable: true
type: array
items:
type: string
variableEstimates:
type: object
default: null
referralCode:
type: string
description: Referral code that will be included in an on-chain event.
maxLength: 16
pattern: ^.{0,16}$
destinationChainId:
type: number
description: Chain ID of the network to bridge to and receive tokenOut
crosschainRouteMode:
type: string
description: >-
Controls cross-chain route complexity. direct uses only a bridge,
source allows routing before the bridge, destination allows routing
after the bridge, sourceOrDestination allows routing on either chain
but not both, and full allows routing on both chains
default: full
enum:
- direct
- source
- destination
- sourceOrDestination
- full
refundReceiver:
type: string
description: >-
Ethereum address of the receiver of any dust tokens that might be
produced during the execution of actions
example: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045'
required:
- fromAddress
- amountIn
- tokenIn
- tokenOut
- variableEstimates
RouteShortcutTransaction:
type: object
properties:
gas:
type: string
amountOut:
type: string
priceImpact:
type: number
nullable: true
description: Price impact in basis points, null if USD price not found
feeAmount:
description: An array of the fee amount collected for each tokenIn
type: array
items:
type: string
minAmountOut:
type: string
description: The minimum allowable amount out after slippage
createdAt:
type: number
description: Block number the transaction was created on
tx:
description: The tx object to use in `ethers`
allOf:
- $ref: '#/components/schemas/Transaction'
route:
description: The route the shortcut will use
type: array
items:
$ref: '#/components/schemas/Hop'
ensoFeeAmount:
type: array
items:
type: string
metadata:
$ref: '#/components/schemas/ShortcutResponseMetadata'
transactionCost:
type: string
nullable: true
description: >-
Point-in-time lower-bound estimate of mandatory source-chain
transaction fees in the native token smallest unit. Excludes
priority fees, transaction value, bridge fees, and destination
execution.
transactionCostUsd:
type: string
nullable: true
description: >-
Decimal string USD value of transactionCost. Null when the
native-token price or source-chain fee estimate is unavailable.
preTransactions:
description: >-
Transactions that may need to be executed before the main shortcut
transaction. Token approvals should be skipped when the current
allowance is already sufficient.
type: array
items:
$ref: '#/components/schemas/PreTransaction'
required:
- gas
- amountOut
- priceImpact
- feeAmount
- minAmountOut
- createdAt
- tx
- route
- ensoFeeAmount
- metadata
Transaction:
type: object
properties:
data:
type: string
to:
type: string
from:
type: string
value:
type: string
required:
- data
- to
- from
- value
Hop:
type: object
properties:
tokenIn:
type: array
items:
type: string
tokenOut:
type: array
items:
type: string
protocol:
type: string
action:
type: string
enum:
- approve
- borrow
- borrowwithpositionid
- bridge
- deposit
- singledeposit
- singledepositwithpositionid
- multideposit
- tokenizedsingledeposit
- tokenizedmultideposit
- multioutsingledeposit
- depositclmm
- harvest
- permittransferfrom
- redeem
- singleredeem
- singleredeemwithpositionid
- multiredeem
- tokenizedsingleredeem
- tokenizedmultiredeem
- redeemclmm
- repay
- repaywithpositionid
- swap
- transfer
- transferfrom
- route
- call
- split
- merge
- balance
- minamountout
- slippage
- fee
- ensofee
- paymasterfee
primary:
type: string
internalRoutes:
type: array
items:
type: string
args:
type: object
chainId:
type: number
sourceChainId:
type: number
destinationChainId:
type: number
estimatedAmountOut:
description: >-
Only available for split actions returned by the pathfinder routing
engine. Display estimates use the planned split input, are ordered
to match tokenOut, and are not execution guarantees
type: array
items:
type: string
required:
- tokenOut
- protocol
- internalRoutes
- action
- args
- tokenIn
- primary
ShortcutResponseMetadata:
type: object
properties:
bridgeRefundAssets:
type: array
description: >-
Protocol-specific refund destinations for bridge principal in the
returned transaction. An entry does not guarantee that every bridge
failure is refundable.
items:
$ref: '#/components/schemas/BridgeRefundAsset'
bridgeFees:
description: Bridge protocol and intent execution fees
type: array
items:
$ref: '#/components/schemas/BridgeFee'
bridgeFeeUsd:
type: string
description: >-
USD sum of the reported bridge protocol and intent execution fee
amounts when includeTransactionCost=true. May include maximum fee
reserves. Null when any non-zero fee cannot be priced.
nullable: true
required:
- bridgeRefundAssets
PreTransaction:
type: object
properties:
type:
type: string
enum:
- tokenApproval
- requiredApproval
tx:
description: Transaction to execute before the main shortcut transaction
allOf:
- $ref: '#/components/schemas/Transaction'
token:
type: string
description: Token whose allowance is being set
spender:
type: string
description: Account receiving the token allowance
amount:
type: string
description: Total allowance required by the shortcut
description:
type: string
description: Human-readable explanation for a required approval
required:
- type
- tx
BridgeRefundAsset:
type: object
properties:
protocol:
type: string
enum:
- cctp
- stargate
- ccip
- relay
chainId:
type: number
token:
type: string
description: Address of the bridge principal token that may be refunded
example: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
recipient:
type: string
description: Address that would receive the bridge principal refund
example: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045'
symbol:
type: string
description: Token symbol when metadata is available
example: USDC
required:
- protocol
- chainId
- token
- recipient
BridgeFee:
type: object
properties:
protocol:
type: string
description: Bridge protocol associated with the fee
component:
type: string
enum:
- bridge
- intentExecution
chainId:
type: number
description: Chain on which the fee is paid
destinationChainId:
type: number
description: Destination chain of the bridge action
token:
type: string
description: Token used to pay the bridge fee
type:
type: string
enum:
- maximum
- quoted
description: >-
Whether amount is a maximum reserved for execution or a quote-time
fee breakdown
deductedFromAmountOut:
type: boolean
description: Whether the fee has already reduced the candidate amountOut
amount:
type: string
description: Bridge fee in the token base unit
amountUsd:
type: string
description: >-
Bridge fee in USD when includeTransactionCost=true and pricing is
available
nullable: true
required:
- protocol
- chainId
- destinationChainId
- token
- type
- deductedFromAmountOut
- amount
````