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
PreviousGetting StartedNextAggregator API

Last updated