# ProxyChill API reference

> REST API of ProxyChill, a proxy service (datacenter, ISP, mobile, residential). JSON over HTTPS, Bearer-key auth, prepaid USD balance. Human-readable version: https://proxy-chill.com/docs

## Basics

- **Base URL:** `https://proxy-chill.com/api/?action=<action>` — every endpoint is selected by the `action` query parameter (dot notation, e.g. `catalog.types`).
- **Methods:** `GET` endpoints take parameters in the query string; `POST` endpoints take a JSON body with `Content-Type: application/json`.
- **Authentication:** create a key in the web console (Settings → API Keys) and send `Authorization: Bearer hp_live_...`. Key auth needs no cookies and no CSRF token.
- **Response envelope:** every endpoint (except plain-text exports) returns

```json
{ "ok": true,  "data": { ... }, "error": null }
{ "ok": false, "data": null,   "error": "error_code" }
```

- **Errors** are machine-readable codes in `error` plus an HTTP status (see the table at the end).
- **Money:** all prices and balances are strings in USD with two decimals. Purchases are charged from the prepaid balance; top up the balance in the web console.
- **Typical flow:** `catalog.types` → `catalog.countries?type=…` → `catalog.quote` → `orders.create` → poll `proxies.list` (new proxies appear within seconds; while provisioning they are listed under `data.pending`).
- **Residential proxies** are sold as GB packages. After purchase add one or more *lists* (geo + rotation) with `proxies.resident_configure`; each list gets its own login/password on the shared gateway host and all lists draw from the package GB pool.

## Endpoints

- `GET catalog.types` — List proxy directions (ipv4, isp, mix, residential) with the minimum per-unit price and available country count
- `GET catalog.countries` — Per-unit price by country for a direction
- `GET catalog.resident_geo` — Residential geo reference
- `GET catalog.quote` — Price quote for a given direction, country and quantity
- `POST orders.create` — Create and pay an order from your prepaid balance
- `GET orders.list` — List your orders (most recent first)
- `GET proxies.list` — All active proxies with credentials
- `GET proxies.export` — Plain-text export of per-IP proxies (one per line)
- `POST proxies.renew` — Renew an assignment for one more period
- `POST proxies.autorenew` — Enable or disable automatic renewal for an assignment
- `POST proxies.check` — Live connectivity check through a proxy
- `POST proxies.resident_configure` — Add a new list to a residential package, targeting a geo and rotation
- `POST proxies.resident_list_delete` — Delete a single residential list (not the package)
- `POST proxies.traffic_topup` — Buy more GB for a residential package
- `GET proxies.consumption` — Traffic usage detail for a residential package: per-day series (30 days) and per-list breakdown, in bytes
- `GET billing.balance` — Current account balance
- `GET billing.ledger` — Balance movements (deposits, purchases, refunds)

## Catalog

### GET catalog.types

List proxy directions (ipv4, isp, mix, residential) with the minimum per-unit price and available country count.

`GET https://proxy-chill.com/api/?action=catalog.types`

No parameters.

Request:

```bash
curl "https://proxy-chill.com/api/?action=catalog.types" \
  -H "Authorization: Bearer hp_live_xxxxxxxx"
```

Response `200 application/json`:

```json
{
  "ok": true,
  "data": {
    "types": [
      { "type": "ipv4", "unit": "IP", "mode": "country",
        "min": 1, "steps": null, "unit_price": "1.10", "countries": 40 },
      { "type": "resident", "unit": "GB", "mode": "package",
        "min": 1, "unit_price": "1.80", "countries": 12 }
    ],
    "tiers": [],
    "currency": "USD"
  },
  "error": null
}
```

### GET catalog.countries

Per-unit price by country for a direction. For residential (mode=package) returns GB packages instead of countries.

`GET https://proxy-chill.com/api/?action=catalog.countries`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `type` | string | required | ipv4 \| isp \| mix \| resident |

Request:

```bash
curl "https://proxy-chill.com/api/?action=catalog.countries&type=ipv4" \
  -H "Authorization: Bearer hp_live_xxxxxxxx"
```

Response `200 application/json`:

