Tycho is a community project that helps DEXs and Solvers coordinate.

What you can contribute

A quick overview, there are three ways to contribute to Tycho:

• Pick an issue: Find issues to contribute to in the Tycho issue tracker – or propose an issue for a new feature.

• Build an app: Build an app using Tycho. Use the specifications in Tycho X as an inspiration.

• Win a bounty: Some issues, integrations, or Tycho X projects have bounties sponsored by the community; you can find all bounties here: Bounty Tracker.

How to get started

Whichever way you choose to contribute – Tycho maintainers and the community are here to help you. Before you get started:

1. Join tycho.build – our telegram group for Tycho builders.

2. Reach out to Tanay - so that he can support you and ensure someone else isn't already working on the same project.

In some cases, the community sponsors a bounty.

Specifically for:

• DEX Integrations: Some DEXs can't integrate themselves - and instead sponsor a bounty for the community.

• Orderflow integrations: Tools that want to use Tycho in their router.

• Tycho X Projects: Teams can also sponsor bounties for Tycho X projects.

How bounties work

• Cumulative Bounties: Several parties can sponsor and cumulate a bounty for the same issue.

• Single winner: Bounties are, unless specified otherwise, awarded in full to the first team that satisfies the requirements.

• Core Maintainer Support: Tycho maintainers will support every team working on a bounty. Incl. guidance, PR reviews, and final assessment.

• Award of a Bounty: Each bounty has a board of three assessors, usually the one who specified the bounty, the sponsor of the bounty, and one dev from the Tycho team.

Steps

• Discover a bounty: Find current open bounties in the – Bounty Tracker.

• Reach out: Reach out to Tycho maintainers at tycho.build or dm Tanay if you plan to work on a bounty.

• Submit: Submit your work in a PR and notify maintainers.

• Review & Award: After a successful review by the three assessors, maintainers will merge the PR and payout the bounty. (any merged PR automatically qualifies for the bounty.)

Open Bounties

Find the list of open bounties here: Bounty Tracker

What is Tycho?

Tycho is an open-source interface to on-chain liquidity. Tycho

• Indexes DEX protocol state for you with low latency,

• Simulates swaps extremely fast with one interface for all DEXs, and

• Executes swaps on-chain

Ending the integration nightmare

Integrations are the largest point of friction for both DEXs and Solvers:

• Solvers can't scale integrations. So, Solvers spend much of their time on integrations, and new solvers can't catch up and compete.

• DEXs need to convince solvers to integrate them to get orderflow and win LPs. But Solvers prioritize DEXs with liquidity. This makes it hard for new DEXs to get the flow their design deserves.

In the end, every solver separately integrates every DEX – leading to massive wasted effort from which no one benefits.

Tycho fixes this:

• DEXs can integrate themselves and don't need to wait for solvers, and

• Solvers can use new DEXs without any additional effort.

Tycho lowers barriers to entry so that both innovative DEXs and Solvers have a chance to win flow.

Get started

Solvers – Access more liquidity

Tycho makes it easy to simulate and execute over on-chain liquidity sources – without needing to understand protocol internals, run nodes, or do RPC calls.

To set up, go to the and start your liquidity stream.

DEXs – Get more flow

To integrate your DEX, submit a PR to Tycho Protocol Integrations on .

To get started, check the docs.

Or so we can help you integrate.

Components of Tycho

Tycho has three components for solvers:

• Tycho Indexer: Infrastructure to parse, store and stream protocol state deltas. It also comes with clients in Python and Rust and a hosted webstream if you don't want to run your version of the Indexer. -> .

• Tycho Protocol Simulation: A simulation library with a unified interface to query swaps and prices. Optimized for speed, running on compiled contracts in REVM with in-memory storage. -> .

• Tycho Execution: Audited and gas-efficient router and DEX executor contracts for safe, simple, and competitive execution of swaps.

And one integration SDK for DEXs:

• Tycho Protocol Integration: An SDK for any DEX (or Stable Coin, LRT, etc.) to integrate their liquidity and receive flow from solvers.

FAQ

Tycho exposes data through two mechanisms, the RPC and the stream. The RPC provides you access to static data, like the state of a component at a given block or extended information about the tokens it has found. For streaming data, we recommend using the . This guide documents the RPC interfaces.

Token Information

Tycho stream provides only the token addresses that Protocol Components use. If you require more token information, you can request using 's endpoint. This service allows filtering by both quality and activity.

Quality Token Quality Ratings

The quality rating system helps you quickly assess token's specific properties:

• 100: Normal ERC-20 Token behavior

• 75: Rebasing token

• 50: Fee-on-transfer token

• 10: Token analysis failed at first detection

• 5: Token analysis failed multiple times (after creation)

• 0: Failed to extract attributes, like Decimal or Symbol

API Documentation

This section documents Tycho's RPC API. Full swagger docs are available at:

Tycho is free and open source

Tycho is, and always will be, free software, open source, and MIT licensed.

Free hosted indexer: Today, we host a free indexer for each chain, and we aim to maintain this indefinitely. If this ever changes, you will know at least 3 months ahead of time and have enough time to host your own indexer.

Indexer Redundancy

We are working with independent third parties to host additional indexers, both free and paid – to add redundancy to our indexer.

Tycho's Financial Model

Tycho finances development and maintenance through:

• Grants: Tycho receives grants from chains, DEXs, and others that benefit from the flow that Tycho brings.

• Tools built on Tycho: Useful tooling built on Tycho with a fee model (Coming soon).

Road to Community Ownership

Control over Tycho projects, grant funding, and fees earned will gradually transfer to Tycho users. (in planning).

Tycho indexes on-chain liquidity, with a current focus on token swaps. Future development can include other liquidity provisioning, lending, and derivatives.

The DeFi Fragmentation Challenge

The rapid innovation in DeFi protocols has created a fragmented ecosystem without standardized interfaces for fundamental operations like swaps, liquidity provisioning, etc.

Tycho aims to provide a standardized interface across those operations.

With a focus on fast local simulations on top of the latest known state of the chain and settlements through tycho-execution.

Key Challenges in Liquidity Indexing

Before Tycho, you might face the following issues if you want to settle on onchain protocols:

Technical Complexity

• Rewrite protocol-specific mathematics in your application programming language to simulate fast locally.

• Develop protocol-specific indexing to supply data for local simulations.

• Watch and filter out user-created token pairs with unusual or malicious behavior.

• Navigate an enormous search space of liquidity sources with effective filtering heuristics.

Blockchain-Specific Issues

• Chain reorganizations ("reorgs") that alter transaction history must be handled with care.

• Block propagation delays caused by peer-to-peer network topology and geographic distribution.

• Continuous maintenance of node infrastructure, such as updating client versions (especially during hard forks), updating storage space, etc.

Push-Based Architecture

Problems with Traditional RPC Polling

Traditional indexers rely on node client RPC interfaces, which have significant limitations:

• Data must be requested from nodes, introducing latency and potential for error.

• Multiple requests are often needed to assemble a complete view of the data.

• Complex query contracts may be required for comprehensive data extraction (e.g., to get all Uniswap V3 ticks) whose execution adds additional latency to data retrieval.

• Load-balanced RPC endpoints can expose inconsistent state views during reorgs, making it hard to scale across many node clients.

• May involve maintaining and running multiple instances of modified node clients.

The Streaming Solution

Tycho adopts a fundamentally different approach:

• Data is pushed/streamed as a block is processed by the node client.

• Current implementation leverages Substreams as the primary data source.

• Alternative data sources can be integrated if they provide comparable richness.

• State changes are communicated to clients through streaming interfaces.

User Experience Philosophy

Abstraction by Default

• Non-blockchain-native users shouldn't need to understand chain-specific concepts.

• Reorgs and optimistic state changes remain invisible to users by default.

• Users perceive only that state has changed, regardless of underlying mechanism.

Optional Transparency

• Advanced users can access detailed information about state changes when needed.

• Granular visibility allows inspection of upcoming state changes.

• Applications can track specific liquidity pair changes for specialized use cases.

Tycho Protocol SDK is a library to help you integrate liquidity layer protocols (DEXs, Staking, Lending, etc.) into Tycho.

Integration Process

To integrate with Tycho, you need three components:

1. Indexing: You must provide the protocol state/data needed for simulation and execution.

2. Simulation: You have to implement the protocol's logic for simulations.

3. Execution: You have to define how to encode and execute swaps against your protocol.

We provide a comprehensive testing suite to ensure you can integrate indexing, simulation, and execution correctly. A passing test suite is essential for an integration to be considered complete.

Indexing

You will need a substreams package that emits a specified set of messages. If your protocol already has a substreams package, you can adjust it to emit the required messages.

It's important to note that simulation happens entirely off-chain. This means everything you need during simulation must be explicitly indexed.

Simulation

Tycho offers two integration modes:

• VM Integration: You need to implement an adapter interface in a language that compiles to VM bytecode. This SDK provides a Solidity interface (read more here). Simulations run in an empty VM loaded only with the indexed contracts, storage and token balances.

• Native Rust Integration: You need to implement a Rust trait that defines the protocol logic. You must index values used in this logic as state attributes.

Execution

To enable swap execution, implement:

1. SwapEncoder: This is a Rust struct that formats input/output tokens, pool addresses, and other parameters correctly for the Executor contract.

2. Executor: This is a Solidity contract that handles the execution of swaps over your protocol's liquidity pools.

Integration Criteria

Tycho supports many protocol designs. However, certain architectures present indexing challenges.

Before you integrate, consider these unsupported designs:

• Protocols where any operation that Tycho should support requires off-chain data, such as signed prices.

Tycho Execution provides tools for encoding and executing swaps against Tycho routers and protocol executors. It is divided into two main components:

• Encoding: A Rust crate that encodes swaps and generates calldata for execution.

• Executing: Solidity contracts for executing trades on-chain.

The source code for Tycho Execution is available . For a practical example of its usage, please refer to our .

Token allowances

You can authorize token transfers in one of three ways with Tycho Execution:

• Permit2

• Standard ERC20 Approvals

• Direct Transfers

Permit2

Tycho Execution leverages Permit2 for token approvals. Before executing a swap via our router, you must approve the Permit2 contract for the specified token and amount. This ensures the router has the necessary permissions to execute trades on your behalf.

