Uniswap Routing API: Trade Simulation & Dry-Run Failures

introduction

QUOTE SIMULATION FAILURES

Introduction

How the Uniswap Routing API simulates trades, why dry-runs fail, and how integrators must handle null responses to avoid broken user experiences.

The Uniswap Routing API provides a critical service for programmatic consumers: it returns a fully formed transaction payload that, when submitted on-chain, should execute a swap. To generate this payload, the API performs an on-chain simulation—a dry-run—of the constructed route. This simulation is the final gate before a quote is returned to the caller. If the simulation fails, the API returns a null or error response, and no executable calldata is provided. For any UI, bot, or aggregator that depends on this API, an unhandled simulation failure is not a minor error; it is a hard break in the swap flow that directly degrades the end-user experience.

Simulation failures are deterministic and stem from a finite set of on-chain state conflicts. The most common causes include the swap exceeding the user's specified slippage tolerance, insufficient pool liquidity to satisfy the quoted amount, and incompatibility with fee-on-transfer tokens where the received amount is less than the input amount specified in the swap. The simulation also reverts if the Permit2 authorization is insufficient, if a token's transfer is paused, or if a hook in a V4 pool reverts during the beforeSwap or afterSwap callbacks. Each failure mode represents a divergence between the static off-chain view of the pool state and the dynamic on-chain reality at the moment of simulation.

For integrators, the operational requirement is unambiguous: every code path that calls the Routing API must implement a graceful degradation strategy for null or error responses. This strategy should include retry logic with backoff, fallback to alternative quoting sources, and clear user-facing messaging that explains the failure without exposing raw revert reasons. Teams that treat the Routing API as a reliable, always-successful endpoint will inevitably ship a broken swap interface. Chainscore Labs can assess an integration's error-handling robustness, review simulation-failure recovery flows, and ensure that quote-consumption logic does not silently fail when the API returns no executable route.

ROUTING API TRADE SIMULATION AND DRY-RUN FAILURES

Quick Facts

Operational facts about how the Uniswap Routing API simulates trades, common failure modes, and the integration impact of unhandled simulation errors.

Field	Value	Why it matters
Simulation mechanism	The API performs an on-chain dry-run (eth_call) against the proposed swap path before returning a quote.	A failed simulation results in a null quote response, directly breaking any UI or bot that does not handle this case gracefully.
Primary failure trigger	Insufficient output amount due to slippage, low liquidity, or the trade exceeding pool price impact thresholds.	Integrators must distinguish between a routable trade and a simulation failure to avoid displaying broken quotes or preventing valid swaps.
Fee-on-transfer token risk	Tokens that deduct a fee on transfer cause the final received amount to be less than the swap output, reverting the simulation.	Wallets and aggregators must detect fee-on-transfer tokens and either exclude them from routing or adjust expected output amounts to prevent consistent failures.
Affected consumers	Any system programmatically consuming the /quote endpoint: trading bots, aggregators, wallet swap flows, and DeFi frontends.	An unhandled null response can crash a trading bot, freeze a wallet's swap UI, or cause an aggregator to drop a profitable route.
Error response handling	The API returns an error code or a null quote; it does not return a fallback route.	Integrators are solely responsible for implementing fallback logic, such as retrying with higher slippage, splitting the route, or querying an alternative solver.
Slippage tolerance interaction	A simulation can fail if the on-chain price moves beyond the slippage tolerance set in the quote request between the time of the quote and the simulation.	Bots and UIs must implement retry logic with updated slippage parameters, especially during high volatility, to prevent a cascade of quote failures.
Gas estimation dependency	The simulation includes gas estimation; a failure can also be caused by a flawed gas strategy or insufficient ETH to cover the transaction cost.	Integrators using custom gas strategies must validate that their parameters do not cause simulation reverts, which are indistinguishable from liquidity failures without detailed error parsing.
Operational monitoring need	Integrators should monitor the ratio of successful to failed quote requests from their own systems.	A sudden increase in simulation failures can indicate a broken integration, a deprecated API version, or a market-wide liquidity event requiring immediate operational intervention.

