{"id":31817690,"url":"https://github.com/crossmint/crossmint-checkout-telegram-agent","last_synced_at":"2025-10-11T10:23:30.250Z","repository":{"id":298759671,"uuid":"1001050572","full_name":"Crossmint/crossmint-checkout-telegram-agent","owner":"Crossmint","description":"Buy anything on amazon using your credit card/crypto in Telegram!","archived":false,"fork":false,"pushed_at":"2025-06-24T16:19:51.000Z","size":461,"stargazers_count":11,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-24T17:34:01.267Z","etag":null,"topics":["agents","crossmint","tg-bot"],"latest_commit_sha":null,"homepage":"https://t.me/crossmint_bot","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Crossmint.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-12T18:28:42.000Z","updated_at":"2025-06-24T16:19:55.000Z","dependencies_parsed_at":"2025-06-13T08:53:44.759Z","dependency_job_id":null,"html_url":"https://github.com/Crossmint/crossmint-checkout-telegram-agent","commit_stats":null,"previous_names":["crossmint/tg-ecommerce-bot","crossmint/crossmint-checkout-telegram-agent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Crossmint/crossmint-checkout-telegram-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Crossmint%2Fcrossmint-checkout-telegram-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Crossmint%2Fcrossmint-checkout-telegram-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Crossmint%2Fcrossmint-checkout-telegram-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Crossmint%2Fcrossmint-checkout-telegram-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Crossmint","download_url":"https://codeload.github.com/Crossmint/crossmint-checkout-telegram-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Crossmint%2Fcrossmint-checkout-telegram-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279006851,"owners_count":26084204,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","crossmint","tg-bot"],"created_at":"2025-10-11T10:23:16.287Z","updated_at":"2025-10-11T10:23:30.243Z","avatar_url":"https://github.com/Crossmint.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🤖 Crossmint E-Commerce Telegram Bot\n\nAI-powered Telegram shopping assistant with Crossmint wallet integration for seamless e-commerce experiences.\n\n## 🚀 Features\n\n- **AI Chat**: GPT-4o powered conversations\n- **Product Search**: Amazon product search with instant results\n- **Crossmint Wallets**: Client-side wallet creation with passkey signers\n- **Delegation**: Enable fast shopping with automatic transaction signing\n- **Secure Payments**: USDC payments on Base Sepolia testnet\n- **Web Interface**: Next.js app for wallet management and delegation\n\n## ⚡ Quick Start\n\n### 🚀 Super Quick Start (Recommended)\n```bash\n# 1. Clone and install\ngit clone \u003cyour-repo-url\u003e\ncd telegram-agent\nnpm install \u0026\u0026 cd web-interface \u0026\u0026 npm install \u0026\u0026 cd ..\n\n# 2. Setup environment files\nnpm run setup\n\n# 3. Get your API keys (see detailed instructions below)\n# 4. Update .env and web-interface/.env.local with your keys\n\n# 5. One command to start everything!\nnpm run dev:full\n```\n\nThis automatically:\n- ✅ Starts ngrok tunnels\n- ✅ Updates all environment files with ngrok URLs\n- ✅ Starts both development servers\n\n### 📝 Manual Quick Start\n```bash\n# 1-4. Same as above\n\n# 5. Start ngrok tunnels\nngrok start --all --config ngrok.yml\n\n# 6. Auto-update environment files with ngrok URLs\nnpm run update-urls\n\n# 7. Start the application\nnpm run dev:all\n```\n\n## 📋 Prerequisites\n\n- **Node.js** 18+\n- **npm** or **yarn**\n- **ngrok** account (for local development)\n- **Telegram Bot Token** (from @BotFather)\n- **OpenAI API Key**\n- **Crossmint API Keys** (staging environment)\n- **SearchAPI.io Key** (for Amazon product search)\n\n## 🔑 Crossmint API Scopes\n\nWhen creating your Crossmint API keys, ensure you enable the following scopes:\n\n### Server-side API Key Scopes:\n- `wallets.read` - To fetch wallet information\n- `wallets:transactions.create` - To create transactions for purchasing products\n- `wallets:transactions.read` - To check transaction status\n- `wallets:transactions.sign` - To sign transactions when delegation is enabled\n- `orders.create` - To create orders for headless checkout\n- `orders.read` - To check order status\n- `orders.update` - To update orders if needed\n\n### Client-side API Key Scopes:\n- `wallets.read` - To view wallet information in web interface\n- `wallets.create` - To create client-side wallets via passkey signers\n- `orders.create` - To create checkout orders from client-side\n\nYou can configure API keys and scopes in your Crossmint dashboard under Project Settings \u003e API Keys.\n\n## 💨 Quick Setup\n\n### 1. Clone and Install\n\n```bash\ngit clone \u003cyour-repo-url\u003e\ncd telegram-agent\nnpm install\ncd web-interface \u0026\u0026 npm install \u0026\u0026 cd ..\n```\n\n### 2. Quick Setup (Recommended)\n\n```bash\nnpm run setup\n```\n\nThis will:\n- Copy `.env.example` to `.env`\n- Copy `web-interface/.env.example` to `web-interface/.env.local`\n- Show setup completion message\n\n**OR** follow the manual setup below:\n\n### 3. Get Required API Keys\n\n#### Telegram Bot Token\n1. Message [@BotFather](https://t.me/BotFather) on Telegram\n2. Create new bot: `/newbot`\n3. Follow prompts and save your bot token in `.env` in root directory\n\n#### OpenAI API Key\n1. Go to [OpenAI Platform](https://platform.openai.com/api-keys)\n2. Create new API key\n3. Save the key (starts with `sk-`) in `.env` in root directory\n\n#### Crossmint API Keys\n1. Sign up at [Crossmint Console](https://staging.crossmint.com)\n2. Create new project\n3. Get both **Server API Key** and **Client API Key**\n4. Use **staging** environment for development\n\n#### SearchAPI.io Key\n1. Sign up at [SearchAPI.io](https://searchapi.io)\n2. Get your API key from dashboard\n\n### 4. Configure Environment Variables\n\n#### Bot Configuration\n```bash\ncp .env.example .env\n```\n\n#### Web Interface Configuration\n```bash\ncd web-interface\ncp .env.example .env.local\n```\n\n## 🌐 ngrok Setup (Required for Local Development)\n\nTelegram API sometimes may give a hard time working with http URLs, so we need ngrok to tunnel localhost.\n\n### 1. Install ngrok\n\n```bash\n# Option A: npm (recommended)\nnpm install -g ngrok\n\n# Option B: Download from https://ngrok.com/download\n```\n\n### 2. Create ngrok Account\n\n1. Sign up at [ngrok.com](https://ngrok.com)\n2. Get your authtoken from dashboard\n3. Configure ngrok:\n\n```bash\nngrok config add-authtoken YOUR_NGROK_AUTHTOKEN\n```\n\n### 3. Start ngrok Tunnels\nWe've included a `ngrok.yml` configuration file in root.\n\n1. Add your auth token to `ngrok.yml` file\n2. Start both tunnels:\n\n```bash\n# Start ngrok with our configuration\nngrok start --all --config ngrok.yml\n```\n\nThis will create two tunnels:\n- **Bot Server**: `https://abc123.ngrok.io` → `localhost:3000`\n- **Web Interface**: `https://def456.ngrok.io` → `localhost:3001`\n\n### 4. Update Environment Variables\n\nCopy the ngrok URLs and update your environment files:\n\n**Main `.env`:**\n```bash\nWEB_APP_URL=https://def456.ngrok.io  # Web interface ngrok URL\n```\n\n**Web Interface `.env.local`:**\n```bash\nNEXT_PUBLIC_BOT_API_URL=https://abc123.ngrok.io  # Bot server ngrok URL\nBOT_WEBHOOK_URL=https://abc123.ngrok.io/api/webhook/wallet-created\nNEXTAUTH_URL=https://def456.ngrok.io  # Web interface ngrok URL\n```\n\n## 🚀 Start the Application\n\n### Option A: Start Both Services Together\n\n```bash\nnpm run dev:all\n```\n\nThis starts:\n- 🤖 **Bot Server** on `localhost:3000`\n- 🌐 **Web Interface** on `localhost:3001`\n\n### Option B: Start Services Separately\n\n**Terminal 1 - Bot Server:**\n```bash\nnpm run dev:bot\n```\n\n**Terminal 2 - Web Interface:**\n```bash\nnpm run dev:web\n```\n\n**Terminal 3 - ngrok (keep running):**\n```bash\nngrok start --all --config ngrok.yml\n```\n\n## 🧪 Test the Setup\n\n### 1. Test Bot Connection\n1. Find your bot on Telegram (search for your bot's username)\n2. Send `/start` command\n3. You should get a welcome message\n\n### 2. Test Product Search\n```\n/search wireless headphones\n```\nYou should see Amazon products with \"Buy with Crossmint\" buttons.\n\n### 3. Test Wallet Creation\n1. Click any \"Buy with Crossmint\" button\n2. Should redirect to web interface for wallet creation\n3. Complete wallet setup with email/passkey\n\n\n## 🔧 Available Scripts\n\n### Bot Scripts\n```bash\nnpm run setup            # Quick setup - copy environment files\nnpm run update-urls      # Auto-update ngrok URLs in environment files\nnpm run dev:full         # 🚀 Start everything (ngrok + URL updates + servers)\nnpm run dev:bot          # Start bot in development mode\nnpm run dev:web          # Start web interface in development mode\nnpm run dev:all          # Start both bot and web interface\nnpm run build            # Build both bot and web interface\nnpm run start            # Start production build\nnpm run lint             # TypeScript type checking\nnpm run clean            # Clean build artifacts\n```\n\n### Web Interface Scripts\n```bash\ncd web-interface\nnpm run dev              # Start Next.js development server\nnpm run build            # Build for production\nnpm run start            # Start production server\n```\n\n## 🎯 Key Features Walkthrough\n\n### 1. AI Chat\n- Send any message to the bot\n- Powered by GPT-4o via Vercel AI SDK\n- Maintains conversation context\n\n### 2. Product Search\n```\n/search [product name]\n```\n- Searches Amazon products via SearchAPI.io\n- Shows product cards with images and prices\n- \"Buy with Crossmint\" buttons for each product\n\n### 3. Wallet Management\n```\n/login    # Create/connect Crossmint wallet\n/balance  # Check wallet balance\n/topup    # Add funds to wallet\n/logout   # Sign out and clear session\n```\n\n### 5. Memory \u0026 Preferences\n```\n/memory   # See conversation history\n/forget   # Clear conversation history\n```\n\n## 🔒 Security Notes\n\n- **Environment Variables**: Never commit `.env` files\n- **HTTPS Required**: Telegram requires HTTPS for inline keyboards\n- **API Keys**: Keep all API keys secure and rotate regularly\n- **Staging Environment**: Use Crossmint staging for development\n\n## 🐛 Troubleshooting\n\n### Bot Not Responding\n- Check `TELEGRAM_BOT_TOKEN` is correct\n- Verify bot server is running on port 3000\n- Check ngrok tunnel is active\n\n### \"Invalid web app URL\" Error\n- Ensure `WEB_APP_URL` uses HTTPS (ngrok URL)\n- Verify web interface is running on port 3001\n- Check ngrok tunnel for web interface\n\n### Wallet Creation Fails\n- Verify `CROSSMINT_CLIENT_API_KEY` is correct\n- Check web interface environment variables\n- Ensure `NEXTAUTH_URL` matches web interface ngrok URL\n\n### Product Search Not Working\n- Verify `SEARCHAPI_KEY` is valid\n- Check SearchAPI.io quota/limits\n- Ensure internet connection is stable\n\n### ngrok Issues\n- Verify authtoken is configured: `ngrok config check`\n- Check if ports 3000/3001 are available\n- Try restarting ngrok: `ngrok start --all --config ngrok.yml`\n\n## 📚 Documentation\n\n- [Crossmint Documentation](https://docs.crossmint.com)\n- [Telegram Bot API](https://core.telegram.org/bots/api)\n- [Vercel AI SDK](https://sdk.vercel.ai)\n- [Next.js Documentation](https://nextjs.org/docs)\n\n## 👷 Support\n\nJoin our [telegram chat](https://t.me/+FmKl2FsaRKIzZjlk) if you have any questions.\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create feature branch: `git checkout -b feature/amazing-feature`\n3. Commit changes: `git commit -m 'Add amazing feature'`\n4. Push to branch: `git push origin feature/amazing-feature`\n5. Open Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n**Ready to revolutionize shopping with AI! 🛒🤖**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrossmint%2Fcrossmint-checkout-telegram-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrossmint%2Fcrossmint-checkout-telegram-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrossmint%2Fcrossmint-checkout-telegram-agent/lists"}