🚀 AI Perps Trading Platform

Pigeon uses a multi-agent architecture where different specialized agents handle different tasks:

• Master Agent: Coordinates user requests and routes to specialized agents
• Market Data Agent: Fetches prices via CoinGecko, LunarCrush, Ostium APIs
• Trading Execution Agent: Handles swaps, orders, position management
• Research Agent: Social sentiment, news analysis
• Code Generation Agent: Creates "Pigeon Code" scripts for automation

Category	Integration	Purpose
DEX (EVM)	KyberSwap	Aggregated swaps on Ethereum, Base, Arbitrum, etc.
DEX (Solana)	Jupiter	Solana swaps + limit orders
DEX (TON)	DeDust	TON blockchain swaps
Perpetuals	Hyperliquid	Perps trading with advanced orders
Traditional	Ostium	Stocks, forex, commodities (synthetic)
Predictions	Polymarket	Event betting on Polygon

• Backend: Python (based on their fast-agent fork and solana-agent-kit usage)
• Agent Framework: Custom multi-agent with MCP (Model Context Protocol) support
• LLM Provider: Likely Anthropic Claude (based on building-effective-agents reference)
• Wallet: Privy (Stripe) MPC wallets — self-custodial, exportable
• Messaging: Multi-platform (Telegram, WhatsApp, Discord, Farcaster, XMTP, SMS)
• Code Runtime: Sandboxed execution environment for "Pigeon Code" scripts

// User says: "Every 15 min, alert me if SOL falls below $150"
// Pigeon generates monitoring code that:
// 1. Polls SOL price every 15 minutes
// 2. Compares against threshold
// 3. Sends notification if condition met

┌─────────────────────────────────────────────────────────────────┐
│                        USER INTERFACES                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
│  │ Telegram │  │ Discord  │  │   Web    │  │   API    │        │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘        │
└───────┼─────────────┼─────────────┼─────────────┼───────────────┘
        │             │             │             │
        └─────────────┴──────┬──────┴─────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    GATEWAY / MESSAGE ROUTER                     │
│  • Session management  • Rate limiting  • Auth                  │
└─────────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                     ORCHESTRATOR AGENT                          │
│  • Intent classification  • Agent routing  • Context mgmt      │
│  • Uses: Gemini 2.5 Flash (fast) or Pro (complex)              │
└─────────────────────────────────────────────────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        ▼                    ▼                    ▼
┌───────────────┐  ┌───────────────┐  ┌───────────────┐
│ RESEARCH AGENT│  │ TRADING AGENT │  │ STRATEGY AGENT│
│ • Market data │  │ • Order exec  │  │ • Backtest    │
│ • Sentiment   │  │ • Position    │  │ • Code gen    │
│ • News        │  │ • Risk mgmt   │  │ • Monitoring  │
└───────┬───────┘  └───────┬───────┘  └───────┬───────┘
        │                  │                  │
        └────────────────┬─┴──────────────────┘
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                      TOOL LAYER (MCP)                           │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │ Hyperliquid │  │  CoinGecko  │  │   MongoDB   │             │
│  │    SDK      │  │    API      │  │   Store     │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
└─────────────────────────────────────────────────────────────────┘

Purpose: Handle multi-platform messaging, session management, authentication

Recommended: Python + FastAPI or use existing frameworks

• python-telegram-bot for Telegram
• Pycord for Discord
• Start with Telegram only for MVP

Purpose: Classify user intent, route to specialized agents, maintain context

Recommended: Use Gemini 2.5 Flash for routing (fast + cheap), Pro for complex reasoning

# Intent Classification
intents = [
    "price_check",      # "What's BTC price?"
    "open_position",    # "Long ETH 10x"
    "close_position",   # "Close my BTC position"
    "set_alert",        # "Alert me if SOL > 200"
    "portfolio_check",  # "Show my positions"
    "strategy_create",  # "Create a grid trading strategy"
    "backtest",         # "Backtest this strategy"
]

Purpose: Execute trades, manage positions, handle risk

SDK: hyperliquid-python-sdk