technical-context

QUOTE VALIDATION LIFECYCLE

How Trade Simulation Works

The Routing API simulates a swap against on-chain state before returning a quote, and integrators must handle simulation failures gracefully.

The Uniswap Routing API does not return static price estimates. When a consumer requests a quote via the /quote endpoint, the API performs an on-chain simulation of the proposed swap using a eth_call (or equivalent for the target chain). This simulation executes the entire multi-hop route, including any Permit2 transfers and Universal Router commands, against the current block state. The result is a quote that reflects real-time liquidity, pool fees, and gas costs, not a theoretical price derived from pool reserves alone. The methodParameters field in the response contains the fully-encoded calldata that, if submitted, will produce the simulated outcome—assuming no state change occurs between simulation and execution.

Simulation failures are a normal and expected part of the quote lifecycle. The API returns a null quote or an error object when the simulation reverts. Common causes include: the swap exceeding the configured slippage tolerance, insufficient liquidity in one or more pools along the route, fee-on-transfer tokens where the received amount is less than the simulated input, and tokens with transfer hooks that modify state in ways the router does not expect. The API also simulates with the user's configured deadline and recipient; a deadline that is too short can cause the simulation to revert if the block timestamp advances during processing. Integrators must treat a null response as a normal operational state, not an API outage.

The operational burden falls on the consuming application to degrade gracefully. A UI that receives a failed simulation should not display a stale quote, retry silently without user feedback, or fall back to a less accurate pricing mechanism without indicating the change. Bots and solvers consuming the API programmatically must implement retry logic with backoff, distinguish between transient failures (liquidity shifts, block advancement) and persistent failures (unsupported token, paused pool), and avoid submitting transactions when the simulation has already indicated a revert. Chainscore can assess an integration's error-handling robustness, verify that retry and fallback logic does not mask systemic routing failures, and review calldata consumption patterns to ensure that methodParameters blobs are used atomically and not decomposed in ways that invalidate the simulated execution path.

IMPACT ANALYSIS

Affected Systems and Integrators

Wallets & Frontends

Any interface that displays a quote before prompting a user to sign a transaction is directly affected. A simulation failure that returns a null or error response must be handled gracefully; presenting a broken quote or a frozen UI creates immediate user confusion and erodes trust.

Action Items:

Implement a fallback UI state for failed simulations (e.g., "No quote available for this pair").
Log the specific error code from the Routing API to distinguish between transient failures (slippage) and permanent failures (unsupported token).
Do not cache failed quotes as valid. Ensure the retry logic is user-triggered or time-bound, not an infinite loop.
Verify that Permit2 signature requests are not generated for a trade that has already failed simulation.

implementation-impact

SIMULATION FAILURE ANALYSIS

Common Failure Modes and Causes

Trade simulation failures in the Uniswap Routing API are deterministic and stem from a specific set of on-chain state mismatches. Integrators must handle these failures gracefully to avoid broken user experiences.

Insufficient Pool Liquidity

The most common failure occurs when the requested trade size exceeds available pool depth at the time of simulation. The API's quoteGasAndData simulation reverts because the amountOut falls below the amountOutMinimum set by the user's slippage tolerance. This is not an API bug but a real-time liquidity constraint. Integrators should catch these failures and prompt users to reduce trade size or increase slippage tolerance rather than displaying a generic error.

Fee-On-Transfer Token Incompatibility

Tokens that deduct a fee on transfer (e.g., some rebasing or deflationary tokens) cause a mismatch between the simulated amountIn and the actual amount received by the pool. The simulation uses the full input amount, but the pool receives less, causing the swap to fail the invariant check. The Uniswap Router explicitly reverts on these tokens. Integrators must pre-screen token contracts for fee-on-transfer mechanics before submitting quotes or handle the specific revert reason to inform users that the token is unsupported.

Stale Quotation and Front-Run Reverts

