How to add swaps to your app using Kuru Flow

Your application may need to allow users to swap between two assets. You want your users to get the best price available across the ecosystem. Aggregators check many liquidity sources and find the best price. Integrating an aggregator API can thus be a convenient and efficient means of enabling swapping in your app. In this guide, we will examine integrating one such aggregator, Kuru Flow. You’ll learn how to integrate Kuru Flow into a frontend application—from authentication to fetching quotes and executing swaps.

Requirements

Before you begin, ensure you have the following:

A frontend framework with wallet connection (React, Next.js, etc.)
wagmi and viem for wallet interactions
User wallet connected to Monad mainnet (chain ID 143)

1. Configure Authentication

We first need to get credentials to access the Kuru Flow API. Kuru Flow uses JWT tokens for API authentication.

lib/kuru-flow.ts

const KURU_FLOW_API = "https://ws.kuru.io";

async function generateToken(userAddress: string) {
  const response = await fetch(`${KURU_FLOW_API}/api/generate-token`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ user_address: userAddress }),
  });

  return response.json();
  // Returns: { token: string, expires_at: number, rate_limit: { rps: number, burst: number } }
}

2. Get a Swap Quote

The /api/quote endpoint calculates the best swap path and returns transaction data. The following parameters are supported:

Parameter	Required	Description
`userAddress`	Yes	User’s wallet address
`tokenIn`	Yes	Token address (`0x0` for native MON)
`tokenOut`	Yes	Token address (`0x0` for native MON)
`amount`	Yes	Amount in smallest token units
`autoSlippage`	No*	Set to `true` for automatic slippage calculation
`slippageTolerance`	No*	Manual slippage in basis points (1-10000)
`referrerAddress`	No	Your address to receive referral fees
`referrerFeeBps`	No	Referral fee in basis points (0-10000)

*Either autoSlippage: true OR slippageTolerance must be provided. We can write a small function to interact with the quote API:

lib/kuru-flow.ts

const KURU_FLOW_API = "https://ws.kuru.io";

// Your wallet address to receive referral fees
const REFERRER_ADDRESS = "0xYOUR_WALLET_ADDRESS_HERE";
const REFERRER_FEE_BPS = 50; // 0.5%

async function getQuote(
  userAddress: string,
  tokenIn: string,
  tokenOut: string,
  amount: string,
  token: string
) {
  const response = await fetch(`${KURU_FLOW_API}/api/quote`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({
      userAddress,
      tokenIn,
      tokenOut,
      amount,
      autoSlippage: true,
      referrerAddress: REFERRER_ADDRESS,
      referrerFeeBps: REFERRER_FEE_BPS,
    }),
  });

  return response.json();
}

Response Structure

lib/kuru-flow.ts

export interface QuoteResponse {
  type: string;
  status: "success" | "error";
  output: string;           // Expected output amount (in wei)
  minOut: string;           // Minimum output with slippage
  transaction: {
    to: string;             // Router contract address
    calldata: string;       // Transaction calldata (WITHOUT 0x prefix!)
    value: string;          // Native MON amount (non-zero when swapping native MON)
  };
  gasPrices: {
    slow: string;
    standard: string;
    fast: string;
    rapid: string;
    extreme: string;
  };
  message?: string;         // Error message if status is "error"
}

The calldata field does NOT include the 0x prefix. You must add it before sending the transaction.

3. Check Token Allowance (ERC20 Only)

Before executing a swap with ERC20 tokens, we should verify that the router has permission to spend the user’s tokens.

Native MON does not require approval. Skip this step when swapping native MON.

components/SwapCard.tsx

import { useState } from "react";
import { useAccount, useReadContract } from "wagmi";
import { parseUnits } from "viem";
import type { QuoteResponse } from "@/lib/kuru-flow";

// Token addresses
const NATIVE_MON = "0x0000000000000000000000000000000000000000" as const;
const USDC = "0x754704Bc059F8C67012fEd69BC8A327a5aafb603" as const;

const ERC20_ABI = [
  {
    name: "allowance",
    type: "function",
    stateMutability: "view",
    inputs: [
      { name: "owner", type: "address" },
      { name: "spender", type: "address" },
    ],
    outputs: [{ name: "", type: "uint256" }],
  },
] as const;

// Inside your component:
const { address } = useAccount();
const [amount, setAmount] = useState("");
const [quote, setQuote] = useState<QuoteResponse | null>(null);

const tokenIn = USDC; // Example: swapping USDC
const isNativeToken = tokenIn === NATIVE_MON;
const amountWei = amount ? parseUnits(amount, 6) : BigInt(0);

// Check allowance against router address from quote (skip for native MON)
const { data: allowance } = useReadContract({
  address: tokenIn,
  abi: ERC20_ABI,
  functionName: "allowance",
  args: address && quote?.transaction?.to
    ? [address, quote.transaction.to as `0x${string}`]
    : undefined,
  query: {
    enabled: !isNativeToken, // Don't check allowance for native token
  },
});

// Native tokens don't need approval
const needsApproval = !isNativeToken && allowance !== undefined && amountWei > allowance;

