OKX DEX API Essentials: Single and Cross-Chain Swaps on Avalanche C-Chain

Ready to integrate DEX aggregation and cross-chain swaps into your EVM DApp? This tutorial shows you how to interact with the OKX DEX API to perform token swaps both within a single chain and across different blockchains from the Avalanche C-Chain. Your implementation will use Web3.js and the OKX DEX API to create robust handling of quotes, approvals, and swap execution. By default, this implementation demonstrates:

• Single-chain swaps: AVAX to WAVAX on Avalanche C-Chain
• Cross-chain swaps: AVAX on Avalanche C-Chain to POL on Polygon

DEX API Utility File Overview

This tutorial focuses on implementing dexUtils.js, a utility file that contains all the necessary functions for interacting with the OKX DEX API. This file handles:

• Network and token configurations
• Header construction
• API endpoint and call construction
• Quote retrieval
• Token approvals
• Single-chain swaps
• Cross-chain swaps

Prerequisites

Before beginning, you need:

• Node.js installed (v20 or later)
• Basic knowledge of Web3 and blockchain concepts
• A wallet address and private key
• OKX API credentials (API Key, Secret Key, and Passphrase) from the OKX Developer Portal
• A Project ID from the OKX Developer Portal
• Git installed on your machine

Setup

You have two options to get started:

Option 1: Local Development

1. Clone the repository and switch to the demo branch:

git clone https://github.com/Julian-dev28/okx-os-evm-swap-app.git
cd okx-os-evm-swap-app
git checkout avalanche-demo

1. Install the dependencies:

npm install

1. Set up your environment variables:

REACT_APP_API_KEY=your_api_key
REACT_APP_SECRET_KEY=your_secret_key
REACT_APP_API_PASSPHRASE=your_passphrase
REACT_APP_PROJECT_ID=your_project_id
REACT_APP_USER_ADDRESS=your_wallet_address
REACT_APP_PRIVATE_KEY=your_private_key

Option 2: Using Replit

1. Fork the Replit project:
   OKX OS Avalanche Swap App

2. Add your environment variables in the Replit Secrets tab (located in the Tools panel):

   • Click on "Secrets"
   • Add each environment variable:
     • REACT_APP_API_KEY
     • REACT_APP_SECRET_KEY
     • REACT_APP_API_PASSPHRASE
     • REACT_APP_PROJECT_ID
     • REACT_APP_USER_ADDRESS
     • REACT_APP_PRIVATE_KEY

3. Click "Run" to start your development environment

Initial Configuration

This section shows how to set up your network configurations and token addresses needed for interacting with the OKX DEX on the Avalanche C-Chain:

import Web3 from "web3";
import cryptoJS from "crypto-js";

// RPC endpoint for Avalanche C-Chain
const avalancheCMainnet = "https://avalanche-c-chain-rpc.publicnode.com";

// OKX DEX contract address on Avalanche
// Used to show token allowance
const okxDexAddress = "0x40aA958dd87FC8305b97f2BA922CDdCa374bcD7f";

// Standard token addresses
// baseTokenAddress represents the native token (ETH/AVAX) across chains
const baseTokenAddress = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
// WAVAX token address on Avalanche
const wavaxTokenAddress = "0xb31f66aa3c1e785363f0875a1b74e27b85fd66c7";

// Environment variables
export const chainId = targetChainId;
export const fromTokenAddress = wavaxTokenAddress;
export const toTokenAddress = baseTokenAddress;
export const ratio = BigInt(3) / BigInt(2);
export const user = process.env.REACT_APP_USER_ADDRESS;
export const privateKey = process.env.REACT_APP_PRIVATE_KEY;
export const spenderAddress = okxDexAddress;

const apiKey = process.env.REACT_APP_API_KEY;
const secretKey = process.env.REACT_APP_SECRET_KEY;
const apiPassphrase = process.env.REACT_APP_API_PASSPHRASE;
const projectId = process.env.REACT_APP_PROJECT_ID;

// Initialize Web3 instance with Avalanche RPC
const web3 = new Web3(avalancheCMainnet);

// Base URL for API requests
const apiBaseUrl = "https://www.okx.com/api/v5/dex/aggregator";

/**
 * Helper function for constructing API URLs
 * @param {string} methodName - API endpoint path
 * @param {Object} queryParams - URL parameters
 * @returns {string} Complete API URL
 */
