Swapping and Adding Liquidity
This guide will cover how to execute a swap-and-add operation in a single atomic transaction. It is based on the swap-and-add example, found in the Uniswap code examples repository. To run this example, check out the examples's README and follow the setup instructions.
If you need a briefer on the SDK and to learn more about how these guides connect to the examples repository, please visit our background page!
When adding liquidity to a Uniswap v3 pool, you must provide two assets in a particular ratio. In many cases, your contract or the user's wallet hold a different ratio of those two assets. In order to deposit 100% of your assets, you must first swap your assets to the optimal ratio and then add liquidity.
However, the swap may shift the balance of the pool and thus change the optimal ratio. To avoid that, we can execute this swap-and-add liquidity operation in an atomic fashion, using a router. The inputs to our guide are the two tokens that we are pooling for, the amount of each token we are pooling for, the amount of each token to swap-and-add, and the Pool fee.
The guide will cover:
- Setup a router instance
- Configuring our ratio calculation
- Calculating our currency ratio
- Constructing and executing our swap-and-add transaction
At the end of the guide, given the inputs above, we should be able swap-and-add liquidity using 100% of the input assets with the press of a button and see the change reflected in our position and the balance of our tokens.
For this guide, the following Uniswap packages are used:
The core code of this guide can be found in
This guide assumes you are familiar with our Minting a Position guide. A minted position is required to add or remove liquidity from, so the buttons will be disabled until a position is minted.
Also note that we do not need to give approval to the
NonfungiblePositionManager to transfer our tokens as we will have already done that when minting our position.
Setup a router instance
The first step is to approve the
SwapRouter smart contract to spend our tokens for us in order for us to add liquidity to our position:
The we can setup our router, the
AlphaRouter, which is part of the smart-order-router package. The router requires a
chainId and a
provider to be initialized. Note that routing is not supported for local forks, so we will use a mainnet provider even when swapping on a local fork:
For a more detailed example, check out our routing guide.
Configuring our ratio calculation
Having created the router, we now need to construct the parameters required to make a call to its
routeToRatio function, which will ensure the ratio of currency used matches the pool's required ratio to add our total liquidity. This will require the following parameters:
The first two parameters are the currency amounts we use as input to the
Next, we will create a placeholder position with a liquidity of
1 since liquidity is still unknown and will be set inside the call to
We then need to create an instance of
SwapAndAddConfig which will set additional configuration parameters for the
ratioErrorTolerancedetermines the margin of error the resulting ratio can have from the optimal ratio.
maxIterationsdetermines the maximum times the algorithm will iterate to find a ratio within error tolerance. If max iterations is exceeded, an error is returned. The benefit of running the algorithm more times is that we have more chances to find a route, but more iterations will longer to execute. We've used a default of 6 in our example.
Finally, we will create an instance of
SwapAndAddOptions to configure which position we are adding liquidity to and our defined swapping parameters in two different objects:
recipientof leftover dust from swap,
deadlinefor the swap.
addLiquidityOptionsmust contain a
tokenIdto add to an existing position
Calculating our currency ratio
Having constructed all the parameters we need to call
routeToRatio, we can now make the call to the function:
The return type of the function call is SwapToRatioResponse. If a route was found successfully, this object will have two fields: the status (success) and the
SwapToRatioRoute object. We check to make sure that both of those conditions hold true before we construct and submit the transaction:
In case a route was not found, we return from the function a
Failed state for the transaction.
Constructing and executing our swap-and-add transaction
After making sure that a route was successfully found, we can now construct and send the transaction. The response (
SwapToRatioRoute) will have the properties we need to construct our transaction object:
If the transaction was successful, our swap-and-add will be completed! We should see our input token balances decrease and our position balance should be increased accordingly.