Quickstart

How to swap on-chain with Tycho. This quickstart will help you:

• Fetch real-time market data from Tycho Indexer.

• Simulate swaps between token pairs. This lets you calculate spot prices and output amounts using Tycho Simulation.

• Encode the best trade for given token pairs.

• Simulate or execute the best trade using Tycho Execution.

Run the Quickstart

Clone the ; here's code.

Run the quickstart with execution using the following commands:

If you don't have an RPC URL, here are some public ones for , , and .

The PRIVATE_KEY environment variable is unnecessary if you want to run the quickstart without simulation or execution.

What it does

The quickstart fetches all protocol states. Then it returns the best amount out (best price) for a given token pair (by default, 10 USDC to WETH).

Additionally, it returns calldata to execute the swap on this pool with the Tycho Router.

You should see an output like this:

If you want to see results for a different token, amount, or chain, or minimum TVL, you can set additional flags:

This example would seek the best swap for 10 USDC -> WETH on Base.

The TVL filter means we will only look for snapshot data for pools with TVL greater than the specified threshold (in ETH). Its default is 1000 ETH to limit the data you pull.

Logs

If you want to see all the Tycho Indexer and Simulation logs, run with RUST_LOG=info:

How the quickstart works

The quickstart shows you how to:

1. Set up and load necessary data, like available tokens.

2. Connect to the Tycho Indexer to fetch on-chain protocol data (e.g., Uniswap V2, Balancer V2) and build a Protocol Stream that streams updates, like new pools and states, in real-time.

3. Simulate swaps on all available pools for a specified pair (e.g., USDC, WETH), and print out the most WETH available for 10 USDC.

4. Encode

1. Set up

Run Tycho Indexer by setting up the following environment variables:

• TYCHO_URL (by default "tycho-beta.propellerheads.xyz")

• TYCHO_API_KEY key

• PRIVATE_KEY if you wish to execute the swap against the Tycho Router

The Indexer stream or the Simulation does not manage tokens; you manage them yourself.

To simplify this, gets all current token information from Tycho Indexer RPC for you.

2. Connect to Tycho Indexer

The protocol stream connects to Tycho Indexer to fetch the real-time state of protocols.

Here, you only subscribe to Uniswap V2 and Balancer V2. To include additional protocols like Uniswap V3, simply add:

For a full list of supported protocols and which simulation state (like UniswapV3State) they use, see .

Note: The protocol stream supplies all protocol states in the first BlockUpdate object. All subsequent BlockUpdates contain only new and changed protocol states (i.e., deltas).

3. Simulate swap

get_best_swap uses Tycho Simulation to simulate swaps and calculate buy amounts. We inspect all protocols updated in the current block (i.e., protocols with balance changes).

a. Simulating token swaps

result is a GetAmountOutResult containing information on amount out, gas cost, and the protocol's new state. So you could follow your current swap with another.

By inspecting each of the amount outs, you can then choose the protocol component with the highest amount out.

4. Encode a swap

After choosing the best swap, you can use Tycho Execution to encode it.

a. Create a solution object

Now you know the best protocol component (i.e., pool), you can compute a minimum amount out. And you can put the swap into the expected input format for your encoder.

The minimum amount out is a very important parameter to set in Tycho Execution. The value acts as a guardrail and protects your funds during execution against MEV. This quickstart accepts a slippage of 0.25% over the simulated amount out.

After this, you can create the Swap and Solution objects. For more info about the Swap and Solution models, see .

b. Encode solution

5. Encode full method calldata

You need to build the full calldata for the router. Tycho handles the swap encoding, but you control the full input to the router method. This quickstart provides helper functions (encode_tycho_router_call and sign_permit)

Use it as follows:

6. Simulate or execute the best swap

This step allows you to test or perform real transactions based on the best available swap options. For this step, you need to pass your wallet's private key in the run command. Handle it securely and never expose it publicly.

When you provide your private key, the quickstart will check your token balances and display them before showing you options:

If you don't have enough tokens for the swap, you'll see a warning:

You'll then encounter the following prompt:

You have three options:

1. Simulate the swap: Tests the swap without executing it on-chain. It simulates an approval (for permit2) and a swap transaction on the node. You'll see something like this:

If status is false, the simulation has failed. You can print the full simulation output for detailed failure information.

1. Execute the swap: Performs the swap on-chain using your real funds. The process performs an approval (for permit2) and a swap transaction. You'll receive transaction hashes and statuses like this:

After a successful execution, the program will exit. If the transaction fails, the program continues to stream new blocks.

1. Skip this swap: Ignores this swap. Then the program resumes listening for blocks.

Recap

In this quickstart, you explored how to use Tycho to:

1. Connect to the Tycho Indexer: Retrieve real-time protocol data filtered by TVL.

2. Fetch Token and Pool Data: Load all token details and process protocol updates.

3. Simulate Token Swaps: Compute the output amount, gas cost, and updated protocol state for a swap.

4. Encode a Swap: Create a solution from the best pool state and retrieve calldata to execute against a Tycho router.

What's next?

• Integrate with your Solver: Add Tycho pool liquidity to your solver, using this .

• Learn more about and the datatypes necessary to encode an execution against a Tycho router or executor.

• Learn more about : Explore custom filters, protocol-specific simulations, and state transitions.