Pagra AI - Starknet Wallet API

A comprehensive Node.js API for Starknet wallet management with Telegram bot integration and MCP (Model Context Protocol) chat functionality.

🚀 Quick Start

Prerequisites

• Node.js (v16 or higher)
• npm or yarn
• Supabase account and project
• Starknet RPC endpoint access

Installation

1. Clone and install dependencies:

   npm install

2. Environment Setup: Create a .env file in the root directory with the following variables:

   # Server Configuration
   PORT=3000
   NODE_ENV=development
   
   # Supabase Configuration
   SUPABASE_URL=your_supabase_project_url
   SUPABASE_ANON_KEY=your_supabase_anon_key
   SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
   
   # Starknet Configuration
   STARKNET_RPC_URL=your_starknet_rpc_url
   STARKNET_NETWORK=sepolia
   
   # Telegram Bot (Optional)
   TELEGRAM_BOT_TOKEN=your_telegram_bot_token
   
   # MCP Configuration
   ANTHROPIC_API_KEY=your_anthropic_api_key
   
   # Security
   JWT_SECRET=your_jwt_secret_here
   ENCRYPTION_KEY=your_32_byte_encryption_key

3. Database Setup:

   • Run the database migration scripts from the migrations/ folder
   • See migrations/README.md for detailed instructions

Running the Application

Development mode (with auto-reload):

npm run dev

Production mode:

npm start

The server will start on http://localhost:3000

📁 Project Structure

pagra-ai/
├── src/                     # Source code
│   ├── config/              # Configuration files
│   ├── helpers/             # Helper functions and utilities
│   ├── services/            # Service layer (Telegram, etc.)
│   └── server.js            # Main server file
├── tests/                   # Test files and utilities
│   ├── mocks/               # Mock files for testing
│   ├── *.test.js            # Jest test files
│   ├── test-*.js            # Manual test scripts
│   └── README.md            # Testing documentation
├── migrations/              # Database migration scripts
│   ├── *.sql                # SQL migration files
│   └── README.md            # Migration documentation
├── docs/                    # Documentation
│   ├── telegram-setup.md    # Telegram bot setup guide
│   ├── mcp-chat-example.md  # MCP chat examples
│   ├── TEST_SCENARIOS.md    # Testing scenarios
│   └── README.md            # Documentation index
├── .env                     # Environment variables (create this)
├── package.json
└── README.md                # This file

🔗 API Endpoints

Core Wallet Operations

• POST /api/start - Create new wallet account
• POST /api/deploy_account - Deploy wallet to Starknet
• POST /api/get_wallet_address - Get wallet address
• POST /api/get_balance - Check wallet balance
• POST /api/transfer - Transfer funds
• POST /api/get_transactions - Get transaction history

Chat & AI Integration

• POST /api/chat - Process chat messages with MCP
• POST /api/chat/clear - Clear conversation history
• GET /api/chat/history/:phone_number - Get chat history

Telegram Integration

• POST /api/telegram/webhook - Telegram webhook endpoint
• POST /api/telegram/set-webhook - Set webhook URL

System

• GET /health - Health check endpoint
• GET /api-docs - Swagger API documentation

🛠️ Available Scripts

• npm run dev - Start development server with nodemon
• npm start - Start production server
• npm test - Run Jest tests
• npm run test:watch - Run tests in watch mode
• npm run test:coverage - Generate test coverage report

🧪 Testing

The project includes comprehensive testing:

• Automated Tests: Jest-based unit and integration tests
• Manual Tests: Interactive testing scripts
• Telegram Tests: Bot integration testing
• MCP Tests: Chat functionality testing

See tests/README.md for detailed testing instructions.

🗄️ Database

The project uses Supabase PostgreSQL with:

• Users table: Wallet and user information
• Transactions table: Transfer history and status
• Row Level Security: Secure data access
• Helper functions: Database utilities

See migrations/README.md for database setup instructions.

🤖 Features

Wallet Management

• ✅ Create Starknet wallets
• ✅ Deploy accounts to network
• ✅ Transfer funds between wallets
• ✅ Check balances and transaction history
• ✅ Secure private key encryption

Telegram Bot

• ✅ Interactive wallet operations via Telegram
• ✅ Polling mode for development
• ✅ Webhook mode for production
• ✅ Natural language commands

AI Chat Integration

• ✅ MCP (Model Context Protocol) support
• ✅ Context-aware conversations
• ✅ Tool integration for wallet operations
• ✅ Conversation history management

Security

• ✅ PIN-based authentication
• ✅ Private key encryption
• ✅ Rate limiting
• ✅ Input validation
• ✅ Row Level Security (RLS)

🔧 Dependencies

Core

• Express - Web framework
• Supabase - Database and backend services
• Starknet.js - Starknet blockchain integration

Security & Middleware

• CORS - Cross-origin resource sharing
• Helmet - Security middleware
• Morgan - HTTP request logger
• express-rate-limit - Rate limiting

Integrations

• node-telegram-bot-api - Telegram bot integration
• @anthropic-ai/sdk - Claude AI integration
• swagger-ui-express - API documentation

Development

• Nodemon - Development auto-reload
• Jest - Testing framework
• Dotenv - Environment variable management

📚 Documentation

Comprehensive documentation is available in the docs/ folder:

• Telegram Setup: Complete bot integration guide
• MCP Chat Examples: AI chat functionality examples
• Test Scenarios: Testing strategies and procedures

🚨 Important Security Notes

1. Never commit .env files to version control
2. Use strong encryption keys (32 bytes minimum)
3. Enable RLS policies in Supabase
4. Validate all user inputs before processing
5. Use HTTPS in production environments
6. Regularly rotate API keys and secrets

🆘 Troubleshooting

Common Issues

• Supabase connection: Check environment variables and project status
• Starknet RPC errors: Verify RPC URL and network configuration
• Telegram bot issues: Ensure bot token is valid and webhook is set
• Database permissions: Run migrations/fix-permissions.sql

Getting Help

1. Check the relevant documentation in docs/
2. Review test files in tests/ for examples
3. Verify environment configuration
4. Check server logs for detailed error messages

🔄 Development Workflow

1. Setup: Follow installation instructions
2. Database: Run migrations from migrations/
3. Testing: Use test scripts in tests/
4. Documentation: Update relevant docs when adding features
5. Deployment: Use production environment variables

📈 Next Steps

1. Set up your Supabase database using migration scripts
2. Configure Telegram bot (optional) using docs/telegram-setup.md
3. Test API endpoints using provided test scripts
4. Implement additional features as needed
5. Deploy to production environment