# REST API: баланс, использование, учётные данные, заказы, списки и устройства.

Все функции панели управления в формате JSON через HTTPS. Базовый URL: `https://api.hodlproxy.com/v1`, аутентификация Bearer, пагинация с курсором.

> Info: Контракт на этой странице является окончательным. Тот же контракт опубликован как [документ OpenAPI 3.1](https://hodlproxy.com/ru/docs/openapi.json), сформированный на основе этой страницы, для генераторов клиентов и инструментов агентов.


## Соглашения

- **Базовый URL**: `https://api.hodlproxy.com/v1`
- **Аутентификация**: `Authorization: Bearer TOKEN`. Токены создаются в разделе **API-токены** панели управления; каждый из них можно отозвать независимо. Для `GET /v1/pricing` токен не требуется.
- **Формат**: Входные и выходные данные — JSON, `Content-Type: application/json`, UTF-8. Метки времени соответствуют ISO 8601 и указываются в UTC. Денежные суммы передаются десятичной строкой в USD; трафик указывается в байтах, если только в имени поля не указано `_gb`.
- **Пагинация**: Конечные точки списков принимают `limit` (по умолчанию 50, максимум 200) и `cursor`, а возвращают `next_cursor` (`null` на последней странице).
- **Идемпотентность**: Передавайте заголовок `Idempotency-Key` при запросах `POST /orders` и `POST /orders/{id}/renew`; повторный ключ в течение 24 часов вернёт исходный результат без повторного списания.
- **Ограничение частоты**: 120 запросов в минуту на токен. В каждом ответе передаётся `X-RateLimit-Remaining`; при превышении лимита возвращается `429` с `Retry-After`.


## Ошибки

Для ошибок используются стандартные коды статуса и единая структура JSON. Поле `code` стабильно и предназначено для программы; поле `message` предназначено для людей и может изменяться.

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

| Статус | Коды | Значение |
| --- | --- | --- |
| 400 | invalid_request, invalid_parameter | Некорректный JSON или недопустимое значение поля; в `message` указано имя поля |
| 401 | invalid_token | Bearer-токен отсутствует, отозван или имеет неверный формат |
| 402 | insufficient_balance | Средств в кошельке недостаточно для покупки |
| 404 | not_found | Неизвестный идентификатор или объект принадлежит другой учётной записи |
| 409 | conflict | Текущее состояние не допускает действие, например продление уже завершившегося заказа |
| 429 | rate_limited | Слишком много запросов; подождите указанное в `Retry-After` число секунд |
| 5xx | internal_error | Повторите запрос с увеличивающейся задержкой; если объект `order` не возвращён, средства не списывались |


## Учётная запись и баланс


### GET /v1/account

Учётная запись, которой принадлежит токен.

Запрос:

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

Ответ:

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


### GET /v1/balance

Баланс кошелька и остатки трафика для каждой сети пула в байтах и ГБ.

Запрос:

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

Ответ:

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


### GET /v1/usage

Трафик, израсходованный по дням, с фильтрацией по сети, заказу или дополнительному пользователю. Для сетей пула указываются тарифицированные байты, а для выделенных заказов — переданные байты.

| Поле | Где | Описание |
| --- | --- | --- |
| from, to | query | Даты `YYYY-MM-DD` включительно, UTC. По умолчанию: последние 30 дней |
| network | query | `residential`, `mobile`, `isp`, `datacenter` (необязательно) |
| order_id | query | Ограничить одним выделенным заказом (необязательно) |
| subuser_id | query | Ограничить одним дополнительным пользователем (необязательно) |

Запрос:

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

Ответ:

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


## Учётные данные, дополнительные пользователи и белый список


### GET /v1/credentials

Имя пользователя и пароль учётной записи для общих шлюзов.

Запрос:

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

Ответ:

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


### POST /v1/credentials/rotate

Создать новый пароль. Предыдущий продолжит работать в течение десяти минут.

Запрос:

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

Ответ:

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


### POST /v1/subusers

Создать дополнительного пользователя: отдельную пару учётных данных с собственным лимитом трафика. `GET /v1/subusers` возвращает их список; `PATCH /v1/subusers/{id}` изменяет лимит или отключает пользователя; `DELETE` удаляет его.

| Поле | Где | Описание |
| --- | --- | --- |
| label | body | Произвольный текст, отображаемый в отчётах об использовании |
| limit_gb | body | Общий лимит в ГБ для сетей пула или `null`, если лимита нет |
| networks | body | Массив разрешённых сетей пула, по умолчанию `["residential","mobile"]` |

Запрос:

```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}'
```

Ответ:

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

Адреса, которым разрешено подключаться без учётных данных.

Запрос:

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

Ответ:

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


### POST /v1/whitelist

Добавляет IPv4-адрес (до 50 на аккаунт). `DELETE /v1/whitelist/{ip}` удаляет один адрес. Изменения вступают в силу в течение минуты.

| Поле | Где | Описание |
| --- | --- | --- |
| ip | body | Публичный IPv4-адрес |
| label | body | Необязательный текст в свободной форме |

Запрос:

```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"}'
```

Ответ:

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


## Цены


### GET /v1/pricing (публичный, без токена)

Опубликованные таблицы цен: тарифные ступени за ГБ, сроки аренды выделенных продуктов, зоны расположения и скидки за объём. Данные совпадают с указанными на сайте; токен не требуется.

Запрос:

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

Ответ:

```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 } ]
  }
}
```


## Заказы и списки прокси


### POST /v1/orders

Покупает трафик в сети с общим пулом или арендует выделенные адреса либо устройства. При успешном выполнении средства списываются с кошелька; передайте `Idempotency-Key`.

| Поле | Где | Описание |
| --- | --- | --- |
| network | body | `residential`, `mobile`, `isp`, `datacenter`, `mobile_device` |
| gb | body | Сети с общим пулом: приобретаемый объём в ГБ (тарифная ступень определяется по этому объёму) |
| country | body | Выделенные продукты: ISO-код страны адресов |
| city | body | Выделенные продукты: город, если доступен выбор (необязательно) |
| carrier_asn | body | Мобильные устройства: предпочтительный номер AS оператора (необязательно) |
| quantity | body | Выделенные продукты: количество адресов или устройств |
| term_days | body | Выделенные продукты: `1`, `30`, `60` или `90` (`1` — только для ISP-прокси и мобильных устройств) |

Запрос:

```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}'
```

Ответ:

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

Все заказы, начиная с самых новых. `GET /v1/orders/{id}` возвращает один заказ, включая его адреса после их предоставления.

| Поле | Где | Описание |
| --- | --- | --- |
| status | query | `provisioning`, `active`, `ended` (необязательно) |
| network | query | Фильтр по сети (необязательно) |

Запрос:

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

Ответ:

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

Продлевает выделенный заказ ещё на один срок с сохранением тех же адресов. Доступно, пока заказ активен.

| Поле | Где | Описание |
| --- | --- | --- |
| term_days | body | `30`, `60` или `90`; по умолчанию — текущий срок заказа |

Запрос:

```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}'
```

Ответ:

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


### GET /v1/proxies

Ваши выделенные адреса из всех заказов. `format=txt` возвращает обычные строки `ip:port:user:pass`, по одной на адрес, готовые для использования в любом инструменте.

| Поле | Где | Описание |
| --- | --- | --- |
| network | query | `isp`, `datacenter`, `mobile_device` (необязательно) |
| order_id | query | Только один заказ (необязательно) |
| format | query | `json` (по умолчанию) или `txt` |

Запрос:

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

Ответ:

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


## Устройства


### GET /v1/devices

Ваши выделенные мобильные устройства с текущим IP-адресом, оператором и настройками ротации. `GET /v1/devices/{id}` возвращает одно устройство.

Запрос:

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

Ответ:

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

Запрашивает у оператора новый IP-адрес. Ответ возвращается, когда устройство снова подключится к сети с новым адресом; активные соединения при этом разрываются. Ссылка для ротации в панели управления вызывает ту же операцию, используя подписанный ключ вместо токена.

Запрос:

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

Ответ:

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


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

Изменяет таймер ротации. Значение `null` отключает его.

| Поле | Где | Описание |
| --- | --- | --- |
| rotate_every_minutes | body | Целое число от 2 до 1440 или `null` |

Запрос:

```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}'
```

Ответ:

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


Источник: https://hodlproxy.com/ru/docs/api