Skip to content

VORTEX_INTEGRATION.md

Latest commit

 

History

History
348 lines (263 loc) · 9.7 KB

VORTEX_INTEGRATION.md

File metadata and controls

348 lines (263 loc) · 9.7 KB

Vortex Telegram Bot Integration

📋 Document Summary

What This Document Covers:

  • Vortex Launch bot integration via Telegram automation
  • Advanced bundling and sniper protection features
  • Pyrogram-based command automation (no official API)
  • Launch orchestration and configuration
  • Setup, usage examples, and troubleshooting

Sections in This Document:

Related Documentation:

Context Tags: #vortex #telegram #bundling #sniper-protection

Production Status: This integration is located in src/vortex/ with orchestrator in src/orchestrators/vortex/. It automates Telegram bot commands, which is inherently brittle and may break if Vortex changes its interface.

Overview

Vortex is a Telegram bot for launching memecoins on pump.fun with advanced features like:

  • Bundle launches - Multiple wallets buying simultaneously in same block
  • Sniper protection - Automatic selling if token gets sniped
  • Wallet warming - Avoid new-wallet detection by scanners
  • Stealth funding - Bypass BubbleMaps detection

Since Vortex has no public API, this integration uses Pyrogram (Telegram MTProto client) to automate user interactions with the bot programmatically.

Architecture

LaunchAgencyBot → VortexOrchestrator → VortexTelegramClient → Vortex Bot → Solana Blockchain
      ↓                    ↓                      ↓
TokenMetadata      Launch Workflow      Pyrogram Automation

Components

1. VortexTelegramClient (vortex_client.py)

  • Pyrogram-based user bot for Telegram automation
  • Command interface: /start, /launch, /bundle, /settings
  • Response parsing with regex pattern matching
  • Session management with persistent authentication

Key Methods:

async def send_command(command: str) -> str
async def wait_for_response(timeout: int = 30) -> str
async def launch_token(metadata: TokenMetadata) -> dict

2. VortexOrchestrator (src/orchestrators/vortex/vortex.py)

  • High-level orchestration layer
  • Converts TokenMetadata → Vortex commands
  • Launch workflow management
  • Result extraction and tracking

Key Methods:

async def launch_token(metadata: TokenMetadata) -> VortexLaunchResult
async def launch_with_bundle(...) -> VortexLaunchResult
async def launch_with_bundle_and_sniper(...) -> VortexLaunchResult

3. Configuration Models (config.py)

  • VortexConfig - Telegram API credentials (Pydantic BaseModel)
  • VortexLaunchConfig - Launch mode configuration (Pydantic BaseModel)
  • VortexLaunchMode - Enum for launch types
  • VortexLaunchResult - Launch outcome data (Pydantic BaseModel)

Note: All models migrated from dataclass to Pydantic BaseModel (October 2025) for validation and type safety.

Setup Guide

1. Install Dependencies

pip install pyrogram>=2.0.106 tgcrypto>=1.2.5

2. Get Telegram API Credentials

  1. Go to https://my.telegram.org
  2. Login with your phone number
  3. Navigate to "API development tools"
  4. Create a new application
  5. Copy your api_id and api_hash

3. Get Telegram Session String

You need to export a session string from an existing authenticated Telegram session.

Use the included helper script (RECOMMENDED)

# Set your API credentials first
export TELEGRAM_API_ID="your_api_id"
export TELEGRAM_API_HASH="your_api_hash"

# Run the session generator
PYTHONPATH=. python src/vortex/utils/session_generator.py

The script will:

  1. Prompt for your phone number
  2. Send you a verification code via Telegram
  3. Generate and display your session string
  4. Show you the .env line to copy

4. Set Environment Variables in .env

Add to your .env file:

TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
TELEGRAM_SESSION_STRING=your_session_string_here
VORTEX_BOT_USERNAME=@VortexLaunchBot  # Optional, has default
NETWORK=devnet  # or "mainnet"

No phone verification needed! The session string handles authentication.

Usage Examples

Basic Launch (No Bundling)

import asyncio
from src.models.token_models import TokenMetadata
from src.vortex import VortexConfig
from src.orchestrators.vortex.vortex import VortexOrchestrator