When encoding a transaction, we provide functionality to build the Permit struct. However, you are responsible for signing the permit.

For more details on Permit2 and how to use it, see the .

Standard ERC20 Approvals

Tycho also supports traditional ERC20 approvals. In this model, you explicitly call approve on the token contract to grant the router permission to transfer tokens on your behalf. This is widely supported and may be preferred in environments where Permit2 is not yet available.

Direct Transfers

It is possible to bypass approvals altogether by directly transferring the input token to the router within the same transaction. When using this option, the router must be funded during execution.

⚠️ Warning: This feature is intended for advanced users only. The Tycho Router is not designed to securely hold funds — any tokens left in the router are considered lost. Ensure you have appropriate security measures in place to guarantee that funds pass through the router safely and cannot be intercepted or lost.

Security and Audits

The Tycho Router has been audited by . We continuously work to improve security and welcome feedback from the community. The current audits are .

If you discover potential security issues or have suggestions for improvements, please reach out through our official channels.

In some cases, you may need to create custom intermediate protobuf messages, especially when facilitating communication between Substreams handler modules or storing additional data in stores.

Place these protobuf files within your Substreams package, such as ./substreams/ethereum-template/proto/custom-messages.proto. Be sure to link them in the substreams.yaml file. For more details, refer to the substreams or review the official Substreams example integration.

If protocols use factories to deploy components, a common pattern used during indexing is to detect the creation of these new components and store their contract addresses to track them downstream. Later, you might need to emit balance and state changes based on the current set of tracked components.

Implementation Steps

1. Implement logic to identify newly created components. A recommended approach is to create a factory.rs module to facilitate the detection of newly deployed components.

2. Use the logic/helper module from step 1 in a map handler that consumes substreams_ethereum::pb::eth::v2::Block models and outputs a message containing all available information about the component at the time of creation, along with the transaction that deployed it. The recommended output model for this initial handler is BlockTransactionProtocolComponents. Note that a single transaction may create multiple components. In such cases, TransactionProtocolComponents.components should list all newly created ProtocolComponents.

3. After emitting, store the protocol components in a Store. This you will use later in the module to detect relevant balance changes and to determine whether a contract is relevant for tracking.

Once you have the calldata from Encoding, you can execute your trade in one of two ways:

1. Via the Tycho Router – Execute trades through our audited router for seamless execution.

2. Directly to the Executor – Bypass the Tycho Router and execute the trade using your own router.

Tycho Router

The source code for the Tycho Router is here (see contract addresses here). To execute a trade, simply send the calldata generated by the TychoRouterEncoder to the router. The setup for token transfers will vary depending on the token allowance method you chose: if you're using Permit2, ensure the Permit2 contract is approved; for standard ERC-20 approvals, approve the router to spend the token; and if you're using direct transfers, make sure you send tokens to the router before execution.

For an example of how to execute trades using the Tycho Router, refer to the Quickstart.

Executing Directly to the Executor Contract

If you use the TychoExecutorEncoder (see here how to select encoders), you will receive only the calldata for a single swap without any Tycho Router-specific data.

This provides greater control on the token transfers and approvals. But also gives you greater responsibility to make sure that the swap was executed correctly. You are responsible for token approvals, token transfers and error handling in your execution flow.

You need to integrate Tycho Executors into your own router contract. Implement a mechanism similar to our Dispatcher, which uses delegate calls to interact with the Executor contracts.

Steps to integrate Tycho Executors into your own router:

1. Implement something similar to Dispatcher that routes calldata to the correct Executor contract for swap and in case of callbacks.

2. Ensure that your router contract correctly manages token approvals and transfers.

3. Append the calldata for the swap to your overall execution flow.

⚠️ Security Considerations

Tycho's Router has been audited, and its entire execution flow has been verified. However, when using direct execution, Tycho is not responsible for security checks, validation, or execution guarantees. You assume full responsibility for managing token approvals, transfers, and error handling. Ensure that your router contract implements the necessary security measures to prevent reentrancy, slippage manipulation, or loss of funds.

Currently, Tycho supports the following protocols:

VM v.s. Native

There are two types of implementations:

• Native protocols have been implemented using an analytical approach and are ported to Rust - faster simulation.

• VM protocols execute the VM bytecode locally - this is easier to integrate the more complex protocols, however has slower simulation times than a native implementation.

Interested in adding a protocol? Refer to the documentation for implementation guidelines.

In VM implementations, accurately identifying and extracting relevant contract changes is essential.

The tycho_substreams::contract::extract_contract_changes helper function simplifies this process significantly.

Factory protocols

In factory-based protocols, each contract typically corresponds to a unique component, allowing its hex-encoded address to serve as the component ID, provided there is a one-to-one relationship between contracts and components.

The example below shows how to use a component store to define a predicate. This predicate filters for contract addresses of interest:

Other protocols

For protocols where contracts aren't necessarily pools themselves, you'll need to identify specific contracts to track. These addresses can be:

1. Hard-coded (for single-chain implementations)

2. Configured via parameters in your file (for chain-agnostic implementations)

3. Read from the storage of a known contract (hardcoded or configured)

Here's how to extract changes for specific addresses using configuration parameters:

Tracking balances is complex if only relative values are available. If the protocol provides absolute balances (e.g., through logs), you can skip this section and simply emit the absolute balances.

To derive absolute balances from relative values, you’ll need to aggregate by component and token, ensuring that balance changes are tracked at the transaction level within each block.

Implementation Steps:

1. Index relative balance changes

To accurately process each block and report balance changes, implement a handler that returns the BlockBalanceDeltas struct. Each BalanceDelta for a component-token pair must be assigned a strictly increasing ordinal to preserve transaction-level integrity. Incorrect ordinal sequencing can lead to inaccurate balance aggregation.

Example interface for a handler that uses an integer, loaded from a store to indicate if a specific address is a component:

Use the tycho_substream::balances::extract_balance_deltas_from_tx function from our Substreams SDK to extract BalanceDelta data from ERC20 Transfer events for a given transaction, as in the .

2. Aggregate balances with an additive store

To efficiently convert BlockBalanceDeltas messages into absolute values while preserving transaction granularity, use the StoreAddBigInt type with a store module. The tycho_substream::balances::store_balance_changes helper function simplifies this task.

Typical usage of this function:

3. Combine absolute values with component and address

Finally, associate absolute balances with their corresponding transaction, component, and token. Use the tycho_substream::balances::aggregate_balances_changes helper function for the final aggregation step. This function outputs BalanceChange structs for each transaction, which can then be integrated into map_protocol_changes to retrieve absolute balance changes per transaction.

Example usage:

Each step ensures accurate tracking of balance changes, making it possible to reflect absolute values for components and tokens reliably.

Some protocol design choices follow a common pattern. Instructions on how to handle these cases are provided. Such cases include:

• [VM implementations]

Factory contracts

A common protocol design is to use factories to deploy components. In this case it is recommended to detect the creation of these components and store their contract addresses (an potentially other metadata) to track them for use later in the module. See

Tracking contract storage

For VM implementations it is essential that the contract code and storage of all involved contracts are tracked. If these contracts are known, static, and their creation event is observable by the substreams package (occurs after the start block of the package), they can be indexed by the substream package with some helpful utils: see .

If these contracts need to be dynamically determined or their creation event is not observable, instead see below:

Using the Dynamic Contract Indexer (DCI)

For contracts that cannot be statically determined at time of integration or their creation events are not observable by the substreams package, Dynamic Contract Indexer (DCI) support is provided. Keep in mind using this feature adds indexing latency and should be avoided if possible.

The DCI allows you to specify external contract call information, which it will use to trace and identify all contract dependencies. It then automates the indexing of those identified contracts and their relevant storage slots. See.

Using relative component balances

For some protocols, absolute component balances are not easily obtainable. Instead, balance deltas/changes are observed. Since absolute balances are expected by Tycho, it is recommended to use a balance store to track current balances and apply deltas as the occur. See .

Vaults/Singleton contracts

For protocols that store balances in an a-typical way (not on dedicated pool contracts), a special approach to balance tracking must be used. See.

