my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

my-project-public — gitlawb

#1	# MAWDBot - AI-Powered Multi-Chain Trading Agent
#2
#3	Exfoliate, trade, launch, vibe!
#4
#5	MAWDBot is an enterprise-grade AI-powered trading agent for Solana and multi-chain DeFi. Built on advanced LLM technology, MAWDBot combines natural language processing with real-time market data, autonomous trading across multiple DEXs, and creative content generation.
#6
#7	## Key Features
#8
#9	- AI-Powered Intelligence: Advanced NLP using OpenRouter (Claude, MiniMax) for natural conversation
#10	- Solana DEX Trading: Autonomous token swaps via Jupiter API (Meteora, Raydium aggregation)
#11	- Perpetuals Trading: LONG/SHORT positions with up to 125x leverage on Aster DEX & Hyperliquid
#12	- CDP Wallet Management: Secure custodial Solana accounts via Coinbase Developer Platform
#13	- Real-Time Market Data: Live prices from CoinGecko Pro API for 10,000+ cryptocurrencies
#14	- Real-Time Analytics: Live market data from Birdeye with trending tokens, charts, and security analysis
#15	- Unified Address Analysis: Analyze any Solana address (tokens, wallets, transactions) instantly
#16	- Web Search Integration: Real-time market research via SearchAPI, SerpAPI, and XAI
#17	- Multimodal Content: Generate images, music, videos, and speech with AI
#18	- Social Integration: Automated Twitter/X posting for trade updates
#19	- Multiple Interfaces: CLI, Web UI, Telegram Bot, and programmatic API
#20	- Persistent Memory: Trading notes and session history that carry across conversations
#21	- Security First: Token rug checks, balance verification, and trade confirmations
#22
#23	## Tools Arsenal (46 Tools)
#24
#25	### Solana Trading Tools (9)
#26
#27	\| Tool \| Description \| Example \|
#28	\|------\|-------------\|---------\|
#29	\| `get_wallet_balance` \| Check SOL and all token balances \| "Check my wallet balance" \|
#30	\| `get_token_price` \| Get current token price from Birdeye \| "What's the price of BONK?" \|
#31	\| `get_token_info` \| Comprehensive token data (price, volume, liquidity, holders) \| "Get full info on JUP token" \|
#32	\| `get_swap_quote` \| Get swap quote without executing \| "Quote for 1 SOL to USDC" \|
#33	\| `buy_token` \| Execute buy order with SOL \| "Buy 0.5 SOL worth of BONK" \|
#34	\| `sell_token` \| Execute sell order for SOL \| "Sell all my WIF tokens" \|
#35	\| `get_portfolio` \| Full portfolio with USD values \| "Show my complete portfolio" \|
#36	\| `get_trending_tokens` \| Discover trending tokens via Birdeye \| "What's trending today?" \|
#37	\| `search_token` \| Search tokens by name or symbol \| "Find tokens named PEPE" \|
#38
#39	### Aster DEX Perpetuals & Spot (10)
#40
#41	\| Tool \| Description \| Example \|
#42	\|------\|-------------\|---------\|
#43	\| `aster_open_long` \| Open LONG perpetual (bet price UP) \| "Open 10x LONG on BTCUSDT with 50 USDT" \|
#44	\| `aster_open_short` \| Open SHORT perpetual (bet price DOWN) \| "Short ETHUSDT at 20x with 25 USDT" \|
#45	\| `aster_close_position` \| Close open perpetual position \| "Close my LONG on SOLUSDT" \|
#46	\| `aster_get_positions` \| View all positions with unrealized P&L \| "Show my open positions" \|
#47	\| `aster_set_leverage` \| Set leverage 1x-125x for pair \| "Set 15x leverage on BTCUSDT" \|
#48	\| `aster_spot_buy` \| Buy tokens on Aster spot market \| "Buy 0.1 BTC on Aster spot" \|
#49	\| `aster_spot_sell` \| Sell tokens on Aster spot market \| "Sell 1 ETH on Aster" \|
#50	\| `aster_get_balance` \| Check futures and spot balances \| "What's my Aster balance?" \|
#51	\| `aster_transfer` \| Transfer between futures and spot \| "Transfer 100 USDT to futures" \|
#52	\| `aster_get_price` \| Get current price and 24h stats \| "Price of SOLUSDT on Aster?" \|
#53
#54	### Hyperliquid DEX Perpetuals & Spot (15)
#55
#56	\| Tool \| Description \| Example \|
#57	\|------\|-------------\|---------\|
#58	\| `hyperliquid_get_account` \| Get account info, balance, margin summary \| "Check my Hyperliquid account" \|
#59	\| `hyperliquid_get_price` \| Get current prices for assets \| "BTC price on Hyperliquid?" \|
#60	\| `hyperliquid_open_long` \| Open LONG perpetual position \| "Long BTC 5x with 100 USDC" \|
#61	\| `hyperliquid_open_short` \| Open SHORT perpetual position \| "Short ETH 10x with 50 USDC" \|
#62	\| `hyperliquid_close_position` \| Close position (full or partial) \| "Close my BTC position" \|
#63	\| `hyperliquid_get_positions` \| View all open positions with PnL \| "Show my Hyperliquid positions" \|
#64	\| `hyperliquid_set_leverage` \| Set leverage (cross/isolated margin) \| "Set 20x leverage on SOL" \|
#65	\| `hyperliquid_place_limit_order` \| Place limit orders at specific prices \| "Buy BTC at $60,000" \|
#66	\| `hyperliquid_cancel_order` \| Cancel open orders \| "Cancel my pending BTC order" \|
#67	\| `hyperliquid_get_open_orders` \| View all pending orders \| "Show my open orders" \|
#68	\| `hyperliquid_get_trade_history` \| View recent trades (fills) \| "Show my trade history" \|
#69	\| `hyperliquid_get_available_coins` \| List all tradeable markets \| "What can I trade on Hyperliquid?" \|
#70	\| `hyperliquid_transfer` \| Transfer USDC between perp/spot \| "Transfer 500 USDC to spot" \|
#71	\| `hyperliquid_get_asset_ids` \| Get asset IDs for API calls \| "Get Hyperliquid asset IDs" \|
#72	\| `hyperliquid_spot_order` \| Place spot orders (HYPE, PURR, etc.) \| "Buy 100 HYPE tokens" \|
#73
#74	### CDP Account Management (5)
#75
#76	\| Tool \| Description \| Example \|
#77	\|------\|-------------\|---------\|
#78	\| `cdp_create_account` \| Create CDP-managed Solana account \| "Create a new CDP wallet" \|
#79	\| `cdp_list_accounts` \| List all CDP-managed accounts \| "Show my CDP accounts" \|
#80	\| `cdp_get_balance` \| Get SOL balance for any address \| "Check CDP wallet balance" \|
#81	\| `cdp_send_sol` \| Send SOL securely (no keys exposed) \| "Send 1 SOL to wallet X" \|
#82	\| `cdp_request_faucet` \| Request devnet SOL (devnet only) \| "Get testnet SOL" \|
#83
#84	### CoinGecko Market Data (5)
#85
#86	\| Tool \| Description \| Example \|
#87	\|------\|-------------\|---------\|
#88	\| `get_crypto_price` \| Get prices with market cap, volume, 24hr change \| "Price of BTC, ETH, SOL?" \|
#89	\| `get_coin_market_data` \| Comprehensive market data with rankings \| "Top 10 cryptos by market cap" \|
#90	\| `get_trending_cryptos` \| Trending coins by search activity \| "What cryptos are trending?" \|
#91	\| `search_crypto` \| Search coins by name/symbol \| "Find Dogecoin" \|
#92	\| `get_global_crypto_stats` \| Global market statistics \| "Global crypto market stats" \|
#93
#94	### Advanced Wallet Analytics (5)
#95
#96	\| Tool \| Description \| Example \|
#97	\|------\|-------------\|---------\|
#98	\| `get_wallet_net_worth` \| Detailed net worth breakdown with USD values \| "What's my net worth?" \|
#99	\| `get_wallet_net_worth_chart` \| Historical net worth changes over time \| "Show net worth for last 30 days" \|
#100	\| `get_wallet_pnl` \| Comprehensive P&L analysis \| "What's my P&L this month?" \|
#101	\| `get_token_chart` \| OHLCV candlestick chart data \| "Get 1h chart for BONK" \|
#102	\| `analyze_token_security` \| Security analysis, rug check, risk assessment \| "Is this token safe?" \|
#103
#104	### Real-Time Search & Analysis (2)
#105
#106	\| Tool \| Description \| Example \|
#107	\|------\|-------------\|---------\|
#108	\| `web_search` \| Real-time web search \| "Latest news on Solana DeFi" \|
#109	\| `analyze_solana_address` \| Unified analysis for any address type \| "Analyze this wallet: 7xKX..." \|
#110
#111	### Creative & Social (5)
#112
#113	\| Tool \| Description \| Example \|
#114	\|------\|-------------\|---------\|
#115	\| `post_to_twitter` \| Post tweets automatically \| "Tweet about my 10x gain" \|
#116	\| `generate_image` \| AI image generation \| "Generate a BONK meme" \|
#117	\| `generate_music` \| AI music with/without lyrics \| "Make a trap beat" \|
#118	\| `generate_video` \| AI video and animation \| "Create a trading recap video" \|
#119	\| `text_to_speech` \| Convert text to speech \| "Read my portfolio aloud" \|
#120
#121	## Quick Start
#122
#123	### 1. Installation
#124
#125	```bash
#126	cd solana-agent
#127	pip install -r requirements.txt
#128	```
#129
#130	### 2. Configuration
#131
#132	Copy `.env.example` to `.env.local` and configure:
#133
#134	```env
#135	# ============ REQUIRED ============
#136
#137	# Helius RPC (Solana blockchain access)
#138	HELIUS_API_KEY=your_helius_api_key
#139	HELIUS_RPC_URL=<redacted>
#140	HELIUS_WSS_URL=wss://mainnet.helius-rpc.com/?api-key=your_key
#141
#142	# Jupiter Trading API (Solana DEX swaps)
#143	JUPITER_API_KEY=your_jupiter_api_key
#144	JUPITER_REFERRAL_ACCOUNT=your_referral_account
#145
#146	# Birdeye API (Market data and analytics)
#147	BIRDEYE_API_KEY=your_birdeye_api_key
#148
#149	# Your Solana Wallet
#150	MAWD_WALLET=your_wallet_public_key
#151	MAWD_PRIVATE_KEY=your_private_key_base58
#152
#153	# LLM Configuration
#154	OPENROUTER_API_KEY=your_openrouter_api_key
#155	OPENROUTER_MODEL=minimax/minimax-m2-her
#156
#157	# ============ OPTIONAL ============
#158
#159	# Aster DEX (Perpetuals & Spot Trading)
#160	ASTER_API_KEY=your_aster_api_key
#161	ASTER_USER_ADDRESS=0x_your_ethereum_address
#162	ASTER_SIGNER_ADDRESS=0x_your_signer_address
#163	ASTER_PRIVATE_KEY=0x_your_private_key
#164
#165	# Hyperliquid DEX (Perpetuals on Hyperliquid L1)
#166	HYPERLIQUID_WALLET=your_wallet_address
#167	HYPERLIQUID_PRIVATE_KEY=your_private_key
#168	HYPERLIQUID_USE_TESTNET=false
#169
#170	# CDP (Coinbase Developer Platform) - Managed Solana Accounts
#171	CDP_API_KEY_ID=your_cdp_api_key_id
#172	CDP_API_KEY_SECRET=your_base64_ed25519_private_key
#173	CDP_WALLET_SECRET=optional_wallet_secret
#174	CDP_NETWORK=solana-mainnet
#175
#176	# CoinGecko Pro API (Real-time market data)
#177	COINGECKO_API_KEY=your_coingecko_api_key
#178
#179	# Twitter/X (Social posting)
#180	TWITTER_CONSUMER_KEY=your_key
#181	TWITTER_CONSUMER_SECRET=your_secret
#182	TWITTER_ACCESS_TOKEN=your_token
#183	TWITTER_ACCESS_TOKEN_SECRET=your_secret
#184
#185	# MiniMax (AI content generation)
#186	MINIMAX_API_KEY=your_key
#187
#188	# Search APIs (Real-time web search)
#189	SEARCH_API_KEY=your_searchapi_key
#190	SERP_API_KEY=your_serpapi_key
#191	XAI_API_KEY=your_xai_key
#192
#193	# Telegram Bot
#194	TELEGRAM_BOT_TOKEN=<redacted>
#195	```
#196
#197	### 3. Run MAWDBot
#198
#199	CLI Interface:
#200	```bash
#201	# Interactive mode
#202	python agent.py
#203
#204	# Web interface
#205	cd web && python api_server.py
#206	# Open http://localhost:8000
#207	```
#208
#209	Telegram Bot:
#210	```bash
#211	python telegram_bot.py
#212	```
#213
#214	## Telegram Bot Commands
#215
#216	MAWDBot includes a full-featured Telegram bot for trading on the go:
#217
#218	### Quick Commands
#219	- `/start` - Welcome message and quick start guide
#220	- `/help` - Show all available commands
#221	- `/balance` - Check wallet SOL and token balances
#222	- `/portfolio` - View complete portfolio with USD values
#223	- `/trending` - Show trending Solana tokens
#224	- `/price <token>` - Get token price (e.g., `/price BONK`)
#225
#226	### Trading Commands
#227	- `/buy <amount> <token>` - Buy tokens (e.g., `/buy 0.5 BONK`)
#228	- `/sell <amount> <token>` - Sell tokens (e.g., `/sell 100 WIF`)
#229	- `/quote <amount> <from> <to>` - Get swap quote
#230
#231	### Perpetuals Trading
#232	- `/long <pair> <leverage> <amount>` - Open LONG position
#233	- `/short <pair> <leverage> <amount>` - Open SHORT position
#234	- `/positions` - View all open positions
#235	- `/close <pair>` - Close a position
#236
#237	### Market Data
#238	- `/crypto <coins>` - CoinGecko prices (e.g., `/crypto bitcoin,ethereum`)
#239	- `/global` - Global crypto market stats
#240	- `/trendingcrypto` - Trending cryptocurrencies
#241
#242	### CDP Wallets
#243	- `/cdp_create` - Create new CDP wallet
#244	- `/cdp_list` - List CDP wallets
#245	- `/cdp_balance <address>` - Check CDP wallet balance
#246
#247	### Utilities
#248	- `/analyze <address>` - Analyze any Solana address
#249	- `/search <query>` - Search for tokens
#250	- `/security <token>` - Token security analysis
#251
#252	## Architecture
#253
#254	```
#255	mawd/
#256	├── solana-agent/ # Core agent
#257	│ ├── agent.py # Main SolanaAgent class
#258	│ ├── config.py # Configuration management
#259	│ ├── telegram_bot.py # Telegram bot interface
#260	│ ├── clients/ # API clients
#261	│ │ ├── jupiter_client.py # Solana DEX trading (Jupiter)
#262	│ │ ├── helius_client.py # Solana RPC & DAS
#263	│ │ ├── birdeye_client.py # Market data & analytics
#264	│ │ ├── aster_client.py # Aster DEX perpetuals
#265	│ │ ├── hyperliquid_client.py # Hyperliquid DEX
#266	│ │ ├── cdp_client.py # Coinbase Developer Platform
#267	│ │ ├── coingecko_client.py # CoinGecko Pro API
#268	│ │ ├── twitter_client.py # Twitter/X posting
#269	│ │ ├── minimax_client.py # AI content generation
#270	│ │ ├── search_client.py # Web search
#271	│ │ └── solana_analyzer.py # Address analysis
#272	│ └── tools/ # Tool implementations
#273	│ └── solana_tools.py # All 46 trading tools
#274	├── web/ # Web interface
#275	│ ├── api_server.py # FastAPI backend
#276	│ └── frontend/ # Web UI
#277	│ └── index.html # Main interface
#278	└── .env.local # Your configuration
#279	```
#280
#281	## API Integrations (11 Clients)
#282
#283	\| Client \| Purpose \| Features \|
#284	\|--------\|---------\|----------\|
#285	\| Jupiter \| Solana DEX trading \| Swap quotes, transaction building, best rates \|
#286	\| Helius \| Solana RPC & DAS \| Account data, balances, history, NFTs \|
#287	\| Birdeye \| Market analytics \| Prices, trending, charts, security \|
#288	\| Aster DEX \| Perpetuals trading \| LONG/SHORT 1x-125x, spot trading \|
#289	\| Hyperliquid \| Perpetuals trading \| Cross/isolated margin, limit orders \|
#290	\| CDP \| Managed wallets \| Secure custodial accounts via Coinbase \|
#291	\| CoinGecko \| Market data \| 10,000+ crypto prices, trends, global stats \|
#292	\| Twitter \| Social posting \| Tweet posting, media uploads \|
#293	\| MiniMax \| AI content \| Images, music, video, TTS \|
#294	\| Search \| Web search \| Multi-provider (SearchAPI, SerpAPI, XAI) \|
#295	\| Solana Analyzer \| Address analysis \| Auto-detect and analyze any address \|
#296
#297	## Security Features
#298
#299	- Trade Confirmations: All trades require explicit approval
#300	- Price Impact Warnings: Alerts on high slippage trades
#301	- Balance Verification: Checks before executing swaps
#302	- Token Security Analysis: Automatic rug check for new tokens
#303	- Private Key Protection: Keys never logged or exposed
#304	- Liquidation Warnings: Clear risk warnings for leveraged positions
#305	- CDP Secure Custody: Coinbase-managed keys for extra security
#306	- Rate Limiting: Respects API rate limits
#307	- Error Handling: Graceful failures with detailed messages
#308
#309	## Usage Examples
#310
#311	### Solana Trading
#312	```
#313	You: "What's trending?"
#314	MAWDBot: [Shows top trending Solana tokens with prices and changes]
#315
#316	You: "Buy 0.5 SOL worth of BONK"
#317	MAWDBot: [Confirms trade, executes, shows transaction]
#318	```
#319
#320	### Perpetuals Trading
#321	```
#322	You: "Open 10x LONG on BTCUSDT with 100 USDT"
#323	MAWDBot: [Shows position details, liquidation price, executes]
#324
#325	You: "Show my positions"
#326	MAWDBot: [Lists all positions with unrealized P&L]
#327	```
#328
#329	### Market Research
#330	```
#331	You: "Price of bitcoin, ethereum, and solana"
#332	MAWDBot: [CoinGecko prices with 24hr changes]
#333
#334	You: "Global crypto market stats"
#335	MAWDBot: [Total market cap, volume, BTC dominance]
#336	```
#337
#338	### CDP Wallets
#339	```
#340	You: "Create a new CDP wallet"
#341	MAWDBot: [Creates secure custodial Solana account]
#342
#343	You: "Send 1 SOL from CDP to wallet X"
#344	MAWDBot: [Executes secure transfer without exposing keys]
#345	```
#346
#347	## Roadmap
#348
#349	- [x] Solana DEX trading (Jupiter)
#350	- [x] Aster DEX perpetuals
#351	- [x] Hyperliquid perpetuals
#352	- [x] CDP wallet management
#353	- [x] CoinGecko market data
#354	- [x] Telegram bot
#355	- [x] Web interface
#356	- [ ] Multi-wallet support
#357	- [ ] Automated trading strategies
#358	- [ ] Portfolio rebalancing
#359	- [ ] Mobile app interface
#360	- [ ] Copy trading features
#361	- [ ] NFT trading support
#362	- [ ] Cross-chain bridges
#363
#364	## License
#365
#366	MIT License - Use at your own risk!
#367
#368	## Disclaimer
#369
#370	MAWDBot is provided as-is for educational and research purposes. Cryptocurrency trading involves substantial risk of loss. Never trade with funds you cannot afford to lose. Always verify transactions before confirming. The developers assume no responsibility for financial losses.
#371
#372	Perpetuals Trading Warning: Leveraged trading can result in liquidation and total loss of margin. Understand the risks before trading with leverage.
#373
#374	---
#375
#376	Built with love by the MAWDBot team
#377
#378	Exfoliate, trade, launch, vibe!
#379

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public