export function getAggregatorRequestUrl(methodName, queryParams) {
    return (
        apiBaseUrl +
        methodName +
        "?" +
        new URLSearchParams(queryParams).toString()
    );
}

Getting Token Quotes

The quote functionality retrieves current prices and swap routes. Here's the implementation:

Generating Headers

/**
 * Generates headers required for OKX DEX quote API calls
 * Headers include timestamp, signature, and API credentials
 * 
 * @param {Object} quoteParams - Parameters for the quote request
 * @returns {Object} Headers object with required authentication
 */
export function getQuoteHeaders(quoteParams) {
    const date = new Date();
    const timestamp = date.toISOString();

    // Create signature string following OKX API requirements
    const stringToSign =
        timestamp +
        "GET" +
        "/api/v5/dex/aggregator/quote?" +
        new URLSearchParams(quoteParams).toString();

    // Return headers with HMAC signature
    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,
    };
}

Calling the API

/**
 * Fetches a quote from the OKX DEX Aggregator
 * Used to get current prices and optimal swap routes
 * 
 * @param {Object} quoteParams - Parameters including tokens, amount, and chain
 * @returns {Promise<Object>} Quote data including price and route information
 */
export async function getQuote(quoteParams) {
    const apiRequestUrl = `${apiBaseUrl}/quote?${new URLSearchParams(quoteParams)}`;
    const response = await fetch(apiRequestUrl, {
        method: "GET",
        headers: getQuoteHeaders(quoteParams),
    });

    if (!response.ok) {
        throw new Error("Network response was not ok");
    }

    return response.json();
}

Token Approvals

Implement these approval functions for ERC20 tokens before swapping:

Generating Headers

/**
* Generates headers required for OKX DEX approve transaction API calls
* Headers include timestamp, signature, and API credentials
* 
* @param {Object} params - Parameters for the approve transaction
* @returns {Promise<Object>} Headers object with required authentication
*/
export function getApproveTransactionHeaders(params) {
   const date = new Date();
   const timestamp = date.toISOString();
   const stringToSign =
       timestamp +
       "GET" +
       "/api/v5/dex/aggregator/approve-transaction?" +
       new URLSearchParams(params).toString();

   // Check if required environment variables are present
   if (!projectId || !apiKey || !secretKey || !apiPassphrase) {
       throw new Error(
           "Missing required environment variables for API authentication"
       );
   }

   return {
       "Content-Type": "application/json",
       "OK-PROJECT-ID": projectId,
       "OK-ACCESS-KEY": apiKey,
       "OK-ACCESS-SIGN": cryptoJS.enc.Base64.stringify(
           cryptoJS.HmacSHA256(stringToSign, secretKey)
       ),
       "OK-ACCESS-TIMESTAMP": timestamp,
       "OK-ACCESS-PASSPHRASE": apiPassphrase,
   };
}

Calling the API

// ABI for ERC20 token allowance function
// This minimal ABI only includes the allowance function needed for checking token approvals
// Full ERC20 ABI not needed since we're only checking allowances
const tokenABI = [
    {
        constant: true,
        inputs: [
            {
                name: "_owner",
                type: "address",
            },
            {
                name: "_spender",
                type: "address",
            },
        ],
        name: "allowance",
        outputs: [
            {
                name: "",
                type: "uint256",
            },
        ],
        payable: false,
        stateMutability: "view",
        type: "function",
    },
];

/**
 * Checks the current allowance for a token
 * Used to determine if approval is needed before swap
 * 
 * @param {string} ownerAddress - Address of token owner
 * @param {string} spenderAddress - Address of spender (DEX contract)
 * @param {string} tokenAddress - Address of token contract
 * @returns {Promise<number>} Current allowance amount
 */
export async function getAllowance(ownerAddress, spenderAddress, tokenAddress) {
    const tokenContract = new web3.eth.Contract(tokenABI, tokenAddress);
    try {
        const allowance = await tokenContract.methods
            .allowance(ownerAddress, spenderAddress)
            .call();
        return parseFloat(allowance);
    } catch (error) {
        console.error("Failed to query allowance:", error);
        throw error;
    }
}


/**
 * Gets approval transaction data from the API
 * 
 * @param {string} chainId - Network chain ID
 * @param {string} tokenContractAddress - Token to approve
 * @param {string} approveAmount - Amount to approve
 * @returns {Promise<Object>} Approval transaction data
 */
