---
title: "Paperclip"
description: "Installez le plugin Paperclip TwexAPI pour la recherche de tweets, les profils, les timelines et les tweets tendance dans les agents Paperclip."
---

Le plugin Paperclip TwexAPI ajoute six outils Twitter/X en lecture seule aux agents [Paperclip](https://paperclip.ai). Il encapsule les routes REST TwexAPI documentées avec des schémas d'outils typés, une authentification basée sur des secrets et des résultats JSON prévisibles.

Utilisez ce plugin lorsqu'un agent Paperclip a besoin de recherche de tweets, lookup de profil, recherche utilisateur, lectures de timeline ou tweets tendance globaux sans écrire des appels HTTP bruts.

## Outils

| Tâche agent | Outil Paperclip | Route TwexAPI |
| --- | --- | --- |
| Rechercher des tweets | `twexapi.search_tweets` | `POST /twitter/advanced_search/page` |
| Lire un tweet | `twexapi.lookup_tweet` | `POST /v2/tweet/detail` |
| Rechercher des utilisateurs | `twexapi.search_users` | `GET /twitter/search-user/{keyword}/{target_count}` |
| Lire un profil | `twexapi.get_user` | `GET /twitter/{screen_name}/about` |
| Lire les tweets de profil | `twexapi.get_user_tweets` | `POST /twitter/{screen_name}/timeline/page` |
| Lire les tweets tendance | `twexapi.get_trends` | `GET /twitter/global-trending/tweets` |

Ce plugin n'exporte pas les abonnés ni publie des posts. Utilisez l'[API REST](/api-reference/overview), le [CLI](/sdks/cli) ou le [Serveur MCP](/mcp/overview) pour ces tâches.

## Prérequis

- Node.js 18 ou plus récent
- Paperclip CLI (`paperclipai`)
- Une clé API TwexAPI depuis le [tableau de bord](https://twexapi.io/dashboard)
- Une référence de secret Paperclip pour la clé API

## Installation

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

Verrouillez la release actuelle lorsque vous avez besoin d'installations reproductibles :

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

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

## Configuration

Créez une clé API dans le [tableau de bord TwexAPI](https://twexapi.io/dashboard). Stockez-la dans un secret Paperclip et référencez-la depuis la config du plugin.

| Paramètre | Objectif |
| --- | --- |
| `apiBaseUrl` | Endpoint REST TwexAPI. Par défaut `https://api.twexapi.io`. |
| `apiKeySecretRef` | Référence de secret Paperclip pour la clé API TwexAPI. |
| `defaultTimelineCount` | Nombre de pages de timeline par défaut de 1 à 100. |
| `defaultUserSearchCount` | Nombre de recherche utilisateur par défaut de 1 à 100. |
| `defaultTrendCount` | Nombre de tendances par défaut de 1 à 100. |

Paperclip résout la clé API au moment de l'appel et envoie `Authorization: Bearer`.

Exemple de forme de config du plugin :

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

Ne jamais committer des clés API dans des fichiers de config de plugin versionnés.

## Exemples de tâches agent

### Rechercher des tweets

Demandez à l'agent de rechercher des posts récents sur un sujet. Le plugin appelle `POST /twitter/advanced_search/page` via `twexapi.search_tweets`.

Prompt suggéré :

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

### Lire un profil et une timeline

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

### Lire les tweets tendance globaux

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

## Checklist de handoff

Lorsque les agents Paperclip transmettent des résultats à des systèmes en aval, préservez des identifiants stables.

| Type de données | Stocker |
| --- | --- |
| Tweets | `tweet_id`, `text`, `author_username`, `created_at`, requête de recherche |
| Profils | `user_id`, `username`, `name`, compteurs d'abonnés |
| Tendances | pays, sujet, tag de contenu, lignes de tweet |
| Pagination | `next_cursor`, `has_more`, paramètres de requête originaux |

Consultez [Agent MCP Handoff](/mcp/agent-handoff) lorsque vous mixez les outils Paperclip avec des agents basés sur MCP dans le même workflow.

## Gestion des erreurs

| Statut | Action |
| ------ | ------ |
| `400` | Corrigez l'entrée de l'outil. Ne pas réessayer sans modification. |
| `401` | Vérifiez la référence de secret Paperclip et la valeur de la clé API. |
| `403` | Vérifiez l'accès au compte et les crédits. |
| `429` | Ralentissez avant de réessayer. |
| `5xx` | Réessayez avec backoff borné. |

## Développer localement

```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` exécute les vérifications de types, les tests et le build.

## Guides associés

* [Serveur MCP](/mcp/overview)
* [CLI](/sdks/cli)
* [SDK TypeScript](/sdks/typescript)
* [Schéma OpenAPI](https://docs.twexapi.io/openapi.json)
* [Dépôt source](https://github.com/twexapi-dev/paperclip-plugin-x-api-scraper)