Introduction

Build Swap Applications on Sui#

There are two approaches to building swap applications with OKX DEX on Sui:

The API-first approach directly interacting with OKX DEX API endpoints
The SDK approach using the @okx-dex/okx-dex-sdk package for a simplified developer experience

This guide covers both methods to help you choose the approach that best fits your needs.

Method 1: API-first Approach#

In this guide, we will provide a use case for Sui token exchange through the OKX DEX.

1. Set Up Your Environment#

Import the necessary Node.js libraries and set up your environment variables:

// Required libraries
import { SuiWallet } from "@okxweb3/coin-sui";
import { getFullnodeUrl, SuiClient } from '@mysten/sui/client';
import { Transaction } from '@mysten/sui/transactions';
import cryptoJS from "crypto-js";
// Install dependencies
// npm i @okxweb3/coin-sui
// npm i @mysten/sui
// npm i crypto-js
// Set up environment variables
const apiKey = 'your_api_key';
const secretKey = 'your_secret_key';
const apiPassphrase = 'your_passphrase';
const projectId = 'your_project_id';
const userAddress = 'your_sui_wallet_address';
const userPrivateKey = 'your_sui_wallet_private_key';
// Constants
const SUI_CHAIN_ID = "784";
const DEFAULT_GAS_BUDGET = 50000000;
const MAX_RETRIES = 3;
// Initialize Sui client
const wallet = new SuiWallet();
const client = new SuiClient({
    url: getFullnodeUrl('mainnet')
});
// For Sui, you need to use the hexWithoutFlag format of your private key
// You can convert your key using sui keytool:
// sui keytool convert <your_sui_private_key>

2. Obtain Token Information and Swap Quote#

First, create a utility function to handle API authentication headers:

function getHeaders(timestamp, method, requestPath, queryString = "") {
    if (!apiKey || !secretKey || !apiPassphrase || !projectId) {
        throw new Error("Missing required environment variables");
    }
    const stringToSign = timestamp + method + requestPath + queryString;
    return {
        "Content-Type": "application/json",
        "OK-ACCESS-KEY": apiKey,
        "OK-ACCESS-SIGN": cryptoJS.enc.Base64.stringify(
            cryptoJS.HmacSHA256(stringToSign, secretKey)
        ),
        "OK-ACCESS-TIMESTAMP": timestamp,
        "OK-ACCESS-PASSPHRASE": apiPassphrase,
        "OK-ACCESS-PROJECT": projectId,
    };
}

Then, create a function to get token information:

async function getTokenInfo(fromTokenAddress, toTokenAddress) {
    const timestamp = new Date().toISOString();
    const requestPath = "/api/v5/dex/aggregator/quote";
    const params = {
        chainId: SUI_CHAIN_ID,
        fromTokenAddress,
        toTokenAddress,
        amount: "1000000",
        slippage: "0.5",
    };
    const queryString = "?" + new URLSearchParams(params).toString();
    const headers = getHeaders(timestamp, "GET", requestPath, queryString);
    const response = await fetch(
        
https://web3.okx.com${requestPath}${queryString}
,
        { method: "GET", headers }
    );
    if (!response.ok) {
        throw new Error(
Failed to get quote: ${await response.text()}
);
    }
    const data = await response.json();
    if (data.code !== "0" || !data.data?.[0]) {
        throw new Error("Failed to get token information");
    }
    const quoteData = data.data[0];
    return {
        fromToken: {
            symbol: quoteData.fromToken.tokenSymbol,
            decimals: parseInt(quoteData.fromToken.decimal),
            price: quoteData.fromToken.tokenUnitPrice
        },
        toToken: {
            symbol: quoteData.toToken.tokenSymbol,
            decimals: parseInt(quoteData.toToken.decimal),
            price: quoteData.toToken.tokenUnitPrice
        }
    };
}

Create a function to convert human-readable amounts to base units:

function convertAmount(amount, decimals) {
    try {
        if (!amount || isNaN(parseFloat(amount))) {
            throw new Error("Invalid amount");
        }
        const value = parseFloat(amount);
        if (value <= 0) {
            throw new Error("Amount must be greater than 0");
        }
        return (BigInt(Math.floor(value * Math.pow(10, decimals)))).toString();
    } catch (err) {
        console.error("Amount conversion error:", err);
        throw new Error("Invalid amount format");
    }
}

