Once you have calldata from Encoding, you can execute your trade via the Tycho Router.

Tycho Router

Send the encoded calldata to the TychoRouterV3 contract (see contract addresses here). Preparation depends on the user_transfer_type in your Solution:

• TransferFrom: Call approve() on your input token to allow the TychoRouterV3 to spend it.

• TransferFromPermit2: Approve the Permit2 contract - use the Permit2 utility from the encoding crate to build and sign the PermitSingle. You must handle the permit; the encoder does not.

• UseVaultsFunds: No approval needed — the router draws from your vault balance. Deposit sufficient funds into the vault before swapping.

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

The TychoRouterV3 supports a dual fee system:

• Client fees: Construct a ClientFeeParams with your client_fee_bps, client_fee_receiver, and signature, and pass it when calling the router. Fees are credited to the receiver's vault balance.

• Router fees: Configured on-chain by Propeller Heads. These are mandatory and cannot be bypassed through encoding. The router can charge a fee on the output amount and/or a percentage of the client fee. Currently set to 0.1 bps (0.001%) on the swap output and 20% share of the client fee (the integrator keeps 80%).

All fee rates — yours and the router's — use 8-decimal fee units where 100_000_000 = 100%. See .

Fees apply to the output your swap actually produced, never to your quote. When the router captures positive slippage, it subtracts that surplus first and charges fees on what remains. If the fees would exceed the output altogether, the swap reverts with TychoRouter__FeesExceedOutput.

Positive slippage capture is a single on-chain switch on the FeeCalculator, and Propeller Heads can exempt individual client addresses from it. An exempt client's swaps keep the whole surplus above expectedAmountOut. The router resolves which client applies the same way it resolves fee rates: from clientFeeReceiver when you pass a signed one, otherwise from tx.origin.

Propeller Heads can configure a custom router fee rate for specific client addresses. If your address has a negotiated rate, the router applies it automatically — no extra configuration required on your end.

When you call the router without a clientFeeReceiver (i.e., passing all-zero ClientFeeParams), the router looks up custom fee rates using tx.origin. This means your negotiated rate applies to any transaction you originate, even when no client signature is present. When a clientFeeReceiver is provided, the signed address takes precedence over tx.origin for the fee lookup.

If the swap output falls below minAmountOut, the router covers the shortfall from the client's vault balance, up to max_client_contribution. Beyond that, the transaction reverts with TychoRouter__NegativeSlippage. This lets clients absorb minor slippage without a separate transaction — but set max_client_contribution conservatively, as a high value can expose you to MEV attacks.

A contribution requires a signed ClientFeeParams: the router rejects a non-zero maxClientContribution when clientFeeReceiver is the zero address.

The contribution comes out of the client's own vault balance, so clientFeeReceiver has to be an address that can both hold a balance and sign. Either an EOA or a contract qualifies: the router recovers an ECDSA signature first and falls back to an check, so a Safe can act as the client. Deposit the contribution into that address's vault balance before the swap — see .

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.

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

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.

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.

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

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

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 – our telegram group for Tycho builders.

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

Tycho Fellows are Solvers, Searchers, and Market Makers who work with the Propeller Foundation to bring all DeFi liquidity (across chains, pools, and tokens) to all traders.

For Solvers & Searchers

Benefits as a Tycho Fellow

• Early Access to DEXs: Be first to access new DEXs on our development endpoint before they goes live in production.

• Shape the future of Tycho: Give input and prioritize new features.

Requirements

As a Tycho Fellow, you need to:

• Integrate new DEXs: Test and integrate new DEXs as soon as they are live.

• Settle Volume on Tycho: Settle more than > 1mio / week on Tycho Router.

If you want to become a Tycho Fellow please contact @tanay_j on Telegram.

Tycho Fellows can connect your DEX to most orderflow in defi.

For DEXs: Tycho Fellows integrate with all orderflow auctions and can quickly connect your DEX to most defi orderflow.

For Auctions: Tycho Fellows can serve as a competitive and diverse set of solvers in your auction. Get top quotes, competitive solutions, and optimize revenue from day 0.

For Chains: Help bring orderflow auctions and their users to your chain with the help of the solvers that power them.

Write us (@tanay_j on tg) before you launch and we'll help you start ahead.

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.

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 . Note that a single transaction may create multiple components. In such cases,

