IPLoop Node.js SDK

Official Node.js SDK for IPLoop — residential proxy service with millions of real IPs worldwide.

Installation

npm install iploop

Quick Start

import { IPLoopClient } from 'iploop';

const client = new IPLoopClient({ apiKey: 'your-api-key' });
const response = await client.get('https://httpbin.org/ip');
console.log(response.data);

Features

• Residential proxies — millions of real IPs across 195+ countries
• Geographic targeting — country and city-level precision
• Sticky sessions — keep the same IP across multiple requests
• Auto-retry — failed requests automatically retry with fresh IPs
• Smart headers — Chrome fingerprint headers matched to target country
• HTTP & SOCKS5 — both protocols supported
• Concurrent fetching — batch requests with configurable concurrency
• TypeScript — full type definitions included

Authentication

Get your API key from the IPLoop Dashboard.

// New format (v2): iploop_{short}_{secret} — single key, no customer_id needed!
const client = new IPLoopClient({
  apiKey: 'iploop_fd80eb86_72dabf65a3e44459423ade99a5e4a83e133c9125',
  country: 'US',       // default country for all requests
  debug: true,         // enable request logging
});

Geographic Targeting

// Target a specific country
const resp = await client.get('https://example.com', { country: 'DE' });

// Target a specific city
const resp = await client.get('https://example.com', { country: 'US', city: 'miami' });

Sticky Sessions

Keep the same proxy IP across multiple requests:

const session = client.session(undefined, 'US', 'newyork');

const page1 = await session.get('https://site.com/page1'); // same IP
const page2 = await session.get('https://site.com/page2'); // same IP

HTTP Methods

// GET
const resp = await client.get('https://httpbin.org/get');

// POST
const resp = await client.post('https://httpbin.org/post', { key: 'value' });

// PUT
const resp = await client.put('https://httpbin.org/put', { key: 'value' });

// DELETE
const resp = await client.delete('https://httpbin.org/delete');

Concurrent Fetching

Fetch multiple URLs in parallel:

const results = await client.fetchAll([
  'https://example.com/page1',
  'https://example.com/page2',
  'https://example.com/page3',
], { country: 'US' }, 10); // 10 concurrent workers

console.log(results);
// [{ url: '...', status: 200, success: true, sizeKb: 42 }, ...]

SOCKS5 Support

// Use SOCKS5 protocol
const resp = await client.get('https://example.com', { protocol: 'socks5' });

// Get SOCKS5 proxy URL for use with other libraries
const proxyUrl = client.getProxyUrl({ protocol: 'socks5', country: 'US' });

Use with Other Libraries

Get the proxy URL or agent for use with Puppeteer, Playwright, Got, etc:

// Get proxy URL string
const proxyUrl = client.getProxyUrl({ country: 'US', session: 'my-session' });
// → http://iploop:[email protected]:8880

// Get axios-compatible agent
const agent = client.getProxyAgent({ country: 'DE' });

// Use with Puppeteer
const browser = await puppeteer.launch({
  args: [`--proxy-server=${client.getProxyUrl({ country: 'US' })}`],
});

Chrome Fingerprinting

Every request automatically includes 14 Chrome desktop headers matched to the target country. You can also get them directly:

const headers = client.fingerprint('JP');
// Full Chrome headers with Japanese locale

Request Statistics

// After making requests...
console.log(client.getStats());
// { requests: 10, success: 9, errors: 1, totalTime: 23500, avgTime: 2350, successRate: 90.0 }

API Methods

// Check bandwidth usage
const usage = await client.getUsage();

// Service status
const status = await client.getStatus();

// Available countries
const countries = await client.getCountries();

Error Handling

import { AuthenticationError, QuotaExceededError, ProxyError, RateLimitError } from 'iploop';

try {
  const resp = await client.get('https://example.com');
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (err instanceof QuotaExceededError) {
    console.log('Upgrade at https://iploop.io/pricing');
  } else if (err instanceof ProxyError) {
    console.log('Proxy connection failed');
  } else if (err instanceof RateLimitError) {
    console.log('Rate limited, retry after:', err.retryAfter);
  }
}

Debug Mode

const client = new IPLoopClient({ apiKey: 'your-key', debug: true });
// Logs: IPLoop: GET https://example.com → 200 (450ms) country=US session=abc123

Configuration

| Option | Default | Description | |--------|---------|-------------| | apiKey | required | Your IPLoop API key | | proxyHost | gateway.iploop.io | Proxy gateway hostname | | httpPort | 8880 | HTTP proxy port | | socksPort | 1080 | SOCKS5 proxy port | | timeout | 30000 | Request timeout in ms | | country | — | Default target country | | city | — | Default target city | | debug | false | Enable debug logging |

Links

• Website: iploop.io
• Dashboard: iploop.io/dashboard
• Documentation: docs.iploop.io

License

MIT