This release is a pre-release and may not be stable for production use.
proxy6-sdk
Unofficial — this project is a community-built client for Proxy6.net and is not affiliated with, endorsed by, or supported by Proxy6.net. All trademarks belong to their respective owners.
A typed Python SDK for the Proxy6.net API.
Covers all nine documented endpoints — getprice, getcount, getcountry,
getproxy, setdescr, buy, prolong, delete, check — plus the
keyless account call. Responses are parsed into dataclasses with proper
types (datetime, int, bool, enums) instead of the raw strings the API
returns.
Status: alpha (
0.1.0a1). The public API may change before0.1.0. See CHANGELOG.md for what shipped.
Install
uv add proxy6-sdk
# or
pip install proxy6-sdk
The distribution name is proxy6-sdk; the import name is proxy6:
from proxy6 import Proxy6Client
Requires Python 3.13+.
Quick start
from proxy6 import Proxy6Client, Version
# Pass the key explicitly...
with Proxy6Client(api_key="YOUR_KEY") as client:
...
# ...or set PROXY6_API_KEY in the environment and omit it.
with Proxy6Client() as client:
info = client.account()
print(f"Balance: {info.balance} {info.currency}")
# How much for 10 Russian IPv6 proxies for 30 days?
quote = client.get_price(count=10, period=30, version=Version.IPV6)
print(quote.price, quote.price_single)
# Buy them
order = client.buy(
count=10,
period=30,
country="ru",
version=Version.IPV6,
descr="scraper-pool",
)
for proxy in order.proxies:
print(proxy.auth_url()) # http://user:pass@host:port
API surface
| Method | Purpose |
|---|---|
account() |
Balance / currency (calls API with no method) |
get_price(count?, period?, version?) |
Single-quote or full price table |
get_count(country, version?) |
Available stock for a country |
get_country(version) |
List of ISO2 codes for a version |
get_proxy(state?, descr?, page?, limit?) |
List your proxies |
set_descr(new, old?, ids?) |
Rename the technical comment |
buy(count, period, country, version, descr?, ...) |
Purchase proxies |
prolong(period, ids) |
Extend existing proxies |
delete(ids?, descr?) |
Delete by id or by comment |
check(ids?, proxy?) |
Liveness check via id or ip:port:user:pass |
proxies(refresh?) |
Cached view of the full pool (filter locally) |
invalidate_proxy_cache() |
Drop the pool cache |
select_proxy(country?, version?, active?, ...) |
Pick one proxy from the pool, raises if nothing matches |
requests_session(country?, version?, ...) |
One-shot: pick a proxy → ready requests.Session |
httpx_client(country?, ..., **kwargs) |
One-shot: pick a proxy → ready httpx.Client |
httpx_async_client(country?, ..., **kwargs) |
One-shot: pick a proxy → ready httpx.AsyncClient |
aiohttp_kwargs(country?, ...) |
One-shot: pick a proxy → kwargs for aiohttp requests |
Using your proxies in an HTTP client
The SDK ships convenience helpers at two levels so you don't have to stitch together proxy URLs by hand.
One-liner on the client — picks a proxy from the cached pool (auto-filtered
to active=True by default) and hands back a ready-to-use HTTP client:
with Proxy6Client() as c:
with c.requests_session(country="us") as s:
r = s.get("https://api.ipify.org?format=json", timeout=10)
Per-proxy — when you want to pick the proxy yourself first (e.g. inspect it, reuse it across calls) and produce the client from there:
with Proxy6Client() as c:
proxy = c.select_proxy(country="us", version=Version.IPV4)
# equivalently: c.proxies().filter(country="us", version=Version.IPV4).random()
with proxy.requests_session() as s:
r = s.get("https://api.ipify.org?format=json", timeout=10)
Both forms share the cache — back-to-back calls don't re-hit /getproxy.
Filter args (country, version, active, descr, type) are the same
as :meth:ProxyList.filter. If nothing matches, a LookupError is raised
with the criteria that failed.
Examples per library
requests
from proxy6 import Proxy6Client
with Proxy6Client() as c:
# One-shot.
with c.requests_session(country="us") as s:
r = s.get("https://api.ipify.org?format=json", timeout=10)
print(r.json()["ip"])
# Per-proxy (lets you inspect/reuse `proxy`).
proxy = c.select_proxy(country="us")
with proxy.requests_session() as s:
r = s.get("https://api.ipify.org?format=json", timeout=10)
httpx (sync)
from proxy6 import Proxy6Client
with Proxy6Client() as c:
with c.httpx_client(country="us", timeout=10) as client:
r = client.get("https://api.ipify.org?format=json")
print(r.json()["ip"])
# Per-proxy.
proxy = c.select_proxy(country="us")
with proxy.httpx_client(timeout=10) as client:
r = client.get("https://api.ipify.org?format=json")
httpx (async)
import asyncio
from proxy6 import Proxy6Client
async def main() -> None:
with Proxy6Client() as c:
async with c.httpx_async_client(country="us", timeout=10) as client:
r = await client.get("https://api.ipify.org?format=json")
print(r.json()["ip"])
asyncio.run(main())
aiohttp — aiohttp has no session-level proxy setting, so the proxy
goes on each request. The helper returns a kwargs dict you spread in:
import asyncio
import aiohttp
from proxy6 import Proxy6Client
async def main() -> None:
with Proxy6Client() as c:
kw = c.aiohttp_kwargs(country="us") # {"proxy": "http://u:p@host:port"}
async with aiohttp.ClientSession() as s:
async with s.get("https://api.ipify.org?format=json", **kw) as r:
print((await r.json())["ip"])
asyncio.run(main())
subprocess / curl / wget — env-var format for shelling out:
import os
import subprocess
from proxy6 import Proxy6Client
with Proxy6Client() as c:
proxy = c.select_proxy(country="us")
subprocess.run(
["curl", "https://api.ipify.org"],
env={**os.environ, **proxy.as_env()},
)
Just give me the URL / dict — if you're plugging into another HTTP lib not covered above:
proxy.auth_url() # "http://user:pass@host:port"
proxy.as_requests_dict() # {"http": auth_url, "https": auth_url}
proxy.aiohttp_kwargs() # {"proxy": auth_url}
httpx and aiohttp are imported lazily — they only need to be installed
if you actually call the corresponding helper.
Caching the proxy pool
get_proxy() is the raw API call and always hits the wire. For the
"give me my pool, I'll filter locally" workflow there's proxies(), which
fetches the full pool once and reuses it for repeated calls:
pool = client.proxies() # one API call
us_v4 = pool.filter(country="us", version=Version.IPV4, active=True)
proxy = us_v4.random()
client.proxies() # served from cache, no HTTP
- Default TTL is 24 hours. Override with
Proxy6Client(proxy_cache_ttl=3600)(seconds) or passNoneto disable caching entirely. - The cache is automatically invalidated after any state-changing call
(
buy,prolong,delete,set_descr), so newly-bought proxies show up on the nextproxies()call. - Force a refresh with
client.proxies(refresh=True)or drop the cache explicitly withclient.invalidate_proxy_cache(). ProxyListis iterable / sized / indexable and supportsfilter(...)(country,version,active,descr,type) andrandom(*, rng=None)so most pool workflows don't need to touchclient.proxiesdirectly.
Authentication
The client resolves the API key in this order:
- The
api_key=constructor argument - The
PROXY6_API_KEYenvironment variable
If neither is set, Proxy6Client() raises ValueError. The SDK does not
load .env files itself — if you keep your key in .env, use
python-dotenv in your
application:
from dotenv import load_dotenv
from proxy6 import Proxy6Client
load_dotenv()
client = Proxy6Client()
Enums
from proxy6 import Version, State, ProxyType
Version.IPV4_SHARED # 3
Version.IPV4 # 4
Version.MTPROTO # 5
Version.IPV6 # 6
State.ACTIVE | State.EXPIRED | State.EXPIRING | State.ALL
ProxyType.HTTP | ProxyType.SOCKS
Errors
The API uses an envelope of {"status":"no","error_id":N,"error":"..."}. Each
documented error code has its own exception subclass, so you can catch
specific failures directly:
from proxy6 import (
InsufficientBalanceError,
NotEnoughProxiesError,
Proxy6APIError,
)
try:
client.buy(count=100, period=30, country="ru", version=Version.IPV6)
except InsufficientBalanceError:
topup()
except NotEnoughProxiesError:
wait_and_retry()
except Proxy6APIError as e:
# Catch-all for anything else
log.error("proxy6 %s: %s", e.error_id, e.error)
| Code | Exception | Meaning |
|---|---|---|
| 30 | UnknownError |
Unknown error |
| 100 | AuthError |
Wrong API key |
| 105 | IPNotAllowedError |
IP restriction blocked the call |
| 110 | MethodError |
Wrong method name |
| 200 | InvalidCountError |
Bad proxies quantity |
| 210 | InvalidPeriodError |
Bad period (days) |
| 220 | InvalidCountryError |
Bad country code |
| 230 | InvalidIdsError |
Bad proxy id list |
| 240 | InvalidVersionError |
Bad proxy version |
| 250 | InvalidDescriptionError |
Bad technical description |
| 260 | InvalidProxyTypeError |
Bad proxy type/protocol |
| 270 | InvalidPortError |
Bad port |
| 280 | InvalidProxyStringError |
Bad ip:port:user:pass for check |
| 300 | NotEnoughProxiesError |
Stock too low |
| 400 | InsufficientBalanceError |
Zero / low balance |
| 404 | NotFoundError |
Element not found |
| 410 | PriceCalculationError |
Cost ≤ 0 |
The raw documented messages are also exposed as the proxy6.ERROR_CODES
dict.
Rate limiting
The API allows 3 requests per second; over that limit it returns HTTP 429.
The SDK ships with a thread-safe sliding-window limiter that all
Proxy6Client instances share by default, so you don't have to think about
it — concurrent calls just block long enough to stay under the cap.
from proxy6 import Proxy6Client, RateLimiter
# Default — uses the process-wide DEFAULT_RATE_LIMITER (3/s).
client = Proxy6Client()
# Custom limit (e.g. you have a higher-tier agreement).
client = Proxy6Client(rate_limiter=RateLimiter(max_requests=10, period=1.0))
# Disable entirely (you're handling throttling yourself).
client = Proxy6Client(rate_limiter=None)
Verifying a proxy against a live IP-check service
ProxyVerifier routes a request through a proxy and asks a public
"what's my IP" service what it sees, so you can confirm the proxy is
egressing as expected and your real IP isn't leaking. By default it walks
through four built-in providers in order and returns the first success,
so a single provider being down or blocking your IP doesn't break the
check.
from proxy6 import Proxy6Client, ProxyVerifier
with Proxy6Client() as c:
proxy = c.proxies().filter(country="us", active=True).random()
with ProxyVerifier() as v: # fallback enabled by default
leak = v.check_leak(proxy)
print(leak.result.ip, leak.result.country, leak.leaked, leak.result.provider)
check_leak() returns a LeakCheck whose leaked property is True
whenever the IP the service saw differs from proxy.ip (the proxy's
egress). For the IPv6 product proxy.host is the IPv4 SOCKS ingress —
comparing against that would produce a false positive on every check —
so the comparison is always against the egress.
Built-in providers (the default chain, in order):
| Provider | Endpoint | Data returned |
|---|---|---|
IpifyProvider |
api.ipify.org / api6.ipify.org |
IP only — smallest moving part |
IcanhazipProvider |
ipv4.icanhazip.com / ipv6.icanhazip.com |
IP only, plain text |
IfconfigCoProvider |
ifconfig.co/json (dual-stack apex) |
IP + country + region + city + ASN |
IpinfoIoProvider (IPv4 only by default) |
ipinfo.io/json |
IP + country + region + city + ASN; ipinfo.io has no AAAA record, so the verifier skips it for IPv6 proxies. Pass supported_versions= to override. |
Pin a single provider (no fallback) or control the chain explicitly:
# Single provider — failures raise instead of falling back.
ProxyVerifier(provider=IpifyProvider()).check(proxy)
# Custom fallback chain, tried in order.
ProxyVerifier(providers=[MyChecker(), IpifyProvider(), IcanhazipProvider()]).check(proxy)
If every provider in the chain fails, check() raises a single
VerificationError whose message lists each failure in order — no silent
fallbacks, no truncated history. To use a custom provider or run your own
endpoint, see docs/VERIFICATION.md.
Using a custom session
Inject any requests.Session (e.g. with retry policies or a proxy of your
own):
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
session = requests.Session()
session.mount("https://", HTTPAdapter(max_retries=Retry(
total=5, backoff_factor=0.5, status_forcelist=(429, 500, 502, 503, 504)
)))
client = Proxy6Client(api_key="...", session=session)
Development
uv sync
uv run pytest # unit tests only (integration is gated)
uv run pytest -m integration # hit the real API; needs PROXY6_API_KEY
Put your key in a local .env; tests/conftest.py loads it automatically.
User-visible changes are tracked in CHANGELOG.md — add an
entry under [Unreleased] whenever you ship something that affects the
public API.
License
MIT — see LICENSE. This is an unofficial project and ships with no warranty of fitness for any particular purpose.
Metadata
Release files for proxy6-sdk 0.1.0a3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| proxy6_sdk-0.1.0a3.tar.gz | 22.2 kB | With provenance | Details for proxy6_sdk-0.1.0a3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| proxy6_sdk-0.1.0a3-py3-none-any.whl | Python 3 | none | any | Details for proxy6_sdk-0.1.0a3-py3-none-any.whl |
Total release size: 47.5 kB
Release files / proxy6_sdk-0.1.0a3.tar.gz
| Download URL | proxy6_sdk-0.1.0a3.tar.gz |
|---|---|
| Size | 22.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c9eb73ab475b0d532c3ead128277d8eff22fcddccbd87dd2341bc0b955753eb2
|
|
BLAKE2b-256 checksum How to use checksums |
f5ec24ef9560baf561333ab32e0b2adddf97ee6db283d9fde40d66eef7970d69
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 18, 2026.
Transparency logRelease files / proxy6_sdk-0.1.0a3-py3-none-any.whl
| Download URL | proxy6_sdk-0.1.0a3-py3-none-any.whl |
|---|---|
| Size | 25.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ffeb06388b1bdbe11bc065f3b1585eb0f6c24c9cd9041c704669e19bb6b7c31b
|
|
BLAKE2b-256 checksum How to use checksums |
2b2a0db937a982d910a5c846143303c55402723aa14d4b3be7c84f52ac78b091
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 18, 2026.
Transparency logSecurity for proxy6-sdk 0.1.0a3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for proxy6_sdk-0.1.0a3.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.