4. Approve Token Spending (ERC20 Only)

If allowance is insufficient for an ERC20 token, we should request approval before swapping.

components/SwapCard.tsx

import { encodeFunctionData } from "viem";
import { useSendTransaction } from "wagmi";

const APPROVE_ABI = [
  {
    name: "approve",
    type: "function",
    stateMutability: "nonpayable",
    inputs: [
      { name: "spender", type: "address" },
      { name: "amount", type: "uint256" },
    ],
    outputs: [{ name: "", type: "bool" }],
  },
] as const;

// Inside your component:
const { sendTransaction: sendApproveTx } = useSendTransaction();

const handleApprove = () => {
  if (!quote?.transaction?.to) return;

  const data = encodeFunctionData({
    abi: APPROVE_ABI,
    functionName: "approve",
    args: [quote.transaction.to as `0x${string}`, amountWei],
  });

  sendApproveTx({
    to: tokenIn,
    data,
  });
};

Use viem’s encodeFunctionData instead of manual hex string manipulation for reliable ABI encoding.

5. Execute the Swap

To submit the swap, we should use the transaction data from the quote response:

components/SwapCard.tsx

// Inside your component:
const { sendTransaction: sendSwapTx } = useSendTransaction();

const handleSwap = () => {
  if (!quote || quote.status !== "success") return;

  // IMPORTANT: Add 0x prefix to calldata
  const calldata = quote.transaction.calldata.startsWith("0x")
    ? quote.transaction.calldata
    : `0x${quote.transaction.calldata}`;

  sendSwapTx({
    to: quote.transaction.to as `0x${string}`,
    data: calldata as `0x${string}`,
    value: BigInt(quote.transaction.value || "0"),
  });
};

Token Addresses and Decimals (Mainnet)

Token	Address	Decimals	Notes
MON (native)	`0x0000000000000000000000000000000000000000`	18	No approval needed
USDC	`0x754704Bc059F8C67012fEd69BC8A327a5aafb603`	6	Requires approval

Be careful with token decimals when formatting output. USDC uses 6 decimals, not 18.

import { formatEther, formatUnits } from "viem";

// WRONG - assumes 18 decimals
formatEther(BigInt(quote.output))  // Shows 0.000000002301622011

// CORRECT - use actual token decimals
formatUnits(BigInt(quote.output), 6)  // Shows 2301.62

Referral Fee System

Kuru features a referral system. As the referrer, we can earn fees on every swap by including your referrer details in quote requests.

lib/kuru-flow.ts

// Replace with YOUR wallet address to receive referral fees
export const REFERRER_ADDRESS = "0xYOUR_WALLET_ADDRESS_HERE";

// Fee in basis points (50 = 0.5%, 100 = 1%)
export const REFERRER_FEE_BPS = 50;

Example fee calculations at 50 bps (0.5%):

Swap Output	Fee Amount
100 USDC	0.5 USDC
500 USDC	2.5 USDC
1000 USDC	5 USDC

Replace 0xYOUR_WALLET_ADDRESS_HERE with your actual wallet address before deploying. The referrerAddress must be a valid Ethereum address or transactions will fail.

Error Handling

Along the way, we might run into errors. Here is how to interpret them:

Status Code	Meaning
400	Bad request - check parameters
401	Unauthorized - invalid or expired token
429	Rate limited - wait before retrying
500	Server error - retry later

Common Mistakes

Missing 0x prefix - Add 0x prefix to calldata before sending
Invalid referrer address - Must be a valid Ethereum address
Skipping approval for ERC20 - ERC20 tokens require approval before swap (native MON does not)
Wrong decimals - USDC has 6 decimals, MON has 18
Zero value for native MON swaps - When swapping native MON, the transaction value must be set to the swap amount

Next Steps

Try the Live Demo to see Kuru Flow in action
Clone the Example Repository for a complete working implementation
Read the Kuru Flow Overview for more details
See Monad Network Information for RPC endpoints and chain configuration

Introduction

Developer Essentials

Tooling and Infrastructure

Reference

Guides

Resources

How to add swaps to your app using Kuru Flow

Requirements

1. Configure Authentication

2. Get a Swap Quote

Response Structure

3. Check Token Allowance (ERC20 Only)

4. Approve Token Spending (ERC20 Only)

5. Execute the Swap

Token Addresses and Decimals (Mainnet)

Referral Fee System

Error Handling

Common Mistakes

Next Steps

​Requirements

​1. Configure Authentication

​2. Get a Swap Quote

​Response Structure

​3. Check Token Allowance (ERC20 Only)

​4. Approve Token Spending (ERC20 Only)

​5. Execute the Swap

​Token Addresses and Decimals (Mainnet)

​Referral Fee System

​Error Handling

​Common Mistakes

​Next Steps

Requirements

1. Configure Authentication

2. Get a Swap Quote

Response Structure

3. Check Token Allowance (ERC20 Only)

4. Approve Token Spending (ERC20 Only)

5. Execute the Swap

Token Addresses and Decimals (Mainnet)

Referral Fee System

Error Handling

Common Mistakes

Next Steps