feat: implement copy trading system with documentation

terminal/src/app/api/copy-trading/run/route.ts

@@ -0,0 +1,40 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { CopyTrader } from '@/lib/copy-trader';
+
+export async function GET(req: NextRequest) {
+    const { searchParams } = new URL(req.url);
+    const target = searchParams.get('target') || undefined;
+    const isTest = searchParams.get('test') === 'true';
+    const amountParam = searchParams.get('amount');
+
+    // Parse and validate trade amount (default: 5 USDC)
+    const tradeAmount = amountParam ? parseFloat(amountParam) : 5;
+    if (isNaN(tradeAmount) || tradeAmount <= 0) {
+        return NextResponse.json(
+            { error: 'Invalid trade amount. Must be a positive number.' },
+            { status: 400 }
+        );
+    }
+
+    try {
+        const trader = new CopyTrader();
+
+        if (isTest) {
+            const result = await trader.testExecution();
+            return NextResponse.json({ success: true, data: result });
+        }
+
+        const result = await trader.run(target, tradeAmount);
+
+        return NextResponse.json({ 
+            success: true, 
+            data: result 
+        });
+    } catch (error) {
+        console.error('Copy Trading execution failed:', error);
+        return NextResponse.json(
+            { error: 'Failed to run copy trader', details: error instanceof Error ? error.message : String(error) },
+            { status: 500 }
+        );
+    }
+}

terminal/src/app/copy-trading/README.md

@@ -0,0 +1,59 @@
+# Polymarket Copy Trading Bot
+
+## Overview
+The **Polymarket Copy Trading Bot** is an automated system designed to mimic the trades of profitable users on the Polymarket platform. By monitoring a target wallet, this system automatically executes identical trades (Buy/Sell) on the same markets, leveraging the insights of successful traders.
+
+## Features
+- **Leaderboard Integration:** View top traders by category (Politics, Sports, Crypto, etc.) and time period.
+- **One-Click Copy:** Easily select a trader from the leaderboard to start copying.
+- **Automated Execution:** Monitors the target wallet in real-time and executes trades instantly.
+- **Configurable Trade Amounts:** Set a fixed USDC amount ("n USDC to trade") for every copied trade, managing your risk independent of the target's trade size.
+- **Safety Mechanism:** Filters out large or risky trades based on configurable parameters (default: safe mode).
+
+## System Architecture
+
+### 1. Frontend (Next.js)
+- Located at `/copy-trading`.
+- Provides a dashboard to:
+    - Search/Select target wallets.
+    - View leaderboard statistics.
+    - Configure trade paramters (Amount per trade).
+    - View real-time logs of bot activity.
+
+### 2. Backend (Next.js API Routes)
+- **Monitoring Endpoint:** `/api/copy-trading/run`
+- **Logic:**
+    1. Fetches recent trades from the target wallet using Polymarket's Gamma API.
+    2. Compares trade timestamps to identify new activity.
+    3. If a new trade is found, it constructs a mirroring order.
+
+### 3. Privy Integration (Security)
+We use **Privy** for secure, server-side wallet management and signing.
+- **Why Privy?** It allows the bot to sign transactions programmatically without exposing private keys in the frontend or requiring constant user confirmation (MetaMask popups).
+- **Implementation:**
+    - `src/lib/privy-client.ts`: Initializes the Privy client and manages the "Bot Wallet".
+    - **Server-Side Signing:** The bot generates a special `PrivySigner` (ethers.js compatible) that intercepts signing requests and delegates them to Privy's secure enclave.
+    - This ensures that your trading bot can run autonomously while your assets remain secure.
+
+## Usage Guide
+
+1. **Fund the Bot Wallet:**
+   - Go to the Copy Trading Terminal.
+   - Copy the "Bot Execution Wallet" address.
+   - Send **USDC (Polygon)** for trading and **MATIC** for gas fees to this address.
+
+2. **Select a Trader:**
+   - Browse the "Top Traders Leaderboard".
+   - Click "Copy" on a profitable trader, or manually enter a wallet address.
+
+3. **Configure Amount:**
+   - Enter the **"Trade Amount (USDC)"**.
+   - *Example:* If you set this to **10 USDC**, the bot will buy $10 worth of shares for every trade the target makes, regardless of whether the target traded $100 or $10,000.
+
+4. **Start the Bot:**
+   - Click **"START COPY BOT"**.
+   - Keep the terminal open to monitor logs.
+
+## Development Verification
+- **Test Market Fetching:** `node test-active-market.js`
+- **Test Order Execution:** `node test-live-order.mjs` (Requires funded bot wallet)

terminal/src/app/copy-trading/page.tsx

@@ -0,0 +1,20 @@
+"use client";
+
+import CopyTradingTerminal from "@/components/CopyTradingTerminal";
+import Sidebar from "@/components/Sidebar";
+
+export default function CopyTradingPage() {
+    return (
+        <div className="flex h-screen">
+            {/* Sidebar Navigation */}
+            <div className="relative z-10 overflow-visible">
+                <Sidebar activeTab="copytrading" />
+            </div>
+
+            {/* Main Content */}
+            <main className="flex-1 overflow-y-auto overflow-x-hidden">
+                <CopyTradingTerminal />
+            </main>
+        </div>
+    );
+}