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.

🎯 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.

🖼️ 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

| 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