Docs & API — Fetch Proxies Programmatically

stormsia/proxy-list is a fully open-source project that runs an asynchronous Python daemon every 15 minutes to collect, validate and publish free proxy servers. Each proxy is tested by a native validator for actual connectivity and response time — only working proxies make it to the list.

All data is freely accessible without authentication: grab a plain-text file with curl, poll the JSON feed, or query the GitHub REST API. This page documents every integration method available.

Available Data Endpoints

All endpoints below are publicly accessible without authentication. GitHub's raw CDN also supports HTTP range requests for partial downloads.

JSON

/proxies.json

Full proxy list as JSON. Contains protocol, host, port, timeout, exit_ip, ASN, and geolocation for every entry.

Open →

TXT

working_proxies.txt

All working proxies in host:port format. One entry per line.

Open →

TXT

socks5.txt

SOCKS5-only proxies in host:port format.

Open →

TXT

socks4.txt

SOCKS4-only proxies.

Open →

TXT

http.txt

HTTP/HTTPS-only proxies.

Open →

JSON Schema Reference

Each entry in proxies.json follows this structure:

{
  "protocol": "socks5",       // "socks5" | "socks4" | "http" | "https"
  "host": "1.2.3.4",          // Proxy IP address
  "port": 1080,               // Proxy port number
  "timeout": 0.312,           // Response time in seconds
  "exit_ip": "1.2.3.4",       // External IP seen through the proxy
  "asn": {
    "autonomous_system_number": 12345,
    "autonomous_system_organization": "Example ISP"
  },
  "geolocation": {
    "city": { "names": { "en": "Frankfurt" } },
    "continent": { "code": "EU", "names": { "en": "Europe" } },
    "country": {
      "iso_code": "DE",
      "names": { "en": "Germany" }
    },
    "location": { "latitude": 50.11, "longitude": 8.68 },
    "registered_country": {
      "iso_code": "DE",
      "names": { "en": "Germany" }
    }
  }
}

Download via cURL

The quickest way to grab the list from any Unix-like system or CI pipeline:

# All working proxies (host:port)
curl -o working.txt https://raw.githubusercontent.com/stormsia/proxy-list/main/working_proxies.txt

# SOCKS5 only
curl -o socks5.txt https://raw.githubusercontent.com/stormsia/proxy-list/main/socks5.txt

# SOCKS4 only
curl -o socks4.txt https://raw.githubusercontent.com/stormsia/proxy-list/main/socks4.txt

# HTTP/HTTPS only
curl -o http.txt https://raw.githubusercontent.com/stormsia/proxy-list/main/http.txt

# Full JSON dataset (protocol, geolocation, ASN, latency)
curl -o proxies.json https://stormsia.github.io/proxy-list/proxies.json

Python — Auto-Update & Use

Fetch and immediately use the latest proxies inside a requests session:

import requests
import random

SOCKS5_URL = "https://raw.githubusercontent.com/stormsia/proxy-list/main/socks5.txt"
HTTP_URL   = "https://raw.githubusercontent.com/stormsia/proxy-list/main/http.txt"

def fetch_proxies(url: str) -> list[str]:
    """Download a plain-text proxy list and return as a list of host:port strings."""
    response = requests.get(url, timeout=15)
    response.raise_for_status()
    return [line.strip() for line in response.text.splitlines() if line.strip()]


if __name__ == "__main__":
    proxies = fetch_proxies(SOCKS5_URL)
    print(f"Loaded {len(proxies)} SOCKS5 proxies")

    proxy = random.choice(proxies)


    try:
        
        print("Proxy:", proxy)
    except Exception as e:
        print(f"Error: {e}")

Node.js (fetch API)

Works in Node 18+ without any extra dependencies:

// Download the SOCKS5 proxy list and log the first 5
const SOCKS5_URL = "https://raw.githubusercontent.com/stormsia/proxy-list/main/socks5.txt";

async function fetchProxies(url) {
  const res = await fetch(url);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const text = await res.text();
  return text.split("\n").map(l => l.trim()).filter(Boolean);
}

const proxies = await fetchProxies(SOCKS5_URL);
console.log(`Loaded ${proxies.length} SOCKS5 proxies`);
console.log("Sample:", proxies.slice(0, 5));

Go

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

const socks5URL = "https://raw.githubusercontent.com/stormsia/proxy-list/main/socks5.txt"

func main() {
	resp, err := http.Get(socks5URL)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	lines := strings.Split(strings.TrimSpace(string(body)), "\n")

	fmt.Printf("Loaded %d SOCKS5 proxies\n", len(lines))
	for i, proxy := range lines[:5] {
		fmt.Printf("%d: %s\n", i+1, strings.TrimSpace(proxy))
	}
}

GitHub REST API

To inspect file metadata (SHA, size, last commit timestamp) before downloading, query the GitHub REST API. An auth token is optional but raises your rate limit from 60 to 5 000 requests/hour.

GET https://api.github.com/repos/stormsia/proxy-list/contents/working_proxies.txt
Accept: application/vnd.github.v3+json
// Optional (raises rate limit):
// Authorization: Bearer <YOUR_GITHUB_TOKEN>

The response includes a sha field you can cache locally to detect changes without re-downloading the full file:

import requests

API = "https://api.github.com/repos/stormsia/proxy-list/contents/working_proxies.txt"
HEADERS = {"Accept": "application/vnd.github.v3+json"}
# headers["Authorization"] = "Bearer <token>"  # optional

meta = requests.get(API, headers=HEADERS).json()
print("SHA:",       meta["sha"])
print("Size:",      meta["size"], "bytes")
print("Last push:", meta.get("commit", {}).get("committer", {}).get("date", "—"))

⚠️

Anonymity Disclaimer

Proxies in this list have varying anonymity levels — transparent, anonymous, and elite. The project does not guarantee anonymity for any specific proxy. Always verify the anonymity level of a proxy with a tool like httpbin.org/ip before using it in production.