# Quick Start #### Initialize SDK ```typescript import { initMainnetAggV2SDK, initMainnetAggV2SDKWithMultiProviders, AggProvider } from '@ferra-labs/aggregator'; // Single provider initialization const sdk = initMainnetAggV2SDK( AggProvider.CETUS, // Primary provider "0xYourSuiAddress" // Sender address ); // Multi-provider initialization (for best price comparison) const multiSdk = initMainnetAggV2SDKWithMultiProviders( [AggProvider.CETUS, AggProvider.FLOWX, AggProvider.BLUEFIN], "0xYourSuiAddress" ); ``` #### Get Quote and Execute Swap ```typescript // 1. Get quote from provider const quote = await sdk.Quoter.getQuote({ fromType: "0x2::sui::SUI", targetType: "0xUSdcCoinType...", amount: "1000000000", // 1 SUI (9 decimals) }); // 2. Execute swap const tx = await sdk.AggSwap.swap( { fromType: "0x2::sui::SUI", targetType: "0xUsdcCoinType...", amountIn: "1000000000", amountOut: quote.amountOut, quote: { provider: EProvider.CETUS, quote: quote.routeData, }, }, 50 // slippage: 50 bps = 0.5% ); // 3. Sign and execute transaction const result = await suiClient.signAndExecuteTransaction({ transaction: tx, signer: keypair, }); ``` ### API Reference #### SDK Initialization **`initMainnetAggV2SDK(provider, sender, sdkOptions?)`** Initialize SDK with a single provider. | Parameter | Type | Description | | ------------ | ----------------------- | ---------------------------------------- | | `provider` | `AggProvider` | Primary provider (CETUS, FLOWX, BLUEFIN) | | `sender` | `string` | Sender's Sui address | | `sdkOptions` | `Partial` | Optional SDK configuration | **`initMainnetAggV2SDKWithMultiProviders(providers, sender, sdkOptions?)`** Initialize SDK with multiple providers for best price discovery. | Parameter | Type | Description | | ------------ | ----------------------- | ---------------------------- | | `providers` | `AggProvider[]` | Array of providers to enable | | `sender` | `string` | Sender's Sui address | | `sdkOptions` | `Partial` | Optional SDK configuration | #### SDK Options ```typescript interface SdkV2Options { providers: { cetus: { disabled: boolean }; bluefin7k: { disabled: boolean }; flowx: { disabled: boolean }; }; slippageBps: number; // Default slippage in basis points fullNodeUrl: string; // Sui RPC endpoint agg_pkg: { package_id: string; // Ferra aggregator package ID published_at: string; config: { config: string; // Global config object ID }; }; sender: string; // Sender address } ``` #### AggSwapV2Module **`swap(params, slippageBps?)`** Execute a swap transaction. ```typescript interface SwapV2Params { fromType: string; // Input coin type targetType: string; // Output coin type amountIn: string; // Input amount (smallest unit) amountOut: string; // Expected output amount quote: { provider: EProvider; // CETUS, FLOWX, or BLUEFIN7K quote: RouterDataV3 | FlowxQuoteResponse | QuoteResponse; }; } ``` **Returns**: `Promise` - Sui transaction ready for signing **`swapCustomizable(params, slippageBps?, tx?)`** Execute a swap with customizable output handling. Returns both the transaction and output coin for further composition. ```typescript interface SwapCustomizableOutput { tx: Transaction; coinOut: TransactionObjectArgument; } ``` **Use case**: When you need to use the output coin in subsequent transaction steps (e.g., providing liquidity, staking). **`swapWithInputCustomizable(params, slippageBps?, tx?)`** Execute a swap with both input and output coins customizable. Input coin is passed as `TransactionObjectArgument`. ```typescript interface SwapV2ParamsInputCustomizable { fromType: string; targetType: string; amountIn: TransactionObjectArgument; // Pre-split coin object amountOut: string; quote: ProviderQuote; } ``` **Use case**: When input coin comes from a previous transaction step. ### Transaction Composition Example Build complex DeFi transactions by chaining swap operations: ```typescript import { Transaction } from "@mysten/sui/transactions"; // Initialize transaction const tx = new Transaction(); // Step 1: Swap SUI -> USDC const { tx: tx1, coinOut: usdcCoin } = await sdk.AggSwap.swapCustomizable( { fromType: "0x2::sui::SUI", targetType: USDC_TYPE, amountIn: "1000000000", amountOut: usdcQuote.amountOut, quote: { provider: EProvider.CETUS, quote: usdcQuote }, }, 50, tx ); // Step 2: Use USDC output for another swap or DeFi operation const { tx: tx2, coinOut: finalCoin } = await sdk.AggSwap.swapWithInputCustomizable( { fromType: USDC_TYPE, targetType: TARGET_TYPE, amountIn: usdcCoin, // Use output from previous swap amountOut: targetQuote.amountOut, quote: { provider: EProvider.FLOWX, quote: targetQuote }, }, 50, tx1 ); // Step 3: Transfer final coin to recipient tx2.transferObjects([finalCoin], "0xRecipientAddress"); // Execute composed transaction const result = await suiClient.signAndExecuteTransaction({ transaction: tx2, signer: keypair, }); ``` ### Provider Selection Guide | Provider | Best For | Considerations | | ----------- | -------------------------- | ------------------------------- | | **Cetus** | Large trades, stable pairs | Deep liquidity, reliable routes | | **FlowX** | DEX aggregation | Multi-hop optimization | | **Bluefin** | Perpetuals, derivatives | Specialized markets | ### Configuration #### Mainnet Configuration ```typescript const mainnetConfig: SdkV2Options = { providers: { cetus: { disabled: false }, bluefin7k: { disabled: false }, flowx: { disabled: false }, }, slippageBps: 100, // 1% default slippage fullNodeUrl: "https://wallet-rpc.mainnet.sui.io/", agg_pkg: { package_id: "0x38fa90a77d04e79ca45add358fd5dcf16ed02228b936b9d3113253bbedbff504", published_at: "0x38fa90a77d04e79ca45add358fd5dcf16ed02228b936b9d3113253bbedbff504", config: { config: "0x856305e41f85e28e6745778cf40e4f5b8cfb3ca635a28b8cf71cb3c054c8a07d", }, }, sender: "", }; ``` #### Custom RPC Endpoint ```typescript const sdk = initMainnetAggV2SDK( AggProvider.CETUS, senderAddress, { fullNodeUrl: "https://your-custom-rpc.com", slippageBps: 50, // 0.5% slippage } ); ``` ### Migration from V1 #### Key Changes | V1 | V2 | | -------------------- | -------------------------- | | Internal routing | External provider quotes | | Single DEX support | Multi-provider aggregation | | `FerraAggregatorSDK` | `FerraAggregatorV2SDK` | | `initMainnetSDK()` | `initMainnetAggV2SDK()` | #### Migration Steps 1. Update imports to use V2 SDK 2. Initialize with provider selection 3. Fetch quotes from external providers 4. Pass provider-specific quote data to swap functions ```typescript // V1 (deprecated) const sdk = initMainnetSDK(); const tx = await sdk.Swap.swap(params); // V2 (current) const sdk = initMainnetAggV2SDK(AggProvider.CETUS, sender); const quote = await sdk.Quoter.getQuote(params); const tx = await sdk.AggSwap.swap({ ... params, quote: quote, }); ``` ### Support * **Documentation**: [docs.ferra.ag](https://docs.ferra.ag/) * **GitHub Issues**: Bug reports and feature requests * **Discord**: Join our developer community ### License MIT License - see LICENSE file for details. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.ferra.ag/integration/aggregator-v2/typescript-sdk/quick-start.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.