Webshare Static Residential Proxies

An agent skill for operating Webshare.io static residential (shared ISP) proxies.

Fetch your proxy list, read per-proxy ASN/geo/validity detail, and replace a burned IP inside the same ASN — the part most proxies get wrong.

---

What this skill does

Scope	Static residential proxies only — proxy_type: shared + proxy_subtype: isp
Base URL	https://proxy.webshare.io
Auth	Authorization: Token $WEBSHARE_API_KEY
Endpoints	v2 (list, config, pricing, purchase) · v3 (replace, stats, status)
Out of scope	Rotating residential (backbone), free plans, dedicated/semidedicated

It gives an agent the three things you actually need from the Webshare API:

1. Full proxy inventory — IP, port, valid, last verification, country, city, ASN number/name, for every proxy on the plan.
2. Same-ASN replacement — swap a dead IP for a fresh one on the same ASN (falling back to a same-ASN IP range), so network identity is preserved.
3. Plan growth by upgrade — copy the live plan's own fields into a pricing quote and purchase with behavior: "upgrade", instead of hand-building a payload that drifts from what you already own.

Why same-ASN replacement is the default

A static residential proxy's value is its network identity. Swap a burned Rcn (AS6079) IP for a random Comcast IP and anything that fingerprinted you by ASN, /24, or netblock sees a brand-new host. Swap it inside the same ASN and the network identity holds.

The skill enforces this ordering:

same ASN  →  same-ASN /24  →  same-ASN /16  →  same-ASN /8  →  (ask first)

Country-level and any fallbacks exist in the API but are only used with explicit user consent.

Install

npx skills add Apothic-AI/webshare-skill

Install globally, or target specific agents:

npx skills add Apothic-AI/webshare-skill -g -a claude-code -a opencode -y

Preview what's inside without installing:

npx skills add Apothic-AI/webshare-skill --list

Use it in a one-off session, no install:

npx skills use Apothic-AI/webshare-skill --agent claude-code

Works with 75+ agents — Claude Code, OpenCode, Codex, Cursor, Droid, Gemini CLI, Copilot, Windsurf, Zed, and the rest. See the skills CLI for the full matrix.

Requirements

export WEBSHARE_API_KEY="..."   # Webshare dashboard → API keys

One environment variable. That's it — no SDK, no language runtime, no dependencies beyond curl and python3.

The skill refuses to call the API when the key is unset. It never logs, prints, or commits the API key, proxy username/password, full user:pass@ip:port strings, or the proxy_list_download_token.

What the agent gets

A single SKILL.md, written to be acted on directly:

• Environment gate — hard-fail fast on a missing WEBSHARE_API_KEY.
• Core facts — naming (shared + isp = "static residential"), auth header, mode=direct requirement, pagination, rate limits (240/min general, 60/min proxy-list, 30/min downloads; wait 60s on 429), plan_id resolution.
• Inventory — plan, proxy list with the per-proxy field table, proxy config (available_asns, available_ip_ranges_24|16|8, download token), v3 stats and status, plain-text list download path grammar.
• Replacement — ASN-priority selection rules, to_replace shapes, mandatory dry-run gate, async polling loop, credit accounting, error codes.
• Purchase — the standard config table (shared/isp, 250 GB, US, 50 manual replacements, no rotation, high-priority network, monthly) and the upgrade-not-rebuild path.

Triggers on: "what are my Webshare proxies", "replace this Webshare proxy", "that proxy is burned", "buy more Webshare proxies", "which ASN is this IP on".

Replacement in four calls

KEY=$WEBSHARE_API_KEY
PLAN=14216736

# 1. which ASN is the dead IP on?
curl -s -H "Authorization: Token $KEY" \
  "https://proxy.webshare.io/api/v2/proxy/list/?mode=direct&page_size=1000&plan_id=$PLAN"

# 2. is that ASN in the available pool? (check available_asns in proxy config)
curl -s -H "Authorization: Token $KEY" \
  "https://proxy.webshare.io/api/v2/proxy/config/?plan_id=$PLAN"

# 3. dry run — no credits consumed. removed == added, both 1
curl -s -X POST "https://proxy.webshare.io/api/v3/proxy/replace/?plan_id=$PLAN" \
  -H "Authorization: Token $KEY" -H "Content-Type: application/json" \
  -d '{"to_replace":{"type":"ip_address","ip_addresses":["193.160.82.205"]},
       "replace_with":[{"type":"asn","asn_numbers":["6079"]}],
       "dry_run": true}'

# 4. same body with "dry_run": false, then poll GET /api/v3/proxy/replace/{id}/

Replacements are asynchronous. The POST returns state: "validating" — poll until completed (dry runs settle at validated).

Errors it knows

Code	Meaning
400 active_replacement	A replacement is already running — wait and retry
400 not_enough_replacements_in_subscription	Out of replacement credits
400 invalid	Proxy list not editable
no_proxies_to_be_replaced	The IP isn't in this plan's list
payment_required: true	Recaptcha/Stripe confirmation — cannot be done via API; finish in the dashboard

Verification status

Every endpoint, request body, response field, and error path in this skill was checked live against proxy.webshare.io, including a full dry-run replacement cycle (state: validated, proxies_removed: 1, proxies_added: 1).

When this skill is ambiguous or may be stale, read apidocs.webshare.io before inventing API behavior.

Links

• Canonical API docs — https://apidocs.webshare.io/
• Dashboard — https://dashboard.webshare.io
• Agent Skills spec — https://agentskills.io

License

MIT