# HProxy Proxy API > Buy and manage residential, datacenter, ISP and mobile proxies over REST (base https://hproxy.com/api/v1). Source: https://hproxy.com/docs ## Proxy API *Buy and deliver residential, ISP, datacenter and mobile proxies programmatically: quotes, wallet orders, line generation, proxy delivery, webhooks and renewals.* URL: https://hproxy.com/docs/proxy-api A small, predictable REST API for running a proxy business from your own code. You prepay from your wallet balance, every order is idempotent so a retry never double-charges, and by default nothing ever silently falls back to charging a card you didn't pick. The whole loop is programmatic: buy, **deliver** (generated residential lines or dedicated IPs with credentials), get **pushed** on fulfillment, renew. 1. **List products**: `GET /products`, the buyable catalog with pricing model, quantity bounds and each product's targeting contract. 2. **Get a quote**: `GET /products/{id}/price?quantity=N`, the exact amount the order will charge. Add `country` and `period_days` for dedicated IPs. 3. **Place the order**: `POST /orders`, debits your wallet (or returns a hosted payUrl for card/crypto). 4. **Deliver**: A gateway product (`delivery` is `lines`: every product priced per GB): `POST /plans/{id}/generate` for targeted `host:port:user:pass` lines. Dedicated addresses (`delivery` is `addresses`): `GET /proxies?order_id=…` for the IPs with credentials. 5. **Get pushed**: Register a [webhook](https://hproxy.com/docs/proxy-api/webhooks) and receive `order.fulfilled` instead of polling. - [Products & pricing](https://hproxy.com/docs/proxy-api/products): The catalog and server-side quotes. - [Orders](https://hproxy.com/docs/proxy-api/orders): Create, list, poll, and renew. - [Plans & generation](https://hproxy.com/docs/proxy-api/plans): What you own, and generating lines. - [Your proxies](https://hproxy.com/docs/proxy-api/proxies): Dedicated IPs with credentials, by order. - [Webhooks](https://hproxy.com/docs/proxy-api/webhooks): Signed pushes on fulfillment. - [Reselling guide](https://hproxy.com/docs/proxy-api/reselling): The end-to-end storefront loop. - [Reseller API](https://hproxy.com/docs/proxy-api/reseller): Act as each of your customers, at your rates. ## Products & pricing *GET /products lists the buyable proxy catalog. GET /products/{id}/price returns the exact server-authoritative amount an order will charge.* URL: https://hproxy.com/docs/proxy-api/products #### GET /api/v1/products **List products.** The buyable catalog: for each product its family, its shape (what buying and delivery look like), its unit, description and features, its lifecycle, its published price, its quantity bounds and a how-to with the exact calls for that shape. **Request** ```bash curl https://hproxy.com/api/v1/products -H "X-API-Key: hpx_your_key_here" ``` **Response** ```json { "products": [ { "id": "residential-lite", "name": "Residential Lite", "family": "residential", "shape": "gateway_gb", "unit": "GB", "delivery": "lines", "renewal": "topup", "state": "active", "description": "Budget-friendly rotating residential proxies at the lowest price per GB", "features": ["country-targeting", "sticky-sessions", "rotation-control"], "available": true, "billing": { "payg": true, "subscription": true, "intervals": ["month","year"] }, "minQuantity": 1, "maxQuantity": 10000, "price": { "kind": "ladder", "unit": "GB", "unitCents": 50, "rungs": [ … ], "quote": "/api/v1/products/residential-lite/price?quantity=N" }, "howTo": { "summary": "Buy gigabytes, then generate as many proxy lines as you like against the plan.", "steps": [ … ] } } ] } ``` #### GET /api/v1/products/{id} **Read one product.** One product by its id, or by any id it used to carry, with its lifecycle. A retired product answers `200` with `state: "retired"` and `successorId`, never a `404`, so a menu built from an old catalog can tell its customer what to buy now. `state` is `active`, `parked` (listed, orders answer `409 product_unavailable` until it is back) or `retired`. `family` names the umbrella (`residential`, `isp`, `mobile`, `ipv4`, `ipv6`) so a storefront groups products without guessing from the name. `shape` says what buying and delivery look like, and it is what to key an integration on, never a list of ids: `gateway_gb` and `gateway_time` are a plan you generate lines from (`delivery` is `lines`), `addresses` and `addresses_mobile` are dedicated IPs that land in [proxies](https://hproxy.com/docs/proxy-api/proxies) (`delivery` is `addresses`). `renewal` is `topup` (order again, the units land on the plan you hold), `repurchase` (a fresh plan for a fresh period) or `extend` (an extension naming the addresses to keep). `howTo` spells the exact calls for that shape, from the price to the first use, with the targeting fields its network takes. A product we add on a known shape works in your code the day it lands. **Request** ```bash curl https://hproxy.com/api/v1/products/residential-lite -H "X-API-Key: hpx_your_key_here" ``` **Response** ```json { "id": "residential-lite", "name": "Residential Lite", "family": "residential", "state": "active", "successorId": null, "available": true, "shape": "gateway_gb", "unit": "GB", "delivery": "lines", "renewal": "topup", "minQuantity": 1, "maxQuantity": 10000, "billing": { "payg": true, "subscription": true, "intervals": ["month","year"] } } ``` #### GET /api/v1/products/{id}/price **Price a product.** A server-authoritative quote: the exact amount `POST /orders` will charge for the same inputs. Pass the quantity as a query parameter. For dedicated per-IP products, add `country` and `period_days` to quote the exact targeting you'll order. Omitted, they default to `USA` / 30 days. **On a reseller key** the answer also says what the order costs **you**: `yourCostCents` is what we debit from your balance when one of your customers places it, `amountCents` is what that customer pays (your retail or markup, else our price), `marginCents` is the difference, `listCents` is our own price, and `note` spells out which is which. To see every period of a country at once, use the [price list](#price-list). | Field | Type | Required | Description | | --- | --- | --- | --- | | `quantity` | `integer (query)` | required | GB for residential, or number of IPs for dedicated products. | | `country` | `string (query)` | optional | Per-IP products: target country, alpha-3 (e.g. USA, DEU). Default USA. | | `period_days` | `integer (query)` | optional | Per-IP products: rental period in days (e.g. 30, 90). Default 30. | **Request** ```bash curl "https://hproxy.com/api/v1/products/residential-lite/price?quantity=5" \ -H "X-API-Key: hpx_your_key_here" ``` **Response** ```json { "productId": "residential-lite", "quantity": 5, "unitPriceCents": 100, "amountCents": 500, "currency": "USD", "billingType": "PAYG" } ``` #### GET /api/v1/products/{id}/price-list **Price list for a country.** For **dedicated per-IP products** (ISP, IPv4, IPv6 and mobile IPs): every rental period of one country priced in one call, so you can print a price table without one quote per period. Each line carries `listCents`, our price for the order, and `available` (false when that period is sold out right now). Mobile answers one line per carrier, service and rotation mode for one period instead (pick it with `period_days`; the carrier ids go straight into `fulfillment_meta`), from the day's price refresh, so quote one mobile order with [price](#price) for the exact figure. **On a reseller key every line also says what it costs you**: `yourCostCents` is what we debit from your balance when one of your customers orders that line, `customerCents` what that customer pays (our price times your markup), and `marginCents` what you keep; `partner` states your discount, your markup and whether the product is on your catalog. The same table is under Pricing in your business dashboard. Products sold per GB or per speed tier answer `400 no_price_list`: they have one price per unit, which [price](#price) quotes. | Field | Type | Required | Description | | --- | --- | --- | --- | | `country` | `string (query)` | required | Alpha-3 from [options](#options), e.g. USA. | | `quantity` | `integer (query)` | optional | How many IPs every line prices. Default: the product's smallest order (1, or 10 for IPv6). A bigger order can cost less per IP. | | `period_days` | `integer (query)` | optional | Mobile only: the period every carrier is priced for. Default 30. | **Request** ```bash curl "https://hproxy.com/api/v1/products/isp/price-list?country=USA" \ -H "X-API-Key: hpx_your_key_here" ``` **Response (reseller key)** ```json { "productId": "isp", "unit": "IP", "country": "USA", "quantity": 1, "currency": "USD", "countries": [{ "alpha3": "USA", "name": "United States" }, { "alpha3": "TUR", "name": "Turkey" }], "partner": { "discountPct": 20, "markup": 1.3, "sellable": true }, "lines": [ { "days": 7, "period": "1 week", "available": true, "listCents": 250, "yourCostCents": 200, "customerCents": 325, "marginCents": 125 }, { "days": 30, "period": "1 month", "available": true, "listCents": 270, "yourCostCents": 216, "customerCents": 351, "marginCents": 135 } ], "note": "listCents is our own price for this order. yourCostCents is what we debit from your balance when one of your customers orders it …" } ``` #### GET /api/v1/products/{id}/options **Available countries & periods.** For **dedicated per-IP products** (IPv4, IPv6, ISP), the live list of countries you can order and the rental periods available, so you can build a picker without hardcoding anything. Countries come back as `{ name, alpha3 }` and are **kept current for you**: the list is refreshed from stock and a country that has run out is removed automatically, so what this returns is always orderable. Feed an `alpha3` straight into the `country` of [price](#price) and [orders](https://hproxy.com/docs/proxy-api/orders), and a `days` into `period_days`. Gateway products (`delivery` is `lines`: residential, mobile, ISP rotating, IPv4 and IPv6 per GB) have no per-country configurator and return `400 no_options`: they target by country at generation time instead (see [generate](https://hproxy.com/docs/proxy-api/plans#generate)). **Request** ```bash curl https://hproxy.com/api/v1/products/ipv4/options \ -H "X-API-Key: hpx_your_key_here" ``` **Response** ```json { "productId": "ipv4", "unit": "IP", "minQuantity": 1, "maxQuantity": 1000, "countries": [ { "name": "United States", "alpha3": "USA" }, { "name": "Germany", "alpha3": "DEU" }, { "name": "United Kingdom", "alpha3": "GBR" } ], "periods": [ { "days": 30, "label": "30 days" }, { "days": 90, "label": "90 days" } ] } ``` ## Orders *POST /orders buys a product from your wallet (or returns a hosted payUrl for card and crypto). GET /orders lists history, GET /orders/{id} polls one.* URL: https://hproxy.com/docs/proxy-api/orders #### POST /api/v1/orders **Create an order.** Buy a product. By default this is a wallet prepay: it debits your balance and returns immediately, or fails with `402` if the balance is short (it never silently charges a card you didn't pick). Set `method` to `"card"` or `"crypto"` to get a hosted `payUrl` back instead. Always send an `Idempotency-Key` so a retry never double-charges; on a reseller key an order without one is refused. The body takes **only the five fields below**. Anything else, including a top-level `country`, is refused with `400 unknown_field` before anything is charged. What goes in it depends on the product's `delivery` on [GET /products](https://hproxy.com/docs/proxy-api/products). **Residential and other gateway products** (`delivery` is `lines`): send `product_id` and `quantity`, nothing else. There is no country in the order. You choose the country for each line when you [generate lines](https://hproxy.com/docs/proxy-api/plans#generate) from the plan, so one plan serves every country. A package size is the `quantity` (1 GB is `1`, 10 GB is `10`), never a separate product id, and it is a whole number from the product's `minQuantity`. **Dedicated IPs** (`delivery` is `addresses`: IPv4, IPv6, ISP and mobile IPs): `quantity` counts IPs, and the targeting goes inside `fulfillment_meta`, for example `{"country": "DEU", "period_days": 30}`. | Field | Type | Required | Description | | --- | --- | --- | --- | | `product_id` | `string` | required | A product id from GET /products, e.g. "residential-lite". | | `quantity` | `integer` | required | A whole number; a fraction is refused. GB for residential and other per-GB products, or number of IPs for dedicated products, between the product's `minQuantity` and `maxQuantity`. For renewals: the number of ids. | | `method` | `string` | optional | "wallet" (default), "card" or "crypto". card/crypto return a payUrl. | | `fulfillment_meta` | `object` | optional | Dedicated IPs: country (alpha-3, e.g. "DEU"), period_days, and operator_id on mobile. For a RENEWAL of dedicated proxies: {"kind": "extension", "ids": ["…"], "period_days": 30} (ids from GET /proxies, ownership-checked server-side). Leave it out for residential and other per-GB products: you choose their country per line at POST /plans/{id}/generate. | | `expected_amount_cents` | `integer` | optional | The total you showed the buyer (the `amountCents` of your quote). If the price moved in between, the order is refused with `409 price_changed` carrying the new `amountCents`, and nothing is charged. Omit it to be charged the price at the moment of the order. | **Request (residential)** ```bash # Residential: product_id + quantity (GB). No country here: # the country is chosen per line at POST /plans/{id}/generate. curl -X POST https://hproxy.com/api/v1/orders \ -H "X-API-Key: hpx_your_key_here" \ -H "Idempotency-Key: order-2026-07-11-001" \ -H "Content-Type: application/json" \ -d '{"product_id":"residential-lite","quantity":1}' ``` **Request (dedicated IPs)** ```bash # Dedicated IPs: the country (alpha-3) and the period go in fulfillment_meta curl -X POST https://hproxy.com/api/v1/orders \ -H "X-API-Key: hpx_your_key_here" \ -H "Idempotency-Key: order-2026-07-11-002" \ -H "Content-Type: application/json" \ -d '{"product_id":"ipv4","quantity":5,"fulfillment_meta":{"country":"DEU","period_days":30}}' ``` **201 Created** ```json { "orderId": "ord_8f491789-58cd-4e82-81a2-ec7c28088821", "amountCents": 120, "currency": "USD", "status": "processing" } ``` #### GET /api/v1/orders **List orders.** Your order history, newest first, one page at a time. Without parameters you get the 15 most recent. | Field | Type | Required | Description | | --- | --- | --- | --- | | `limit` | `integer (query)` | optional | Page size, 1 to 200. Default 15. A larger value is capped at 200. | | `offset` | `integer (query)` | optional | Rows to skip, newest first. Default 0. Page 3 of 50 is `limit=50&offset=100`. | **Request** ```bash curl "https://hproxy.com/api/v1/orders?limit=50&offset=0" -H "X-API-Key: hpx_your_key_here" ``` **Response** ```json { "orders": [ { "orderId": "ord_8f491789-58cd-4e82-81a2-ec7c28088821", "productId": "residential-lite", "type": "PURCHASE", "status": "PAYMENT_RECEIVED", "quantityGb": 1.0, "amountCents": 120, "currency": "USD", "createdAt": "2026-07-11T09:46:05.191+00:00" } ] } ``` #### GET /api/v1/orders/{id} **Get an order.** Fetch a single order by its id to poll fulfillment status. Once it reads `completed`, a dedicated-IP order's proxies are ready at [GET /proxies?order_id=…](https://hproxy.com/docs/proxy-api/proxies). **Request** ```bash curl https://hproxy.com/api/v1/orders/ord_8f49...8821 \ -H "X-API-Key: hpx_your_key_here" ``` > [!TIP] Skip the polling loop entirely: register a [webhook](https://hproxy.com/docs/proxy-api/webhooks) and get pushed `order.fulfilled` / `order.failed` / `order.refunded` the moment they happen. ## Plans & line generation *GET /plans lists the plans a key owns, each with its status. POST /plans/{id}/generate returns host:port:user:pass lines with country, city, ISP and sticky-session targeting.* URL: https://hproxy.com/docs/proxy-api/plans #### GET /api/v1/plans **List plans.** Your plans: residential GB balances and dedicated allocations. By default the list holds the plans that can be used now; add `?status=all` to include the ones that ran out or were switched off. A plan is never deleted. Every plan carries `status`: `active`, `used_up` (its traffic ran out, so it was switched off at 0 GB) or `inactive` (switched off with GB still on it: refunded, moved or turned off by hand). Only an `active` plan generates lines. An order for a customer whose plan is `used_up` refills that same plan: it turns `active` again with the same login, so nothing changes on your customer's side. The `id` is what you pass to the endpoints below; `label` is your own tag (see PATCH), `null` until you set it. `productId` is the catalog id you ordered (`residential-lite`, `residential-premium`, …) and the field to branch on; `product` is our internal family name, kept for compatibility, and it can change when we move a product to a new pool. `dataGbTotal` and `dataGbRemaining` here are the usage sync's reading, taken about every 30 minutes (a plan bought moments ago shows its full balance until the next pass); `GET /plans/{id}` refreshes them from the network on the call and carries `usageAsOf`. The network enforces every plan's cap itself, in real time. **Request** ```bash curl "https://hproxy.com/api/v1/plans?status=all" -H "X-API-Key: hpx_your_key_here" ``` **Response** ```json { "plans": [ { "id": "cmjfmhhpd004c4i4hqsk3mzrr", "product": "residential-premium", "productId": "residential-premium", "status": "active", "dataGbTotal": 1.0, "dataGbRemaining": 1.0, "expiresAt": null, "createdAt": "2025-12-21T11:07:14.785Z", "label": "customer-1042" }, { "id": "cmk2b7xq9001s8f3lw4tn6v0e", "product": "residential-lite", "productId": "residential-lite", "status": "used_up", "dataGbTotal": 5.0, "dataGbRemaining": 0.0, "expiresAt": null, "createdAt": "2026-03-02T09:14:22.104Z", "label": "customer-2077" } ] } ``` #### GET /api/v1/plans/{id} **Get one plan.** A single plan you own, whatever its `status`: the per-customer read for a reseller dashboard. A plan whose traffic ran out answers `200` with `"status": "used_up"` and `dataGbRemaining` 0, so you can tell your customer their GB is spent; only an id that is not yours is a `404`. `dataGbRemaining` is refreshed from the network's own meter on this call (one network read per plan per minute; between reads you get the last reading), and `usageAsOf` says when that reading was taken. The list endpoint carries the usage sync's reading instead, taken about every 30 minutes, so poll this door when you show a customer what is left. The network enforces the plan's cap itself, in real time: a customer cannot use more than the plan holds, whatever the figure here shows between readings. **Request** ```bash curl https://hproxy.com/api/v1/plans/cmjfmhhpd004c4i4hqsk3mzrr \ -H "X-API-Key: hpx_your_key_here" ``` **Response** ```json { "id": "cmjfmhhpd004c4i4hqsk3mzrr", "product": "residential-premium", "productId": "residential-premium", "status": "active", "dataGbTotal": 10.0, "dataGbRemaining": 3.2, "expiresAt": null, "createdAt": "2026-07-23T01:07:14.785Z", "label": "customer-1042" } ``` #### PATCH /api/v1/plans/{id} **Label a plan.** `PATCH` a plan with your own reference, e.g. which of YOUR customers it belongs to. Pure metadata: it changes nothing about pricing, traffic or generation, and it comes back in `GET /plans`, `GET /plans/{id}` and in [webhook](https://hproxy.com/docs/proxy-api/webhooks) payloads, so every signal is already attributed to your customer. `null` (or an empty body) clears it. | Field | Type | Required | Description | | --- | --- | --- | --- | | `label` | `string | null` | optional | 1 to 64 characters, no control characters. null/omitted clears. | **Request** ```bash curl -X PATCH https://hproxy.com/api/v1/plans/cmjfmhhpd004c4i4hqsk3mzrr \ -H "X-API-Key: hpx_your_key_here" \ -H "Content-Type: application/json" \ -d '{"label": "customer-1042"}' ``` **Response** ```json { "id": "cmjfmhhpd004c4i4hqsk3mzrr", "product": "residential-premium", "productId": "residential-premium", "dataGbTotal": 10.0, "dataGbRemaining": 10.0, "expiresAt": null, "createdAt": "2026-07-23T01:07:14.785Z", "label": "customer-1042" } ``` #### GET /api/v1/plans/{id}/stats **Traffic statistics.** How a **Residential Premium** plan was used, bucket by bucket: bytes, requests and success rate straight from the network's own metering of that plan. Add `/targets` to the path (`GET /plans/{id}/stats/targets`) for the breakdown by target host and country, heaviest first (`rows[]` with `host`, `country`, `bandwidthBytes`, `requests`, `successRate`, `avgLatencyMs`; `limit` 1 to 500). Plans on other products answer 400. | Field | Type | Required | Description | | --- | --- | --- | --- | | `days` | `integer` | optional | Window ending now, 1 to 30. Default 7. | | `granularity` | `string` | optional | "hour" (windows up to 29 days) or "day". Default: hour up to 2 days, else day. | **Request** ```bash curl "https://hproxy.com/api/v1/plans/cmjfmhhpd004c4i4hqsk3mzrr/stats?days=7" \ -H "X-API-Key: hpx_your_key_here" ``` **Response** ```json { "planId": "cmjfmhhpd004c4i4hqsk3mzrr", "days": 7, "granularity": "day", "from": "2026-08-28T00:00:00.000Z", "to": "2026-09-04T00:00:00.000Z", "points": [ { "at": "2026-09-04T00:00:00.000Z", "bandwidthBytes": 7497, "requests": 15, "successfulRequests": 15, "failedRequests": 0, "successRate": 100 } ], "totals": { "bandwidthBytes": 7497, "bandwidthGb": 0.0, "requests": 15, "successfulRequests": 15, "successRate": 100 } } ``` #### GET /api/v1/plans/{id}/whitelist **IP whitelist.** The IP addresses that may use a **Residential Premium** plan WITHOUT the password (IP authentication), up to 150 per plan. `GET` lists them, `POST` adds (`{"ips": ["203.0.113.9", {"ip": "2001:db8::1", "description": "office"}]}`), `DELETE` removes (`{"ips": ["203.0.113.9"]}`); each answers the resulting list. Every entry must be a valid IPv4 or IPv6 address. A whitelisted connection carries no username, so it takes no targeting: it rotates through any country on the rotating ports and holds one IP per sticky port. Use the generated lines (password included) whenever you need a country, state, city or ISP. Whitelist only addresses you alone control: everything that connects from a whitelisted IP spends this plan's traffic, and a shared office, VPN or cloud egress address is shared with everyone behind it. Plans on other products answer 400. | Field | Type | Required | Description | | --- | --- | --- | --- | | `ips` | `array` | required | POST / DELETE body: IP strings, or `{ip, description}` objects (description up to 80 characters). | **Request** ```bash curl -X POST https://hproxy.com/api/v1/plans/cmjfmhhpd004c4i4hqsk3mzrr/whitelist \ -H "X-API-Key: hpx_your_key_here" \ -H "Content-Type: application/json" \ -d '{"ips": [{"ip": "203.0.113.9", "description": "office"}]}' ``` **Response** ```json { "planId": "cmjfmhhpd004c4i4hqsk3mzrr", "max": 150, "ips": [ { "ip": "203.0.113.9", "description": "office" } ] } ``` #### GET /api/v1/plans/{id}/sessions **Sticky sessions.** The sticky sessions a **Residential Premium** plan holds right now, up to 250 per page: the port and its protocol, the session label the line carried, the exit country, the session's full length, the seconds it has run and the seconds it has left. A session whose line was generated here also carries `targeting` (what the line aimed at: country, state or city, `asn`, `os`, exclusions, `strict`, `udp`), `line` (the exact line, with the plan's password) and `generatedAt`; a session opened with a session id of your own carries null in all three. A port holds any number of sessions, one per session id, so `total` can be far larger than the number of ports; read further pages with `page`. A sticky line opens its session on the first request. `POST /plans/{id}/release-sessions` ends sessions and takes exactly one of three bodies: `{"sessions": [{"port": 10000, "sessionId": "a41f9c02"}]}` ends exactly those (up to 1,000 per call), `{"ports": [10000]}` ends every session on those ports (up to 200 ports), `{"all": true}` ends every open session. The next request on a released line draws a fresh IP. The answer carries `releasedSessions` (how many ended), `released` (their ports), `notOpen` (named ports that held none) and `remaining`: a `ports` or `all` release ends at most 5,000 sessions per call, so call again until `remaining` is 0. Plans on other products answer 400. | Field | Type | Required | Description | | --- | --- | --- | --- | | `page` | `integer` | optional | List only: the page to read, from 1. Default 1. | | `pageSize` | `integer` | optional | List only: sessions per page, 1 to 250. Default 250. | | `sessions` | `object[]` | optional | Release only: 1 to 1,000 `{port, sessionId}` pairs, as the list shows them. Exactly those sessions end. | | `ports` | `integer[]` | optional | Release only: 1 to 200 sticky ports. Every open session on them ends. | | `all` | `boolean` | optional | Release only: `true` ends every open session on the plan. | **Request** ```bash curl "https://hproxy.com/api/v1/plans/cmjfmhhpd004c4i4hqsk3mzrr/sessions" \ -H "X-API-Key: hpx_your_key_here" ``` **Response** ```json { "planId": "cmjfmhhpd004c4i4hqsk3mzrr", "total": 3, "page": 1, "pageSize": 250, "sessions": [ { "port": 10000, "protocol": "http", "sessionId": "k3m9x20000", "country": "DE", "lifetimeSeconds": 1800, "elapsedSeconds": 587, "remainingSeconds": 1213, "targeting": { "country": "de", "city": "berlin", "os": "windows" }, "line": "premium.hproxy.com:10000:USERNAME-type-residential-country-de-city-berlin-os-windows-session-k3m9x20000-lifetime-30:PASSWORD", "generatedAt": "2026-09-15T14:02:11Z" }, { "port": 10000, "protocol": "http", "sessionId": "c7d1e8b3", "country": "US", "lifetimeSeconds": 3600, "elapsedSeconds": 120, "remainingSeconds": 3480, "targeting": null, "line": null, "generatedAt": null }, { "port": 12000, "protocol": "socks5", "sessionId": "p7q2d80000", "country": "US", "lifetimeSeconds": 86400, "elapsedSeconds": 489, "remainingSeconds": 85911, "targeting": { "country": "us", "asn": 7922, "udp": true }, "line": "premium.hproxy.com:12000:USERNAME-type-residential-country-us-asn-7922-requireUdp-true-session-p7q2d80000-lifetime-1440:PASSWORD", "generatedAt": "2026-09-15T13:40:57Z" } ] } ``` **Release one session** ```bash curl -X POST https://hproxy.com/api/v1/plans/cmjfmhhpd004c4i4hqsk3mzrr/release-sessions \ -H "X-API-Key: hpx_your_key_here" \ -H "Content-Type: application/json" \ -d '{"sessions": [{"port": 10000, "sessionId": "a41f9c02"}]}' ``` **Release every session** ```bash curl -X POST https://hproxy.com/api/v1/plans/cmjfmhhpd004c4i4hqsk3mzrr/release-sessions \ -H "X-API-Key: hpx_your_key_here" \ -H "Content-Type: application/json" \ -d '{"all": true}' # {"ok": true, "released": [10000, 12000], "releasedSessions": 3, "notOpen": [], "remaining": 0} ``` #### POST /api/v1/plans/{id}/password **Rotate the proxy password.** Replace the password behind a **residential** plan's lines with a fresh one, confirmed by the network before it is stored, and answer the new `username` and `password` once. Every line generated before the call stops working within seconds; generate again afterwards. Use it when a line has leaked. Throttled to three rotations per account every ten minutes, because each call cuts every line that account is running. No body. Residential Plus plans answer 400. **Request** ```bash curl -X POST https://hproxy.com/api/v1/plans/cmjfmhhpd004c4i4hqsk3mzrr/password \ -H "X-API-Key: hpx_your_key_here" ``` **Response** ```json { "ok": true, "username": "hproxy_k2m9x4qp7wz1", "password": "3f1c2a9e-8b7d-4e6f-a1b2-c3d4e5f60718" } ``` #### POST /api/v1/plans/{id}/generate **Generate proxy lines.** Turn a **gateway** plan you own into ready-to-use proxy lines, fully programmatic, using the same hardened generator the dashboard uses. Every product whose `delivery` is `lines` on [products](https://hproxy.com/docs/proxy-api/products) generates (residential, mobile, ISP rotating, IPv4 and IPv6 per GB); the product's `generate` block, and each plan's, says which targeting fields its network takes. Lines come back as `host:port:username:password` with the targeting baked into the username, so any client that accepts a proxy username and password uses them without extra settings. Chrome and other Chromium browsers never send a SOCKS5 username and password, so for them generate with `protocol` set to `http`, the default. Every field is optional; an empty body returns one rotating line with the plan's defaults. Generating lines is free and repeatable: traffic is only consumed when the lines are used. All generated lines draw from the SAME plan balance. Dedicated per-IP products don't generate; fetch them from [GET /proxies](https://hproxy.com/docs/proxy-api/proxies) instead. | Field | Type | Required | Description | | --- | --- | --- | --- | | `protocol` | `string` | optional | "http" (default) or "socks5". | | `count` | `integer` | optional | Lines to return, 1 to 5000, and at most the plan's own `generate.maxCount` (5,000 on Residential Premium, 1,000 on Residential Lite); a count past it answers 400 `invalid_count` naming the ceiling. Default 1. Sticky and rotating batches share this limit: on Residential Premium sticky lines take the sticky ports in turn and every line holds its own session, so the number of ports never limits a batch. Each plan's `generate.sticky` block carries the sticky port range (`port`, `ports`). | | `country` | `string` | optional | Country targeting, e.g. "US" (letters only, 2 to 40 chars). This is where a residential order gets its country: the order carries none, so one plan serves every country and each call can target a different one. | | `state` | `string` | optional | State / region targeting, where the pool supports it. | | `city` | `string` | optional | City targeting, where the pool supports it. | | `isp` | `string` | optional | ISP targeting by name. Residential Plus plans only (400 on other products). | | `asn` | `integer` | optional | ISP targeting by AS number, e.g. 7018 for AT&T or 7922 for Comcast, together with `country`. Residential Premium plans only; the list per country is `GET /v1/products/residential-premium/geo/asns?country=US`. 400 on other products. | | `os` | `string` | optional | "windows", "android", "ios" or "mac": the device the exit IP belongs to. Residential Premium only. | | `strict` | `boolean` | optional | Default true: a target with no IP free fails the request. false: the gateway hands out another IP from the same country instead. Residential Premium only. | | `excludeAsn` | `integer[]` | optional | Up to 20 AS numbers to avoid. Not together with `excludeCountries`. Residential Premium only. | | `excludeCountries` | `string[]` | optional | Up to 20 two-letter country codes to avoid; only without `country`. Residential Premium only. One exclusion kind per call: countries, states, cities or networks, never two. | | `excludeStates` | `string[]` | optional | Up to 20 state / region names to avoid inside `country` (e.g. ["California", "Texas"]); not together with a `state` target. Residential Premium only. | | `excludeCities` | `string[]` | optional | Up to 20 city names to avoid inside `country` (e.g. ["New York", "Houston"]); not together with a `city` target. Residential Premium only. | | `udp` | `boolean` | optional | `true` lets a `socks5` line open UDP relays (SOCKS5 UDP ASSOCIATE). Refused on `http`. Residential Premium only. | | `stickyMinutes` | `integer` | optional | Turns sticky on. Omit for rotating IPs. On Residential Premium the number is the session length in minutes, 3 to 1440 (24 hours), and each sticky line holds its own session with no limit on how many; on Plus it is the session length up to 24 hours. On Residential Lite the pool takes no duration, so any value above 0 simply turns sticky on and the session lasts as long as you keep reusing the line. Each plan's `generate` block reports its own `minStickyMinutes` / `maxStickyMinutes`. | **Request** ```bash curl -X POST https://hproxy.com/api/v1/plans/cmjfmhhpd004c4i4hqsk3mzrr/generate \ -H "X-API-Key: hpx_your_key_here" \ -H "Content-Type: application/json" \ -d '{"count": 3, "country": "US", "stickyMinutes": 30}' ``` **Response** ```json { "lines": [ "203.0.113.10:10000:hp_x92kf-us-sess-a8x2q-t-30:9f2a1c7b", "203.0.113.10:10000:hp_x92kf-us-sess-k3m7d-t-30:9f2a1c7b", "203.0.113.10:10000:hp_x92kf-us-sess-p5r1w-t-30:9f2a1c7b" ], "productId": "residential-premium" } ``` Ownership is strict: the plan must be **yours** and **active**, anything else is a plain `404` (an id never confirms another account's plan exists). Free-text targeting is validated before it touches the network (letters, digits, spaces and simple punctuation only), so a bad value is a clean `400` naming the rule. The exact host, port and username grammar in the response varies by pool; treat lines as opaque and use them verbatim. ### Rotating vs sticky sessions This is the one choice that shapes how a line behaves, and it is just whether you send `stickyMinutes`: *Mode* | Field | Type | Description | | --- | --- | --- | | `Rotating (default)` | `omit stickyMinutes` | Every request through the line can exit from a different residential IP. Best for scraping, wide coverage, and spreading load. Ask for `count: N` and you get N interchangeable rotating lines. | | `Sticky` | `stickyMinutes: N` | The line holds the SAME exit IP instead of rotating per request. Best for anything that needs a stable identity across several requests: a login, a cart, a session. Each line you generate gets its OWN sticky session, so `count: 10` with stickyMinutes gives ten simultaneous stable identities. How long it holds depends on the product: Residential Premium and Plus take the duration you ask for, while Residential Lite holds the address for as long as you keep using the line and takes no duration. The address can still change early on any product if that particular device leaves the network, so write a retry either way. | **Generation is free, instant and repeatable, and it reveals nothing new.** A plan has ONE credential pair; every line is that same pair with the country and session written into the username, so calling generate again just hands back more lines against the same balance. Nothing is 'used up' until traffic actually flows. So a storefront can safely let a customer regenerate lines whenever they want (roll a fresh IP, retarget a country) without spending anything. Data is metered only by bytes through the proxy, drawn from the plan's GB, and you can read what is left any time from [GET /plans/{id}](#plan-get) or be [pushed `plan.low_traffic`](https://hproxy.com/docs/proxy-api/webhooks) at 10%. Generate when you need lines rather than storing them: the pair inside a line can rotate when we move a pool, while the plan id and its balance stay the same. > [!TIP] Building a reseller integration? The [reselling guide](https://hproxy.com/docs/proxy-api/reselling) walks the whole loop, and the [Reseller API](https://hproxy.com/docs/proxy-api/reseller) does the same generation **as each of your customers** so every line is billed and isolated per customer. ## Your dedicated proxies *GET /api/v1/proxies lists the dedicated IPv4, IPv6, ISP and mobile proxies a key owns, credentials included. Filter by family or by the order that delivered them.* URL: https://hproxy.com/docs/proxy-api/proxies #### GET /api/v1/proxies **List your proxies.** Every **dedicated** proxy the account owns (IPv4, IPv6, ISP, Mobile), with connection credentials: the delivery step after a per-IP purchase. Served from a local mirror, so it's instant and keeps working through upstream turbulence: new purchases appear right after the order fulfills, everything else refreshes within ~30 minutes. Filter `order_id` with the id `POST /orders` returned to fetch exactly that order's proxies. Each proxy's `id` is what a [renewal](https://hproxy.com/docs/proxy-api/orders#orders-create) references in `fulfillment_meta.ids`. | Field | Type | Required | Description | | --- | --- | --- | --- | | `family` | `string (query)` | optional | "ipv4", "ipv6", "isp" or "mobile". Omitted = all. | | `order_id` | `string (query)` | optional | Only the proxies delivered by this order (ord_…). | | `include_inactive` | `boolean (query)` | optional | true to include expired/retired proxies. Default: active only. | | `limit` | `integer (query)` | optional | Max rows. Default 1000, max 5000. | **Request** ```bash curl "https://hproxy.com/api/v1/proxies?family=ipv4&order_id=ord_8f49...8821" \ -H "X-API-Key: hpx_your_key_here" ``` **Response** ```json { "count": 2, "proxies": [ { "active": true, "country": "US", "expiresAt": "2026-08-22", "family": "ipv4", "id": "9214321", "ip": "203.0.113.7", "orderId": "ord_8f491789-58cd-4e82-81a2-ec7c28088821", "password": "d41f9c2a", "portHttp": 10090, "portSocks": 11090, "protocols": ["http", "socks5"], "username": "hp_k29dj" }, { "active": true, "country": "US", "expiresAt": "2026-08-22", "family": "ipv4", "id": "9214322", "ip": "203.0.113.8", "orderId": "ord_8f491789-58cd-4e82-81a2-ec7c28088821", "password": "d41f9c2a", "portHttp": 10090, "portSocks": 11090, "protocols": ["http", "socks5"], "username": "hp_k29dj" } ] } ``` Fields the record doesn't state are `null`, never invented. A proxy that expired or was retired flips to `active: false` (hidden unless `include_inactive=true`). History is kept, nothing silently disappears. Gateway plans (residential, mobile, ISP rotating, IPv4 and IPv6 per GB) don't live here: their lines are generated on demand from [Plans & generation](https://hproxy.com/docs/proxy-api/plans#generate). > [!NOTE] A freshly fulfilled order's proxies appear within seconds. If you get an empty list right after `POST /orders`, poll [GET /orders/{id}](https://hproxy.com/docs/proxy-api/orders#orders-get) until it's `completed`, or skip polling entirely with a [webhook](https://hproxy.com/docs/proxy-api/webhooks). ## Webhooks *Register an HTTPS endpoint and get pushed order.fulfilled, order.failed, order.refunded and subscription events, HMAC-SHA256 signed, instead of polling.* URL: https://hproxy.com/docs/proxy-api/webhooks Stop polling. Register an HTTPS endpoint and we **push** you a signed JSON event the moment an order or subscription reaches a terminal state. Deliveries are HMAC-SHA256 signed, retried with backoff for hours, and idempotently enqueued (one event per endpoint per resource), so treat them as at-least-once and de-duplicate on `(event, data.orderId)`. #### POST /api/v1/webhooks **Register an endpoint.** Register an **https** URL for event pushes. The response carries your signing `secret` **once**. Store it now, it is never shown again. `events` defaults to everything; up to 10 active endpoints per account. Private/internal hosts are refused at registration. | Field | Type | Required | Description | | --- | --- | --- | --- | | `url` | `string` | required | HTTPS endpoint to receive signed event POSTs. | | `events` | `string[]` | optional | Subset of: order.fulfilled, order.failed, order.refunded, subscription.canceled, subscription.expired, plan.low_traffic, announcement.published. Omitted = all. | **Request** ```bash curl -X POST https://hproxy.com/api/v1/webhooks \ -H "X-API-Key: hpx_your_key_here" \ -H "Content-Type: application/json" \ -d '{"url": "https://api.your-shop.com/hproxy-webhook", "events": ["order.fulfilled", "order.failed"]}' ``` **201 Created** ```json { "active": true, "createdAt": "2026-07-23T09:15:02.114Z", "events": ["order.fulfilled", "order.failed"], "id": "whs_1f7c9a2b8d3e4f50a1b2c3d4e5f60718", "secret": "whsec_9a1b…store-me-now…7f2e", "url": "https://api.your-shop.com/hproxy-webhook" } ``` #### GET /api/v1/webhooks **List endpoints.** Your registered endpoints, newest first. Secrets are never re-shown. **Request** ```bash curl https://hproxy.com/api/v1/webhooks -H "X-API-Key: hpx_your_key_here" ``` **Response** ```json { "webhooks": [ { "active": true, "createdAt": "2026-07-23T09:15:02.114Z", "events": ["order.fulfilled", "order.failed"], "id": "whs_1f7c9a2b8d3e4f50a1b2c3d4e5f60718", "url": "https://api.your-shop.com/hproxy-webhook" } ] } ``` #### DELETE /api/v1/webhooks/{id} **Delete an endpoint.** Remove an endpoint; its pending deliveries go with it. **Request** ```bash curl -X DELETE https://hproxy.com/api/v1/webhooks/whs_1f7c9a2b8d3e4f50a1b2c3d4e5f60718 \ -H "X-API-Key: hpx_your_key_here" ``` **Response** ```json { "deleted": true } ``` #### POST /api/v1/webhooks/{id}/test **Send a test delivery.** Queues a `ping` event through the **real** pipeline (same signing, same worker) so you can verify your endpoint and signature code end to end. Expect the POST within about a minute. **Request** ```bash curl -X POST https://hproxy.com/api/v1/webhooks/whs_1f7c9a2b8d3e4f50a1b2c3d4e5f60718/test \ -H "X-API-Key: hpx_your_key_here" ``` **202 Accepted** ```json { "queued": true, "event": "ping" } ``` ### What a delivery looks like Every delivery is a `POST` with `Content-Type: application/json` and three headers: `X-HProxy-Event` (the event type), `X-HProxy-Signature` (hex HMAC-SHA256 of the raw body) and `X-HProxy-Timestamp` (a convenience mirror. The tamper-proof time is `created` **inside** the signed body). Order events carry the same public vocabulary as `GET /orders/{id}`, so your handler and your poller read identical statuses. **Delivery body** ```json { "event": "order.fulfilled", "created": "2026-07-23T09:16:41.220Z", "resource": "order", "data": { "orderId": "ord_8f491789-58cd-4e82-81a2-ec7c28088821", "status": "completed", "productId": "ipv4", "quantity": 5, "amountCents": 1050, "currency": "USD", "createdAt": "2026-07-23T09:15:12.003Z", "fulfilledAt": "2026-07-23T09:16:38.551Z" } } ``` ### Plan events: know when a customer runs low `plan.low_traffic` fires when an active GB plan drops to **10% or less** of its total: the signal a reseller uses to prompt their customer to top up. It carries the plan snapshot including your [label](https://hproxy.com/docs/proxy-api/plans#plan-label), so the alert is already attributed to your customer. It fires **once per plan per endpoint** (a top-up does not re-arm it), and a newly registered endpoint receives one event per plan that is already low at that moment. **plan.low_traffic delivery** ```json { "event": "plan.low_traffic", "created": "2026-07-23T02:01:00.412Z", "resource": "plan", "data": { "planId": "cmjfmhhpd004c4i4hqsk3mzrr", "label": "customer-1042", "product": "residential-premium", "dataGbTotal": 10.0, "dataGbRemaining": 0.8, "thresholdPct": 10, "expiresAt": null } } ``` ### Service notices: know when we change something `announcement.published` fires when we publish a [service notice](https://hproxy.com/docs/announcements): a maintenance window, an incident, a pricing change, or an `ACTION_REQUIRED` notice about the API itself. It carries the id, title, kind and audience; read the body from [GET /announcements](https://hproxy.com/docs/announcements) when you need it. Only notices addressed to an audience your account belongs to are delivered, and every account with a key belongs to `DEVELOPERS`. **announcement.published delivery** ```json { "event": "announcement.published", "created": "2026-09-03T18:40:12.101Z", "resource": "announcement", "data": { "announcementId": "1f3c9a7e-…", "title": "Order bodies are now strict: unknown fields return 400", "kind": "ACTION_REQUIRED", "audience": "DEVELOPERS" } } ``` ### Verifying the signature Compute HMAC-SHA256 of the **exact raw request body bytes** with your `whsec_…` secret and compare it (constant-time) to `X-HProxy-Signature`. We sign the exact bytes we send, so there is nothing to re-serialize. Respond `2xx` to acknowledge; anything else is retried with exponential backoff (first retry ~30s, doubling, capped at 6h) for up to 10 attempts. **Node.js** ```js import crypto from "crypto"; export function verifyHproxySignature(rawBody, signatureHeader, secret) { const expected = crypto.createHmac("sha256", secret) .update(rawBody) // the EXACT raw bytes, before any JSON.parse .digest("hex"); return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader)); } ``` **Python** ```python import hashlib, hmac def verify_hproxy_signature(raw_body: bytes, signature_header: str, secret: str) -> bool: expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, signature_header) ``` > [!WARNING] **Verify before you trust**: Parse the body ONLY after the signature checks out, and reject events whose `created` is older than your replay window (5 minutes is a good default). ## Build a reseller business on HProxy *The reseller loop over the HProxy API: fund a wallet, sell residential GB or dedicated IPs, deliver programmatically, get pushed on fulfillment and renew.* URL: https://hproxy.com/docs/proxy-api/reselling Everything a proxy storefront needs, over one API: **prepaid wallet**, **server-authoritative quotes**, **idempotent orders**, **programmatic delivery** for both residential lines and dedicated IPs, **webhooks** on fulfillment, and **renewals**. Your customers never see HProxy: every response is white-label by construction. 1. **Fund the wallet**: `POST /deposits` returns a hosted `payUrl` (card or crypto). Everything below prepays from this balance and fails with an honest `402` when it's short. No surprise card charges, ever. 2. **Quote before you sell**: `GET /products/{id}/price` returns the exact amount the order will charge. For dedicated IPs pass `country` and `period_days` too. Put your margin on top and show YOUR price. 3. **Buy on demand**: `POST /orders` with an `Idempotency-Key`. Wallet-paid orders return in seconds; a retry with the same key can never double-charge. For residential the body is `product_id` plus `quantity` in GB and nothing else: the country is chosen in the next step. 4. **Deliver**: Residential: `POST /plans/{id}/generate` per customer request. Dedicated: `GET /proxies?order_id=…` once the order completes. 5. **Attribute**: `PATCH /plans/{id}` with a `label`. Your reference rides on every read and every webhook for that plan after that. 6. **Get pushed, don't poll**: Register a [webhook](https://hproxy.com/docs/proxy-api/webhooks): `order.fulfilled` fulfills the sale, `plan.low_traffic` prompts the top-up. 7. **Renew**: `POST /orders` with `fulfillment_meta: {"kind": "extension", "ids": […]}` renews exactly the proxies your customer keeps. ### Selling residential GB: how plans work **One account holds one active plan per residential product, and every purchase tops it up.** Buy 5 GB of `residential-lite`, then 3 GB more, and you have one plan with 8 GB, one credential pair and one balance. Generation is free and repeatable: every line you generate is that same credential with the country and session written into the username, and the plan's GB is drawn down only by the traffic that actually flows. There is no per-line metering, so lines you hand to different people share one balance. That is the right shape for **your own usage, trials and burst capacity**, and the wrong shape for selling to more than one customer: whoever generates lines first can spend the other's traffic, and nothing in this lane can stop them. **Isolation per customer is the Reseller API**, described below: one header names your customer, and the call runs as an account of their own, with its own plan, its own credentials, its own GB cap and its own balance. That is the sub-user model, and it is the lane a storefront should be on before its second customer. **Residential loop, single account** ```bash # The single-account loop: your own usage, or one trial pool. # 1. Buy 10 GB. A later purchase of the same product tops up this plan. curl -X POST https://hproxy.com/api/v1/orders \ -H "X-API-Key: hpx_your_key_here" -H "Idempotency-Key: pool-resi-10gb" \ -H "Content-Type: application/json" \ -d '{"product_id": "residential-lite", "quantity": 10}' # 2. Your plan (one per residential product), with its remaining GB curl https://hproxy.com/api/v1/plans -H "X-API-Key: hpx_your_key_here" # 3. Tag it with your own reference curl -X PATCH https://hproxy.com/api/v1/plans/{planId} \ -H "X-API-Key: hpx_your_key_here" -H "Content-Type: application/json" \ -d '{"label": "trial-pool"}' # 4. Generate lines (free, repeatable; GB is spent by traffic only) curl -X POST https://hproxy.com/api/v1/plans/{planId}/generate \ -H "X-API-Key: hpx_your_key_here" -H "Content-Type: application/json" \ -d '{"count": 100, "country": "US", "stickyMinutes": 10}' # 5. Read the balance any time (synced about every 30 minutes) curl https://hproxy.com/api/v1/plans/{planId} -H "X-API-Key: hpx_your_key_here" ``` > [!NOTE] **Updated**: Updated 2026-09-03. An earlier version of this section described a per-purchase plan model that no longer applies: a purchase of a residential product tops up the plan you hold for it. If you built on the older wording, read plan ids from `GET /plans` after each order instead of expecting a new one, and use the Reseller API below for isolation per customer. ### Sub-users: one account per customer, over one header On the Reseller API your key names a customer with `X-Reseller-Customer-Id`, and every call runs **as that customer**: `POST /orders` provisions their own plan and credentials, `GET /plans` lists only theirs, `GET /wallet` is the credit you issued them, and `GET /customers` is your whole book. Customer A can never generate from customer B's plan, because they are different accounts. Nothing else about the API changes. The lane is granted rather than self-served, and getting on it is four steps: 1. **Apply from your dashboard**: Sign in and open [Reseller](https://hproxy.com/dashboard/reseller): your business name, a few lines about what you sell, and the Partner Agreement. The application is tied to the account whose key you already use, so there is nothing to re-create. 2. **We review it, in person**: Every partner is onboarded by a person, the founder included. We reply on the email of your account and ask for a Telegram or WhatsApp contact, so you have a direct line for the whole time you sell on the platform. 3. **Approval provisions the lane**: Your account gets a rate card and a business dashboard (balance, customers, your prices, statement, support inbox). In the dashboard, under Storefront, API access, you create your reseller API key yourself: it carries the `act_as_reseller_customer` scope, it is shown once, and it is the key that names customers. The key you have today keeps working for your own account. 4. **Put customers behind the header**: Add `X-Reseller-Customer-Id: ` to any call. The first call creates the customer; `PUT /customer/contact` attaches their email and a display name; an order as them provisions their own plan. The full loop is on the [Reseller API](https://hproxy.com/docs/proxy-api/reseller) page. ### Selling dedicated IPs (IPv4 / IPv6 / ISP / Mobile) **Dedicated loop** ```bash # 0. Show your customer the countries in stock right now (name + alpha3), # plus the rental periods. Always current: sold-out countries drop out. curl https://hproxy.com/api/v1/products/ipv4/options -H "X-API-Key: hpx_your_key_here" # 1. Quote the exact charge for the targeting your customer picked curl "https://hproxy.com/api/v1/products/ipv4/price?quantity=5&country=DEU&period_days=30" \ -H "X-API-Key: hpx_your_key_here" # 2. Buy with the same targeting curl -X POST https://hproxy.com/api/v1/orders \ -H "X-API-Key: hpx_your_key_here" -H "Idempotency-Key: cust-1042-ipv4-de-5" \ -H "Content-Type: application/json" \ -d '{"product_id": "ipv4", "quantity": 5, "fulfillment_meta": {"country": "DEU", "period_days": 30}}' # 3. On the order.fulfilled webhook (or once GET /orders/{id} says completed): curl "https://hproxy.com/api/v1/proxies?order_id={orderId}" -H "X-API-Key: hpx_your_key_here" # -> ip, ports, username, password per proxy. Hand them to your customer. # 4. Renewal, 30 more days for the proxies the customer kept curl -X POST https://hproxy.com/api/v1/orders \ -H "X-API-Key: hpx_your_key_here" -H "Idempotency-Key: cust-1042-renew-jul" \ -H "Content-Type: application/json" \ -d '{"product_id": "ipv4", "quantity": 2, "fulfillment_meta": {"kind": "extension", "ids": ["9214321", "9214322"], "period_days": 30}}' ``` Renewals are ownership-checked server-side: the `ids` (from [GET /proxies](https://hproxy.com/docs/proxy-api/proxies)) must belong to the calling account, and the renewal is priced for exactly those proxies. `quantity` should match the number of ids. ### Selling scrapers A scraper call is charged to your own balance at our normal per-call price, the same as for every customer, whether you call it for yourself or for a customer of yours. Put your own price on top in your billing. The [Scraper API](https://hproxy.com/docs/scrapers) pages list every endpoint and its price. > [!WARNING] **Scrapers change often**: A scraper reads a website we do not control. When that website changes its pages, its limits or how it blocks automated traffic, a scraper can fail, return fewer fields, or return fields in a different shape until we update it, and we update scrapers often. **Scrapers are not a stable product that never breaks.** Handle errors and retry, read the fields inside `data` defensively, subscribe to [service notices](https://hproxy.com/docs/announcements), and do not promise your customers that a scraper will never change or never fail. The envelope around `data` keeps its shape. ### What stays stable when we change things underneath The networks behind a product change, sometimes at short notice, and a storefront should never notice. Build on the things we keep stable and treat everything else as a value to read, not to remember: 1. **Product ids**: `residential-lite`, `residential-premium`, `ipv4` and the rest are ours and stay put when the pool behind them is swapped. Read `GET /products` for `available` and the targeting contract instead of hardcoding either. 2. **Plan ids and balances**: A plan id never changes meaning: the plan keeps serving its remaining gigabytes from the pool it was bought on. When we move a product to a new pool, the next purchase of that product opens a fresh plan beside the old one, so for a while `GET /plans` can list two plans for one product. List plans and read their balances rather than assuming one per product, and read plan ids from the API after an order completes rather than predicting them. 3. **Lines, generated on demand**: Generate through `POST /plans/{id}/generate` when a customer needs lines, and hand those out. The credentials inside a line can rotate when a pool moves, so do not store lines for longer than a session or bake them into a customer's config. 4. **Order and proxy ids**: Renewals and lookups run on our ids (`orderId`, the `id` in `GET /proxies`), never on anything that names a network. 5. **Notices**: A change that needs something from you arrives as an `ACTION_REQUIRED` [service notice](https://hproxy.com/docs/announcements): in the feed, as the `announcement.published` webhook, and by email to the account. Subscribe once and you will not learn about a change from a failing request. Our side of it: fields and codes are only ever added, never renamed or removed, and an existing `code` keeps its meaning. If a call ever has to change how it behaves, the change is announced as an `ACTION_REQUIRED` notice with a date before it happens, and the old behavior keeps working until that date. Nothing in a response names a network or a provider, so a pool change is not something your code can see. ### Safety rails for production Send an `Idempotency-Key` on every write, so retries converge instead of double-charging. Put a **daily spend cap** on the key in your dashboard, so a leak can't drain the wallet. Verify [webhook signatures](https://hproxy.com/docs/proxy-api/webhooks) before trusting a delivery. Branch on the machine `code` in error bodies (`402` = top up, `429` = back off per `Retry-After`). And generate your client from the [OpenAPI spec](https://hproxy.com/docs/openapi) instead of hand-writing one. > [!NOTE] **White-label by construction**: Responses never name upstream networks or infrastructure partners, so your storefront stays fully white-label. > [!TIP] **The sub-user lane**: Selling to more than one customer? Apply for the [Reseller API](https://hproxy.com/docs/proxy-api/reseller) from your [dashboard](https://hproxy.com/dashboard/reseller): one account per customer, isolated plans and balances, your negotiated rates, and a customer book with names and emails. ## Reseller API: act as your customers *For approved resellers: name each of your customers with X-Reseller-Customer-Id and every call runs as them: isolated plans and balances per customer, orders at your negotiated rates, and a customer book with contact identity.* URL: https://hproxy.com/docs/proxy-api/reseller The reselling guide's loop runs everything through YOUR account and tags plans with labels. **Approved resellers get a stronger model**: your key names one of your customers per request, and the call runs **as that customer**: their own plans, their own spendable balance, their own order history, fully isolated from every other customer. You price in your business dashboard, we charge you your negotiated rates, and your customers never see us anywhere. Reseller access is granted, not self-served. Apply from [Reseller in your dashboard](https://hproxy.com/dashboard/reseller) with the account whose key you already use; we review every application in person and reply on the account's email. Approval provisions your rate card and opens your business dashboard (balance, statement, customers, your prices, storefront, support inbox). Your reseller API key, carrying the `act_as_reseller_customer` scope, is one you create in that dashboard under Storefront, API access; it is shown once, and you can hold up to three and revoke any of them there. The [reselling guide](https://hproxy.com/docs/proxy-api/reselling#sub-users-one-account-per-customer-over-one-header) walks the four steps. ### Naming a customer Add one header to any `/api/v1` call. The id is **yours** (your user id, an email hash, anything stable): up to 64 characters of letters, digits, `_`, `-`, `.`. It is scoped to your account, so two businesses using the same id refer to different people and can never see each other's data. **The customer is created the first time you name one**, so there is no signup call. **Any call, as your customer** ```bash curl https://hproxy.com/api/v1/plans \ -H "X-API-Key: hpx_your_key_here" \ -H "X-Reseller-Customer-Id: user-4021" ``` Without the header, the same key acts as your own account (your wallet, your deposits), which is how you top up your reseller balance. With it, reads and writes belong to that customer. ### Do I need to set up CORS? **No.** CORS is a rule browsers apply to web pages, and your reseller key belongs on your **server**, never in your site's JavaScript: a key in the browser can be copied by any visitor and spent against your balance. Server-to-server calls (your backend calling ours) are not subject to CORS at all, so there is nothing to configure on your side or ours. Your customers' browsers talk to **your** site; your site's backend calls `/api/v1`. For completeness: `/api/v1` does answer browser preflights from any origin and accepts `X-API-Key`, `Authorization`, `X-Reseller-Customer-Id`, `Idempotency-Key` and `Content-Type`, which is what our own browser extension relies on. It sends no cookies and reads none, so opening it to every origin gives nobody access they would not have with your key anyway. Optional hardening: in your business dashboard under **API keys**, **Lock your keys to your servers** lets you list the IP addresses your backend calls from. Your keys then stop working from anywhere else, so a leaked copy is useless. ### How the money works Your customers pay **you**, on your site, with your payment methods. You mirror what they paid you as **store credit** on that customer (from your business dashboard, or from your own backend with [`PUT /customer/credit`](#partner-customer-credit)), and their orders spend that credit at **your prices** while your prepaid reseller balance is charged **your negotiated rate** in the same transaction. The gap is your margin, and it never appears in anything their side can read. When their credit is short an order fails with `402 customer_credit_insufficient`; when your balance is short, `402 reseller_balance_insufficient`. Nothing half-charges. Your storefront can also take the payment itself: connect your **own** gateway (Heleket or NOWPayments for crypto, Stripe or Payoneer Checkout for cards) under Payments in your business dashboard, and [`POST /deposits`](#partner-deposit-create) for a named customer returns a pay page on **your** merchant account. What arrives is credited to that customer automatically, underpayments and overpayments included. Without a gateway for the requested method the call answers `403 deposits_not_available`; there is never a payment page of ours for your customers to reach. #### GET /api/v1/customer **Read the acting customer.** The named customer's profile: your id for them, your display name (`label`), the email you attached, the credit they can still spend (in cents, at your prices), and when they were created and last seen. Requires the `X-Reseller-Customer-Id` header. **Request** ```bash curl https://hproxy.com/api/v1/customer \ -H "X-API-Key: hpx_your_key_here" \ -H "X-Reseller-Customer-Id: user-4021" ``` **Response** ```json { "customer": { "externalId": "user-4021", "label": "Alex M.", "contactEmail": "alex@example.com", "creditCents": 2500, "createdAt": "2026-08-23T15:02:11+00:00", "lastSeenAt": "2026-08-23T16:40:03+00:00" } } ``` #### PUT /api/v1/customer/contact **Attach their identity.** Set the customer's email and your display name for them, ideally right after your own signup flow, so your customer book, your business dashboard and our support all see a person instead of an opaque id. Each field: **omitted = unchanged, empty string = cleared, value = set**. We never send mail to this address; it is identity, not a channel. | Field | Type | Required | Description | | --- | --- | --- | --- | | `email` | `string` | optional | The customer's email address. Stored lowercased. Empty string clears it. | | `label` | `string` | optional | Your display name for them, 1 to 120 characters. Empty string clears it. | **Request** ```bash curl -X PUT https://hproxy.com/api/v1/customer/contact \ -H "X-API-Key: hpx_your_key_here" \ -H "X-Reseller-Customer-Id: user-4021" \ -H "Content-Type: application/json" \ -d '{"email": "alex@example.com", "label": "Alex M."}' ``` **Response** ```json { "customer": { "externalId": "user-4021", "label": "Alex M.", "contactEmail": "alex@example.com", "creditCents": 2500, "createdAt": "2026-08-23T15:02:11+00:00", "lastSeenAt": "2026-08-23T16:40:03+00:00" } } ``` #### PUT /api/v1/customer/credit **Credit or revoke their balance.** Move store credit on the named customer, from your own backend: **grant** when they paid you, **revoke** for a refund on your side or a correction. Amounts are whole cents at your retail prices; one movement is at most $5,000. Send your own `request_id` for every movement (your payment id, your refund id): a repeat with the same id answers `409 already_applied` instead of moving the credit twice, so a retry is always safe. A revoke larger than what is left is refused (`revoke_exceeds_credit`) and names the remaining figure. Requires the `X-Reseller-Customer-Id` header. | Field | Type | Required | Description | | --- | --- | --- | --- | | `amount_cents` | `integer` | required | Positive whole cents at your prices. | | `direction` | `string` | required | "grant" or "revoke". | | `request_id` | `string` | required | Your id for this movement, one per intent, 1 to 100 characters. | | `note` | `string` | optional | Shown on your statement, up to 200 characters. | **Request** ```bash curl -X PUT https://hproxy.com/api/v1/customer/credit \ -H "X-API-Key: hpx_your_key_here" \ -H "X-Reseller-Customer-Id: user-4021" \ -H "Content-Type: application/json" \ -d '{"amount_cents": 2500, "direction": "grant", "request_id": "pay_8f3a21", "note": "Stripe pi_3Q…"}' ``` **Response** ```json { "customer": { "externalId": "user-4021", "label": "Alex M.", "contactEmail": "alex@example.com", "creditCents": 5000, "createdAt": "2026-08-23T15:02:11+00:00", "lastSeenAt": "2026-08-23T16:40:03+00:00" } } ``` #### POST /api/v1/deposits **Let the named customer pay you.** With `X-Reseller-Customer-Id`, this creates an invoice on **your own** payment gateway (connected under Payments in your business dashboard) and returns its pay page: crypto through Heleket or NOWPayments (`method: "crypto"`), cards through Stripe Checkout or Payoneer Checkout (`method: "card"`); one live gateway per rail. The page shows your merchant name, the money goes to your account, and when it arrives we credit the customer's store credit automatically: the exact amount, the whole amount when they overpay, and what actually arrived when a crypto invoice closes short. Amounts are whole cents; sub-floor amounts are raised to the method floor ($3 crypto, $10 card) and one invoice is at most $5,000. Send an `Idempotency-Key` and a retried request returns the same open invoice. No gateway for that method ⇒ `403 deposits_not_available`. **An order can pay for itself.** [`POST /orders`](https://hproxy.com/docs/proxy-api/orders) for a named customer with `method: "crypto"` or `"card"` and short credit still answers `402 customer_credit_insufficient`, but with `payUrl`, `depositId`, `chargeCents` (the shortfall raised to the rail's minimum) and `shortfallCents` added. Send the customer to `payUrl`: when the money lands, the credit is granted and the order is placed automatically under the same `Idempotency-Key`, a Telegram customer is told in the store's bot, and [`GET /deposits/{id}`](#partner-deposit-get) shows `for_order: true`. Without a gateway for that rail the 402 carries no pay page and the customer needs credit first. | Field | Type | Required | Description | | --- | --- | --- | --- | | `amount_cents` | `integer` | required | Whole cents at your prices. | | `method` | `string` | optional | "crypto" or "card". Default "card". | | `return_url` | `string` | optional | Where the customer lands after paying (https). Default: your website, else your Telegram storefront. | **Request** ```bash curl -X POST https://hproxy.com/api/v1/deposits \ -H "X-API-Key: hpx_your_key_here" \ -H "X-Reseller-Customer-Id: user-4021" \ -H "Idempotency-Key: topup_8f3a21" \ -H "Content-Type: application/json" \ -d '{"amount_cents": 2500, "method": "crypto", "return_url": "https://shop.example.com/wallet"}' ``` **Response** ```json { "deposit_id": "rpay_cmt9x2k1a0001", "pay_url": "https://pay.heleket.com/pay/4f1c…", "amount_cents": 2500, "status": "awaiting_payment" } ``` #### GET /api/v1/deposits/{id} **Read one of your customers' payments.** The state of a deposit your storefront created, for your own backend to show "payment received". `status` is `awaiting_payment`, `paid`, `paid_over`, `underpaid`, `expired`, `cancelled`, `failed`, `locked` (held by the gateway; nothing credited) or `needs_review`. `credited_cents` is what landed on the customer's store credit. Account-level: no customer header needed, and only your own deposits resolve. **Request** ```bash curl https://hproxy.com/api/v1/deposits/rpay_cmt9x2k1a0001 \ -H "X-API-Key: hpx_your_key_here" ``` **Response** ```json { "deposit_id": "rpay_cmt9x2k1a0001", "status": "paid", "provider": "heleket", "method": "crypto", "amount_cents": 2500, "received_cents": 2500, "credited_cents": 2500, "pay_url": null, "created_at": "2026-09-04T09:12:41+00:00", "settled_at": "2026-09-04T09:20:03+00:00" } ``` #### GET /api/v1/usage **A customer's bandwidth history.** With `X-Reseller-Customer-Id`, the named customer's traffic from the meter: one row per day and one per plan over the last `days` days (1 to 365, default 30). `gbUsed` is what was consumed that day; `null` means no reading exists for that day (a plan's first day, or a gap) and is never zero, and `unknownDays` counts those. Each day also carries `gbTotal` (the caps of the plans measured that day) and `gbLeft` (what they still held at the day's last reading), so how much a customer had and how much is left is a history, not a snapshot. Each plan line carries its cap, the meter at the last reading (`gbUsedEnd`) and `gbLeft`. Narrow to one plan with `plan_id`. What they bought is on [`GET /orders`](https://hproxy.com/docs/proxy-api/orders); this is what they used. Readings land every 30 minutes, one pass after the plan's own figures are synced, so a plan bought in the last hour may have no row yet; for a live figure read the plan itself (`GET /plans/{id}`). | Field | Type | Required | Description | | --- | --- | --- | --- | | `days` | `integer (query)` | optional | Window in days, 1 to 365. Default 30. | | `plan_id` | `string (query)` | optional | One plan only. | **Request** ```bash curl "https://hproxy.com/api/v1/usage?days=7" \ -H "X-API-Key: hpx_your_key_here" \ -H "X-Reseller-Customer-Id: user-4021" ``` **Response** ```json { "days": 7, "gbUsed": 3.42, "unknownDays": 1, "daily": [ { "day": "2026-09-01", "gbUsed": null, "gbTotal": 10, "gbLeft": 9.1, "plans": 1, "unknown": 1, "meterResets": 0 }, { "day": "2026-09-02", "gbUsed": 1.2, "gbTotal": 10, "gbLeft": 7.9, "plans": 1, "unknown": 0, "meterResets": 0 } ], "plans": [ { "planId": "plan_…", "product": "residential-premium", "productName": "Residential Premium", "label": null, "gbUsed": 3.42, "daysKnown": 6, "unknownDays": 1, "gbTotal": 10, "gbUsedEnd": 4.3, "gbLeft": 5.7 } ] } ``` #### GET /api/v1/store/usage **Your whole store's bandwidth.** Account-level (no customer header): what all your customers used per day beside what you sold per day, per product, and the ten customers that used the most, over the last `days` days. `gb_used` is the meter, `gb_sold` is GB on paid orders by the day they were paid, `gb_total` and `gb_left` are what the measured plans had and still held at the day's last reading; the four are never mixed into one number. `unknown_days` counts plan-days without a reading. Readings land every 30 minutes, one pass after each plan's own figures are synced. Snake_case like the other account-level doors. | Field | Type | Required | Description | | --- | --- | --- | --- | | `days` | `integer (query)` | optional | Window in days, 1 to 365. Default 30. | **Request** ```bash curl "https://hproxy.com/api/v1/store/usage?days=30" \ -H "X-API-Key: hpx_your_key_here" ``` **Response** ```json { "days": 30, "totals": { "gb_used": 41.2, "gb_sold": 120, "gb_total": 300, "gb_left": 212.6, "unknown_days": 3, "plans": 17 }, "daily": [ { "day": "2026-09-04", "gb_used": 1.4, "gb_total": 300, "gb_left": 212.6, "gb_sold": 10, "plans": 17, "unknown": 0, "meter_resets": 0 } ], "products": [ { "product": "residential-premium", "product_name": "Residential Premium", "gb_used": 30.1, "plans": 9, "unknown_days": 1, "gb_sold": 80, "orders": 12 } ], "customers": [ { "external_id": "user-4021", "label": "Ali", "gb_used": 14.2, "plans": 2 } ] } ``` #### GET /api/v1/customers **List your customers.** Every customer on your account, newest first, with identity and credit, the read your backend reconciles against. This is an **account-level** call: send it **without** the `X-Reseller-Customer-Id` header (naming a customer here is refused with a `400` telling you to drop the header). | Field | Type | Required | Description | | --- | --- | --- | --- | | `limit` | `integer (query)` | optional | Page size, 1 to 200. Default 50. | | `offset` | `integer (query)` | optional | Rows to skip. Default 0. | **Request** ```bash curl "https://hproxy.com/api/v1/customers?limit=50" \ -H "X-API-Key: hpx_your_key_here" ``` **Response** ```json { "customers": [ { "externalId": "user-4021", "label": "Alex M.", "contactEmail": "alex@example.com", "creditCents": 2500, "createdAt": "2026-08-23T15:02:11+00:00", "lastSeenAt": "2026-08-23T16:40:03+00:00" }, { "externalId": "user-3990", "label": null, "contactEmail": null, "creditCents": 0, "createdAt": "2026-08-22T10:11:40+00:00", "lastSeenAt": null } ] } ``` ### The whole loop, as one customer **Signup to delivery** ```bash # 0. Your customer signs up on YOUR site -> create + identify them curl -X PUT https://hproxy.com/api/v1/customer/contact \ -H "X-API-Key: hpx_your_key_here" -H "X-Reseller-Customer-Id: user-4021" \ -H "Content-Type: application/json" \ -d '{"email": "alex@example.com", "label": "Alex M."}' # 1. They paid you -> mirror it as credit, from your backend (or in the # business dashboard: Customers -> user-4021 -> Add credit) curl -X PUT https://hproxy.com/api/v1/customer/credit \ -H "X-API-Key: hpx_your_key_here" -H "X-Reseller-Customer-Id: user-4021" \ -H "Content-Type: application/json" \ -d '{"amount_cents": 2500, "direction": "grant", "request_id": "pay_8f3a21"}' # Their balance, any time: curl https://hproxy.com/api/v1/wallet \ -H "X-API-Key: hpx_your_key_here" -H "X-Reseller-Customer-Id: user-4021" # -> { "balanceCents": 2500, "currency": "USD" } (their credit, your prices) # 2. They buy on your site -> order AS them (Idempotency-Key is REQUIRED here). # Residential: product_id + quantity in whole GB, NO country. A 1 GB # package is "quantity": 1. The country comes in step 3. curl -X POST https://hproxy.com/api/v1/orders \ -H "X-API-Key: hpx_your_key_here" -H "X-Reseller-Customer-Id: user-4021" \ -H "Idempotency-Key: your-order-83741" \ -H "Content-Type: application/json" \ -d '{"product_id": "residential-lite", "quantity": 5}' # 3. Deliver: once GET /orders/{orderId} reads "completed" (or the # order.fulfilled webhook arrives), take the plan id from GET /plans and # generate lines from THEIR plan (free, repeatable). The country goes HERE. curl https://hproxy.com/api/v1/plans \ -H "X-API-Key: hpx_your_key_here" -H "X-Reseller-Customer-Id: user-4021" curl -X POST https://hproxy.com/api/v1/plans/{planId}/generate \ -H "X-API-Key: hpx_your_key_here" -H "X-Reseller-Customer-Id: user-4021" \ -H "Content-Type: application/json" \ -d '{"count": 100, "country": "US", "stickyMinutes": 10}' ``` > [!NOTE] **Packages and countries**: A menu of **packages** (1 GB, 5 GB, 10 GB) is one product id ordered with different `quantity` values, never one id per package. `quantity` is a whole number of the product's unit from its `minQuantity`, so a residential package is at least 1 GB. The **country** is never part of a residential order: sell the GB, then generate lines for whichever country your customer picks, as often as they like, from the same plan. Dedicated IPs work the same way: list the countries in stock with [`GET /products/{id}/options`](https://hproxy.com/docs/proxy-api/products#options) (always current, sold-out countries drop out on their own), quote and order with `country` and `period_days` in `fulfillment_meta` while naming the customer, then `GET /proxies?order_id=…` **as that customer** once the order completes. Renewals too: the `ids` must belong to the acting customer, exactly as ownership works everywhere else. ### Rules the lane enforces **An `Idempotency-Key` is required on every reseller order** (a plain key merely should send one; a reseller key must, and an order without one is refused before any charge): only your system knows whether a request is a new sale or a retry, and this is what makes retries free. Isolation is structural: a customer id that is not yours simply does not resolve, plan and proxy ownership follow the acting customer, and `GET /plans` for customer A can never show customer B's plans. Reseller keys also carry a **higher rate-limit tier**, sized for a whole storefront (thousands of customers behind one key) rather than a single integration, so a busy shop or a bulk operation is never throttled for being busy. > [!NOTE] **Your catalog**: On a reseller key, `GET /products` lists every product you can sell: the products sold per GB on your price list and, since September 15, 2026, dedicated IPs and ISP Unlimited too. It can include storefront-only products the public catalog does not list. Everything about them (pricing, options, ordering) works exactly like every other product on this page, and every quote on this key is at your prices. The other direction is yours too: a product you hide in your business dashboard (Pricing, then Hide) leaves your catalog and your bot on their next read, and an order for it as one of your customers answers `409 product_unavailable`. ### What you can sell, and what you pay 1. **Products sold per GB**: Residential Premium and Lite, IPv4 and IPv6 per GB, ISP Rotating and Mobile per GB each have **one fixed price per GB** on your price list (Pricing in your business dashboard), with your discount already in it when you have one. A single order never costs you more than our own customers pay for the same order. 2. **Dedicated IPs**: Static ISP, IPv4, IPv6 and mobile IPs are priced live per country and period. You pay **our customer price, less your discount** when you have one, and never below what the order costs us. Your customers pay our price times your markup, which you set per family in your business dashboard. **To see every price**, read [`GET /products/{id}/price-list?country=USA`](https://hproxy.com/docs/proxy-api/products#price-list): every period of the country with `yourCostCents` on each line. Your dashboard shows the same table under Pricing. 3. **ISP Unlimited**: `isp-unlimited` sells as a monthly speed tier: `quantity` is the tier in Mbps (10, 25, 50 or 100). You pay our tier price, less your discount when you have one; your customers pay it times your markup. Each order is its own plan: take its id from `GET /plans` and generate lines from it, as with residential. 4. **Scrapers**: A scraper call is charged to **your own balance** at our normal scraper price, the same as for every customer. Call scrapers with a reseller API key made from September 15, 2026, on (it carries the `scrape` scope) or with any key on your account that has that scope, and send them **without** `X-Reseller-Customer-Id`: naming a customer on a scraper call is refused with `400 drop_customer_header`. You bill your customers for scraper use yourself. > [!WARNING] **Scrapers change often**: A scraper reads a website we do not control. When that website changes its pages, its limits or how it blocks automated traffic, a scraper can fail, return fewer fields, or return fields in a different shape until we update it, and we update scrapers often. **Scrapers are not a stable product that never breaks.** Handle errors and retry, read the fields inside `data` defensively, subscribe to [service notices](https://hproxy.com/docs/announcements), and do not promise your customers that a scraper will never change or never fail. The envelope around `data` keeps its shape. > [!NOTE] **When your prices apply**: Your partner prices (your fixed prices, your discount) apply to orders placed **for one of your customers**: through your bot, or on the API with `X-Reseller-Customer-Id`. An order your key places with no customer named is bought for **your own account at our normal price**, without them. Every quote on your key says both figures: `yourCostCents` for your customers' orders, `listCents` for an order of your own. ### Lock your key to your servers Your reseller key is a server-to-server credential, so you can pin it to the IP addresses your own backend calls us from. Set the allowlist in your business dashboard under **Storefront → Key access**, and the key stops working from anywhere else. A leaked copy is inert. It is off by default, holds a handful of IPv4/IPv6 addresses, and restricts **only the API key**: the dashboard is a separate, session-authed login, so a wrong entry locks your integration, never you out of fixing it. A call from a disallowed IP is refused with `403 ip_not_allowed`. > [!TIP] **Where the rest lives**: Issue and revoke customer credit, set your prices, watch your statement and answer your customers' support messages in your business dashboard. The API is the selling lane; the dashboard is the business lane.