Paperclip - twexapi

The TwexAPI Paperclip plugin adds six read-only Twitter/X tools to Paperclip agents. It wraps documented TwexAPI REST routes with typed tool schemas, secret-backed authentication, and predictable JSON results. Use this plugin when a Paperclip agent needs tweet search, profile lookup, user search, timeline reads, or global trending tweets without writing raw HTTP calls.

Tools

Agent task	Paperclip tool	TwexAPI route
Search tweets	`twexapi.search_tweets`	`POST /twitter/advanced_search/page`
Read one tweet	`twexapi.lookup_tweet`	`POST /v2/tweet/detail`
Search users	`twexapi.search_users`	`GET /twitter/search-user/{keyword}/{target_count}`
Read a profile	`twexapi.get_user`	`GET /twitter/{screen_name}/about`
Read profile tweets	`twexapi.get_user_tweets`	`POST /twitter/{screen_name}/timeline/page`
Read trending tweets	`twexapi.get_trends`	`GET /twitter/global-trending/tweets`

This plugin does not export followers or publish posts. Use the REST API, CLI, or MCP Server for those tasks.

Prerequisites

Node.js 18 or newer
Paperclip CLI (paperclipai)
A TwexAPI API key from the dashboard
A Paperclip secret reference for the API key

Install

paperclipai plugin install @twexapi-dev/paperclip-plugin-x-api-scraper

Pin the current release when you need reproducible installs:

paperclipai plugin install @twexapi-dev/paperclip-plugin-x-api-scraper --version 0.1.2

npm: @twexapi-dev/paperclip-plugin-x-api-scraper Source: twexapi-dev/paperclip-plugin-x-api-scraper

Configure

Create an API key in the TwexAPI dashboard. Store it in a Paperclip secret and reference it from the plugin config.

Setting	Purpose
`apiBaseUrl`	TwexAPI REST endpoint. Defaults to `https://api.twexapi.io`.
`apiKeySecretRef`	Paperclip secret reference for the TwexAPI API key.
`defaultTimelineCount`	Default timeline page count from 1 to 100.
`defaultUserSearchCount`	Default user search count from 1 to 100.
`defaultTrendCount`	Default trend count from 1 to 100.

Paperclip resolves the API key at call time and sends Authorization: Bearer. Example plugin config shape:

{
  "apiBaseUrl": "https://api.twexapi.io",
  "apiKeySecretRef": "twexapi/api-key",
  "defaultTimelineCount": 20,
  "defaultUserSearchCount": 10,
  "defaultTrendCount": 20
}

Never commit API keys to plugin config files checked into source control.

Example agent tasks

Search tweets

Ask the agent to search recent posts about a topic. The plugin calls POST /twitter/advanced_search/page through twexapi.search_tweets. Suggested prompt:

Search X for recent posts about "AI agents lang:en -filter:retweets".
Return tweet IDs, author usernames, text, and created_at for the top 10 results.

Read a profile and timeline

Look up @openai, then read the latest timeline page.
Return username, user_id, follower count, and the 5 most recent tweet IDs.

Get trending tweets for United States, topic Sports, content NFL.
Summarize the top themes and list 5 representative tweet IDs.

Handoff checklist

When Paperclip agents hand results to downstream systems, preserve stable identifiers.

Data type	Store
Tweets	`tweet_id`, `text`, `author_username`, `created_at`, search query
Profiles	`user_id`, `username`, `name`, follower counts
Trends	country, topic, content tag, tweet rows
Pagination	`next_cursor`, `has_more`, original request parameters

See Agent MCP Handoff when mixing Paperclip tools with MCP-based agents in the same workflow.

Error handling

Status	Action
`400`	Fix tool input. Do not retry unchanged.
`401`	Check the Paperclip secret reference and API key value.
`403`	Check account access and credits.
`429`	Back off before retrying.
`5xx`	Retry with bounded backoff.

Develop locally

git clone https://github.com/twexapi-dev/paperclip-plugin-x-api-scraper.git
cd paperclip-plugin-x-api-scraper
pnpm install
pnpm check

pnpm check runs type checks, tests, and the build.

​Tools

​Prerequisites

​Install

​Configure

​Example agent tasks

​Search tweets

​Read a profile and timeline

​Read global trending tweets

​Handoff checklist

​Error handling

​Develop locally

​Related guides