Proxies

Surfsky offers three ways to handle proxies for your browser automation needs. This guide covers each option and helps you choose the right approach for your use case.

Quick Start

Default Behavior

When you don't specify a proxy parameter, Surfsky automatically assigns a shared proxy to your browser session. While convenient for quick testing, shared proxies have limitations for production use.

# No proxy specified = shared proxy assigned
curl -X POST 'https://api-public.surfsky.io/profiles/one_time' \
  -H 'X-Cloud-Api-Token: YOUR_API_TOKEN' \
  -d '{"fingerprint": {"os": "win"}}'

Using Your Own Proxy

For better control and performance, provide your own proxy URL:

curl -X POST 'https://api-public.surfsky.io/profiles/one_time' \
  -H 'X-Cloud-Api-Token: YOUR_API_TOKEN' \
  -d '{
    "fingerprint": {"os": "win"},
    "proxy": "socks5://user:[email protected]:1080"
  }'

Using Surfsky Proxies

After setting up Surfsky proxy access (contact support), use geolocation-based selection:

curl -X POST 'https://api-public.surfsky.io/profiles/one_time' \
  -H 'X-Cloud-Api-Token: YOUR_API_TOKEN' \
  -d '{
    "fingerprint": {"os": "win"},
    "proxy": {
      "country": "us",
      "state": "california",
      "city": "los-angeles"
    }
  }'

Proxy Options Comparison

Option	Best For	Setup Required	Cost
Shared Proxies	Quick tests, development	None	Free (included)
Your Own Proxies	Full control, existing infrastructure	Proxy credentials	Browser time only
Surfsky Proxies	Production, geo-targeting	Contact support	Browser time + proxy traffic

Shared Proxies (Default)

When no proxy is specified, Surfsky assigns a shared proxy from our pool.

Limitations:

• Multiple users may share the same IP
• Rate limits apply across all users
• Not recommended for sites with strict anti-bot measures
• IP reputation may vary

Good for:

• Development and testing
• Low-volume scraping
• Learning the API

Using Your Own Proxies

Bring your existing proxy infrastructure to Surfsky. Simply provide the proxy URL when creating or starting a profile.

Supported Formats

# SOCKS5
"proxy": "socks5://username:[email protected]:1080"

# HTTP/HTTPS
"proxy": "http://username:[email protected]:8080"

# SSH
"proxy": "ssh://user:[email protected]:22"

# Shadowsocks
"proxy": "ss://method:[email protected]:8388"
# Example: ss://chacha20-ietf-poly1305:[email protected]:8388

Shadowsocks Methods

Supported encryption methods for Shadowsocks:

• chacha20-ietf-poly1305 (recommended)
• aes-256-gcm
• aes-128-gcm
• 2022-blake3-aes-128-gcm
• 2022-blake3-aes-256-gcm
• 2022-blake3-chacha20-poly1305

OpenVPN Configuration

For OpenVPN, use the open_vpn parameter instead:

{
  "open_vpn": {
    "config": "client\ndev tun\nproto udp\nremote vpn.example.com 1194\n...",
    "username": "vpn_user",
    "password": "vpn_pass"
  }
}

WireGuard Configuration

For WireGuard VPN connections, use the wireguard parameter:

{
  "wireguard": {
    "private_key": "your_base64_private_key",
    "address": ["10.0.0.2/32"],
    "peers": [
      {
        "public_key": "server_base64_public_key",
        "endpoint": "vpn.example.com:51820",
        "allowed_ips": ["0.0.0.0/0", "::/0"]
      }
    ]
  }
}

WireGuard Parameters

Parameter	Required	Type	Description
private_key	Yes	string	Base64-encoded WireGuard private key
address	Yes	array	List of IP addresses for the interface (e.g., ["10.0.0.2/32"])
peers	Yes	array	List of WireGuard peer configurations
mtu	No	integer	MTU size (default: 1408)

Peer Parameters

Parameter	Required	Type	Description
public_key	Yes	string	Base64-encoded peer public key
endpoint	Yes	string	Peer endpoint in host:port format
allowed_ips	No	array	Allowed IP ranges (default: ["0.0.0.0/0", "::/0"])
pre_shared_key	No	string	Optional pre-shared key for additional security
persistent_keepalive_interval	No	integer	Keepalive interval in seconds

Generating WireGuard Keys

# Generate private key
wg genkey

# Generate public key from private key
echo "private_key" | wg pubkey

Note: You can only use one of proxy, open_vpn, or wireguard at a time.

Surfsky Proxies

Premium proxy infrastructure with intelligent geo-targeting. Perfect for production workloads requiring reliable, rotating IPs.

Setup Process

1. Contact Support - Email [email protected] to enable proxy access
2. Get Credentials - Receive your proxy provider credentials
3. Start Using - Use geolocation parameters instead of proxy URLs

How It Works

Instead of managing proxy URLs, simply specify the location:

{
  "proxy": {
    "country": "us",     // Required: 2-letter country code
    "state": "texas",    // Optional: state/region name
    "city": "houston"    // Optional: city name
  }
}

The system automatically:

• Selects an appropriate proxy from the pool
• Handles rotation and session management
• Ensures IP quality and availability

Available Locations

Check available locations using our API:

# Get countries
GET /proxies/countries

# Get regions/states
GET /proxies/regions

# Get cities
GET /proxies/cities

# Get hierarchical structure
GET /proxies/nested

See Proxies API Reference for complete documentation.

Monitor Usage

Track your proxy data consumption:

GET /proxies/remaining-data

Response shows remaining balance in bytes and GB:

{
  "success": true,
  "data": {
    "remaining_bytes": 10737418240,
    "remaining_gb": 10.0
  }
}

Proxy Features

Residential IPs

• 50M+ IP pool across 190+ countries
• Authentic residential connections
• High trust scores on target sites

Rotation Control

• Session duration: 1-60 minutes
• Sticky sessions for consistent IPs
• Automatic rotation on failure

Performance Metrics

• 95%+ success rate
• 200-500ms average latency
• 5-15 Mbps typical bandwidth

Pricing

For proxy pricing information and volume discounts, please contact our sales team. We offer competitive rates and custom packages based on your usage requirements.