IBRL Agent

A sophisticated Solana-focused AI agent with web and Telegram interfaces.

🚀 Features

• Real-time Solana Data

  • Live price tracking and market analysis
  • Trending token insights via Birdeye API
  • Wallet balance monitoring with USD conversion
  • Transaction analysis with detailed breakdowns
  • Jito MEV rewards tracking
  • Compressed NFT minting via Crossmint
  • Token swapping via Jupiter

• AI-Powered Interactions

  • Natural language processing via GPT-4o models
  • Context-aware responses with memory
  • Blockchain-specific knowledge integration
  • Sarcastic, Solana-focused personality
  • Custom function calling for blockchain operations
  • Rich responses with images and memes

• Wallet Integration

  • Built-in agent wallet functionality with auto-recovery
  • Secure SOL transfers with validation
  • Transaction signature verification
  • Balance management with caching
  • Failover RPC connections (Helius + QuickNode)

• Robust Error Handling

  • Comprehensive error classification system
  • User-friendly error messages with personality
  • Graceful degradation for API failures
  • Automatic retry mechanisms
  • Detailed error logging and context

• Third-Party Integrations

  • Helius RPC for blockchain data
  • Crossmint for compressed NFT minting
  • Jito for MEV analytics
  • CoinGecko for price data
  • Jupiter for token swaps
  • Birdeye for market insights
  • Lulo for USDC lending rates

• Enhanced Telegram Bot

  • Command-based interactions (/start, /help, /solprice, etc.)
  • Extended conversation history (15 messages)
  • Session management with inactivity cleanup
  • Photo message handling
  • Interactive elements and responses
  • Persistent error recovery

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v18 or higher recommended)
• npm, yarn, pnpm, or bun
• Git

Environment Setup

1. Create a .env.local file in the root directory
2. Add the following environment variables:

# Required: OpenAI API key for the AI functionality
OPENAI_API_KEY=your_openai_key

# Required: Solana RPC providers (at least one is needed)
NEXT_PUBLIC_HELIUS_API_KEY=your_helius_api_key
NEXT_PUBLIC_QUICKNODE_RPC_URL=your_quicknode_rpc_url # backup for Helius

# Required: Wallet configuration for the agent
WALLET_MNEMONIC=your_wallet_mnemonic

# Optional: Third-party service integrations
CROSSMINT_API_KEY=your_crossmint_api_key
CROSSMINT_COLLECTION_ID=your_crossmint_collection_id
NEXT_PUBLIC_BIRDEYE_API_KEY=your_birdeye_api_key

# Optional: Telegram bot configuration
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
TELEGRAM_WEBHOOK_URL=your_webhook_url # for production deployments
BOT_API_BASE_URL=http://127.0.0.1:3000 # if running locally

Getting Started

1. Clone the repository:

git clone https://github.com/introvertmac/IBRL.git
cd IBRL

2. Install dependencies:

npm install
# or
yarn install
# or
pnpm install
# or
bun install

3. Run the development server and Telegram bot:

# Run web interface only
npm run dev

# Run Telegram bot only
npm run start-bot

# Run both web interface and Telegram bot
npm run start-all

4. Open http://localhost:3000 with your browser to see the web interface.
5. For the Telegram bot, search for your bot's username on Telegram and start a conversation.

Project Structure

├── src/
│   ├── app/                       # Next.js app directory
│   │   ├── api/                   # API routes
│   │   │   ├── birdeye/           # Birdeye API integration
│   │   │   ├── crossmint/         # NFT minting
│   │   │   ├── lulo/              # Lending rates
│   │   │   └── wallet/            # Wallet operations
│   │   │       ├── route.ts       # Wallet balance
│   │   │       ├── send/          # Send SOL
│   │   │       └── sign/          # Sign transactions
│   │   ├── layout.tsx             # App layout
│   │   ├── page.tsx               # Main page
│   │   └── globals.css            # Global styles
│   │
│   ├── components/                # React components
│   │   ├── ApiKeyModal.tsx        # API key input
│   │   ├── Chat.tsx               # Chat interface
│   │   └── Icon.tsx               # UI icons
│   │
│   ├── telegram/                  # Telegram bot
│   │   ├── bot.ts                 # Bot initialization
│   │   ├── handler.ts             # Message handler
│   │   └── scripts/               # Bot startup scripts
│   │
│   └── utils/                     # Utility functions
│       ├── airdrop.ts             # Devnet airdrop
│       ├── birdeye.ts             # Market data
│       ├── coingecko.ts           # Price feeds
│       ├── errors.ts              # Error handling system
│       ├── helius.ts              # Blockchain data
│       ├── jito.ts                # MEV rewards
│       ├── jup.ts                 # Token swaps
│       ├── lulo.ts                # Lending rates
│       ├── openai.ts              # AI integration
│       ├── validation.ts          # Input validation
│       └── wallet.ts              # Wallet management
│
├── public/                        # Static assets
│   ├── IBRL.jpeg                  # Logo
│   └── *.jpg, *.png               # Meme images
│
├── next.config.js                 # Next.js configuration
├── tailwind.config.ts             # Tailwind CSS config
├── tsconfig.json                  # TypeScript config
├── tsconfig.bot.json              # Bot TypeScript config
└── package.json                   # Dependencies

API Routes

POST /api/crossmint
├── Description: Mint compressed NFTs on Solana
├── Parameters:
│   ├── recipient: string        # Recipient wallet address
│   ├── name: string             # NFT name
│   ├── image: string            # Image URL
│   └── description: string      # NFT description
└── Returns: { status: string, tokenId?: string, error?: string }

GET /api/wallet
├── Description: Get agent wallet balance
└── Returns: { address: string, balance: number }

POST /api/wallet/send
├── Description: Send SOL from agent wallet
├── Parameters:
│   ├── recipient: string        # Recipient wallet address
│   ├── amount: number           # Amount in SOL
│   └── rpcUrl?: string          # Optional RPC provider to use
└── Returns: { signature: string, status: 'success'|'error', message: string }

POST /api/wallet/sign
├── Description: Sign and send a transaction
├── Parameters:
│   ├── transaction: string      # Base64 encoded transaction
│   └── rpcUrl?: string          # Optional RPC provider to use
└── Returns: { signature: string }

GET /api/birdeye/trending
├── Description: Get trending tokens from Birdeye
├── Parameters:
│   └── limit?: number           # Number of tokens (default: 10)
└── Returns: Array of trending token objects with price metrics

GET /api/lulo/rates
├── Description: Get current USDC lending rates across Solana protocols
└── Returns: { rates: Array<{protocol: string, rate: number}>, error?: string }

Telegram Bot Commands

/start    - Start a conversation with IBRL
/help     - Show available commands
/solprice - Get current Solana price
/trending - Show trending Solana tokens
/clear    - Clear conversation history

Error Handling System

The application implements a comprehensive error handling system in src/utils/errors.ts with custom error classes:

• IBRLError - Base error class
• APIError - For third-party API issues
• WalletError - For wallet operations
• ValidationError - For input validation
• BlockchainError - For blockchain interactions
• ConfigurationError - For environment/setup issues

All errors provide user-friendly messages that maintain the bot's sarcastic Solana-focused personality.

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Demo

Check out the Twitter demo to see IBRL in action!