Tycho's source code is public on . You can inspect, run, and modify it.

• Tycho releases before 0.435.0: we released these versions under the MIT License, and they stay under it.

• Tycho 0.435.0 and later: we release these versions under the . Settlements that use Tycho must execute through the . Revenue you earn from settlements or services that use Tycho, including solver rewards, carries a 20% revenue share. Using Tycho internally, offering it for free, or trading with your own capital does not by itself trigger a revenue share.

lists which license covers which files. For a custom license, contact legal@propellerheads.xyz.

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

• 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 Rust. You can do so with the following command:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Install Substreams

You can do so with any of the following:

Using Homebrew:

brew install streamingfast/tap/substreams

Using precompiled binaries

# Use correct binary for your platform
LINK=$(curl -s https://api.github.com/repos/streamingfast/substreams/releases/latest | awk '/download.url.*linux/ {print $2}' | sed 's/"//g')
curl -L  $LINK  | tar zxf -

Compiling from source:

git clone https://github.com/streamingfast/substreams
cd substreams
go install -v ./cmd/substreams

Install Buf

Using Homebrew:

brew install bufbuild/buf/buf

For other installation methods, see the official buf website\

Fork the monorepo

1. Start by making a fork of the Tycho monorepo repository

2. Clone the fork you just created

3. Make sure everything compiles fine

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:

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.

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

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:

Install foudryup and foundry

For security purposes, new Executors must have:

• No ERC20 token transfers

Tycho is a source-available 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

The following diagram summarizes the code architecture:

The TychoRouterEncoder validates solutions and produces a list of transactions to execute against the TychoRouterV3.

The TychoRouterEncoder chooses a strategy encoder automatically based on the solution (see more about strategies ).

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

The TychoRouterV3

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

• Cargo

• Rust 1.84.0 or later

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 .

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:

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

Step 4: Verify Installation

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

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

or use the command line flag

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:

Or skip secure connections entirely with --no-tls for local setups.

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-folder option.

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

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

When the Tycho server or one of its extractors restarts, every client reconnects at the same moment. To spread the load, the client waits a random time between 0 and --snapshot-jitter seconds before it requests a new snapshot. The client discards deltas during the wait and takes the snapshot at the next block. The default is 60 seconds and the minimum is 5 seconds.

The first start has no delay. A restart that continues from the next expected block, or a stream with --no-state, requests no snapshot and has no delay. To shorten the wait, set a lower value:

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.

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 protocols/substreams/Cargo.toml.

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 '

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

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.

Tycho Execution provides tools for encoding and executing swaps against Tycho Router 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 lives at crates/tycho-execution inside the Tycho monorepo. For a practical example of its usage, please refer to our Quickstart.

Token transfers

You can transfer tokens in one of three ways with Tycho Execution:

• Permit2

• Standard ERC20 Approvals

• Using Vault funds

See how to change between these options when encoding .

Tycho Execution supports 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.

Permit2 handling is not part of the encoding step. You are responsible for creating and signing the permit yourself. The Permit2 utility struct is publicly exported from the encoding crate, so you can use it to build the PermitSingle and obtain the data needed for signing.

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

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.

The TychoRouterV3 includes a built-in vault () that lets you deposit, hold, and withdraw tokens directly in the router contract. The vault tracks per-user balances, so your tokens are only accessible by you.

The router draws from your deposited balance instead of performing a transferFrom on your wallet. This saves gas (no approval or external transfer needed) and lets you use fees, proceeds from previous trades, or pre-positioned liquidity directly.

Fees earned through the fee-taking system are automatically credited to the fee receiver's vault balance, making them immediately available for future swaps or withdrawals.

More on the Vault .

The Tycho Router V2 and V3 have been audited by . Past audits are .

Follow this checklist when using TychoRouterV3. It covers essential security requirements but is not exhaustive.

• Always set expectedAmountOut and minAmountOut on TychoRouterV3's swap... functions. expectedAmountOut is your quoted output; minAmountOut is the amount below which the swap reverts.

  • Example: if you expect 1000 USDC and accept 5% slippage, set expectedAmountOut

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

Cow Protocol

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

First, initialize the encoder:

let swap_encoder_registry = SwapEncoderRegistry::new_with_defaults(Chain::Ethereum)
    .expect("Failed to get default SwapEncoderRegistry");

let encoder = TychoRouterEncoderBuilder::new()
    .chain(Chain::Ethereum)
    .swap_encoder_registry(swap_encoder_registry)
    .build()
    .expect("Failed to build encoder");

When solving for CoW Protocol, you need to return a Solution object 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.

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 TychoRouterV3 from reactorCallback to execute swaps

See how to encode the callbackData for TychoRouterV3 .

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

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

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=crates/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 for real-time data streaming

• RPC Client: Pure Python implementation for querying data

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:

Here's one example on how to use it:

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 endpoint):

