11dice

11dice

A fetch-like HTTP client for Node.js that scrapes free proxies, validates them, and rotates through a fresh proxy on every request — so you can hammer your own servers or APIs without tripping IP-based rate limits.

import { ElevenDice } from '11dice'

const client = new ElevenDice({ rotation: 'random' })
const res = await client.fetch('https://api.example.com/health')
console.log(res.proxy.url) // the proxy that actually served the request

Features

• Auto-scraping — pulls free proxies from trusted CDN sources (jsDelivr/API endpoints) on startup and refreshes them every 15 minutes by default. Add your own sources or seed a list directly via proxyList.
• Auto-validation — every scraped proxy is probed for liveness before it enters the pool, so you rarely ask a dead proxy to do work.
• Rotation — random (default), round-robin, or sticky (reuse one proxy for N requests to keep sessions).
• Retries — transparently retries 429 / 5xx and network failures through a different proxy.
• Realistic User-Agent — a random real browser UA is attached by default; your own explicit user-agent header always wins.
• HTTP, HTTPS & SOCKS5 — powered by undici's ProxyAgent.
• TypeScript — full type definitions, ESM + CJS.

Install

npm install 11dice

Requires Node.js >=20.18.0.

Quick start

import { ElevenDice } from '11dice'

const client = new ElevenDice({
  rotation: 'round-robin',
  retries: 3,              // extra proxies tried after the first failure
  retryStatuses: [429, 500, 502, 503, 504],
})

const res = await client.fetch('https://httpbin.org/headers', {
  headers: { 'x-anything': 'yes' },
})

console.log(res.status)      // 200
console.log(res.proxy?.host) // the IP that served you
console.log(res.elapsedMs)   // total time including retries
await client.close()         // stop the refresh timer

Options

All fields are optional; defaults are safe for most users.

Per-request options

fetch accepts everything undici's fetch does, plus:

• timeoutMs — override requestTimeoutMs for this call.
• proxy — force one specific proxy for this call, skipping rotation.
• rotation — override the pool strategy for this call.

The returned response

client.fetch returns a standard Response (use .json(), .text(), etc.) with these extras:

• res.proxy — the ProxyInfo that served the request, or null for direct.
• res.attempts — every proxy tried, in order.
• res.elapsedMs — total wall-clock time including retries.

Errors

import { NoProxiesAvailableError, AllRetriesFailedError } from '11dice'

• NoProxiesAvailableError — the pool is empty after a refresh and no fallback applies.
• AllRetriesFailedError — every attempt (through different proxies) failed; .cause holds the final underlying error.
• InvalidProxyError, UnsupportedProtocolError — bad proxyList entries.

Disclaimer

Use at your own risk, and only against servers you control or have explicit permission to load-test.

• Free proxies are unreliable, slow, and commonly operated by strangers. They can read, log, drop, or tamper with every byte you send through them. Never route credentials, tokens, or any sensitive or personally identifiable data through this client.
• A proxy can MITM your traffic, return forged responses, or black-hole requests. Treat all proxied responses as untrusted input.
• Do not use this to hammer websites, APIs, or services you do not own or that do not authorize load testing — that is abuse and may be illegal.
• Free proxy lists churn constantly; expect intermittent failures and flaky results. This package is a convenience wrapper over data you did not author.

By using 11dice you accept full responsibility for the traffic you send and the targets you send it to.

License

MIT