πŸ’±Swap

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


Installation

npm install @holdstation/worldchain-sdk \\
            @holdstation/worldchain-ethers-v5 \\
            ethers@^5.8.0

Setup

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

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

// 2. Wire up the SDK client
const client    = new Client(provider);
const multicall = new Multicall3(provider);
config.client    = client;
config.multicall3 = multicall;

// 3. Helpers for tokens & swaps
const tokenProvider = new TokenProvider();
const quoter        = new Quoter(client);
const swapHelper    = new SwapHelper(client, { tokenStorage: config.tokenStorage });

Contract Address

Include your target contract address in the configuration:

const TARGET_CONTRACT = "0x43222f934ea5c593a060a6d46772fdbdc2e2cff0";

Overall Flow

  1. Fetch token metadata (if you need decimals, symbol, etc.)

const info = await tokenProvider.details("0xTokenAddress");
  1. Preview routes (optional)

const route = await quoter.simple(tokenIn, tokenOut);
const smart = await quoter.smart(tokenIn, { slippage: 1, deadline: 300 });
  1. Get a live quote

const quoteParams = {
  tokenIn:  tokenIn,
  tokenOut: tokenOut,
  amountIn: "1.5",
  slippage: "0.5",
  fee:      "0.2",
};
const quote = await swapHelper.quote(quoteParams);
  1. Execute the swap

const swapParams = {
  ...quoteParams,
  tx: {
    data:  quote.data,
    to:    quote.to,
    value: quote.value,
  },
  feeAmountOut: quote.addons?.feeAmountOut,
  feeReceiver:  ethers.constants.AddressZero,
};
const receipt = await swapHelper.swap(swapParams);
console.log("Transaction:", receipt.transactionHash);

Detailed Examples

Token Metadata

// Single token
const tokenInfo = await tokenProvider.details("0xTokenAddress");
console.log(tokenInfo);

// Multiple tokens
const infos = await tokenProvider.details(
  "0xToken1", "0xToken2", "0xToken3"
);
console.log(infos);

Quote

Simple Quote

const simpleQuote = await quoter.simple(
  "0xWETH",
  "0xUSDC"
);
console.log(simpleQuote.best);

Smart Quote

const smartQuote = await quoter.smart("0xWETH", {
  slippage: 2,       // 2%
  deadline: 120,     // seconds
});
console.log(smartQuote.quote);

SwapParams Interfaces

Quote Input

Name
Type
Required
Description

tokenIn

string

βœ…

Address of input token

tokenOut

string

βœ…

Address of output token

amountIn

string

βœ…

Amount of input token (human units)

slippage

string

βœ…

Max slippage in % (e.g. "0.3")

fee

string

βœ…

Platform fee in % (e.g. "0.2")

Swap Input

Name
Type
Required
Description

tokenIn

string

βœ…

Address of input token

tokenOut

string

βœ…

Address of output token

amountIn

string

βœ…

Amount of input token

tx

object

βœ…

{ data, to, value } from quote()

fee

string

βœ…

Fee in %

feeAmountOut

string

❌

Absolute fee taken from output (optional)

feeReceiver

string

βœ…

Address to receive fee (AddressZero if none)


Full Example & Further Reading

For a complete, end‑to‑end swap example, and to explore all available methods, check out the SDK repo and docs:

πŸ”— Documentation & Examples

https://www.npmjs.com/package/@holdstation/worldchain-sdk

Last updated