Skip to main content
The ouroborai Twitter bot monitors mentions on X/Twitter and replies with agent-generated responses. Users mention the bot with a trading intent (e.g. “@ouroborai swap 50 USDC for ETH”) and receive a threaded reply with the agent’s analysis or execution result.

​
How It Works

Twitter API (search) --> Mention Handler --> API Client --> Hono API Server
                                                               |
                                                         Agent Runner
                                                               |
Twitter API (tweet) <-- Format Reply <-- Poll Job Result <-----+
  1. The bot polls the Twitter v2 search endpoint every 30 seconds for new mentions.
  2. Each mention is stripped of the bot username and forwarded to POST /agent/prompt.
  3. The bot polls the job status until completion.
  4. The agent’s response is formatted for tweet length and posted as a reply thread.

​
Authentication

The bot uses OAuth 1.0a (user context) for posting tweets and a Bearer token for searching mentions. Both are configured via the twitter-api-v2 library.

​
Environment Variables

VariableRequiredDescription
TWITTER_BEARER_TOKENYesBearer token for search/read endpoints
TWITTER_API_KEYYesOAuth 1.0a consumer key
TWITTER_API_SECRETYesOAuth 1.0a consumer secret
TWITTER_ACCESS_TOKENYesOAuth 1.0a access token
TWITTER_ACCESS_SECRETYesOAuth 1.0a access token secret
TWITTER_BOT_USERNAMENoBot username without @ (default: ouroborai_bot)
ARB_API_URLNoAPI server URL (default: http://localhost:3000)
ARB_API_KEYNoAPI key for authenticated requests

​
Response Formatting

Responses are split into a tweet thread if they exceed the 280-character limit:
Posted as a single reply tweet. Markdown is stripped (bold, italic, code, headers, links) to produce clean plain text.
Split on sentence boundaries, with each tweet suffixed with a counter (e.g. (1/3), (2/3), (3/3)). Each tweet in the thread replies to the previous one, creating a readable reply chain.The suffix length (6 chars for (X/N)) is accounted for when splitting.

​
Rate Limiting

The bot enforces a per-user rate limit of one reply per 5 minutes. This prevents abuse from users who mention the bot repeatedly and protects against Twitter API rate limits. Rate limit state is held in-memory via a Map<authorId, timestamp>. The search query filters out retweets to avoid processing the same content multiple times: 
@ouroborai_bot -is:retweet
The since_id parameter tracks the newest processed tweet ID, ensuring each mention is handled exactly once across polling cycles.
The bot requests author_id, created_at, and conversation_id tweet fields, plus author_id expansions, to support threading and user attribution.

​
Setup

Go to the Twitter Developer Portal and create a project with read and write permissions. Generate all four OAuth 1.0a tokens plus a Bearer token.
Export all six authentication tokens plus the bot username.
bun run apps/twitter/src/index.ts
The bot logs the username and polling interval on startup, then begins polling immediately.
The Twitter API v2 search endpoint requires Elevated or Academic access for full archive search. The Basic tier supports recent search (last 7 days), which is sufficient for real-time mention monitoring.