export async function approveTransaction(chainId, tokenContractAddress, approveAmount) {
    if (!chainId || !tokenContractAddress || !approveAmount) {
        throw new Error("Missing required parameters for approval");
    }

    const params = { chainId, tokenContractAddress, approveAmount };
    const apiRequestUrl = getAggregatorRequestUrl("/approve-transaction", params);
    const headersParams = getApproveTransactionHeaders(params);

    try {
        const response = await fetch(apiRequestUrl, {
            method: "GET",
            headers: headersParams,
        });

        if (!response.ok) {
            const errorData = await response.json().catch(() => null);
            throw new Error(
                `API request failed: ${response.status} ${response.statusText}${
                    errorData ? ` - ${JSON.stringify(errorData)}` : ""
                }`
            );
        }

        const data = await response.json();

        // Validate the response data
        if (!data || !data.data || !Array.isArray(data.data) || data.data.length === 0) {
            throw new Error("Invalid response format from approval API");
        }

        return data;
    } catch (error) {
        console.error("Approval request failed:", error);
        throw error;
    }
}

/**
 * Handles the approval transaction if needed
 * Checks current allowance and submits approval transaction if necessary
 * 
 * @param {string} approveAmount - Amount to approve for spending
 * @returns {Promise<Object|null>} Transaction receipt or null if approval not needed
 */
export async function sendApproveTx(approveAmount) {
    // Skip approval for native tokens (ETH/AVAX)
    if (fromTokenAddress.toLowerCase() === baseTokenAddress.toLowerCase()) {
        return null;
    }

    const allowanceAmount = await getAllowance(
        user,
        spenderAddress,
        fromTokenAddress
    );

    // Only approve if current allowance is insufficient
    if (BigInt(allowanceAmount) < BigInt(approveAmount)) {
        const approvalResult = await approveTransaction(
            chainId,
            fromTokenAddress,
            approveAmount
        );

        // Prepare approval transaction with safety margins for gas
        const txObject = {
            nonce: await web3.eth.getTransactionCount(user),
            to: fromTokenAddress,
            gasLimit: BigInt(approvalResult.data[0].gasLimit) * BigInt(2),
            gasPrice: (BigInt(await web3.eth.getGasPrice()) * BigInt(3)) / BigInt(2),
            data: approvalResult.data[0].data,
            value: "0",
        };

        return sendSignedTransaction(txObject);
    }

    return null;
}

Single-Chain Swaps

The following implementation demonstrates executing swaps within the same chain, specifically from AVAX to WAVAX on Avalanche C-Chain:

/**
 * Helper function to get headers for swap API calls
 * @param {Object} swapParams - Swap parameters
 * @returns {Object} Headers with authentication
 */
export function getSwapHeaders(swapParams) {
    const date = new Date();
    const timestamp = date.toISOString();
    const stringToSign = 
        timestamp + 
        "GET" + 
        "/api/v5/dex/aggregator/swap?" + 
        new URLSearchParams(swapParams).toString();

    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,
    };
}

/**
 * Helper function to get swap data from API
 * @param {Object} swapParams - Swap parameters
 * @returns {Promise<Object>} Swap transaction data
 */
export async function getSwapData(swapParams) {
    const apiRequestUrl = getAggregatorRequestUrl("/swap", swapParams);
    const response = await fetch(apiRequestUrl, {
        method: "GET",
        headers: getSwapHeaders(swapParams),
    });

    if (!response.ok) {
        throw new Error("Network response was not ok");
    }

    return response.json();
}

/**
 * Executes a single-chain token swap
 * Handles the main swap transaction after approval
 * 
 * @param {Object} swapParams - Parameters for the swap
 * @returns {Promise<Object>} Transaction receipt
 */
export async function sendSwapTx(swapParams) {
    // Get swap transaction data from API
    const { data: swapData } = await getSwapData(swapParams);

    // Validate swap data
    if (!swapData || swapData.length === 0 || !swapData[0].tx) {
        throw new Error("Invalid swap data received");
    }

    const swapDataTxInfo = swapData[0].tx;
    const nonce = await web3.eth.getTransactionCount(user, "latest");

    // Prepare transaction with adjusted gas parameters for safety
    const signTransactionParams = {
        data: swapDataTxInfo.data,
        gasPrice: BigInt(swapDataTxInfo.gasPrice) * BigInt(ratio),
        to: swapDataTxInfo.to,
        value: swapDataTxInfo.value,
        gas: BigInt(swapDataTxInfo.gas) * BigInt(ratio),
        nonce,
    };

    return sendSignedTransaction(signTransactionParams);
}

