Reseller API

Buy proxies, manage orders, and check your account - all over REST. Keys are per-reseller and rate limited at 1000 req/hour.

Base URLhttps://catproxies.com/api/v1/public

How our reseller model works. You sell from the catalogue we assign to your account - not an open pool. Your /store lists exactly the packages an admin has enabled for you, each at the reseller price we set. Every order is paid from your prepaid balance. So your whole API surface is: read your store, buy a package, get credentials, manage and extend. There is nothing to provision or configure beyond that.

Quick start

# 1. See what you can sell (and your price)
curl -H "Authorization: Bearer cp_your_api_key_here" \
  https://catproxies.com/api/v1/public/store

# 2. Buy a package (paid from your balance)
curl -X POST https://catproxies.com/api/v1/public/order \
  -H "Authorization: Bearer cp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "packageId": "PACKAGE_ID_FROM_STORE" }'

# 3. Read the credentials back any time
curl -H "Authorization: Bearer cp_your_api_key_here" \
  https://catproxies.com/api/v1/public/order/ORDER_ID
# -> proxyCredentials: { username, password, hostip, port, ... }

Authentication

API Key Format

API keys are prefixed with cp_ followed by 64 hexadecimal characters.

cp_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2

Using Your API Key

Include your API key in the Authorization header using the Bearer scheme:

curl -X GET https://catproxies.com/api/v1/public/account \
  -H "Authorization: Bearer cp_your_api_key_here"

Rate Limits

1000 requests per hour per API key, reset at the top of each hour.

Mobile Targeting endpoints have a separate shared bucket: 60 requests per 10 minutes across all 4 mobile targeting sub-endpoints per API key. Cache responses where possible.

Check your current rate limit usage via the /account endpoint:

{
  "rateLimits": {
    "requestsPerHour": 1000,
    "requestsUsed": 47,
    "requestsRemaining": 953,
    "resetAt": "2025-11-29T21:00:00.000Z"
  }
}

Account

Store & Products

Orders

Targeting

Rotating Mobile - targeting endpoints

Need all countries, regions, cities, and ISPs at once? Download the full offline snapshot instead of hitting these endpoints repeatedly.

Download Snapshot

ISP Proxies - Quick Guide

ISP proxies use per-IP pricing. The resellerPrice in /store is the price per single IP. Your total = resellerPrice × quantity.

Complete ISP workflow

# 1. List ISP packages - note resellerPrice (per IP), minQty, maxQty, locations[]
GET /api/v1/public/store?proxyType=Isp

# 2. Buy 5 IPs in the US (countryId from locations[].id)
POST /api/v1/public/order
{ "packageId": "...", "ispData": { "quantity": 5, "countryId": 1 } }
# Charged: resellerPrice × 5

# 3. Get credentials
GET /api/v1/public/order/{orderId}

# 4. Check extend cost (resellerPrice × 5 for another 30 days)
GET /api/v1/public/order/{orderId}/extendOptions

# 5. Extend - packageId is optional for ISP
POST /api/v1/public/order/{orderId}/extend
{}
# Charged: resellerPrice × 5 again

Field	Notes
`ispData.quantity`	Defaults to 1 if omitted. Must be ≥ minQty and ≤ maxQty from the store product.
`ispData.countryId`	Defaults to the first location if omitted. Use locations[].id from the store product.
`ispData.authMethod / authIp`	Optional IP authentication. "ip" + a single IPv4 (authIp) whitelists that IP so the proxies work with no username/password. Fixed at purchase; GET /order/:id echoes it back as auth_mode + whitelist_ip.
`Extend packageId`	Optional for ISP - the API resolves the package from the order automatically. Pass {} as the body.
`extendType`	"days" for ISP (adds one full period). "bandwidth" for Residential/Mobile.
`Extend cost`	resellerPrice × order.package_ips (same quantity as the original purchase).

Premium Residential - Quick Guide

Premium Residential is a bandwidth product. Buy and extend it exactly like Standard Residential - no extra body parameters. Geo and session targeting are appended to the password, so a single set of credentials covers every country and session.

Connection endpoints

GET /order/:id returns proxyCredentials.hostip / port (the global HTTP gateway IP by default) plus an endpoints object with the ip:port for every region and SOCKS5. The host is always the IP from your order; pick the region closest to your target via the ports below.

Region	HTTP / HTTPS port	SOCKS5 port
Global	`7777`	`7780`
Europe	`7778`	`7781`
Asia	`7779`	`7782`

Targeting - append to the password

Keep the username as-is and append one or more flags to the password, in the order shown below.

Target	Flag	Value format
Country	`-cc-us`	ISO-2 code, lowercase
US state	`-state-us_california`	us_<state>, lowercase, _ for spaces
City	`-city-los_angeles`	lowercase, _ for spaces
US ZIP code	`-postalcode-10001`	5 digits
ASN / carrier	`-asn-7922`	ASN number only
Continent	`-cn-eu`	eu, na, sa, as, af, oc, an
Sticky session	`-sessid-ab12cd34-sesstime-1440`	any id + minutes (max 1440)

How the flags combine