When a contract change is indexed, consumers of the indexed data typically trigger recalculating prices on all pools marked as associated with that contract (the contract is listed in the ProtocolComponent's contracts field). In the case where multiple components are linked to a single contract, such as a vault, this may cause excessive and unnecessary simulations on components that are unaffected by a specific change on the linked contract. In this case it is recommended to use 'manual update' triggers. See for more details.

Persisting data between modules

It is often the case where data needs to be persisted between modules in your substream package. This may be because components and their metadata (such as their tokens, or pool type) are needed when handling state changes downstream, or could be because the protocol reports relative changes instead of absolute values and the relative changes must be compounded to reach an absolute value. For this, substream and are recommended.

Tycho Indexer gives you a low-latency, reorg-aware stream of all attributes you need to simulate swaps over DEX and other onchain liquidity.

Native and VM indexing

Tycho can track protocols in two ways:

• For Native Simulation: Tycho gives structured data that mirrors on-chain states, so you can simulate protocol logic outside the VM (e.g. in your own Rust rewrite of Uni v2 swap function). Useful for example if you solve analytically over the trading curves.

• Virtual Machine (VM) Compatibility: Tycho tracks the state of all protocol contracts so you can simulate calls over it with no network overhead (locally on revm). Used by to simulate key protocol functions (swap, price, derivatives etc.).

Native integrations are more effort, but run faster (~1-5 microseconds or less per simulation), VM integrations are easier to do but run slower (~100–1000 microseconds per simulation).

What Makes Tycho Unique?

• Complete Protocol Systems: Tycho doesn’t just track standalone data; it indexes whole systems, like Uniswap pools or Balancer components, even detecting new elements as they’re created.

• Detailed Component Data: For each tracked protocol component, Tycho records not just static values (like fees or token pairs) but also dynamic state changes, ensuring you have all you need to replicate the onchain state.

Leveraging Substreams

Tycho Indexer leverages Substreams, a robust and scalable indexing framework by StreamingFast.

While Tycho currently uses Substreams to deliver high-performance indexing, our architecture is designed to be flexible, supporting future integrations with other data sources.

A Simple Setup

Setting up using Tycho is simple with the .

Available as a CLI binary, rust crate, or python package.

Some best practices we encourage on all integrations are:

• Clear Documentation: Write clear, thorough comments. Good documentation:

  • Helps reviewers understand your logic and provide better feedback

  • Serves as a guide for future developers who may adapt your solutions

  • Explains why you made certain decisions, not just what they do

• Module Organisation: For complex implementations it is recommended to:

  • Break large module.rs files into smaller, focused files

  • Place these files in a modules directory

  • Name files clearly with numerical prefixes indicating execution order (e.g., 01_parse_events.rs, 02_process_data.rs)

  • Use the same number for parallel modules that depend on the same previous module

  A good example of this done well is in the .

• Substream Initial Block: Your package will work just fine setting the initial block in your manifest file to 1, however it means anyone indexing your protocol has to wait for it to process an excessive number of unnecessary blocks before it reaches the first relevant block. This increases substream costs and causes long wait times for the protocol to reach the current block.

  A good rule of thumb is to identify the earliest deployed contract that you index and set this config to that block.

• Performance Considerations:

  • Minimize use of .clone(), especially in loops or on complex/nested data structures. Instead use references (&) when possible.

Install Rust

Install . You can do so with the following command:

Install Substreams

You can do so with any of the following:

Using Homebrew:

Using precompiled binaries

Compiling from source:

Install Buf

Using Homebrew:

For other installation methods, see the

Fork the SDK repo

1. Start by making a fork of the repository

2. Clone the fork you just created

3. Make sure everything compiles fine

The rust crate provides a flexible library for developers to integrate Tycho’s real-time data into any Rust application.

Setup Guide

To use Tycho Client in Rust, add the following crates to your Cargo.toml:

// Cargo.toml

[dependencies]
tycho-client = "0.66.2"
tycho-common = "0.66.2"

Step 2: Use Tycho-client

From there it is easy to add a Tycho stream to your rust program like so:

// Import required dependencies
use tracing_subscriber::EnvFilter;
use tycho_client::{feed::component_tracker::ComponentFilter, stream::TychoStreamBuilder};
use tycho_common::dto::Chain;

/// Example of using the Tycho client to subscribe to exchange data streams
///
/// This example demonstrates how to:
/// 1. Initialize a connection to the Tycho service
/// 2. Set up filters for specific exchanges and pools
/// 3. Receive and process real-time updates
#[tokio::main]
async fn main() {
    // Initialize the tracing subscriber with environment-based filter configuration
    // Set RUST_LOG environment variable (e.g., RUST_LOG=info) to control logging level
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::from_default_env())
        .init();

    // Create a new Tycho stream for Ethereum blockchain
    // The first returned value is a JoinHandle that we're ignoring here (_)
    let (_, mut receiver) =
        TychoStreamBuilder::new("tycho-beta.propellerheads.xyz", Chain::Ethereum)
            // Set authentication key
            // In production, use environment variable: std::env::var("TYCHO_AUTH_KEY").expect("...")
            .auth_key(Some("sampletoken".into()))
            // Subscribe to Uniswap V2 pools with TVL above 1000 ETH and remove the ones below 900 ETH
            .exchange("uniswap_v2", ComponentFilter::with_tvl_range(900.0, 1000.0))
            // Subscribe to specific Uniswap V3 pools by their pool IDs (contract addresses)
            .exchange(
                "uniswap_v3",
                ComponentFilter::Ids(vec![
                    // Include only these 2 UniswapV3 pools.
                    "0xCBCdF9626bC03E24f779434178A73a0B4bad62eD".to_string(), // USDC/WETH 0.3% pool
                    "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640".to_string(), // USDC/WETH 0.05% pool
                ]),
            )
            // Build the stream client
            .build()
            .await
            .expect("Failed to build tycho stream");

    // Process incoming messages in an infinite loop
    // NOTE: This will continue until the channel is closed or the program is terminated
    while let Some(msg) = receiver.recv().await {
        // Print each received message to stdout
        println!("{:?}", msg);
    }
}

You can also use the client to interact with Tycho RPC for fetching static information. For example, you can fetch tokens (available at Tycho RPC endpoint) with the following:

use tycho_client::rpc::HttpRPCClient;
use tycho_common::dto::Chain;

let client = HttpRPCClient::new("insert_tycho_url", Some("my_auth_token"));

let tokens = client
    .get_all_tokens(
        Chain::Ethereum,
        Some(51_i32), // min token quality to filter for certain token types
        Some(30_u64), // number of days since last traded
        1000,         // pagination chunk size
    )
    .await
    .unwrap();
    
/// Token quality is between 0-100, where:
///  - 100: Normal token
///  - 75: Rebase token
///  - 50: Fee token
///  - 10: Token analysis failed at creation
///  - 5: Token analysis failed on cronjob (after creation).
///  - 0: Failed to extract decimals onchain

A python package is available to ease integration into python-based projects. To install locally:

Setup Guide

Prerequisites

• Git

• Rust 1.84.0 or later

• Python 3.9 or above

Install the package

pip install git+https://github.com/propeller-heads/tycho-indexer.git#subdirectory=tycho-client-py

Understanding and using the Python Client

The Python client is a Python wrapper around our Rust Client that enables interaction with the Tycho Indexer. It provides two main functionalities:

• Streaming Client: Python wrapper around Rust Client for real-time data streaming

• RPC Client: Pure Python implementation for querying Tycho RPC data

Streaming Implementation

The TychoStream class:

1. Locates the Rust binary (tycho-client-cli)

2. Spawns the binary as a subprocess

3. Configures it with parameters like URL, authentication, exchanges, and filters

4. Implements an async iterator pattern that:

   • Reads JSON output from the binary's stdout

   • Parses messages into Pydantic models

   • Handles errors and process termination

Here's one example on how to use it:

import asyncio
from tycho_indexer_client import Chain, TychoStream
from decimal import Decimal

async def main():
    stream = TychoStream(
        tycho_url="localhost:8888",
        auth_token="secret_token",
        exchanges=["uniswap_v2"],
        min_tvl=Decimal(100),
        blockchain=Chain.ethereum,
    )

    await stream.start()

    async for message in stream:
        print(message)

asyncio.run(main())

RPC Client Implementation

The TychoRPCClient class:

• Makes HTTP requests to the Tycho RPC server

• Serializes Python objects to JSON

• Deserializes JSON responses to typed Pydantic models

• Handles blockchain-specific data types like HexBytes

Here's one example on how to use it to fetch tokens information (available at Tycho RPC endpoint):

from tycho_indexer_client import (
    TychoRPCClient,
    TokensParams,
    Chain,
    PaginationParams
)

client = TychoRPCClient("http://0.0.0.0:4242", chain=Chain.ethereum)

all_tokens = []
page = 0

while True:
    tokens = client.get_tokens(
        TokensParams(
            min_quality=51,
            traded_n_days_ago=30,
            pagination=PaginationParams(page=page, page_size=1000),
        )
    )
    
    if not tokens:
        break
    
    all_tokens.extend(tokens)
    page += 1

Sometimes the balances a component uses is stored on a contract that is not a dedicated single pool contract. During Tycho VM simulations, token contracts are mocked and any balances checked or used during a swap need to be overwritten for a simulation to succeed. Default behavior is for the component balances reported to be used to overwrite the pool contract balances. This assumes 2 things: there is a one-to-one relationship between contracts and components, and the hex-encoded contract address serves as the component ID.

If a protocol deviates from this assumption, the balances for each appropriate contract needs to be tracked for that contract. All contracts that have their balances checked/accessed during a simulation need to be tracked in this way.

Implementation Steps:

1. Implement logic/a helper function to extract the absolute balances of the contract. This is protocol specific and might be obtained from an event, or extracted from a storage slot if an appropriate one is identified.

2. Create an InterimContractChange for the contract and add the contract balances using upsert_token_balance.

3. Add these contract changes to the appropriate TransactionChangesBuilder using add_contract_changes.

An example for a protocol that uses a single vault contract is as follows:

use tycho_substreams::models::{InterimContractChange, TransactionChangesBuilder};

// all changes on this block, aggregated by transaction
let mut transaction_changes: HashMap<_, TransactionChanges> = HashMap::new();

// Extract token balances for vault contract
block
    .transaction_traces
    .iter()
    .for_each(|tx| {
        // use helper function to get absolute balances at this transaction
        let vault_balance_change = get_vault_reserves(tx, &components_store, &tokens_store);

        if !vault_balance_change.is_empty() {
            let tycho_tx = Transaction::from(tx);
            let builder = transaction_changes
                .entry(tx.index.into())
                .or_insert_with(|| TransactionChangesBuilder::new(&tycho_tx));

            let mut vault_contract_changes = InterimContractChange::new(VAULT_ADDRESS, false);
            for (token_addr, reserve_value) in vault_balance_change {
                vault_contract_changes.upsert_token_balance(
                    token_addr.as_slice(),
                    reserve_value.value.as_slice(),
                );
            }
            builder.add_contract_changes(&vault_contract_changes);
        }
    });

To add support for a new RFQ provider in Tycho, you’ll need to implement a client, a state, and the logic to encode and execute trades.

The state, encoding, and execution logic for RFQs follow the same structure as on-chain protocol integrations. See our simulation and execution guides for details.

We recommend using the existing Bebop integration as a reference.

RFQClient

Each RFQ protocol must implement the RFQClient trait:

#[async_trait]
pub trait RFQClient: Send + Sync {
    fn stream(
        &self,
    ) -> BoxStream<'static, Result<(String, StateSyncMessage<TimestampHeader>), RFQError>>;

    async fn request_binding_quote(
        &self,
        params: &GetAmountOutParams,
    ) -> Result<SignedQuote, RFQError>;
}

Responsibilities:

• stream: Connects to the RFQ provider and emits real-time indicative price updates.

• request_binding_quote: Sends an HTTP request to fetch a binding quote for a specific swap.

You’ll also need to provide a builder to configure and construct your client, similar to BebopClientBuilder.

State

Each provider must define a state object that represents a full snapshot of their indicative prices.

This state must implement:

• ProtocolSim for simulation

• TryFromWithBlock to decode incoming messages into a usable state

Details on how to implement these can be found here.

Encoder + Executor

To support execution, implement:

