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?

$3

- ❌ Need ETH on every chain for gas fees
- ❌ Complex multi-step approval processes
- ❌ Failed transactions waste gas
- ❌ Cross-chain operations require multiple signatures

$3

✅ 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

$3

- 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

$3

- 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

$3

- MEE Orchestration: Self-executing transaction flows with conditional logic
- Intelligent Routing: MEE optimizes gas costs and execution paths automatically

$3

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

Claude MCP Success

MCP Liquidity Tool

MEE Success Transaction

Price OKX Fetch

---

🎨 Superior User Experience

$3

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

$3

`
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

$3

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

$3

| 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

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

$3

| 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

$3

- Node.js 18+ or Bun installed
- Claude Desktop app (for mcp test)
- OKX DEX API credentials
- Private key for wallet operations

$3

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

$3

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
`

$3

`bash
bun run build
`

$3

`bash

Test a token swap(checkout serveral test scripts out there )

bun run test:swap

Start server locally

bun run start
`

$3

`bash
which bun

Example output: /opt/homebrew/bin/bun

`

$3

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

$3

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

$3

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

$3

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

$3

- Ethereum: Chain ID 1
- Base: Chain ID 8453
- Optimism: Chain ID 10
- xLayer: Chain ID 196

$3

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

---

$3

`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: {...}
}
`

---

$3


`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

$3

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