{"id":26874208,"url":"https://github.com/vero-git-hub/xbot-ai","last_synced_at":"2025-03-31T09:34:15.361Z","repository":{"id":276982269,"uuid":"929936040","full_name":"vero-git-hub/xbot-ai","owner":"vero-git-hub","description":"Xbot AI is an AI-powered assistant for X (formerly Twitter) that fetches Google Trends, generates posts via Gemini AI, and logs interactions on the NEAR blockchain. Users can interact with the bot by mentioning @xbot_ai_. ","archived":false,"fork":false,"pushed_at":"2025-02-25T18:56:58.000Z","size":609,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-25T19:38:52.865Z","etag":null,"topics":["ai","ai-assistant","blockchain","flask","gemini-api","google-trends","java","near","oauth","python","react","spring-boot","twitter","twitter-bot","typescript","x-api","x-bot"],"latest_commit_sha":null,"homepage":"https://devpost.com/software/xbot-ai","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vero-git-hub.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2025-02-09T18:32:29.000Z","updated_at":"2025-02-25T19:12:55.000Z","dependencies_parsed_at":"2025-02-18T19:25:36.554Z","dependency_job_id":null,"html_url":"https://github.com/vero-git-hub/xbot-ai","commit_stats":null,"previous_names":["vero-git-hub/xbot-ai"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vero-git-hub%2Fxbot-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vero-git-hub%2Fxbot-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vero-git-hub%2Fxbot-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vero-git-hub%2Fxbot-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vero-git-hub","download_url":"https://codeload.github.com/vero-git-hub/xbot-ai/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246447808,"owners_count":20779050,"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","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":["ai","ai-assistant","blockchain","flask","gemini-api","google-trends","java","near","oauth","python","react","spring-boot","twitter","twitter-bot","typescript","x-api","x-bot"],"created_at":"2025-03-31T09:34:14.696Z","updated_at":"2025-03-31T09:34:15.349Z","avatar_url":"https://github.com/vero-git-hub.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🤖 XBot AI\n\n**XBot AI** is an **X-based intelligent agent** that integrates **Java Spring Boot, Gemini AI for getting trends and post generation, and blockchain logging on NEAR Testnet**. Users interact with the bot via **X mentions and replies**, enabling real-time trend analysis, AI-generated posts, and transparent blockchain logging.\n\n\n## ✨ Features\n\n- **X (formerly Twitter) Integration:** Users can interact with the bot via **X mentions and replies**.\n- **Trending Topics Analysis:** Fetch **real-time trending topics** using **Gemini**.\n- **AI-Powered Post Generation:** Uses **Gemini AI** to create engaging posts based on **selected trends**.\n- **Blockchain Logging (NEAR Testnet):** Logs posts and interactions for transparency.\n- **React-Based UI:** A **dashboard** for managing accounts, checking blockchain logs.\n\n🎯 **This project was created for the** [One Trillion Agents Hackathon](https://devpost.com/software/xbot-ai).\n\n\n## ⚙️ Architecture\n\n### **1️⃣ Core Technologies**\n| **Technology**             | **Version** | **Usage** |\n|----------------------------|-------------|------------------------------------------------|\n| **Java 23+ (Spring Boot)** | v3.4.2      | Backend for fetching data from X, AI content generation, blockchain API integration |\n| **Apache Maven**           | v3.9.9      | Dependency management \u0026 project build system for Java |\n| **Lombok**                 | v1.18.36    | Java annotation library to reduce boilerplate code    |\n| **Vite, React, TypeScript** | -           | UI for bot management \u0026 monitoring logs in blockchain |\n| **Node.js**                | v23.4.0     | JavaScript runtime for Vite \u0026 frontend tooling |\n| **npm, npx**               | v10.9.2     | Package management \u0026 script execution for frontend |\n| **Git \u0026 GitHub**           | -           | Version control \u0026 code hosting |\n| **Postman**                | 11.33.5     | API testing |\n| **IntelliJ IDEA**          | 2024.3.3    | Development environment |\n\n### **2️⃣ Blockchain \u0026 Smart Contracts**\n| **Component** | **Version** | **Usage** |\n|--------------|------------|------------------------------------------------|\n| **NEAR Protocol** | - | Blockchain platform for smart contracts, transaction processing |\n| **NEAR CLI** | v4.0.13 | Command-line interface for NEAR blockchain interaction |\n| **Node.js, JavaScript, WebAssembly (WASM)** | - | Smart contract deployment, method execution via near-api-js, NEAR interaction |\n| **UnencryptedFileSystemKeyStore** | - | NEAR authentication \u0026 key storage (.near-credentials) |\n| **WSL for Ubuntu** | - | NEAR contract compilation \u0026 deployment |\n| **MyNearWallet** | - | NEAR Testnet wallet |\n\n### **3️⃣ Data Fetching**\n| **API** | **Plan** | **Usage** |\n|--------|----------|---------------------------------------------|\n| **X API** | Free     | X API v2 (OAuth 1.0a via ScribeJava) |\n\n### **4️⃣ X Developer Platform**\n| **Component** | **Usage**                                       |\n|--------------|-------------------------------------------------|\n| **X Developer Platform** | Two developer accounts for XBot AI (user \u0026 bot) |\n\n### **5️⃣ X API Endpoints**\n| **Endpoint** | **Usage** |\n|-------------|----------------------------------------------|\n| `POST /2/tweets` | Post publishing |\n| `GET /2/users/:id/mentions` | Replying to mentions |\n| `GET /2/tweets/search/recent` | Searching for recent posts |\n| `GET /2/users/by/username/:username` | Fetching user details |\n\n### **6️⃣ Databases \u0026 Storage**\n| **Database**                           | **Usage** |\n|----------------------------------------|-------------------------------------------------------------|\n| **H2 (SQL), JPA, Lombok, Spring Boot** | Temporary local storage, ORM, and entity relationship management |\n| **User-SocialAccount Mapping**         | One-to-One entity linkage between User \u0026 SocialAccount/SocialAccountBot |\n| **JWT (JSON Web Token)**               | Authentication \u0026 session management |\n\n### **7️⃣ AI Integration**\n| **Service**                           | **Model**    -   | **Usage**                     |\n|---------------------------------------|------------------|-------------------------------|\n| **Gemini API (Google Cloud Console)** | gemini-1.5-flash | Get trends \u0026 generate post    |\n\n\n## 📥 Installation\n\n### 1️⃣ Clone the repository:\n\n```bash\n   git clone https://github.com/vero-git-hub/xbot-ai.git\n   cd xbot-ai\n   ```\n\n### 2️⃣Start the Project (2 services need to be running):\n\n✅ **Run backend service, start the Spring Boot service (Java):**\n\nCreate a file named **application-local.properties** in resources (example: ```src/main/resources/application-local-example.properties```). Fill in the file with your credentials:\n\n##### 🔹 Obtain a Google Cloud API Key\n\n1. Create an account on [Google Cloud](https://cloud.google.com/).\n2. Create a new project in **Google Cloud Console**\n3. Enable **Gemini API**\n4. Generate an **API Key**:\n  1. Go to **API \u0026 Services \u003e Credentials**\n  2. Click **\"Create Credentials\" \u003e \"API key\"**\n5. Add the API key to ```src/main/resources/application-local.properties```:\n\n```bash\n   google.cloud.api.key=your_google_cloud_api_key\n   ```\n\n##### 🔹 Generate jwt.secret\n\nOn **Windows (PowerShell):**\n\n```bash\n   [Convert]::ToBase64String((1..64 | ForEach-Object {Get-Random -Maximum 256}))\n   ```\n\nOn **Linux/macOS**:\n\n```bash\n   openssl rand -base64 64\n   ```\n\nAdd the **generated secret key** to ```src/main/resources/application.properties:```\n```bash\n   jwt.secret=your_jwt_secret\n   ```\n\n\n##### 🔹 Start the Spring Boot service:\n```bash\n   mvn spring-boot:run\n   ```\n\n\n✅ **Run frontend service, start Node.js (React UI):**\n```bash\n    cd frontend\n    npm install\n    npm run dev\n   ```\n\n---\n\n### 3️⃣ Configure X accounts via UI\n1. Open the UI interface:\n\n   🔗 Go to http://localhost:5173/\n\n2. Register a user:\n* Click REGISTER → Enter your details → Click REGISTER\n* You will be redirected to the login page\n* Enter the credentials you just registered → Click LOGIN\n\n#### ✅ Connect your X account\n\n🔹 Click **\"CONNECT YOUR ACCOUNT X\"**\n\nFill in the fields with your credentials. How to find them?\n\n1. **Log in or sign up** on [X Developer Platform](https://developer.x.com/en)\n2. Go to [Developer Dashboard](https://developer.twitter.com/en/portal/dashboard)\n3. In the left sidebar, click **Projects \u0026 Apps**, and select your project (default one)\n4. In the **User authentication settings** block, click **Edit and configure**:\n* **App permissions:** ```Read and write```\n* **Type of App:** ```Web App, Automated App, or Bot```\n* **App info:**\n  * **Callback URI / Redirect URL:** ```http://localhost:8080/auth/callback```\n  * **Website URL:** *(Any valid URL, e.g., GitHub repo)*\n5. Click **Save**\n6. Generate keys in Keys and Tokens tab:\n\n| Field              | Value |\n| -------------------|-------------------|\n| Username           | X account username  |\n| API Key            | Consumer Keys: API Key     |\n| API Secret         | Consumer Keys: API Secret     |\n| Access Token       | Authentication Tokens: Access Token    |\n| Access Token Secret| Authentication Tokens: Access Token Secret     |\n\n\n7. Get the User ID:\n\n* Retrieve the **Bearer Token** from the **Keys and tokens** tab\n\n* Use **Postman** or another API tool to make a request:\n\n```bash\n   GET https://api.twitter.com/2/users/by/username/YOUR_USERNAME\n   ```\n\n* Add the header:\n\n```bash\n   Authorization: Bearer YOUR_BEARER_TOKEN\n   ```\n* The response will contain an ```id``` field. Use this as **User ID** in the UI.\n\n9. Click **Save Settings → Back to Dashboard**\n\n---\n\n#### ✅ Connect bot X account\n\n🔹 Click **\"CONNECT BOT ACCOUNT X\"** and follow the same steps as for the personal account.\n\n📌 Note: Use your **bot's username** when mentioning the bot (e.g., ```@your_bot```).\n\n---\n\n### 4️⃣Connect NEAR for blockchain logging\n\n1. **Install NEAR CLI:**\n\n```bash\n   npm install -g near-cli\n   near --version\n   ```\n\n2. **Create a MyNearWallet account on the Testnet:**\n\n```bash\n   near login --networkId testnet\n   ```\n\nThis will store your credentials locally:\n\n```C:\\Users\\\u003cYOUR_USERNAME\u003e\\.near-credentials\\testnet```\n\n3. **Deploy the smart contract:**\n\nThe contract is already compiled into .wasm format and located at:\n\n```blockchain/ubuntu/near-logger-contract.wasm```\n\nTo deploy it to your Testnet account, run:\n\n```bash\n    cd blockchain\n    near deploy [your-name].testnet ubuntu/near-logger-contract.wasm\n    npm install near-api-js\n   ```\n\n---\n\n### 5️⃣Test the Bot Interaction in X\n\n#### 🟢 Step 1: Trigger the bot with a mention\n\n1. Open your X account and post:\n\n```bash\n    @[your_bot] trends\n   ```\n\n2. Set **Who can reply? → Only accounts you mention can reply** → Post\n\n3. Uncomment line 88:\n\n```bash\n    src/main/java/org/example/xbotai/service/core/impl/SocialMediaBotMentionService.java\n   ```\n\n```bash\n    @Scheduled(fixedDelay = 900000)\n   ```\n\nThis line enables bot mention tracking.\n\n❇️ API Free Plan has limitations. You can see them in [X Developer Platform](https://developer.twitter.com/en/portal/products) It's recommended to enable it only when everything is set up. ❇️\n\n4. Start both servers:\n\n```bash\n    mvn spring-boot:run\n    npm run dev\n   ```\n\n5. Check if the bot responds:\n```bash\n   Enter your country to search for trends (United States, Canada)\n   ```\n\n#### 🟢 Step 2: Provide a country for trend search\n\n1. Reply:\n\n```bash\n    country United States\n   ```\n\n2. **Restart the Java server** (to activate an additional endpoint to search for bot mentions):\n```bash\n    mvn spring-boot:run\n   ```\n\n3. The bot will fetch trends and respond:\n\n```bash\n    Trend1, Trend2, Trend3\n   ```\n\n#### 🟢 Step 3: Select a trend for AI post generation\n\n1. Reply with a trend:\n\n```bash\n    trend [selected-trend]\n   ```\n\n2. The bot will generate a post and publish it **after 15 minutes.**\n\n#### 🟢 Step 4: Bot confirms post publication\n\n✅ If everything works correctly, you will see:\n\n```bash\n    The post was posted on your behalf. Contact me again!\n   ```\n🔹 **Check your X account** to verify the post is published.\n\n🔹 **If the tweet doesn't appear**, make sure the services are running correctly and check the logs in Spring Boot.\n\n---\n\n### 6️⃣Test the Blockchain Interaction via UI\n\n1. **Log in to the UI**\n2. Click **\"GO TO NEAR CONSOLE\"**\n3. Check if your tweet is recorded **with a timestamp.**\n\n📌 **If no logs appear, make sure your NEAR contract is deployed successfully.**\n\n🎯 Final Notes\n\n🔹 API **rate limits** apply! Monitor them in **X Developer Portal**.\n\n🔹 **Automate your social media posts securely with XBot AI!** 🚀\n\n\n## 📡 API Endpoints\n\n### 🔑 Authentication\n\n* POST ```/api/auth/login``` — Log in and receive a JWT token.\n* POST ```/api/auth/register``` — Register a new user.\n\n### 🌍 Fetching Trends Data\n* GET ```/api/bot/trends``` — Retrieve trending topics.\n\n### 📝 Post Generation \u0026 AI\n\n* POST ```/api/bot/select-trend``` — Select a trend.\n* GET ```/api/bot/generate-tweet``` — Generate a post.\n* POST ```/api/bot/post-tweet``` — Post a tweet.\n\n### 🔗 Blockchain Logging\n\n* GET ```/api/blockchain/logs``` — View post logs stored on the blockchain.\n\n### 🪪 Local Links\n\n* Frontend UI: http://localhost:5173\n* H2 Database Console: http://localhost:8080/h2-console\n\n\n## 🧠 Gemini AI Integration\n\n🔹 **How It Works:**\n\n1️⃣ Retrieves **trending topics** by country from **Gemini**.\n\n2️⃣ Processes the trend and sends it to **Gemini**.\n\n3️⃣ Generates on **AI-powered post**.\n\n4️⃣ Publishes the post on **X**.\n\n5️⃣ Logs the interaction on **NEAR Testnet** for transparency.\n\n\n## 🚀 Future Improvements\n\n🔹 More blockchain integrations.\n\n🔹 AI-powered trend analysis for better post engagement.\n\n🔹 Multimedia post support (images, videos, polls).\n\n\n## 📜 License\n\n🔹 **MIT License** – Open-source and free to modify.\n\n🔹 **XBot AI – your AI-powered assistant for X**.\n\n✨ Automate, publish, and analyze trends effortlessly! 🚀","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvero-git-hub%2Fxbot-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvero-git-hub%2Fxbot-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvero-git-hub%2Fxbot-ai/lists"}