3. Process and Sign Transaction#

Once you have the data from the /swap endpoint, you need to process and sign the transaction:

async function executeSwap(txData, privateKey) {
    // Create transaction block
    const txBlock = Transaction.from(txData);
    txBlock.setSender(normalizedWalletAddress);
    // Set gas parameters
    const referenceGasPrice = await client.getReferenceGasPrice();
    txBlock.setGasPrice(BigInt(referenceGasPrice));
    txBlock.setGasBudget(BigInt(DEFAULT_GAS_BUDGET));
    // Build and sign transaction
    const builtTx = await txBlock.build({ client });
    const txBytes = Buffer.from(builtTx).toString('base64');
    const signedTx = await wallet.signTransaction({
        privateKey,
        data: {
            type: 'raw',
            data: txBytes
        }
    });
    if (!signedTx?.signature) {
        throw new Error("Failed to sign transaction");
    }
    return { builtTx, signature: signedTx.signature };
}

4. Execute the Transaction#

Finally, execute the signed transaction:

async function sendTransaction(builtTx, signature) {
    // Execute transaction
    const result = await client.executeTransactionBlock({
        transactionBlock: builtTx,
        signature: [signature],
        options: {
            showEffects: true,
            showEvents: true,
        }
    });
    // Wait for confirmation
    const confirmation = await client.waitForTransaction({
        digest: result.digest,
        options: {
            showEffects: true,
            showEvents: true,
        }
    });
    console.log("\nSwap completed successfully!");
    console.log("Transaction ID:", result.digest);
    console.log("Explorer URL:", 
https://suiscan.xyz/mainnet/tx/${result.digest}
);
    return result.digest;
}

5. Complete Implementation#

Here's a complete implementation putting it all together:

