OKX MCP SERVER

Revolutionary gasless DEX swapping powered by OKX DEX API + Biconomy MEE - Swap without holding ETH for gas fees!

📝 Note: Swapping occurs only for OKX supported networks and tokens.

📦 Package Available on NPM

Live Package: https://www.npmjs.com/package/okx-mcp-server

Quick Setup for Claude Desktop:

{
  "mcpServers": {
    "okx-dex": {
      "command": "npx",
      "args": ["-y", "okx-mcp-server"],
      "env": {
        "PRIVATE_KEY": "0xxxx",
        "OKX_API_KEY": "xxx",
        "OKX_SECRET_KEY": "xxxA1",
        "OKX_PASSPHRASE": "xxx"
      }
    }
  }
}

Related MCP server: Universal Crypto MCP

🎯 What Problem Are We Solving?

The DeFi Gas Problem:

• ❌ Need ETH on every chain for gas fees

• ❌ Complex multi-step approval processes

• ❌ Failed transactions waste gas

• ❌ Cross-chain operations require multiple signatures

Our Solution:

✅ Gasless Swaps: Use your source tokens to pay for ALL transaction costs
✅ One-Click Multi-Chain: Single signature for complex cross-chain flows
✅ Natural Language: "Swap 10 USDC to WETH on Base" - that's it!
✅ MEE Orchestration: Smart execution across 50+ DEX sources

🌟 Key Features

✅ Gasless Swaps: No ETH needed for gas fees
✅ Multi-Chain: Ethereum, Base, Optimism, xLayer
✅ Best Prices: OKX DEX aggregates 50+ DEX sources
✅ Natural Language: "Swap 10 USDC to WETH on Base"
✅ Real-time Quotes: Get current market prices
✅ Portfolio Management: Check balances across chains

🏆 Hackathon Tracks

Smart Account UX & Abstraction (TRACK)

• Revolutionary Gas Abstraction: Use ANY token to pay gas on ANY chain - no ETH required

• Biconomy MEE Integration: Superior to ERC-4337 with true composability and cross-chain orchestration

• One-Signature Multi-Chain: Execute complex flows across Ethereum, Base, Optimism with single approval

• Natural Language Interface: "Swap 10 USDC to WETH on Base" via Claude Desktop

DeFi Innovation (TRACK)

• 50+ DEX Aggregation: OKX DEX routes across Uniswap, SushiSwap, 1inch for best prices

• Gasless Trading: Eliminates the #1 barrier to DeFi adoption

• Cross-Chain Liquidity: Access unified liquidity pools across all supported networks

• Professional Tools: Real-time quotes, slippage protection, transaction tracking

Autonomous Apps(TRACK)

• MEE Orchestration: Self-executing transaction flows with conditional logic

• Intelligent Routing: MEE optimizes gas costs and execution paths automatically

Key MEE Advantages Over ERC-4337:

Impact: 95% reduction in user steps, 100% elimination of native gas requirements, zero learning curve with natural language commands.

🖼️ Gallery of the Project

Here are some screenshots and visuals from the project in action:

🎨 Superior User Experience

Before (Traditional DEX):

1. Check ETH balance for gas ❌
2. Approve token spending ⏳
3. Wait for confirmation ⏳  
4. Execute swap transaction ⏳
5. Wait for confirmation ⏳
6. Pay gas in native ETH ❌

After (Our MEE Implementation):

1. "Swap 10 USDC to WETH on Base" ✅
2. Single signature ✅
3. MEE handles everything ✅
4. Gas paid from USDC ✅
5. Done! 🎉

🆚 MEE vs ERC-4337: Why We Chose Superior Technology

1. True Composability

2. Cross-Chain Orchestration

3. Universal Gas Abstraction

4. Advanced Automation

📋 Available MCP Tools

Once deployed, you'll have access to these tools in Claude:

1. get_supported_networks_okx - List supported networks

2. get_supported_tokens_okx - Get tokens for a network

3. get_account_balance_evm - Check wallet balances

4. get_token_swap_quote_okx - Get swap quotes/prices

5. swap_tokens_okx_mee - Execute gasless token swaps (using Biconomy MEE)

6. transfer_tokens_evm - Transfer tokens

7. get_transaction_evm - Check transaction status

🚀 How to Deploy This MCP Server

Prerequisites

• Node.js 18+ or Bun installed

• Claude Desktop app (for mcp test)

• OKX DEX API credentials

• Private key for wallet operations

Step 1: Clone and Setup

git clone https://github.com/Nith567/okx-dex-mcp.git
cd okx-dex-mcp
bun install

Step 2: Environment Configuration

Create a .env file in the project root:

# OKX DEX API Configuration
OKX_API_KEY=your_okx_api_key_here
OKX_SECRET_KEY=your_okx_secret_key_here
OKX_PASSPHRASE=your_okx_passphrase_here

