Autorização

A API x402 não possui contas, senhas ou chaves de API. Em vez disso, são utilizados três tipos de comprovação: a assinatura de pagamento, o token de acesso do pedido e a assinatura da carteira.

Não forneça seus tokens de acesso a terceiros e nunca envie a chave privada da sua carteira para ninguém, inclusive para nós.

Principais recursos

Assinatura de pagamento

A carteira que efetua o pagamento é do comprador. O primeiro pagamento bem-sucedido cria automaticamente uma conta na carteira; não é necessário se cadastrar. Renovações e tráfego residencial de um pedido só podem ser pagos a partir da carteira que efetuou o pagamento do pedido.

Token de acesso

Cada pedido pago gera um access_token uma vez, no 202 Resposta. Envie-a no Authorization cabeçalho em todas as solicitações relacionadas a este pedido: status e credenciais, renovação, tráfego, configurações, substituição de IP e eventos.

Assinatura da carteira

Para obter novos tokens para seus pedidos ou sacar seu saldo, assine uma mensagem de texto única (EIP-4361) com a mesma carteira. A assinatura não movimenta fundos.

Tokens de acesso

Authorization: Bearer x402_q8Zt3Lw0mN6pR2vY9cK4hJ7sD1fG5bX8aE3uW0iO2nT

Propriedade	Valor
Formatação	`x402_` seguido por 43 caracteres. A palavra `Bearer` não diferencia maiúsculas de minúsculas
Onde	Apenas no `Authorization` cabeçalho. Tokens na string de consulta não são aceitos
Escopo	Um pedido: `/orders/{id}` e seus sub-recursos, incluindo renovação e tráfego dessa ordem. Um token de recarga abre apenas `GET /topup/{id}`
Emitido	Uma vez por operação, no `202` resposta. Repetir a mesma solicitação assinada em até 24 horas retorna o mesmo token. Depois disso, novos tokens são emitidos apenas por Recuperar acesso
Vida útil	Até a data de validade do pedido mais 90 dias; as renovações prorrogam esse prazo. Para uma operação sem data de validade, 90 dias após seu status final
Revogação	Bloqueio da carteira, `revoke_existing` em Recuperar acesso, ou suporte mediante solicitação

Novos tokens não revogam os antigos: todos os tokens válidos de um pedido continuam funcionando.

Erros

Resposta	Quando
`401 unauthorized`	O `Authorization` o cabeçalho está faltando ou não está `Bearer x402_…`
`404 order_not_found`	Qualquer outro problema: a ordem não existe, o token pertence a outra ordem, o token foi revogado ou expirou. A API não distingue esses casos

Exemplo

401: Acesso não 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

Se o token for perdido, recupere o acesso com sua carteira: Recuperar acesso. A resposta lista todos os pedidos da carteira com novos tokens.