Swapper contract

Swapper coverts incoming payments to the output currency of your choice. When ETH and ERC20s are received by a Swapper, they are automatically swapped into the specified output token according to the oracle's clearing price and the swapper's discount.

In the example above, incoming ERC20s are automatically swapped to ETH before being sent to the beneficiary address. The Oracle is the way Swapper determines the clearing price, and the Caller is the account that initiated the transaction.

Remember#

Keep these in mind whenever interacting with any smart contracts:

1. Interacting with contracts require onchain transactions, and onchain transactions are irreversible.
2. Contracts are entirely your property; we hold no control or special privileges over them.
3. Each contract operates exclusively on the network on which it has been deployed—make sure you're on the right network.

Creating a Swapper#

To create a new contract, first click “New contract” from the navigation. Then select the network on which you want to deploy the contract, and click “Swapper” from the list of contracts. You will now see that you’re creating a new Swapper on the network of your choice.

Output token#

Use the dropdown to select your output token. If you want to choose an option that isn't on the list, you'll need to find the token's contract address and paste it in using the "Enter address" option.

Beneficiary#

The beneficiary is the address that will receive the swapped tokens. Any account capable of receiving a transaction on an EVM blockchain is eligible. This includes other smart contracts. Since fund recipients do not need to withdraw for themselves, the only criteria for a beneficiary is being able to receive ETH and ERC20 tokens.

Owner#

The owner, if designated, has full control over the contract, including the ability to manually swap tokens not supported by the oracle.

Important: Swappers without owners will not be able to recover tokens received that aren't supported by their oracle. Be very careful when using immutable Swappers.

In general, we recommend setting yourself or a trusted party as the owner on a Swapper unless you're using it in a trust-less setting where having an owner limits its usefulness.

Oracle#

The oracle is the source for the price of tokens to be swapped. Make sure that the oracle supports any tokens you expect to receive. Currently the app offers Splits' Uniswap-based oracle, but you can also enter the address for a different one that you want to use, as long as it abides by the expected oracle interface. The oracle interface is NOT a Uniswap pool – read the docs if you’re using a custom oracle.

You may notice the "Advanced settings" dropdown, which allows you to change the incentive that pays for automatic swapping. Do not tinker with this field unless you know what you're doing and have a thought-out plan — mistakes will prevent the Swapper from functioning as intended.

Name#

This is the contract name that will be displayed in the Splits app instead of the contract’s hexadecimal address. This gets stored offchain (therefore you must be signed in to add one), and you can choose to make the name public, available to other Splits users, or keep it private for personal use only.

Using a Swapper#

Once you’ve created a Swapper, you’re now ready to use it. Using Swapper means 1) sending ETH or ERC20 tokens to the Swapper’s address, and 2) releasing the swapped tokens (and possibly withdrawing any unswapped ones).

Sending funds#

Sending ETH and ERC20 tokens to your Swapper is as easy as sending funds to any other account. Just copy the address, which can be found at the top of the contract’s detail page, and send tokens to the address. You can send funds via the app, but most people will use the Swapper address in other platforms and apps (e.g., Zora, Highlight, OpenSea, Manifold, etc).

Swapping and withdrawing#

Swapper is designed with an incentive for third parties to automatically swap and withdraw balances on your behalf. However, if you ever need to swap and withdraw manually, you can do so by navigating to your Swapper contract’s detail page in the app, selecting the balances, and clicking the “Swap” button. You will need to connect your wallet to complete the swap and withdrawal.

Editing a Swapper#

Connect your wallet and then navigate to the Swapper’s detail page. At the top, you’ll see a message that says “You control this Swapper”, and the ability to “Edit Swapper” or “Pause”.

Editing the Swapper lets you change the output token, beneficiary, oracle, and discount incentives as desired.

Pausing the Swapper will prevent non-owners (i.e., any account that is not you/the owner of the Swapper) from being able to interact with the contract. We encourage you to leave this on unless you need to prevent others from interacting with Swapper.

Private RPC#

Swap transactions can revert if they are front-run by bots. Your funds are safe, but the transaction will revert.

You can prevent this from happening by adding a private RPC, such as Flashbots Protect, to your wallet and using it to execute the swap.

To do this, go to Flashbots Protect and click “Connect Wallet to Protect”. Reference Flashbots’ manual instructions if you’re having issues.