RoutePlan schema

The routePlan object is returned on every successful /quote and /execute call. It’s the canonical description of what the swap will do, broken down by route and leg. You don’t need to construct a RoutePlan yourself. The API generates it; this page is for callers who want to display its contents in detail or audit a swap before signing.

Top-level shape

{
  "chainId": 8453,
  "tokenIn": "0x...",
  "tokenOut": "0x...",
  "amountIn": "1000000000",
  "expectedAmountOut": "484446072048780734",
  "minAmountOut": "479601611328292926",
  "slippageBps": 100,
  "feeBps": 30,
  "blockNumber": 44266656,
  "gasEstimate": { "gasUnits": 300000, "gasCostWei": "..." },
  "feeBreakdown": {
    "protocolFeeAmount": "...",
    "integratorFeeAmount": "..."
  },
  "routes": [ /* SplitRoute[] */ ],
  "metadata": { /* RouteMetadata */ },
  "nativeIn": false,
  "nativeOut": false
}

Field	Type	Description
`chainId`	integer	EVM chain ID. `8453` for Base.
`tokenIn`	address	Echo of the request `tokenIn`.
`tokenOut`	address	Echo of the request `tokenOut`.
`amountIn`	string	Echo of the request `amountIn`, in wei.
`expectedAmountOut`	string	The output amount the optimizer believes you’ll receive, in wei.
`minAmountOut`	string	The on-chain enforced minimum after slippage.
`slippageBps`	integer	Slippage tolerance in bps. Same value as the request.
`feeBps`	integer	Total fee in bps (protocol + optional integrator).
`blockNumber`	integer	Block at which the routing engine snapshotted pool state.
`gasEstimate`	object	Estimated gas usage. See gasEstimate.
`feeBreakdown`	object	Fee split between protocol and integrator. See feeBreakdown.
`routes`	array	One or more `SplitRoute` objects. See Routes.
`metadata`	object	Optimizer telemetry. See metadata.
`nativeIn`	boolean	`true` when the request used the native sentinel for `tokenIn`. The submit handler must set `useNativeIn: true` accordingly.
`nativeOut`	boolean	`true` when the request used the native sentinel for `tokenOut`. Mirrors of `nativeIn`.

`gasEstimate`

{ "gasUnits": 300000, "gasCostWei": "12000000000000000" }

Field	Type	Description
`gasUnits`	integer	Estimated gas units the swap will consume.
`gasCostWei`	string	(Optional) Estimated gas cost in wei at the snapshotted base fee. Display only; the transaction is priced by the user’s wallet, not this number.

`feeBreakdown`

{
  "protocolFeeAmount": "1457804507741243911",
  "integratorFeeAmount": "0"
}

Field	Type	Description
`protocolFeeAmount`	string	Protocol fee taken out of `expectedAmountOut`, in `tokenOut` base units.
`integratorFeeAmount`	string	Integrator fee (when you set `feeBps` on the request), in `tokenOut` base units.

Routes

routes[] is an array of SplitRoute. Each route is one path through the venue graph. When the optimizer splits a trade, you’ll see multiple entries with the input divided across them.

{
  "amountIn": "600000000",
  "legs": [ /* RouteLeg[] */ ]
}

Field	Type	Description
`amountIn`	string	Portion of the total `amountIn` allocated to this route.
`legs`	array	1 to 3 hops. Each `leg` swaps one pair on a specific venue.

`RouteLeg`

{
  "dex": "UNIV3",
  "tokenIn": "0x...",
  "tokenOut": "0x...",
  "amountIn": "600000000",
  "minOut": "0",
  "poolId": "0xd0b5...f224",
  "data": { "kind": "v3_direct", "pool": "0xd0b5...f224" }
}

Field	Type	Description
`dex`	`DexId`	Which venue the adapter dispatches to. See Supported DEXes.
`tokenIn`	address	Input token for this leg.
`tokenOut`	address	Output token for this leg.
`amountIn`	string	Input amount to this leg, in wei.
`minOut`	string	Minimum output for this leg in isolation. May be `0` because the global `minAmountOut` is the binding check.
`poolId`	string	A human-friendly identifier for the pool, when applicable.
`data`	object	Tagged union with `kind` discriminator. Shape varies per venue. See below.

`data` shapes (by `kind`)

The data object is a tagged union keyed by kind. The router’s adapter for each venue knows how to consume the corresponding shape.

`kind`	Carries	Used for
`v2_direct`	`pool`, `feeBps`	Single Uni V2 / Aerodrome V2-like / PancakeSwap V2 pool
`v3_direct`	`pool`	Single Uni V3 pool
`pancake_v3_direct`	`pool`	Single PancakeSwap V3 pool
`algebra_direct`	`pool`	Algebra family pool (Hydrex, QuickSwap V4)
`hydrex`	`deadline`	Hydrex multi-hop
`univ4`	`commands`, `inputs`, `deadline`	Uniswap V4 universal-router payload
`curve`	`pool`, `i`, `j`	Curve TwoCrypto-NG (or compatible)
`prop_amm`	`router`, `protocol`	Proprietary AMMs (PropSwap, Tessera, Elfomofi, LunarBase, Feltir)
`dodo_v2`	`pool`, `baseToken`	DODO V2
`woofi`	`router`	WooFi
`univ2`	`path`, `deadline`	Multi-hop V2 fallback
`univ3`	`path`, `deadline`	Multi-hop V3 path-encoded fallback
`aerodrome_v2`	`routes`, `deadline`	Aerodrome multi-hop with stable/volatile flags

These details exist mainly for debugging and auditing. Application code rarely needs to inspect them.

`metadata`

Optimizer telemetry. Useful for displaying a “tried N paths, picked M” indicator in dev tools or analytics.

{
  "candidatePaths": 16,
  "selectedPaths": 1,
  "connectorsConsidered": [
    "0xcbb7...3bf",
    "0x9401...631"
  ],
  "candidates": [ /* RouteCandidateMetadata[] */ ]
}

Field	Type	Description
`candidatePaths`	integer	Number of token paths the optimizer considered.
`selectedPaths`	integer	How many of those are in the final plan.
`connectorsConsidered`	array of address	Intermediate tokens the optimizer hopped through.
`candidates`	array	(Optional) Per-candidate scoring detail. Useful for debugging “why did it pick that route?”

In production UIs, the only fields most apps need from routePlan are expectedAmountOut, minAmountOut, feeBps, gasEstimate.gasUnits, and the list of dex names from routes[].legs[]. Treat the rest as advanced.

Overview

Getting Started

Features

API

Native Token: $O

Community

Top-level shape

`gasEstimate`

`feeBreakdown`

Routes

`RouteLeg`

`data` shapes (by `kind`)

`metadata`

​Top-level shape

​gasEstimate

​feeBreakdown

​Routes

​RouteLeg

​data shapes (by kind)

​metadata

Top-level shape

`gasEstimate`

`feeBreakdown`

Routes

`RouteLeg`

`data` shapes (by `kind`)

`metadata`