```json
{
  "ok": true,
  "data": {
    "type": "ipv4", "unit": "IP", "mode": "country",
    "countries": [
      { "country_id": 571, "alpha3": "ITA", "country_name": "Italy", "unit_price": "1.10" },
      { "country_id": 792, "alpha3": "CZE", "country_name": "Czechia", "unit_price": "1.10" }
    ]
  },
  "error": null
}
```

### GET catalog.resident_geo

Residential geo reference. Without a country returns the list of countries. With country=XX returns its regions, cities and ISPs (used to target a residential list).

`GET https://proxy-chill.com/api/?action=catalog.resident_geo`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `country` | string | optional | alpha-2 or alpha-3, e.g. US / USA |

Request:

```bash
curl "https://proxy-chill.com/api/?action=catalog.resident_geo&country=US" \
  -H "Authorization: Bearer hp_live_xxxxxxxx"
```

Response `200 application/json`:

```json
{
  "ok": true,
  "data": {
    "country": "US",
    "regions": [
      { "name": "California",
        "cities": [ { "name": "Los Angeles", "isps": ["Comcast","AT&T"] } ] }
    ]
  },
  "error": null
}
```

### GET catalog.quote

Price quote for a given direction, country and quantity.

`GET https://proxy-chill.com/api/?action=catalog.quote`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `type` | string | required | ipv4 \| isp \| mix \| resident |
| `country_id` | int | required | from catalog.countries |
| `qty` | int | required | quantity / GB |

Request:

```bash
curl "https://proxy-chill.com/api/?action=catalog.quote&type=ipv4&country_id=571&qty=5" \
  -H "Authorization: Bearer hp_live_xxxxxxxx"
```

Response `200 application/json`:

```json
{ "ok": true, "data": { "unit_price": "1.10", "qty": 5, "subtotal": "5.50" }, "error": null }
```

## Orders

### POST orders.create

Create and pay an order from your prepaid balance. Provisioning starts immediately; the proxies appear in proxies.list within seconds.

`POST https://proxy-chill.com/api/?action=orders.create`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `ps_order_type` | string | required | ipv4 \| isp \| mix \| resident |
| `country_id` | int | required | country (per-IP) or GB package id (resident) |
| `quantity` | int | required | IP count; 1 for resident |
| `label` | string | optional | label for the proxies |
| `assignee_id` | int | optional | team member to assign to |

Request:

```bash
curl -X POST "https://proxy-chill.com/api/?action=orders.create" \
  -H "Authorization: Bearer hp_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "ps_order_type": "ipv4", "country_id": 571, "quantity": 2, "label": "scraper-eu" }'
```

Response `200 application/json`:

```json
{ "ok": true, "data": { "order_id": 42, "status": "paid" }, "error": null }
```

Possible errors: `insufficient_funds`, `rate_not_found`, `invalid_quantity`, `type_unavailable`.

### GET orders.list

List your orders (most recent first).

`GET https://proxy-chill.com/api/?action=orders.list`

No parameters.

Request:

```bash
curl "https://proxy-chill.com/api/?action=orders.list" \
  -H "Authorization: Bearer hp_live_xxxxxxxx"
```

Response `200 application/json`:

```json
{
  "ok": true,
  "data": { "orders": [
    { "id": 42, "status": "active", "type": "IPV4", "quantity": 2,
      "plan_title": "IPV4 x2", "price": "2.20", "currency": "USD",
      "created_at": "2026-06-15 18:00:00", "expires_at": "2026-07-15 18:00:00" }
  ] },
  "error": null
}
```

## Proxies

### GET proxies.list

All active proxies with credentials. Per-IP entries carry host/port/user/pass. Residential entries are packages: ip_type="residential" with a lists[] array (one connection per geo) plus traffic_limit / traffic_used (bytes).

`GET https://proxy-chill.com/api/?action=proxies.list`

No parameters.

Request:

```bash
curl "https://proxy-chill.com/api/?action=proxies.list" \
  -H "Authorization: Bearer hp_live_xxxxxxxx"
```

Response `200 application/json`:

