Portefeuilles Invités

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.

Choisissez une méthode d’accès

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 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 :

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"}'

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

curl -sS https://api.twexapi.io/guest-wallets/status \
  -H "Authorization: Bearer $GUEST_KEY"

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

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 :

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é :

{
  "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. 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

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

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 pour les clés API de compte
• Protocole de paiements machine pour un accès par paiement par requête
• Aperçu MCP pour utiliser la clé à partir d’un client IA
• Tarification pour les coûts des Credits par requête