@shogun-sdk/root v1.2.24

@shogun-sdk/root

SDK for root swaps between EVM chains and Solana. This package provides functionality for cross-chain token swaps and balance checking.

Quick Start

1. Install the package

npm install @shogun-sdk/root
# or
yarn add @shogun-sdk/root

2. Initialize the Quote Client

import { ShogunQuoteApiClient } from '@shogun-sdk/root';

// Create a new client instance
const client = new ShogunQuoteApiClient(
  'YOUR_API_KEY', // Get this from Shogun dashboard
  'https://api.shogun.com' // API endpoint
);

3. Basic Usage Example

// Example: Swap ETH from Ethereum to SOL on Solana
async function getSwapQuote() {
  try {
    const quoteParams = {
      srcChain: 1, // Ethereum mainnet
      destChain: 8453, // Base chain
      srcToken: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH
      destToken: '0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599', // WBTC
      amount: '1000000000000000000', // 1 ETH (in wei)
      senderAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
      affiliateWallet: '0x123...', // Your affiliate wallet
      affiliateFee: '1', // 1% affiliate fee
      slippage: 0.5, // 0.5% slippage tolerance
      destinationAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
      dynamicSlippage: true // Enable dynamic slippage for Solana
    };

    const quote = await client.fetchQuote(quoteParams);
    console.log('Quote received:', quote);
  } catch (error) {
    console.error('Error fetching quote:', error);
  }
}

Balance Checking

The SDK provides balance checking capabilities for both EVM and Solana chains:

import { ShogunBalancesApiClient } from '@shogun-sdk/root';

// Initialize the balances client
const balancesClient = new ShogunBalancesApiClient('YOUR_API_KEY');

// Example: Check balances across chains
async function checkBalances() {
  try {
    // 1. Check EVM wallet balances
    const evmBalances = await balancesClient.getEvmWalletBalance('0x742d35Cc6634C0532925a3b844Bc454e4438f44e');
    console.log('EVM Balances:', evmBalances);

    // 2. Get detailed token info
    const tokenInfo = await balancesClient.getTokenInfo(
      evmBalances,
      '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2' // WETH
    );
    console.log('Token Info:', tokenInfo);

    // 3. Check Solana token balances
    const solanaBalances = await balancesClient.getSolanaTokenBalances('your-solana-address');
    console.log('Solana Balances:', solanaBalances);

    // 4. Get token price in USD
    const tokenPrice = await balancesClient.getTokenUSDPrice(
      '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH
      1 // Ethereum mainnet
    );
    console.log('Token Price:', tokenPrice);
  } catch (error) {
    console.error('Error checking balances:', error);
  }
}

Common Use Cases

1. Cross-chain Token Swap

async function performCrossChainSwap() {
  try {
    // 1. Get the quote
    const quote = await client.fetchQuote({
      srcChain: 1, // Ethereum
      destChain: 8453, // Base
      srcToken: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH
      destToken: '0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599', // WBTC
      amount: '1000000000000000000', // 1 ETH
      senderAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
      affiliateWallet: '0x123...',
      affiliateFee: '1',
      slippage: 0.5,
      destinationAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
    });

    // 2. Check if quote is valid
    if (!quote.status) {
      console.error('Invalid quote:', quote.error);
      return;
    }

    // 3. Execute the swap
    const swapResult = await executeSwap(quote.data);
    console.log('Swap successful:', swapResult);
  } catch (error) {
    console.error('Swap failed:', error);
  }
}

2. Balance Monitoring

async function monitorBalances() {
  const balancesClient = new ShogunBalancesApiClient('YOUR_API_KEY');
  
  // Monitor EVM balances
  setInterval(async () => {
    try {
      const balances = await balancesClient.getEvmWalletBalance('0x742d35Cc6634C0532925a3b844Bc454e4438f44e');
      console.log('Updated EVM balances:', balances);
    } catch (error) {
      console.error('Error updating balances:', error);
    }
  }, 30000); // Check every 30 seconds
}

Error Handling

Here's a comprehensive example of error handling:

async function handleSwapWithErrors() {
  try {
    const quote = await client.fetchQuote({
      // ... quote parameters
    });

    if (!quote.status) {
      // Handle specific error cases
      switch (quote.error) {
        case 'INSUFFICIENT_BALANCE':
          console.error('Not enough tokens to complete the swap');
          break;
        case 'INVALID_QUOTE':
          console.error('Quote is no longer valid');
          break;
        case 'SLIPPAGE_TOO_HIGH':
          console.error('Price impact is too high');
          break;
        default:
          console.error(`Failed to fetch quote: ${quote.error}`);
      }
      return;
    }

    // Success case
    console.log('Quote received successfully:', quote.data);
    
  } catch (error) {
    // Handle unexpected errors
    if (error instanceof Error) {
      console.error('Unexpected error:', error.message);
      console.error('Stack trace:', error.stack);
    } else {
      console.error('Unknown error occurred:', error);
    }
  }
}

API Reference

ShogunQuoteApiClient

Constructor

new ShogunQuoteApiClient(apiKey: string, baseUrl: string)

Methods

• fetchQuote(params: QuoteParams): Promise<QuoteResponse>
• getQuoteStatus(quoteId: string): Promise<QuoteStatusResponse>

ShogunBalancesApiClient

Constructor

new ShogunBalancesApiClient(apiKey: string)

Methods

• getEvmWalletBalance(address: string): Promise<EvmBalances>
• getSolanaTokenBalances(address: string): Promise<SolanaBalances>
• getTokenInfo(balances: EvmBalances, address: string): Promise<TokenInfo>
• getTokenUSDPrice(tokenAddress: string, chainId: number): Promise<number>
• isValidAddress(address: string): boolean

Best Practices

1. Always Check Quote Status

const quote = await client.fetchQuote({...});
if (!quote.status) {
  // Handle error
  return;
}

2. Use TypeScript for Better Type Safety

import { ShogunQuoteApiClient, QuoteParams } from '@shogun-sdk/root';

const params: QuoteParams = {
  // ... parameters
};

3. Implement Proper Error Handling

try {
  const quote = await client.fetchQuote({...});
  // Handle success
} catch (error) {
  // Handle errors
}

4. Keep API Keys Secure

// Use environment variables
const client = new ShogunQuoteApiClient(
  process.env.SHOGUN_API_KEY,
  process.env.SHOGUN_API_URL
);

Troubleshooting

Common issues and their solutions:

1. API Key Issues

   • Ensure your API key is valid and active
   • Check if you've exceeded your API rate limits
   • Verify the API key format

2. Quote Failures

   • Check if you have sufficient balance
   • Verify token addresses and chain IDs
   • Ensure slippage settings are appropriate

3. Balance Checking Issues

   • Verify wallet addresses
   • Check network connectivity
   • Ensure you're using the correct chain IDs

Support

If you encounter any issues or need help: 1. Check the GitHub Issues 2. Join our Discord Community 3. Contact support at support@shogun.com