@shogun-sdk/intents-sdk 1.2.1 → 1.2.3

package/README.md

@@ -1,8 +1,34 @@
-# Intents SDK for Cross-Chain Swaps
+# Shogun Intents SDK
 
-A TypeScript SDK for facilitating cross-chain token swaps across multiple blockchain ecosystems. This SDK helps developers easily integrate with Intents Protocol to enable seamless cross-chain transfers and swaps.
+A comprehensive TypeScript SDK for intent-based cross-chain and single-chain token swaps across multiple blockchain ecosystems. Built on the Shogun Network, this SDK enables developers to create sophisticated trading strategies with advanced features like DCA (Dollar Cost Averaging), stop-loss, take-profit, and multi-chain routing.
 
-## Installation (To be defined and published)
+## Features
+
+### 🔄 Cross-Chain Swaps
+- **Multi-chain Support**: Seamlessly swap tokens across EVM chains (Arbitrum, Optimism, Base, Hyperliquid), Solana, and Sui
+- **Intent-based Architecture**: Express trading intentions rather than executing complex multi-step transactions
+- **Automatic Routing**: Intelligent routing through multiple DEXs and bridges for optimal execution
+- **Stablecoin Intermediary**: Uses stablecoins as intermediate assets for efficient cross-chain swaps
+
+### 📈 Single-Chain Trading
+- **Limit Orders**: Set specific price targets for token swaps
+- **DCA Orders**: Dollar Cost Averaging with configurable intervals and amounts
+- **Stop-Loss & Take-Profit**: Advanced risk management with automatic execution
+- **Extra Transfers**: Include additional token transfers in your orders
+
+### 🛡️ Advanced Risk Management
+- **Stop-Loss Protection**: Automatically sell when price drops below threshold
+- **Take-Profit Orders**: Lock in profits when price reaches target
+- **Slippage Protection**: Built-in slippage controls and price impact calculations
+- **Deadline Management**: Time-based order expiration
+
+### 🔌 Multi-Provider Integration
+- **EVM Chains**: ParaSwap integration for optimal routing
+- **Solana**: Jupiter aggregator for best prices
+- **Sui**: Aftermath and LiquidSwap integration
+- **Cross-Chain**: DefiLlama price feeds and stablecoin routing
+
+## Installation
 
 ```bash
 npm install @shogun-sdk/intents-sdk
@@ -10,114 +36,649 @@ pnpm install @shogun-sdk/intents-sdk
 yarn add @shogun-sdk/intents-sdk
 ```
 
+## Constants & Configuration
+
+The SDK provides important constants for guard addresses, stablecoins, and chain configurations:
+
+```typescript
+import {
+  // Guard addresses for different order types
+  CROSS_CHAIN_GUARD_ADDRESSES,
+  SINGLE_CHAIN_GUARD_ADDRESSES,
+  DCA_SINGLE_CHAIN_GUARD_ADDRESSES,
+  
+  // Stablecoin configurations
+  SOLANA_USDC_MINT,
+  SUI_GUARD_COLLATERAL_TYPE,
+  SUI_GUARD_STABLECOIN_TYPE,
+  
+  // Package and contract IDs
+  SUI_PACKAGE_ID,
+  PERMIT2_ADDRESS,
+  
+  // Native token addresses
+  NATIVE_SOLANA_TOKEN_ADDRESS,
+  WRAPPED_SOL_MINT_ADDRESS,
+  NATIVE_SUI_TOKEN_ADDRESS,
+  WRAPPED_ETH_ADDRESSES,
+  
+  // Utility functions
+  isNativeEvmToken,
+  
+  // Chain IDs
+  ChainID,
+} from "@shogun-sdk/intents-sdk";
+
+// Example: Get guard address for specific chain and order type
+const arbitrumCrossChainGuard = CROSS_CHAIN_GUARD_ADDRESSES[ChainID.Arbitrum];
+const baseSingleChainGuard = SINGLE_CHAIN_GUARD_ADDRESSES[ChainID.Base];
+const hyperliquidDcaGuard = DCA_SINGLE_CHAIN_GUARD_ADDRESSES[ChainID.Hyperliquid];
+
+// Example: Use Solana stablecoin configuration
+console.log('Solana USDC:', SOLANA_USDC_MINT.mint, 'Decimals:', SOLANA_USDC_MINT.decimals);
+
+// Example: Check if token is native ETH
+const isNativeEth = isNativeEvmToken('0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee');
+```
+
 ## Architecture
 
 The SDK uses a modular architecture with chain-specific implementations:
-- `EVMSDK`: Implementation for Ethereum Virtual Machine chains
-- `SolanaSDK`: Implementation for Solana blockchain
-- `SuiSDK`: Implementation for Sui blockchain
+
+- **`EVMSDK`**: Ethereum Virtual Machine chains (Arbitrum, Optimism, Base, Hyperliquid)
+- **`SolanaSDK`**: Solana blockchain with Jupiter integration
+- **`SuiSDK`**: Sui blockchain with Aftermath and LiquidSwap support
 
 ## Usage
 
-### Basic Usage
+### SDK Setup (server-side)
 
 ```typescript
 import { ChainID, EVMSDK, SolanaSDK, SuiSDK } from "@shogun-sdk/intents-sdk";
 
-// For EVM chains (Arbitrum, Optimism, Base)
+// EVM (Arbitrum, Optimism, Base, Hyperliquid)
 const evmSdk = new EVMSDK({
   chainId: ChainID.Arbitrum,
-  privateKey: '0x...', // Your private key
-  rpcProviderUrl: 'https://arbitrum-mainnet.public.blastapi.io', // Optional: Default RPC will be used if not provided
+  privateKey: '0x...',
+  rpcProviderUrl: 'https://arbitrum-mainnet.public.blastapi.io', // optional
 });
 
-// For Solana
+// Solana
 const solanaSdk = new SolanaSDK({
-  privateKey: '...', // Your private key
-  commitment: 'finalized', // Or 'confirmed'
-  rpcProviderUrl: 'https://api.mainnet-beta.solana.com', // Optional
+  privateKey: '...',
+  commitment: 'finalized', // 'confirmed' | 'finalized'
+  rpcProviderUrl: 'https://api.mainnet-beta.solana.com', // optional
 });
 
-// For Sui
+// Sui
 const suiSdk = new SuiSDK({
-  privateKey: '...', // Your private key
+  privateKey: '...',
 });
 ```
 
-### Creating and Submitting Orders
+### Cross-chain order (one call)
 
 ```typescript
-// Create and prepare a cross-chain order
-const preparedOrder = await sdk.createOrder({
+import { ChainID } from "@shogun-sdk/intents-sdk";
+
+const response = await evmSdk.createAndSendCrossChainOrder({
   sourceChainId: ChainID.Arbitrum,
-  sourceTokenAddress: '0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9',
-  sourceTokenAmount: BigInt(12000),
+  sourceTokenAddress: '0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9', // USDT
+  sourceTokenAmount: BigInt(10_000_000),
   destinationChainId: ChainID.Solana,
-  destinationTokenAddress: 'So11111111111111111111111111111111111111112',
-  destinationTokenMinAmount: BigInt(10000),
+  destinationTokenAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
   destinationAddress: '3Kiz4oBXpR9YuPNsVfvE5XnNzgwjrM9m2CbRzyyEVkpQ',
-  minStablecoinAmount: BigInt(11000),
-  deadline: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
+  deadline: Math.floor(Date.now() / 1000) + 3600,
 });
+```
 
