Quick Start

Initialize SDK

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

// 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<SdkV2Options>	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<SdkV2Options>	Optional SDK configuration

SDK Options

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.

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<Transaction> - 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.

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.

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:

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

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

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

// 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

• GitHub Issues: Bug reports and feature requests

• Discord: Join our developer community

License

MIT License - see LICENSE file for details.