The TychoRouterV3 includes an integrated vault built on the ERC6909 multi-token standard. This replaces the "direct transfer" pattern from V2, where tokens sent to the router risked being lost.

How It Works

The vault uses dual storage:

• Transient storage tracks balance changes ("deltas") during a swap. Credits are recorded when tokens arrive at the router; debits when they leave. This is cheap (~100 gas per operation) and automatically clears at the end of each transaction.

• Persistent storage (ERC6909 balances) holds final user balances across transactions. These are updated only after a swap is fully validated.

At the end of every swap, _finalizeBalances validates the transient state before committing:

• For wallet-funded swaps: all deltas must net to zero.

• For vault-funded swaps: at most one negative delta is allowed (the input token), which is burned from the user's vault balance.

This catches encoding errors and balance mismatches before any persistent state changes.

Tokens in the vault can be used for swaps by setting user_transfer_type: UseVaultsFunds in the . They can be withdrawn at any time.

By default, output tokens are sent to the receiver address after a swap. If you set the receiver to the TychoRouterV3 address, the output tokens are credited to the caller's vault balance instead of transferred out.

This works with all swap types — single, sequential, and split — and with both wallet-funded and vault-funded swaps.

This enables vault rebalancing: converting one token to another without tokens leaving the contract. For example, a solver holding WETH in the vault can convert it to USDC in a single transaction, with both the debit and credit happening within the vault.

It also supports cyclical arbitrage, where you route through multiple pools and end up with more of the starting token, all settled within the vault.

The vault serves three purposes:

1. Gas savings. Keep tokens in the contract to avoid repeated approvals and transfer costs across swaps.

2. In-contract rebalancing. Convert between tokens without ERC-20 transfers or approvals — input and output settle entirely within the router.

3. Fee accounting. Fees are credited with a storage write rather than an ERC-20 transfer, saving gas at fee-taking time.

• Vault balances are scoped per user. Only the owner can use their funds (via msg.sender or signature checks). This is enforced at the contract level and cannot be overridden through encoding.

• Output tokens credited to the vault always go to msg.sender, not to the receiver parameter. This prevents a malicious encoder from redirecting output into another user's vault.

• Tokens sent to the router without calling deposit() are considered lost. The vault does not credit balances from raw transfers.

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:

use tycho_substreams::contract::extract_contract_changes;

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

extract_contract_changes(
    &block,
    |addr| {
        components_store
            .get_last(format!("pool:{0}", hex::encode(addr)))
            .is_some()
    },
    &mut transaction_changes,
);

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:

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 Tycho Client. 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 Tycho RPC's Tycho RPCendpoint. 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

• 9-5: Token analysis kept failing on re-analysis after creation; 5 is the floor

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

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

Integrate here if your venue prices off the chain: instead of pool state Tycho reads from the chain, you publish a complete book — the price levels you will trade at — over a WebSocket or an API. Two kinds share that shape: RFQ market makers, who price indicatively and sign a binding quote at execution (Bebop, Hashflow, Liquorice, Native), and off-chain-priced pAMMs, whose book prices a pool a taker executes against directly, with nothing to sign (Metric). Tycho stamps your components rfq:<venue>.

You implement a feed, a client, a state, and the logic to encode and execute trades.

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

We recommend using the existing Bebop integration as a reference for an RFQ venue, and Metric for a pAMM.

