# 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.

> Info: The contract on this page is final. The same contract is published as an [OpenAPI 3.1 document](https://hodlproxy.com/docs/openapi.json), generated from this page, for client generators and agent tooling.


## 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.

```json
{
  "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/account

The account behind the token.

Request:

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

Response:

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


### GET /v1/balance

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

Request:

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

Response:

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


### GET /v1/usage

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:

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

Response:

```json
{
  "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/credentials

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

Request:

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

Response:

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


### POST /v1/credentials/rotate

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

Request:

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

Response:

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


### POST /v1/subusers

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:

```bash
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:

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


### GET /v1/whitelist

Addresses allowed to connect without credentials.

Request:

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

Response:

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


### POST /v1/whitelist

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:

```bash
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:

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


## Pricing


### GET /v1/pricing (public, no token)

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

Request:

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

Response:

```json
{
  "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/orders

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:

```bash
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:

```json
{
  "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/orders

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:

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

Response:

```json
{
  "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}/renew

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:

```bash
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:

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


### GET /v1/proxies

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:

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

Response:

```json
203.0.113.42:8000:u7f3a9c:kq2Lm8Pz1r
203.0.113.57:8000:u7f3a9c:kq2Lm8Pz1r
```


## Devices


### GET /v1/devices

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

Request:

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

Response:

```json
{
  "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}/rotate

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:

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

Response:

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


### PATCH /v1/devices/{id}

Change the rotation timer. `null` disables it.

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

Request:

```bash
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:

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


Source: https://hodlproxy.com/docs/api