Catproxy Developer Documentation

See the Swagger UI for live request/response schemas and to try endpoints directly in your browser.

Get balance

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

GET /v1/user/balance

Scope: balance:read

curl https://api.catproxy.io/v1/user/balance \
  -H "X-API-Key: cat_YOUR_API_KEY"

import requests

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

Example response

{
  "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.

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

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"

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())

Example response

{
  "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.

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

curl "https://api.catproxy.io/v1/plans?proxy_type=residential" \
  -H "X-API-Key: cat_YOUR_API_KEY"

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())

Example response

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

​Get balance

​Get balance history

​Get plans

Get balance

Get balance history

Get plans