A quote is a point-in-time estimate. Between quotation and transaction submission, other transactions can shift the pool's price, causing the user's transaction to fail its slippage check. This is a classic front-running or sandwich-attack symptom. The API simulation succeeds, but the subsequent on-chain execution reverts. Integrators must implement quote refresh logic and set transaction deadlines to minimize the window of vulnerability. Monitoring for high-failure-rate token pairs can identify MEV-heavy pools.

Permit2 Nonce and Allowance Conflicts

When using Permit2-based flows, a simulation can fail if the user's Permit2 nonce has been advanced by a concurrent transaction or if the permit's allowed amount is insufficient to cover the swap plus gas. The simulation assumes the permit is valid at execution time. Integrators must handle Permit2-specific revert reasons (e.g., InvalidNonce, AllowanceExpired) distinctly from standard swap failures and guide users to re-sign a new permit with an updated nonce and deadline.

Unsupported Token Pair Pathing

The Auto Router may fail to find a viable path for exotic token pairs that lack a direct or multi-hop route through whitelisted pools. This is common for newly launched tokens or those with insufficient liquidity across V2, V3, or V4 pools. The API returns a NoRouteFound error. Integrators should catch this specific error code and provide a clear message that the pair is not currently routable, rather than falling through to a generic 'Quote Unavailable' state that confuses users.

Gas Estimation Failure in Simulation

The quoteGasAndData endpoint simulates the swap to estimate gas costs. If the simulation reverts due to a custom hook logic failure in V4 pools or an unexpected state change in a dependent contract, the gas estimate cannot be generated and the entire quote fails. This is distinct from a swap failure. Integrators should differentiate between a swap-path failure and a gas-estimation failure in their error handling, as the latter may indicate a transient chain state or a bug in a pool's hook contract that requires developer investigation.

ROUTING API TRADE SIMULATION AND DRY-RUN FAILURES

Integration Risk Matrix

Assesses the operational impact of trade simulation failures in the Uniswap Routing API on different integrator types and their downstream users.

Area	What changes	Who is affected	Action
Quote Response Handling	The API returns a null or error object when the dry-run simulation fails, instead of a valid quote with methodParameters.	Wallets, trading bots, and frontends that programmatically consume the Routing API.	Implement explicit null-check and error-handling logic. Do not proceed to construct or submit a transaction from a failed quote response.
Slippage Configuration	Simulation fails if the configured slippage tolerance is too low for the current pool state, causing the dry-run to exceed the minimum amount out.	UIs and aggregators that set default or user-defined slippage parameters.	Review default slippage settings. Implement dynamic slippage estimation or provide clear user feedback when a quote fails due to slippage constraints.
Fee-on-Transfer Tokens	Tokens that deduct a fee on transfer cause a mismatch between the quoted input amount and the amount actually received by the pool, leading to simulation reversion.	Integrators supporting a wide range of ERC-20 tokens, including rebasing or fee-on-transfer variants.	Maintain a dynamic list of known fee-on-transfer tokens. Pre-check token behavior before requesting a quote or gracefully handle the specific simulation failure.
Insufficient Liquidity	A quote may be generated but the subsequent simulation fails because the available liquidity depth at the required tick is insufficient to fill the order without exceeding price impact limits.	Aggregators and large traders splitting orders across multiple venues.	Monitor quote success rates per token pair. For large orders, compare Uniswap quotes against alternative routing sources and implement fallback logic.
Gas Estimation Logic	The simulation includes a gas check that can fail if the transaction's estimated gas cost exceeds the user's specified maximum or if the gas price is too volatile.	Bots and interfaces that submit transactions immediately upon receiving a quote.	Set realistic gas limits and priority fees. Implement retry logic with updated gas parameters if a quote fails specifically due to the gas estimation check.
Contract State Staleness	A quote based on a pool's state at block N may fail simulation at block N+1 if a competing transaction alters the price or liquidity before the dry-run executes.	High-frequency trading bots and MEV-aware systems.	Minimize the time between receiving a quote and submitting the transaction. Implement logic to refresh the quote if the initial simulation fails due to a state change.
User Experience Degradation	Unhandled simulation failures result in a broken UI state, a generic 'transaction failed' message, or an infinite loading spinner for the end user.	All frontend applications integrating the Uniswap swap flow.	Design the UI to gracefully surface specific failure reasons (e.g., 'Price moved, please try again') and offer clear next steps instead of a hard failure.

