OKX DEX Scripts

A comprehensive collection of TypeScript scripts for interacting with the OKX DEX API across Ethereum (EVM), Solana, Ton and Tron networks, supporting both single and cross-chain DEX operations.

Note: Cross-Chain API support for TON and TRON coming soon

Prerequisites

• Node v20.17.0 or higher
• git
• a Web3 wallet (e.g., OKX Wallet Extension) for API key generation

Setup

1. Clone the repository:

git clone https://github.com/okx/dex-api-library.git
cd dex-api-library

2. Install dependencies:

npm install

3. Obtain your project ID, API key, secret key, and passphrase from the OKX Developer Portal

4. Create .env file:

OKX_PROJECT_ID=YOUR_PROJECT_ID
OKX_API_KEY=YOUR_API_KEY
OKX_SECRET_KEY=YOUR_API_SECRET_KEY
OKX_API_PASSPHRASE=YOUR_API_PASSPHRASE

Note: Keep your .env file secure and never commit it to version control

Authentication

The project uses a shared authentication utility (shared.ts) for OKX API requests. The utility handles request signing and header generation:

// shared.ts
import CryptoJS from 'crypto-js';
import dotenv from 'dotenv';

dotenv.config();

export function getHeaders(timestamp: string, method: string, requestPath: string, queryString = "") {
    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;

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

The utility takes in a timestamp, method, path, and query string to generate signed API headers. Here's how to use it with a Solana quote request:

// Example: Getting a SOL to USDC quote on Solana
const params = {
    chainId: '501',              // Solana Chain ID
    fromTokenAddress: 'So11111111111111111111111111111111111111112',  // Wrapped SOL
    toTokenAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',  // USDC
    amount: '10000000000',       // Amount in lamports
    slippage: '0.1'             // 0.1% slippage tolerance
};

const timestamp = new Date().toISOString();
const requestPath = "/api/v5/dex/aggregator/quote";
const queryString = "?" + new URLSearchParams(params).toString();

// Generate headers for the request using the shared utility function
const headers = getHeaders(timestamp, "GET", requestPath, queryString);

// Make the request with the generated headers
const response = await fetch(`https://www.okx.com${requestPath}${queryString}`, {
    method: "GET",
    headers
});

The complete implementation can be found in solana-quote.ts.

Available Scripts

Run Individual Commands

To run individual commands, you can use the following scripts with the target network as an argument (e.g., evm, solana, ton, tron):

# Individual Commands
npm run quote:<target_network>                # Get swap quotes
npm run chain:<target_network>                # Get chain info
npm run tokens:<target_network>               # List supported tokens
npm run liquidity:<target_network>            # Get liquidity info
npm run bridge-tokens:<target_network>        # List bridge tokens
npm run bridges:<target_network>              # Get bridge info
npm run cross-chain-quote:<target_network>    # Get cross-chain quotes
npm run token-pairs:<target_network>          # List token pairs

Example:

npm run quote:solana

You can also run all scripts for a specific network using the following commands:

npm run quote:<target_network>

Example:

npm run all:solana

Run All Commands

npm run get-all    # Run all 'GET' scripts for EVM, Solana, Ton, and Tron

Chain IDs & Common Token Addresses

To retrieve token swap quotes, you need to provide the chain ID and token addresses. Here's the basic structure found in the 'quote' scripts:

const params = {
    chainId: '1',              // Network chain ID
    fromTokenAddress: '',      // Source token address
    toTokenAddress: '',        // Destination token address
    amount: '1000000000',      // Amount in token's smallest unit (consider decimals)
    slippage: '0.1',          // 0.1% slippage tolerance
};

Native Token Addresses

Each blockchain has a specific address to represent its native token (ETH, SOL, etc.). When swapping native tokens, use these addresses:

Chain	Native Token Address
EVM Networks	0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
Solana	11111111111111111111111111111111
Tron	T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb
Ton	EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c

EVM

All scripts in the lib/evm directory accept any valid EVM chain ID, maintaining consistent functionality across networks.

For Example:

• Ethereum ('1')
• X Layer ('196')
• Polygon ('137')
• Base ('8453')
• Arbitrum ('42161')
• You can find more supported chains in the OKX OS Documentation

Common EVM Tokens (Ethereum addresses):

const ETH = '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'  // Native ETH
const USDT = '0xdAC17F958D2ee523a2206206994597C13D831ec7' // USDT
const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' // USDC

Solana ('501')

const SOL = '11111111111111111111111111111111'                // Native SOL
const WSOL = 'So11111111111111111111111111111111111111112'   // Wrapped SOL
const USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v' // USDC

TON ('607')

const TON = 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c'  // Native TON
const USDC = 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs' // USDT

TRON ('195')

const TRX = 'T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb'  // Native TRX
const USDT = 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t' // USDT

Resources

The examples in this repository were built using the OKX DEX API Documentation.

Each API endpoint is implemented in the corresponding scripts within this repository, providing a comprehensive overview of the available functionality.

DEX Aggregator APIs

• Get Supported Chains - List all supported chains for DEX aggregation
• Get Supported Tokens - Retrieve available tokens for trading
• Get Liquidity Sources - View available liquidity sources
• Get Quote - Obtain price quotes for token swaps

Cross-Chain Bridge APIs

• Get Bridge Supported Chains - List all supported chains for cross-chain bridging
• Get Cross-Chain Tokens - View tokens available for cross-chain transfers
• Get Supported Bridge Tokens - List all tokens supported by bridges
• Get Bridge Token Pairs - View available token pairs for bridging
• Get Supported Bridges - List all supported bridge protocols
• Get Route Information - Obtain cross-chain routing details

Ways to Contribute

Join Community Discussions

Join our Discord community to help other developers troubleshoot their integration issues and share your experience with the SOR SmartContract. Our Discord is the main hub for technical discussions, questions, and real-time support.

Open an Issue

• Open issues to suggest features or report minor bugs
• Before opening a new issue, search existing issues to avoid duplicates
• When requesting features, include details about use cases and potential impact

Submit Pull Requests

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Pull Request Guidelines

• Discuss non-trivial changes in an issue first
• Include tests for new functionality
• Update documentation as needed
• Add a changelog entry describing your changes in the PR
• PRs should be focused and preferably address a single concern

Questions?

• Open a discussion issue for general questions
• Join our community for real-time discussions
• Review existing issues and discussions