Developers

API reference

A simple REST API to automate everything in the dashboard — buy and top up packages, manage static IPs, and generate proxy connection strings at scale.

Introduction

The proxy.sb API lets you automate everything you can do in the dashboard: buy traffic, unlimited and static packages, top them up, list usage, and generate ready-to-use proxy connection strings. It is built for resellers and integrations.

Base URL:

https://proxy.sb/api/v1

All responses are JSON wrapped in a { "data": ... } envelope; errors use { "error": { "code", "message" } }.

Authentication

Create an API key in your dashboard (Settings → API keys). The full key is shown once at creation. Send it as a Bearer token on every request:

Authorization: Bearer pfx_live_xxxxxxxxxxxxxxxxxxxxxxxx

Keep keys secret. Revoke a leaked key from the dashboard at any time.

Rate limits

Requests are limited per API key (roughly 600 requests/minute with short bursts). Exceeding it returns 429 rate_limited. Generating proxies is free and never calls the upstream provider, so prefer generating many lines in one call over polling.

Errors

Code	HTTP	Meaning
unauthorized	401	Missing or malformed Authorization header.
invalid_key	401	API key is unknown or revoked.
account_suspended	403	Your account is suspended.
rate_limited	429	Too many requests — slow down.
validation_failed	400	Request body/params failed validation.
invalid_product	400	Unknown or wrong-kind product.
insufficient_funds	402	Balance too low for this purchase.
no_traffic	402	Package has no traffic left — top up first.
package_not_active	409	Package is not active.
not_found	404	Package/resource not found.

Account

GET/account

Get account

Returns your username, email and current balance (in USD cents).

Example request

curl https://proxy.sb/api/v1/account \
  -H "Authorization: Bearer pfx_live_..."

Example response

{
  "data": {
    "username": "reseller1",
    "email": "me@example.com",
    "balanceUsdCents": 124500
  }
}

GET/usage

Get bandwidth usage

Aggregated traffic balances per proxy type. Figures are synced from the upstream provider every ~10 minutes.

Example request

curl https://proxy.sb/api/v1/usage \
  -H "Authorization: Bearer pfx_live_..."

Example response

{
  "data": {
    "bandwidth": [
      { "type": "residential", "gbRemaining": 8.4, "gbPurchasedTotal": 10, "gbUsedTotal": 1.6 },
      { "type": "mobile", "gbRemaining": 0, "gbPurchasedTotal": 0, "gbUsedTotal": 0 },
      { "type": "datacenter", "gbRemaining": 0, "gbPurchasedTotal": 0, "gbUsedTotal": 0 }
    ]
  }
}

Products

GET/products

List products

All active products you can buy. Use the product id when purchasing. priceCents is per GB (traffic), per day (unlimited) or per IP / 30 days (static).

Example request

curl https://proxy.sb/api/v1/products \
  -H "Authorization: Bearer pfx_live_..."

Example response

{
  "data": {
    "products": [
      {
        "id": "residential",
        "kind": "traffic",
        "name": "Residential",
        "description": "Traffic package with editable routing settings.",
        "priceCents": 150,
        "billingUnit": "gb",
        "defaultTtlMinutes": 5,
        "defaultProtocol": "http"
      }
    ]
  }
}

Locations

GET/locations/countries

List countries

Countries available for a product (or for an owned package). Served from cache.

Query parameters

productId	string	Product id, e.g. residential. Defaults to residential.
packageId	string	Optional: use an owned package's provider type/gate instead of productId.

Example request

curl "https://proxy.sb/api/v1/locations/countries?productId=residential" \
  -H "Authorization: Bearer pfx_live_..."

Example response

{
  "data": {
    "countries": [
      { "code": "BE", "name": "Belgium" },
      { "code": "US", "name": "United States" }
    ]
  }
}

GET/locations/regions

List regions

Regions for a country + product. Premium/mobile/datacenter only; basic residential returns an empty list (region stays random).

Query parameters

country*	string	Two-letter country code, e.g. BE.
productId	string	Product id. Defaults to residential.
packageId	string	Optional owned package id.

Example request

curl "https://proxy.sb/api/v1/locations/regions?productId=premium_residential&country=BE" \
  -H "Authorization: Bearer pfx_live_..."

Example response

{
  "data": {
    "regions": [
      { "code": "be-flanders", "name": "Flanders", "availability": "medium" }
    ]
  }
}

Packages

GET/packages

List packages

All your rotating, unlimited and static packages.

Example request

curl https://proxy.sb/api/v1/packages \
  -H "Authorization: Bearer pfx_live_..."

Example response

{
  "data": {
    "packages": [
      {
        "id": "pkg_a1b2c3d4e5",
        "productId": "residential",
        "productName": "Residential",
        "kind": "traffic",
        "country": null,
        "region": null,
        "ttlMinutes": 5,
        "protocol": "http",
        "trafficLimitMb": 10000,
        "trafficUsedMb": 1600,
        "trafficRemainingMb": 8400,
        "status": "active",
        "expiresAt": null,
        "createdAt": "2026-05-29T18:00:00.000Z"
      }
    ]
  }
}

