XBot AI is an intelligent agent for X (formerly Twitter) that integrates Gemini AI for trend detection and content generation, combined with blockchain logging on NEAR Testnet. Users interact with the bot via mentions and replies, enabling real-time trend analysis, AI-generated content, and transparent on-chain activity logging.

• Wildcard Track Winner (AI & Autonomous Infrastructure) at PL_Genesis: Modular Worlds Hackathon
• Founders Forge Top 15 Pick (selected among the top ~4% of projects)

One Trillion Agents Hackathon

• X Integration: Interact with the bot via X mentions and replies on X.
• Trending Topics Analysis: Fetch trending topics using Gemini AI.
• AI-Powered Post Generation: Create post based on selected trend.
• Blockchain Logging (v1): Logs posts and interactions for transparency.
• React-Based UI: Manage accounts, check blockchain logs.

PL_Genesis: Modular Worlds Hackathon

• Bearer Token Support: Auto-fetch userId via username and token.
• Processed Tweet Tracking: DB-level deduplication of handled tweets.
• UI Enhancements: Improved layout, auto-fill, clearer labels.
• Reduced API Usage: Removed redundant X API calls to respect limits.
• Local Auth Bypass: Disabled JWT for internal endpoints during local dev.
• Optimized Logging (v2): Logs minimal tweet metadata to NEAR for verifiable, gas-efficient tracking.

1. ⚡️ The Agentic Internet & AI-led Web3 Experiences

XBot AI is an autonomous agent that interacts with users on X, generates AI-driven content, and logs activity to the NEAR Testnet, forming a working prototype of an AI-led Web3 integration.

2. 🧠 Wildcard: AI & Autonomous Infrastructure

A non-traditional and expressive AI agent that exhibits autonomy, input-aware behavior, and meaningful decision-making. It uses trending data, filters duplicates, and acts independently based on user prompts.

3. 🧱 Protocol Labs: Existing Code

This project began earlier and has evolved significantly for PL_Genesis. New features were added, the UI and backend logic improved, and the architecture was refined to match hackathon goals.

Editors: IntelliJ IDEA Ultimate (2025.1.3), VS Code.

Two developer accounts used (bot & user) on X platform.

 git clone https://github.com/vero-git-hub/xbot-ai.git
 cd xbot-ai

First, create a file named application-local.properties in the src/main/resources directory (example in the application-local-example.properties).

✅ 1. Configure Bot's X Account

You will need a dedicated X account to act as your bot.

First, obtain all developer credentials for this account from the X Developer Portal. Here’s how:

1. Log in or sign up on Developer Portal.
2. In the left sidebar, click Projects & Apps, and select your project (default one).
3. In the User authentication settings, click Edit and configure.
4. Configure the settings as follows:

• App permissions: Read and write
• Type of App: Web App, Automated App, or Bot
• Callback URI / Redirect URL: http://localhost:8080/auth/callback
• Website URL: (Any valid URL, e.g., GitHub repo)

5. Click Save.
6. Navigate to the Keys and Tokens tab to generate and view all your keys.

Next, add these credentials to your application-local.properties file.

xbot.credentials.bot.username=YOUR_BOT_USERNAME_WITHOUT_AT

# Leave this empty for now; you will get it in the next step
xbot.credentials.bot.user-id=

xbot.credentials.bot.api-key=YOUR_BOT_API_KEY
xbot.credentials.bot.api-secret=YOUR_BOT_API_SECRET

# The Bearer Token below is needed once to get the User ID
xbot.credentials.bot.jwt-token=YOUR_BOT_BEARER_TOKEN

xbot.credentials.bot.access-token=YOUR_BOT_ACCESS_TOKEN
xbot.credentials.bot.access-token-secret=YOUR_BOT_ACCESS_TOKEN_SECRET

Finally, get your Bot's User ID. The userId is not displayed on the X dashboard. Use Postman to make the following API request:

• Method: GET

