--- title: "Portefeuilles Invités" description: "Obtenez une clé prépayée TwexAPI sans compte : un agent IA crée un paiement Stripe, une personne le paye, et la clé fonctionne sur tous les points d'entrée et sur le MCP." --- # Portefeuilles Invités Un portefeuille invité est une clé API prépayée TwexAPI qui n'exige pas de compte, d'inscription ou d'email. Un agent IA crée le portefeuille avec une seule requête et renvoie une clé API et un lien de paiement Stripe. Une personne paie ce lien par carte, et la clé fonctionne ensuite sur tous les points d'entrée TwexAPI et sur le serveur MCP, tout comme une clé de compte. :::warning Un portefeuille invité nécessite toujours une personne pour payer. L'agent crée le paiement et remet le lien ; il ne sais pas les détails de la carte. Créez un portefeuille uniquement après que l'utilisateur ait confirmé le montant. ::: ## Choisissez une méthode d'accès | Méthode | Compte | Identifiant | Couverture | Paiement | |---|---|---|---|---| | [Clé API du compte](/fr/authentication) | Oui | `Authorization: Bearer ` | Tous les points d'entrée et MCP | Tableau de bord : carte, PayPal ou crypto | | [Connexion MCP](/fr/mcp/oauth) | Oui | OAuth dans le client MCP | Outils MCP | Crédits du compte | | Portefeuille invité | Non | `Authorization: Bearer ` | Tous les points d'entrée et MCP | Carte, via Stripe Checkout, prépayé | | [MPP](/fr/mpp/machine-payments-protocol) | Non | `Authorization: Payment ` | 12 points d'entrée paginés en lecture | USDC sur Tempo, par requête | Utilisez un portefeuille invité lorsque l'agent a besoin d'une clé API normale pour une personne qui ne veut pas de compte. Utilisez MPP lorsque l'agent a son propre portefeuille et paie par requête. Utilisez une clé de compte pour tout ce qui est de longue durée. ## Créer et activer un portefeuille **1. Confirmez le montant.** Un portefeuille est financé avec 10 à 250 USD, envoyé sous forme de `amount_minor` en cents (`1000` à `25000`). Les crédits sont ajoutés au taux standard de 100 000 Credits par USD, donc 10 USD achètent 1 000 000 Credits. Voir [Tarification](/fr/guides/pricing) pour le coût d'une requête. **2. Créez le paiement.** Envoyez un nouveau UUID v4 dans l'en-tête `Idempotency-Key` : ```bash curl -sS https://api.twexapi.io/guest-wallets \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen | tr A-Z a-z)" \ -d '{"amount_minor": 1000, "currency": "usd"}' ``` ```json { "code": 200, "msg": "success", "data": { "wallet_id": "6f1c2a4e-8b3d-4c5e-9a7f-1d2e3f4a5b6c", "api_key": "twitterx_...", "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_...", "checkout_expires_at": "2026-10-29T14:21:01.000Z", "status_url": "/guest-wallets/status", "poll_after_seconds": 5, "purchase": { "id": "0b8e7d6c-5a4f-4e3d-8c2b-1a0f9e8d7c6b", "kind": "create", "status": "pending", "amount_minor": 1000, "currency": "usd", "credits": 1000000 } } } ``` **3. Stockez la clé.** Enregistrez `api_key` dans un dépôt secret immédiatement. C'est la seule preuve de créance pour le portefeuille, et TwexAPI ne peut pas la récupérer pour vous. **4. Donnez le lien de paiement à la personne.** Montrez `checkout_url` à l'utilisateur et demandez-leur de le payer. Le lien peut être utilisé une seule fois et expire après 60 minutes. Jusqu'à ce que le paiement soit confirmé, la clé renvoie `401` sur les appels API. **5. Attendre jusqu'à ce que la clé soit utilisable.** Attendre `poll_after_seconds` entre les appels : ```bash curl -sS https://api.twexapi.io/guest-wallets/status \ -H "Authorization: Bearer $GUEST_KEY" ``` ```json { "code": 200, "msg": "success", "data": { "wallet_id": "6f1c2a4e-8b3d-4c5e-9a7f-1d2e3f4a5b6c", "key_hint": "twitterx_1a2…9f0e", "usable": true, "paused": false, "available_credits": 1000000, "latest_purchase": { "kind": "create", "status": "completed", "credits": 1000000 }, "poll_after_seconds": null } } ``` Commencez à appeler l'API uniquement lorsque `usable` est `true`. Une page de paiement terminée ne signifie pas que les crédits ont été ajoutés. `latest_purchase.status` est `pending` jusqu'à ce que le paiement soit confirmé, puis `completed`. Un paiement non payé devient `expired`, et un paiement retardé refusé devient `failed`. `poll_after_seconds` est `null` une fois qu'il n'y a plus rien à attendre. ## Appeler l'API Une clé invité utilisable fonctionne sur tous les points d'entrée, avec les mêmes limites de taux et facturation qu'une clé de compte : ```bash curl -sS https://api.twexapi.io/twitter/advanced_search/page \ -H "Authorization: Bearer $GUEST_KEY" \ -H "Content-Type: application/json" \ -d '{"searchTerms": ["openai"], "sortBy": "Latest"}' ``` Quand les crédits s'épuisent, les requêtes renvoient `403` avec `No available credits!`. Rechargez le portefeuille pour continuer. ## Recharger un portefeuille Les recharges ajoutent des crédits au même portefeuille et clé. Confirmez à nouveau le montant avec l'utilisateur, puis envoyez un nouveau UUID v4 : ```bash curl -sS https://api.twexapi.io/guest-wallets/topups \ -H "Authorization: Bearer $GUEST_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen | tr A-Z a-z)" \ -d '{"amount_minor": 2000, "currency": "usd"}' ``` La réponse contient un nouveau `checkout_url`. Donnez-le à la personne, puis surveillez le même point de terminaison de statut jusqu'à ce que `latest_purchase.status` soit `completed`. ## Requêtes sans clé Une requête sans identifiants pour n'importe quel point d'entrée TwexAPI renvoie `403` avec un en-tête `WWW-Authenticate: Bearer realm="twexapi"`. Les champs habituels `code`, `msg` et `data` sont suivis d'un objet `auth_options` qui liste les moyens d'obtenir un accès, y compris comment créer un portefeuille invité : ```json { "code": 403, "msg": "Not authenticated", "data": [], "auth_options": { "account": { "scheme": "Bearer", "dashboard": "https://twexapi.io/dashboard" }, "guest_wallet": { "method": "POST", "url": "https://api.twexapi.io/guest-wallets", "idempotency_header": "Idempotency-Key", "body": { "amount_minor": 1000, "currency": "usd" }, "amount_minor_min": 1000, "amount_minor_max": 25000, "status_url": "https://api.twexapi.io/guest-wallets/status" }, "pay_per_request": { "scheme": "Payment", "endpoints": ["POST /twitter/advanced_search/page", "..."] }, "mcp": { "url": "https://api.twexapi.io/mcp", "pay_per_call_url": "https://api.twexapi.io/mcp/pay" }, "docs": "https://twexapi.io/llms.txt" } } ``` `auth_options` indique ce qui est possible. Ce n'est pas une permission de dépenser de l'argent : l'agent a toujours besoin de l'accord de l'utilisateur avant de créer un portefeuille. ## Utiliser une clé invité avec MCP Une fois que le portefeuille est utilisable, connectez un client MCP à `https://api.twexapi.io/mcp` avec la clé invité dans l'en-tête `Authorization: Bearer`, comme décrit dans l'[aperçu MCP](/fr/mcp/overview). La création d'un portefeuille, son recharge et son contrôle de statut sont uniquement REST ; il n'y a pas d'outils MCP pour eux. ## Erreurs | Statut | Signification | Que faire | |---|---|---| | `400` | Absence ou invalidité de `Idempotency-Key`, `amount_minor` en dehors de 1000–25000 ou une devise autre que `usd` | Corrigez la requête | | `401` | La clé Bearer est manquante ou n'est pas une clé de portefeuille invité | Envoyez la clé invité de l'étape 2 | | `403` | Le portefeuille est en pause | Contactez le support | | `409` | Une requête de paiement expirée est trop proche de son expiration pour être terminée | Réessayez avec un nouveau `Idempotency-Key` | | `422` | Le `Idempotency-Key` a déjà été utilisé pour une requête différente | Utilisez un nouveau UUID v4 | | `429` | Trop de portefeuilles créés à partir d'une adresse IP en une heure | Attendez et réessayez | ## Idempotence et redémarrages sécurisés Chaque requête de création et de recharge nécessite son propre UUID v4 dans `Idempotency-Key`. Si une requête expire, envoyez-la à nouveau inchangée avec la même clé : vous obtenez le résultat original, marqué avec un en-tête `Idempotent-Replayed: true`, et sans second paiement. La réutilisation d'une clé pour un montant différent ou une requête différente renvoie `422`. ## Protéger l'accès au portefeuille - Gardez les valeurs de la clé invité et du `Idempotency-Key` hors des URLs, des journaux et des transcriptions de chat. La redémarrage d'une requête de création avec son `Idempotency-Key` renvoie à nouveau la clé API. - Les réponses sont envoyées avec `Cache-Control: no-store, private`. Ne les cachez pas. - Faites confiance à `usable` à partir du point de terminaison de statut, pas à la page de paiement, avant d'appeler l'API. - Si un paiement est contesté, tout le portefeuille est mis en pause (`paused: true`) et la clé cesse de fonctionner jusqu'à ce que le cas soit résolu. ## FAQ ### Puis-je utiliser l'API Twitter TwexAPI sans compte ? Oui. Un portefeuille invité vous donne une clé API prépayée sans inscription, et [MPP](/fr/mpp/machine-payments-protocol) permet à un agent avec un portefeuille Tempo de payer par requête sans aucune clé. ### Un agent IA peut-il payer pour TwexAPI par lui-même ? Non avec un portefeuille invité : une personne paie toujours le paiement Stripe. Un agent qui détient son propre USDC sur Tempo peut payer par requête avec [MPP](/fr/mpp/machine-payments-protocol). ### Une clé invité est-elle limitée à certains points d'entrée ? Non. Une fois payée, une clé invité fonctionne sur tous les points d'entrée et sur le serveur MCP, avec les mêmes tarifs et limites de taux qu'une clé de compte. ### Puis-je convertir un portefeuille invité en compte plus tard ? Pas aujourd'hui. Continuez à utiliser la clé invité et rechargez-la, ou créez un compte et utilisez sa clé pour de nouveaux travaux. ## Prochaines étapes - [Authentification](/fr/authentication) pour les clés API de compte - [Protocole de paiements machine](/fr/mpp/machine-payments-protocol) pour un accès par paiement par requête - [Aperçu MCP](/fr/mcp/overview) pour utiliser la clé à partir d'un client IA - [Tarification](/fr/guides/pricing) pour les coûts des Credits par requête