# Wallet Configuration
PRIVATE_KEY=0x_your_private_key_here

Step 3: Build the Server

bun run build

Step 4: Test the Server (Optional)

# Test a token swap(checkout serveral test scripts out there )
bun run test:swap

# Start server locally
bun run start

Step 5: Find Your Bun Path

which bun
# Example output: /opt/homebrew/bin/bun

Step 6: Configure Claude Desktop

Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "okx-dex": {
      "command": "/opt/homebrew/bin/bun",
      "args": [
        "run",
        "/Users/your-username/path/to/okx-mcp/build/index.js"
      ],
      "env": {
        "OKX_API_KEY": "your_okx_api_key_here",
        "OKX_SECRET_KEY": "your_okx_secret_key_here", 
        "OKX_PASSPHRASE": "your_okx_passphrase_here",
        "PRIVATE_KEY": "0x_your_private_key_here"
      }
    }
  }
}

Important:

• Replace /opt/homebrew/bin/bun with your actual bun path from Step 5

• Replace /Users/your-username/path/to/okx-mcp with your actual project path

• Replace the environment variables with your actual credentials

Step 7: Restart Claude Desktop

Close and reopen Claude Desktop for the configuration to take effect.

Step 8: Test in Claude

Try this in Claude Desktop:

Can you check what tokens are supported on Optimism network?

or

Swap 10 USDC to USDT on optimism network

🔧 Architecture & Implementation

Token Swap Process Flow

Step-by-Step Execution:

1. Network Validation: Resolve network name to chain ID

2. Token Discovery: Get supported tokens for the network via OKX API

3. Token Validation: Ensure both source and destination tokens are supported

4. Amount Calculation: Convert human-readable amount to token decimals

5. Wallet Setup: Create EOA from private key and get wallet address

6. Approval Transaction:

   • Call OKX /api/v5/dex/aggregator/approve-transaction

   • Decode transaction data to get DEX contract address and amount

7. Swap Transaction:

   • Call OKX /api/v5/dex/aggregator/swap

   • Decode transaction data to get function name and arguments

8. MEE Integration:

   • Create multichain nexus account with supported chains

   • Build approval composable transaction

   • Build swap composable transaction

   • Create trigger with source token details

9. Execution:

   • Get fusion quote from MEE client

   • Execute the fusion quote

   • Return transaction hash and MEE scan link

   • Wait for transaction receipt

Supported Networks

• Ethereum: Chain ID 1

• Base: Chain ID 8453

• Optimism: Chain ID 10

• xLayer: Chain ID 196

Key Technical Features

• OKX API Integration: HMAC-SHA256 authentication for secure API calls

• Transaction Decoding: ERC20 and DEX router ABI for transaction parsing

• Biconomy MEE: Multichain nexus account with composable transactions

• Error Handling: Comprehensive validation and error management

• Type Safety: Full TypeScript implementation

💸 Referral & Fee Revenue Support

This MCP server supports referral-based revenue generation by allowing you to specify a referrer wallet address and a small percentage fee on each swap. This is similar to how Phantom and other wallets have generated significant revenue by taking a small cut of each transaction.

How it works:

• When building the swap request to OKX DEX Aggregator, you can include the following parameters:

const params = {
  chainIndex: chainId,
  amount,
  toTokenAddress,
  fromTokenAddress,
  slippage: SLIPPAGE,
  userWalletAddress,
  fromTokenReferrerWalletAddress: "0xYourReferralAddress", // Your address to receive referral fees
  feePercent: "0.25" // Example: 0.35% fee for revenue
};

• The fromTokenReferrerWalletAddress receives the referral fee, and feePercent sets the percentage (e.g., 0.25 for 0.25%).

• This enables you to earn a small profit on every swap routed through your MCP server.

• Many wallets (like Phantom) have made millions in revenue using this approach.

• We are expanding this by providing MCP as a service, so you can also benefit from referral fees.

Example Usage

// Example: Swap 0.4 USDC to USDT on Optimism
const result = await executeTokenSwap({
  network: 'optimism',
  amount: '0.4',
  fromTokenSymbol: 'USDC', 
  toTokenSymbol: 'USDT'
});

// Returns:
{
  success: true,
  hash: "0x...",
  explorerLink: "https://..",
  meeScanLink: "https://...",
  receipt: {...}
}

Required Environment Variables

PRIVATE_KEY=your_private_key_here
OKX_API_KEY=your_okx_api_key
OKX_SECRET_KEY=your_okx_secret_key
OKX_PASSPHRASE=your_okx_passphrase

🎯 Why This Project Matters

Innovation Impact:

1. Solves Real Problems: Eliminates the #1 barrier to DeFi adoption (gas complexity)

2. Technical Excellence: Leverages cutting-edge MEE technology over legacy ERC-4337

3. User-Centric Design: Natural language interface removes technical barriers

4. Cross-Chain Leadership: True multi-chain operations with single signature