Merge pull request #172 from game-by-virtuals/read-me-changes

Update README.md

Author: celesteanglm

plugins/twitter/README.md

@@ -2,9 +2,62 @@
 
 The **Twitter Plugin** provides a lightweight interface for integrating Twitter (X) functionality into your GAME SDK agents. Built on top of [`virtuals_tweepy`](https://pypi.org/project/virtuals-tweepy/) by the Virtuals team — a maintained fork of [`Tweepy`](https://pypi.org/project/tweepy/)) — this plugin lets you easily post tweets, fetch data, and execute workflows through agent logic.
 
-Use it standalone or compose multiple Twitter actions as part of a larger agent job.
+## 📜 GAME X API Usage Terms & Rules
+By using the GAME X API, you agree to the following terms. Violation of any rule may result in immediate revocation of access. We reserve the right to modify API behavior, limits, or access rights at any time, with or without notice.
+
+### ✅ Allowed Usage (Green Flags)
+#### General
+- Keep under 50 posts/day
+- Follow/unfollow: <100/day
+- Use organic, varied language—avoid robotic or repetitive posts
+- Use a mix of images, videos, and text-based content
+- Include polls, threads, quotes, retweets to encourage engagement
+- Mark account as sensitive if needed
+- Always include the automated label for agent-generated content
+
+#### Replies, Mentions, and DMs
+- Max 10 replies/hour to different users
+- Max 10 DMs/day to new users
+- Agent may only reply or DM when:
+- User mentions, replies, retweets, or DMs the agent
+- Only 1 automated reply/DM per interaction
+- Always validate post existence before replying (statuses/lookup)
+- Filter for sensitive usernames/media/content
+
+#### ✉️ DM Rules
+- DMs must be triggered by valid user interaction
+
+Only use:
+- GET /dm_conversations
+- GET /dm_events
+- POST /dm_events/new
+- No crawling, scraping, or off-platform storage of DM data
+- No DMs used to bypass rate limits or coordinate bot activity
+- One DM per user trigger, no spamming
+
+### 🚫 Prohibited Activity (Red Flags)
+- ❌ Liking tweets, adding users to lists/collections
+- ❌ Engagement farming (e.g., repetitive “Like if…” prompts)
+- ❌ Auto-posting about trending topics
+- ❌ Duplicate phrases across posts/accounts
+- ❌ Tweet bursts (post every 10–15 mins, minimum)
+- ❌ Over-replying or over-DMing
+- ❌ Misleading or redirect-heavy links
+- ❌ Harassment, abuse, hate speech, or doxxing
+- ❌ Cloning multiple automated accounts for similar purposes
+
+## 🚀 API Access Tiers
+### Tier 1 — Default
+- Basic access
+- Standard rate limits
+
+### Tier 2 — Elevated
+- Higher rate limits
+- Request access via Discord → @virtualsio
+- Requires verification
 
 ---
+Use it standalone or compose multiple Twitter actions as part of a larger agent job.
 
 ## Installation
 
@@ -23,18 +76,13 @@ pip install twitter_plugin_gamesdk
 ---
 
 ## Authentication Methods
-
-We support two primary ways to authenticate:
-
-### 1. GAME's Sponsored X Enterprise Access Token (Recommended)
-
 Virtuals sponsors the community with a **Twitter Enterprise API access plan**, using OAuth 2.0 with PKCE. This provides:
 
 - Higher rate limits: **35 calls / 5 minutes**
 - Smoother onboarding
 - Free usage via your `GAME_API_KEY`
 
-#### a. Get Your Access Token
+#### 1. Get Your Access Token
 
 Run the following command to authenticate using your `GAME_API_KEY`:
 
@@ -54,7 +102,7 @@ Authenticated! Here's your access token:
 apx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 ```
 
-#### b. Store Your Access Token
+#### 2. Store Your Access Token
 
 We recommend storing environment variables in a `.env` file:
 
@@ -84,54 +132,6 @@ client = twitter_plugin.twitter_client
 
 client.create_tweet(text="Tweeting with GAME Access Token!")
 ```
-
----
-
-### 2. Use Your Own Twitter Developer Credentials
-
-Use this option if you need access to Twitter endpoints requiring a different auth level (e.g., **OAuth 1.0a User Context** or **OAuth 2.0 App Only**).
-
-> See [X API Auth Mapping](https://docs.x.com/resources/fundamentals/authentication/guides/v2-authentication-mapping) to determine which auth level is required for specific endpoints.
-
-#### a. Get Your Developer Credentials
-
-1. Sign in to the [Twitter Developer Portal](https://developer.x.com/en/portal/dashboard).
-2. Create a project and app.
-3. Generate the following keys and store them in your `.env` file:
-
-```
-# .env
-
-TWITTER_API_KEY=...
-TWITTER_API_SECRET_KEY=...
-TWITTER_ACCESS_TOKEN=...
-TWITTER_ACCESS_TOKEN_SECRET=...
-```
-
-#### b. Initialize the Plugin
-
-```python
-import os
-from dotenv import load_dotenv
-from twitter_plugin_gamesdk.twitter_plugin import TwitterPlugin
-
-load_dotenv()
-
-options = {
-    "credentials": {
-        "api_key": os.environ.get("TWITTER_API_KEY"),
-        "api_key_secret": os.environ.get("TWITTER_API_SECRET_KEY"),
-        "access_token": os.environ.get("TWITTER_ACCESS_TOKEN"),
-        "access_token_secret": os.environ.get("TWITTER_ACCESS_TOKEN_SECRET"),
-    }
-}
-
-twitter_plugin = TwitterPlugin(options)
-client = twitter_plugin.twitter_client
-
-client.create_tweet(text="Tweeting with personal developer credentials!")
-```
-
 ---
 
 ## Examples