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"
      }
    }
  }
}

---

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

<p align="center"> <img src="./img/claude-mcp-success.png" alt="Claude MCP Success" width="600" /> <br><em>Claude MCP Success</em> </p>

<p align="center"> <img src="./img/mcp-liquidity-tool.png" alt="MCP Liquidity Tool" width="600" /> <br><em>MCP Liquidity Tool</em> </p>

<p align="center"> <img src="./img/mee-success-tnx.png" alt="MEE Success Transaction" width="600" /> <br><em>MEE Success Transaction</em> </p>

<p align="center"> <img src="./img/price-okx-fetch.png" alt="Price OKX Fetch" width="600" /> <br><em>Price OKX Fetch</em> </p>

---

🎨 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