Cross-Chain Swaps

The following implementation demonstrates how to execute cross-chain swaps from AVAX (Avalanche C-Chain) to MATIC (Polygon), including quote retrieval and transaction execution:

/**
 * Helper function to get headers for cross-chain quote API calls
 * @param {Object} params - Quote parameters
 * @returns {Object} Headers with authentication
 */
export function getCrossChainQuoteHeaders(params) {
    const date = new Date();
    const timestamp = date.toISOString();
    const stringToSign = 
        timestamp + 
        "GET" + 
        "/api/v5/dex/cross-chain/quote?" + 
        new URLSearchParams(params).toString();

    return {
        "Content-Type": "application/json",
        "OK-PROJECT-ID": projectId,
        "OK-ACCESS-KEY": apiKey,
        "OK-ACCESS-SIGN": cryptoJS.enc.Base64.stringify(
            cryptoJS.HmacSHA256(stringToSign, secretKey)
        ),
        "OK-ACCESS-TIMESTAMP": timestamp,
        "OK-ACCESS-PASSPHRASE": apiPassphrase,
    };
}

/**
 * Helper function to get headers for cross-chain swap API calls
 * @param {Object} params - Swap parameters
 * @returns {Object} Headers with authentication
 */
export function getCrossChainQuoteSwapHeaders(params) {
    const date = new Date();
    const timestamp = date.toISOString();
    const stringToSign = 
        timestamp + 
        "GET" + 
        "/api/v5/dex/cross-chain/build-tx?" + 
        new URLSearchParams(params).toString();

    return {
        "Content-Type": "application/json",
        "OK-PROJECT-ID": projectId,
        "OK-ACCESS-KEY": apiKey,
        "OK-ACCESS-SIGN": cryptoJS.enc.Base64.stringify(
            cryptoJS.HmacSHA256(stringToSign, secretKey)
        ),
        "OK-ACCESS-TIMESTAMP": timestamp,
        "OK-ACCESS-PASSPHRASE": apiPassphrase,
    };
}

/**
 * Gets a quote for cross-chain swaps
 * Used to estimate costs and routes across different networks
 * 
 * @param {string} amount - Amount to swap
 * @returns {Promise<Object>} Quote data for cross-chain swap
 */
export async function getCrossChainQuote(amount) {
    // Define parameters for cross-chain quote
    const quoteParams = {
        fromChainId: targetChainId,
        toChainId: 137, // Example: Polygon
        fromTokenAddress: baseTokenAddress,
        toTokenAddress: baseTokenAddress,
        amount: amount,
        slippage: "0.01", // 1% slippage tolerance
    };

    const response = await fetch(
        `${apiBaseUrl}/cross-chain/quote?${new URLSearchParams(quoteParams)}`,
        {
            method: "GET",
            headers: getCrossChainQuoteHeaders(quoteParams),
        }
    );

    return response.json();
}

/**
 * Executes a cross-chain swap transaction
 * Handles the complete cross-chain swap process
 * 
 * @param {string} amount - Amount to swap
 * @returns {Promise<Object>} Transaction receipt
 */
export async function sendCrossChainSwap(amount) {
    // Define parameters for cross-chain swap
    const quoteParams = {
        fromChainId: targetChainId,
        toChainId: 137, // Target chain (e.g., Polygon)
        fromTokenAddress: baseTokenAddress,
        toTokenAddress: baseTokenAddress,
        receiveAddress: user,
        amount: amount,
        slippage: "0.5", // Higher slippage for cross-chain
        userWalletAddress: user,
        sort: 0,
        priceImpactProtectionPercentage: "1.0", // Price impact protection
    };

    // Get swap transaction data
    const swapData = await fetch(
        `${apiBaseUrl}/cross-chain/build-tx?${new URLSearchParams(quoteParams)}`,
        {
            method: "GET",
            headers: getCrossChainQuoteSwapHeaders(quoteParams),
        }
    ).then(res => res.json());

    const swapDataTxInfo = swapData.data[0].tx;

    // Prepare transaction parameters with safety margins
    const signTransactionParams = {
        from: user,
        data: swapDataTxInfo.data,
        to: swapDataTxInfo.to,
        value: swapDataTxInfo.value,
        nonce: await web3.eth.getTransactionCount(user, "latest"),
        gasPrice: BigInt(swapDataTxInfo.gasPrice) * BigInt(ratio),
        gas: BigInt(swapDataTxInfo.gasLimit) * BigInt(ratio),
    };

    return sendSignedTransaction(signTransactionParams);
}

