2️⃣Aggregator SDK

Installation

The Aggregator is integrated within the NAVI SDK. Install it via npm:

npm i navi-sdk

Set Up NAVI-SDK Client

To use all functions of the NAVI Aggregator, you need to initialize the NAVISDKClient. For detailed steps on setting up NAVISDKClient and an account, please refer to the Getting Started Section.

1️Getting Started

Methods

Get Quote

The NAVISDKClient.getQuote method retrieves a quote and the route for swapping one coin to another.

Parameters	Type	Description
fromCoinAddress	String	The token address you are swapping from (e.g., Sui-0x2::sui::SUI).
toCoinAddress	String	The token address you want to swap to (e.g., NAVX-0xa99b8952d4f7d947ea77fe0ecdcc9e5fc0bcab2841d6e2a5aa00c3044e5544b5::navx::NAVX).
amountIn	Number	The amount of the fromCoinAddress token to swap, specified with decimals (e.g., 1e9 for 1,000,000,000).
apiKey	String(optional)	A string used for API authentication. Leave empty for limited access.
swapOptions	(optional) baseUrl: String depth: Number byAmountIn: Boolean dexList: Enum List	baseUrl - The base URL for the NAVI Aggregator API. depth - The algorithm depth for route calculation. Default is 3. byAmountIn - A boolean to indicate if the calculation is based on the input token amount. Please only use True. dexList - A list of DEXs to use for swaps. If empty, all supported DEXs will be used. Supported DEXs include: Dex.CETUS Dex.TURBOS Dex.KRIYA_V2 Dex.KRIYA_V3 Dex.AFTERMATH Dex.DEEPBOOK Dex.BLUEFIN

Example

const fromCoinAddress = '0x2::sui::SUI';
const toCoinAddress = '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC';
const amount = 1e9;
const apiKey = '{replace this if you have apiKey}'

// Use the NAVISDKClient from the setup  
const quote = await client.getQuote(fromCoinAddress: string, toCoinAddress: string, amountIn: number, apiKey:string);

Example Output

{
  amount_in: '1000000000',
  amount_out: 3711181,
  routes: [
    {
      path: [Array],
      amount_in: 1000000000,
      amount_out: 3711181,
      initial_price: 0
    }
  ],
  from: '0x2::sui::SUI',
  target: '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC'
  from_token: {
    address: '0x2::sui::SUI',
    decimals: 9,
    price: 2.2923232
  },
  to_token: {
    address: '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC'
    decimals: 6
    price: 1.001
  }
}

Swap with AccountManager

The account.swap method performs a complete swap action by using the best quote it got from the aggregator.

Parameters	Type	Description
fromCoinAddress	String	The token address you are swapping from (e.g., Sui-0x2::sui::SUI).
toCoinAddress	String	The token address you want to swap to (e.g., NAVX-0xa99b8952d4f7d947ea77fe0ecdcc9e5fc0bcab2841d6e2a5aa00c3044e5544b5::navx::NAVX).
amountIn	Number	The amount of the fromCoinAddress token to swap, specified with decimals (e.g., 1e9 for 1,000,000,000).
minAmountOut	Number	The minimum output amount of the target token, specified with decimals, used to validate slippage. (e.g., 1e9 or 1,000,000,000)
apiKey	String(optional)	A string used for API authentication. Leave empty for limited access.
swapOptions	(optional) baseUrl: String depth: Number byAmountIn: Boolean dexList: Enum List serviceFee: {fee: number, receiverAddress: String}	baseUrl - The base URL for the NAVI Aggregator API. depth - The algorithm depth for route calculation. Default is 3. byAmountIn - A boolean to indicate if the calculation is based on the input token amount. Please only use True. serviceFee: { fee: number - the transaction fee collected by third-party projects that direct users to swap through our aggregator. 0.01 represents 1% fee, receiverAddress: String - Address to receive the fee} dexList - A list of DEXs to use for swaps. If empty, all supported DEXs will be used. Supported DEXs include: Dex.CETUS Dex.TURBOS Dex.KRIYA_V2 Dex.KRIYA_V3 Dex.AFTERMATH Dex.DEEPBOOK Dex.BLUEFIN

Example

const fromCoinAddress = '0x2::sui::SUI';
const toCoinAddress = '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC';
const amountIn = 1e9;
const minAmountOut = 0.8e5; //expect at least 0.8 USDC to return;
const apiKey = '{replace this if you have apiKey}'

const transactionResult = await account.swap(fromCoinAddress, toCoinAddress, amountIn, minAmountOut, apiKey);

Example Output

