Account · API reference

The REST API: balance, usage, credentials, orders, lists and devices.

Everything the dashboard does, as JSON over HTTPS. Base URL https://api.hodlproxy.com/v1, Bearer authentication, cursor pagination.

6 min read 7 sections Updated Sep 21, 2026

Conventions#

Base URL: https://api.hodlproxy.com/v1
Authentication: Authorization: Bearer TOKEN. Tokens are created in the dashboard under API tokens; each can be revoked independently. GET /v1/pricing needs no token.
Format: JSON in and out, Content-Type: application/json, UTF-8. Timestamps are ISO 8601 in UTC. Money is a decimal string in USD; traffic is in bytes unless a field name says _gb.
Pagination: List endpoints take limit (default 50, max 200) and cursor, and return next_cursor (null on the last page).
Idempotency: Send an Idempotency-Key header on POST /orders and POST /orders/{id}/renew; a repeated key within 24 hours returns the original result instead of charging twice.
Rate limit: 120 requests per minute per token. X-RateLimit-Remaining on every response; 429 with Retry-After when exceeded.

Errors#

Errors use standard status codes and a single JSON shape. code is stable and meant for your program; message is for humans and may change.

Error body

{
  "error": {
    "code": "insufficient_balance",
    "message": "This order costs 28.22 USD; the wallet holds 12.40 USD."
  }
}

Status	Codes	Meaning
400	invalid_request, invalid_parameter	Malformed JSON or a field outside its allowed values; `message` names the field
401	invalid_token	Missing, revoked or malformed Bearer token
402	insufficient_balance	The wallet cannot cover the purchase
404	not_found	Unknown id, or an object that belongs to another account
409	conflict	The state does not allow the action, for example renewing an order that already ended
429	rate_limited	Too many requests; wait `Retry-After` seconds
5xx	internal_error	Retry with backoff; nothing was charged if no `order` object was returned

Account and balance#

GET/v1/accountBearer

The account behind the token.

Request

curl https://api.hodlproxy.com/v1/account -H "Authorization: Bearer TOKEN"

Response

{
  "id": "acc_3f9k2m",
  "created_at": "2026-09-21T08:14:02Z",
  "whitelist_count": 2,
  "subuser_count": 3
}

GET/v1/balanceBearer

Wallet balance and traffic balances per pool network, in bytes and GB.

Request

curl https://api.hodlproxy.com/v1/balance -H "Authorization: Bearer TOKEN"

Response

{
  "wallet_usd": "142.60",
  "traffic": {
    "residential": { "bytes": 96636764160, "gb": 90.0 },
    "mobile":      { "bytes": 2147483648,  "gb": 2.0 }
  }
}

GET/v1/usageBearer

Traffic consumed per day, filtered by network, order or sub-user. Pool networks report bytes billed; dedicated orders report bytes moved.

Field	In	Description
from, to	query	Dates `YYYY-MM-DD`, inclusive, UTC. Default: the last 30 days
network	query	`residential`, `mobile`, `isp`, `datacenter` (optional)
order_id	query	Restrict to one dedicated order (optional)
subuser_id	query	Restrict to one sub-user (optional)

Request

curl "https://api.hodlproxy.com/v1/usage?from=2026-09-01&to=2026-09-21&network=residential" \
     -H "Authorization: Bearer TOKEN"

Response

{
  "network": "residential",
  "days": [
    { "date": "2026-09-20", "bytes": 5368709120, "requests": 184220 },
    { "date": "2026-09-21", "bytes": 1073741824, "requests": 40118 }
  ],
  "total_bytes": 6442450944
}

Credentials, sub-users and whitelist#

GET/v1/credentialsBearer

The account's username and password for the shared gateways.

Request

curl https://api.hodlproxy.com/v1/credentials -H "Authorization: Bearer TOKEN"

Response

{
  "username": "u7f3a9c",
  "password": "kq2Lm8Pz1r",
  "hosts": { "residential": "res.hodlproxy.com", "mobile": "mob.hodlproxy.com" },
  "ports": { "http": 9000, "socks5": 9001 }
}