ROUTING API TRADE SIMULATION AND DRY-RUN FAILURES

Error-Handling Implementation Checklist

A systematic checklist for integrators to ensure their systems gracefully handle Routing API simulation failures. Unhandled null or error responses from the quote endpoint create broken user experiences, stuck loading states, and silent transaction failures. Each item below identifies a specific failure mode, explains why it matters, and provides the signal or artifact that confirms your integration handles it correctly.

What to check: Does your integration explicitly handle HTTP 404 responses or null quote objects from the Routing API without crashing or entering an infinite loading state?

Why it matters: The API returns 404 when no route exists between the token pair, when liquidity is insufficient for the requested amount, or when the token pair is unsupported. Integrations that treat this as an unhandled exception will display broken UI states, spinner loops, or uncaught promise rejections.

Readiness signal: Your integration renders a specific "No route available" or "Trade not executable" message to the user when receiving a 404 or null response. Your error boundary catches this state and prevents the UI from hanging. Logging confirms that 404 responses are classified as expected operational states, not critical errors.

resource-links

UNISWAP ROUTING API

Source Resources

Canonical and implementation-level resources for teams diagnosing Uniswap Routing API quote, simulation, and dry-run failures. Use these sources to verify request schemas, calldata assumptions, router behavior, approval flows, and chain-state simulation methods.

Uniswap Trading API Documentation

Use the Uniswap Labs API documentation as the first source for current quote and swap request fields, response schemas, authentication requirements, and error behavior. For routing simulation failures, verify that your integration is sending the expected token addresses, chain ID, trade type, amount format, slippage settings, recipient fields, and routing preferences. Teams should avoid hard-coding assumptions from older examples; quote APIs and routing preferences can change faster than immutable protocol contracts.

EXPLORE

Smart Order Router Repository

The Uniswap smart-order-router repository is useful for understanding routing logic, path selection, pool discovery, route splitting, and quote construction assumptions. Integrators building fallback routing, local quote comparison, or monitoring for API degradation should inspect this implementation rather than treating the API response as an opaque price feed. It can also help distinguish between route-unavailable conditions, insufficient liquidity, and failures caused by execution-layer constraints such as token behavior or calldata construction.

EXPLORE

Universal Router Documentation

Routing API quote responses may include calldata intended for the Universal Router. When a dry-run fails, decode the returned method parameters and compare the command sequence against the Universal Router documentation. This helps isolate whether the failure is caused by route selection, token transfer behavior, Permit2 authorization, slippage limits, deadline handling, or an unsupported command path. Wallets and bots that submit API-generated calldata should monitor router reverts separately from quote-null responses.

EXPLORE

Permit2 Documentation

Many simulated swap failures are approval-path failures rather than routing failures. Permit2 introduces time-bound and nonce-scoped token permissions, but dry-runs can revert when the user has not approved Permit2, the signature domain is wrong, the nonce has been consumed, the allowance has expired, or the spender does not match the router path. Integrators should validate Permit2 state before showing a quote as executable and separate approval remediation from price or liquidity errors in user-facing messaging.

EXPLORE

Ethereum JSON-RPC eth_call Reference

Dry-run execution usually depends on RPC simulation behavior, commonly via eth_call against recent chain state. Use the Ethereum JSON-RPC reference to verify how your provider handles call parameters, block tags, revert data, gas limits, and state-dependent execution. Quote success at the API layer does not guarantee transaction success if the local simulation uses stale state, a different block, a different sender, missing approval state, or chain-specific RPC behavior on L2 networks.

EXPLORE

Universal Router Source Repository

