> ## Documentation Index
> Fetch the complete documentation index at: https://docs.catproxy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Баланс и тарифы

> Проверяйте баланс аккаунта, просматривайте историю транзакций и получайте доступные тарифные планы. Необходимое разрешение: balance:read.

<Info>
  Полные схемы запросов и ответов, а также возможность тестирования эндпоинтов доступны в [Swagger UI](https://api.catproxy.io/swagger/index.html).
</Info>

***

## Получить баланс

Возвращает текущий доступный баланс аккаунта аутентифицированного пользователя в USD.

```http theme={null}
GET /v1/user/balance
```

**Разрешение:** `balance:read`

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.catproxy.io/v1/user/balance \
    -H "X-API-Key: cat_YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  r = requests.get(
      "https://api.catproxy.io/v1/user/balance",
      headers={"X-API-Key": "cat_YOUR_API_KEY"}
  )
  print(r.json())
  ```
</CodeGroup>

**Пример ответа**

```json theme={null}
{
  "result": true,
  "data": {
    "funds_available": 42.50
  }
}
```

***

## Получить историю баланса

Возвращает постраничный список транзакций баланса (пополнения и списания) за указанный период.

```http theme={null}
GET /v1/user/balance-history
```

**Параметры запроса**

| Параметр    | Тип     | Обязательный | Описание                                                       |
| :---------- | :------ | :----------- | :------------------------------------------------------------- |
| `date_from` | string  | Да           | Начальная дата в формате `YYYY-MM-DD`                          |
| `date_to`   | string  | Да           | Конечная дата в формате `YYYY-MM-DD`                           |
| `limit`     | integer | Нет          | Элементов на страницу. По умолчанию: `100`                     |
| `page`      | integer | Нет          | Номер страницы начиная с `0`. По умолчанию: `0`                |
| `order`     | string  | Нет          | Направление сортировки: `asc` или `desc`. По умолчанию: `desc` |

**Разрешение:** `balance:read`

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.catproxy.io/v1/user/balance-history?date_from=2026-01-01&date_to=2026-12-31" \
    -H "X-API-Key: cat_YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  r = requests.get(
      "https://api.catproxy.io/v1/user/balance-history",
      headers={"X-API-Key": "cat_YOUR_API_KEY"},
      params={"date_from": "2026-01-01", "date_to": "2026-12-31", "limit": 50}
  )
  print(r.json())
  ```
</CodeGroup>

**Пример ответа**

```json theme={null}
{
  "result": true,
  "data": [
    {
      "id": 1234567,
      "tx_id": 1234567,
      "type": "Top-up",
      "source": "payment",
      "amount": 100.00,
      "currency": "USD",
      "description": "Manual Top-up via Visa ****4242",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ]
}
```

***

## Получить тарифные планы

Возвращает список доступных тарифных планов. Используйте `id` из ответа в качестве `tariff_id` при создании прокси.

```http theme={null}
GET /v1/plans
```

**Параметры запроса**

| Параметр     | Тип     | Обязательный | Описание                              |
| :----------- | :------ | :----------- | :------------------------------------ |
| `proxy_type` | string  | Да           | `residential` или `mobile`            |
| `enabled`    | boolean | Нет          | Показывать только активные планы      |
| `popular`    | boolean | Нет          | Показывать только рекомендуемые планы |

**Разрешение:** `proxies:read` или `proxies:write`

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.catproxy.io/v1/plans?proxy_type=residential" \
    -H "X-API-Key: cat_YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  r = requests.get(
      "https://api.catproxy.io/v1/plans",
      headers={"X-API-Key": "cat_YOUR_API_KEY"},
      params={"proxy_type": "residential"}
  )
  print(r.json())
  ```
</CodeGroup>

**Пример ответа**

```json theme={null}
{
  "result": true,
  "data": [
    {
      "id": 1,
      "title": "Residential 1GB",
      "description": "Pay-as-you-go residential proxy traffic",
      "amount": 4.50,
      "currency": "USD",
      "traffic_available": 1000000000,
      "traffic_type": "package"
    }
  ]
}
```