Quickstart

Swap via Fynd in minutes.

Integrate Fynd into your application in two steps.

To interact with live quotes directly in your terminal, go to swap CLI instead.

Prerequisites

• Tycho API key (set as TYCHO_API_KEY, get one here)

• Rust 1.92+ (install via rustup) or Docker (install Docker)

Step 0 — Start Fynd

cargo install

cargo install fynd
export TYCHO_API_KEY=your-api-key
export RUST_LOG=fynd=info
fynd serve

Docker

Images are available for linux/amd64 and linux/arm64.

docker run \
  -e TYCHO_API_KEY=your-api-key \
  -e RUST_LOG=fynd=info \
  -p 3000:3000 -p 9898:9898 \
  ghcr.io/propeller-heads/fynd serve

Build from source

git clone https://github.com/propeller-heads/fynd.git
cd fynd
cargo install --locked --path .
export TYCHO_API_KEY=your-api-key
export RUST_LOG=fynd=info
fynd serve

Select a chain

Each Fynd instance serves a single chain. fynd serve defaults to Ethereum; pass --chain to target another one:

fynd serve --chain base

For Docker, append the flag after serve:

docker run \
  -e TYCHO_API_KEY=your-api-key \
  -e RUST_LOG=fynd=info \
  -p 3000:3000 -p 9898:9898 \
  ghcr.io/propeller-heads/fynd serve --chain base

Supported chain names are case-insensitive: ethereum, base, unichain, bsc, arbitrum, polygon, robinhood. The first six ship with built-in Tycho and RPC endpoints. For Robinhood Chain, pass --tycho-url and --rpc-url explicitly.

Your client must target the same chain. If you use the TypeScript client (Step 1), set chainId and the viem chain to match the server:

import { base } from 'viem/chains';

const publicClient = createPublicClient({ chain: base, transport: http(rpcUrl) });
const client = new FyndClient({ baseUrl: FYND_URL, chainId: base.id, /* ... */ });

Step 1 — Execute a swap

Fynd currently only supports sell orders (exact input). Set "side": "sell" in your order. Buy orders (exact output) are not yet supported.

TypeScript

Full example: clients/typescript/examples/tutorial/main.ts

Install the @kayibal/fynd-client package:

npm install @kayibal/fynd-client

const client = new FyndClient({
  baseUrl: FYND_URL,
  sender: account.address,
  provider: viemProvider(publicClient),
  fetchRevertReason: true,
});

// 1. Quote
const quote = await client.quote({
  order: { tokenIn: WETH, tokenOut: USDC, amount: SELL_AMOUNT, side: 'sell', sender: account.address },
  options: { encodingOptions: encodingOptions(0.005) },
});
console.log(`amount_out: ${quote.amountOut}`);

// 2. Approve if needed (checks on-chain allowance, skips if sufficient)
const approvalPayload = await client.approval({ token: WETH, amount: SELL_AMOUNT, checkAllowance: true });
if (approvalPayload !== null) {
  const sig = await account.sign({ hash: approvalSigningHash(approvalPayload) });
  await client.executeApproval({ tx: approvalPayload.tx, signature: sig });
}

// 3. Sign and execute swap
const payload = await client.swapPayload(quote);
const sig = await account.sign({ hash: swapSigningHash(payload) });
const settled = await (await client.executeSwap(assembleSignedSwap(payload, sig))).settle();
console.log(`settled: ${settled.settledAmount}, gas: ${settled.gasCost}`);

Rust

Full example: clients/rust/examples/swap_erc20.rs

Add the fynd-client crate to your Cargo.toml:

cargo add fynd-client

let client = FyndClientBuilder::new(FYND_URL)
    .with_rpc_url(RPC_URL)
    .with_sender(sender)
    .build()
    .await?;

// 1. Quote
let quote = client
    .quote(QuoteParams::new(
        Order::new(
            Bytes::copy_from_slice(sell_token.as_slice()),
            Bytes::copy_from_slice(buy_token.as_slice()),
            BigUint::from(SELL_AMOUNT),
            OrderSide::Sell,
            Bytes::copy_from_slice(sender.as_slice()),
            None,
        ),
        QuoteOptions::default()
            .with_timeout_ms(5_000)
            .with_encoding_options(EncodingOptions::new(SLIPPAGE)),
    ))
    .await?;
println!("amount_out: {}", quote.amount_out());

// 2. Approve if needed (checks on-chain allowance, skips if sufficient)
if let Some(approval_payload) = client
    .approval(
        &ApprovalParams::new(
            Bytes::copy_from_slice(sell_token.as_slice()),
            BigUint::from(SELL_AMOUNT),
            true,
        ),
        &SigningHints::default(),
    )
    .await?
{
    let sig = signer.sign_hash(&approval_payload.signing_hash()).await?;
    client
        .execute_approval(SignedApproval::assemble(approval_payload, sig))
        .await?
        .await?;
}

// 3. Sign and execute swap
let payload = client.swap_payload(quote, &SigningHints::default()).await?;
let sig = signer.sign_hash(&payload.signing_hash()).await?;
let receipt = client
    .execute_swap(SignedSwap::assemble(payload, sig), &ExecutionOptions::default())
    .await?
    .await?;
println!("gas: {}", receipt.gas_cost());

curl

# Wait until healthy
curl http://localhost:3000/v1/health
# → {"healthy":true,...}

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

This quotes 1000 USDC (6 decimals → 1 000 000 000 atomic units) for WETH.

Native ETH swaps

To swap native ETH, use 0x0000...0000 as the token_in or token_out address in your order.

Next steps

• Encoding options - encode quotes into ready-to-submit transactions

• Fynd Fees - understand Fynd fees on executed swaps

• Charge Fees on your Swaps - charge integrator fees on swaps

• Server configuration

• Custom algorithm

• Benchmarking

• Swap CLI