--- title: "Billeteras de Invitado" description: "Obtén una clave de TwexAPI prepaga sin una cuenta: un agente de IA crea un checkout de Stripe, una persona lo paga y la clave funciona en todos los endpoints y en el MCP." --- # Billeteras de Invitado Una billetera de invitado es una clave de API prepaga de TwexAPI que no requiere cuenta, registro o correo electrónico. Un agente de IA crea la billetera con una solicitud y devuelve una clave de API y un enlace de checkout de Stripe. Una persona paga ese enlace con una tarjeta, y la clave funciona en todos los endpoints de TwexAPI y en el servidor MCP, exactamente como una clave de cuenta. :::warning Una billetera de invitado siempre necesita una persona para pagar. El agente crea el checkout y entrega el enlace; nunca introduce detalles de la tarjeta. Crea una billetera solo después de que el usuario haya confirmado la cantidad. ::: ## Elegir un método de acceso | Método | Cuenta | Credencial | Cobertura | Pago | |---|---|---|---|---| | [Clave de API de cuenta](/es/authentication) | Sí | `Authorization: Bearer ` | Cada endpoint y MCP | Tablero: tarjeta, PayPal o criptomonedas | | [Inicio de sesión en MCP](/es/mcp/oauth) | Sí | OAuth en el cliente MCP | Herramientas MCP | Créditos de la cuenta | | Billetera de invitado | No | `Authorization: Bearer ` | Cada endpoint y MCP | Tarjeta, a través de Stripe Checkout, prepaga | | [MPP](/es/mpp/machine-payments-protocol) | No | `Authorization: Payment ` | 12 endpoints de lectura paginados | USDC en Tempo, por solicitud | Usa una billetera de invitado cuando un agente necesite una clave de API normal para una persona que no desea una cuenta. Usa MPP cuando el agente tiene su propia billetera y paga por solicitud. Usa una clave de cuenta para cualquier cosa a largo plazo. ## Crear y activar una billetera **1. Confirma la cantidad.** Una billetera se financia con USD 10 a 250, enviada como `amount_minor` en centavos (`1000` a `25000`). Los créditos se agregan a la tasa estándar de 100,000 créditos por USD, por lo que USD 10 compra 1,000,000 créditos. Ver [Precios](/es/guides/pricing) para lo que cuesta una solicitud. **2. Crea el checkout.** Envía un nuevo UUID v4 en el encabezado `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": "éxito", "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": "pendiente", "amount_minor": 1000, "currency": "usd", "credits": 1000000 } } } ``` **3. Almacena la clave.** Guarda `api_key` en un almacén secreto de inmediato. Es la única credencial para la billetera y TwexAPI no puede recuperarla por ti. **4. Da al usuario el enlace de checkout.** Muestra `checkout_url` al usuario y pídele que lo pague. El enlace solo se puede usar una vez y expira después de 60 minutos. Hasta que se confirme el pago, la clave devuelve `401` en las llamadas a la API. **5. Consulta hasta que la clave sea usable.** Espera `poll_after_seconds` entre las llamadas: ```bash curl -sS https://api.twexapi.io/guest-wallets/status \ -H "Authorization: Bearer $GUEST_KEY" ``` ```json { "code": 200, "msg": "éxito", "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 } } ``` Empieza a llamar a la API solo cuando `usable` sea `true`. Una página de checkout terminada por sí sola no significa que los créditos se hayan agregado. `latest_purchase.status` es `pendiente` hasta que se confirme el pago, luego `completed`. Un checkout no pagado se convierte en `expirado` y un pago retrasado rechazado se convierte en `fallido`. `poll_after_seconds` es `null` una vez que no hay nada más por esperar. ## Llamar a la API Una clave de invitado usable funciona en todos los endpoints, con los mismos límites de tasa y facturación que una clave de cuenta: ```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"}' ``` Cuando los créditos se agoten, las solicitudes devuelven `403` con `No available credits!`. Recarga la billetera para continuar. ## Recargar una billetera Las recargas agregan créditos a la misma billetera y clave. Confirma la cantidad con el usuario nuevamente y envía un nuevo 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 respuesta tiene un nuevo `checkout_url`. Dáselo al usuario, luego consulta el mismo punto de estado hasta que `latest_purchase.status` sea `completed`. ## Solicitudes sin clave Una solicitud sin credenciales a cualquier endpoint de TwexAPI devuelve `403` con un encabezado `WWW-Authenticate: Bearer realm="twexapi"`. Los campos habituales `code`, `msg` y `data` son seguidos por un objeto `auth_options` que lista las formas de obtener acceso, incluyendo cómo crear una billetera de invitado: ```json { "code": 403, "msg": "No autenticado", "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` dice a un agente lo que es posible. No es permiso para gastar dinero: el agente aún necesita que el usuario acepte una cantidad antes de crear una billetera. ## Usar una clave de invitado con MCP Una vez que la billetera sea usable, conecta un cliente MCP a `https://api.twexapi.io/mcp` con la clave de invitado en el encabezado `Authorization: Bearer`, como se describe en la [visión general de MCP](/es/mcp/overview). Crear una billetera, recargarla y verificar su estado son solo REST; no hay herramientas MCP para ellos. ## Errores | Estado | Significado | ¿Qué hacer? | |---|---|---| | `400` | Falta o es inválido `Idempotency-Key`, `amount_minor` fuera de 1000–25000 o una moneda diferente a `usd` | Arregla la solicitud | | `401` | La clave de portador falta o no es una clave de billetera de invitado | Envía la clave de invitado del paso 2 | | `403` | La billetera está pausada | Contacta con soporte | | `409` | Una solicitud de checkout reintentada está demasiado cerca de su vencimiento para completarse | Reintentar con un nuevo `Idempotency-Key` | | `422` | El `Idempotency-Key` ya se utilizó para una solicitud diferente | Usa un nuevo UUID v4 | | `429` | Se crearon demasiadas billeteras desde una dirección IP en una hora | Espera y reintentar | ## Idempotencia y intentos seguros Cada solicitud de creación y recarga necesita su propio UUID v4 en `Idempotency-Key`. Si una solicitud se interrumpe, envíala de nuevo sin cambios con la misma clave: obtienes el resultado original, marcado con un encabezado `Idempotent-Replayed: true`, y no hay segundo checkout. Reutilizar una clave para una cantidad o solicitud diferentes devuelve `422`. ## Proteger el acceso a la billetera - Mantén los valores de la clave de invitado y `Idempotency-Key` fuera de URLs, registros y transcripciones de chat. Reintentar una solicitud de creación con su `Idempotency-Key` devuelve la clave de API nuevamente. - Las respuestas se envían con `Cache-Control: no-store, private`. No las almacenes. - Confía en `usable` del punto de estado de estado, no en la página de checkout, antes de llamar a la API. - Si un pago es disputado, toda la billetera se pausa (`paused: true`) y la clave deja de funcionar hasta que se resuelva el caso. ## Preguntas frecuentes ### ¿Puedo usar la API de Twitter de TwexAPI sin una cuenta? Sí. Una billetera de invitado te da una clave de API prepaga sin registrarte, y [MPP](/es/mpp/machine-payments-protocol) permite a un agente con una billetera de Tempo pagar por solicitud sin ninguna clave. ### ¿Puede un agente de IA pagar por sí mismo por TwexAPI? No con una billetera de invitado: siempre necesita una persona para pagar el checkout de Stripe. Un agente que tiene su propia billetera de USDC en Tempo puede pagar por solicitud con [MPP](/es/mpp/machine-payments-protocol). ### ¿Una clave de invitado está limitada a algunos endpoints? No. Una vez pagada, una clave de invitado funciona en todos los endpoints y en el servidor MCP, con los mismos precios y límites de tasa que una clave de cuenta. ### ¿Puedo convertir una billetera de invitado en una cuenta más tarde? No hoy. Sigue usando la clave de invitado y recárgala, o crea una cuenta y usa su clave para nuevo trabajo. ## Siguientes pasos - [Autenticación](/es/authentication) para claves de API de cuenta - [Protocolo de pagos por máquina](/es/mpp/machine-payments-protocol) para acceso por pago por solicitud - [Visión general de MCP](/es/mcp/overview) para usar la clave desde un cliente AI - [Precios](/es/guides/pricing) para los costos de crédito por solicitud