PolyBucket — Polymarket Copy-Trading

Executive Summary & Core Pillars

PolyBucket is the first production-grade Polymarket copy-trading system that implements the exact bucket/basket consensus algorithm from 0xMega's viral Medium article word-for-word. Instead of blindly mirroring a single wallet (the approach every competitor uses, including PolyCop), PolyBucket groups 5–10 expert wallets by niche and only executes when ≥80% of the bucket agrees on the same outcome within a tight price band with favorable spreads.

The system's core pillars consist of:
1. Bucket Consensus Engine: Core Go module implementing hard gates before any trade executes.
2. WalletDiscoveryEngine: Automated scanner that discovers, scores, and suggests the best wallets per niche using Polymarket's Gamma API, CLOB API, and on-chain Polygon data.
3. Interactive Bucket Builder: Web + Telegram UI where users select a niche, review scored wallets, approve/reject, and create buckets.
4. Sub-150ms Execution Pipeline: WebSocket-first architecture with pre-computed order payloads, dedicated Polygon RPC, and connection pooling.

The Consensus Mechanism

All four conditions must be true simultaneously for a trade to execute:

EXECUTE TRADE = (
agreement_pct >= 80%
AND abs(entry_price - avg_bucket_price) <= 3%
AND market_spread <= 5%
AND all_wallet_filters_pass
)

Threshold Constants:
- Consensus Threshold: 80.0% (80%+ wallets must agree)
- Price Band: 3.0% (Entries within ±3% of bucket average)
- Max Spread: 5.0% (Maximum acceptable bid-ask spread)
- Min Market Volume: $10,000.0 (24h minimum volume to ensure deep liquidity)
- MinWinRate: 60.0% (Win rate required for any tracked wallet)
- MinClosedTrades: 50 (Minimum historical closed trades for tracking)
- MinMonthsActive: 4 (At least 4 months of verifiable active trading history)
- MaxTradesPerMonth: 100 (To filter out high-frequency algorithmic bots)
- MinBucketSize: 5 (Minimum wallets in a bucket to avoid single-wallet dependency)
- MaxBucketSize: 10 (Maximum wallets in a bucket to avoid signal dilution)

Sub-150ms Execution Pipeline

An ultra-low-latency order submission pipeline designed for sub-150ms end-to-end execution. Below is the latency budget breakdown:

- Signal Detection (WebSocket): <10ms (Persistent WS connection to CLOB)
- Consensus Check: <20ms (Redis-cached bucket state)
- Filter Chain: <15ms (In-memory filter evaluation)
- Order Building: <10ms (Pre-computed order templates)
- EIP-712 Signing: <30ms (go-ethereum secp256k1 signing)
- CLOB Submission: <50ms (Persistent HTTP/2 connection pool)
- Confirmation: <15ms (WebSocket order status confirmation)
- Total End-to-End Latency: <150ms

Key Latency Optimizations:
1. Pre-signed order templates: For each monitored market, pre-compute order payloads with only price/quantity needing update.
2. Connection pooling: Maintain persistent HTTP/2 connections to CLOB API to eliminate cold-connect handshake latency.
3. Nonce pipeline: Pre-fetch and cache the next 5 nonces per wallet, avoiding round-trips.
4. WebSocket-first: All monitoring runs via Polymarket's CLOB WebSocket subscription stream (wss://ws-subscriptions-clob.polymarket.com/ws/) — never poll REST.
5. Dedicated RPC: Use wss://polygon-mainnet.g.alchemy.com/v2/ for high-performance on-chain queries.

WalletDiscoveryEngine & Scoring System

Automates the process of finding high-performance expert wallets to copy. The scanner uses Polymarket's Gamma API, CLOB API, and on-chain Polygon data to score wallets across 8 dimensions (overall score out of 100):

1. Win Rate Score (20% weight): 60% = 0, 70% = 50, 80%+ = 100
2. Track Record Score (10% weight): 4 months = 0, 12 months = 100
3. Niche Focus Score (15% weight): concentration in #1 niche. Categorizes trading history into niches like elections, geopolitics, and science-tech (primary niches must cover >=70% of trades, max 3 niches)
4. Frequency Score (10% weight): sweet spot is 20-60 trades/month. High frequency (>100) or inactive (<20) scores are penalized.
5. Liquidity Score (15% weight): percentage of trades in deep-liquidity markets (>$5k volume)
6. Position Accumulation Score (10% weight): analyzes time-series of entries to ensure the wallet builds positions over days/weeks, rather than single-dump entries.
7. Recency Score (15% weight): 30-day performance is weighted 2.0x compared to all-time performance to capture the wallet's current alpha.
8. Not-Bot Score (5% weight): multi-signal bot, insider, and high-risk gambler detection filter.