• Encoder: Encodes the calldata to execute a swap on the RFQ via the Tycho Router. Be sure to request the binding quote here.

• Executor: Executes the swap

For more see here.

This allows the RFQ to be used in hybrid routes and benefit from Tycho’s execution optimizations.

The following diagram summarizes the code architecture:

Encoding

The TychoRouterEncoder and TychoExecutorEncoder are responsible for validating the solutions of orders and providing you with a list of transactions that you must execute against the TychoRouter or Executors.

The TychoRouterEncoder uses a StrategyEncoder that it choses automatically depending on the solution (see more about strategies here).

Internally, both encoders choose the appropriate SwapEncoder(s) to encode the individual swaps, which depend on the protocols used in the solution.

Execution

The TychoRouter calls one or more Executors (corresponding with the output of the SwapEncoders) to interact with the correct protocol and perform each swap of the solution. The TychoRouter optionally verifies that the user receives a minimum amount of the output token.

If you select the ExecutorStrategyEncoder during setup, you must execute the outputted calldata directly against the Executor which corresponds to the solution’s swap’s protocol. Beware that you are responsible for performing any necessary output amount checks. This strategy is useful if you want to call Tycho executors through your own router. For more information direct execution, see here.

Substreams relies on witnessing contract creations to provide a contract's entire storage. Unless the system witnesses the creation and identifies at that point that the contract is relevant to the protocol, it cannot be indexed or used in simulations.

The Dynamic Contract Indexing (DCI) system is a Tycho feature that addresses this limitation by dynamically identifying and indexing dependency contracts - such as oracles and price feeds - whose creation events are not observable. This may be because:

• the contracts were created long before the protocol's first indexed block (startBlock on the substreams configuration file)

• the dependency is updatable and which contracts are called may change during the protocol's lifetime. For example: a protocol switches oracle provider.

Using predefined tracing information (known as entry points), Tycho's DCI assumes responsibility for these edge cases, with Substreams supplying only the core subset of the data for simulation.

Understanding Entry Points

DCI relies on the substreams package to supply tracing information for it to analyse and detect dependency contracts. It is important to understand the protocol being integrated and know where it might make external calls during simulations (swaps, price etc). These external calls need to be able to be defined fully by the combination of 'Entry Points' and 'Tracing Parameters'. See below for more information on what is not covered by the current DCI implementation.

When an entry point is traced, all subsequent calls to other external contracts are automatically traced. Only the initial entry point needs to be supplied.

Entry Point

An entry point defines an external call in very simple terms:

• address of the contract called

• signature of the function called on that contract

Tracing Parameters

This defines how the entry point should be analysed and provides extra data needed for that analysis. Currently only one approach is supported:

• RPC Trace

  This uses an RPC to simulate the defined external call (entry point) using sample call data. The sample data/parameters that can be defined for this trace include: caller and call data. Any new contracts detected by these traces are fetched at the current block—both code and relevant storage—using an RPC as well. Once the contract is known, further updates are extracted by the DCI from the substream message's block storage_changes (see implementation step 2 below). Note: This approach may cause a temporary indexing delay whenever a new trace is conducted: ie. when new entry points or new tracing parameters are added. The delay depends on the complexity/depth of the trace.

Retracing

A retrace of an entry point occurs in one of two situations:

1. New trace parameters are added to the entry point.

2. A retrigger is triggered. Retriggers are storage slots automatically flagged by the DCI for their potential to influence a trace result. Every time one those identified storage slots are updated, the trace is redone.

Implementation Steps

To use the DCI system, you will need to extend your substream package to emit the following:

1. Data to perform a trace

For successful tracing we need to define: - An 'Entry Point' for each call made to an external contract during a simulation action (swap, price calculation, etc.). - Tracing parameters for the entry point. For every entry point defined, at least 1 set of tracing parameters must be supplied. It is vital that every component that uses an entry point is explicitly linked to that entry point. Some useful helper functions are provided to facilitate building the entry point messages:

• To create a new entry point, use: tycho_substreams::entrypoint::create_entrypoint. Add the returned entry point and entry point parameter messages to the TransactionChangesBuilder using add_entrypoint and add_entrypoint_params respectively. They should be added to the transaction builder for the transaction the linked component was created.

• To add new tracing params to an existing entry point, use: tycho_substreams::entrypoint::add_entrypoint_params. Add the created entry point parameter message to the TransactionChangesBuilderusing add_entrypoint_params:

• To link a new component to an existing entry point, use: tycho_substreams::entrypoint::add_component_to_entrypoint. Add the created entry point message to the TransactionChangesBuilderusing add_entrypoint:

2. All contract changes that occurred on the current block

The tycho_substreams::block_storage::get_block_storage_changes helper function simplifies this process by collecting all relevant changes for you. These changes need to be added to the storage_changes field of the final BlockChanges message emitted by the substream package.

This will be used by the DCI to extract and index contract storage updates for all contracts it identifies.

Limitations

DCI is currently limited to only support cases that can be covered by explicitly defined example trace parameters (i,e callers and call data). This means it cannot cover:

• Arbitrary call data: the automatic generation of call data, or fuzzing, is not supported. For example, external calls that take swap amounts as input - example amounts will not be auto generated and must be explicitly supplied as a Tracing Parameter.

• External signatures: calls that require externally created signatures (like Permit2 signatures). DCI cannot automatically generate valid cryptographic signatures and therefore can only support cases where a valid signature can be defined as a Tracing Parameter.

• Call data from external sources: input parameters that need to be fetched or derived from a separate trace are not supported. Only call data available within the Substreams package context can be processed.

Frequently Asked Questions

Q: Is it okay to redefine the same entry point multiple times? A: Yes. Tycho will deduplicate entry points, allowing you to add the same entry point for every new component without needing to track which ones already exist. Using storage on a substreams module affects the performance of the module so should be avoided where possible.

1. Understanding the protocol

Before integrating, ensure you understand the protocol’s structure and behavior. Here are the key areas:

1. Contracts and their roles: Identify the protocol's contracts and their specific roles. Understand how the contracts impact the behavior of the component you want to integrate.

2. Conditions for state changes: Determine which conditions trigger state changes – like price updates – in the protocol. For example, oracle updates or particular method calls.

3. Component addition and removal: Check how the protocol adds and removes components. Many protocols use a factory contract to deploy new components. Or they provide new components directly through specific method calls.

Once you understand the protocol's mechanics, you can proceed with implementation.

2. Choosing a template

These two templates outline all necessary steps for implementation:

• Use when the protocol deploys one contract per pool (e.g., UniswapV2, UniswapV3).

• Usewhen the protocol uses a fixed set of contracts (e.g., UniswapV4).

Find support in the group if you don't know which template to choose.

After choosing a template:

1. Create a new directory for your integration: copy the template and rename all the references to ethereum-template-[factory|singleton] to [CHAIN]-[PROTOCOL_SYSTEM](use lowercase letters):

2. Generate the required protobuf code by running:

3. Register the new package within the workspace by adding it to the members list in substreams/Cargo.toml.

4. Add any protocol-specific ABIs under [CHAIN]-[PROTOCOL-SYSTEM]/abi/

5. Your project should compile and it should run with substreams:

3. Implementation

If you use a template, you must implement at least three key sections to ensure proper functionality:

1. Identify new ProtocolComponents and metadata

   Extract relevant protocol components and attach all metadata (attributes) necessary to encode swaps (or other actions) or to filter components. For example: pool identifier, pool keys, swap fees, pool_type, or other relevant static properties. Some. They are not always needed but must be respected for compatibility.

2. Emit balances forProtocolComponents Tycho tracks TVL per component. So you must emit a BalanceChange whenever an event impacts a component's associated balances. Absolute balances are expected here. Protocols often only identify balance deltas - to handle these effectively please see ''.

3. Track relevant storage slot changes (VM implementations only) For factory-like protocols: the template covers this automatically if the ProtocolComponent.id matches the contract address. For singleton contracts: you must collect the changes for contracts that you need tracked. To do this effectively, please see ''.

Some protocols may require additional customisation based on their specific architecture. See for how to handle these cases.

4. Testing

To test indexing only, follow the instructions for the, but set to true. This will limit the test run to evaluating only the substreams package's indexing behavior, without running simulations.

Local Development

Changing Rust Code

Please make sure that the following commands pass if you have changed the code:

We are using the stable toolchain for building and testing, but the nightly toolchain for formatting and linting, as it allows us to use the latest features of rustfmt and clippy.

If you are working in VSCode, we recommend you install the extension, and use the following VSCode user settings:

Changing Solidity code

Setup

Install foudryup and foundry

Running tests

Code formatting

Assembly

Please minimize use of assembly for security reasons.

Contract Analysis

We use to detect any potential vulnerabilities in our contracts.

To run locally, simply install Slither in your conda env and run it inside the foundry directory.

Creating a Pull Request

We use as our convention for formatting commit messages and PR titles.

Cow Protocol

To solve orders on , you'll need to prepare your solution following specific formatting requirements.

First, initialize the encoder:

Since you are not passing the swapper_pk, the TychoRouter will use a transferFrom to transfer the token in as opposed to using permit2.

When solving for CoW Protocol, you need to return a that contains a list of interactions to be executed in sequence.

To solve with the Tycho Router you only need one custom interaction where:

1. callData is the full encoded method calldata using the encoded solution returned from encoder.encode_solutions(...)

2. allowances is a list with one entry where the allowance for the token in and amount in is set for spender to be the Tycho Router. This is necessary for the transferFrom to work.

Uniswap X

To help you fill Uniswap X orders using Tycho, we provide an example contract. This contract is a starting point—you should adapt it to fit your use case.

The example contract:

• Inherits from IReactorCallback and implements execute and reactorCallback

• Calls the TychoRouter from reactorCallback to execute swaps

• Uses standard token approvals to allow TychoRouter to pull funds; you can replace this with Permit2 easily (you need to change the encoding accordingly though).

• Approves the UniswapX Reactor contract to transfer tokens out after execution

• Only supports solving one order at a time; you can extend it to support batching by implementing executeBatch and updating reactorCallback

• Can safely hold tokens. The Uniswap X Reactor only transfers out the required amount. If your solution is more efficient, any surplus stays in the filler contract