from hyperliquid.info import Info
from hyperliquid.exchange import Exchange

# Core operations to implement:
class HyperliquidAgent:
    async def get_price(self, symbol: str) -> float
    async def open_position(self, symbol: str, side: str, size: float, leverage: int)
    async def close_position(self, symbol: str, percentage: float = 100)
    async def set_stop_loss(self, symbol: str, price: float)
    async def set_take_profit(self, symbol: str, price: float)
    async def get_positions(self) -> List[Position]
    async def get_pnl(self) -> PnLSummary

Purpose: Help users build, backtest, and deploy trading strategies

This is where you can differentiate from Pigeon:

• Strategy Templates: Pre-built strategies users can customize
• Backtesting: Test strategies against historical data
• Live Monitoring: Track strategy performance in real-time
• Risk Management: Automatic position sizing, max drawdown limits

// Collections

// users - User accounts and settings
{
  _id: ObjectId,
  platform: "telegram",
  platform_id: "123456789",
  wallet_address: "0x...",  // Hyperliquid wallet
  settings: {
    default_leverage: 5,
    max_position_size: 1000,
    risk_per_trade: 0.02
  },
  created_at: ISODate
}

// strategies - User-created strategies
{
  _id: ObjectId,
  user_id: ObjectId,
  name: "ETH Grid Bot",
  type: "grid",
  parameters: {
    symbol: "ETH",
    lower_bound: 3000,
    upper_bound: 4000,
    grid_count: 10,
    size_per_grid: 0.1
  },
  status: "active",
  performance: {
    total_pnl: 150.5,
    win_rate: 0.65,
    trades_count: 42
  }
}

// trades - Trade history
{
  _id: ObjectId,
  user_id: ObjectId,
  strategy_id: ObjectId,  // null for manual trades
  symbol: "BTC",
  side: "long",
  entry_price: 45000,
  exit_price: 46500,
  size: 0.1,
  pnl: 150,
  timestamp: ISODate
}

// alerts - Price/condition alerts
{
  _id: ObjectId,
  user_id: ObjectId,
  symbol: "SOL",
  condition: "price_above",
  threshold: 200,
  triggered: false,
  created_at: ISODate
}

1. Building Effective Agents by Anthropic — Must read! Pigeon cites this directly
2. OpenAI Function Calling Guide — Core concept for tool-use
3. Gemini API Documentation — Your primary LLM

Build a simple chatbot that can:

1. Take natural language input
2. Call Gemini API
3. Use function calling to get BTC price from CoinGecko
4. Return formatted response

# Goal: "What's BTC price?" → Calls CoinGecko → "BTC is $45,000"

Framework	Best For	Learning Curve
fast-agent	MCP-enabled agents, what Pigeon uses	Medium
LangChain	General purpose, huge ecosystem	Medium
LlamaIndex	RAG, data retrieval	Easy
OpenAI Agents SDK	Simple multi-agent	Easy
Custom (recommended for MVP)	Full control, simpler	Easy

• Hyperliquid Docs
• Python SDK — Read the examples folder
• Trade manually on Hyperliquid to understand the UX
• Understand: funding rates, mark price vs. index price, liquidation mechanics

• Grid Trading — Buy low, sell high in a range
• DCA (Dollar Cost Averaging) — Regular buys regardless of price
• Momentum — Follow trends
• Mean Reversion — Bet on return to average
• Funding Rate Arbitrage — Exploit funding rate differentials

• Telegram bot interface
• Natural language → Gemini → Function calling → Hyperliquid
• Check price: "What's ETH price?"
• Open position: "Long ETH 0.1 size 5x leverage"
• Close position: "Close my ETH position"
• View portfolio: "Show my positions"
• Set SL/TP: "Set stop loss at $3000"

• Strategy templates
• Backtesting
• Alerts system
• P&L tracking over time
• Multiple users/authentication