Multi-Signal Bot & Bad-Actor Detection

To safeguard users against copy-trading automated bots, frontrunning scripts, and bad actors, a multi-signal risk evaluator runs on every scanned profile:

- Bot Signals: Flags inhuman trade frequency (>50 trades/day consistently), periodic timing patterns (trades at exact intervals down to the second), lack of niche specialization (>10 categories), or sub-second reaction to new market creations.
- Insider Signals: Suspicously prescient binary event trading (win rate >85% across 20+ trades before major news events).
- Gambler Signals: High-volatility market preference (>60% volatile markets), all-in sizing (>50% bankroll on single trades), or one massive jackpot followed by a severe balance death spiral.

Non-Custodial Key Cryptography (AES-256-GCM Vault)

User funds and execution security are managed via a strict non-custodial structure. User private keys are never stored in plaintext, never leave the server's memory, and are securely zeroized (wiped with zeroes) immediately after each EIP-712 order signing.

Key Security Architecture:
- Master Key Derivation: Master key is derived dynamically from the `POLYBUCKET_MASTER_KEY` environment variable using a high-cost Argon2id hashing setup.
- Authenticated Encryption: AES-256-GCM is used to encrypt keys at rest. A new random cryptographic nonce is generated for every encryption pass.
- Zeroize Memory Sanitization: Plaintext keys exist only in short-lived memory byte arrays and are overwritten with zeroes immediately after order submission.

Paper Trading Simulation Model

For users wanting to validate a bucket's performance before committing capital, a high-fidelity Paper Trading engine simulates live execution with realistic market parameters:

- Real-World Base Fee: 0.5% transaction fee applied to all mock trades to mimic the Polymarket CLOB fee.
- Dynamic Slippage: 0.1% to 2.0% slippage calculated based on the simulated order size compared to real-time orderbook depth snapshots.
- Gas Fee Modeling: Mock transaction fees (~0.003 MATIC) factored in using live Polygon gas oracle estimations.
- Limit Order Fills: 95% fill probability modeled for limit orders positioned within 2% of mid-price.
- Partial Fills: Simulated whenever a user's position size exceeds 20% of top-of-book depth.

Telegram Bot Command & REST API Architecture

The Go backend binary acts as a unified orchestrator exposing both an interactive Telegram Bot and a Next.js-compatible REST/WebSocket API:

- Core TG Commands:
- /start: Generates a new non-custodial Polygon wallet for the user.
- /wallet, /balance: Check USDC balances, deposit addresses, and export private keys.
- /discover: Initiates a niche-based wallet scanner and presents inline approval buttons.
- /buckets: Lists active copy-trading buckets and their status.
- /paper <id>, /start_trading <id>: Toggles simulated or live trading for any approved bucket.
- REST / WebSocket Endpoints:
- /api/auth/register, /api/auth/login: Standard JWT-based secure sessions.
- /api/discovery/run: Triggers the multi-worker parallel scanner.
- /api/buckets: Handles CRUD operations for custom portfolios.
- /ws/consensus: Real-time consensus feed streaming signals, agreement %, and validation states.
- /ws/trades: High-fidelity stream of executed positions and latencies.

Zero-Cost Production & Deployment Hosting Stack

PolyBucket is engineered to run on a highly optimized, fully distributed hosting stack that costs $0/month for up to 200 active users, offering production-grade speed without overhead:

- Go Backend VM: Hosted on Fly.io free tier (3 shared-cpu VMs, 256MB RAM each). Implements net/http + Chi router with goroutine pools and zero-GC-pause tuning.
- Next.js Web App: Deployed on Vercel's Edge network for sub-10ms Server-Side Rendering (SSR) and edge-cached static pages.
- Primary Database: PostgreSQL 16 on Supabase (500MB free database) with Row-Level Security (RLS) policies for user data isolation.
- Cache & Consensus State: Upstash Redis free tier (10K commands/day) for sub-millisecond consensus state reads, WebSocket Pub/Sub coordination, and rate-limiting counters.
- Blockchain RPC nodes: Polygon WebSocket connection pool via Alchemy's free tier (300M compute units/month).