• Is not audited—use at your own risk

See how to encode the callbackData for TychoRouter .

For more on filling Uniswap X orders, see their and .

Other competition venues

For other venues, like 1inch Fusion, please contact us.

Our indexing integrations require a Substreams SPKG to transform raw blockchain data into structured data streams. These packages enable our indexing integrations to track protocol state changes with low latency.

What is Substreams?

Substreams is a new indexing technology that uses Rust modules to process blockchain data. An SPKG file contains the Rust modules, protobuf definitions, and a manifest, and runs on the Substreams server.

Learn more:

Integration Modes

VM Integration

VM integrations primarily track contract storage associated with the protocol’s behavior. Most integrations will likely use the VM method due to its relative simplicity, so this guide focuses on VM-based integrations.

It's important to know that simulations run in an empty VM, which is only loaded with the indexed contracts and storage. If your protocol calls external contracts during any simulation (swaps, price calculations, etc.), those contracts also have to be indexed. There are 2 approaches that can be used to index external contracts:

• Direct indexing on the substream package. This is where you index the external contract the same way you would index your own protocol's contract. A key limitation in Substreams to keep in mind is that you must witness a contract’s creation to access its full storage and index it.

• Using the DCI (Dynamic Contract Indexer). To be used if your protocol calls external contracts whose creation event cannot be witnessed within the Substreams package - for example: oracles deployed long before the protocol's initial block, or when which contract is called can be changed during the protocol's lifetime. Use of the DCI introduces indexing latency and should only be used if necessary.

Native Integration

Native integrations follow a similar approach, with one main difference: Instead of emitting changes in contract storage slots, they should emit values for all created and updated attributes relevant to the protocol’s behavior.

Understanding the Data Model

The Tycho Indexer ingests all data versioned by block and transaction. This approach maintains a low-latency feed. And it correctly handles chains that undergo reorgs. Here are the key requirements for the data emitted:

1. Each state change must include the transaction that caused it.

2. Each transaction must be paired with its corresponding block.

3. All changes must be absolute values (final state), not deltas.

Details of the data model that encodes these changes, transactions, and blocks in messages are available . These models facilitate communication between Substreams and the Tycho Indexer, and within Substreams modules. Tycho Indexer expects to receive a BlockChanges output from your Substreams package.

You must aggregate changes at the transaction level. Emitting BlockChanges with duplicate transactions in the changes attributes is an error.

Data Encoding

To ensure compatibility across blockchains, many data types are encoded as variable-length bytes. This flexible approach requires an informal interface so that consuming applications can interpret these bytes consistently:

• Integers: When encoding integers, particularly those representing balances, always use unsigned big-endian format. Multiple points within the system reference balances, so they must be consistently decoded along their entire journey.

• Strings: Use UTF-8 encoding for any string data stored as bytes.

• Attributes: Attribute encoding is variable and depends on specific use cases. But whenever possible, follow the encoding standards above for integers and strings.

Reserved Attributes

We reserve some attribute names for specific functions in our simulation process. Use these names only for their intended purposes. .

Changes of interest

Tycho Protocol Integrations should communicate the following changes:

1. New Protocol Components: Signify any newly added protocol components. For example, pools, pairs, or markets – anything that indicates you can execute a new operation using the protocol.

2. ERC20 Balances: For any contracts involved with the protocol, you should report balance changes in terms of absolute balances.

3. Protocol State Changes: For VM integrations, this typically involves reporting contract storage changes for all contracts whose state is accessible during a swap operation (except token contracts).

For a hands-on integration guide, see the following pages:

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 Tycho Simulation repository; here's the quickstart code.

Run the quickstart with execution using the following commands:

export RPC_URL=https://ethereum.publicnode.com
export PRIVATE_KEY=<your-private-key>
cargo run --release --example quickstart --

export RPC_URL=https://base-rpc.publicnode.com
export PRIVATE_KEY=<your-private-key>
cargo run --release --example quickstart -- --chain base

export RPC_URL=https://unichain-rpc.publicnode.com
export PRIVATE_KEY=<your-private-key>
cargo run --release --example quickstart -- --chain unichain

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

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:

Looking for pool with best price for 10 USDC -> WETH

==================== Received block 14222319 ====================

The best swap (out of 6 possible pools) is:
Protocol: "uniswap_v3"
Pool address: "0x65081cb48d74a32e9ccfed75164b8c09972dbcf1"
Swap: 10.000000 USDC -> 0.006293 WETH 
Price: 0.000629 WETH per USDC, 1589.052587 USDC per WETH

Signer private key was not provided. Skipping simulation/execution. Set PRIVATE_KEY env variable to perform simulation/execution.

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

export TYCHO_URL=<tycho-api-url-for-chain>
export TYCHO_API_KEY=<tycho-api-key-for-chain>
cargo run --release --example quickstart -- --sell-token "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" --buy-token "0x4200000000000000000000000000000000000006" --tvl-threshold 100 --sell-amount 10 --chain "base"

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:

RUST_LOG=info cargo run --release --example quickstart

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 a swap of 10 USDC against the best pool.

5. Execute the swap against the Tycho Router.

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 (by default, the test key is sampletoken)

• 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, load_all_tokens 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.

let mut protocol_stream = ProtocolStreamBuilder::new(&tycho_url, Chain::Ethereum)
    .exchange::<UniswapV2State>("uniswap_v2", tvl_filter.clone(), None)
    .exchange::<EVMPoolState<PreCachedDB>>(
        "vm:balancer_v2",
        tvl_filter.clone(),
        Some(balancer_pool_filter),
    )
    .auth_key(Some(tycho_api_key.clone()))
    .set_tokens(all_tokens.clone())
    .await
    .build()
    .await
    .expect("Failed building protocol stream");

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

.exchange::<UniswapV3State>("uniswap_v3", tvl_filter.clone(), None)

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

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

let result = state.get_amount_out(amount_in, &tokens[0], &tokens[1])

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.

let other_result = result.new_state.get_amount_out(other_amount_in, &tokens[0], &tokens[1])

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.

let slippage = 0.0025; // 0.25% slippage
let bps = BigUint::from(10_000u32);
let slippage_percent = BigUint::from((slippage * 10000.0) as u32);
let multiplier = &bps - slippage_percent;
let min_amount_out = (expected_amount * &multiplier) / &bps;

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

let simple_swap =
    SwapBuilder::new(component, sell_token.address.clone(), buy_token.address.clone()).build();

// Then we create a solution object with the previous swap
let solution = Solution {
    sender: user_address.clone(),
    receiver: user_address,
    given_token: sell_token.address,
    given_amount: sell_amount,
    checked_token: buy_token.address,
    exact_out: false,     // it's an exact in solution
    checked_amount: min_amount_out,
    swaps: vec![simple_swap],
    ..Default::default()
};

b. Encode solution

let encoder = TychoRouterEncoderBuilder::new()
    .chain(chain)
    .user_transfer_type(UserTransferType::TransferFromPermit2)
    .build()
    .expect("Failed to build encoder");

let encoded_solution = encoder
    .encode_solutions(vec![solution.clone()])
    .expect("Failed to encode router calldata")[0]

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:

let tx = encode_tycho_router_call(
    named_chain.into(),
    encoded_solution.clone(),
    &solution,
    chain.native_token().address,
    signer.clone(),
)
.expect("Failed to encode router call");

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.

cargo run --release --example quickstart -- --swapper-pk $PK

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

Your balance: 100.000000 USDC
Your WETH balance: 1.500000 WETH

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

Your balance: 5.000000 USDC
⚠️ Warning: Insufficient balance for swap. You have 5.000000 USDC but need 10.000000 USDC
Your WETH balance: 1.500000 WETH

You'll then encounter the following prompt:

Would you like to simulate or execute this swap?
Please be aware that the market might move while you make your decision, which might lead to a revert if you've set a min amount out or slippage.
Warning: slippage is set to 0.25% during execution by default.

? What would you like to do? ›
❯ Simulate the swap
  Execute the swap
  Skip this swap

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:

Simulating by performing an approval (for permit2) and a swap transaction...

Simulated Block 21944458:
  Transaction 1: Status: true, Gas Used: 46098
  Transaction 2: Status: true, Gas Used: 182743

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:

Executing by performing an approval (for permit2) and a swap transaction...

Approval transaction sent with hash: 0xf2a9217016397b09f5274e225754029ebda31743b4da7dd1441e13971e1f43b0 and status: true

Swap transaction sent with hash: 0x0b26c9965b4ee39b5646ab93070f018c027ac3d0c9d56548a6db4412be7abbc8 and status: true

✅ Swap executed successfully! Exiting the session...

Summary: Swapped 10.000000 USDC → 0.006293 WETH at a price of 0.000629 WETH per USDC

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.

5. Execute a Swap: Execute the best trade using the Tycho Router.

What's next?

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

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

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

• Explore Tycho Indexer: Add or modify the data that Tycho indexes.

When to use the binary client

The binary client is recommended for 2 situations:

• For a quick setup, to consume data from Tycho Indexer direct on a terminal

• To consume data from Tycho Indexer on apps developed in languages where there isn't a native tycho client available (e.g: any languages apart from Rust and Python). For the supported languages, please check the Rust Clientor Python Clientdocs.

Installing Tycho-client

This guide provides two methods to install Tycho Client:

1. Install with Cargo (recommended for most users)

2. Download pre-built binaries from GitHub Releases

Method 1: Install with Cargo

Prerequisites

• Cargo

• Rust 1.84.0 or later

cargo install tycho-client

Method 2: Download from GitHub Releases

Step 1: Download the pre-built binary

For a simple, setup-free start, download the latest tycho-client binary release that matches your OS/architecture on GitHub.

Step 2: Extract the binary from the tar.gz

Open a terminal and navigate to the directory where the file was downloaded. Run the following command to extract the contents:

tar -xvzf tycho-client-aarch64-apple-darwin-{version}.tar.gz

Step 3: Link the binary to a directory in your system's PATH (recommended):

// Ensure the binary is executable:
sudo chmod +x tycho-client
// Create symlink
sudo ln -s $(pwd)/tycho-client /usr/local/bin/tycho-client

export PATH"/usr/local/bin:$PATH"

/bin
/sbin
/usr/bin
/usr/sbin
/usr/local/bin
/usr/local/sbin

