💱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