> ## Documentation Index
> Fetch the complete documentation index at: https://ouroborai.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Twitter Bot

> Autonomous agent on X/Twitter

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](https://github.com/PLhery/node-twitter-api-v2) library.

## Environment Variables

| Variable                | Required | Description                                       |
| ----------------------- | -------- | ------------------------------------------------- |
| `TWITTER_BEARER_TOKEN`  | Yes      | Bearer token for search/read endpoints            |
| `TWITTER_API_KEY`       | Yes      | OAuth 1.0a consumer key                           |
| `TWITTER_API_SECRET`    | Yes      | OAuth 1.0a consumer secret                        |
| `TWITTER_ACCESS_TOKEN`  | Yes      | OAuth 1.0a access token                           |
| `TWITTER_ACCESS_SECRET` | Yes      | OAuth 1.0a access token secret                    |
| `TWITTER_BOT_USERNAME`  | No       | Bot username without @ (default: `ouroborai_bot`) |
| `ARB_API_URL`           | No       | API server URL (default: `http://localhost:3000`) |
| `ARB_API_KEY`           | No       | API key for authenticated requests                |

## Response Formatting

Responses are split into a tweet thread if they exceed the 280-character limit:

<AccordionGroup>
  <Accordion title="Short responses (under 280 chars)">
    Posted as a single reply tweet. Markdown is stripped (bold, italic, code,
    headers, links) to produce clean plain text.
  </Accordion>

  <Accordion title="Long responses (over 280 chars)">
    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.
  </Accordion>
</AccordionGroup>

## 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>`.

## Mention Search

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.

<Info>
  The bot requests `author_id`, `created_at`, and `conversation_id` tweet
  fields, plus `author_id` expansions, to support threading and user
  attribution.
</Info>

## Setup

<AccordionGroup>
  <Accordion title="1. Create a Twitter Developer App">
    Go to the [Twitter Developer Portal](https://developer.twitter.com/) and
    create a project with read and write permissions. Generate all four OAuth
    1.0a tokens plus a Bearer token.
  </Accordion>

  <Accordion title="2. Set environment variables">
    Export all six authentication tokens plus the bot username.
  </Accordion>

  <Accordion title="3. Start the bot">
    ```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
    bun run apps/twitter/src/index.ts
    ```

    The bot logs the username and polling interval on startup, then begins
    polling immediately.
  </Accordion>
</AccordionGroup>

<Warning>
  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.
</Warning>