• URL: https://api.twitter.com/2/users/by/username/YOUR_BOT_USERNAME_HERE

• Headers:

  • Authorization: Bearer YOUR_BOT_BEARER_TOKEN_HERE

Copy the id from the JSON response and paste it into the xbot.credentials.bot.user-id field in your application-local.properties file.

✅ 2. Configure Google Cloud API

1. Create an account and a new project on Google Cloud.
2. Enable the Gemini API.
3. Generate an API Key in API & Services > Credentials.

Add the API key to application-local.properties:

google.cloud.api.key=your_google_cloud_api_key  

✅ 3. Configure JWT Secret

Run one of the following commands in your terminal:

[Convert]::ToBase64String((1..64 | ForEach-Object {Get-Random -Maximum 256}))  
  
# Linux/macOS:  
openssl rand -base64 64  

Add the key to application-local.properties:

 jwt.secret=your_jwt_secret  

1. Run backend service:

mvn spring-boot:run  

2. Run frontend service (in a new terminal):

 cd frontend
 npm install
 npm run dev  

1. Open the UI interface in your browser: http://localhost:5173/.
2. Register a new user for the service and log in.
3. Click "CONNECT YOUR ACCOUNT X" on the main page.
4. Fill in the fields with credentials from your personal X developer account. The process to obtain these is the same as described in Configure Bot’s X Account step above.
5. After filling in the form, click the save settings button.

📌 Note: When testing, use your bot's username (e.g., @your_bot_username) to mention the bot in your tweets.

To write logs to the blockchain, the backend script needs to sign transactions. This requires access to a NEAR Testnet account's keys. This is a one-time setup for your local development environment.

1. Install NEAR CLI:

npm install -g near-cli

2. Authorize Your Local Machine:

near login

After you authorize, near-cli will automatically create a key file in ~/.near-credentials (for Linux/macOS) or C:\Users\YOUR_USERNAME\.near-credentials (for Windows).

The application's script will automatically use these credentials to sign transactions when running on your local machine. You are not deploying a new contract, only setting up the "key" needed to write to the existing one.

1. Open your X account and click "Post".
2. Set Who can reply? → Only accounts you mention can reply.
3. Send a post with text:

@[your_bot] trends

4. Uncomment line in the src/main/java/.../service/core/impl/SocialMediaBotMentionService.java file:

@Scheduled(fixedDelay = 60000)

This line enables bot mention tracking.

❇️ API Free Plan has limitations. You can see them in X Developer Platform It's recommended to enable it only when everything is set up. ❇️

5. Start both servers:

mvn spring-boot:run

cd frontend
npm run dev

1. The bot will fetch trends and respond:

 Trend1, Trend2, Trend3

2. Reply with a trend:

 trend [selected-trend]

3. The bot will generate a post and publish it from your username.

If everything works correctly, you will see:

🔹 Check your X account to verify the post is published.

🔹 If the tweet doesn't appear, make sure the services are running correctly and check the logs in Spring Boot.

1. Log in to the UI: http://localhost:5173/ .
2. Click "GO TO NEAR CONSOLE"
3. Check if your tweet is recorded with a metadata: Tweet ID, User ID, URL, Trend, Timestamp.

📌 If no logs appear, make sure your NEAR contract is deployed successfully.

• POST /api/auth/login — Log in and receive a JWT token.
• POST /api/auth/register — Register a new user.

• GET /api/bot/trends — Retrieve trending topics.

• POST /api/bot/select-trend — Select a trend.
• GET /api/bot/generate-tweet — Generate a tweet.
• POST /api/bot/post-tweet — Post a tweet.

• GET /api/blockchain/logs — View post logs stored on the blockchain.

• H2 Database Console: http://localhost:8080/h2-console:

  • JDBC URL — jdbc:h2:file:./data/xbot-ai-db

This project is licensed under the MIT License – free to use, modify, and distribute.

Contributions are welcome! If you find bugs, want to add features, or improve documentation, feel free to open an issue or submit a pull request.