When revert reasons are unclear, compare decoded calldata against the Universal Router source and tests. The repository is the practical reference for command execution order, balance checks, partial-fill behavior, recipient handling, and interaction with Permit2 and Uniswap pool versions. Security and reliability teams should use it to build regression tests around known failure classes: fee-on-transfer tokens, insufficient output amount, expired deadlines, missing approvals, and token contracts with non-standard transfer behavior.

EXPLORE

Chains We Build On

Looking to build on a specific blockchain?

We build smart contracts, DeFi applications, wallets, tokenization platforms, and blockchain infrastructure across the major ecosystems teams choose today. That includes Ethereum, Arbitrum, Optimism, Polygon, Avalanche, Solana, Sui, Aptos, Hedera, Stellar, and NEAR, with support for additional EVM and non-EVM networks based on your product requirements.

Learn More

EVM ecosystems

Ethereum
Arbitrum
Optimism
Polygon
Avalanche
Cronos

Non-EVM ecosystems

Solana
Sui
Aptos
Hedera
Stellar
NEAR

Additional ecosystems

Polkadot
Cosmos
TON
Cardano
Algorand
Tempo

Also available for Base, appchains, custom EVM networks, and cross-chain product architecture.

ROUTING API DRY-RUN DIAGNOSTICS

Frequently Asked Questions

Common failure modes when simulating trades through the Uniswap Routing API and how integrators should interpret and handle error responses.

The Routing API performs a dry-run simulation against the current on-chain state before returning a firm quote. A null response or simulation failure typically indicates one of the following conditions:

Insufficient liquidity: The requested trade size exceeds available depth across all candidate pools at the current block.
Slippage exceeded: The simulated execution price falls outside the maxSlippage or slippageTolerance parameter specified in the request.
Fee-on-transfer tokens: Tokens that deduct a fee on transfer cause the actual received amount to differ from the expected output, breaking the simulation's balance checks.
Rebasing tokens: Supply changes between quote time and simulation can invalidate the expected outcome.
Paused or killed pools: If the router's candidate set includes a pool that has been paused or killed, the simulation will revert.
Gas constraints: The gasStrategies or gasLimit parameters may be too restrictive for the optimal route.

Integrators should never silently swallow a null response. The user must be informed that a quote could not be produced, and the UI should offer actionable alternatives such as reducing trade size or adjusting slippage.

Trusted by Industry Leaders

Delivering blockchain solutions for 5+ years.

We have partnered with 50+ leading DeFi protocols, NFT ecosystems, and fintech innovators to build secure, scalable, and capital-efficient blockchain products.

Selected Partners & Clients

“I've been working with Chainscore Labs for last 3+ years, they've consistently delivered with strong ownership across multiple projects. The team is reliable and detail-oriented.”

Lee Erswell

CEO, Telos Foundation

how to get started

How to get started?

If you're looking for blockchain integration, ChainScore Labs has 5+ years of experience helping teams build and integrate exchanges, wallets, smart contracts, tokenization solutions, and protocol-connected products, we can help you choose the right path, integrate securely, and get to production faster. Our team consists of experienced blockchain developers and architects who can help you with your blockchain integration needs.

Exploration & Strategy

Define your product goals and choose the right blockchain architecture for your use case.

Architecture & Design

Design the smart contracts, tokenomics, and security parameters of your system.

Development & Integration

Build and integrate with wallets, oracles, and front-end dApps for a seamless experience.

Security & Launch

Comprehensive audits followed by a risk-managed mainnet deployment to protect your users.

Learn More

Explore More Solutions

Discover our
blockchain development services.

We build production-grade blockchain solutions for top-tier projects across DeFi and Web3.

Book a Call

DeFi Protocol Development

End-to-end development of custom DeFi protocols including core smart contracts and system architecture.

DEX & Exchange Development

Building high-performance decentralized exchanges with optimized liquidity and advanced trading logic.

Lending & Borrowing Platforms

Scalable credit markets and money protocols built for production-grade liquidity and security.

Routing API Trade Simulation and Dry-Run Failures

Introduction

Quick Facts

How Trade Simulation Works

Affected Systems and Integrators

Wallets & Frontends