Step 4: Verify Installation

tycho-client --version
tycho-client 0.54.0 # should match the latest version published on GitHub

You should see the Tycho Client version displayed. If you need more guidance, contact us via Telegram

Using Tycho Client

Running the client

Step 1: Setting up API Key

If you're connecting to our hosted service, please follow our to get an API Key. Once you have a key, export it using an environment variable

export TYCHO_AUTH_TOKEN={your_token}

or use the command line flag

tycho-client --auth-key {your_token}

Step 2: Consume data from Tycho Indexer

Now, you're all set up!

Before consuming the data, you first need to choose which protocols you want to track. You can find a list of here. For example, to track the Uniswap V2 and V3 pools on Mainnet, with a minimum value locked of 100 ETH, run:

tycho-client --exchange uniswap_v2 --exchange uniswap_v3 --min-tvl 100 --tycho-url 
tycho-beta.propellerheads.xyz

Or skip secure connections entirely with --no-tls for local setups [coming soon].

Debugging

Since all messages are sent directly to stdout in a single line, logs are saved to a file: ./logs/dev_logs.log. You can configure the directory with the --log-dir option.

Configuring the client

For more details on using the CLI and its parameters, run:

tycho client --help

For extended explanation on how each parameter works, check our guide.

Ethereum

Base

Unichain

To enable simulations for a newly added protocol, it must first be integrated into the Tycho Simulation repository. Please submit a pull request to the to include it.

Native Integration

In order to add a new native protocol, you will need to complete the following high-level steps:

1. Create a protocol state struct that contains the state of the protocol, and implements the ProtocolSim trait (see ).

2. Create a tycho decoder for the protocol state: i.e. implement TryFromWithBlock for ComponentWithState to your new protocol state.

Each native protocol should have its own module under tycho-simulation/src/evm/protocol.

VM Integration

To create a VM integration, provide a manifest file and an implementation of the corresponding adapter interface. is a library to integrate DEXs and other onchain liquidity protocols into Tycho.

Example Implementations

The following exchanges are integrated with the VM approach:

• Balancer V2 (see code )

Install prerequisites

1. Install , start by downloading and installing the Foundry installer:

   then start a new terminal session and run

2. Clone the Tycho Protocol SDK:

3. Install dependencies:

Understanding the ISwapAdapter

Read the documentation of the interface. It describes the functions that need to be implemented and the manifest file.

Additionally, read through the docstring of the interface and the interface, which defines the data types and errors the adapter interface uses. You can also generate the documentation locally and look at the generated documentation in the ./docs folder:

Implementing the ISwapAdapter interface

Your integration should be in a separate directory in the evm/src folder. Start by cloning the template directory:

Implement the ISwapAdapter interface in the ./evm/src/<your-adapter-name>.sol file. See Balancer V2 implementation for reference.

Testing your implementation

1. Set up test files:

   • Copy evm/test/TemplateSwapAdapter.t.sol

   • Rename to <your-adapter-name>.t.sol

2. Write comprehensive tests:

   • Test all implemented functions.

   • Use fuzz testing (see , especially the chapter for )

   • Reference existing test files: BalancerV2SwapAdapter.t.sol

3. Configure fork testing (run a local mainnet fork against actual contracts and data):

   • Set ETH_RPC_URL environment variable

   • Use your own Ethereum node or services like

4. Run the tests with

Add implementation to Tycho simulation

Once you have the swap adapter implemented for the new protocol, you will need to:

1. Generate the adapter runtime file by running the script in our SDK repository with the proper input parameters. For example, in order to build the Balancer V2 runtime, the following command can be run:

2. Add the associated adapter runtime file to tycho-simulations/src/protocol/vm/assets. Make sure to name the file according to the protocol name used by Tycho Indexer in the following format: <Protocol><Version>Adapter.evm.runtime. For example: vm:balancer_v2 will be BalancerV2Adapter.evm.runtime. Following this naming format is important as we use an automated name resolution for these files.

Filtering

If your implementation does not support all pools indexed for a protocol, you can create a filter function to handle this. This filter can then be used when registering an exchange in the ProtocolStreamBuilder. See for example implementations.

Swap/Exchange Protocol Guide

Implementing the Protocol

To integrate an EVM exchange protocol:

1. Implement the interface.

2. Create a manifest file summarizing the protocol's metadata.

The Manifest File

The manifest file contains author information and additional static details about the protocol and its testing. Here's a list of all valid keys:

Key Functions

Price (optional)

Calculates marginal prices for specified amounts.

• Return marginal prices in buyToken/sellToken units.

• Include all protocol fees (use minimum fee for dynamic fees).

• If you don't implement this function, flag it accordingly in capabilities and make it revert using the NotImplemented error.

• While optional, we highly recommend implementing this function. If unavailable, we'll numerically estimate the price function from the swap function.

Swap

Simulates token swapping on a given pool.

• Execute the swap and change the VM state accordingly.

• Include a gas usage estimate for each amount (use gasleft() function).

• Return a Trade struct with a price attribute containing price(specifiedAmount).

• If the price function isn't supported, return Fraction(0, 1) for the price (we'll estimate it numerically).

GetLimits

Retrieves token trading limits.

• Return the maximum tradeable amount for each token.

• The limit is reached when the change in received amounts is zero or close to zero.

• Overestimate the limit if in doubt.

• Ensure the swap function doesn't error with LimitExceeded for amounts below the limit.

getCapabilities

Retrieves pool capabilities.

getTokens (optional)

Retrieves tokens for a given pool.

• We mainly use this for testing, as it's redundant with the required substreams implementation.

getPoolIds (optional)

Retrieves a range of pool IDs.

• We mainly use this for testing. It's okay not to return all available pools here.

• This function helps us test against the substreams implementation.

• If you implement it, it saves us time writing custom tests.

Certain attribute names are reserved exclusively for specific purposes. Please use them only for their intended applications. Attribute names are unique: if the same attribute is set twice, the value will be overwritten.

Static Attributes

The following attributes names are reserved and must be given using ProtocolComponent.static_att. These attributes MUST be immutable.

1. manual_updates

Description

Determines whether the component updates should be manually triggered using the update_marker state attribute. By default, updates occur automatically whenever there is a change indexed for any of the required contracts. For contracts with frequent changes, automatic updates may not be desirable. For instance, a change in Balancer Vault storage should only trigger updates for the specific pools affected by the change, rather than for all pools indiscriminately. The manual_updates field helps to control and prevent unnecessary updates in such cases.

If it's enable, updates on this component are only triggered by emitting an update_marker state attribute (described ).

Type

Set to [1u8]to enable manual updates.

Example Usage

2. pool_id

Description

The pool_id static attribute is used to specify the identifier of the pool when it differs from the ProtocolComponent.id. For example, Balancer pools have a component ID that corresponds to their contract address, and a separate pool ID used for registration on the Balancer Vault contract (needed for swaps and simulations).

Notice: In most of the cases, using ProtocolComponent.id is preferred over pool_id and pool_id should only be used if a special identifier is strictly necessary.

Type

This attribute value must be provided as a UTF-8 encoded string in bytes.

Example Usage

State Attributes

The following attributes names are reserved and must be given using EntityChanges. Unlike static attributes, state attributes are updatable.

1. stateless_contract_addr

Description

The stateless_contract_addr_{index} field specifies the address of a stateless contract required by the component. Stateless contracts are those where storage is not accessed for the calls made to it during swaps or simulations.

This is particularly useful in scenarios involving DELEGATECALL. If the contract's bytecode can be retrieved in Substreams, provide it using the stateless_contract_code attribute (see ).

Note: If no contract code is given, the consumer of the indexed protocol has to access a chain node to fetch the code. This is considered non-ideal and should be avoided where possible.

An index is used if multiple stateless contracts are needed. This index should start at 0 and increment by 1 for each additional stateless_contract_addr.

The value for stateless_contract_addr_{index} can be provided in two ways:

1. Direct Contract Address: A static contract address can be specified directly.

2. Dynamic Address Resolution: Alternatively, you can define a function or method that dynamically resolves and retrieves the stateless contract address at runtime. This can be particularly useful in complex contract architectures, such as those using a dynamic proxy pattern. It is important to note that the called contract must be indexed by the Substreams module.

Type

This attribute value must be provided as a UTF-8 encoded string in bytes.

Example Usage

1. Direct Contract Address

To specify a direct contract address:

2. Dynamic Address Resolution

To specify a function that dynamically resolves the address:

2. stateless_contract_code

Description

The stateless_contract_code_{index} field is used to specify the bytecode for a given stateless_contract_addr. The index used here must match with the index of the related address.

Type

This attribute value must be provided as bytes.

Example Usage

3. update_marker

Description

The update_marker field is used to indicate that a pool has changed, thereby triggering an update on the protocol component. This is particularly useful for when is enabled.

Type

Set to [1u8]to trigger an update.

Example Usage

4. balance_owner[deprecated]

Description

The balance_owner field specifies the address of the account that owns the protocol component tokens, when tokens are not owned by the protocol component itself or the multiple contracts are involved. This is particularly useful for protocols that use a vault, for example Balancer.

Type

This attribute value must be provided as bytes.

Example Usage

Request for Quote (RFQ) protocols work differently from on-chain protocols. Instead of reading pool data from the chain, they fetch prices from off-chain market makers via WebSocket or API.

You ask for a quote for a specific trade size, and they return a price. Quotes can be:

• Indicative — estimated prices used for simulation.

• Binding — firm prices, valid for a short time, used at execution.

Tycho supports streaming, simulating, and executing RFQ quotes as part of multi-protocol swaps.

Quickstart

The RFQ quickstart is similar to the other protocols .

See the code . As of now, and are the only supported providers.

You need to set up the API credentials of the desired RFQs to access live pricing data and quoting, as well as your private key if you wish to execute against the Tycho Router:

Then run the example:

What it does

The quickstart:

• Connects to the RFQ stream and fetches live price updates.

• Simulates the best available amount out for a given pair (default: 10 USDC → WETH on mainnet).

• Encodes the swap and prepares calldata to execute it via the Tycho Router.

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

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

Set up

You’ll need to configure:

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

• Tycho API key (by default, the test key is sampletoken)