GET/packages/{id}

Get package

A single package by its id.

Example request

curl https://proxy.sb/api/v1/packages/pkg_a1b2c3d4e5 \
  -H "Authorization: Bearer pfx_live_..."

Example response

{ "data": { "package": { "id": "pkg_a1b2c3d4e5", "status": "active", "trafficRemainingMb": 8400 } } }

POST/packages

Buy a package

Buy a rotating (traffic) package by GB, or an unlimited package by days. Charges your balance.

Body fields

productId*	string	Product id from /products (must not be a static product).
gb	number	Traffic products: one of 1, 5, 10, 100, 500, 1000.
days	number	Unlimited products: number of days (1-365).

Example request

curl -X POST https://proxy.sb/api/v1/packages \
  -H "Authorization: Bearer pfx_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "productId": "residential", "gb": 10 }'

Example response

{
  "data": {
    "orderId": "ord_...",
    "packageId": "pkg_a1b2c3d4e5",
    "transactionId": "tx_...",
    "balanceUsdCents": 123000,
    "gbAdded": 10,
    "product": "residential"
  }
}

POST/packages/{id}/topup

Top up a package

Add more traffic (GB) to an existing rotating/unlimited package. Charges your balance.

Body fields

gb*

number

One of 1, 5, 10, 100, 500, 1000.

Example request

curl -X POST https://proxy.sb/api/v1/packages/pkg_a1b2c3d4e5/topup \
  -H "Authorization: Bearer pfx_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "gb": 5 }'

Example response

{ "data": { "balanceUsdCents": 122250, "transactionId": "tx_...", "gbAdded": 5 } }

POST/packages/{id}/proxies

Generate proxies

Build ready-to-use connection strings for a package. This is free and does not call the upstream provider — generate as many as you need. Geo and rotation are encoded in the credentials.

Body fields

count	number	How many lines to return (1-10000). Default 1.
format	string	user_pass_host_port \| host_port_user_pass \| host_port_at_user_pass \| protocol_user_pass_host_port.
protocol	string	http or socks5. Default http.
country	string	Two-letter country code, or omit for random.
region	string	Region code from /locations/regions (premium/mobile/datacenter only).
ttlMinutes	number	Rotation: -1 every request, 0 sticky, or 1/2/5/10 minutes.
sessionMode	string	Optional: rotate_each_request \| sticky \| rotate_lifetime (alternative to ttlMinutes).

Example request

curl -X POST https://proxy.sb/api/v1/packages/pkg_a1b2c3d4e5/proxies \
  -H "Authorization: Bearer pfx_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "count": 3, "protocol": "http", "country": "US", "ttlMinutes": 5, "format": "protocol_user_pass_host_port" }'

Example response

{
  "data": {
    "host": "g3.proxy.sb",
    "port": 8080,
    "protocol": "http",
    "username": "PM4pPudEUJUe",
    "password": "zHP2t26EaLha9UV",
    "count": 3,
    "format": "protocol_user_pass_host_port",
    "lines": [
      "http://PM4pPudEUJUe-country-US-session-785195-ttl-300:zHP2t26EaLha9UV@g3.proxy.sb:8080"
    ],
    "sample": "http://PM4pPudEUJUe-country-US-session-785195-ttl-300:zHP2t26EaLha9UV@g3.proxy.sb:8080",
    "package": { "id": "pkg_a1b2c3d4e5", "productName": "Residential", "protocol": "http" }
  }
}

Static IPs

GET/static

List static IPs

Your dedicated (static) IPs with credentials.

Example request

curl https://proxy.sb/api/v1/static \
  -H "Authorization: Bearer pfx_live_..."

Example response

{
  "data": {
    "items": [
      {
        "id": 12,
        "ip": "31.57.176.192",
        "countryCode": "US",
        "proxyType": "datacenter",
        "host": "31.57.176.192",
        "port": 16353,
        "username": "user282335",
        "password": "fmzerl",
        "status": "active",
        "expiresAt": "2026-06-29T00:00:00.000Z",
        "createdAt": "2026-05-29T18:00:00.000Z"
      }
    ]
  }
}

POST/static

Buy static IPs

Buy one or more dedicated IPs in a country. Charges your balance.

Body fields

productId*	string	A static product id from /products (e.g. static_datacenter).
countryCode*	string	Two-letter country code.
quantity*	number	How many IPs (1-100).

Example request

curl -X POST https://proxy.sb/api/v1/static \
  -H "Authorization: Bearer pfx_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "productId": "static_datacenter", "countryCode": "US", "quantity": 2 }'

Example response

{
  "data": {
    "orderId": "ord_...",
    "transactionId": "tx_...",
    "balanceUsdCents": 121650,
    "quantity": 2,
    "status": "active"
  }
}