> For the complete documentation index, see [llms.txt](https://docs.ferra.ag/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ferra.ag/integration/aggregator-v2/typescript-sdk/quick-start.md).

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

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

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