• RFQ API keys (Have a look at src/rfq/constants.rs to see the authentication variables that are expected)

• Private key if you wish to execute the swap against the Tycho Router

To get token information from Tycho Indexer RPC please use .

RFQClient

Each RFQ protocol will have its own client. The client can stream live prices updates and request binding quotes.

Example setup for Bebop:

TVL threshold is specified in USD, as most RFQ quotes are USD-denominated. This setting filters out token pairs with low liquidity on the RFQ side, helping avoid thin or illiquid quotes.

Quote tokens: You can optionally specify quote tokens when configuring the RFQ client to define which tokens the client should consider “approved” for TVL normalization purposes. The client uses this approved quote token list exclusively for TVL filtering and does not use it for quote requests or trade execution.

You should specify USD-priced stablecoins (e.g., USDC, USDT, DAI) as quote tokens, since currently-supported RFQ providers quote most of their currently supported liquidity in USD stablecoins. This ensures the client calculates TVL accurately when comparing pairs with different quote tokens. For instance, if you receive price levels for an ETH/WBTC pair where WBTC is the quote token, the client will look up the WBTC price in one of your approved quote tokens (USD stablecoins) to properly calculate the TVL in dollar terms. If you don’t explicitly set quote tokens, the client uses chain-specific defaults.

Note: Some RFQ providers may support tokens that Tycho does not. Because execution happens through the Tycho Router, it’s important to ensure that all tokens used in RFQ quotes are also supported by Tycho.

Stream: Real-Time Price Updates

The RFQStreamBuilder handles registration of multiple RFQ clients and merges their message streams. It merges updates from one or more RFQ clients and decodes them into Update messages:

• Use add_client() for each RFQ provider.

• Streams that return errors are removed automatically.

RFQ streams are timestamped, not block-based. Each update provides the full known state from the provider at that moment (not just deltas). The removed_pairs field indicates any pairs that disappeared since the last update. The new_pairs field contains all the currently available pairs.

Simulation

You can simulate a swap against an RFQ state using:

This returns an indicative output amount, which you can use to decide if this swap is worth including.

Encoding

After choosing the best swap, you can use Tycho Execution to encode it. This is very similar to the encoding done in the general .

Create a solution object

The key parameter is minimum amount out, which protects against slippage and MEV. The quickstart applies 0.25% slippage tolerance.

Build the Swap and Solution:

When working with RFQs, two fields are required in Swap:

• protocol_state: This is needed to enable the runtime generation of a binding quote at encoding time—for example:

• estimated_amount_in : This represents the estimaed input amount for the quote request. It’s especially important when the swap path is complex (e.g., involving multiple hops), where the actual input amount may differ slightly because of slippage. We recommend setting estimated_amount_in a bit higher than your expected value. Many RFQs enforce that execution can only occur for amounts less than or equal to the quoted base amount—so setting it conservatively helps avoid dropping funds. If the actual required input exceeds your estimate, any leftover tokens will remain in the Tycho Router.

This mechanism also makes RFQs composable with other on-chain swaps. That enables hybrid routing strategies, such as a path like Uniswap → RFQ → Curve, seamlessly combining RFQ-based and traditional on-chain routes.

Encode solution

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:

Execution

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.

Once the best swap is found you can:

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. If the status is false, the simulation has failed. You can print the full simulation output for detailed failure information.

2. 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. After a successful execution, the program will exit. If the transaction fails, the program continues to stream new price updates.

3. Skip this swap: Ignores this swap. Then the program resumes listening for price updates.

Tycho Simulation is a Rust crate that provides powerful tools for interacting with protocol states, calculating spot prices, and simulating token swaps.

The repository is available here.

Installation

The tycho-simulation package is available on Github.

To use the simulation tools with Ethereum Virtual Machine (EVM) chains, add the optional evm feature flag to your dependency configuration:

tycho-simulation = { 
     git = "https://github.com/propeller-heads/tycho-simulation.git",
     package = "tycho-simulation",
     tag = "x.y.z", # Replace with latest version
     features = ["evm"]
}

Add this to your project's Cargo.toml file.

Main Interface

All protocols implement the ProtocolSim trait (see definition here). It has the main methods:

Spot price

spot_price returns the pool's current marginal price.

fn spot_price(&self, base: &Token, quote: &Token) -> Result<f64, SimulationError>;

Get amount out

get_amount_out simulates token swaps.

fn get_amount_out(
    &self,
    amount_in: BigUint,
    token_in: &Token,
    token_out: &Token,
) -> Result<GetAmountOutResult, SimulationError>;

You receive a GetAmountOutResult , which is defined as follows:

pub struct GetAmountOutResult {
    pub amount: BigUint, // token_out amount you receive
    pub gas: BigUint, // gas cost
    pub new_state: Box<dyn ProtocolSim>, // state of the protocol after the swap
}

new state allows you to, for example, simulate consecutive swaps in the same protocol.

Please refer to the in-code documentation of the ProtocolSim trait and its methods for more in-depth information.

Fee

fee returns the fee of the protocol as a ratio. For example if the fee is 1%, the value returned would be 0.01.

fn fee(&self) -> f64;

Get limits

get_limits returns a tuple containing the maximum amount in and out that can be traded between two tokens.

fn get_limits(
        &self,
        sell_token: Address,
        buy_token: Address,
    ) -> Result<(BigUint, BigUint), SimulationError>;

Streaming Protocol States

To maintain up-to-date states of the protocols you wish to simulate over, you can use a Tycho Indexer stream. Such a stream can be set up in 2 easy steps:

Step 1: Fetch tokens

It is necessary to collect all tokens you are willing to support/swap over as this must be set on the stream builder in step 2. You can either set up custom logic to define this, or use the Tycho Indexer RPC to fetch and filter for tokens of interest. To simplify this, a util function called load_all_tokensis supplied and can be used as follows:

use tycho_simulation::utils::load_all_tokens;
use tycho_core::models::Chain;

let all_tokens = load_all_tokens(
            "tycho-beta.propellerheads.xyz",  // tycho url
            false,                            // use tsl (this flag disables tsl)
            Some("sampletoken"),              // auth key
            Chain::Ethereum,                  // chain
            None,                             // min quality (defaults to 100: ERC20-like tokens only) 
            None,                             // days since last trade (has chain specific defaults)
        ).await;

Step 2: Create a stream

You can use the ProtocolStreamBuilder to easily set up and manage multiple protocols within one stream. An example of creating such a stream with Uniswap V2 and Balancer V2 protocols is as follows:

use tycho_simulation::evm::{
    engine_db::tycho_db::PreCachedDB,
    protocol::{
        filters::balancer_pool_filter, uniswap_v2::state::UniswapV2State, vm::state::EVMPoolState,
    },
    stream::ProtocolStreamBuilder,
};
use tycho_core::models::Chain;
use tycho_client::feed::component_tracker::ComponentFilter;

let tvl_filter = ComponentFilter::with_tvl_range(9, 10); // filter buffer of 9-10ETH
let mut protocol_stream = ProtocolStreamBuilder::new("tycho-beta.propellerheads.xyz", Chain::Ethereum)
    .exchange::<UniswapV2State>("uniswap_v2", tvl_filter.clone(), None)
    .exchange::<EVMPoolState<PreCachedDB>>(
        "vm:balancer_v2",
        tvl_filter.clone(),
        Some(balancer_pool_filter),
    )
    .auth_key(Some("sampletoken"))
    .skip_state_decode_failures(true) // skips the pool instead of panicking if it errors on decode
    .set_tokens(all_tokens.clone())
    .await
    .build()
    .await
    .expect("Failed building protocol stream");

Some protocols, such as Balancer V2 and Curve, require a pool filter to be defined to filter out unsupported pools. If a protocol needs a pool filter and the user does not provide one, a warning will be raised during the stream setup process.

The stream created emits Update messages which consist of:

• block number_or_timestamp- the block this update message refers to

• new_pairs- new components witnessed (either recently created or newly meeting filter criteria)

• removed_pairs- components no longer tracked (either deleted due to a reorg or no longer meeting filter criteria)

• states- the updated ProtocolSim states for all components modified in this block

The first message received will contain states for all protocol components registered to. Thereafter, further block updates will only contain data for updated or new components.

Note: For efficiency, ProtocolSim states contain simulation-critical data only. Reference data such as protocol names and token information is provided in the ProtocolComponent objects within the new_pairs field. Consider maintaining a store of these components if you need this metadata.

For a full list of supported protocols and the simulation state implementations they use, see Supported Protocols.

 // SIMULATION PARAMS
 // Set sell and buy tokens to USDC and USDT respectively
 let sell_token = Token::new("0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", 6, "USDC", BigUint::from(10000u64));
 let buy_token = Token::new("0xdac17f958d2ee523a2206206994597c13d831ec7", 6, "USDT", BigUint::from(10000u64));
 let sell_amount = BigUint::from(1000000000u64); // 1000 USDC

// PERSIST DATA BETWEEN BLOCKS
// track all witnessed ProtocolComponents from the stream
let mut all_pools = HashMap::new();
// track all amount_outs for each pool simulated
let mut amount_out = HashMap::new()

// loop through stream messages
while let Some(stream_message) = protocol_stream.next().await {
     let message = match stream_message {
        Ok(msg) => msg,
        Err(err) => {
            eprintln!("Error receiving message: {err}");
            break; // Exit loop on stream error
        }
    };
    
    // Store any new protocol components we haven't seen before
    for (id, comp) in message.new_pairs.iter() {
        all_pools
            .entry(id.clone())
            .or_insert_with(|| comp.clone());
    }
    
    // Simulate swaps on any updated pools that contain our token pair
    for (id, state) in message.states.iter() {
        if let Some(component) = all_pools.get(id) {
            // Skip if this pool doesn't contain both of our tokens
            let tokens = &component.tokens;
            if !tokens.contains(&sell_token) || !tokens.contains(&buy_token) {
                continue;
            }
            
            // Calculate the amount out for our swap
            match state.get_amount_out(sell_amount.clone(), &sell_token, &buy_token) {
                Ok(result) => {
                    amounts_out.insert(id.clone(), result.amount);
                },
                Err(err) => {
                    eprintln!("Error calculating amount out for pool {id}: {err}");
                }
            }
        }
    }
}