-// Or Send the order to the auctioneer
-const response = await sdk.createAndSendOrder({
-  sourceChainId: ChainID.Arbitrum,
-  sourceTokenAddress: '0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9',
-  sourceTokenAmount: BigInt(12000),
-  destinationChainId: ChainID.Solana,
-  destinationTokenAddress: 'So11111111111111111111111111111111111111112',
-  destinationTokenMinAmount: BigInt(10000),
+### Single-chain limit order (one call)
+
+```typescript
+import { ChainID } from "@shogun-sdk/intents-sdk";
+
+const response = await solanaSdk.createAndSendSingleChainOrder({
+  chainId: ChainID.Solana,
+  amountIn: BigInt(1_000_000), // 1 SOL (6 decimals)
+  tokenIn: 'So11111111111111111111111111111111111111112',
+  tokenOut: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+  amountOutMin: BigInt(100_000_000), // 100 USDC
   destinationAddress: '3Kiz4oBXpR9YuPNsVfvE5XnNzgwjrM9m2CbRzyyEVkpQ',
-  minStablecoinAmount: BigInt(11000),
-  deadline: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
+  deadline: Math.floor(Date.now() / 1000) + 86400,
+});
+```
+
+### DCA order (EVM, one call)
+
+```typescript
+import { ChainID } from "@shogun-sdk/intents-sdk";
+
+const response = await evmSdk.createAndSendDcaSingleChainOrder({
+  chainId: ChainID.Arbitrum,
+  tokenIn: '0x82aF49447D8a07e3bd95BD0d56f35241523fBab1', // WETH
+  tokenOut: '0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9', // USDT
+  destinationAddress: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
+  startTime: Math.floor(Date.now() / 1000),
+  amountInPerInterval: BigInt(100_000_000),
+  totalIntervals: 10,
+  intervalDuration: 3600,
+  deadline: Math.floor(Date.now() / 1000) + 86400 * 7,
+});
+```
+
+### Sui Single-Chain Orders (Manual Transaction Building)
+
+```typescript
+import {
+  ChainID,
+  createSuiClient,
+  getSuiSingleChainLimitOrderTransaction,
+  getSuiSingleChainDcaOrderTransaction,
+  generateSuiLimitOrderSecretData,
+  generateSuiDcaOrderSecretData,
+  createSuiSingleChainLimitOrderIntentRequest,
+  createSuiSingleChainDcaOrderIntentRequest,
+  // Import guard addresses and stablecoin configurations
+  CROSS_CHAIN_GUARD_ADDRESSES,
+  SUI_GUARD_STABLECOIN_TYPE,
+  SUI_PACKAGE_ID,
+} from "@shogun-sdk/intents-sdk";
+
+// Create Sui client
+const client = createSuiClient();
+// Use the correct guard address from constants
+const guardAddress = CROSS_CHAIN_GUARD_ADDRESSES[ChainID.Sui];
+
+// Example: Sui Single-Chain Limit Order
+const limitOrder = await SingleChainOrder.create({
+  chainId: ChainID.Sui,
+  amountIn: BigInt(200_000),
+  tokenIn: "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
+  tokenOut: "0xdeeb7a4662eec9f2f3def03fb937a663dddaa2e215b8078a284d026b7946c270::deep::DEEP",
+  amountOutMin: BigInt(1),
+  destinationAddress: "0x...",
+  deadline: Math.floor(Date.now() / 1000) + 3600,
+  user: "0x...",
+});
+
+// Generate secret data
+const { secretNumber, secretHash } = generateSuiLimitOrderSecretData(
+  limitOrder.tokenOut,
+  limitOrder.destinationAddress,
+  undefined, // auto-generate secret number
+  limitOrder.extraTransfers
+);
+
+// Build transaction
+const tx = await getSuiSingleChainLimitOrderTransaction(
+  limitOrder,
+  secretHash,
+  guardAddress,
+  client
+);
+
+// Sign and execute transaction
+const result = await client.signAndExecuteTransaction({
+  signer: keypair,
+  transaction: tx,
+});
+
+// Create intent request for auctioneer
+const intentRequest = createSuiSingleChainLimitOrderIntentRequest({
+  user: limitOrder.user,
+  tokenIn: limitOrder.tokenIn,
+  tokenOut: limitOrder.tokenOut,
+  amountIn: limitOrder.amountIn,
+  amountOutMin: limitOrder.amountOutMin,
+  destinationAddress: limitOrder.destinationAddress,
+  deadline: limitOrder.deadline,
+  transactionHash: result.digest,
+  secretNumber,
+});
+
+// Example: Sui Single-Chain DCA Order
+const dcaOrder = await DcaSingleChainOrder.create({
+  chainId: ChainID.Sui,
+  tokenIn: "0xdeeb7a4662eec9f2f3def03fb937a663dddaa2e215b8078a284d026b7946c270::deep::DEEP",
+  tokenOut: "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
+  destinationAddress: "0x...",
+  startTime: Math.floor(Date.now() / 1000),
+  amountInPerInterval: BigInt(1_932_100),
+  totalIntervals: 2,
+  intervalDuration: 300, // 5 minutes
+  deadline: Math.floor(Date.now() / 1000) + 1200, // 20 minutes
+  user: "0x...",
 });
+
+// Generate DCA secret data
+const { secretNumber: dcaSecretNumber, secretHash: dcaSecretHash } = generateSuiDcaOrderSecretData(
+  dcaOrder.tokenOut,
+  dcaOrder.destinationAddress
+);
+
+// Build DCA transaction
+const dcaTx = await getSuiSingleChainDcaOrderTransaction(
+  dcaOrder,
+  dcaSecretHash,
+  guardAddress,
+  client
+);
+
+// Create DCA intent request
+const dcaIntentRequest = createSuiSingleChainDcaOrderIntentRequest({
+  user: dcaOrder.user,
+  tokenIn: dcaOrder.tokenIn,
+  tokenOut: dcaOrder.tokenOut,
+  amountInPerInterval: dcaOrder.amountInPerInterval,
+  totalIntervals: dcaOrder.totalIntervals,
+  intervalDuration: dcaOrder.intervalDuration,
+  amountOutMin: dcaOrder.amountOutMin,
+  destinationAddress: dcaOrder.destinationAddress,
+  startTime: dcaOrder.startTime,
+  deadline: dcaOrder.deadline,
+  transactionHash: result.digest,
+  secretNumber: dcaSecretNumber,
+});
+```
+
+### Advanced risk management (stop-loss / take-profit)
+
+```typescript
+import { ChainID } from "@shogun-sdk/intents-sdk";
+
+await evmSdk.createAndSendCrossChainOrder({
+  sourceChainId: ChainID.Base,
+  sourceTokenAddress: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913', // USDC
+  sourceTokenAmount: BigInt(1_000_000_000), // 1000 USDC (6dp)
+  destinationChainId: ChainID.Arbitrum,
+  destinationTokenAddress: '0x82aF49447D8a07e3bd95BD0d56f35241523fBab1', // WETH
+  destinationAddress: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
+  stopLossMaxOut: BigInt(2_500_000_000),
+  takeProfitMinOut: BigInt(3_500_000_000),
+  deadline: Math.floor(Date.now() / 1000) + 3600,
+});
+```
+
+### EVM Guard Addresses and Configuration
+
+When working with EVM chains, you can access guard addresses for different order types:
+
+```typescript
+import {
+  CROSS_CHAIN_GUARD_ADDRESSES,
+  SINGLE_CHAIN_GUARD_ADDRESSES,
+  DCA_SINGLE_CHAIN_GUARD_ADDRESSES,
+  PERMIT2_ADDRESS,
+  WRAPPED_ETH_ADDRESSES,
+  ChainID,
+} from "@shogun-sdk/intents-sdk";
+
+// Get guard addresses for different chains and order types
+const arbitrumCrossChain = CROSS_CHAIN_GUARD_ADDRESSES[ChainID.Arbitrum];
+const baseSingleChain = SINGLE_CHAIN_GUARD_ADDRESSES[ChainID.Base];
+const hyperliquidDca = DCA_SINGLE_CHAIN_GUARD_ADDRESSES[ChainID.Hyperliquid];
+
+// Get Permit2 address for token approvals
+const permit2Address = PERMIT2_ADDRESS[ChainID.Arbitrum];
+
+// Get wrapped ETH address for each chain
+const wrappedEthArbitrum = WRAPPED_ETH_ADDRESSES[ChainID.Arbitrum];
+const wrappedEthBase = WRAPPED_ETH_ADDRESSES[ChainID.Base];
+
+console.log('Arbitrum Cross-chain Guard:', arbitrumCrossChain);
+console.log('Base Single-chain Guard:', baseSingleChain);
+console.log('Hyperliquid DCA Guard:', hyperliquidDca);
+```
+
+### Solana Configuration
+
+For Solana integration, use the provided mint addresses and configurations:
+
+```typescript
+import {
+  SOLANA_USDC_MINT,
+  NATIVE_SOLANA_TOKEN_ADDRESS,
+  WRAPPED_SOL_MINT_ADDRESS,
+  CROSS_CHAIN_GUARD_ADDRESSES,
+  SINGLE_CHAIN_GUARD_ADDRESSES,
+  ChainID,
+} from "@shogun-sdk/intents-sdk";
+
+// Solana USDC mint configuration
+console.log('USDC Mint:', SOLANA_USDC_MINT.mint);
+console.log('USDC Decimals:', SOLANA_USDC_MINT.decimals);
+
+// Native and wrapped SOL addresses
+console.log('Native SOL:', NATIVE_SOLANA_TOKEN_ADDRESS);
+console.log('Wrapped SOL:', WRAPPED_SOL_MINT_ADDRESS);
+
+// Guard addresses for Solana
+const solanaCrossChainGuard = CROSS_CHAIN_GUARD_ADDRESSES[ChainID.Solana];
+const solanaSingleChainGuard = SINGLE_CHAIN_GUARD_ADDRESSES[ChainID.Solana];
+```
+
+### Browser integration (manual signing)
+
+For browser wallets, prepare the order and sign manually, then submit:
+
+```typescript
+import {
+  ChainID,
+  CrossChainOrder,
+  getEVMCrossChainOrderTypedData,
+} from "@shogun-sdk/intents-sdk";
+import { createWalletClient, custom } from 'viem';
+
+// 1) Build order (user address is inferred by SDK when using high-level APIs).
+const order = await CrossChainOrder.create({
+  sourceChainId: ChainID.Arbitrum,
+  sourceTokenAddress: '0xfd086...bb9',
+  sourceTokenAmount: BigInt(10_000_000),
+  destinationChainId: ChainID.Base,
+  destinationTokenAddress: '0x833589...2913',
+  destinationAddress: '0xYourDest',
+  deadline: Math.floor(Date.now() / 1000) + 3600,
+  user: '0xYourEoa', // required when not using EVMSDK.create* helpers
+});
+
+// 2) Get EIP-712 typed data + random nonce
+const { orderTypedData, nonce } = await getEVMCrossChainOrderTypedData(order);
+
+// 3) Sign with wallet client (e.g. window.ethereum)
+const walletClient = createWalletClient({ transport: custom(window.ethereum!) });
+const signature = await walletClient.signTypedData({
+  account: order.user as `0x${string}`,
+  domain: orderTypedData.domain,
+  types: orderTypedData.types,
+  primaryType: orderTypedData.primaryType,
+  message: orderTypedData.message,
+});
+
+// 4) Submit to auctioneer
+await order.sendToAuctioneer({ nonce: nonce.toString(), signature: signature.slice(2) });
 ```
 
 ## Supported Chains
 
-| Chain | Chain ID | Status |
-|-------|----------|--------|
-| Arbitrum | 42161 | ✅ Supported |
-| Optimism | 10 | ✅ Supported |
-| Base | 8453 | ✅ Supported |
-| Solana | 7565164 | ✅ Supported |
-| Sui | 101 | ✅ Supported |
+| Chain | Chain ID | Type | Features | Status |
+|-------|----------|------|----------|--------|
+| Arbitrum | 42161 | EVM | Cross-chain, Single-chain, DCA | ✅ Supported |
+| Optimism | 10 | EVM | Cross-chain, Single-chain, DCA | ✅ Supported |
+| Base | 8453 | EVM | Cross-chain, Single-chain, DCA | ✅ Supported |
+| Hyperliquid | 999 | EVM | Cross-chain, Single-chain, DCA | ✅ Supported |
+| Solana | 7565164 | Solana | Cross-chain, Single-chain, DCA | ✅ Supported |
+| Sui | 101 | Sui | Cross-chain, Single-chain, DCA | ✅ Supported |
+
+## Use Cases
+
+### 🏦 DeFi Applications
+- **Cross-chain DEX Aggregation**: Build applications that find the best prices across multiple chains
+- **Portfolio Management**: Automate rebalancing across different blockchain ecosystems
+- **Yield Farming**: Move assets between chains to optimize yield opportunities
+
+### 📊 Trading Platforms
+- **Advanced Order Types**: Implement sophisticated trading strategies with stop-loss and take-profit
+- **DCA Strategies**: Allow users to dollar-cost average into positions over time
+- **Cross-chain Arbitrage**: Execute arbitrage opportunities across different chains
+
+### 🔄 Bridge Applications
+- **Intent-based Bridging**: Let users express their destination intent rather than complex multi-step processes
+- **Multi-hop Routing**: Automatically find optimal paths through multiple chains and DEXs
+- **Stablecoin Routing**: Use stablecoins as intermediate assets for efficient cross-chain transfers
+
+### 🎯 Automated Trading
+- **Bot Integration**: Build trading bots that can operate across multiple chains
+- **Strategy Execution**: Implement complex trading strategies that span multiple ecosystems
+- **Risk Management**: Automate stop-loss and take-profit execution across chains
+
+## Order Management
+
+### Fetching User Orders
+
+```typescript
+import { fetchUserOrders } from "@shogun-sdk/intents-sdk";
+
+// Authenticate and fetch user orders
+const jwt = await evmSdk.authenticate(); // or solanaSdk.authenticate(), suiSdk.authenticate()
+const orders = await fetchUserOrders(jwt);
+
+console.log('Cross-chain orders:', orders.crossChainLimitOrders);
+console.log('Single-chain orders:', orders.singleChainLimitOrders);
+```
+
+### Canceling Orders
 
-## Example Implementation
+```typescript
+// Cancel a cross-chain order
+const cancelTxHash = await evmSdk.cancelCrossChainOrder({
+  orderId: '0x...',
+  user: '0x...',
+  tokenIn: '0x...',
+  amountIn: BigInt(1000),
+  srcChainId: ChainID.Arbitrum,
+  deadline: 1234567890,
+  minStablecoinsAmount: BigInt(1000),
+  executionDetailsHash: '0x...',
+  nonce: BigInt(123)
+});
+
+// Cancel a single-chain order
+const cancelTxHash2 = await evmSdk.cancelSingleChainOrder({
+  orderId: '0x...',
+  user: '0x...',
+  tokenIn: '0x...',
+  amountIn: BigInt(1000),
+  requestedOutput: { token: '0x...', receiver: '0x...', amount: BigInt(1000) },
+  extraTransfers: [],
+  encodedExternalCallData: '0x',
+  deadline: 1234567890,
+  nonce: BigInt(123)
+});
+
+// Solana cancellations use order public keys
+await solanaSdk.cancelCrossChainOrder('OrderPubkeyBase58');
+await solanaSdk.cancelSingleChainOrder('OrderPubkeyBase58');
 
-Here's a complete example of creating an order from Arbitrum to Solana:
+// Sui cancellations use digest/hash
+await suiSdk.cancelCrossChainOrder('TransactionDigest');
+```
+
+## Quotes & pricing
+
+You can fetch rough price/amount estimates without creating orders using the built-in quote aggregator:
+
+```typescript
+import { ChainID, QuoteProvider } from "@shogun-sdk/intents-sdk";
+
+// Cross-chain quote (uses routers with DefiLlama fallback)
+const quote = await QuoteProvider.getQuote({
+  sourceChainId: ChainID.Arbitrum,
+  destChainId: ChainID.Base,
+  amount: BigInt(10_000_000), // 10 USDT
+  tokenIn: '0xfd086...bb9',
+  tokenOut: '0x833589...2913', // USDC on Base
+});
+
+console.log({
+  amountInUsd: quote.amountInUsd,
+  estimatedAmountOut: quote.estimatedAmountOut.toString(),
+  estimatedAmountOutReduced: quote.estimatedAmountOutReduced.toString(),
+});
+```
+
+## Quote Providers
+
+The SDK integrates with multiple quote providers for optimal pricing:
+
+- **ParaSwap**: EVM chain routing and pricing
+- **Jupiter**: Solana DEX aggregation
+- **Aftermath**: Sui DEX integration
+- **LiquidSwap**: Sui native DEX
+- **DefiLlama**: Cross-chain price feeds
+
+## Error Handling
+
+```typescript
+import { ValidationError } from "@shogun-sdk/intents-sdk";
+
+try {
+  const order = await CrossChainOrder.create(params);
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.error("Order validation failed:", error.message);
+  } else {
+    console.error("Unexpected error:", error);
+  }
+}
+```
+
+## Complete example
 
 ```typescript
 import { ChainID, EVMSDK, ValidationError } from "@shogun-sdk/intents-sdk";
 
-async function createCrossChainOrder() {
+async function createAdvancedCrossChainOrder() {
   try {
     const sdk = new EVMSDK({
       chainId: ChainID.Arbitrum,
       privateKey: process.env.PRIVATE_KEY as `0x${string}`,
     });
 
-    const response = await sdk.createAndSendOrder({
+    const response = await sdk.createAndSendCrossChainOrder({
       sourceChainId: ChainID.Arbitrum,
-      sourceTokenAddress: '0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9', // USDT on Arbitrum
-      sourceTokenAmount: BigInt(10_000_000), // 10 USDT with 6 decimals
+      sourceTokenAddress: '0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9',
+      sourceTokenAmount: BigInt(10_000_000),
       destinationChainId: ChainID.Solana,
-      destinationTokenAddress: 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB', // USDT on Solana
-      destinationTokenMinAmount: BigInt(9_500_000), // 9.5 USDT minimum to receive
-      destinationAddress: '3Kiz4oBXpR9YuPNsVfvE5XnNzgwjrM9m2CbRzyyEVkpQ', // Solana destination address
-      minStablecoinAmount: BigInt(9_800_000), // Minimum stablecoin amount for protocol
-      deadline: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
+      destinationTokenAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+      destinationAddress: '3Kiz4oBXpR9YuPNsVfvE5XnNzgwjrM9m2CbRzyyEVkpQ',
+      stopLossMaxOut: BigInt(9_000_000),
+      takeProfitMinOut: BigInt(11_000_000),
+      deadline: Math.floor(Date.now() / 1000) + 3600,
     });
 
+    console.log('Order created successfully:', response);
     return response;
   } catch (error) {
     if (error instanceof ValidationError) {
       console.error("Invalid order parameters:", error.message);
     } else {
-      console.error("Failed to create and send order:", error);
+      console.error("Failed to create order:", error);
     }
     throw error;
   }
 }
-```
+```
+
+## Advanced Sui Integration
+
+The SDK provides comprehensive Sui blockchain support with both high-level SDK methods and low-level transaction builders:
+
+### High-Level SDK Usage (Recommended)
+
+```typescript
+import { ChainID, SuiSDK } from "@shogun-sdk/intents-sdk";
+
+const suiSdk = new SuiSDK({
+  privateKey: '...',
+});
+
+// Cross-chain order (one call)
+const crossChainResponse = await suiSdk.createAndSendCrossChainOrder({
+  sourceChainId: ChainID.Sui,
+  sourceTokenAddress: '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC',
+  sourceTokenAmount: BigInt(500_000),
+  destinationChainId: ChainID.Base,
+  destinationTokenAddress: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+  destinationAddress: '0xD022311DAcaa30f8396cA9d2C4662a2eF083A1Dd',
+  deadline: Math.floor(Date.now() / 1000) + 1200,
+});
+```
+
+### Low-Level Transaction Builders
+
+For advanced use cases, you can use the low-level transaction builders:
+
+```typescript
+import {
+  createSuiClient,
+  getSuiOrderTransaction,
+  getSuiSingleChainLimitOrderTransaction,
+  getSuiSingleChainDcaOrderTransaction,
+  createSuiCrossChainOrderIntentRequest,
+  generateExecutionDetailsHash,
+  // Import constants for proper configuration
+  CROSS_CHAIN_GUARD_ADDRESSES,
+  SUI_GUARD_STABLECOIN_TYPE,
+  SUI_PACKAGE_ID,
+  ChainID,
+} from "@shogun-sdk/intents-sdk";
+
+// Create client with optional custom configuration
+const client = createSuiClient();
+const guardAddress = CROSS_CHAIN_GUARD_ADDRESSES[ChainID.Sui];
+
+// Cross-chain transaction builder
+const crossChainTx = await getSuiOrderTransaction(crossChainOrder, client);
+
+// Single-chain limit order transaction builder
+const limitOrderTx = await getSuiSingleChainLimitOrderTransaction(
+  singleChainOrder,
+  secretHash,
+  guardAddress, // Using CROSS_CHAIN_GUARD_ADDRESSES[ChainID.Sui]
+  client
+);
+
+// Single-chain DCA order transaction builder
+const dcaTx = await getSuiSingleChainDcaOrderTransaction(
+  dcaOrder,
+  secretHash,
+  guardAddress, // Using CROSS_CHAIN_GUARD_ADDRESSES[ChainID.Sui]
+  client
+);
+
+// Cross-chain intent request builder
+const crossChainIntent = createSuiCrossChainOrderIntentRequest({
+  user: "0x...",
+  srcChainId: ChainID.Sui,
+  tokenIn: "0x...",
+  amountIn: BigInt(500_000),
+  minStablecoinsAmount: BigInt(1),
+  deadline: Math.floor(Date.now() / 1000) + 1200,
+  destChainId: ChainID.Base,
+  destinationAddress: "0x...",
+  tokenOut: "0x...",
+  amountOutMin: BigInt(1),
+  transactionHash: "FQWndwYJhNQUoHyvR8UuhGURC2EKx9eWErFm9Tc2DggF",
+});
+```
+
+### Sui-Specific Features
+
+- **Secret Hash Generation**: Automatic generation of cryptographic hashes for order security
+- **Gas Optimization**: Smart coin merging and splitting to minimize gas costs
+- **Native SUI Support**: Handles native SUI token transactions with gas considerations
+- **Extra Transfers**: Support for additional token transfers within orders (limited to 1 per order)
+- **Guard Contract Integration**: Seamless integration with Sui guard contracts
+- **Transaction Validation**: Built-in validation and balance checking
+
+### Available Sui Functions
+
+| Function | Description | Use Case |
+|----------|-------------|----------|
+| `getSuiOrderTransaction` | Cross-chain order transaction | Cross-chain swaps from Sui |
+| `getSuiSingleChainLimitOrderTransaction` | Single-chain limit order | Limit orders on Sui |
+| `getSuiSingleChainDcaOrderTransaction` | Single-chain DCA order | DCA strategies on Sui |
+| `createSuiCrossChainOrderIntentRequest` | Cross-chain intent payload | Manual cross-chain order submission |
+| `createSuiSingleChainLimitOrderIntentRequest` | Limit order intent payload | Manual limit order submission |
+| `createSuiSingleChainDcaOrderIntentRequest` | DCA order intent payload | Manual DCA order submission |
+| `generateSuiLimitOrderSecretData` | Secret hash for limit orders | Security for limit orders |
+| `generateSuiDcaOrderSecretData` | Secret hash for DCA orders | Security for DCA orders |
+| `generateExecutionDetailsHash` | Execution details hash | Cross-chain order verification |
+| `getSuiRandomU64Number` | Random number generation | Cryptographic randomness |
+
+## Notes
+
+- Server-side usage is recommended for EVM/Sui/Solana private keys. In browsers, use the manual signing flow with the exported helpers and never expose raw private keys.
+- Non‑EVM chains (Solana, Sui) perform on-chain preparation during create/send flows; validation is handled for you when using the high-level methods.
+- Sui orders support up to 1 extra transfer per order due to Move language constraints.
+- All Sui transaction builders accept an optional `client` parameter for better dependency injection and performance optimization.