Buying — wallet & orders

Your wallet

GET /v1/wallet returns your spendable balance in cents. Every order debits it.

GET /v1/wallet

{ "balanceCents": 686, "currency": "USD" }

Place an order

POST /v1/orders buys a product, paid from your wallet. Send a product_id, a quantity, and — for targeted per-IP products — an optional fulfillment_meta object (e.g. { "country": "US" }).

bash

curl -X POST https://hproxy.com/v1/orders \
  -H "X-API-Key: hpx_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-2026-06-30-001" \
  -d '{ "product_id": "residential-standard", "quantity": 5 }'

Idempotency

Always send an **Idempotency-Key* header. If a request times out and you retry with the same key, you get the same* order back — never a second charge.

If an order can't go through

Two ways an order is refused before any charge:

402 insufficient_balanceYour wallet balance is below the order total. Top up and retry.

402 key_spend_cap_reachedThis key's daily spend cap would be exceeded. Raise the cap, or wait for the 24h window to roll off.

Track the order

POST /v1/orders returns immediately with status: "processing" and fulfils in the background — residential completes in seconds; per-IP can take a few minutes. Poll GET /v1/orders/{id}:

GET /v1/orders/{id}

{
  "orderId": "cmr0abc...",
  "status": "completed",
  "productId": "residential-standard",
  "quantity": 5,
  "amountCents": 750,
  "currency": "USD",
  "createdAt": "2026-06-30T12:00:00.000Z",
  "fulfilledAt": "2026-06-30T12:00:04.000Z"
}

Order statuses

status	Meaning
`processing`	Paid, being fulfilled — keep polling.
`completed`	Done — your plan is ready. List it with `GET /v1/plans`.
`review`	Held for a quick manual check (rare). Resolves to completed or refunded.
`refunded`	Refunded back to your wallet.
`cancelled`	Did not complete; nothing was charged (or it was already refunded).

You only ever see your own orders. Asking for another account's order id returns 404.

Was this helpful?

Pricing

Using your proxies