Skip to main content

Quick Start

Install the SDK using npm:
npm i clearproxy

Basic Usage

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

const client = new ClearProxy("clearpx_yourkey");

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

  console.log("Summary:", result.summary);
  console.log("Working:", result.working.length);

  // Save to file
  fs.writeFileSync("working.txt", client.export(result.working, "txt", true));
})();

Custom URL Validation

Validate proxies against specific URLs with custom rules:
import { ClearProxy } from "clearproxy";

const client = new ClearProxy("clearpx_yourkey");

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

  // Access custom validation results
  console.log("Custom Validation:", result.custom_url_validation);
  
  // Get summary
  const summary = client.getCustomUrlSummary(result);
  console.log("Overall success rate:", summary.overall_success_rate);
  
  // Filter by specific URL
  const discordProxies = client.filterByCustomUrl(result, "https://discord.com");
  console.log("Discord working proxies:", discordProxies.length);
})();

Configuration Options

OptionTypeDescriptionDefault
regionstringTesting region (us1, eu1, asia1)us1
timeoutnumberTimeout in milliseconds5000
typestringProxy type (http, https, socks4, socks5)http
customUrlsarrayCustom URL validation rules[]

Custom URL Options

FieldTypeRequiredDescription
urlstringTarget URL to test
requiredStatusCodesarrayValid HTTP status codes (default: [200])
requiredTextstringText that must appear in response
caseSensitivebooleanCase-sensitive text matching (default: false)

Methods

check(file, options)

Check proxies from a file. Parameters:
  • file (string) - Path to proxy file
  • options (object) - Configuration options
Returns: Promise with check results Example:
const result = await client.check("proxies.txt", {
  region: "us1",
  timeout: 5000,
  type: "http",
  customUrls: [
    { url: "https://example.com", requiredStatusCodes: [200] }
  ]
});

export(proxies, format, auth)

Export proxies to different formats. Parameters:
  • proxies (array) - Array of proxy objects
  • format (string) - Export format (txt, json, csv)
  • auth (boolean) - Include authentication
Returns: Formatted string Example:
const exported = client.export(result.working, "txt", true);
fs.writeFileSync("working.txt", exported);

filterByCustomUrl(result, url)

Filter proxies that passed validation for a specific URL. Parameters:
  • result (object) - Result object from check() method
  • url (string) - URL to filter by
Returns: Array of successful proxies Example:
const discordProxies = client.filterByCustomUrl(result, "https://discord.com");
console.log(`Found ${discordProxies.length} working Discord proxies`);

getCustomUrlSummary(result)

Get summary of custom URL validation results. Parameters:
  • result (object) - Result object from check() method
Returns: Summary object with validation statistics Example:
const summary = client.getCustomUrlSummary(result);
console.log(`Total URLs: ${summary.total_urls}`);
console.log(`Success rate: ${summary.overall_success_rate}`);
console.log(`Per-URL:`, summary.per_url);
Response:
{
  total_urls: 2,
  total_proxies_tested: 150,
  total_success: 210,
  total_failed: 90,
  overall_success_rate: "70.00%",
  per_url: [
    {
      url: "https://discord.com",
      success_count: 120,
      failed_count: 30,
      success_rate: "80.00%"
    },
    {
      url: "https://www.google.com",
      success_count: 90,
      failed_count: 60,
      success_rate: "60.00%"
    }
  ]
}

me()

Get account information and quota. Returns: Promise with user account data Example:
const account = await client.me();
console.log(`Checks remaining: ${account.user.checks}`);

regions()

Get available checking regions. Returns: Promise with regions list Example:
const regions = await client.regions();
console.log("Available regions:", regions);

health()

Check API health status. Returns: Promise with health status Example:
const health = await client.health();
console.log("API status:", health.status);

Response Structure

Standard Check Response

{
  summary: {
    total_working: 150,
    countries: { "United States": 100, "Germany": 30, "United Kingdom": 20 },
    anonymity_levels: { elite: 120, anonymous: 20, transparent: 10 }
  },
  metadata: {
    user: {
      email: "[email protected]",
      checks_used: 500,
      remaining_checks: 4500
    },
    region_used: "us1",
    proxy_type: "http",
    timeout_used: "5000ms",
    total_checked: 500,
    processing_time: "8.32s"
  },
  proxies: [
    {
      proxy: {
        host: "67.67.67.67",
        port: 80,
        hasAuth: false
      },
      status: "working",
      statusCode: 200,
      responseTime: "1549.48 ms",
      anonymity: "anonymous",
      origin: "67.67.67.67",
      country: "ID",
      location: "Jakarta",
      isp: "Six Seven LLC",
      asn: 6767
    }
  ],
  working: [...], // Array of working proxies
  failed: [...],  // Array of failed proxies
  custom_url_validation: null // or validation results if customUrls provided
}

Custom URL Validation Response

{
  // ... standard response fields above ...
  custom_url_validation: {
    summary: {
      total_urls_tested: 2,
      total_proxies_tested: 150,
      processing_time: "8.45s"
    },
    per_url_summary: [
      {
        url: "https://discord.com",
        total_tested: 150,
        success_count: 120,
        failed_count: 30,
        success_rate: "80.00%",
        requiredStatusCodes: [200, 301, 302],
        successful_proxies: [
          {
            proxy: "192.168.1.1:8080",
            status: "working",
            statusCode: 200,
            responseTime: "250ms"
          }
        ],
        failed_proxies: [...]
      },
      {
        url: "https://www.google.com",
        total_tested: 150,
        success_count: 90,
        failed_count: 60,
        success_rate: "60.00%",
        requiredStatusCodes: [200],
        requiredText: "Search",
        caseSensitive: false,
        successful_proxies: [...],
        failed_proxies: [...]
      }
    ]
  }
}

Examples

Basic Proxy Check

import { ClearProxy } from "clearproxy";

const client = new ClearProxy("clearpx_yourkey");

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

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

Discord Proxy Validation

const result = await client.check("proxies.txt", {
  region: "us1",
  customUrls: [
    {
      url: "https://discord.com",
      requiredStatusCodes: [200, 301, 302]
    }
  ]
});

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

// Export to file
const exported = client.export(discordProxies, "txt", true);
fs.writeFileSync("discord-proxies.txt", exported);

Multiple URL Validation

const result = await client.check("proxies.txt", {
  region: "us1",
  timeout: 6000,
  customUrls: [
    { url: "https://discord.com", requiredStatusCodes: [200, 301, 302] },
    { url: "https://twitter.com", requiredStatusCodes: [200] },
    { url: "https://instagram.com", requiredStatusCodes: [200, 302] }
  ]
});

// Get overall summary
const summary = client.getCustomUrlSummary(result);
console.log(`Overall success rate: ${summary.overall_success_rate}`);

// Get proxies for each platform
const discordProxies = client.filterByCustomUrl(result, "https://discord.com");
const twitterProxies = client.filterByCustomUrl(result, "https://twitter.com");
const instagramProxies = client.filterByCustomUrl(result, "https://instagram.com");

console.log(`Discord: ${discordProxies.length}`);
console.log(`Twitter: ${twitterProxies.length}`);
console.log(`Instagram: ${instagramProxies.length}`);

Error Handling

try {
  const result = await client.check("proxies.txt", {
    region: "us1",
    customUrls: [
      { url: "https://example.com" }
    ]
  });
  
  console.log("Check completed:", result.summary);
} catch (error) {
  if (error.message.includes('API Error')) {
    console.error("API error:", error.message);
  } else if (error.message.includes('No proxies found')) {
    console.error("Invalid proxy file");
  } else {
    console.error("Unexpected error:", error);
  }
}