// swap.ts
import { SuiWallet } from "@okxweb3/coin-sui";
import { getFullnodeUrl, SuiClient } from '@mysten/sui/client';
import { Transaction } from '@mysten/sui/transactions';
import cryptoJS from "crypto-js";
import dotenv from 'dotenv';
dotenv.config();
// Environment variables
const apiKey = process.env.OKX_API_KEY;
const secretKey = process.env.OKX_SECRET_KEY;
const apiPassphrase = process.env.OKX_API_PASSPHRASE;
const projectId = process.env.OKX_PROJECT_ID;
const userAddress = process.env.WALLET_ADDRESS;
const userPrivateKey = process.env.PRIVATE_KEY;
// Constants
const SUI_CHAIN_ID = "784";
const DEFAULT_GAS_BUDGET = 50000000;
const MAX_RETRIES = 3;
// Initialize clients
const wallet = new SuiWallet();
const client = new SuiClient({
    url: getFullnodeUrl('mainnet')
});
// Normalize wallet address
const normalizedWalletAddress = userAddress;
function getHeaders(timestamp, method, requestPath, queryString = "") {
    if (!apiKey || !secretKey || !apiPassphrase || !projectId) {
        throw new Error("Missing required environment variables");
    }
    const stringToSign = timestamp + method + requestPath + queryString;
    return {
        "Content-Type": "application/json",
        "OK-ACCESS-KEY": apiKey,
        "OK-ACCESS-SIGN": cryptoJS.enc.Base64.stringify(
            cryptoJS.HmacSHA256(stringToSign, secretKey)
        ),
        "OK-ACCESS-TIMESTAMP": timestamp,
        "OK-ACCESS-PASSPHRASE": apiPassphrase,
        "OK-ACCESS-PROJECT": projectId,
    };
}
async function getTokenInfo(fromTokenAddress, toTokenAddress) {
    const timestamp = new Date().toISOString();
    const requestPath = "/api/v5/dex/aggregator/quote";
    const params = {
        chainId: SUI_CHAIN_ID,
        fromTokenAddress,
        toTokenAddress,
        amount: "1000000",
        slippage: "0.5",
    };
    const queryString = "?" + new URLSearchParams(params).toString();
    const headers = getHeaders(timestamp, "GET", requestPath, queryString);
    const response = await fetch(
        
https://web3.okx.com${requestPath}${queryString}
,
        { method: "GET", headers }
    );
    if (!response.ok) {
        throw new Error(
Failed to get quote: ${await response.text()}
);
    }
    const data = await response.json();
    if (data.code !== "0" || !data.data?.[0]) {
        throw new Error("Failed to get token information");
    }
    const quoteData = data.data[0];
    return {
        fromToken: {
            symbol: quoteData.fromToken.tokenSymbol,
            decimals: parseInt(quoteData.fromToken.decimal),
            price: quoteData.fromToken.tokenUnitPrice
        },
        toToken: {
            symbol: quoteData.toToken.tokenSymbol,
            decimals: parseInt(quoteData.toToken.decimal),
            price: quoteData.toToken.tokenUnitPrice
        }
    };
}
function convertAmount(amount, decimals) {
    try {
        if (!amount || isNaN(parseFloat(amount))) {
            throw new Error("Invalid amount");
        }
        const value = parseFloat(amount);
        if (value <= 0) {
            throw new Error("Amount must be greater than 0");
        }
        return (BigInt(Math.floor(value * Math.pow(10, decimals)))).toString();
    } catch (err) {
        console.error("Amount conversion error:", err);
        throw new Error("Invalid amount format");
    }
}
async function main() {
    try {
        const args = process.argv.slice(2);
        if (args.length < 3) {
            console.log("Usage: ts-node swap.ts <amount> <fromTokenAddress> <toTokenAddress>");
            console.log("Example: ts-node swap.ts 1.5 0x2::sui::SUI 0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC");
            process.exit(1);
        }
        const [amount, fromTokenAddress, toTokenAddress] = args;
        if (!userPrivateKey || !userAddress) {
            throw new Error("Private key or user address not found");
        }
        // Get token information
        console.log("Getting token information...");
        const tokenInfo = await getTokenInfo(fromTokenAddress, toTokenAddress);
        console.log(
From: ${tokenInfo.fromToken.symbol} (${tokenInfo.fromToken.decimals} decimals)
);
        console.log(
To: ${tokenInfo.toToken.symbol} (${tokenInfo.toToken.decimals} decimals)
);
        // Convert amount using fetched decimals
        const rawAmount = convertAmount(amount, tokenInfo.fromToken.decimals);
        console.log(
Amount in ${tokenInfo.fromToken.symbol} base units:
, rawAmount);
        // Get swap quote
        const quoteParams = {
            chainId: SUI_CHAIN_ID,
            amount: rawAmount,
            fromTokenAddress,
            toTokenAddress,
            slippage: "0.5",
            userWalletAddress: normalizedWalletAddress,
        };
        // Get swap data
        const timestamp = new Date().toISOString();
        const requestPath = "/api/v5/dex/aggregator/swap";
        const queryString = "?" + new URLSearchParams(quoteParams).toString();
        const headers = getHeaders(timestamp, "GET", requestPath, queryString);
        console.log("Requesting swap quote...");
        const response = await fetch(
            
https://web3.okx.com${requestPath}${queryString}
,
            { method: "GET", headers }
        );
        const data = await response.json();
        if (data.code !== "0") {
            throw new Error(
API Error: ${data.msg}
);
        }
        const swapData = data.data[0];
        // Show estimated output and price impact
        const outputAmount = parseFloat(swapData.routerResult.toTokenAmount) / Math.pow(10, tokenInfo.toToken.decimals);
        console.log("\nSwap Quote:");
        console.log(
Input: ${amount} ${tokenInfo.fromToken.symbol} ($${(parseFloat(amount) * parseFloat(tokenInfo.fromToken.price)).toFixed(2)})
);
        console.log(
Output: ${outputAmount.toFixed(tokenInfo.toToken.decimals)} ${tokenInfo.toToken.symbol} ($${(outputAmount * parseFloat(tokenInfo.toToken.price)).toFixed(2)})
);

        if (swapData.priceImpactPercentage) {
            console.log(
Price Impact: ${swapData.priceImpactPercentage}%
);
        }
        console.log("\nExecuting swap transaction...");
        let retryCount = 0;
        while (retryCount < MAX_RETRIES) {
            try {
                // Create transaction block
                const txBlock = Transaction.from(swapData.tx.data);
                txBlock.setSender(normalizedWalletAddress);
                // Set gas parameters
                const referenceGasPrice = await client.getReferenceGasPrice();
                txBlock.setGasPrice(BigInt(referenceGasPrice));
                txBlock.setGasBudget(BigInt(DEFAULT_GAS_BUDGET));
                // Build and sign transaction
                const builtTx = await txBlock.build({ client });
                const txBytes = Buffer.from(builtTx).toString('base64');
                const signedTx = await wallet.signTransaction({
                    privateKey: userPrivateKey,
                    data: {
                        type: 'raw',
                        data: txBytes
                    }
                });
                if (!signedTx?.signature) {
                    throw new Error("Failed to sign transaction");
                }
                // Execute transaction
                const result = await client.executeTransactionBlock({
                    transactionBlock: builtTx,
                    signature: [signedTx.signature],
                    options: {
                        showEffects: true,
                        showEvents: true,
                    }
                });
                // Wait for confirmation
                const confirmation = await client.waitForTransaction({
                    digest: result.digest,
                    options: {
                        showEffects: true,
                        showEvents: true,
                    }
                });
                console.log("\nSwap completed successfully!");
                console.log("Transaction ID:", result.digest);
                console.log("Explorer URL:", 
https://suiscan.xyz/mainnet/tx/${result.digest}
);
                process.exit(0);
            } catch (error) {
                console.error(
Attempt ${retryCount + 1} failed:
, error);
                retryCount++;
                if (retryCount === MAX_RETRIES) {
                    throw error;
                }
                await new Promise(resolve => setTimeout(resolve, 2000 * retryCount));
            }
        }
    } catch (error) {
        console.error("Error:", error instanceof Error ? error.message : "Unknown error");
        process.exit(1);
    }
}
if (require.main === module) {
    main();
}

