Paperclip

Instala el plugin Paperclip de TwexAPI para búsqueda de tweets, perfiles, líneas de tiempo y tweets en tendencia en agentes Paperclip.

El plugin Paperclip de TwexAPI añade seis herramientas de solo lectura de Twitter/X a agentes de Paperclip. Envuelve rutas REST documentadas de TwexAPI con esquemas de herramientas tipados, autenticación respaldada por secretos y resultados JSON predecibles.

Usa este plugin cuando un agente Paperclip necesite búsqueda de tweets, consulta de perfiles, búsqueda de usuarios, lectura de líneas de tiempo o tweets en tendencia global sin escribir llamadas HTTP en bruto.

Herramientas

Tarea del agente	Herramienta Paperclip	Ruta de TwexAPI
Buscar tweets	`twexapi.search_tweets`	`POST /twitter/advanced_search/page`
Leer un tweet	`twexapi.lookup_tweet`	`POST /v2/tweet/detail`
Buscar usuarios	`twexapi.search_users`	`GET /twitter/search-user/{keyword}/{target_count}`
Leer un perfil	`twexapi.get_user`	`GET /twitter/{screen_name}/about`
Leer tweets de perfil	`twexapi.get_user_tweets`	`POST /twitter/{screen_name}/timeline/page`
Leer tweets en tendencia	`twexapi.get_trends`	`GET /twitter/global-trending/tweets`

Este plugin no exporta seguidores ni publica posts. Usa la REST API, el CLI o el MCP Server para esas tareas.

Requisitos previos

Node.js 18 o más reciente
Paperclip CLI (paperclipai)
Una API key de TwexAPI desde el dashboard
Una referencia de secreto de Paperclip para la API key

Instalación

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

Fija la versión actual cuando necesites instalaciones reproducibles:

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

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

Fuente: twexapi-dev/paperclip-plugin-x-api-scraper

Configurar

Crea una API key en el dashboard de TwexAPI. Guárdala en un secreto de Paperclip y refiérenciala desde la configuración del plugin.

Configuración	Propósito
`apiBaseUrl`	Endpoint REST de TwexAPI. Por defecto `https://api.twexapi.io`.
`apiKeySecretRef`	Referencia de secreto de Paperclip para la API key de TwexAPI.
`defaultTimelineCount`	Cantidad de páginas de línea de tiempo por defecto de 1 a 100.
`defaultUserSearchCount`	Cantidad de búsqueda de usuarios por defecto de 1 a 100.
`defaultTrendCount`	Cantidad de tendencias por defecto de 1 a 100.

Paperclip resuelve la API key en tiempo de llamada y envía Authorization: Bearer.

Ejemplo de forma de configuración del plugin:

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

Nunca subas API keys a archivos de configuración del plugin en control de versiones.

Tareas de agente de ejemplo

Buscar tweets

Pide al agente que busque publicaciones recientes sobre un tema. El plugin llama a POST /twitter/advanced_search/page a través de twexapi.search_tweets.

Prompt sugerido:

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.

Leer un perfil y línea de tiempo

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

Leer tweets en tendencia global

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

Lista de verificación de entrega

Cuando los agentes Paperclip entregan resultados a sistemas posteriores, conserva identificadores estables.

Tipo de dato	Almacenar
Tweets	`tweet_id`, `text`, `author_username`, `created_at`, consulta de búsqueda
Perfiles	`user_id`, `username`, `name`, cantidades de seguidores
Tendencias	país, tema, etiqueta de contenido, filas de tweets
Paginación	`next_cursor`, `has_more`, parámetros de solicitud originales

Consulta Agent MCP Handoff cuando mezcles herramientas Paperclip con agentes basados en MCP en el mismo flujo de trabajo.

Manejo de errores

Estado	Acción
`400`	Corrige la entrada de la herramienta. No reintentes sin cambios.
`401`	Verifica la referencia de secreto de Paperclip y el valor de la API key.
`403`	Verifica acceso a la cuenta y créditos.
`429`	Espera antes de reintentar.
`5xx`	Reintenta con backoff acotado.

Desarrollar localmente

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 ejecuta verificaciones de tipos, pruebas y el build.