{
  digest: 'J2FJmRkcUiU5bM9hQ1DDeATRCg9bqFWppKRVPZGnr7',
  effects: {
    messageVersion: 'v1',
    status: { status: 'success' },
    executedEpoch: '586',
    gasUsed: {
      computationCost: '1500000',
      storageCost: '13915600',
      storageRebate: '9201852',
      nonRefundableStorageFee: '92948'
    },
    modifiedAtVersions: [ [Object], [Object], [Object] ],
    sharedObjects: [ [Object], [Object], [Object], [Object] ],
    transactionDigest: 'J2FJmRkcUiU5bM9hQ1DDeATRCg9bqFWppKRVPZGnr7aT',
    created: [ [Object], [Object], [Object], [Object] ],
    mutated: [ [Object], [Object], [Object] ],
    gasObject: { owner: [Object], reference: [Object] },
    eventsDigest: '8xbxf1E3DJuxr7CuuWGPZ6ZXzVR6qp7f8dF34wiEmTJe',
    dependencies: [
      //.........Dependencies list
    ]
  },
  confirmedLocalExecution: false
}

Dry Run Swap with AccountManager

The account.dryRunSwap method simulates a swap without executing it on-chain, offering a risk-free way to preview the results.

Parameters	Type	Description
fromCoinAddress	String	The token address you are swapping from (e.g., Sui-0x2::sui::SUI).
toCoinAddress	String	The token address you want to swap to (e.g., NAVX-0xa99b8952d4f7d947ea77fe0ecdcc9e5fc0bcab2841d6e2a5aa00c3044e5544b5::navx::NAVX).
amountIn	Number	The amount of the fromCoinAddress token to swap, specified with decimals (e.g., 1e9 for 1,000,000,000).
minAmountOut	Number	The minimum output amount of the target token, specified with decimals, used to validate slippage. (e.g., 1e9 or 1,000,000,000)
apiKey	String(optional)	A string used for API authentication. Leave empty for limited access.
swapOptions	(optional) baseUrl: String depth: Number byAmountIn: Boolean dexList: Enum List serviceFee: {fee: number, receiverAddress: String}	baseUrl - The base URL for the NAVI Aggregator API. depth - The algorithm depth for route calculation. Default is 3. byAmountIn - A boolean to indicate if the calculation is based on the input token amount. Please only use True. serviceFee: { fee: number - the transaction fee collected by third-party projects that direct users to swap through our aggregator. 0.01 represents 1% fee, receiverAddress: String - Address to receive the fee} dexList - A list of DEXs to use for swaps. If empty, all supported DEXs will be used. Supported DEXs include: Dex.CETUS Dex.TURBOS Dex.KRIYA_V2 Dex.KRIYA_V3 Dex.AFTERMATH Dex.DEEPBOOK Dex.BLUEFIN

const fromCoinAddress = '0x2::sui::SUI';
const toCoinAddress = '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC';
const amountIn = 1e9;
const minAmountOut = 0.8e5; //expect at least 0.8 USDC to return
const apiKey = '{replace this if you have apiKey}'

const dryRunResult = await account.dryRunSwap(fromCoinAddress, toCoinAddress, amountIn, minAmountOut, apiKey);

Example Output

{
  effects: {
    messageVersion: 'v1',
    status: { status: 'success' },
    executedEpoch: '586',
    gasUsed: {
      computationCost: '1500000',
      storageCost: '13915600',
      storageRebate: '11158092',
      nonRefundableStorageFee: '112708'
    },
    modifiedAtVersions: [ [Object], [Object], [Object], [Object], [Object] ],
    sharedObjects: [ [Object], [Object], [Object], [Object] ],
    transactionDigest: 'CS2VpqQiknUq476Wf1fKoZqzcNxqe4DNPRXaAwf',
    created: [ [Object], [Object], [Object], [Object] ],
    mutated: [ [Object], [Object], [Object] ],
    deleted: [ [Object], [Object] ],
    gasObject: { owner: [Object], reference: [Object] },
    eventsDigest: 'EAex75b4Kk1w3in5hZvV37FD5kb4iz3sPmkiksW5',
    dependencies: [
      //.......Dependencies list
    ]
  },
  events: [
    //........Event Emitted
  ],
  objectChanges: [
    //........Object Changes
  ],
  balanceChanges: [
    {
      owner: [Object],
      coinType: '0x2::sui::SUI',
      amount: '-1004257508'
    },
    {
      owner: [Object],
      coinType: '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC',
      amount: '3717038'
    }
  ],
  input: {
    messageVersion: 'v1',
    transaction: {
      kind: 'ProgrammableTransaction',
      inputs: [Array],
      transactions: [Array]
    },
    sender: 'userAddress',
    gasData: {
      payment: [Array],
      owner: 'userAddress',
      price: '750',
      budget: '7941868'
    }
  }
}

Build Swap PTB from Quote

If you'd like to create your own PTB code using a quote, we've provided an easy-to-use interface to help you get started.

