---
title: "Paperclip"
description: "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](https://paperclip.ai). 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](/api-reference/overview), el [CLI](/sdks/cli) o el [MCP Server](/mcp/overview) para esas tareas.

## Requisitos previos

- Node.js 18 o más reciente
- Paperclip CLI (`paperclipai`)
- Una API key de TwexAPI desde el [dashboard](https://twexapi.io/dashboard)
- Una referencia de secreto de Paperclip para la API key

## Instalación

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

Fija la versión actual cuando necesites instalaciones reproducibles:

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

npm: [@twexapi-dev/paperclip-plugin-x-api-scraper](https://www.npmjs.com/package/@twexapi-dev/paperclip-plugin-x-api-scraper)

Fuente: [twexapi-dev/paperclip-plugin-x-api-scraper](https://github.com/twexapi-dev/paperclip-plugin-x-api-scraper)

## Configurar

Crea una API key en el [dashboard de TwexAPI](https://twexapi.io/dashboard). 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:

```json
{
  "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:

```text
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

```text
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

```text
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](/mcp/agent-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

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

## Guías relacionadas

* [MCP Server](/mcp/overview)
* [CLI](/sdks/cli)
* [TypeScript SDK](/sdks/typescript)
* [Esquema OpenAPI](https://docs.twexapi.io/openapi.json)
* [Repositorio fuente](https://github.com/twexapi-dev/paperclip-plugin-x-api-scraper)