Skip to content

Update README.md #172

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
celesteanglm merged 1 commit into from
Jun 17, 2025
Merged

Update README.md #172

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 56 additions & 56 deletions plugins/twitter/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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`:

Expand All @@ -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:

Expand Down Expand Up @@ -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
Expand Down