💱Swap

This guide demonstrates how to fetch token data, quote, and execute token swaps using the Holdstation SDK.

Installation

npm install @holdstation/worldchain-sdk @holdstation/worldchain-ethers-v5 ethers

Setup

import { Client, Multicall3, Quoter, SwapHelper } from "@holdstation/worldchain-ethers-v5";
import { config, inmemoryTokenStorage, TokenProvider } from "@holdstation/worldchain-sdk";
import { ethers } from "ethers";

const RPC_URL = "<https://worldchain-mainnet.g.alchemy.com/public>";
const provider = new ethers.providers.StaticJsonRpcProvider(RPC_URL, {
  chainId: 480,
  name: "worldchain",
});

const client = new Client(provider);
config.client = client;
config.multicall3 = new Multicall3(provider);

const tokenProvider = new TokenProvider();
const quoter = new Quoter(client);
const swapHelper = new SwapHelper(client, {
  tokenStorage: inmemoryTokenStorage,
});

Overall Flow

  1. Call tokenProvider.details(...) to fetch token metadata if needed.

  2. (Optional) Call quoter.simple() or quoter.smart() to preview routes.

  3. Call swapHelper.quote(params) with SwapParams["quoteInput"] to get a live quote for swapping.

  4. Call swapHelper.swap(...) with SwapParams["input"] using the result from quote.

  5. (Optional) Ensure feeReceiver is whitelisted on the contract if you are charging a fee.

Token Metadata

Get Token Info

const tokenInfo = await tokenProvider.details("0xTokenAddress");
console.log("Token Info:", tokenInfo);

Get Multiple Token Details

const tokens = await tokenProvider.details(
  "0xToken1", "0xToken2", "0xToken3"
);
console.log("Token Details:", tokens);

Quoter

Simple Quote

const WETH = "0x4200000000000000000000000000000000000006";
const USDCe = "0x79A02482A880bCE3F13e09Da970dC34db4CD24d1";

const quote = await quoter.simple(WETH, USDCe);
console.log("Best route:", quote.best);

Smart Quote (Slippage + Deadline)

const quote = await quoter.smart(WETH, {
  slippage: 3,
  deadline: 10,
});

console.log("Smart quote:", quote.quote);
🔁 Estimate Swap

📑 Parameters – SwapParams["quoteInput"]

Name
Type
Required
Description

tokenIn

string

✅ Yes

Input token address

tokenOut

string

✅ Yes

Output token address

amountIn

string

✅ Yes

Input amount (human-readable format)

slippage

string

✅ Yes

Slippage percentage (e.g., "0.3" for 0.3%)

fee

string

✅ Yes

Fee percentage (e.g., "0.2" for 0.2%)

📘 Usage Example – Estimate Quote

const params = {
  tokenIn: "0xTokenIn",
  tokenOut: "0xTokenOut",
  amountIn: "2",
  slippage: "0.3",
  fee: "0.2",
};

const estimate = await swapHelper.quote(params);
console.log("Quote estimate:", estimate);

Execute Swap

📑 Parameters – SwapParams["input"]

Name
Type
Required
Description

tokenIn

string

✅ Yes

Input token address

tokenOut

string

✅ Yes

Output token address

amountIn

string

✅ Yes

Input token amount

tx

object

✅ Yes

Transaction data returned from quote()

fee

string

✅ Yes

Fee percentage

feeAmountOut

string

❌ Optional

Fee amount to take from output token

feeReceiver

string

✅ Yes

Address to receive fee (use AddressZero if none)

📘 Usage Example – Execute Swap

const quoteResponse = await swapHelper.quote(params);

const swapParams = {
  tokenIn: "0xTokenIn",
  tokenOut: "0xTokenOut",
  amountIn: "2",
  tx: {
    data: quoteResponse.data,
    to: quoteResponse.to,
    value: quoteResponse.value,
  },
  feeAmountOut: quoteResponse.addons?.feeAmountOut,
  fee: "0.2",
  feeReceiver: ethers.constants.AddressZero,
};

const result = await swapHelper.swap(swapParams);
console.log("Swap result:", result);

🔗 Full Example on GitHub

Check the full swap flow example:

📂 Swap Example – GitHub

PreviousSendNextWidget

Last updated