Country + state + city + ZIP stack together - e.g. -cc-us-state-us_california-city-los_angeles. (state and postalcode are US-only and must follow -cc-us.)
City must belong to the state when you use both - e.g. don't pair us_california with a Texas city, or you get no match.
-asn- and -cn- are standalone - each replaces country/state/city targeting, so don't combine them with geo flags.
Add the sticky session flags last, on top of any of the above.

A given sessid keeps the same exit IP; sesstime is the hold time in minutes (max 1440). Omit the session flags for a fresh rotating IP on every request.

Rotating the password

POST /order/:id/reset-password issues a brand-new password for the order (see the Endpoints section). Because targeting flags are appended to the password, a reset changes the base password only - rebuild your proxy strings with the new base password and re-append the same flags. The old password stops working immediately and the new one takes 1 to 2 minutes to activate.

Country, state, city & ASN lists

You don't need to discover valid values by trial and error - download the full reference. It contains every supported country, US state, city token (worldwide + per US state), continent code and carrier ASN, all in the exact token format the flags expect.

Premium Residential targeting reference (JSON)

141 countries, 50 US states, ~15,000 city tokens, carrier ASNs.

Download Reference

Tip: any city in the world can be requested, but because the residential pool is dynamic, very small cities may fall back to the wider region. Prefer larger cities, or pair a city with its state for tighter results.

Example

# Credentials from GET /order/:id  (HOST = your order's hostip - a plain
# unbranded IP; regional/SOCKS5 endpoints are in the endpoints object)
#   username: hftjvbtwgxxxceb205604
#   password: ngnstzylne
#   host:     HOST   port: 7777

# Rotating IP in the US (new IP per request)
curl -x HOST:7777 \
  -U "hftjvbtwgxxxceb205604:ngnstzylne-cc-us" \
  https://ipinfo.io

# Sticky IP in New York City (state + city) for up to 24h
curl -x HOST:7777 \
  -U "hftjvbtwgxxxceb205604:ngnstzylne-cc-us-state-us_new_york-city-new_york-sessid-ab12cd34-sesstime-1440" \
  https://ipinfo.io

Datacenter - Quick Guide

Datacenter plans (proxyType: DatacenterP) give you a list of dedicated IPs plus a shared bandwidth pool for a fixed duration - e.g. 100 IPs / 250 GB / 30 days. At purchase you decide how the IPs split across US, CA, DE, GB and NL. Every IP is its own proxy; they all share the same username:password.

Complete Datacenter workflow

# 1. List Datacenter packages - note ips (IP count), bandwidth (GB pool), days
GET /api/v1/public/store?proxyType=DatacenterP

# 2. Check live IP stock per country before allocating
GET /api/v1/public/datacenterp-countries

# 3. Buy - country_proxies must total EXACTLY the package IP count
POST /api/v1/public/order
{
  "packageId": "...",
  "datacenterPData": {
    "country_proxies": { "US": 60, "DE": 20, "GB": 20 },
    "high_concurrency": false,
    "high_priority": false,
    "whitelisted_ips": false
  }
}

# 4. Read the IP list back (ip_list is refreshed live on every call)
GET /api/v1/public/order/{orderId}

# 5. Optional - whitelist your server IP for credential-less access
PATCH /api/v1/public/order/{orderId}/whitelist
{ "ip": "203.0.113.42" }

What GET /order/:id returns for Datacenter

{
  "payload": {
    "order": {
      "id": "c5c7c6b5-e488-420c-b436-e90e86031751",
      "package_title": "Datacenter Proxies - 1 Month - 100 IPs - 250GB",
      "status": "CONFIRMED",
      "proxyCredentials": {
        "username": "dcuser482913",
        "password": "dcpass91827",
        "available_bandwidth": 237.6,
        "used_bandwidth": 12.4,
        "bandwidth_left": 237.6,
        "expired_at": "2026-08-04T10:00:00.000Z",
        "port_http": "1338",
        "port_socks5": "1339",
        "whitelist_ip": [],
        "ip_list": [
          {
            "iso2": "US",
            "name": "United States",
            "cities": [
              { "ips": ["195.63.2.251", "195.63.11.195", "..."] }
            ],
            "count_ips": 60
          },
          { "iso2": "DE", "name": "Germany", "cities": ["..."], "count_ips": 20 }
        ],
        "country_list": {
          "countries": { "US": 60, "DE": 20, "GB": 20 },
          "proxyNumber": 100
        }
      }
    }
  }
}

Using the proxies

# Every IP in ip_list is a dedicated proxy. Same credentials on all of them.
#   HTTP:   <ip>:1338:<username>:<password>
#   SOCKS5: <ip>:1339:<username>:<password>

curl -x 195.63.2.251:1338 -U "dcuser482913:dcpass91827" https://ipinfo.io

# After whitelisting your server IP, credentials are optional:
curl -x 195.63.2.251:1338 https://ipinfo.io

