1.2.24 • Published 3 months ago
@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
- Always Check Quote Status
const quote = await client.fetchQuote({...});
if (!quote.status) {
// Handle error
return;
}
- Use TypeScript for Better Type Safety
import { ShogunQuoteApiClient, QuoteParams } from '@shogun-sdk/root';
const params: QuoteParams = {
// ... parameters
};
- Implement Proper Error Handling
try {
const quote = await client.fetchQuote({...});
// Handle success
} catch (error) {
// Handle errors
}
- 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:
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
Quote Failures
- Check if you have sufficient balance
- Verify token addresses and chain IDs
- Ensure slippage settings are appropriate
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