POST/v1/credentials/rotateBearer

Generate a new password. The previous one keeps working for ten minutes.

Request

curl -X POST https://api.hodlproxy.com/v1/credentials/rotate -H "Authorization: Bearer TOKEN"

Response

{ "username": "u7f3a9c", "password": "Xr4Nv7Qw2t", "previous_valid_until": "2026-09-21T09:24:00Z" }

POST/v1/subusersBearer

Create a sub-user: an extra credential pair with its own traffic ceiling. GET /v1/subusers lists them; PATCH /v1/subusers/{id} changes the limit or disables it; DELETE removes it.

Field	In	Description
label	body	Free text, shown in usage reports
limit_gb	body	Ceiling in GB across pool networks, or `null` for no ceiling
networks	body	Array of allowed pool networks, default `["residential","mobile"]`

Request

curl -X POST https://api.hodlproxy.com/v1/subusers \
     -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
     -d '{"label":"client-acme","limit_gb":50}'

Response

{
  "id": "sub_9d2x",
  "label": "client-acme",
  "username": "u7f3a9c-acme",
  "password": "Pm3Kz8Rt5v",
  "limit_gb": 50,
  "used_gb": 0,
  "networks": ["residential", "mobile"],
  "enabled": true
}

GET/v1/whitelistBearer

Addresses allowed to connect without credentials.

Request

curl https://api.hodlproxy.com/v1/whitelist -H "Authorization: Bearer TOKEN"

Response

{ "items": [ { "ip": "198.51.100.23", "label": "worker-1", "added_at": "2026-09-19T10:02:11Z" } ] }

POST/v1/whitelistBearer

Add an IPv4 address (up to 50 per account). DELETE /v1/whitelist/{ip} removes one. Changes apply within a minute.

Field	In	Description
ip	body	Public IPv4 address
label	body	Optional free text

Request

curl -X POST https://api.hodlproxy.com/v1/whitelist \
     -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
     -d '{"ip":"198.51.100.23","label":"worker-1"}'

Response

{ "ip": "198.51.100.23", "label": "worker-1", "added_at": "2026-09-21T09:15:40Z" }

Pricing#

GET/v1/pricingPublic

The published price tables: per-GB ladders, dedicated terms, location zones and volume discounts. The same figures as the website; no token required.

Request

curl https://api.hodlproxy.com/v1/pricing

Response

{
  "currency": "USD",
  "residential": { "unit": "GB", "tiers": [ { "min_gb": 1, "price": "2.45" }, { "min_gb": 100, "price": "1.54" } ] },
  "isp": {
    "terms": [ { "days": 30, "per_month": "1.12" }, { "days": 90, "per_month": "0.99" } ],
    "zones": { "a": { "label": "United States", "mult": 1.0, "codes": ["US"] } },
    "volume_discounts": [ { "min_ips": 10, "pct": 5 } ]
  }
}

Orders and proxy lists#

POST/v1/ordersBearer

Buy traffic on a pool network, or rent dedicated addresses or devices. The wallet is charged on success; send an Idempotency-Key.

Field	In	Description
network	body	`residential`, `mobile`, `isp`, `datacenter`, `mobile_device`
gb	body	Pool networks: GB to buy (the tier is derived from this amount)
country	body	Dedicated: ISO country code of the addresses
city	body	Dedicated: city value where offered (optional)
carrier_asn	body	Mobile devices: preferred carrier AS number (optional)
quantity	body	Dedicated: number of addresses or devices
term_days	body	Dedicated: `1`, `30`, `60` or `90` (`1` only for ISP and mobile devices)

Request

curl -X POST https://api.hodlproxy.com/v1/orders \
     -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
     -H "Idempotency-Key: 5d1c7e2a-order-de-isp" \
     -d '{"network":"isp","country":"DE","quantity":10,"term_days":90}'

Response