Field	Notes
`country_proxies`	Must total exactly the package ips value. Allowed countries: US, CA, DE, GB, NL. Check /datacenterp-countries for live stock first - over-allocating a country fails the purchase.
`Addons`	high_concurrency (more parallel connections), high_priority (priority routing), whitelisted_ips (3 whitelist slots instead of 1). All three are booleans and must be present in datacenterPData.
`Bandwidth`	One shared GB pool across all IPs in the plan. Track it via bandwidth_left on GET /order/:id (refreshed live).
`ip_list`	Grouped by country then city. Flatten cities[].ips to get every proxy IP. Refreshed live on each GET /order/:id.
`Authentication`	username:password on any IP, or whitelist your server IP (PATCH /order/:id/whitelist) and connect without credentials.
`HTTP 429`	Returned by the proxy when you hit the plan’s concurrent-connection limit - lower parallelism, or buy with the high_concurrency addon for a higher limit. 407 = wrong credentials / non-whitelisted IP.
`Extending`	Not supported - /order/:id/extendOptions returns an empty list. Buy a new package when the plan expires or the bandwidth pool runs out.

IPv6 - Quick Guide

IPv6 plans (proxyType: Ipv6p) rotate through a huge pool of IPv6 addresses - a fresh exit IP on every request by default. Two plan flavors in /store: bandwidth plans (GB pool, no speed cap) and unlimited plans (bandwidth "0" = no GB cap, speed capped at the speed value in Mbps). Purchase needs only the packageId - no extra body fields.

Connection gateways

IPv6 is served through country gateways - the exit country is chosen by which gateway you connect to, and the same username:password works on all of them. Locations: Worldwide, United States, Germany, United Kingdom, Netherlands. Ports: 1338 HTTP/HTTPS, 1339 SOCKS5.

The gateway addresses are returned per order by GET /order/:id - unbranded plain IPs, safe to pass straight to your own customers:

GET /api/v1/public/order/{orderId}
{
  "proxyCredentials": {
    "username": "...",
    "password": "...",
    "hostip": "<worldwide gateway>",   // default gateway
    "port": "1338",
    "ports": { "http": "1338", "socks5": "1339" },
    "endpoints": {                     // one gateway IP per country
      "ww": "...", "us": "...", "de": "...", "gb": "...", "nl": "..."
    },
    "usage": { "bandwidth_left": 87.4, ... }  // null on unlimited plans
  }
}

Sessions - append to the username

Default is rotating: a new IPv6 address on every request, nothing to configure. For a sticky session (keep the same exit IP), append -session-<id>-ttl-<minutes> to the username (password unchanged). The session id must be a number between 0 and 999999; ttl is 1-120 minutes. Use different session ids to hold several sticky IPs in parallel.

# Credentials + gateway IPs from GET /order/:id (same login on all gateways)
#   username: ipv6user291   password: v6pass817
#   endpoints.us -> US_GATEWAY,  endpoints.de -> DE_GATEWAY, ...

# Rotating - fresh IPv6 address on every request (US gateway)
curl -x US_GATEWAY:1338 -U "ipv6user291:v6pass817" https://api6.ipify.org

# Sticky - hold the same IPv6 exit for 60 minutes (Germany gateway)
curl -x DE_GATEWAY:1338 \
  -U "ipv6user291-session-483920-ttl-60:v6pass817" \
  https://api6.ipify.org

# SOCKS5
curl --socks5 US_GATEWAY:1339 -U "ipv6user291:v6pass817" https://api6.ipify.org

The target site must support IPv6

Exits are IPv6-only, so the destination needs an AAAA (IPv6) DNS record. Major platforms (Google, YouTube, Facebook, Instagram, TikTok) support it; many smaller sites do not and will be unreachable. Check your target domain first at ready.chair6.net, then confirm the proxy works end-to-end by requesting https://api6.ipify.org through it. An unreachable IPv6-less target typically surfaces as a 503 from the proxy.

Field	Notes
`Bandwidth plans`	bandwidth > 0 in /store. Track usage via bandwidth_left / usage on GET /order/:id (refreshed live).
`Unlimited plans`	bandwidth "0" + speed cap in Mbps. usage is null in /order/:id - only expired_at limits the plan.
`Sticky session`	-session-<id>-ttl-<minutes> appended to the username. id numeric 0-999999, ttl max 120 minutes; omit both for rotating.
`Authentication`	username:password only. IP whitelisting is currently unavailable for IPv6 plans.
`Extending`	Not supported - /order/:id/extendOptions returns an empty list. Buy a new package instead.

Proxy response codes

Code	Meaning
`407`	Wrong or missing proxy credentials.
`429`	Concurrent-connection / thread limit reached - lower parallelism or retry with backoff.
`503`	Could not reach the target - DNS failed or the site has no IPv6 (AAAA) support.
`504`	The target site did not respond in time.

Errors

Status Code	Description
`200`	Success - Request completed successfully
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Not a reseller account or access denied
`404`	Not Found - Resource doesn't exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Something went wrong

Error Response Format

{
  "type": "error",
  "message": "Insufficient balance. Required: $2.50, Available: $1.00",
  "status": 400
}

Ready to Get Started?

Create your first API key and start integrating CatProxies into your application today.

Manage API Keys Contact Support