sui-defi-sdk

A TypeScript SDK for building CLMM swap transactions on Sui, supporting multiple DEX protocols through a unified interface.

Installation

pnpm add @tradeport/sui-defi-sdk

Usage

ManualQuoter

The ManualQuoter lets you construct swap transactions from pre-computed route data. You provide the pool IDs, token types, amounts, and swap direction for each hop and the SDK builds the on-chain transaction.

import { getFullnodeUrl, SuiClient } from "@mysten/sui/client";
import { Protocol, SwapBuilder, ManualQuoter, ManualQuoteParam } from "@byzantion-xyz/sui-defi-sdk";

const client = new SuiClient({ url: getFullnodeUrl("mainnet") });

const manualQuote: ManualQuoteParam = {
  tokenIn: "0x2::sui::SUI",
  tokenOut: "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
  amountIn: "100000000",   // 0.1 SUI (9 decimals)
  amountOut: "350000",      // minimum acceptable output (6 decimals for USDC)
  paths: [
    // Each inner array is a route (a sequence of hops).
    // Multiple routes split the trade across pools.
    [{
      poolId: "0x51e883ba7c0b566a26cbc8a94cd33eb0abd418a77cc1e60ad22fd9b1f29cd2ab",
      protocolName: Protocol.CETUS,
      tokenIn: "0x2::sui::SUI",
      tokenOut: "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
      amountIn: "100000000",
      amountOut: "350000",
      extra: {
        // true if swapping token X → Y in the pool, false for Y → X.
        // Check the pool's type params to determine which token is X and which is Y.
        swapXToY: false,
      },
    }],
  ],
  protocolConfig: {
    // See "Protocol Configs" section below
    [Protocol.CETUS.toLowerCase()]: {
      globalConfigObjectId: "0xdaa46292632c3c4d8f31f23ea0f9b36a28ff3677e9684980e4438403a67a3d8f",
      wrappedRouterPackageId: "0x62a97a4997a54999ac817621c43433c482392698061c9d6aef867cac5d30d838",
    },
  },
};

const quoter = new ManualQuoter("mainnet");
const routes = quoter.fromRawQuote(manualQuote);
const builder = new SwapBuilder("mainnet", routes.routes);

const tx = await builder
  .sender("0xYOUR_ADDRESS")
  .slippage(1000) // 0.1% (out of 1_000_000 BPS)
  .build()
  .buildTransaction({ client });

// Sign and execute `tx` with your keypair

Multi-hop example

Chain multiple pools in a single route to swap through an intermediate token:

const manualQuote: ManualQuoteParam = {
  tokenIn: "0x2::sui::SUI",
  tokenOut: "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
  amountIn: "100000000",
  amountOut: "1",
  paths: [
    // Single route with two hops: SUI → WAL → USDC
    [
      {
        poolId: "0xf4238fa592c9ed7f148fd091cb2c4147cb15ad81b797115ce42971923ebf6e4c",
        protocolName: Protocol.CETUS,
        tokenIn: "0x2::sui::SUI",
        tokenOut: "0x356a26eb9e012a68958082340d4c4116e7f55615cf27affcff209cf0ae544f59::wal::WAL",
        amountIn: "100000000",
        amountOut: "500000000",
        extra: { swapXToY: false },
      },
      {
        poolId: "0xa8479545ff8a71659a7a3b5a2149cab68c5468a67aab8b18f62e4b42623e341e",
        protocolName: Protocol.BLUEFIN,
        tokenIn: "0x356a26eb9e012a68958082340d4c4116e7f55615cf27affcff209cf0ae544f59::wal::WAL",
        tokenOut: "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
        amountIn: "500000000",
        amountOut: "1",
        extra: { swapXToY: true },
      },
    ],
  ],
  protocolConfig: {
    [Protocol.CETUS.toLowerCase()]: {
      globalConfigObjectId: "0xdaa46292632c3c4d8f31f23ea0f9b36a28ff3677e9684980e4438403a67a3d8f",
      wrappedRouterPackageId: "0x62a97a4997a54999ac817621c43433c482392698061c9d6aef867cac5d30d838",
    },
    [Protocol.BLUEFIN.toLowerCase()]: {
      globalConfigObjectId: "0x03db251ba509a8d5d8777b6338836082335d93eecbdd09a11e190a1cff51c352",
      wrappedRouterPackageId: "0xf4f9cb1af69b44abdcc43f68aad3fcbde27600d5019469f1759b3b200e8ca896",
    },
  },
};