async def basic_launch():
    # Configure (using Pydantic model)
    config = VortexConfig(
        api_id=12345,
        api_hash="your_api_hash",
        session_string="your_session_string_here",
        bot_username="@VortexLaunchBot",
        network="devnet"
    )

    # Initialize and start orchestrator
    orchestrator = VortexOrchestrator(vortex_config=config)
    await orchestrator.start_orchestrator()

    # Create metadata
    metadata = TokenMetadata(
        name="My Token",
        ticker="MYTKN",
        description="Testing Vortex integration",
        image_path="path/to/image.jpg",
        twitter="https://x.com/mytoken",
    )

    # Launch
    result = await orchestrator.launch_token(metadata)

    if result.success:
        print(f"✅ Launched! Mint: {result.mint_address}")
        print(f"URL: {result.pump_fun_url}")
    else:
        print(f"❌ Failed: {result.error}")

    await orchestrator.stop_orchestrator()

asyncio.run(basic_launch())

Bundle Launch (Multiple Wallets)

result = await orchestrator.launch_with_bundle(
    metadata=metadata,
    bundle_wallet_count=5,
    bundle_sol_per_wallet=0.01
)

Bundle + Sniper Protection

result = await orchestrator.launch_with_bundle_and_sniper(
    metadata=metadata,
    bundle_wallet_count=5,
    bundle_sol_per_wallet=0.01,
    sniper_threshold=20.0  # 20% threshold
)

Launch Modes

1. Basic Launch

  • Standard token creation
  • No bundling or sniper protection
  • Fastest and simplest option

2. Sniper Mode

  • Launch with sniper protection
  • Auto-sells if token gets sniped over threshold
  • Protects against sniper bots

3. Bundle Mode

  • Launch with multiple wallets buying simultaneously
  • All buys happen in same block as creation
  • Creates instant liquidity and market interest

4. Bundle + Sniper Mode

  • Combines bundling with sniper protection
  • Maximum protection and market impact
  • Recommended for serious launches

Configuration Options

VortexConfig

Telegram API Credentials (Pydantic BaseModel):

VortexConfig(
    api_id=12345,                           # Telegram API ID
    api_hash="your_api_hash",               # Telegram API hash
    session_string="your_session_string",   # Pyrogram session string
    bot_username="@VortexLaunchBot",        # Vortex bot username
    network="devnet"                        # "devnet" or "mainnet"
)

VortexLaunchConfig

Launch Configuration Parameters (Pydantic BaseModel):

VortexLaunchConfig(
    launch_mode=VortexLaunchMode.BUNDLE_SNIPER,
    bundle_wallet_count=5,           # Number of bundled wallets
    bundle_sol_per_wallet=0.01,      # SOL per wallet
    sniper_protection_threshold=20.0, # Sniper threshold %
    auto_sell_on_snipe=True,         # Auto-sell if sniped
    wallet_warming_enabled=False     # Enable wallet warming
)

# Serialize to dict using Pydantic v2 API
config_dict = config.model_dump()

# Deserialize from dict using Pydantic v2 API
config = VortexLaunchConfig.model_validate(config_dict)

VortexLaunchMode Enum

class VortexLaunchMode(Enum):
    BASIC = "basic"                    # No bundling or sniper
    SNIPER = "sniper"                  # Sniper protection only
    BUNDLE = "bundle"                  # Bundle launch only
    BUNDLE_SNIPER = "bundle_sniper"    # Bundle + sniper

Demo Script

Run the included demo script:

# Basic launch
PYTHONPATH=. python src/playground/run_vortex_launch_demo.py --mode basic

# Bundle launch
PYTHONPATH=. python src/playground/run_vortex_launch_demo.py --mode bundle

# Bundle + Sniper
PYTHONPATH=. python src/playground/run_vortex_launch_demo.py --mode bundle_sniper

# Run all demos
PYTHONPATH=. python src/playground/run_vortex_launch_demo.py --mode all

Troubleshooting

"Client not started" Error

Call await orchestrator.start_orchestrator() before launching

Authentication Issues

Verify your session string is valid and not expired. Generate a new session string if needed.

Timeout Waiting for Response

Increase timeout in VortexTelegramClient:

client.response_timeout = 60  # 60 seconds

Parsing Errors

Check raw response and adjust regex patterns in _parse_launch_response()

Rate Limit Errors

Add delays between commands:

await asyncio.sleep(2)  # Wait 2 seconds

File Structure

src/playground/vortex_integration/
├── README.md                      # This documentation
├── vortex_client.py              # Pyrogram Telegram client
├── vortex_orchestrator.py        # Launch orchestration
├── config.py                     # Configuration models (Pydantic)
├── generate_session_string.py    # Session string generator
└── __init__.py                   # Module exports

src/playground/
└── run_vortex_launch_demo.py     # Demo script

Document Status: Complete Last Updated: October 15, 2025 Implementation: src/playground/vortex_integration/ (Experimental) Dependencies: Pyrogram >=2.0.106, TgCrypto >=1.2.5