moar-perps/
├── pyproject.toml          # Dependencies (use uv or poetry)
├── .env                    # Secrets (never commit!)
├── src/
│   ├── __init__.py
│   ├── main.py             # Entry point
│   ├── config.py           # Configuration
│   ├── bot/
│   │   ├── __init__.py
│   │   ├── telegram.py     # Telegram bot handlers
│   │   └── handlers.py     # Command handlers
│   ├── agents/
│   │   ├── __init__.py
│   │   ├── orchestrator.py # Main routing agent
│   │   ├── trading.py      # Hyperliquid trading agent
│   │   └── research.py     # Market data agent
│   ├── tools/
│   │   ├── __init__.py
│   │   ├── hyperliquid.py  # Hyperliquid SDK wrapper
│   │   ├── coingecko.py    # Price data
│   │   └── gemini.py       # LLM client
│   ├── models/
│   │   ├── __init__.py
│   │   ├── user.py         # User model
│   │   ├── trade.py        # Trade model
│   │   └── strategy.py     # Strategy model
│   └── db/
│       ├── __init__.py
│       └── mongo.py        # MongoDB client
├── tests/
│   └── ...
└── README.md

• Response Time: Time from message to response (target: < 3s)
• Intent Accuracy: % of correctly classified intents
• Trade Execution Success: % of trades that execute without errors
• User Retention: Daily/weekly active users
• Strategy Performance: Win rate, Sharpe ratio, max drawdown

1. Log Everything: All user messages, agent responses, trade executions
2. Review Failures: Weekly review of failed intents, errors
3. A/B Test Prompts: Try different system prompts, measure accuracy
4. User Feedback: Add thumbs up/down to responses
5. Iterate: Improve prompts, add tools, expand capabilities

"""
Minimal example: Gemini + Hyperliquid Price Check
"""
import google.generativeai as genai
from hyperliquid.info import Info
import json

# Configure Gemini
genai.configure(api_key="YOUR_GEMINI_API_KEY")

# Define tools
tools = [
    {
        "name": "get_crypto_price",
        "description": "Get the current price of a cryptocurrency on Hyperliquid",
        "parameters": {
            "type": "object",
            "properties": {
                "symbol": {
                    "type": "string",
                    "description": "The trading symbol, e.g., BTC, ETH, SOL"
                }
            },
            "required": ["symbol"]
        }
    }
]

# Tool implementation
def get_crypto_price(symbol: str) -> dict:
    info = Info(skip_ws=True)
    meta = info.meta()
    # Find the asset
    for asset in meta["universe"]:
        if asset["name"] == symbol:
            # Get mid price
            l2 = info.l2_snapshot(asset["name"])
            bid = float(l2["levels"][0][0]["px"])
            ask = float(l2["levels"][1][0]["px"])
            mid = (bid + ask) / 2
            return {"symbol": symbol, "price": mid}
    return {"error": f"Symbol {symbol} not found"}

# Chat function
def chat(user_message: str):
    model = genai.GenerativeModel(
        "gemini-2.5-flash",
        tools=tools,
        system_instruction="You are a helpful trading assistant for Hyperliquid perps."
    )
    
    response = model.generate_content(user_message)
    
    # Handle function calls
    if response.candidates[0].content.parts[0].function_call:
        fc = response.candidates[0].content.parts[0].function_call
        if fc.name == "get_crypto_price":
            result = get_crypto_price(fc.args["symbol"])
            # Send result back to model
            response = model.generate_content([
                user_message,
                {"function_call": fc},
                {"function_response": {"name": fc.name, "response": result}}
            ])
    
    return response.text

# Test
print(chat("What's the price of ETH?"))

Day 1-2: Project Setup

• Initialize Python project with uv or Poetry
• Set up project structure (see 5.1 above)
• Configure environment variables (.env)
• Set up MongoDB Atlas cluster
• Create basic Telegram bot with python-telegram-bot
• Deliverable: Bot responds to /start with welcome message

Day 3-4: LLM Integration

• Integrate Gemini 2.5 Flash API
• Implement function calling schema
• Build orchestrator that routes messages through Gemini
• Add get_price tool (CoinGecko or Hyperliquid)
• Deliverable: "What's BTC price?" returns actual price

Day 5-7: Hyperliquid Core

