Recover access

Lost the access token of an order? Prove that you own the paying wallet by signing a one-time message, and get all orders of the wallet with new access tokens, the payments still in progress and the balance.

Old tokens keep working unless you revoke them.

The flow

Get a challenge
POST /wallet/challenge
Returns a text message (EIP-4361) for your wallet.
Sign the message
personal_sign (EIP-191) of message exactly as received. Signing does not move funds.
Recover
POST /wallet/recover
Returns the orders of the wallet with new access tokens.

Get a challenge

POSThttps://proxy-seller.com/api/x402/v1/wallet/challenge

Request body

Name	Type	Description
address	String	Required. Wallet address, `0x` + 40 hex. A mixed-case address must have a valid EIP-55 checksum
purpose	String	`recover` (default) or `withdraw` (Withdraw balance)

A challenge is issued to any address: the response does not tell whether the address has orders.

Example

POST https://proxy-seller.com/api/x402/v1/wallet/challenge
{
    "address": "0x1111111111111111111111111111111111111111",
    "purpose": "recover"
}

Response

200: OK

{
    "challenge_id": "chl_01JZ9E5F7G9H1J3K5M7N9P1Q3R",
    "address": "0x1111111111111111111111111111111111111111",
    "purpose": "recover",
    "message": "proxy-seller.com wants you to sign in with your Ethereum account:\n0x1111111111111111111111111111111111111111\n\nRecover access to orders paid from this wallet at Proxy-Seller. Signing does not move funds.\n\nURI: https://proxy-seller.com/api/x402/v1/wallet/recover\nVersion: 1\nChain ID: 8453\nNonce: sDYRsY6sbhBxxPSC\nIssued At: 2026-11-02T12:00:00Z\nExpiration Time: 2026-11-02T12:05:00Z\nRequest ID: chl_01JZ9E5F7G9H1J3K5M7N9P1Q3R",
    "expires_at": "2026-11-02T12:05:00Z",
    "signature": {
        "type": "eip191_personal_sign",
        "contract_wallets": "eip1271"
    }
}

A challenge lives 5 minutes and can be used once. Smart-contract wallets are supported through EIP-1271 when contract_wallets is eip1271.

Recover

POSThttps://proxy-seller.com/api/x402/v1/wallet/recover

Request body

Name	Type	Description
challenge_id	String	Required. Id of a challenge with `purpose: recover`
signature	String	Required. Signature of `message`, `0x` hex: 65 bytes for a regular wallet, longer for a smart-contract wallet
limit	Integer	Orders per page, 1–200, 50 by default
offset	Integer	Page offset, from 0
revoke_existing	Boolean	Revoke every token of this wallet issued before this challenge was created

Every page needs a new challenge. Send revoke_existing: true only with the first page: on a later page it would revoke the tokens you have just received on the earlier pages.

Example

POST https://proxy-seller.com/api/x402/v1/wallet/recover
{
    "challenge_id": "chl_01JZ9E5F7G9H1J3K5M7N9P1Q3R",
    "signature": "0x9a7c…1c",
    "limit": 50,
    "offset": 0
}

Response

200: OK

{
    "wallet": "0x1111111111111111111111111111111111111111",
    "network": "eip155:8453",
    "account": {
        "type": "wallet",
        "exists": true,
        "status": "active",
        "balance_usd": "6.40",
        "email_attached": false,
        "topup_url": "https://proxy-seller.com/api/x402/v1/topup",
        "withdraw_url": "https://proxy-seller.com/api/x402/v1/wallet/withdraw"
    },
    "orders": [
        {
            "order_id": "ord_01JZ8Q7K5N2R4T6V8X0Z2B4D6F",
            "status": "active",
            "payment_state": "settled",
            "summary": "2x IPv4 US, 30 days",
            "amount_usd": "3.60",
            "created_at": "2026-11-02T10:01:12Z",
            "expires_at": "2026-12-02T23:59:59Z",
            "url": "https://proxy-seller.com/api/x402/v1/orders/ord_01JZ8Q7K5N2R4T6V8X0Z2B4D6F",
            "access_token": "x402_Nf5gT2hY8jU4kI1oL7pA3sD9fG6hJ0kL2zX5cV8bN4m",
            "token_type": "Bearer"
        }
    ],
    "pending_payments": [],
    "topups": [
        {
            "id": "tup_01JZ9D4E6F8G0H2J4K6M8N0P2Q",
            "status": "credited",
            "payment_state": "settled",
            "amount_usd": "10.00",
            "created_at": "2026-11-02T11:20:31Z",
            "url": "https://proxy-seller.com/api/x402/v1/topup/tup_01JZ9D4E6F8G0H2J4K6M8N0P2Q",
            "access_token": "x402_Rt6yU1iO7pA2sD8fG3hJ9kL4zX0cV5bN6mQ1wE7rT2y",
            "token_type": "Bearer"
        }
    ],
    "withdrawals": [
        {
            "id": "wdr_01JZ9E8H0J2K4M6N8P0Q2R4S6T",
            "status": "done",
            "amount_usd": "6.40",
            "address": "0x1111111111111111111111111111111111111111",
            "network": "eip155:8453",
            "created_at": "2026-12-03T09:14:22Z",
            "tx_hash": "0x5c3e8a1f0b7d4e2c9a6f1b8d3e0c7a4f2b9e6d1c8a5f3e0b7d4c1a9f6e3b8d2c",
            "sent_at": "2026-12-03T15:40:05Z",
            "confirmed_at": "2026-12-03T15:43:10Z"
        }
    ],
    "pagination": {
        "limit": 50,
        "offset": 0,
        "total": 1
    }
}

Name	Description
account	`exists`, `status` (`active` or `blocked`), `balance_usd`, `topup_url`, `withdraw_url`
orders	Orders of the wallet, newest first, with new tokens. A token is not issued when the access period of the order is over (90 days after its expiry)
pending_payments	Payments whose outcome is not known yet or that are under review: `{nonce, network, status, operation_id, kind, order_id, payment_state, amount_atomic, status_changed_at}`. Do not pay again for them
topups	Up to 20 latest top-ups with new tokens
withdrawals	Up to 20 latest withdrawal requests of the wallet, newest first: `{id, status, amount_usd, address, network, created_at, tx_hash, sent_at, confirmed_at}`. `status`: `requested`, `approved`, `sent`, `done` or `rejected` (Withdraw balance)
pagination	`{limit, offset, total}`
notice	Only for a blocked wallet: orders are listed without tokens

401: Unauthorized — the signature is not from the address of the challenge.

404: Not found

{
    "error": "not_found",
    "message": "Challenge not found",
    "retryable": false,
    "retry_action": "abandon",
    "detail": "challenge is unknown, expired or already used"
}

The challenge is unknown, expired, already used or issued for withdraw. Get a new one.

The flow

Get a challenge

Sign the message

Recover

Get a challenge

Request body

Example

Response

Recover

Request body

Example

Response

On this page