Swap Chain

A comprehensive cross-chain bridging application with AI intent extraction, real-time quotes from Relay API, and Starknet integration for seamless token swaps.

🚀 Features

AI Assistant

• Natural language intent extraction
• Automatic form filling
• Clarification requests for unclear inputs
• Smart chain mapping and validation

Cross-Chain Bridge

• Real quotes from Relay API
• 9 supported chains (including Starknet)
• Multiple supported tokens
• Live fee calculations
• Transaction monitoring

Starknet Integration

• Direct token swaps on Starknet
• AutoSwappr SDK integration
• Ekubo DEX support
• Account balance validation
• Transaction status tracking

Same-Chain Swap

• Mock exchange rates
• Token switching
• Real-time calculations

📋 Supported Chains & Tokens

Chains (9 total)

• EVM Testnets (5): Sepolia, Base Sepolia, Arbitrum Sepolia, OP Sepolia, Polygon Amoy
• Solana (2): Solana Devnet, Eclipse Testnet
• Bitcoin (1): Bitcoin Testnet 4
• Starknet (1): Starknet Mainnet

Tokens (4 total)

• ETH - Ethereum (EVM chains + Starknet)
• SOL - Solana (Solana chains)
• BTC - Bitcoin (Bitcoin chain)
• USDC - USD Coin (Starknet)

🛠️ API Endpoints

Intent API (/api/intent)

POST /api/intent
{
  "message": "I want to swap 0.1 ETH from sepolia to base-sepolia"
}

Routes API (/api/routes)

POST /api/routes
{
  "sourceChain": "sepolia",
  "targetChain": "base-sepolia", 
  "token": "ETH",
  "amount": "0.1"
}

Execute API (/api/execute)

POST /api/execute
{
  "quoteId": "0x...",
  "userAddress": "0x...",
  "sourceChain": "sepolia",
  "targetChain": "base-sepolia",
  "token": "ETH",
  "amount": "0.1"
}

Starknet Swap API (/api/starknet-swap)

POST /api/starknet-swap
{
  "fromToken": "ETH",
  "toToken": "USDC",
  "amount": "0.001",
  "accountAddress": "0x..."
}

Testing

1. Start the Application

# Install dependencies (if not already done)
npm install

# Start development server
npm run dev

# Open browser to http://localhost:3000

2. Test AI Intent Extraction

1. Connect Wallet to Navigate to the main page

2. Try natural language inputs:

   • "I want to swap 0.1 ETH from sepolia to base-sepolia"
   • "Bridge 50 USDC from arbitrum-sepolia to polygon-amoy"
   • "Swap 0.5 SOL on solana-devnet"
   • "I need to transfer 0.01 BTC from bitcoin-testnet4"

3. Click on Get Quote to find the optimal route

4. Execute Swap

3. Test Different Features

• Cross-chain bridges: Try different chain combinations
• Starknet swaps: Test ETH ↔ USDC swaps on Starknet

🏗️ Architecture

Frontend

• React with TypeScript
• Tailwind CSS for styling
• Real-time form updates
• Error handling and loading states
• RainbowKit for wallet connection
• Starknet provider integration

Backend

• Next.js API routes
• OpenAI integration for intent extraction
• Relay API integration for quotes
• AutoSwappr SDK for Starknet swaps
• Balance validation and error handling

Key Design Decisions

• Minimal & Manageable: Focused on core functionality
• Real API Integration: Gets actual quotes from Relay and Starknet
• Security First: Private keys handled server-side
• Clear Error Messages: Comprehensive error handling
• Multi-Chain Support: Seamless cross-chain and same-chain swaps

📈 Success Rate

• ✅ Cross-chain transfers working perfectly across EVM testnets
• ✅ Starknet swaps with AutoSwappr SDK
• ✅ Real bridge fees and timing from Relay API
• ✅ AI intent extraction with clarification support
• ✅ Balance validation and error handling
• ✅ Clean, maintainable code structure

🎯 Getting Started

1. Install dependencies

   npm install

2. Set up environment variables

   # Create .env.local
   OPEN_API_KEY=your_openai_api_key_here

3. Start development server

   npm run dev

4. Open browser

   http://localhost:3000
   

🔧 Development

Adding New Chains

1. Update SUPPORTED_CHAINS in /api/routes/route.ts
2. Add chain to CHAINS array in /app/page.tsx
3. Update token address mapping in getNativeTokenAddress()

Adding New Tokens

1. Update SUPPORTED_TOKENS in /api/routes/route.ts
2. Add token to TOKENS array in /app/page.tsx
3. Update decimals mapping in getTokenDecimals()

Starknet Configuration

1. Update TOKEN_ADDRESSES in AutoSwap.tsx
2. Configure RPC endpoints in API routes
3. Set up private keys in environment variables

🔐 Security

• Private Keys: Handled server-side only
• Environment Variables: Sensitive data stored securely
• Error Handling: No sensitive information exposed in errors
• Validation: Input validation on all API endpoints

Environment Setup

# Required environment variables
OPEN_API_KEY=your_openai_api_key

📝 License

MIT License - feel free to use this as a foundation for your own projects!