{
  "id": "ord_7hq4",
  "network": "isp",
  "country": "DE",
  "quantity": 10,
  "term_days": 90,
  "starts_at": "2026-09-21T09:20:00Z",
  "ends_at": "2026-12-20T09:20:00Z",
  "total_usd": "33.86",
  "status": "provisioning"
}

GET/v1/ordersBearer

All orders, newest first. GET /v1/orders/{id} returns one, including its addresses once provisioned.

Field	In	Description
status	query	`provisioning`, `active`, `ended` (optional)
network	query	Filter by network (optional)

Request

curl "https://api.hodlproxy.com/v1/orders?status=active" -H "Authorization: Bearer TOKEN"

Response

{
  "items": [ { "id": "ord_7hq4", "network": "isp", "country": "DE", "quantity": 10, "status": "active", "ends_at": "2026-12-20T09:20:00Z" } ],
  "next_cursor": null
}

POST/v1/orders/{id}/renewBearer

Extend a dedicated order by another term and keep the same addresses. Allowed while the order is active.

Field	In	Description
term_days	body	`30`, `60` or `90`; default: the order's current term

Request

curl -X POST https://api.hodlproxy.com/v1/orders/ord_7hq4/renew \
     -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
     -H "Idempotency-Key: renew-ord_7hq4-2026-12" -d '{"term_days":90}'

Response

{ "id": "ord_7hq4", "ends_at": "2027-03-20T09:20:00Z", "total_usd": "33.86", "status": "active" }

GET/v1/proxiesBearer

Your dedicated addresses across orders. format=txt returns plain ip:port:user:pass lines, one per address, ready for any tool.

Field	In	Description
network	query	`isp`, `datacenter`, `mobile_device` (optional)
order_id	query	One order only (optional)
format	query	`json` (default) or `txt`

Request

curl "https://api.hodlproxy.com/v1/proxies?network=isp&format=txt" -H "Authorization: Bearer TOKEN"

Response

203.0.113.42:8000:u7f3a9c:kq2Lm8Pz1r
203.0.113.57:8000:u7f3a9c:kq2Lm8Pz1r

Devices#

GET/v1/devicesBearer

Your dedicated mobile devices with their current IP, carrier and rotation settings. GET /v1/devices/{id} returns one.

Request

curl https://api.hodlproxy.com/v1/devices -H "Authorization: Bearer TOKEN"

Response

{
  "items": [
    {
      "id": "dev_8k2m",
      "order_id": "ord_2ps9",
      "country": "US",
      "carrier": "T-Mobile",
      "endpoint": { "ip": "198.51.100.9", "http": 8000, "socks5": 8001 },
      "current_ip": "172.58.19.204",
      "rotate_every_minutes": null,
      "last_rotated_at": "2026-09-21T08:50:12Z",
      "ends_at": "2026-11-20T09:20:00Z"
    }
  ],
  "next_cursor": null
}

POST/v1/devices/{id}/rotateBearer

Ask the carrier for a new IP now. Returns when the device is back online with its new address; connections in flight are dropped. The dashboard's rotation link calls the same operation with a signed key instead of a token.

Request

curl -X POST https://api.hodlproxy.com/v1/devices/dev_8k2m/rotate -H "Authorization: Bearer TOKEN"

Response

{ "id": "dev_8k2m", "current_ip": "172.58.22.77", "rotated_at": "2026-09-21T09:31:05Z" }

PATCH/v1/devices/{id}Bearer

Change the rotation timer. null disables it.

Field	In	Description
rotate_every_minutes	body	Integer from 2 to 1440, or `null`

Request

curl -X PATCH https://api.hodlproxy.com/v1/devices/dev_8k2m \
     -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
     -d '{"rotate_every_minutes":10}'

Response

{ "id": "dev_8k2m", "rotate_every_minutes": 10 }

Proxies

Menu

The REST API: balance, usage, credentials, orders, lists and devices.

Conventions#

Errors#

Account and balance#

Credentials, sub-users and whitelist#

Pricing#

Orders and proxy lists#

Devices#

Paste the endpoint, watch the exit change.