Path extra fields

Each protocol path requires an extra object. The common field across all protocols is swapXToY (the swap direction in the pool). Some protocols require additional fields:

| Protocol | Extra fields | |---|---| | Cetus, Bluefin, Magma, Momentum, Full Sail | swapXToY | | Turbos | swapXToY, poolStructTag (full Pool<X, Y, Fee> type) | | FlowX V3, Tradeport | swapXToY, fee (pool fee tier) |

All protocols also accept optional nextStateSqrtRatioX64, minSqrtPriceHasLiquidity, and maxSqrtPriceHasLiquidity for precise price limit control. When omitted, the SDK defaults to the full tick range.

Protocol Configs (Mainnet)

These object IDs are suitable for proof-of-concept use. In production, protocol configs should come from a central, versioned source so they stay current if protocols upgrade their packages.

Cetus

[Protocol.CETUS.toLowerCase()]: {
  globalConfigObjectId: "0xdaa46292632c3c4d8f31f23ea0f9b36a28ff3677e9684980e4438403a67a3d8f",
  wrappedRouterPackageId: "0x62a97a4997a54999ac817621c43433c482392698061c9d6aef867cac5d30d838",
}

Bluefin

[Protocol.BLUEFIN.toLowerCase()]: {
  globalConfigObjectId: "0x03db251ba509a8d5d8777b6338836082335d93eecbdd09a11e190a1cff51c352",
  wrappedRouterPackageId: "0xf4f9cb1af69b44abdcc43f68aad3fcbde27600d5019469f1759b3b200e8ca896",
}

Turbos

[Protocol.TURBOS_FIANCE.toLowerCase()]: {
  packageId: "0x91bfbc386a41afcfd9b2533058d7e915a1d3829089cc268ff4333d54d6339ca1",
  versionedObjectId: "0xf1cf0e81048df168ebeb1b8030fad24b3e0b53ae827c25053fff0779c1445b6f",
  wrappedRouterPackageId: "0x8b14f4351bb342b81c27fce2fe6d0f56b98288dc88fbe60b28b26d804b25941a",
}

FlowX V3

[Protocol.FLOWX_V3.toLowerCase()]: {
  poolRegistryObjectId: "0x27565d24a4cd51127ac90e4074a841bbe356cca7bf5759ddc14a975be1632abc",
  versionedObjectId: "0x67624a1533b5aff5d0dfcf5e598684350efd38134d2d245f475524c03a64e656",
  wrappedRouterPackageId: "0x1d200e5a0709f84736d1ec06a5e9a961f4fa86f2d43d15e3a0441ae152440ede",
}

Magma Finance

[Protocol.MAGMA_FINANCE.toLowerCase()]: {
  globalConfigObjectId: "0x4c4e1402401f72c7d8533d0ed8d5f8949da363c7a3319ccef261ffe153d32f8a",
  wrappedRouterPackageId: "0xa448a10cebbe70503a46bd2c13c3cea3159e39aa5ad5ed99c2d87aa05b691ada",
}

Momentum Finance

[Protocol.MOMENTUM_FINANCE.toLowerCase()]: {
  versionObjectId: "0x2375a0b1ec12010aaea3b2545acfa2ad34cfbba03ce4b59f4c39e1e25eed1b2a",
  wrappedRouterPackageId: "0xc47d3016b34748859e6015bfccc5cddb38ac415918980522c9668f1769b8db67",
}

Full Sail

[Protocol.FULL_SAIL.toLowerCase()]: {
  globalConfigObjectId: "0xe93baa80cb570b3a494cbf0621b2ba96bc993926d34dc92508c9446f9a05d615",
  priceProviderObjectId: "0x854b2d2c0381bb656ec962f8b443eb082654384cf97885359d1956c7d76e33c9",
  rewarderGlobalVaultObjectId: "0xfb971d3a2fb98bde74e1c30ba15a3d8bef60a02789e59ae0b91660aeed3e64e1",
  statsObjectId: "0x6822a33d1d971e040c32f7cc74507010d1fe786f7d06ab89135083ddb07d2dc2",
  wrappedRouterPackageId: "0x6a93f5e42001efd713861e193fcbc9704aeb08efe2a1ce2864050fe0bc359620",
}