Autorización

La API x402 no utiliza cuentas, contraseñas ni claves API. En su lugar, se emplean tres tipos de autenticación: la firma de pago, el token de acceso del pedido y la firma del monedero.

No facilites tus tokens de acceso a terceros y nunca envíes la clave privada de tu monedero a nadie, ni siquiera a nosotros.

Características principales

Firma de pago

El monedero que realiza el pago es el comprador. El primer pago realizado con éxito crea automáticamente una cuenta de monedero; no es necesario registrarse. Las renovaciones y el tráfico residencial de un pedido solo se pueden pagar desde el monedero con el que se pagó el pedido.

Token de acceso

Cada pedido pagado genera un access_token una vez, en el 202 respuesta. Envíala en el Authorization Encabezado en todas las solicitudes relacionadas con este pedido: estado y credenciales, renovación, tráfico, configuración, sustitución de IP y eventos.

Firma de la cartera

Para obtener nuevos tokens para tus pedidos o para retirar tu saldo, firma un mensaje de texto único (EIP-4361) con la misma cartera. La firma no implica ninguna transferencia de fondos.

Tokens de acceso

Authorization: Bearer x402_q8Zt3Lw0mN6pR2vY9cK4hJ7sD1fG5bX8aE3uW0iO2nT

Propiedad	Valor
Formato	`x402_` seguido de 43 caracteres. La palabra `Bearer` no distingue entre mayúsculas y minúsculas
Dónde	Solo en el `Authorization` encabezado. No se aceptan tokens en la cadena de consulta
Alcance	Un encargo: `/orders/{id}` y sus recursos secundarios, incluyendo la renovación y el tráfico de este pedido. Una ficha de recarga solo se abre `GET /topup/{id}`
Publicado	Una vez por operación, en el `202` respuesta. Si se repite la misma solicitud firmada en un plazo de 24 horas, se devuelve el mismo token. Pasado ese tiempo, solo se emiten nuevos tokens mediante Recuperar acceso
Vida útil	Hasta la fecha de vencimiento del encargo más 90 días; las renovaciones amplían este plazo. En el caso de una operación sin fecha de vencimiento, 90 días después de su estado final.
Revocación	Bloqueo de la cartera, `revoke_existing` en Recuperar acceso, o asistencia previa solicitud

Los nuevos tokens no anulan a los antiguos: todos los tokens válidos de un pedido siguen siendo válidos.

Errores

Respuesta	Cuando
`401 unauthorized`	El `Authorization` Falta el encabezado o no es `Bearer x402_…`
`404 order_not_found`	Cualquier otro problema: la orden no existe, el token pertenece a otra orden, el token ha sido revocado o ha caducado. La API no distingue entre estos casos.

Ejemplo

401: Acceso no autorizado

{
    "error": "unauthorized",
    "message": "Authorization is required",
    "retryable": false,
    "retry_action": "abandon",
    "detail": "Authorization: Bearer <access_token> from the order response is required"
}

Ficha perdida

Si pierdes el token, recupera el acceso con tu monedero: Recuperar acceso. La respuesta muestra todas las órdenes de la cartera con los nuevos tokens.