```json
{
  "ok": true,
  "data": {
    "proxies": [
      { "id": 1, "ip_type": "datacenter", "proto": "http",
        "host": "91.124.31.97", "port": 50100, "port_socks": 50101,
        "user": "RFTySlwo", "pass": "jFVOgW0oBu",
        "country": "CZE", "expires_at": "2026-07-15 00:00:00" },
      { "id": 5, "ip_type": "residential",
        "traffic_limit": 1073741824, "traffic_used": 70123456,
        "lists": [
          { "id": 3, "host": "residential.example.com", "port": 10000,
            "user": "0ba88f...", "pass": "3gUI5m...",
            "geo": { "country": "DE" }, "rotation": 3600, "ports": 1 }
        ] }
    ],
    "pending": []
  },
  "error": null
}
```

### GET proxies.export

Plain-text export of per-IP proxies (one per line). Residential lists are not included here — read them from proxies.list.

`GET https://proxy-chill.com/api/?action=proxies.export`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `format` | string | optional | host:port:user:pass (default) \| host:port \| user:pass@host:port |

Request:

```bash
curl "https://proxy-chill.com/api/?action=proxies.export&format=user:pass@host:port" \
  -H "Authorization: Bearer hp_live_xxxxxxxx"
```

Response `200 text/plain`:

```
91.124.31.97:50100:RFTySlwo:jFVOgW0oBu
82.47.253.143:50100:atiXJAlx:fgwCAJiKIb
```

### POST proxies.renew

Renew an assignment for one more period. Charged from balance.

`POST https://proxy-chill.com/api/?action=proxies.renew`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | int | required | assignment id from proxies.list |

Request:

```bash
curl -X POST "https://proxy-chill.com/api/?action=proxies.renew" \
  -H "Authorization: Bearer hp_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "id": 1 }'
```

Response `200 application/json`:

```json
{ "ok": true, "data": { "expires_at": "2026-08-15 00:00:00", "price": "1.10" }, "error": null }
```

Possible errors: `insufficient_funds`, `not_found`.

### POST proxies.autorenew

Enable or disable automatic renewal for an assignment.

`POST https://proxy-chill.com/api/?action=proxies.autorenew`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | int | required | assignment id |
| `on` | bool | required | true / false |

Request:

```bash
curl -X POST "https://proxy-chill.com/api/?action=proxies.autorenew" \
  -H "Authorization: Bearer hp_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "id": 1, "on": true }'
```

Response `200 application/json`:

```json
{ "ok": true, "data": { "auto_renew": true }, "error": null }
```

### POST proxies.check

Live connectivity check through a proxy. Returns latency in ms.

`POST https://proxy-chill.com/api/?action=proxies.check`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | int | required | assignment id |

Request:

```bash
curl -X POST "https://proxy-chill.com/api/?action=proxies.check" \
  -H "Authorization: Bearer hp_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "id": 1 }'
```

Response `200 application/json`:

```json
{ "ok": true, "data": { "alive": true, "latency_ms": 142 }, "error": null }
```

## Residential

### POST proxies.resident_configure

Add a new list to a residential package, targeting a geo and rotation. One package (GB) can hold many lists with different countries — all draw from the shared GB pool. Returns the new list credentials.

`POST https://proxy-chill.com/api/?action=proxies.resident_configure`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `assignment_id` | int | required | residential package id from proxies.list |
| `country` | string | required | alpha-2 / alpha-3 from catalog.resident_geo |
| `region` | string | optional | exact name from catalog.resident_geo |
| `city` | string | optional | exact city name |
| `isp` | string | optional | exact ISP name |
| `rotation` | int | required | 0 = new IP each request; 600/1800/3600 = sticky seconds |
| `ports` | int | required | 1-1000 endpoints |

Request:

```bash
curl -X POST "https://proxy-chill.com/api/?action=proxies.resident_configure" \
  -H "Authorization: Bearer hp_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "assignment_id": 5, "country": "DE", "rotation": 1800, "ports": 5 }'
```

Response `200 application/json`:

```json
{ "ok": true, "data": {
  "id": 7, "list_id": "20723612",
  "user": "0ba88f0330f3e10f", "pass": "3gUI5mNxyYFEh0Tr",
  "geo": { "country": "DE" }, "rotation": 1800, "ports": 5 }, "error": null }
```

