Skip to main content
Glama

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:

Feature

ERC-4337

Biconomy MEE

Our Implementation

Cross-Chain

❌ Single chain only

✅ Native multi-chain

✅ 4 chains, 1 signature

Dynamic Execution

❌ Static batching

✅ Conditional logic

✅ Approve → Swap → Transfer

Universal Gas

❌ Chain-specific

✅ Any token, any chain

✅ Pay with your swap token

True Composability

❌ Limited

✅ Runtime calculations

✅ Dynamic amount handling

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


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

Feature

ERC-4337

Biconomy MEE

Our Implementation

Dynamic Execution

❌ Static batching only

✅ Runtime conditional logic

✅ Approval → Swap → Transfer in one flow

Cross-Transaction Data

❌ Cannot use previous results

✅ Each step uses prior outputs

✅ Dynamic amount calculations

Conditional Logic

❌ All steps must execute

✅ Conditional execution paths

✅ Smart slippage handling

2. Cross-Chain Orchestration

Feature

ERC-4337

Biconomy MEE

Our Implementation

Multi-Chain Support

❌ Single chain per transaction

✅ Native cross-chain flows

✅ Ethereum, Base, Optimism, xLayer

Unified Gas Payment

❌ Separate gas per chain

✅ Pay from any chain

✅ Use USDC on Base to swap on Optimism

Atomic Operations

❌ Multiple signatures needed

✅ Single signature for all chains

✅ One signature, multi-chain execution

3. Universal Gas Abstraction

Feature

ERC-4337

Biconomy MEE

Our Implementation

Gas Token Flexibility

⚠️ Limited token support

✅ Any token, any chain

✅ Pay gas with your swap token

Cross-Chain Gas

❌ Chain-specific gas management

✅ Universal gas abstraction

✅ USDC on any chain pays for everything

Gas Optimization

⚠️ Basic bundling

✅ Intelligent routing

✅ MEE optimizes across 50+ DEX sources

4. Advanced Automation

Feature

ERC-4337

Biconomy MEE

Our Implementation

Scheduled Execution

❌ No native scheduling

✅ Built-in automation

🔄 Coming: Limit orders via Gelato

Recurring Transactions

❌ Manual repetition

✅ Automated patterns

🔄 Coming: DCA strategies

Conditional Triggers

❌ No trigger support

✅ Event-based execution

🔄 Coming: Price-based swaps


📋 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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers