Authorization

The x402 API has no accounts, passwords or API keys. Three kinds of proof are used instead: the payment signature, the access token of the order and the wallet signature.

Do not give your access tokens to third parties and never send the private key of your wallet to anyone, including us.

Key features

Payment signature

The wallet that signs the payment is the buyer. The first successful payment creates a wallet account automatically, there is nothing to register. Renewals and residential traffic of an order can be paid only from the wallet that paid the order.

Access token

Every paid order returns an access_token once, in the 202 response. Send it in the Authorization header with every request about this order: status and credentials, renewal, traffic, settings, IP replacement and events.

Wallet signature

To get new tokens for your orders or to withdraw your balance, sign a one-time text message (EIP-4361) with the same wallet. Signing does not move funds.

Access tokens

Authorization: Bearer x402_q8Zt3Lw0mN6pR2vY9cK4hJ7sD1fG5bX8aE3uW0iO2nT

Property	Value
Format	`x402_` followed by 43 characters. The word `Bearer` is case-insensitive
Where	Only in the `Authorization` header. Tokens in the query string are not accepted
Scope	One order: `/orders/{id}` and its sub-resources, including renewal and traffic of this order. A top-up token opens only `GET /topup/{id}`
Issued	Once per operation, in the `202` response. Repeating the same signed request within 24 hours returns the same token. After that, new tokens are issued only by Recover access
Lifetime	Until the expiry date of the order plus 90 days; renewals extend it. For an operation without an expiry date, 90 days after its final status
Revocation	Blocking of the wallet, `revoke_existing` in Recover access, or support on request

New tokens do not revoke old ones: every valid token of an order keeps working.

Errors

Response	When
`401 unauthorized`	The `Authorization` header is missing or is not `Bearer x402_…`
`404 order_not_found`	Any other problem: the order does not exist, the token belongs to another order, the token is revoked or expired. The API does not tell these cases apart

Example

401: Unauthorized

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

Lost token

If the token is lost, recover access with your wallet: Recover access. The response lists all orders of the wallet with new tokens.