Each venue needs a feed type (e.g. BebopFeed) implementing the generic SnapshotFeed trait (tycho_simulation::snapshot_feed

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.

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:

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

• [VM implementations]

Address Convention

Tycho reserves the zero address (0x0000000000000000000000000000000000000000) to represent the native token across all chains.

Some protocols use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE or other sentinel addresses for native tokens. If your protocol follows this pattern, you must normalize these addresses to the zero address in your Substreams package.

Swap/Exchange Protocol Guide

Implementing the Protocol

To integrate an EVM exchange protocol:

1. Implement the ISwapAdapter.sol 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:

yamlCopy# Author information helps us reach out in case of issues
author:
  name: Propellerheads.xyz
  email: alan@propellerheads.xyz

# Protocol Constants
constants:
  # Minimum gas usage for a swap, excluding token transfers
  protocol_gas: 30000
  # Minimum expected capabilities (individual pools may extend these)
  # To learn about Capabilities, see ISwapAdapter.sol)
  capabilities:
    - SellSide
    - BuySide
    - PriceFunction

# Adapter contract (byte)code files
contract: 
  # Contract runtime (deployed) bytecode (required if no source is provided)
  runtime: UniswapV2SwapAdapter.bin
  # Source code (our CI can generate bytecode if you submit this)
  source: UniswapV2SwapAdapter.sol

# Deployment instances for chain-specific bytecode
# Used by the runtime bytecode build script
instances:
  - chain:
      name: mainnet
      id: 1
    # Constructor arguments for building the contract
    arguments:
      - "0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f"

# Automatic test cases (useful if getPoolIds and getTokens aren't implemented)
tests:
  instances:
    - pool_id: "0xB4e16d0168e52d35CaCD2c6185b44281Ec28C9Dc"
      sell_token: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
      buy_token: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
      block: 17000000
      chain:
        name: mainnet
        id: 1

Key Functions

Price (optional)

Calculates marginal prices for specified amounts.

function price(
    bytes32 poolId,
    IERC20 sellToken,
    IERC20 buyToken,
    uint256[] memory sellAmounts
) external returns (Fraction[] memory prices);

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

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).

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.

Retrieves pool capabilities.

Retrieves tokens for a given pool.

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

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.

This outlines the core entities and components that form the foundation of the Tycho system. Understanding these concepts is essential for working with or on the application effectively.

Entities

ProtocolSystem

With ProtocolSystems we usually refer to a DeFi protocol. A group of smart contracts that work collectively provide financial services to users. Each protocol typically contains:

• A single Extractor (see below)

• One or more ProtocolComponents

We model major versions of protocols as distinct entities. For example, Uniswap V2 and Uniswap V3 are separate ProtocolSystems.

Attributes:

• name: The protocols' identifier

• protocol_type: The category of protocol being indexed, currently pure organisational use.

  • name: The identifier of the protocol type

  • financial_type: The specific financial service provided:

Tokens represent fungible tradeable assets on a blockchain. Users interact with protocols primarily to buy, sell, or provide liquidity for tokens. While ERC20 is the most common standard, Tycho supports other token types as well.

Tycho automatically detects and ingests new tokens when a ProtocolComponent using that token is ingested in the DB. Upon detection, we run test transactions to determine the token's behavior.

Attributes:

• Address: The blockchain address that uniquely identifies the token

• Decimals: Number of decimal places used to represent token values

• Symbol: Short human-readable identifier (e.g., ETH, USDC)

• Tax: Token transfer tax in basis points, averaged across simulated transfers

ProtocolComponents represent specific operations that can be executed on token sets within a ProtocolSystem. Examples include liquidity pools in DEXes or lending markets in lending protocols.

A new ProtocolComponent is created whenever a new operation becomes available for a set of tokens such as when a new trading pair is deployed on a DEX.

Attributes:

• id: A unique identifier for the component

• protocol_system: The parent protocol system

• protocol_type_name: Subtype classification for filtering components

• chain: Blockchain where the component operates

Each component also has dynamic attributes that change over time and contain state required to simulate operations.

The indexer subsystem processes blockchain data, maintains an up-to-date representation of entities and provides RPC and Websocket endpoints exposing those entities to clients.

An Extractor processes incoming blockchain data, either at the block level or at shorter intervals (e.g. mempool data or partial blocks from builders).

The Extractor:

1. Pushes finalized state changes to permanent storage

2. Stores unfinalized data in system buffers (see ReorgBuffers below)

3. Performs basic validation, such as checking for the existence of related entities and verifying the connectedness of incoming data

4. Aggregates processed changes and broadcasts them to connected clients

Tycho's persistence layer tracks state changes at the transaction level. This granular versioning enables future use cases such as:

• Replay changes transaction by transaction for backtesting

• Historical analysis of protocol behavior

