okx-mcp-server/README.md

Model Context Protocol (MCP) server for gasless DEX swapping powered by OKX DEX API + Biconomy MEE

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

<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
```bash
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:
```bash
# 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
```bash
bun run build
```

### Step 4: Test the Server (Optional)
```bash
# 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
```bash
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`

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

```js
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

```typescript
// 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
```bash
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