> ## Documentation Index > Fetch the complete documentation index at: https://docs.twexapi.io/llms.txt > Use this file to discover all available pages before exploring further. # Hermes XAPI for Hermes Agent > Install and configure the Hermes XAPI plugin for Twexapi-powered X/Twitter automation in Hermes Agent. Hermes XAPI is the native Hermes Agent plugin for using Twexapi as a structured X/Twitter automation toolset. It packages the Twexapi endpoint catalog, read tools, optional action tools, slash commands, and a bundled Hermes skill into a Python plugin. Use Hermes XAPI when a Hermes Agent workflow needs X/Twitter search, account reads, profile lookups, trends, followers, replies, articles, DMs, tweet posting, likes, retweets, follows, or account status checks. ## Prerequisites * Python `3.11` or newer * Hermes Agent with plugin support * A Twexapi API key from the [dashboard](https://twexapi.io/dashboard) Hermes plugins are opt-in. Install and enable the plugin before expecting the `hermes-xapi` toolset to appear. ## Install Use Hermes' plugin installer for the public GitHub repo: ```bash theme={null} hermes plugins install twexapi-dev/hermes-xapi --enable ``` Hermes prompts for `TWEXAPI_KEY` during an interactive install and stores it in `~/.hermes/.env`. Non-interactive installs skip the prompt. Set the key in the process environment or `~/.hermes/.env` before calling `xapi_read`. Install the published PyPI package directly into the Hermes Python environment when you manage package installation yourself: ```bash theme={null} uv pip install --python ~/.hermes/hermes-agent/venv/bin/python hermes-xapi hermes plugins enable hermes-xapi ``` If your Hermes Python environment includes `pip`, this path is also valid: ```bash theme={null} ~/.hermes/hermes-agent/venv/bin/python -m pip install hermes-xapi hermes plugins enable hermes-xapi ``` The current package version is `0.1.6`. The plugin name is `hermes-xapi`, and the Python entry point is `hermes-xapi = hermes_xapi`. ## Configure Set your Twexapi API key before starting Hermes: ```bash theme={null} export TWEXAPI_KEY="twitterx_..." ``` For persistent Hermes sessions, add the key to `~/.hermes/.env`: ```bash theme={null} TWEXAPI_KEY=twitterx_... ``` Optional environment variables: ```bash theme={null} export TWEXAPI_BASE_URL="https://api.twexapi.io" export HERMES_XAPI_ENABLE_ACTIONS="false" ``` Keep `HERMES_XAPI_ENABLE_ACTIONS=false` for unattended sessions. Enable actions only for workflows with an explicit approval step: ```bash theme={null} export HERMES_XAPI_ENABLE_ACTIONS="true" ``` If Hermes is already running after you edit `~/.hermes/.env`, run `/reload` in an interactive CLI session, or restart gateway and cron sessions before calling `xapi_read`. ## Tools | Tool | Purpose | | -------------- | --------------------------------------------------------------------------------------------------------------- | | `xapi_explore` | Search the bundled Twexapi endpoint catalog without making an API call. Use it before every live endpoint call. | | `xapi_read` | Call catalog-listed read-only endpoints after `TWEXAPI_KEY` is configured. | | `xapi_action` | Call private, paid-bulk, or write-like endpoints only when `HERMES_XAPI_ENABLE_ACTIONS=true`. | Start with `xapi_explore` so the agent can discover the right method, path, parameters, and response shape before it calls an endpoint. ```txt theme={null} Use xapi_explore to find the endpoint for user lookup, then call xapi_read for @username. ``` ## Workflow handoffs Use `xapi_explore` first, then choose `xapi_read` for public reads or `xapi_action` for approved jobs that create or change state. ### Tweet search read Use `xapi_read` with `/twitter/advanced_search` or another catalog-listed search endpoint. Return tweet IDs, text, author usernames, timestamps, engagement metrics, `has_more`, and `next_cursor` when present. ```txt theme={null} Use xapi_explore to find tweet search endpoints. Use xapi_read for /twitter/advanced_search with searchTerms ["AI agents"] and maxItems 25. Return tweet_id, text, author_username, created_at, and engagement counts. ``` ### Trend research Use `xapi_explore` to find trending routes, then call `xapi_read` for country, topic, content, or trend endpoints. ```txt theme={null} Use xapi_explore to find X/Twitter trend endpoints. Use xapi_read to return current trends for worldwide. Preserve the country, topic, content, rank, has_more, and next_cursor fields when present. ``` ### Follower export Use `xapi_explore` to find follower endpoints. Use `xapi_read` for bounded reads and `xapi_action` only when the catalog marks the route as private, paid-bulk, or action-like. ```txt theme={null} Use xapi_explore to find follower export endpoints. Fetch followers for @username with a bounded count. If the response returns a task_id, store it and poll the documented status and next-page routes. ``` ### Controlled write action Use `xapi_action` only after approval. Keep action tools disabled in unattended sessions. ```txt theme={null} Use xapi_explore with include_actions true to find tweet posting endpoints. Draft the exact request body. Ask for explicit approval. Only after approval, call xapi_action. Return tweet_id, status, charged_credits, and any write action ID. ``` ## Runtime diagnostics For scriptable checks, use `hermes tools list`. Bare `hermes tools` opens the interactive tool UI and requires a TTY. ```bash theme={null} hermes tools list ``` Run a non-mutating one-shot probe after the plugin is enabled: ```bash theme={null} hermes -z "Use xapi_explore, then read /twitter/elonmusk/about. Do not call xapi_action." --toolsets hermes-xapi ``` Expected behavior: * `xapi_explore` can inspect catalog endpoints without an API key. * Without `TWEXAPI_KEY`, a non-mutating Hermes probe exposes `xapi_explore` only. * After `TWEXAPI_KEY` is configured and the CLI is reloaded, or the gateway or cron process is restarted, `xapi_read` can read `/twitter/elonmusk/about`. * `xapi_action` stays hidden or disabled unless `HERMES_XAPI_ENABLE_ACTIONS=true`. * `/xstatus` and `/xtrends` appear in the Hermes plugin command registry. Hermes one-shot prompts do not dispatch `/xstatus` as an interactive slash command. Verify slash commands in an active CLI, TUI, Desktop, or gateway session, and use `hermes -z` for tool-call probes. Non-interactive installs cannot prompt for credentials; set `TWEXAPI_KEY` in the process environment or `~/.hermes/.env`. ## Slash commands | Command | Purpose | | ---------- | --------------------------------------------------------------------------------- | | `/xstatus` | Show Twexapi account, subscription, and usage status in an active Hermes session. | | `/xtrends` | Show current X/Twitter trends from the plugin command registry. | ## Safety model Hermes XAPI reads auth from environment variables and injects it at request time. The model does not receive the API key as a tool argument. The plugin blocks cookie/token helper routes, engagement-purchase routes, auto-cookie posting, profile mutation, list creation, and sentiment routes from the agent catalog. Private reads, paid-bulk endpoints, and write-like endpoints go through `xapi_action`, which stays hidden unless `HERMES_XAPI_ENABLE_ACTIONS=true`. For unattended jobs, keep action tools disabled and use only `xapi_explore` plus `xapi_read`. ## API coverage Hermes XAPI includes 76 agent-callable Twexapi endpoints generated from the OpenAPI contract. | Area | Common uses | | --------------------- | --------------------------------------------------------------------------------------------------------- | | Public reads | Tweet search, tweet lookup, user lookup, timelines, articles, replies, and trends. | | Private reads | Account status, balance, and account-level checks. | | Relationship data | Followers, following, retweeters, quote tweets, and favoriters. | | Communities and lists | Community metadata, members, tweets, list tweets, subscribers, and members. | | Actions | Tweet, reply, like, retweet, follow, DM, media, bookmarks, articles, and account operations when enabled. | ## Local development For local plugin development, regenerate the bundled catalog from the Twexapi OpenAPI contract: ```bash theme={null} python scripts/build_catalog.py ../twexapi/openapi.yaml ``` Run that command from the `hermes-xapi` repository after the Twexapi OpenAPI file changes. ## Verify After installing, enabling, and setting `TWEXAPI_KEY`, run: ```txt theme={null} /xstatus ``` For scriptable diagnostics, list the plugin toolset: ```bash theme={null} hermes tools list ``` Then test a read workflow: ```txt theme={null} Use xapi_explore to find X/Twitter trends, then use xapi_read to return current trends. ``` For action workflows, require an explicit draft and approval step before enabling `xapi_action`. ## Troubleshooting | Problem | Fix | | ------------------------- | ------------------------------------------------------------------------------------------------------------ | | Tools missing | Run `hermes plugins enable hermes-xapi`, then confirm `hermes-xapi` appears in `hermes tools list`. | | Auth fails | Confirm `TWEXAPI_KEY` is exported in the same environment that starts Hermes, or stored in `~/.hermes/.env`. | | Env changes not picked up | Run `/reload` in the interactive CLI, or restart gateway and cron sessions. | | Action tool hidden | Set `HERMES_XAPI_ENABLE_ACTIONS=true` only for approved action workflows. | | Endpoint missing | Regenerate the catalog from the current Twexapi OpenAPI file in local development. | | Risky writes | Keep `HERMES_XAPI_ENABLE_ACTIONS=false` and use read tools only. | ## Relationship to XApiClaw XApiClaw is the OpenClaw-native npm plugin. Hermes XAPI is the Hermes-native Python plugin. Both use the same Twexapi API contract and expose agent-safe catalog discovery before live endpoint calls. ## References * [Hermes XAPI GitHub repo](https://github.com/twexapi-dev/hermes-xapi) * [Hermes XAPI on PyPI](https://pypi.org/project/hermes-xapi/) * [Hermes Agent](https://github.com/NousResearch/hermes-agent) * API Reference in the sidebar * [MCP Server](/mcp/overview)