Billeteras de Invitado

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.

Elegir un método de acceso

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 para lo que cuesta una solicitud.

2. Crea el checkout. Envía un nuevo UUID v4 en el encabezado 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": "é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:

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

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

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:

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:

{
  "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. Crear una billetera, recargarla y verificar su estado son solo REST; no hay herramientas MCP para ellos.

Errores

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

¿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 para claves de API de cuenta
• Protocolo de pagos por máquina para acceso por pago por solicitud
• Visión general de MCP para usar la clave desde un cliente AI
• Precios para los costos de crédito por solicitud