Quickstart

Run Fynd

Get Fynd running locally. This guide covers building, running, and tuning the solver. No code changes required.

Prerequisites

• Rust 1.92+ (install via rustup)

• A Tycho API key (get one here)

1. Build

git clone https://github.com/propeller-heads/fynd.git
cd fynd
cargo build --release

The release binary will be at target/release/fynd.

2. Set Environment Variables

export TYCHO_API_KEY=your-api-key
export RUST_LOG=info

3. Run

All on-chain protocols are fetched from Tycho RPC by default, so --protocols is optional. The --tycho-url also defaults to the Fynd endpoint for the selected chain.

cargo run --release -- serve

To run on a different chain, use --chain:

cargo run --release -- serve --chain base

--rpc-url defaults to the public endpoint https://eth.llamarpc.com. For production, pass a dedicated endpoint:

cargo run --release -- serve \
  --rpc-url https://your-rpc-provider.com/v1/your_key

You can also specify protocols explicitly:

cargo run --release -- serve \
  --protocols uniswap_v2,uniswap_v3,vm:curve

See the full list of available protocols.

Once running, Fynd:

1. Connects to Tycho's Streams and syncs all protocol states

2. Builds routing graphs and computes derived data (spot prices, pool depths and token gas prices)

3. Starts the HTTP API on http://localhost:3000

Wait for the /v1/health endpoint to return healthy before sending orders.

3.1 Including RFQ Protocols

Include RFQ (Request-for-Quote) protocols alongside on-chain protocols. Use the all_onchain keyword to combine auto-fetched on-chain protocols with specific RFQ protocols:

cargo run --release -- serve \
  --protocols all_onchain,rfq:bebop

Or specify both on-chain and RFQ protocols explicitly:

cargo run --release -- serve \
  --protocols uniswap_v2,uniswap_v3,rfq:bebop

Limitations:

• RFQ protocols cannot run alone. At least one on-chain protocol is required.

Environment variables:

• RFQ protocols require API keys passed via environment variables. Check the RFQ protocol docs for the specific variables each protocol needs.

3.2 Check Solver Health

curl http://localhost:3000/v1/health

Returns "healthy":true when ready to receive requests.

4. Request a quote

Get the quote for 1 WETH -> USDC (or any pair/amount you want):

curl -X POST http://localhost:3000/v1/quote \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [
      {
        "token_in": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "token_out": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "amount": "1000000000000000000",
        "side": "sell",
        "sender": "0x0000000000000000000000000000000000000001"
      }
    ],
    "options": {
      "timeout_ms": 5000,
      "min_responses": 1
    }
  }'

The response includes the optimal route, amounts, gas estimates, and the net output after gas costs.

4.1 - Optional request fields

Field	Description
options.timeout_ms	Overrides the default solve timeout (configured via global config see configuration section).
options.min_responses	Return early after N solver pools respond. If set to null - it will wait for all solver pools respond until timeout.
options.max_gas	Discard routes above this gas limit

Full interface details: API Specifications

5. Configuration

Tune Fynd with the following flags:

Required

Flag	Env Var	Description
--tycho-api-key	TYCHO_API_KEY	Tycho API key

Optional

