ProxyRequest Python SDK

Official synchronous and asynchronous Python client for the ProxyRequest public API. It covers 81 supported operations in the current contract: users, orders, proxy generation, analytics, invoices, packages, locations, webhooks, API keys, Telegram integration, and more.

See analytics formats and compatibility for Unix timestamps, reporting windows, and feed identifiers.

What is ProxyRequest?

ProxyRequest is a white-label proxy platform for operators and resellers that already have upstream proxy supply. It provides the product and control layer needed to turn that supply into a customer-facing service:

• managed HTTP, HTTPS, SOCKS5, and SOCKS5h gateways;
• packages, users, orders, proxy credentials, limits, and byte accounting;
• geographic and network targeting, sticky sessions, and multi-provider routing;
• customer and reseller dashboards, invoices, coupons, and payment flows;
• analytics, signed webhooks, API keys, and operational reporting.

You can use the complete managed backend and customer dashboard, or keep your own frontend, identity, and billing while ProxyRequest handles provisioning, routing, accounting, and analytics headlessly. You retain your brand, pricing, customer relationships, and upstream provider contracts.

ProxyRequest is not an upstream bandwidth plan. Provider traffic and contracts remain separate from the platform subscription. See the platform overview for the complete operating boundary.

How this SDK fits

The REST API is the control plane around proxy traffic. This SDK provisions resources and reads their state; customer proxy requests go to the managed gateway servers instead of passing through the SDK or REST API.

Your Python backend ── HTTPS/JSON ──> ProxyRequest API
Customer traffic ───── HTTP/SOCKS ──> Managed gateways ──> Destination

Keep the credentials for those paths separate: API keys belong only in trusted backend code, while generated proxy usernames and passwords are supplied only to the customer or workload that connects to a gateway.

The most important resource relationships are:

Customer purchase:
Package -> Invoice -> Paid invoice -> Order / data ledger -> Proxy credentials

Reseller provisioning:
Eligible root order -> Sub-user + child allocation -> Proxy credentials

Invoices describe commercial state. Orders and data ledgers describe service entitlement. Creating an invoice or returning from checkout is therefore not proof that proxy access is active.

Choose an integration path

See purchase a package with an invoice and provision a reseller customer for complete Python examples.

Installation

python -m pip install proxyrequest-sdk

Python 3.11 or newer is required. The package uses httpx and includes both sync and async clients.

Quick start

import os

from proxyrequest_sdk import Client
from proxyrequest_sdk.models import UserCreateRequest

with Client.with_api_key(os.environ["PROXYREQUEST_API_KEY"]) as client:
    profile = client.profile.get()
    user = client.users.create(
        body=UserCreateRequest(
            username="customer-reference",
            password=os.urandom(32).hex(),
        )
    )
    print(profile.username, user.id)

Static API keys are sent as Authorization: Static YOUR_API_KEY. Never expose them to browser code.

The asynchronous API has the same resource and method names:

import os

from proxyrequest_sdk import AsyncClient


async def list_users() -> None:
    async with AsyncClient.with_api_key(os.environ["PROXYREQUEST_API_KEY"]) as client:
        page = await client.users.list(limit=100)
        for user in page.results:
            print(user.username)

Resource API

Client and AsyncClient expose 18 API groups. The pinned public schema contains 83 operations; disabled sessions_list and sessions_destroy operations are intentionally excluded. Sticky session options in proxy generation remain supported.

See backend compatibility and MFA for updated login examples and response-model migration notes.

client.authorization
client.users
client.profile
client.orders
client.providers
client.proxies
client.analytics
client.invoices
client.coupons
client.rewards
client.affiliates
client.packages
client.locations
client.api_keys
client.webhooks
client.telegram
client.settings
client.news

All operation parameters and return values are typed. Request and response models live in proxyrequest_sdk.models, use snake_case attributes, and expose to_dict() / from_dict() helpers. IDs follow their OpenAPI type (UUID or opaque str). Provider balance byte amounts are decimal strings; other byte amounts are Python integers.

See the generated API resource reference and model reference.

Automatic retries and optimistic concurrency

The SDK automatically protects supported writes during up to three total attempts after a network failure, or after 409 Conflict with a numeric Retry-After of at most five seconds. Other HTTP errors are returned immediately. This protection applies inside one running call. If the process stops before saving the result, inspect the affected resource before submitting another write:

response = client.users.create_with_response(
    body=UserCreateRequest(username="customer-reference", password="secret"),
)

print(response.data.id, response.etag)

Every generated method has a _with_response variant exposing status_code, headers, and etag.

Operations that declare If-Match accept the latest strong ETag. A stale value raises ApiError with ErrorKind.PRECONDITION and exposes the current server value as current_etag. ETags are explicit response metadata and are not cached by the SDK.

Pagination

List endpoints return their typed OpenAPI page. Use paginate() to follow all pages lazily:

with Client.with_api_key(os.environ["PROXYREQUEST_API_KEY"]) as client:
    for user in client.paginate(client.users.list, limit=100):
        print(user.username)

The asynchronous variant is also lazy:

async with AsyncClient.with_api_key(os.environ["PROXYREQUEST_API_KEY"]) as client:
    async for user in client.paginate(client.users.list, limit=100):
        print(user.username)

Errors

Every documented and undocumented HTTP failure is normalized to ApiError. Network and decoding problems use the same contract:

from proxyrequest_sdk import ApiError, ErrorKind

try:
    client.profile.get()
except ApiError as error:
    if error.kind is ErrorKind.AUTHENTICATION:
        # Replace the invalid API key or bearer token.
        pass
    print(error.status_code, error.request_id, error.field_errors)

Supported writes receive bounded automatic retries for transient failures. JWTs are never refreshed automatically; call client.authorization.refresh(...) explicitly when your application owns a token pair.

Configuration and custom deployments

import httpx

client = Client.with_api_key(
    os.environ["PROXYREQUEST_API_KEY"],
    base_url="https://customer-api.example/api/v1",
    language="uk",
    timeout=20,
    connect_timeout=5,
)

An existing httpx.Client or httpx.AsyncClient can be supplied through http_client. It must have the same base_url; the SDK applies its auth, language, and user-agent headers but leaves closing the external client to the caller. The request() method is an authenticated escape hatch for endpoints introduced before the next SDK release.

Invoice downloads

download = client.download_invoice_pdf(invoice_id)
path = download.save(f"./{download.filename}")
print(path, download.content_type)

save() does not overwrite an existing file unless overwrite=True is passed.

Webhook verification

Verify the exact raw body before decoding it:

from proxyrequest_sdk import WebhookVerifier

payload = WebhookVerifier.decode_verified_json(
    raw_body,
    request.headers.get("X-Signature", ""),
    os.environ["PROXYREQUEST_WEBHOOK_SECRET"],
)

Deliveries use standard padded Base64 HMAC-SHA256 over the raw body, without a signed timestamp. Verification accepts only this current format. It authenticates the body, but does not prevent replay: deduplicate usage events in your application. These helpers require SDK 2.0.0 or newer; version 1.0.0 does not support the current delivery format.

Platform documentation

• Platform documentation: capabilities, responsibility boundaries, deployment modes, and starting points.
• Integration overview: control-plane boundary and common API flows.
• API fundamentals and API resource map: authentication, errors, pagination, and resource relationships.
• Billing and growth: invoices, payment links, coupons, and entitlement reconciliation.
• Reseller workflow and users and data: sub-user provisioning and safe byte allocation.
• Catalog and proxy generation: packages, orders, locations, and credentials.
• Webhooks and usage accounting: event handling, root ledgers, child limits, and reconciliation.
• API reference: exact endpoints, request schemas, responses, and examples.

Development

uv sync --all-groups
make quality
make generate-check
make build

The vendored schema is pinned in openapi/source.json. Run make sync-openapi SOURCE=/path/to/openapi.yml, followed by make generate, to update it. Generation is pinned and CI rejects uncommitted contract changes.

License

MIT

Reset remaining data (SDK 2.1.0+)

from proxyrequest_sdk.models import ResetDataRequest

order = client.users.reset_data(
    id=user_id,
    body=ResetDataRequest(package_id=package_id),
    idempotency_key=reset_operation_id,
)

Send only package_id, without data. A system administrator can reset any user; other accounts can reset only their direct children. The server atomically clears positive, zero, or negative remaining data for a finite package and returns the updated order. Unlimited packages are rejected. Root orders lose their remaining ledger balances; child orders lose their remaining quota without changing the parent pool. Usage history and invoices are preserved.

Persist one operation ID and reuse it when retrying the same reset, including after a process restart. This prevents a repeated request from clearing a later top-up. Use subtraction when an explicit amount should be removed from a child quota. The backend must support the reset endpoint before calling it.

Version 2.1 retains legacy user and invoice models from 2.0 for compatibility with older deployments. These compatibility types do not change the current public API contract.

Provider data balances

Available since 4.1.0. Authenticate with a superuser JWT or an API key owned by an active superuser.

page = client.providers.list_data_balances(limit=20)
for balance in page.results:
    print(balance.provider_name, balance.remaining_bytes, balance.history)

Provider byte amounts are exact decimal strings, including history entries; calculated usage and remaining amounts can be null. The response includes observation and calculation times, freshness, errors, and recent checkpoint history. History is limited by the server's PROVIDER_DATA_BALANCE_HISTORY_LIMIT setting (default 10). Standard pagination applies to providers.

Country, region, and city methods also support include_asns. Set it to true to populate nested ASN arrays; omitted or false uses the API's empty-array default.