Proxy6

<!-- versions:start -->

🎯 Version Requirements (August 2026)

Primary pins:

• proxy6 API: docs-only (stable REST, no version path)
• Python: 3.14.x
• Node.js: 24.x (Active LTS)

Source of truth: STACK_VERSIONS.md — verified 2026-08-24

<!-- versions:end -->

Usage

Loaded automatically when its description matches the active task. Read only the section you need, then follow the link to the relevant reference file for full detail.

Use this skill when

• Buying / prolonging / deleting proxies through the proxy6.net REST API — calls to buy, prolong, delete
• Building a proxy pool from getproxy results, organising it via descr tags, rotating per request / per worker
• Pre-flighting purchases with getprice + getcount + balance check before calling buy (money safety)
• Setting up ipauth IP allowlist for production scrapers — full-replace semantics, dev/prod separation
• Implementing a rate-limit-safe client (≤ 3 req/s) with retry/backoff on 429 / error_id envelopes
• Debugging proxy6 error responses — error_id 100 (auth), 105 (IP not allowed), 300 (insufficient stock), 400 (no money), 410 (zero price), 429 (rate limited)
• Picking the right proxy version for the workload — 3 (IPv4 Shared), 4 (IPv4), 5 (MTproto), 6 (IPv6) — and the right country
• Building a scheduled-cleanup job for expired proxies (state=expired) and a renewal job before date_end

Do not use this skill when

• Task uses a different proxy provider — Mobileproxy / Webshare / Brightdata / Oxylabs / Smartproxy / iProxy / ProxyEmpire — they have different APIs
• Task is actually using a proxy in HTTP code after acquisition — that belongs to the HTTP-client skill (httpx for Python, nodejs for Node)
• Task is in-browser CORS proxying or local proxy server (mitmproxy / squid / nginx forward proxy) — different domain
• Task is Telegram MTProto client configuration without proxy6 (mtproto auth, session strings) — use telegram-bot and the MTProto client docs

Purpose

proxy6.net is one of the dominant Russian retail proxy providers — IPv4 (dedicated), IPv4 Shared, IPv6, and MTproto-flavoured proxies, sold per proxy per day with a single REST endpoint at https://px6.link/api/{api_key}/{method}/. It is widely used by Russian scraping shops, ad-operations teams, social-media automation, and price-monitoring pipelines that need cheap, short-lived, country-targeted proxies.

This skill is high-stakes because three of the ten methods cost money or destroy state and the API is hard-limited to 3 requests per second:

1. buy debits the merchant balance immediately; auto_prolong silently re-charges on expiry.
2. prolong debits again and (for mixed-version ids) returns no price_single — easy to miscalculate.
3. delete is irreversible; with the descr filter you can wipe an entire pool in one call.
4. ipauth REPLACES the full allowlist — passing a partial list deletes everything else.
5. Over-3-req/s bursts return HTTP 429, breaking unaware clients.

The skill owns provider-domain knowledge — method shapes, error semantics, version tradeoffs, billing safety, rate-limit handling, pool management via descr tags, and ipauth gotchas. HTTP plumbing (retries, async clients, secret loading) belongs to the runtime skill (httpx, nodejs).

Capabilities

API client setup

Single endpoint pattern: https://px6.link/api/{api_key}/{method}/?{params} (api_key in the URL path). Success envelope: {"status":"yes", user_id, balance, currency, ...}. Error envelope: {"status":"no", error_id, error}. Auth via api_key only; optional IP allowlist in dashboard (returns error_id 105 if source IP not allowed). The key in the URL path means it appears in nginx / reverse-proxy access logs — log scrubbing is mandatory.

Full reference: references/setup.md

The 10 methods

getprice (price calc) · getcount (stock check) · getcountry (countries by version) · getproxy (list owned proxies, paged) · setdescr (update comment tag) · buy (purchase — money) · prolong (extend — money) · delete (irreversible) · check (validate one proxy) · ipauth (full-replace allowlist).

Full reference: references/methods.md

Proxy versions (3/4/5/6)

Four version values map to four distinct products with different prices and protocol support: 3 = IPv4 Shared (cheapest, shared across users), 4 = IPv4 dedicated, 5 = MTproto (Telegram-specific), 6 = IPv6. Pick by target: IPv6 only works against IPv6-aware destinations; MTproto only for Telegram clients; IPv4 Shared is fine for low-trust scraping but flags faster on sensitive sites.

Full reference: references/proxy-versions.md

Rate limit handling (3 req/s budget)

Provider enforces 3 requests per second. Practical client budget: 2 req/s (33% headroom) under steady load, brief bursts up to 3. Use a token bucket / leaky bucket gate or per-call sleep ≥ 333 ms. Retry policy: 429 → backoff base 500 ms, cap 30 s, max 5 attempts; never retry 4xx envelope errors except error_id 30 (unknown — single retry).

Full reference: references/rate-limit-and-retry.md

Purchase and billing safety

Canonical pre-buy sequence: getprice(count, period, version) → getcount(country, version) → balance check (from any successful envelope) → buy(...). Always set descr to a stable ops tag so the order is reattributable later. Default auto_prolong = OFF — surprise renewals are a top operational complaint. Document a balance-low threshold (alert when balance < N × daily_burn).

Full reference: references/purchase-and-billing.md

Pool management & rotation

Organise live proxies by descr tag (e.g. descr=pool:scraper-A:prod). Rotation strategies: sticky (worker keeps one proxy until ban / expiry), round-robin (per-request from a shuffled pool), weighted (prefer freshest by date_end). Ban detection: track per-proxy 4xx/5xx ratio; quarantine on threshold; replace via buy with the same descr. Schedule a daily cleanup that getproxy(state=expired) → delete(ids=...).

Full reference: references/pool-management.md

IP authentication strategy

ipauth sets the full list of source IPs allowed to use the proxies (separate from API allowlist — that's in the dashboard). Critical gotcha: every ipauth call REPLACES the prior list. Always send the complete union of dev + prod + CI IPs; pass ip=delete to clear all bindings. Prefer ipauth over user/pass for production worker fleets — fewer secrets in code.

Full reference: references/ipauth-strategy.md

Python integration (httpx + tenacity)

Async httpx.AsyncClient with tenacity retry decorators, pydantic models for response shapes, api_key in env var (PROXY6_API_KEY), per-method functions returning typed envelopes, rate-limit token bucket via asyncio.Semaphore + sleep.

Full reference: references/integration-python.md

Node.js / TypeScript integration

fetch or axios with axios-retry / p-retry, TypeScript types for each method's response, env-based key, rate limit via p-limit or bottleneck.

Full reference: references/integration-node.md