Skip to main content

​
Prerequisites

Before installing the OKX DEX SDK, ensure you have:
The SDK requires Node.js version 16.0.0 or higher. Check your version:
node --version
Download the latest version from nodejs.org
You’ll need API credentials from OKX to use the SDK:
  • API Key - Your unique API key
  • Secret Key - Your API secret for signing requests
  • Passphrase - Your API passphrase
  • Project ID - Your project identifier
Sign up for API access at OKX Developer Portal. API credentials are required for all DEX operations.
For executing swaps (not just quotes), you’ll need:
  • Private Key - For signing transactions
  • RPC URL - Connection to the blockchain network
Never commit private keys to version control. Use environment variables for sensitive data.

​
Install the Package

Install the SDK using your preferred package manager: 
npm install @okx-dex/okx-dex-sdk
The SDK is distributed as a TypeScript package with full type definitions included.

​
Install Required Dependencies

Depending on which blockchains you plan to use, install the corresponding dependencies:
For Ethereum, Base, Polygon, and other EVM-compatible chains:
npm install ethers dotenv
The SDK requires:
  • ethers (v6.14.3 or higher) - For EVM wallet and transaction handling
  • dotenv - For managing environment variables

​
Configuration

​
Environment Variables

Create a .env file in your project root with your credentials:
.env
# OKX API Credentials (Required)
OKX_API_KEY=your_api_key_here
OKX_SECRET_KEY=your_secret_key_here
OKX_API_PASSPHRASE=your_passphrase_here
OKX_PROJECT_ID=your_project_id_here

# EVM Configuration (for Ethereum, Base, Polygon, etc.)
EVM_RPC_URL=https://mainnet.base.org
EVM_WALLET_ADDRESS=0x...
EVM_PRIVATE_KEY=0x...

# Solana Configuration
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
SOLANA_WALLET_ADDRESS=...
SOLANA_PRIVATE_KEY=...

# Sui Configuration
SUI_RPC_URL=https://sui-mainnet.blockvision.org
SUI_WALLET_ADDRESS=0x...
SUI_PRIVATE_KEY=...
Security Best Practices
  • Never commit .env files to version control
  • Add .env to your .gitignore file
  • Use different credentials for development and production
  • Rotate API keys regularly

​
TypeScript Configuration

Ensure your tsconfig.json includes proper ES module support:
tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "moduleResolution": "node"
  }
}

​
Verify Installation

Create a simple test file to verify your installation:
test.ts
import { OKXDexClient } from '@okx-dex/okx-dex-sdk';
import 'dotenv/config';

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!
});

async function test() {
  // Get a simple quote to verify API connection
  const quote = await client.dex.getQuote({
    chainIndex: '8453', // Base
    fromTokenAddress: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE', // ETH
    toTokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC
    amount: '1000000000000000000', // 1 ETH
    slippagePercent: '0.5'
  });
  
  console.log('SDK is working! Quote received:');
  console.log(`${quote.data[0].fromToken.tokenSymbol} → ${quote.data[0].toToken.tokenSymbol}`);
}

test();
Run the test: 
npx ts-node test.ts
You should see output confirming the SDK can connect to OKX APIs.

​
Common Installation Issues

If you see Cannot find module errors, ensure all peer dependencies are installed:
npm install ethers @solana/web3.js @mysten/sui dotenv
If you get 401 Unauthorized or authentication errors:
  • Verify your API credentials are correct in .env
  • Ensure there are no extra spaces in credential values
  • Check that your API key has the necessary permissions
  • Verify the Project ID matches your API key
For network connection issues:
  • Check your internet connection
  • Verify RPC URLs are accessible
  • Try increasing the timeout in client configuration:
const client = new OKXDexClient({
  // ... other config
  timeout: 60000 // 60 seconds
});
If you encounter TypeScript compilation errors:
  • Ensure you’re using TypeScript 5.0 or higher
  • Check that esModuleInterop is enabled in tsconfig.json
  • Try deleting node_modules and reinstalling:
rm -rf node_modules package-lock.json
npm install

​
Advanced Configuration

​
Custom Timeout and Retries

Configure request timeout and retry behavior: 
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!,
  timeout: 30000,    // Request timeout in milliseconds
  maxRetries: 3      // Number of retry attempts
});

​
Chain-Specific Configuration

Configure wallets for multiple chains: 
import { createEVMWallet } from '@okx-dex/okx-dex-sdk/core/evm-wallet';
import { createWallet } from '@okx-dex/okx-dex-sdk/core/wallet';
import { ethers } from 'ethers';
import { Connection } from '@solana/web3.js';

// EVM wallet setup
const evmProvider = new ethers.JsonRpcProvider(process.env.EVM_RPC_URL!);
const evmWallet = createEVMWallet(process.env.EVM_PRIVATE_KEY!, evmProvider);

// Solana wallet setup
const solanaConnection = new Connection(process.env.SOLANA_RPC_URL!);
const solanaWallet = createWallet(process.env.SOLANA_PRIVATE_KEY!, solanaConnection);

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!,
  evm: {
    wallet: evmWallet
  },
  solana: {
    wallet: solanaWallet,
    computeUnits: 300000,
    maxRetries: 3
  }
});

​
Next Steps

Start building with the Quickstart guide

Learn how to execute your first token swap with real code examples

Build docs developers (and LLMs) love

Get started for freeTalk to us