Method 2: SDK Approach#

Using the OKX DEX SDK provides a much simpler developer experience while retaining all the functionality of the API-first approach. The SDK handles many implementation details for you, including retry logic, error handling, and transaction management.

1. Install the SDK#

npm install @okx-dex/okx-dex-sdk
or
yarn add @okx-dex/okx-dex-sdk
or
pnpm add @okx-dex/okx-dex-sdk

2. Setup Your Environment#

Create a .env file with your API credentials and wallet information:

OKX API Credentials
OKX_API_KEY=your_api_key
OKX_SECRET_KEY=your_secret_key
OKX_API_PASSPHRASE=your_passphrase
OKX_PROJECT_ID=your_project_id
Sui Configuration
SUI_WALLET_ADDRESS=your_sui_wallet_address
SUI_PRIVATE_KEY=your_sui_private_key

Remember that you need to use the hexWithoutFlag format of your SUI private key, which you can obtain using the SUI CLI:

sui keytool convert <your_sui_private_key>
```javascript

## 3. Initialize the client
Create a file for your DEX client (e.g., DexClient.ts):

```javascript
// DexClient.ts
import { OKXDexClient } from '@okx-dex/okx-dex-sdk';
import 'dotenv/config';
// Validate environment variables
const requiredEnvVars = [
    'OKX_API_KEY',
    'OKX_SECRET_KEY',
    'OKX_API_PASSPHRASE',
    'OKX_PROJECT_ID',
    'SUI_WALLET_ADDRESS',
    'SUI_PRIVATE_KEY'
];
for (const envVar of requiredEnvVars) {
    if (!process.env[envVar]) {
        throw new Error(
Missing required environment variable: ${envVar}
);
    }
}
// Initialize the client
export const client = new OKXDexClient({
    apiKey: process.env.OKX_API_KEY!,
    secretKey: process.env.OKX_SECRET_KEY!,
    apiPassphrase: process.env.OKX_API_PASSPHRASE!,
    projectId: process.env.OKX_PROJECT_ID!,
    sui: {
        privateKey: process.env.SUI_PRIVATE_KEY!,
        walletAddress: process.env.SUI_WALLET_ADDRESS!,
        connection: {
            rpcUrl: 'https://sui-mainnet.blockvision.org'
        }
    }
});

4. Create a Token Helper (Optional)#

