Proxy302 API documentation

Every endpoint answers HTTP 200 and reports the outcome in the {code, msg, data} envelope: code === 0 means success; data is null on every non-zero code. Money is PTC with at most 3 decimals, traffic volumes are decimal byte strings, timestamps are Unix seconds.

Official MCP server

Maintained by the Proxy302 team and open source on GitHub. Cursor and VS Code add it in one click, Claude.ai and ChatGPT use the web connector, and there is nothing to install.

  • proxy302-mcp (Official) — Lets AI tools such as Claude, ChatGPT, Cursor and VS Code check usage, get proxies, rotate IPs and check IP purity. None of these tools spend money. GitHub · Add to Cursor · Install in VS Code
    Web connector (Claude.ai, ChatGPT): https://mcp.proxy302.com/mcp Add this address as a custom connector and paste <key id>:<secret> on the authorization page.
    Claude Code (then run /mcp to sign in): claude mcp add --transport http proxy302 https://mcp.proxy302.com/mcp
    Key in a header (Claude Code): claude mcp add --transport http proxy302 https://proxy302.com/v1/mcp --header "Authorization: Bearer <key id>:<secret>"
    Local (Claude Code): claude mcp add proxy302 -e PROXY302_API_KEY="<key id>:<secret>" -- npx -y github:proxy302/proxy302-mcp
    Accounts that have topped up get 1 PTC the first time they use Proxy302 through MCP, once per account.

Auth

Issue the Basic credential and inspect the current API key identity. With just the secret (the p302_ string), send Authorization: Bearer <secret>.

  • GET /open_api/v3/user/users/token — Encode the key into the Authorization: Basic header value
  • GET /open_api/v3/user/users/me — Current API key identity (name / email / uid)

Directory

Look up area ids and static price plans before a purchase.

  • GET /open_api/v3/proxy/area/{area_type} — List areas by granularity (country / state / city)
  • GET /open_api/v3/proxy/payway/{payway_name} — List payways (price plans) for a static product

Purchase

Four purchase lines: static traffic, static IP, dynamic traffic, dynamic by-area. Parameters go in the JSON body and/or the query string; the body wins on conflicts.

  • POST /open_api/v3/proxy/api/proxy/static/traffic — Buy static traffic proxy
  • POST /open_api/v3/proxy/api/proxy/static/ip — Buy a static IP (lease-billed)
  • POST /open_api/v3/proxy/api/proxy/dynamic/traffic — Buy dynamic traffic proxy
  • POST /open_api/v3/proxy/api/proxy/dynamic/ip/by_area — Buy dynamic IP proxy by area

Proxy list

Paged listing of owned proxies with filtering, sorting and soft-delete toggles.

  • GET /open_api/v3/proxy/tokens/{generate}/{proxy_type} — List owned proxy tokens (paged)

Traffic & usage

Day-bucketed consumption, usage chart series and pool balance.

  • GET /open_api/v3/proxy/traffic/consume/log/summary — Traffic consumption by day and pool category
  • GET /open_api/v3/proxy/summary/proxies/{proxy_type}/{statistics_type} — Usage chart series
  • GET /open_api/v3/proxy/summary/cost/{statistics_type} — Spend chart by category (PTC)
  • GET /open_api/v3/proxy/traffic/pool/remaining — Remaining traffic pool balance

Renewal

Paid static lease extension and the auto-renewal toggle.

  • POST /open_api/v3/proxy/token/renew/{token_id} — Renew a static IP (paid)
  • PUT /open_api/v3/proxy/token/renew/{token_id} — Toggle auto renewal

ISP directory

ISP options for Premium line targeting.

  • GET /open_api/v3/proxy/isp/catalog — List ISP targeting options (optionally by country)

Session reset

Rotate the exit IP of sticky credentials without new keys (all upstream session segments per token, 1-100 tokens).

  • DELETE /open_api/v3/proxy/sessions — Batch-reset sticky sessions (token_ids array in the body)

Delete proxies

Delete your own proxy connections (static or dynamic), exactly like Delete in the console: it cannot be undone and the unused days of a static IP are not refunded.

  • DELETE /open_api/v3/proxy/token/{token_id} — Delete one proxy connection
  • DELETE /open_api/v3/proxy/tokens — Batch delete (token_ids array in the body)

IP whitelist

Per-token source-IP allowlist (at most 5 IPs per token).

  • GET /open_api/v3/proxy/token/{token_id}/ip-whitelist — List the token's whitelisted IPs
  • POST /open_api/v3/proxy/token/{token_id}/ip-whitelist — Bind a source IP
  • DELETE /open_api/v3/proxy/token/{token_id}/ip-whitelist/{ip} — Unbind a source IP

Traffic caps (sub-accounts)

Every connection has its own username and password; give it a traffic cap and it works as a sub-account for a teammate, a tool or your own customer, stopping when the cap is used up. Only dynamic connections billed by traffic can be capped. Usage counts from when the cap is set (or reset) and includes traffic in flight, so a burst of connections cannot overshoot it. At the cap the HTTP proxy answers 403 and SOCKS5 refuses the connection.

  • GET /open_api/v3/proxy/traffic-caps — List every capped connection of the account
  • GET /open_api/v3/proxy/token/{token_id}/traffic-cap — Read one connection's cap and usage
  • POST /open_api/v3/proxy/token/{token_id}/traffic-cap — Set or change the cap
  • DELETE /open_api/v3/proxy/token/{token_id}/traffic-cap — Remove the cap

Proxy302

PROXY302