Node.js SDK

Installation & Setup

Get started with ClearProxy in your Node.js project.

Installation

Install the package via npm:

npm i clearproxy

Initialization

Initialize the client using your API key.

import { ClearProxy } from "clearproxy";

const client = new ClearProxy("clearpx_yourkey");

Validating Proxies

The check() method is the core of the SDK, allowing you to validate proxy lists with various configurations.

`client.check(file, options)`

Parameters:

file (string) - Path to your proxy list file.
options (object) - Configuration for the checking job.

Configuration Options

Option	Type	Description	Default
`region`	string	Testing region (e.g., `us1`, `eu1`, `asia1`)	`us1`
`timeout`	number	Request timeout in milliseconds (1000-20000)	`5000`
`type`	string	Proxy protocol (`http`, `socks4`, `socks5`)	`http`
`customUrls`	array	Custom URL validation rules	`[]`

Basic Example

const result = await client.check("proxies.txt", {
  region: "us1",
  timeout: 5000,
  type: "http"
});

console.log(`Working: ${result.working.length}`);
console.log(`Failed: ${result.failed.length}`);

Real-Time Progress Tracking

Real-time feedback via WebSockets, allowing you to track progress as it happens instead of waiting for the entire job to finish.

Implementation

To enable real-time tracking, provide an onProgress callback in the check() options.

const result = await client.check("proxies.txt", {
  onProgress: (event) => {
    console.log(`Progress: ${event.progress}%`);
    console.log(`Status: ${event.details.message}`);
    console.log(`Working found: ${event.details.working_so_far}`);
  }
});

Job ID Management

You can optionally provide a jobId to identify the socket connection. If omitted while using onProgress, the SDK automatically generates one.

Option	Type	Description
`onProgress`	function	Callback triggered for every progress update.
`jobId`	string	Custom ID for tracking. (Default: `sdk_[random]_[timestamp]`)

WebSocket Logic: The SDK manages the WebSocket lifecycle automatically—opening it when the check starts and closing it upon completion or failure.

Advanced Validation (Custom URLs)

Verify if your proxies can access specific websites with custom status code and content requirements.

Usage

const result = await client.check("proxies.txt", {
  customUrls: [
    {
      url: "https://discord.com",
      requiredStatusCodes: [200, 301, 302]
    },
    {
      url: "https://www.google.com",
      requiredText: "Search",
      caseSensitive: false
    }
  ]
});

Helper Methods

The SDK provides utilities to process custom validation results easily.

`client.getCustomUrlSummary(result)`

Get an aggregated summary of all tested URLs.

`client.filterByCustomUrl(result, url)`

Extract a list of proxies that specifically passed for a given URL.

const discordProxies = client.filterByCustomUrl(result, "https://discord.com");
console.log(`Found ${discordProxies.length} proxies valid for Discord`);

Utility Methods

Exporting Results

Convert your validated proxy lists into different formats.

`client.export(proxies, format, auth)`

format: txt, json, or csv
auth: boolean (include user:pass if available)

const textOutput = client.export(result.working, "txt", true);
fs.writeFileSync("working.txt", textOutput);

Account & API Info

const info = await client.me();
console.log(`Checks Left: ${info.user.checks}`);

const regions = await client.regions();
console.log("Available Regions:", regions);

const status = await client.health();
console.log("API Status:", status.status);

Response Structure

Standard Response

{
  summary: {
    total_working: 150,
    countries: { "United States": 100, "Germany": 50 },
    anonymity_levels: { elite: 120, anonymous: 30 }
  },
  metadata: {
    user: { 
      email: "user@example.com", 
      remaining_checks: 4500,
      subscription_detail: { UnlimitedPro: false }
    },
    region_used: "us1",
    total_checked: 500
  },
  proxies: [...], // Array of all tested proxies
  working: [...], // Array of working proxies only
  failed: [...]   // Array of failed proxies only
}

Custom URL Response

When customUrls are provided, the custom_url_validation field is populated.

{
  custom_url_validation: {
    summary: { total_urls_tested: 2, processing_time: "8.45s" },
    per_url_summary: [
      {
        url: "https://discord.com",
        success_count: 120,
        failed_count: 30,
        successful_proxies: [...]
      }
    ]
  }
}

Error Handling

try {
  const result = await client.check("proxies.txt");
} catch (error) {
  console.error("ClearProxy Error:", error.message);
}

Complete Example

This example demonstrates a full workflow: initialization, checking with real-time progress, using custom validation, and saving results.

import { ClearProxy } from "clearproxy";
import fs from "fs";

async function main() {
  // 1. Initialize the client
  const client = new ClearProxy("clearpx_yourkey");

  try {
    console.log("Starting proxy check...");

    // 2. Perform the check with all features enabled
    const result = await client.check("proxies.txt", {
      region: "us1",
      timeout: 5000,
      onProgress: (event) => {
        console.log(`[${event.progress}%] ${event.details.message}...`);
      },
      customUrls: [
        {
          url: "https://discord.com",
          requiredStatusCodes: [200, 301, 302]
        }
      ]
    });

    // 3. Process the results
    console.log(`\nCheck Complete!`);
    console.log(`Total Working: ${result.working.length}`);

    // 4. Filter and export specific results
    const discordProxies = client.filterByCustomUrl(result, "https://discord.com");
    console.log(`Discord Valid: ${discordProxies.length}`);

    if (discordProxies.length > 0) {
      const output = client.export(discordProxies, "txt", true);
      fs.writeFileSync("discord_working.txt", output);
      console.log("Saved discord_working.txt");
    }

    // 5. Check remaining balance
    const info = await client.me();
    console.log(`Remaining Checks: ${info.user.checks}`);

  } catch (error) {
    console.error("Workflow Failed:", error.message);
  }
}

main();

Getting started

Rest API

SDKs

Installation & Setup

Validating Proxies

`client.check(file, options)`

Configuration Options

Basic Example

Real-Time Progress Tracking

Implementation

Job ID Management

Advanced Validation (Custom URLs)

Usage

Helper Methods

`client.getCustomUrlSummary(result)`

`client.filterByCustomUrl(result, url)`

Utility Methods

Exporting Results

`client.export(proxies, format, auth)`

Account & API Info

Response Structure

Standard Response

Custom URL Response

Error Handling

Complete Example

​Installation & Setup

​Validating Proxies

​client.check(file, options)

​Configuration Options

​Basic Example

​Real-Time Progress Tracking

​Implementation

​Job ID Management

​Advanced Validation (Custom URLs)

​Usage

​Helper Methods

​client.getCustomUrlSummary(result)

​client.filterByCustomUrl(result, url)

​Utility Methods

​Exporting Results

​client.export(proxies, format, auth)

​Account & API Info

​Response Structure

​Standard Response

​Custom URL Response

​Error Handling

​Complete Example

Installation & Setup

Validating Proxies

`client.check(file, options)`

Configuration Options

Basic Example

Real-Time Progress Tracking

Implementation

Job ID Management

Advanced Validation (Custom URLs)

Usage

Helper Methods

`client.getCustomUrlSummary(result)`

`client.filterByCustomUrl(result, url)`

Utility Methods

Exporting Results

`client.export(proxies, format, auth)`

Account & API Info

Response Structure

Standard Response

Custom URL Response

Error Handling

Complete Example