Example Use Case: Token Price Printer

You can find an example of a price printer here.

Clone the repo, then run:

export RPC_URL=<your-eth-rpc-url>
cargo run --release --example price_printer -- --tvl-threshold 1000

You will see a UI where you can select any pool, press enter, and simulate different trade amounts on the pool.

The program prints logs automatically to a file in the logs directory in the repo.

Tycho Client helps you consume data from Tycho Indexer. It's the recommended way to connect to the Indexer data stream, whether you're using our or running your own instance.

In this guide, you'll learn more about the Tycho Client and the streamed data models.

Key Features

• Real-Time Streaming: Get low-latency updates to stay in sync with the latest protocol changes. Discover new pools as they’re created.

• TVL Filtering: Receive updates only for pools exceeding a specified TVL threshold (denominated in the Chain's Native Token).

• Support for multiple protocols and chains

Available Clients

The client is written in Rust and available as:

Follow one of the guides above to learn how to set up the client appropriate for you.

We welcome community contributions to expand language support. See our contribution guidelines .

Authentication

Currently, interacting with the hosted Tycho Indexer doesn't require a personalized API Key; you can use the key sampletoken. For broader rate-limiting, priority support, and access to new products, please contact @tanay_j on Telegram.

Usage

Tycho Client provides a stream of protocol components, snapshots, their state changes, and associated tokens. For simplicity, we will use Tycho Client Binary as a reference, but the parameters described below are also available for our Rust and Python versions.

Component Filtering

You can request individual pools or use a minimum TVL threshold to filter the components. If you choose minimum TVL tracking, Tycho-client will automatically add snapshots for any components that exceed the TVL threshold, e.g., because more liquidity was provided. It will also notify you and remove any components that fall below the TVL threshold. Note that the TVL values are estimates intended solely for filtering the most relevant components.

TVL Filtering:

TVL is measured in the chain's native currency (e.g., 1 00 ETH on Ethereum Mainnet).

You can filter by TVL in 2 ways:

1. Set an exact TVL boundary:

This will stream updates for all components whose TVL exceeds the minimum threshold set. Note: if a pool fluctuates in TVL close to this boundary, the client will emit a message to add/remove that pool every time it crosses that boundary. To mitigate this, please use the ranged tv boundary described below.

1. Set a ranged TVL boundary (recommended):

This will stream state updates for all components whose TVL exceeds the add-tvl-threshold. It will continue to track already added components if they drop below the add-tvl-threshold, only emitting a message to remove them if they drop below remove-tvl-threshold.

Understanding Tycho Client Messages

Tycho emits data in an easy-to-read JSON format. Get granular updates on each block:

• Snapshots for complete component (or pool) states,

• Deltas for specific updates, and

• Removal notices for components that no longer match your filtration criteria.

• Extractor status for keeping track of the sync status of each extractor.

Each message includes block details to help you stay on track with the latest block data.

FeedMessage

The main outer message type. It contains both the individual SynchronizerState (one per extractor) and the StateSyncMessage (also one per extractor). Each extractor is supposed to emit one message per block (even if no changes happened in that block) and metadata about the extractor's block synchronization state. The latter allows consumers to handle delayed extractors gracefully.

SynchronizerState (sync_states)

This struct contains metadata about the extractor's block synchronization state. It allows consumers to handle delayed extractors gracefully. Extractors can have any of the following states:

• Ready: the extractor is in sync with the expected block

• Advanced: the extractor is ahead of the expected block

• Delayed: the extractor has fallen behind on recent blocks but is still active and trying to catch up

• Stale: the extractor has made no progress for a significant amount of time and is flagged to be deactivated

• Ended: the synchronizer has ended, usually due to a termination or an error

StateSyncMessage (state_msgs )

This struct, as the name states, serves to synchronize the state of any consumer to be up-to-date with the blockchain.

The attributes of this struct include the header (block information), snapshots, deltas, and removed components.

• Snapshots are provided for any components that have NOT been observed yet by the client. A snapshot contains the entire state at the header.

• Deltas contain state updates observed after or at the snapshot. Any components mentioned in the snapshots and deltas within the same StateSynchronization message must have the deltas applied to their snapshot to arrive at a correct state for the current header.

• Removed components is a map of components that should be removed by consumers. Any components mentioned here will not appear in any further messages/updates.

Snapshots

Snapshots are simple messages that contain the complete state of a component (ComponentWithState) along with the related contract data (ResponseAccount). Contract data is only emitted for protocols that require vm simulations, it is omitted for protocols implemented natively (like UniswapV2 - see the list of and how they're implemented).

Snapshots are only emitted once per protocol, upon the client's startup. All the state is updated later via deltas from the next block onwards.

ComponentWithState

Tycho differentiates between component and component state.

The component itself is static: it describes, for example, which tokens are involved or how much fees are charged (if this value is static).

The component state is dynamic: it contains attributes that can change at any block, such as reserves, balances, etc.

ResponseAccount

This contains all contract data needed to perform simulations. This includes the contract address, code, storage slots, native balance, account balances, etc.

Deltas

Deltas contain only targeted changes to the component state. They are designed to be lightweight and always contain absolute new values. They will never contain delta values so that clients have an easy time updating their internal state.

Deltas include the following few special attributes:

• state_updates: Includes attribute changes, given as a component to state key-value mapping, with keys being strings and values being bytes. The attributes provided are protocol-specific. Tycho occasionally makes use of reserved attributes, see for more details.

• account_updates: Includes contract storage changes given as a contract storage key-value mapping for each involved contract address. Here, both keys and values are bytes.

• new_protocol_components: Components that were created on this block. Must not necessarily pass the tvl filter to appear here.

• deleted_protocol_components: Any components mentioned here have been removed from the protocol and are not available anymore.

• new_tokens: Token metadata of all newly created components.

• component_balances: Balances changes are emitted for every tracked protocol component.

• component_tvl: If there was a balance change in a tracked component, the new tvl for the component is emitted.

• account_balances: For protocols that need the balance (both native and ERC-20) of accounts tracked for the simulation package (like BalancerV3 which needs the Vault balances), the updated balances are emitted.

Note: exact byte encoding might differ depending on the protocol, but as a general guideline integers are big-endian encoded.

To integrate a new protocol into Tycho, you need to implement two key components:

1. SwapEncoder (Rust struct) – Handles swap encoding.

2. Executor (Solidity contract) – Executes the swap on-chain.

See more about our code architecture .

Main Encoder Interface

Each new protocol requires a dedicated SwapEncoder that implements the SwapEncoder trait. This trait defines how swaps for the protocol are encoded into calldata.

This function encodes a swap and its relevant context information into calldata that is compatible with the Executor contract. The output of the SwapEncoder is the input of the Executor (see next section). See current implementations .

If your protocol needs some specific constant addresses please add them in .

After implementing your SwapEncoder , you need to:

• Add your protocol with a placeholder address in: and

• Add your protocol in the .

Main Swap Interface

Every integrated protocol requires its own swap executor contract. This contract must conform to the IExecutor interface, allowing it to interact with the protocol and perform swaps be leveraging the RestrictTransferFrom contract. See currently implemented executors .

The IExecutor interface has the main method:

This function:

• Accepts the input amount (givenAmount). Note that the input amount is calculated at execution time and not during encoding. This is to account for possible slippage.

• Processes the swap using the provided calldata (data) which is the output of the SwapEncoder.

• Returns the final output amount (calculatedAmount).

Ensure that the implementation supports transferring received tokens to a designated receiver address, either within the swap function or through an additional transfer step.

If the protocol requires token approvals (allowances) before swaps can occur, manage these approvals within the implementation to ensure smooth execution of the swap.

Callbacks

Some protocols require a callback during swap execution. In these cases, the executor contract must inherit from and implement the necessary callback functions.

Required Methods

• handleCallback: The main entry point for handling callbacks.

• verifyCallback: Should be called within handleCallback to ensure that the msg.sender is a valid pool from the expected protocol.

Token Transfers

The Executor contracts manage token transfers between the user, protocols, and the Tycho Router. The only exception is when unwrapping WETH to ETH after a swap—in this case, the router performs the final transfer to the receiver.

The TychoRouter architecture optimizes token transfers and reduces gas costs during both single and sequential swaps. Whenever possible:

• The executor transfers input tokens directly from the user to the target protocol.

• The executor instructs the protocol to send output tokens directly to the next protocol in the swap sequence.

• For the final swap in a sequence, the protocol sends output tokens directly to the user.

Each executor must inherit from the RestrictTransferFrom contract, which enables flexible and safe transfer logic. During encoding, the executor receives instructions specifying one of the following transfer types:

Two key constants are used in encoding to configure protocol-specific behavior:

Include your protocol in these constants if necessary.

Testing

Each new integration must be thoroughly tested in both Rust and Solidity. This includes:

• Unit tests for the SwapEncoder in Rust

• Unit tests for the Executor in Solidity

• Two key integration tests to verify the full swap flow: SwapEncoder to Executor integration test and a full TychoRouter integration test

1. SwapEncoder ↔ Executor integration test

Verify that the calldata generated by the SwapEncoder is accepted by the corresponding Executor.

Use the helper functions:

• write_calldata_to_file() in the encoding module (Rust)

• loadCallDataFromFile() in the execution module (Solidity)

These helpers save and load the calldata to/from calldata.txt.

2. Full TychoRouter Integration Test

• In tests/protocol_integration_tests.rs, write a Rust test that encodes a single swap and saves the calldata using write_calldata_to_file().

• In TychoRouterTestSetup, deploy your new executor and add it to executors list in deployExecutors.

• Run the setup to retrieve your executor’s deployed address and add it to .

• Create a new Solidity test contract that inherits from TychoRouterTestSetup. For example:

These tests ensure your integration works end-to-end within Tycho’s architecture.

Deploying and Whitelisting

Once your implementation is approved:

1. Deploy the executor contract on the appropriate network.

2. Contact us to whitelist the new executor address on our main router contract.

3. Update the configuration by adding the new executor address to executor_addresses.json and register the SwapEncoder within the SwapEncoderBuilder .

By following these steps, your protocol will be fully integrated with Tycho, enabling it to execute swaps seamlessly.

Tycho Indexer

Metrics