Signing and Sending Transactions

The sendSignedTransaction method signs and sends transactions using the user's wallet private key

/**
 * Signs and sends a transaction to the network
 * 
 * @param {Object} txObject - Transaction parameters
 * @returns {Promise<Object>} Transaction receipt
 */
export async function sendSignedTransaction(txObject) {
    const { rawTransaction } = await web3.eth.accounts.signTransaction(
        txObject,
        privateKey,
    );
    const result = await web3.eth.sendSignedTransaction(rawTransaction);
    return result;
}

Using the Functions

The flexibility of the application is demonstrated through the Params objects, swapParams, and quoteParams. These objects act as configuration points, enabling users to customize the quote requests and swaps based on their specific requirements.

For example, within the swapParams object, you'll find the following properties:

// Example params used to build tx data for single-chain swaps
const swapParams = {
  chainId: chainId,
  fromTokenAddress: fromTokenAddress,
  toTokenAddress: toTokenAddress,
  amount: amountInTokenUnits,
  slippage: '0.5',
  userWalletAddress: user
};

Here, you can specify the chainId (the blockchain network you want to use), the fromTokenAddress and toTokenAddress (the tokens you want to swap), the amount of tokens you want to swap, the acceptable slippage percentage, and your own userWalletAddress.

The quoteParams in dexUtils.js object allows you to configure the source and target blockchain networks:

// Example params used to build tx data for cross-chain swaps
  const quoteParams = {
        fromChainId: targetChainId,
        toChainId: 137,
        fromTokenAddress: baseTokenAddress,
        toTokenAddress: baseTokenAddress,
        receiveAddress: "0x85032bb06a9e5c96e3a1bb5e2475719fd6d4796e",
        amount: amount,
        slippage: "0.5",
        userWalletAddress: user,
        sort: 0,
        priceImpactProtectionPercentage: "1.0",
};

In this example, you can specify the fromChainId (the blockchain network you're starting from) and the toChainId (the blockchain network you want to swap to), as well as the fromTokenAddress and toTokenAddress. This allows you to easily move your tokens across different blockchain ecosystems, such as from Avalanche to Polygon.

Additionally, you can set the receiveAddress to designate where the swapped tokens should be sent, adjust the slippage tolerance, and even configure the priceImpactProtectionPercentage to safeguard against unfavorable price movements.

By exposing these configuration options, the application becomes highly adaptable, enabling builders to tailor the app to their users' specific needs.

You can find a working example of how these functions are implemented in components and integrated into an app by checking out the example React application.

Conclusion

Thank you for taking the time to check out this tutorial! I hope the information provided has been helpful in understanding how to leverage the power of the OKX DEX Aggregator API within your own projects.

Additional Resources

• OKX DEX API Documentation
• Web3.js Documentation
• Avalanche C-Chain Documentation

---

Found this helpful? Don't forget to check out the resources at the beginning of the article, including the boilerplate code and documentation. Join the OKX OS Community to connect with other developers, and follow Julian on Twitter for more Web3 development content!

---

This content is provided for informational purposes only and may cover products that are not available in your region. It represents the views of the author(s) and it does not represent the views of OKX. It is not intended to provide (i) investment advice or an investment recommendation; (ii) an offer or solicitation to buy, sell, or hold digital assets, or (iii) financial, accounting, legal, or tax advice. Digital asset holdings, including stablecoins and NFTs, involve a high degree of risk and can fluctuate greatly. You should carefully consider whether trading or holding digital assets is suitable for you in light of your financial condition. Please consult your legal/tax/investment professional for questions about your specific circumstances. Information (including market data and statistical information, if any) appearing in this post is for general information purposes only. While all reasonable care has been taken in preparing this data and graphs, no responsibility or liability is accepted for any errors of fact or omission expressed herein. Both OKX Web3 Wallet and OKX NFT Marketplace are subject to separate terms of service at www.okx.com.

© 2024 OKX. This article may be reproduced or distributed in its entirety, or excerpts of 100 words or less of this article may be used, provided such use is non-commercial. Any reproduction or distribution of the entire article must also prominently state: “This article is © 2024 OKX and is used with permission.” Permitted excerpts must cite to the name of the article and include attribution, for example “Integrate the OKX DEX Widget in Just 30 Minutes, Julian Martinez, © 2024 OKX.” No derivative works or other uses of this article are permitted.