Parameters	Type	Description
userAddress	String	The user Address that will run the PTB
txb	Transaction Block from Sui SDK	Sui programmable transaction blocks
minAmountOut	Number	The minimum output amount of the target token, specified with decimals, used to validate slippage. (e.g., 1e9 or 1,000,000,000)
coinIn	Transaction Object	The transaction Object of Coin that will be swapped. (e.g., const coinIn = txb.splitCoins(txb.gas, [amount]);)
quote	Quote	Quote from getQuote()
referral	Number	Used to identify the swap service provider, default to 0
ifPrint	Boolean	Used to print the swap information, default to true
apiKey	String(optional)	A string used for API authentication. Leave empty for limited access.
swapOptions	(optional) baseUrl: String depth: Number byAmountIn: Boolean dexList: Enum List serviceFee: {fee: number, receiverAddress: String}	baseUrl - The base URL for the NAVI Aggregator API. depth - The algorithm depth for route calculation. Default is 3. byAmountIn - A boolean to indicate if the calculation is based on the input token amount. Please only use True. serviceFee: { fee: number - the transaction fee collected by third-party projects that direct users to swap through our aggregator. 0.01 represents 1% fee, receiverAddress: String - Address to receive the fee} dexList - A list of DEXs to use for swaps. If empty, all supported DEXs will be used. Supported DEXs include: Dex.CETUS Dex.TURBOS Dex.KRIYA_V2 Dex.KRIYA_V3 Dex.AFTERMATH Dex.DEEPBOOK Dex.BLUEFIN

This function returns a coin object from the transaction, which can be used in further PTB code.

import { Transaction } from "@mysten/sui/transactions";
import { NAVISDKClient } from "navi-sdk";
import { buildSwapPTBFromQuote } from "navi-sdk/dist/libs/Aggregator";

const account = client.accounts[0];
const fromCoinAddress = '0x2::sui::SUI';
const toCoinAddress = '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC';
const amount = 1e9;
const minAmountOut = 1e5;

const txb = new Transaction();
const coinIn = txb.splitCoins(txb.gas, [amount]);

const quote = await client.getQuote(fromCoinAddress: string, toCoinAddress: string, amountIn: number, apiKey:string);
const coinB = await buildSwapPTBFromQuote(account.address, txb, minAmountOut, coinIn, quote);

//..Futher PTB Code

Swap PTB

If you'd like to create your own PTB code without managing a quote, we've provided an easy-to-use interface for developers to customize swap fee and receiving address.

Parameters	Type	Description
userAddress	String	The user Address that will run the PTB
txb	Transaction Block from Sui SDK	Sui programmable transaction blocks
fromCoinAddress	String	The token address you are swapping from (e.g., Sui-0x2::sui::SUI).
toCoinAddress	String	The token address you want to swap to (e.g., NAVX-0xa99b8952d4f7d947ea77fe0ecdcc9e5fc0bcab2841d6e2a5aa00c3044e5544b5::navx::NAVX).
coin	Transaction Object	The transaction Object of Coin that will be swapped. (e.g., const coinIn = txb.splitCoins(txb.gas, [amount]);)
amountIn	Number	The amount of the fromCoinAddress token to swap, specified with decimals (e.g., 1e9 for 1,000,000,000).
minAmountOut	Number	The minimum output amount of the target token, specified with decimals, used to validate slippage. (e.g., 1e9 or 1,000,000,000)
apiKey	String(optional)	A string used for API authentication. Leave empty for limited access.
swapOptions	(optional) baseUrl: String depth: Number byAmountIn: Boolean dexList: Enum List serviceFee: {fee: number, receiverAddress: String}	baseUrl - The base URL for the NAVI Aggregator API. depth - The algorithm depth for route calculation. Default is 3. byAmountIn - A boolean to indicate if the calculation is based on the input token amount. Please only use True. serviceFee: { fee: number - the transaction fee collected by third-party projects that direct users to swap through our aggregator. 0.01 represents 1% fee, receiverAddress: String - Address to receive the fee} dexList - A list of DEXs to use for swaps. If empty, all supported DEXs will be used. Supported DEXs include: Dex.CETUS Dex.TURBOS Dex.KRIYA_V2 Dex.KRIYA_V3 Dex.AFTERMATH Dex.DEEPBOOK Dex.BLUEFIN

This function returns a coin object from the transaction after swapping, which can be used in further PTB code.

import { Transaction } from "@mysten/sui/transactions";
import { NAVISDKClient } from "navi-sdk";
import { buildSwapPTBFromQuote } from "navi-sdk/dist/libs/Aggregator";

const account = client.accounts[0];
const from = '0x2::sui::SUI';
const to = '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC';
const amount = 1e9;
const minAmountOut = 1e5;

const txb = new Transaction();
const coinIn = txb.splitCoins(txb.gas, [amount]);

const coinB = swapPTB(account.address, txb, from, to, coinIn, amount, minAmountOut, "", {
    feeOption: {
        fee: 0.1, //represents 10% of fee
        receiverAddress: "0xa" //receiver address
    }
}) //Swapped coin after fee and swap

await txb.transferObjects([coinB], account.address);
await SignAndSubmitTXB(txb, account.client, account.keypair)

Swap fee will be processed in voloSui

Demo

We’ve prepared a demo to help developers get started quickly and easily.

Developer Links​

🛩️NAVI SDK