• Integrate hyperliquid-python-sdk
• Implement wallet connection (use testnet first!)
• Build open_position tool
• Build close_position tool
• Build get_positions tool
• Add basic error handling
• Deliverable: Can execute trades via chat

Day 8-9: Order Management

• Implement leverage selection
• Add stop-loss / take-profit tools
• Implement order types (market, limit)
• Build portfolio summary view
• Deliverable: Full position lifecycle works

Day 10-11: User Management + Safety

• User registration in MongoDB
• Wallet address storage per user
• Basic risk limits (max position size, max leverage)
• Confirmation prompts for large trades
• Deliverable: Multi-user support with safety rails

Day 12-13: Polish + Testing

• Improve error messages and UX
• Add conversation context (remember previous messages)
• Write basic tests for critical paths
• Test on Hyperliquid testnet extensively
• Deliverable: Smooth user experience

Day 14: Deploy

• Deploy to GCP Cloud Run or Compute Engine
• Set up logging and monitoring
• Switch to mainnet (with caution!)
• Invite beta testers
• Deliverable: Live MVP! 🚀

Day 1-2: Project Architecture

• Design database schema carefully
• Set up project with proper structure
• Configure CI/CD (GitHub Actions → GCP)
• Set up development, staging, production environments
• Initialize MongoDB with proper indexes

Day 3-4: Telegram Bot Foundation

• Build Telegram bot with conversation handlers
• Implement session management
• Add user registration flow
• Create help commands and onboarding

Day 5-7: LLM Layer

• Integrate Gemini with proper error handling
• Build tool registry system
• Implement conversation memory (last N messages)
• Add fallback responses for unknown intents
• Deliverable: Conversational bot that understands context

Day 8-10: Hyperliquid Integration

• Build comprehensive SDK wrapper
• Implement all trading operations:
  • get_price(symbol)
  • get_funding_rate(symbol)
  • open_long(symbol, size, leverage)
  • open_short(symbol, size, leverage)
  • close_position(symbol, percentage)
  • set_stop_loss(symbol, price)
  • set_take_profit(symbol, price)
• Add retry logic for network failures

Day 11-12: Portfolio & Analytics

• Build portfolio view (all positions)
• Add P&L calculations
• Implement position history tracking
• Store trades in MongoDB

Day 13-14: Testing on Testnet

• Comprehensive testnet testing
• Edge case handling (insufficient margin, etc.)
• Unit tests for critical functions
• Deliverable: Reliable trading via chat

Day 15-16: Risk Management

• Implement per-user risk limits:
  • Max position size
  • Max leverage allowed
  • Max open positions
  • Daily loss limit
• Add confirmation prompts for large trades
• Implement "paper trading" mode for new users

Day 17-18: User Experience

• Improve response formatting (emojis, tables)
• Add inline keyboards for quick actions
• Build settings menu (/settings)
• Add price formatting (human-readable)

Day 19-21: Alerts System

• Price alert functionality
• Position alerts (liquidation warning)
• Funding rate alerts
• Background job scheduler (Celery or APScheduler)
• Deliverable: Proactive notifications

Day 22-23: Research Tools (Differentiator)

• Add funding rate analysis
• Open interest data
• Simple market sentiment (Fear & Greed index)
• These make you more than just "trade executor"

Day 24-25: Production Hardening

• Set up proper logging (structured, searchable)
• Add monitoring and alerting (GCP Monitoring)
• Rate limiting per user
• Error reporting (Sentry or similar)

Day 26-27: Beta Testing

• Deploy to production (mainnet)
• Invite 5-10 beta testers
• Collect feedback actively
• Fix critical bugs immediately

Day 28: Launch

• Final bug fixes
• Documentation for users
• Announce on social media
• Deliverable: Production MVP with real users! 🎉

Dev	Focus Area	Key Deliverables
Dev 1 (Backend Lead)	LLM + Orchestration	Gemini integration, function calling, intent routing
Dev 2 (Trading)	Hyperliquid + MongoDB	SDK wrapper, trade execution, data storage
Dev 3 (Frontend/Ops)	Telegram Bot + DevOps	Bot UX, CI/CD, deployment, monitoring