Possible errors: `invalid_country`, `not_found`, `upstream_failed`.

### POST proxies.resident_list_delete

Delete a single residential list (not the package).

`POST https://proxy-chill.com/api/?action=proxies.resident_list_delete`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | int | required | list id (lists[].id from proxies.list) |

Request:

```bash
curl -X POST "https://proxy-chill.com/api/?action=proxies.resident_list_delete" \
  -H "Authorization: Bearer hp_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "id": 7 }'
```

Response `200 application/json`:

```json
{ "ok": true, "data": { "ok": true }, "error": null }
```

### POST proxies.traffic_topup

Buy more GB for a residential package. Charged from balance; quota increases instantly.

`POST https://proxy-chill.com/api/?action=proxies.traffic_topup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `assignment_id` | int | required | residential package id |
| `tarif_id` | int | required | GB package id from catalog.countries?type=resident |

Request:

```bash
curl -X POST "https://proxy-chill.com/api/?action=proxies.traffic_topup" \
  -H "Authorization: Bearer hp_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "assignment_id": 5, "tarif_id": 25208 }'
```

Response `200 application/json`:

```json
{ "ok": true, "data": { "traffic_limit": 2147483648, "added_gb": 1, "price": "1.80" }, "error": null }
```

Possible errors: `insufficient_funds`, `not_found`, `upstream_failed`.

### GET proxies.consumption

Traffic usage detail for a residential package: per-day series (30 days) and per-list breakdown, in bytes.

`GET https://proxy-chill.com/api/?action=proxies.consumption`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `assignment_id` | int | required | residential package id |

Request:

```bash
curl "https://proxy-chill.com/api/?action=proxies.consumption&assignment_id=5" \
  -H "Authorization: Bearer hp_live_xxxxxxxx"
```

Response `200 application/json`:

```json
{
  "ok": true,
  "data": {
    "daily": [ { "date": "2026-06-15", "bytes": 70123456 } ],
    "lists": [ { "id": 3, "geo": { "country": "DE" }, "bytes": 35061728 } ],
    "used_bytes": 70123456, "limit_bytes": 1073741824,
    "per_gb_price": 1.80, "total_cost": 0.13, "currency": "USD"
  },
  "error": null
}
```

## Billing

### GET billing.balance

Current account balance.

`GET https://proxy-chill.com/api/?action=billing.balance`

No parameters.

Request:

```bash
curl "https://proxy-chill.com/api/?action=billing.balance" \
  -H "Authorization: Bearer hp_live_xxxxxxxx"
```

Response `200 application/json`:

```json
{ "ok": true, "data": { "balance": "16.70", "currency": "USD" }, "error": null }
```

### GET billing.ledger

Balance movements (deposits, purchases, refunds). References are anonymized to the operation kind.

`GET https://proxy-chill.com/api/?action=billing.ledger`

No parameters.

Request:

```bash
curl "https://proxy-chill.com/api/?action=billing.ledger" \
  -H "Authorization: Bearer hp_live_xxxxxxxx"
```

Response `200 application/json`:

```json
{
  "ok": true,
  "data": { "ledger": [
    { "type": "purchase", "amount": "-1.80", "balance_after": "15.50",
      "ref": "order", "created_at": "2026-06-15 18:00:00" }
  ] },
  "error": null
}
```

## Error codes

| HTTP | error | Meaning |
|---|---|---|
| 401 | `unauthorized` | Missing or invalid API key. |
| 402 | `insufficient_funds` | Balance too low for the operation. |
| 403 | `forbidden` | Not allowed for this account. |
| 404 | `not_found` | Resource not found or not yours. |
| 422 | `invalid_input / rate_not_found / invalid_quantity` | Bad or missing parameters. |
| 422 | `type_unavailable` | This proxy type is not purchasable right now. |
| 429 | `rate_limited` | Too many requests, slow down. |
| 502 | `upstream_failed` | Provider error, retry shortly. |
| 500 | `server_error` | Unexpected error. |

---
Generated from the same source as https://proxy-chill.com/docs. Markdown: https://proxy-chill.com/docs.md · Index: https://proxy-chill.com/llms.txt