> ## 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 & Plans

> Check your account balance, view transaction history, and retrieve available tariff plans. Required scope: balance:read.

<Info>
  See the [Swagger UI](https://api.catproxy.io/swagger/index.html) for live request/response schemas and to try endpoints directly in your browser.
</Info>

***

## Get balance

Returns the current spendable balance of the authenticated user's account in USD.

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

**Scope:** `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>

**Example response**

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

***

## Get balance history

Returns a paginated list of balance transactions (top-ups and charges) for a given date range.

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

**Query parameters**

| Parameter   | Type    | Required | Description                                      |
| :---------- | :------ | :------- | :----------------------------------------------- |
| `date_from` | string  | Yes      | Start date in `YYYY-MM-DD` format                |
| `date_to`   | string  | Yes      | End date in `YYYY-MM-DD` format                  |
| `limit`     | integer | No       | Items per page. Default: `100`                   |
| `page`      | integer | No       | Page number starting from `0`. Default: `0`      |
| `order`     | string  | No       | Sort direction: `asc` or `desc`. Default: `desc` |

**Scope:** `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>

**Example response**

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

***

## Get plans

Returns the list of available tariff plans. Use the `id` from this response as `tariff_id` when creating a proxy.

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

**Query parameters**

| Parameter    | Type    | Required | Description                   |
| :----------- | :------ | :------- | :---------------------------- |
| `proxy_type` | string  | Yes      | `residential` or `mobile`     |
| `enabled`    | boolean | No       | Filter to only active plans   |
| `popular`    | boolean | No       | Filter to only featured plans |

**Scope:** `proxies:read` or `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>

**Example response**

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