The default storage backend (PostgreSQL) maintains versioned data up to a configurable time horizon. Older changes are pruned to conserve storage space and maintain query performance.

ReorgBuffers store unfinalized blockchain state changes that haven't yet reached sufficient confirmation depth.

This approach allows Tycho to:

1. Respond to queries with the latest state by merging buffer data with permanent storage

2. Handle chain reorganizations by rolling back unconfirmed changes

3. Send precise correction messages to clients when previously reported states are invalidated

When a reorganization occurs, the system uses these buffers to calculate exactly what data needs correction, minimizing disruption to connected applications.

The DCI is an extractor extension designed to dynamically identify and index dependency contracts based on supplied tracing information. The DCI relies on an integrated protocol to provide the information with which it can analyse and detect contracts that require indexing.

On a successful trace, the DCI identifies all external contracts that were called, which storage slots were accessed for those contracts, and potential retriggers for the entry point. A retrigger is any contract storage slot that is flagged for its potential to influence a trace result. If a retrigger slot is updated, the trace is repeated. For all identified contracts, the code and relevant storage is fetched at the current block. Thereafter, updates for those contracts are extracted from the block messages themselves.

The simulation library allows clients to locally compute the outcome of potential operations without executing them on-chain, enabling efficient price discovery and impact analysis.

Tycho offers two approaches for simulating protocol operations:

Virtual Machine (VM) Integration

• Uses the blockchain's VM to execute operations

• Requires a contract that adapts the protocol's interface to Tycho's interface

• Creates a minimal local blockchain view with only the necessary contract state

• Advantages:

Native Implementation

• Reimplements protocol operations directly in Rust code

• Compiles to optimized machine code for the target architecture

• May still access the VM if required, e.g. to simulate Uniswap V4 hooks

• Advantages:

The Solution represents a complete pathway for moving tokens through one or more protocols to fulfil a trade. It bridges the gap between finding the best trade route and actually executing it on-chain.

Solutions can represent single-hop swaps, sequential multi-hop trades, or split routes where a token amount is distributed across multiple pools. See more about Solutions .

Strategies define how Solutions are translated into Transactions, offering different tradeoffs between complexity, gas efficiency, and security. They encapsulate the logic for how trades should be executed on-chain.

Tycho currently supports three distinct strategies for executing trades: Single, Sequential, and Split.

Before diving into these, it is useful to clarify a few terms:

• Solution / Trade: A complete plan to exchange token A for token B. This may involve routing through intermediate tokens, but it is conceptually treated as a single trade.

• Swap/Hop: An individual exchange between two tokens. A trade may consist of one or more swaps.

The encoder uses the single strategy when a Solution has exactly one swap on one pool.

The encoder uses the sequential strategy when your Solution has multiple sequential swaps, and no splits (e.g. A → B → C). Outputs from one are equal to the input to the next swap.

With the Split strategy, you can encode the most advanced solutions: Trades that involve multiple swaps, where you split amounts either in parallel paths or within stages of a multi-hop route.

For more about split swaps, see .

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 Protocol Simulation 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).

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

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.

Setting up using Tycho is simple with the .

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

The contains everything you need to integrate liquidity layer protocols (DEXs, Staking, Lending, etc.) into Tycho.

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.

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:

[dependencies]
tycho-client = "x.y.z"
tycho-common = "x.y.z"

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("your-api-key".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);
    }
}

Snapshot jitter

When the Tycho server or one of its extractors restarts, every client restarts its synchronizers at the same moment. To spread the load, a restarted synchronizer waits a random time in [0, jitter] before it requests a new snapshot. It discards deltas during the wait and takes the snapshot at the next block. The first start has no delay. A restart that continues from the next expected block, or a stream with no_state(true), requests no snapshot and has no delay.

The default jitter is 60 seconds. Use snapshot_jitter on the builder to change it. The client raises a value below 5 seconds to 5 seconds:

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

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.

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

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 ).

Tycho Indexer

Tycho Fynd endpoints are dedicated instances for Fynd users. They enforce stricter data filtering restrictions to support higher load.

Each API key is assigned a plan that determines rate limits and endpoint access.

Endpoints enforce data filtering restrictions on API queries. When a restriction is active, requests that do not include the required parameter values are rejected.

All Fynd endpoints share the same filtering restrictions:

The available protocol systems vary by chain:

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

