trading-evm

EVM DEX Trading - Complete API Reference

Trade any token on Ethereum, Arbitrum, Optimism, Base, and Polygon using Uniswap V3 and 1inch aggregator.

Required Environment Variables

EVM_PRIVATE_KEY=0x...                      # Your EVM wallet private key
ALCHEMY_API_KEY=...                        # Optional: for better RPC
ONEINCH_API_KEY=...                        # Optional: for 1inch API

---

Supported Chains

---

Chat Commands

Swaps

/swap eth <amount> <from> to <to>           # Swap on Ethereum
/swap arb <amount> <from> to <to>           # Swap on Arbitrum
/swap op <amount> <from> to <to>            # Swap on Optimism
/swap base <amount> <from> to <to>          # Swap on Base
/swap matic <amount> <from> to <to>         # Swap on Polygon

# Examples:
/swap eth 1 ETH to USDC                     # Swap 1 ETH to USDC on Ethereum
/swap arb 100 USDC to ARB                   # Swap 100 USDC to ARB on Arbitrum
/swap base 0.5 ETH to DEGEN                 # Swap 0.5 ETH to DEGEN on Base

Quotes

/quote eth <amount> <from> to <to>          # Get quote without executing
/quote arb 1 ETH to USDC                    # Quote on Arbitrum

Compare Routes

/compare <chain> <amount> <from> to <to>    # Compare Uniswap vs 1inch
/compare eth 1 ETH to USDC                  # Compare routes on Ethereum

Balances

/balance eth                                # Check ETH and token balances
/balance arb                                # Check Arbitrum balances
/balance base <token>                       # Check specific token on Base

---

TypeScript API Reference

Uniswap V3

import {
  executeUniswapSwap,
  getUniswapQuote,
  resolveToken,
  getTokenInfo,
  getEvmBalance
} from 'clodds/evm/uniswap';

// Get quote
const quote = await getUniswapQuote({
  chain: 'ethereum',
  tokenIn: 'ETH',
  tokenOut: 'USDC',
  amountIn: '1000000000000000000',  // 1 ETH in wei
  slippageTolerance: 0.5,
});

console.log(`Expected output: ${quote.amountOut}`);
console.log(`Price impact: ${quote.priceImpact}%`);
console.log(`Route: ${quote.route.join(' → ')}`);

// Execute swap
const result = await executeUniswapSwap({
  chain: 'ethereum',
  tokenIn: 'ETH',
  tokenOut: 'USDC',
  amountIn: '1000000000000000000',
  slippageTolerance: 0.5,
  deadline: 300,  // 5 minutes
});

console.log(`TX: ${result.transactionHash}`);
console.log(`Amount out: ${result.amountOut}`);

// Resolve token symbol to address
const usdcAddress = resolveToken('USDC', 'ethereum');

// Get token info
const tokenInfo = await getTokenInfo('ethereum', usdcAddress);
console.log(`${tokenInfo.symbol}: ${tokenInfo.decimals} decimals`);

// Check balance
const balance = await getEvmBalance('ethereum', walletAddress, 'USDC');

1inch Aggregator

import {
  executeOneInchSwap,
  getOneInchQuote,
  getOneInchProtocols,
  compareDexRoutes
} from 'clodds/evm/oneinch';

// Get quote from 1inch
const quote = await getOneInchQuote({
  chain: 'ethereum',
  fromToken: 'ETH',
  toToken: 'USDC',
  amount: '1000000000000000000',
});

console.log(`Expected output: ${quote.toAmount}`);
console.log(`Estimated gas: ${quote.estimatedGas}`);
console.log(`Protocols used: ${quote.protocols.join(', ')}`);

// Execute swap via 1inch
const result = await executeOneInchSwap({
  chain: 'ethereum',
  fromToken: 'ETH',
  toToken: 'USDC',
  amount: '1000000000000000000',
  slippage: 0.5,
});

// Get available protocols
const protocols = await getOneInchProtocols('ethereum');
// ['UNISWAP_V3', 'SUSHISWAP', 'CURVE', ...]

// Compare routes between Uniswap and 1inch
const comparison = await compareDexRoutes({
  chain: 'ethereum',
  tokenIn: 'ETH',
  tokenOut: 'USDC',
  amountIn: '1000000000000000000',
});

console.log(`Uniswap: ${comparison.uniswap.amountOut}`);
console.log(`1inch: ${comparison.oneinch.amountOut}`);
console.log(`Best: ${comparison.best}`);

---

Chain-Specific Examples

Ethereum

// Swap ETH → USDC on Ethereum with MEV protection
const result = await executeUniswapSwap({
  chain: 'ethereum',
  tokenIn: 'ETH',
  tokenOut: 'USDC',
  amountIn: '1000000000000000000',
  useMevProtection: true,  // Uses Flashbots
});

Arbitrum

// Swap on Arbitrum (lower gas)
const result = await executeOneInchSwap({
  chain: 'arbitrum',
  fromToken: 'ETH',
  toToken: 'ARB',
  amount: '500000000000000000',  // 0.5 ETH
  slippage: 1,
});

Base

// Swap on Base
const result = await executeUniswapSwap({
  chain: 'base',
  tokenIn: 'ETH',
  tokenOut: 'DEGEN',
  amountIn: '100000000000000000',  // 0.1 ETH
  slippageTolerance: 2,  // Higher slippage for meme coins
});

Optimism

// Swap on Optimism
const result = await executeOneInchSwap({
  chain: 'optimism',
  fromToken: 'USDC',
  toToken: 'OP',
  amount: '100000000',  // 100 USDC (6 decimals)
  slippage: 0.5,
});

Polygon

// Swap on Polygon
const result = await executeUniswapSwap({
  chain: 'polygon',
  tokenIn: 'MATIC',
  tokenOut: 'USDC',
  amountIn: '10000000000000000000',  // 10 MATIC
  slippageTolerance: 0.5,
});

---

Common Tokens

Ethereum

Arbitrum

Base

Optimism

---

MEV Protection

Ethereum (Flashbots)

// Automatically uses Flashbots Protect RPC
const result = await executeUniswapSwap({
  chain: 'ethereum',
  useMevProtection: true,  // Sends via Flashbots
  ...
});

L2 Chains

L2s (Arbitrum, Optimism, Base) have sequencer-level MEV protection by default.

---

Gas Estimation

// Get gas estimate before swapping
const quote = await getUniswapQuote({ ... });
console.log(`Estimated gas: ${quote.gasEstimate}`);
console.log(`Gas price: ${quote.gasPrice} gwei`);
console.log(`Total gas cost: ${quote.gasCostUsd} USD`);

---

Error Handling

import { EvmSwapError, InsufficientBalanceError, SlippageExceededError } from 'clodds/evm';

try {
  await executeUniswapSwap({ ... });
} catch (error) {
  if (error instanceof InsufficientBalanceError) {
    console.log('Not enough balance');
  } else if (error instanceof SlippageExceededError) {
    console.log('Price moved, increase slippage');
  }
}