Payments
Updated:
Every paid endpoint uses the same two-request cycle of the x402 protocol: the first request returns the price, the second one pays it.
The flow
Request a quote
POST /orders(or/renew,/traffic,/topup) without payment headersReturns
402 Payment Required: the quote in the body and the payment requirements in thePAYMENT-REQUIREDheader. Nothing is reserved or charged.Sign the authorization
EIP-3009 transferWithAuthorizationSign a USDC transfer of exactly
amounttopayTowith your wallet. A signature alone does not move funds.Repeat the request with the signature
Same method, path and body plus
PAYMENT-SIGNATUREReturns
202 Acceptedwith the operation id, its status and, for new orders and top-ups, an access token. ThePAYMENT-RESPONSEheader carries the transaction.Poll the result
GET /orders/{id}orGET /topup/{id}The payment is confirmed on the network first, then the operation is fulfilled. Poll every
next_poll_after_secondsuntilstatus_is_terminalistrue.
Before you start
Wallet with USDC on Base — the payer. No ETH for gas is needed.
x402 client — any client with x402 version 2, the
exactscheme and EIP-3009, or your own code (Payment headers).Current terms — the versions from
catalog.termsgo intoaccept_termsof a new order.
Common to all paid endpoints
Base URL
https://proxy-seller.com/api/x402/v1Payment protocol
x402 version 2, scheme exact, transfer method EIP-3009, flow upfront: you pay before the order is fulfilled. The version 1 header X-PAYMENT is rejected.
Quote
A quote lives 15 minutes (quote_expires_at). The paid request must repeat the body of the unpaid one; only idempotency_key, callback_url and auto_renew may differ.
Error model
Real HTTP status codes and a JSON body with retry_action that tells what to do next (Errors).
Paid endpoints
Endpoint | What you pay for | Who can pay |
|---|---|---|
| A new order | Any wallet; it becomes the owner of the order |
| Renewal of an order line | Only the wallet that paid the order |
| Residential traffic | Only the wallet that paid the order |
| Balance top-up for auto-renewal | Any wallet; the balance of this wallet is credited |
How long it takes
After the 202 response the payment is confirmed on the Base network, then the order is fulfilled. Proxies are usually ready within a few minutes. Mobile proxies are issued manually by our staff: allow up to 3 hours.
A paid operation is never lost. If a step fails, the operation waits for our staff, and the money is not taken twice.
After you've paid
FAQ
No. The signed authorization is submitted to the network for you.
Request a new quote. If you already sent a signed request with an expired quote, the response tells you what to do: 402 quote_expired comes with a new quote right in the response; 409 payment_not_settleable means your previous authorization can still be executed, so wait until authorization_expires_at before signing a new one.
No. One authorization can be executed on the network only once, and repeating the same PAYMENT-SIGNATURE returns the result of the first attempt. Do not sign a new authorization while the previous one can still be executed: error responses say until when (authorization_expires_at).
Repeat the same request with the same PAYMENT-SIGNATURE. It is safe: you get the result of the first attempt.
Not through the API. Contact [email protected] with the order id.
If one is available, its address is published in the catalog as protocol.sandbox_url.