The crate lives at crates/tycho-simulation inside the Tycho monorepo.

Installation

The tycho-simulation package is available on crates.io.

Add it to your project's Cargo.toml:

tycho-simulation = "x.y.z"

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.

get_amount_out simulates token swaps.

You receive a GetAmountOutResult , which is defined as follows:

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

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

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

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

query_pool_swap returns the swap volume that achieves a price goal on the pool, together with the pool's state after that swap.

The SwapConstraint you pass in QueryPoolSwapParams sets the goal:

• SwapConstraint::TradeLimitPrice — maximise the trade while keeping amount_out / amount_in at or above a limit price.

• SwapConstraint::PoolTargetPrice — move the pool's marginal price down to a target price.

Both variants take a tolerance fraction that loosens the search, and optional min_amount_in / max_amount_in bounds. Prices use token_out (numerator) per token_in (denominator), net of all fees.

Price represents a price as a rational fraction (numerator / denominator).

PoolSwap holds the resulting trade, read through its accessors:

price_points are the points on the price curve the search passed through. Reuse them as bounds for subsequent searches on the same pool.

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

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:

Collect token metadata up front and pass it to the stream builder in step 2. This token set is used to decode startup snapshots and initialize protocol states correctly. To simplify this, a util function called load_all_tokens is supplied and can be used as follows:

You can use the 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:

set_tokens(...) does not act as an ongoing stream filter. New snapshots/components streamed later include the token metadata required for decoding.

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.

ProtocolStreamBuilder applies a curated blocklist of pools that are known to break simulation (for example, rebasing-token and insolvent pools) by default, so the stream excludes them automatically. To exclude additional components, pass their IDs to blocklist_components(...).

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)

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.

If you want to restrict processing to specific tokens (for example USDC/WETH only), apply that filter in your own consumer logic when reading new_pairs and states.

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 .

Some chains, such as , support flash blocks — pre-confirmation updates that contain parts of a future block before its construction is finished. Enable this on your stream to receive sub-block latency updates as they arrive. On chains without flash block support, enabling this flag is unsupported.

You can find an example of a price printer .

Clone the repo, then run:

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.

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.

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.

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

• address of the contract called

• signature of the function called on that contract

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.

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.

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

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.

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.

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.

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.

To enable simulations for a newly added protocol, it must first be integrated into the Tycho monorepo. Please submit a pull request to the repository targeting crates/tycho-simulation.

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 here).

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 crates/tycho-simulation/src/evm/protocol.

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

The following exchanges are integrated with the VM approach:

• Balancer V2 (see code )

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

   then start a new terminal session and run

2. Clone the Tycho monorepo:

3. Install dependencies:

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:

Your integration should be in a separate directory in the protocols/adapter-integration/evm/src folder. Start by copying the template directory:

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

1. Set up test files:

   • Copy evm/test/TemplateSwapAdapter.t.sol

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

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 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 crates/tycho-simulation/src/evm/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.

If your implementation does not support all pools indexed for a protocol, you can create a filter function to handle this. Add your filter to alongside the existing ones, and add your protocol name to the EXCHANGES_REQUIRING_FILTER constant in . This warns callers if they stream your protocol without providing the required filter.

The builds total execution gas from two components: the simulation-reported swap gas and token-transfer overhead that simulation does not capture. Which overhead applies depends on your protocol's behavior.

Your get_amount_out implementation must return a gas estimate. Measure only what happens inside the protocol's swap() call, including any token transfers that occur during a callback.

After implementing, add your protocol to the relevant constant slices in gas_estimator.rs:

• PROTOCOLS_CALLBACK: The pool pulls tokens inside a callback fired during swap(). The simulation captures that transfer, so the estimator adds no separate input-transfer cost.

• PROTOCOLS_OPTIMIZABLE_TRANSFER_IN: The router might send tokens directly to the pool, skipping the router-to-pool hop. The estimator adds no router-to-pool transfer cost for non-split strategies.

A protocol can appear in more than one list.

In your adapter contract's swap function, measure gas with gasleft() and return it in the Trade struct. The measurement must cover only the pool call itself.

Do not include gas for:

• Token transfers (input or output): the Dispatcher handles these via TransferManager

• approve() calls: also handled by the Dispatcher

Including them would double-count with what the gas estimator adds based on your protocol's category.

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.