You can create a token list helper for easy reference:

// Common tokens on Sui mainnet
export const TOKENS = {
    SUI: "0x2::sui::SUI",
    USDC: "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC"
} as const;

5. Execute a Swap With the SDK#

Create a swap execution file:

// swap.ts
import { client } from './DexClient';
import { TOKENS } from './Tokens'; // Optional, if you created the token helper
/**
Example: Execute a swap from SUI to USDC
*/
async function executeSwap() {
  try {
    if (!process.env.SUI_PRIVATE_KEY) {
      throw new Error('Missing SUI_PRIVATE_KEY in .env file');
    }
    // First, get token information using a quote
    console.log("Getting token information...");
    const fromTokenAddress = TOKENS.SUI; // Or use directly: "0x2::sui::SUI"
    const toTokenAddress = TOKENS.USDC; // Or use directly: "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC"

    const quote = await client.dex.getQuote({
        chainId: '784', // Sui chain ID
        fromTokenAddress,
        toTokenAddress,
        amount: '1000000', // Small amount for quote
        slippage: '0.5'
    });
    const tokenInfo = {
        fromToken: {
            symbol: quote.data[0].fromToken.tokenSymbol,
            decimals: parseInt(quote.data[0].fromToken.decimal),
            price: quote.data[0].fromToken.tokenUnitPrice
        },
        toToken: {
            symbol: quote.data[0].toToken.tokenSymbol,
            decimals: parseInt(quote.data[0].toToken.decimal),
            price: quote.data[0].toToken.tokenUnitPrice
        }
    };
    // Convert amount to base units
    const humanReadableAmount = 1.5; // 1.5 SUI
    const rawAmount = (humanReadableAmount * Math.pow(10, tokenInfo.fromToken.decimals)).toString();
    console.log("\nSwap Details:");
    console.log("--------------------");
    console.log(
From: ${tokenInfo.fromToken.symbol}
);
    console.log(
To: ${tokenInfo.toToken.symbol}
);
    console.log(
Amount: ${humanReadableAmount} ${tokenInfo.fromToken.symbol}
);
    console.log(
Amount in base units: ${rawAmount}
);
    console.log(
Approximate USD value: $${(humanReadableAmount * parseFloat(tokenInfo.fromToken.price)).toFixed(2)}
);
    // Execute the swap
    console.log("\nExecuting swap...");
    const swapResult = await client.dex.executeSwap({
      chainId: '784', // Sui chain ID
      fromTokenAddress,
      toTokenAddress,
      amount: rawAmount,
      slippage: '0.5', // 0.5% slippage
      userWalletAddress: process.env.SUI_WALLET_ADDRESS!
    });
    console.log('Swap executed successfully:');
    console.log("\nTransaction ID:", swapResult.transactionId);
    console.log("Explorer URL:", swapResult.explorerUrl);

    if (swapResult.details) {
        console.log("\nDetails:");
        console.log(
Input: ${swapResult.details.fromToken.amount} ${swapResult.details.fromToken.symbol}
);
        console.log(
Output: ${swapResult.details.toToken.amount} ${swapResult.details.toToken.symbol}
);
        if (swapResult.details.priceImpact) {
            console.log(
Price Impact: ${swapResult.details.priceImpact}%
);
        }
    }

    return swapResult;
  } catch (error) {
    if (error instanceof Error) {
      console.error('Error executing swap:', error.message);
      // API errors include details in the message
      if (error.message.includes('API Error:')) {
        const match = error.message.match(/API Error: (.*)/);
        if (match) console.error('API Error Details:', match[1]);
      }
    }
    throw error;
  }
}
// Run if this file is executed directly
if (require.main === module) {
  executeSwap()
    .then(() => process.exit(0))
    .catch((error) => {
      console.error('Error:', error);
      process.exit(1);
    });
}
export { executeSwap };

Additional SDK functionality

The SDK provides additional methods that simplify development:

Get a quote for a token pair

const quote = await client.dex.getQuote({
    chainId: '784',  // Sui
    fromTokenAddress: '0x2::sui::SUI', // SUI
    toTokenAddress: '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC', // USDC
    amount: '100000000',  // In base units
    slippage: '0.5'     // 0.5%
});