@shogun-sdk/intents-sdk 1.2.31 → 1.4.0

package/src/utils/quote/raydium.ts

@@ -0,0 +1,506 @@
+import { NATIVE_SOLANA_TOKEN_ADDRESS, WRAPPED_SOL_MINT_ADDRESS } from '../../constants.js';
+import {
+  API_URLS,
+  getPdaLaunchpadPoolId,
+  Raydium,
+  LAUNCHPAD_PROGRAM,
+  PlatformConfig,
+  Curve,
+  type LaunchpadConfigInfo,
+  type LaunchpadPoolInfo,
+} from '@raydium-io/raydium-sdk-v2';
+import { type SimpleQuote } from './aggregator.js';
+import { Connection, clusterApiUrl, PublicKey } from '@solana/web3.js'; // Used this package for raydium-sdk-v2 compatibility
+import BN from 'bn.js';
+import { Decimal } from 'decimal.js';
+import { JupiterQuoteProvider, type JupiterQuoteParams } from './jupiter.js';
+import { TWO_SECONDS_MS, TEN_MINUTES_MS } from './utils.js';
+
+const launchpadPoolCache = new Map<
+  string,
+  {
+    data: [
+      LaunchpadPoolInfo & {
+        programId: PublicKey;
+        configInfo: LaunchpadConfigInfo;
+      },
+      PublicKey,
+    ];
+    expiresAt: number;
+  }
+>();
+
+const launchpadPoolInfoCache = new Map<
+  string,
+  {
+    data: LaunchpadPoolInfo & {
+      programId: PublicKey;
+      configInfo: LaunchpadConfigInfo;
+    };
+    expiresAt: number;
+  }
+>();
+
+const platformConfigCache = new Map<
+  string,
+  {
+    data: ReturnType<typeof PlatformConfig.decode>;
+    expiresAt: number;
+  }
+>();
+
+const mintInfoCache = new Map<string, Awaited<ReturnType<Raydium['token']['getTokenInfo']>>>();
+
+// Local implementation of compareAddresses function
+const compareAddresses = (firstAddress?: string, secondAddress?: string): boolean => {
+  return !!firstAddress && !!secondAddress && firstAddress.toLowerCase() === secondAddress.toLowerCase();
+};
+
+const LAUNCHPAD_WHITELISTED_QUOTE_TOKENS = [
+  new PublicKey('So11111111111111111111111111111111111111112'), // WSOL
+  new PublicKey('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'), // USDC
+  new PublicKey('Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB'), // USDT
+  new PublicKey('USD1ttGY1N17NEEHLmELoaybftRBUSErhqYiQzvEmuB'), // USD1
+];
+
+export type RaydiumPumpQuoteParams = {
+  inputMint: string;
+  outputMint: string;
+  amount: string;
+  slippageBps: number;
+};
+
+export type RaydiumQuoteResponse = {
+  success: boolean;
+  data: {
+    inputMint: string;
+    outputMint: string;
+    inAmount: string;
+    outAmount: string;
+    otherAmountThreshold: string;
+    swapMode: string;
+    slippageBps: number;
+    platformFee: null;
+    priceImpactPct: string;
+    routePlan: Array<{
+      swapInfo: {
+        ammKey: string;
+        label: string;
+        inputMint: string;
+        outputMint: string;
+        notEnoughLiquidity: boolean;
+        minInAmount: string;
+        minOutAmount: string;
+        priceImpactPct: string;
+        lpFee: {
+          amount: string;
+          mint: string;
+          pct: number;
+        };
+        platformFee: {
+          amount: string;
+          mint: string;
+          pct: number;
+        };
+      };
+      percent: number;
+    }>;
+  };
+};
+
+let raydium: Raydium | undefined;
+export const initSdk = async (): Promise<Raydium> => {
+  if (raydium) return raydium;
+  raydium = await Raydium.load({
+    connection: new Connection(clusterApiUrl('mainnet-beta')),
+    disableFeatureCheck: true,
+    disableLoadToken: true,
+  });
+  return raydium;
+};
+
+// Using API_URLS from Raydium SDK v2
+
+export class RaydiumQuoteProvider {
+  /**
+   * Get priority fee recommendations from Raydium API
+   * @returns Priority fee data with different tiers (vh, h, m)
+   */
+  public async getPriorityFee(): Promise<{
+    vh: number; // very high
+    h: number; // high
+    m: number; // medium
+  }> {
+    const url = new URL(API_URLS.PRIORITY_FEE, API_URLS.BASE_HOST);
+    const response = await fetch(url);
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch priority fee from Raydium API: ${response.status} ${response.statusText}`);
+    }
+
+    const data = await response.json();
+
+    if (!data.success) {
+      throw new Error('Raydium API returned unsuccessful response for priority fee');
+    }
+
+    return data.data.default;
+  }
+
+  public async getQuote(raydiumParams: RaydiumPumpQuoteParams): Promise<RaydiumQuoteResponse> {
+    const params = { ...raydiumParams };
+
+    // Handle native SOL token mapping for Solana
+    if (compareAddresses(params.inputMint, NATIVE_SOLANA_TOKEN_ADDRESS)) {
+      params.inputMint = WRAPPED_SOL_MINT_ADDRESS;
+    }
+
+    if (compareAddresses(params.outputMint, NATIVE_SOLANA_TOKEN_ADDRESS)) {
+      params.outputMint = WRAPPED_SOL_MINT_ADDRESS;
+    }
+
+    const url = new URL('/compute/swap-base-in', API_URLS.SWAP_HOST);
+    url.searchParams.set('inputMint', params.inputMint);
+    url.searchParams.set('outputMint', params.outputMint);
+    url.searchParams.set('amount', params.amount);
+    url.searchParams.set('slippageBps', params.slippageBps.toString());
+    url.searchParams.set('txVersion', 'V0');
+
+    const response = await fetch(url);
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch quote from Raydium API: ${response.status} ${response.statusText}`);
+    }
+
+    const data: RaydiumQuoteResponse = await response.json();
+
+    if (!data.success) {
+      throw new Error('Raydium API returned unsuccessful response');
+    }
+
+    return data;
+  }
+
+  /**
+   * Get transaction data for executing a swap
+   * @param params - Transaction parameters
+   * @returns Serialized transaction data
+   */
+  public async getSwapTransaction(params: {
+    swapResponse: RaydiumQuoteResponse;
+    wallet: string;
+    txVersion: 'V0' | 'LEGACY';
+    wrapSol?: boolean;
+    unwrapSol?: boolean;
+    inputAccount?: string;
+    outputAccount?: string;
+    computeUnitPriceMicroLamports?: string;
+  }): Promise<{
+    id: string;
+    version: string;
+    success: boolean;
+    data: { transaction: string }[];
+  }> {
+    const url = new URL('/transaction/swap-base-in', API_URLS.SWAP_HOST);
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        computeUnitPriceMicroLamports: params.computeUnitPriceMicroLamports || '0',
+        swapResponse: params.swapResponse,
+        txVersion: params.txVersion,
+        wallet: params.wallet,
+        wrapSol: params.wrapSol || false,
+        unwrapSol: params.unwrapSol || false,
+        inputAccount: params.inputAccount,
+        outputAccount: params.outputAccount,
+      }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to get swap transaction from Raydium API: ${response.status} ${response.statusText}`);
+    }
+
+    const data = await response.json();
+
+    if (!data.success) {
+      throw new Error('Raydium API returned unsuccessful response for swap transaction');
+    }
+
+    return data;
+  }
+
+  public async getQuotePrebonded(raydiumParams: RaydiumPumpQuoteParams): Promise<SimpleQuote> {
+    // First, get the Raydium quote token
+    let raydiumSdk = await initSdk();
+    let inputMintPk = new PublicKey(raydiumParams.inputMint);
+    let outputMintPk = new PublicKey(raydiumParams.outputMint);
+
+    // Check if either input or output mint is in the launchpad whitelisted tokens
+    let poolInfo, inputPoolInfo, outputPoolInfo, quoteToken, isInputPrebonded, inputQuoteToken, outputQuoteToken;
+    try {
+      [inputPoolInfo, inputQuoteToken] = await this.checkPreboundedTokensSwapLaunchpad(raydiumSdk, inputMintPk);
+      if (inputPoolInfo && inputQuoteToken) {
+        isInputPrebonded = true;
+        poolInfo = inputPoolInfo;
+        quoteToken = inputQuoteToken;
+      }
+    } catch (e) {}
+    try {
+      [outputPoolInfo, outputQuoteToken] = await this.checkPreboundedTokensSwapLaunchpad(raydiumSdk, outputMintPk);
+      if (outputPoolInfo && outputQuoteToken) {
+        isInputPrebonded = false;
+        poolInfo = outputPoolInfo;
+        quoteToken = outputQuoteToken;
+      }
+    } catch (e) {}
+
+    if (inputPoolInfo && outputPoolInfo) {
+      // Both input and output are prebonded, which is not supported
+      throw new Error('Both input and output tokens are prebonded, which is not supported');
+    } else if (!quoteToken || !poolInfo) {
+      // Neither input nor output is prebonded, fallback to regular Raydium quote
+      throw new Error('Neither input nor output tokens are prebonded');
+    }
+
+    let quoteIsInput = quoteToken.equals(inputMintPk);
+    let quoteIsOutput = quoteToken.equals(outputMintPk);
+
+    if (isInputPrebonded) {
+      // We have to estimate prebonded first and then swap from quote token to output token (if needed)
+      let { expectedAmountOut, minimumAmountOut } = await this.estimatePrebondedToQuote(
+        raydiumSdk,
+        inputMintPk,
+        poolInfo,
+        'sell',
+        new BN(raydiumParams.amount),
+        new BN(raydiumParams.slippageBps), // Use full slippage for simplicity
+      );
+
+      // Then, if output token is not quote token, we have to swap from quote token to output token
+      if (!quoteIsOutput) {
+        let jupiterQuoteRequest: JupiterQuoteParams = {
+          amount: BigInt(expectedAmountOut.toString()),
+          tokenIn: quoteToken.toString(),
+          tokenOut: raydiumParams.outputMint,
+          swapMode: 'ExactIn',
+          slippageBps: raydiumParams.slippageBps, // Use full slippage for simplicity
+        };
+        const jupiterQuoter = new JupiterQuoteProvider();
+        const jupiterQuote = await jupiterQuoter.getQuote(jupiterQuoteRequest);
+        if (!jupiterQuote.quote) {
+          throw new Error('Jupiter quote failed');
+        }
+
+        return {
+          amountIn: BigInt(raydiumParams.amount),
+          amountOut: BigInt(jupiterQuote.quote.outAmount),
+          amountOutMin: BigInt(jupiterQuote.quote.otherAmountThreshold),
+          slippage: raydiumParams.slippageBps / 100,
+        };
+      } else {
+        return {
+          amountIn: BigInt(raydiumParams.amount),
+          amountOut: BigInt(expectedAmountOut.toString()),
+          amountOutMin: BigInt(minimumAmountOut.toString()),
+          slippage: raydiumParams.slippageBps / 100,
+        };
+      }
+    } else {
+      // We have to swap from input token to quote token and then estimate prebonded
+      let amountOutFromInput = new BN(raydiumParams.amount);
+      if (!quoteIsInput) {
+        let jupiterQuoteRequest: JupiterQuoteParams = {
+          amount: BigInt(raydiumParams.amount),
+          tokenIn: raydiumParams.inputMint,
+          tokenOut: quoteToken.toString(),
+          swapMode: 'ExactIn',
+          slippageBps: raydiumParams.slippageBps, // Use full slippage for simplicity
+        };
+        const jupiterQuoter = new JupiterQuoteProvider();
+        const jupiterQuote = await jupiterQuoter.getQuote(jupiterQuoteRequest);
+        if (!jupiterQuote.quote) {
+          throw new Error('Jupiter quote failed');
+        }
+
+        // Calculate minimum amount with slippage applied
+        amountOutFromInput = new BN(jupiterQuote.quote.outAmount);
+      }
+      // Now estimate prebonded
+      let { expectedAmountOut, minimumAmountOut } = await this.estimatePrebondedToQuote(
+        raydiumSdk,
+        outputMintPk,
+        poolInfo,
+        'buy',
+        amountOutFromInput,
+        new BN(raydiumParams.slippageBps),
+      );
+      return {
+        amountIn: BigInt(raydiumParams.amount),
+        amountOut: BigInt(expectedAmountOut.toString()),
+        amountOutMin: BigInt(minimumAmountOut.toString()),
+        slippage: raydiumParams.slippageBps / 100,
+      };
+    }
+  }
+
+  async checkPreboundedTokensSwapLaunchpad(
+    raydiumSdk: Raydium,
+    raydiumMint: PublicKey,
+  ): Promise<
+    [
+      LaunchpadPoolInfo & {
+        programId: PublicKey;
+        configInfo: LaunchpadConfigInfo;
+      },
+      PublicKey,
+    ]
+  > {
+    // Try cache first
+    const cacheKey = raydiumMint.toBase58();
+    const cached = launchpadPoolCache.get(cacheKey);
+    if (cached && Date.now() < cached.expiresAt) {
+      return cached.data;
+    }
+
+    // Check if either input or output mint is in the launchpad whitelisted tokens
+    // Check for input mint
+    for (const quoteToken of LAUNCHPAD_WHITELISTED_QUOTE_TOKENS) {
+      try {
+        const poolId = getPdaLaunchpadPoolId(LAUNCHPAD_PROGRAM, raydiumMint, quoteToken).publicKey;
+        const poolCacheKey = poolId.toBase58();
+        const cachedPoolInfo = launchpadPoolInfoCache.get(poolCacheKey);
+        const poolInfo =
+          cachedPoolInfo && Date.now() < cachedPoolInfo.expiresAt
+            ? cachedPoolInfo.data
+            : await raydiumSdk.launchpad.getRpcPoolInfo({ poolId });
+
+        launchpadPoolInfoCache.set(poolCacheKey, {
+          data: poolInfo,
+          expiresAt: Date.now() + TWO_SECONDS_MS,
+        });
+        // Cache positive result for a short period
+        launchpadPoolCache.set(cacheKey, {
+          data: [poolInfo, quoteToken],
+          expiresAt: Date.now() + TWO_SECONDS_MS,
+        });
+        return [poolInfo, quoteToken];
+      } catch (e) {
+        // Ignore and continue trying with next quote token
+      }
+    }
+    throw new Error('No launchpad pool found for the given token pair');
+  }
+
+  async estimatePrebondedToQuote(
+    raydiumSdk: Raydium,
+    raydiumMint: PublicKey,
+    poolInfo: LaunchpadPoolInfo & {
+      programId: PublicKey;
+      configInfo: LaunchpadConfigInfo;
+    },
+    trade_type: 'buy' | 'sell',
+    amount: BN,
+    slippage: BN,
+  ): Promise<{ expectedAmountOut: BN; minimumAmountOut: BN }> {
+    const epochInfo = await raydiumSdk.connection.getEpochInfo();
+    const slot = await raydiumSdk.connection.getSlot();
+    const platformCacheKey = poolInfo.platformId.toBase58();
+    let platformInfoEntry = platformConfigCache.get(platformCacheKey);
+    if (!platformInfoEntry || Date.now() > platformInfoEntry.expiresAt) {
+      const accountInfo = await raydiumSdk.connection.getAccountInfo(poolInfo.platformId);
+      if (!accountInfo) {
+        throw new Error('Platform account not found');
+      }
+      platformInfoEntry = {
+        data: PlatformConfig.decode(accountInfo.data),
+        expiresAt: Date.now() + TEN_MINUTES_MS,
+      };
+      platformConfigCache.set(platformCacheKey, platformInfoEntry);
+    }
+    const platformInfo = platformInfoEntry.data;
+
+    const mintCacheKey = raydiumMint.toBase58();
+    let mintInfo = mintInfoCache.get(mintCacheKey);
+    if (!mintInfo) {
+      mintInfo = await raydiumSdk.token.getTokenInfo(raydiumMint);
+      mintInfoCache.set(mintCacheKey, mintInfo);
+    }
+    const shareFeeRate = new BN(0);
+
+    let expectedAmountOut;
+    let minimumAmountOut;
+    if (trade_type === 'buy') {
+      const res = Curve.buyExactIn({
+        poolInfo,
+        amountB: amount,
+        protocolFeeRate: poolInfo.configInfo.tradeFeeRate,
+        platformFeeRate: platformInfo.feeRate,
+        curveType: poolInfo.configInfo.curveType,
+        shareFeeRate,
+        creatorFeeRate: platformInfo.creatorFeeRate,
+        transferFeeConfigA: mintInfo.extensions.feeConfig
+          ? {
+              transferFeeConfigAuthority: PublicKey.default,
+              withdrawWithheldAuthority: PublicKey.default,
+              withheldAmount: BigInt(0),
+              olderTransferFee: {
+                epoch: BigInt(mintInfo.extensions.feeConfig.olderTransferFee.epoch ?? epochInfo?.epoch ?? 0),
+                maximumFee: BigInt(mintInfo.extensions.feeConfig.olderTransferFee.maximumFee),
+                transferFeeBasisPoints: mintInfo.extensions.feeConfig.olderTransferFee.transferFeeBasisPoints,
+              },
+              newerTransferFee: {
+                epoch: BigInt(mintInfo.extensions.feeConfig.newerTransferFee.epoch ?? epochInfo?.epoch ?? 0),
+                maximumFee: BigInt(mintInfo.extensions.feeConfig.newerTransferFee.maximumFee),
+                transferFeeBasisPoints: mintInfo.extensions.feeConfig.newerTransferFee.transferFeeBasisPoints,
+              },
+            }
+          : undefined,
+        slot,
+      });
+      expectedAmountOut = new BN(res.amountA.amount.sub(res.amountA.fee ?? new BN(0)).toString());
+      minimumAmountOut = new BN(
+        new Decimal(res.amountA.amount.sub(res.amountA.fee ?? new BN(0)).toString())
+          .mul((10000 - slippage.toNumber()) / 10000)
+          .toFixed(0),
+      );
+    } else if (trade_type === 'sell') {
+      const res = Curve.sellExactIn({
+        poolInfo,
+        amountA: amount,
+        protocolFeeRate: poolInfo.configInfo.tradeFeeRate,
+        platformFeeRate: platformInfo.feeRate,
+        curveType: poolInfo.configInfo.curveType,
+        shareFeeRate,
+        creatorFeeRate: platformInfo.creatorFeeRate,
+        slot,
+        transferFeeConfigA: mintInfo.extensions.feeConfig
+          ? {
+              transferFeeConfigAuthority: PublicKey.default,
+              withdrawWithheldAuthority: PublicKey.default,
+              withheldAmount: BigInt(0),
+              olderTransferFee: {
+                epoch: BigInt(mintInfo.extensions.feeConfig.olderTransferFee.epoch ?? epochInfo?.epoch ?? 0),
+                maximumFee: BigInt(mintInfo.extensions.feeConfig.olderTransferFee.maximumFee),
+                transferFeeBasisPoints: mintInfo.extensions.feeConfig.olderTransferFee.transferFeeBasisPoints,
+              },
+              newerTransferFee: {
+                epoch: BigInt(mintInfo.extensions.feeConfig.newerTransferFee.epoch ?? epochInfo?.epoch ?? 0),
+                maximumFee: BigInt(mintInfo.extensions.feeConfig.newerTransferFee.maximumFee),
+                transferFeeBasisPoints: mintInfo.extensions.feeConfig.newerTransferFee.transferFeeBasisPoints,
+              },
+            }
+          : undefined,
+      });
+      expectedAmountOut = new BN(res.amountB);
+      minimumAmountOut = new BN(
+        new Decimal(res.amountB.toString()).mul((10000 - slippage.toNumber()) / 10000).toFixed(0),
+      );
+    } else {
+      throw new Error('Invalid trade type. Must be "buy" or "sell".');
+    }
+    return { expectedAmountOut, minimumAmountOut };
+  }
+}

package/src/utils/quote/relay.ts

@@ -0,0 +1,99 @@
+import { type SupportedEvmChain } from "../../chains.js";
+import { isNativeEvmToken, WRAPPED_ETH_ADDRESSES } from "../../constants.js";
+
+const RELAY_BASE_URL = "https://api.relay.link/quote";
+
+export type RelayQuoteRequestParams = {
+    srcToken: string;
+    destToken: string;
+    amount: bigint;
+    user?: string;
+    recipient?: string;
+};
+
+export type RelayQuoteResult = {
+    amountOut: bigint;
+    amountIn: bigint;
+    amountOutUsd: number;
+    amountInUsd: number;
+    slippage: number;
+    priceImpact: number;
+    quote: any;
+};
+
+export class RelayQuoteProvider {
+    protected chainId: SupportedEvmChain;
+
+    constructor(chainId: SupportedEvmChain) {
+        this.chainId = chainId;
+    }
+
+    private async postRelayQuote(params: RelayQuoteRequestParams) {
+        const user = params.user ?? "0x000000000000000000000000000000000000dead";
+
+        const srcToken = isNativeEvmToken(params.srcToken)
+            ? WRAPPED_ETH_ADDRESSES[this.chainId]
+            : params.srcToken;
+
+        const destToken = isNativeEvmToken(params.destToken)
+            ? WRAPPED_ETH_ADDRESSES[this.chainId]
+            : params.destToken;
+
+        const body = {
+            user,
+            recipient: params.recipient ?? user,
+            originChainId: this.chainId,
+            destinationChainId: this.chainId,
+            originCurrency: srcToken,
+            destinationCurrency: destToken,
+            amount: params.amount.toString(),
+            tradeType: "EXACT_INPUT",
+        };
+
+        const res = await fetch(RELAY_BASE_URL, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+
+        if (!res.ok) {
+            throw new Error(`Relay POST /quote failed: ${await res.text()}`);
+        }
+
+        return res.json();
+    }
+
+    public async getSwapEstimation(
+        params: RelayQuoteRequestParams
+    ): Promise<RelayQuoteResult> {
+        const relayQuote = await this.postRelayQuote(params);
+
+        const details = relayQuote.details;
+
+        const amountIn = BigInt(details.currencyIn.amount);
+        const amountOut = BigInt(details.currencyOut.amount);
+
+        const amountInUsd = Number(details.currencyIn.amountUsd ?? 0);
+        const amountOutUsd = Number(details.currencyOut.amountUsd ?? 0);
+
+        const priceImpact = details.totalImpact?.percent
+            ? Number(details.totalImpact.percent)
+            : 0;
+
+        const slippage = details.slippageTolerance?.origin?.percent
+            ? Number(details.slippageTolerance.origin.percent)
+            : 0;
+
+        return {
+            amountIn,
+            amountOut,
+            amountInUsd,
+            amountOutUsd,
+            slippage,
+            priceImpact,
+            quote: relayQuote,
+        };
+    }
+}

package/src/utils/quote/stablecoins-tokens.ts

@@ -9,14 +9,41 @@ export type QuoteParams = {
   slippageBps?: number;
 };
 
-export const CROSS_CHAIN_TOKENS: Record<string, Record<ChainID, string>> = {
+export const CROSS_CHAIN_STABLES: Record<string, Partial<Record<ChainID, { address: string; decimals: number }>>> = {
   USDC: {
-    [ChainID.Solana]: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC on Solana
-    [ChainID.Base]: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC on Base
-    [ChainID.Arbitrum]: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831', // USDC on Arbitrum
-    [ChainID.Hyperliquid]: '0xb8ce59fc3717ada4c02eadf9682a9e934f625ebb', // USDT on Hyperliquid (No USDC on Hyperliquid)
-    [ChainID.Sui]: '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC', // USDC on Sui
-    [ChainID.Optimism]: '0x7F5c764cBc14f9669B88837ca1490cCa17c31607', // USDC on Optimism
+    [ChainID.Solana]: {
+      address: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+      decimals: 6,
+    },
+    [ChainID.Base]: {
+      address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+      decimals: 6,
+    },
+    [ChainID.Arbitrum]: {
+      address: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
+      decimals: 6,
+    },
+    [ChainID.Optimism]: {
+      address: '0x7F5c764cBc14f9669B88837ca1490cCa17c31607',
+      decimals: 6,
+    },
+    [ChainID.Sui]: {
+      address: '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC',
+      decimals: 6,
+    },
+    [ChainID.MONAD]: {
+      address: '0x754704Bc059F8C67012fEd69BC8A327a5aafb603',
+      decimals: 6,
+    },
+  },
+  USDT: {
+    [ChainID.Hyperliquid]: {
+      address: '0xb8ce59fc3717ada4c02eadf9682a9e934f625ebb',
+      decimals: 6,
+    },
+    [ChainID.BSC]: {
+      address: '0x55d398326f99059ff775485246999027b3197955',
+      decimals: 18,
+    },
   },
-  // Add more tokens as needed
 };

package/src/utils/quote/utils.ts

@@ -0,0 +1,8 @@
+export const TEN_MINUTES_MS = 10 * 60 * 1000;
+export const TWO_SECONDS_MS = 2 * 1000;
+export const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+
+export function applySlippage(amount: bigint, slippageBps = 0): bigint {
+  const multiplier = BigInt(10000 - slippageBps);
+  return (amount * multiplier) / 10000n;
+}

package/src/utils/tokens/index.ts

@@ -0,0 +1,38 @@
+import { TOKEN_SEARCH_API_BASE_URL } from '../../constants.js';
+import type { TokenSearchParams, TokenSearchResponse } from '../../types/token-list.js';
+
+/**
+ * getTokenList
+ *
+ * High-level SDK function for token discovery.
+ * Supports cancellation via AbortController.
+ *
+ * Example:
+ * ```ts
+ * import { getTokenList } from "@shogun/sdk";
+ *
+ * const controller = new AbortController();
+ * const res = await getTokenList({ q: "usdc", networkId: 8453, signal: controller.signal });
+ *
+ * To cancel:
+ * controller.abort();
+ * ```
+ */
+export async function getTokenList(params: TokenSearchParams): Promise<TokenSearchResponse> {
+  const url = new URL(`${TOKEN_SEARCH_API_BASE_URL}/tokens/search`);
+
+  if (params.q) url.searchParams.append('q', params.q);
+  if (params.networkId) url.searchParams.append('networkId', String(params.networkId));
+  if (params.page) url.searchParams.append('page', String(params.page));
+  if (params.limit) url.searchParams.append('limit', String(params.limit));
+
+  const res = await fetch(url.toString(), {
+    signal: params.signal,
+  });
+
+  if (!res.ok) {
+    throw new Error(`Failed to fetch tokens: ${res.status} ${res.statusText}`);
+  }
+
+  return (await res.json()) as TokenSearchResponse;
+}