Flag	Env Var	Default	Description
--rpc-url	RPC_URL	https://eth.llamarpc.com	Ethereum RPC endpoint. Use a dedicated endpoint in production.
--tycho-url	TYCHO_URL	(chain-specific)	Tycho URL. Defaults to the Fynd endpoint for the selected chain (e.g. tycho-fynd-ethereum.propellerheads.xyz).
--chain	--	Ethereum	Target chain
-p, --protocols	--	(all on-chain)	Protocols to index (comma-separated). If omitted, all on-chain protocols are fetched from Tycho RPC. Use all_onchain to combine auto-fetched protocols with explicit entries (e.g. all_onchain,rfq:bebop).
--http-host	HTTP_HOST	0.0.0.0	HTTP bind address
--http-port	HTTP_PORT	3000	API port
--min-tvl	--	10.0	Minimum pool TVL in native token (ETH)
--tvl-buffer-ratio	--	1.1	Hysteresis buffer for TVL filtering. Components are added when TVL >= min_tvl and removed when TVL drops below min_tvl / tvl_buffer_ratio.
--traded-n-days-ago	--	3	Only include tokens traded within this many days.
--worker-router-timeout-ms	--	100	Default solve timeout (ms)
--worker-router-min-responses	--	0	Early return threshold (0 = wait for all pools)
-w, --worker-pools-config	WORKER_POOLS_CONFIG	worker_pools.toml	Worker pools config file path
--blacklist-config	BLACKLIST_CONFIG	blacklist.toml	Blacklist config file path
--disable-tls	--	false	Disable TLS for Tycho connection
--min-token-quality	--	100	Minimum token quality filter
--gas-refresh-interval-secs	--	30	Gas price refresh interval
--reconnect-delay-secs	--	5	Reconnect delay on connection failure
--gas-price-stale-threshold-secs	--	(disabled)	Health returns 503 when gas price exceeds this age. Disabled by default.

Run cargo run --release -- serve --help for the full list.

5.1 - Worker pools file (worker_pools.toml)

Worker pools control solver thread count and routing strategies. The default config ships with two pools:

# worker_pools.toml
[pools.most_liquid_2_hops_fast]
algorithm = "most_liquid"
num_workers = 5
task_queue_capacity = 1000
max_hops = 2
timeout_ms = 100

[pools.most_liquid_3_hops]
algorithm = "most_liquid"
num_workers = 3
task_queue_capacity = 1000
min_hops = 2
max_hops = 3
timeout_ms = 5000

Both pools solve every incoming order in parallel. Fynd picks the best result across pools within the timeout.

Worker Pool Configuration:

Field	Default	Description
algorithm	"most_liquid"	Algorithm used for the pool
num_workers	CPU count	Number of OS threads dedicated to this pool
task_queue_capacity	1000	Maximum number of orders that can be queued simultaneously
min_hops	1	Minimum number of hops required for routing
max_hops	3	Maximum number of hops permitted for routing
timeout_ms	100	Maximum time in milliseconds allowed per order processing in this pool
max_routes	(no limit)	Maximum number of candidate routes to evaluate per order

Tuning tips:

• More workers = more orders can be solved concurrently. Each worker is a dedicated OS thread, so avoid exceeding your CPU core count across all pools.

• Lower max_hops = faster solves but may miss better multi-hop routes.

• Higher max_hops = explores deeper routes but takes longer. Pair with a higher timeout_ms.

• The "fast + deep" pattern (default config) gives quick responses from the 2-hop pool while the 3-hop pool searches for better routes in the background.

To use a custom config file:

cargo run --release -- serve -w my_worker_pools.toml

5.2 Blacklist (blacklist.toml)

Exclude specific components from routing, useful for components with known simulation issues ( e.g., rebasing tokens on UniswapV3 pools):

[blacklist]
components = [
    "0x86d257cdb7bc9c0df10e84c8709697f92770b335",
]

6. Logging and Monitoring

Logs

Control log verbosity with RUST_LOG:

# Minimal output
RUST_LOG=warn cargo run --release -- serve ...

# Default (recommended)
RUST_LOG=info cargo run --release -- serve ...

# Debug solver internals
RUST_LOG=info,fynd_core=debug cargo run --release -- serve ...

# Trace-level (very verbose, not recommended)
RUST_LOG=info,fynd_core=trace cargo run --release -- serve ...

Prometheus Metrics

Metrics are exposed at http://localhost:9898/metrics (always on). Scrape this endpoint with Prometheus or any compatible tool. Available metrics: solve duration, response counts, failure types, and pool performance.

7. Validating and Executing the Solutions

With Fynd running, you can validate and execute swaps using fynd-swap-cli — a CLI binary included in the repository at tools/fynd-swap-cli/. It supports dry-run simulation (no funds or private key required) and on-chain execution.

See Executing the solutions for the full walkthrough.