Documentation
Complete guide to setting up website monitoring with PingZen. API documentation, code examples, and best practices.
Monitor SOCKS5 proxy servers with protocol-level health checks and optional authentication verification. PingZen performs a real SOCKS5 handshake (RFC 1928) — not just a TCP port check — to verify your proxy is truly working.
What It Is For
Public proxies and proxy pools
Telegram proxies, pools of entry points, anything real people connect through. Put a monitor on each entry point and the list shows you which one stopped answering and how fast the rest are.
Corporate proxies behind a login
PingZen performs a real SOCKS5 greeting and, if you turn it on, a username and password login (RFC 1929). An open port 1080 proves neither of those.
ssh -D tunnels, and a check before production traffic goes through
The second check level sends a CONNECT through the proxy out to a target address — the same thing curl --socks5 does. That shows traffic really flows through, not just that the connection was accepted.
What It Is Not For
This monitor speaks SOCKS5. For a different question, pick a different monitor:
| You want to know | Use instead |
|---|---|
| Is an HTTP or HTTPS proxy working? | Not supported — this check performs a SOCKS5 handshake, which an HTTP proxy does not answer |
| Is a Telegram MTProxy working? | MTProxy monitor — a different protocol entirely |
| Is the site behind the proxy up? | An HTTP monitor pointed at the site. The proxy-through test proves the proxy can route, not that the destination is healthy |
| Does the proxy’s TLS certificate expire soon? | TLS/SSL certificate monitor |
How It Works
- PingZen connects to your SOCKS5 proxy via TCP
- Sends a SOCKS5 greeting to verify the server speaks SOCKS5 protocol
- If authentication is configured, performs username/password auth (RFC 1929)
- Optionally sends a CONNECT request through the proxy to verify it can route traffic
- Reports status, response time, and any errors with human-readable messages
Check Levels
PingZen offers two levels of SOCKS5 verification:
Level 1: Greeting + Auth
Verifies the server is a real SOCKS5 proxy and authentication works. Fast (~50-100ms). Sufficient for most use cases.
Level 2: Proxy-Through
Additionally tests that the proxy can route traffic by sending a CONNECT request through the proxy — similar to running curl --socks5 user:pass@host:port https://api.ipify.org. More thorough (~200-500ms).
Configuration
Proxy Address
SOCKS5 proxy address. Format: hostname:port or IP:port. Default port: 1080 (IANA standard).
Require Authentication
Enable if your proxy requires username/password authentication (RFC 1929).
Username
SOCKS5 username (shown when authentication is enabled). Max 255 characters per RFC 1929.
Password
SOCKS5 password (shown when authentication is enabled). Max 255 characters per RFC 1929.
Test Target
Optional host:port for proxy-through test (Level 2). Example: google.com:80. Leave empty for Level 1 check only.
Why SOCKS5 Instead of TCP?
A simple TCP check only verifies the port is open. SOCKS5 protocol check goes deeper — it performs a real handshake and can detect failures that TCP misses:
| Scenario | TCP | SOCKS5 |
|---|---|---|
| Port open, but wrong service running | UP | DOWN: Not a SOCKS5 proxy |
| Proxy accepts TCP, but auth is broken | UP | DOWN: Authentication failed |
| Proxy running, but can't route traffic | UP | DOWN: Network unreachable |
| Proxy crashed, systemd holds socket | UP | DOWN: Unexpected EOF |
| Proxy healthy and working | UP | UP |
Error Codes
When a SOCKS5 check fails, PingZen reports specific error codes from the SOCKS5 protocol (RFC 1928):
| Code | Meaning |
|---|---|
| 0x00 | Succeeded — proxy is working correctly |
| 0x01 | General SOCKS server failure — internal proxy error. E.g., proxy process crashed or misconfigured. |
| 0x02 | Connection not allowed by ruleset — proxy firewall blocking. E.g., ACL denies your IP or target domain. |
| 0x03 | Network unreachable — proxy cannot reach the target network. E.g., proxy has no internet access. |
| 0x04 | Host unreachable — target host is down. E.g., Telegram servers are offline in your region. |
| 0x05 | Connection refused — target port is closed. E.g., target service is not running. |
| 0x06 | TTL expired — routing issue. E.g., too many hops between proxy and target. |
| 0x07 | Command not supported — proxy doesn't support CONNECT. E.g., proxy only supports BIND. |
| 0x08 | Address type not supported — proxy doesn't handle this address format. E.g., no IPv6 support. |
Key Features
- Protocol-level verification (not just TCP port check)
- RFC 1928 compliant SOCKS5 handshake
- Username/password authentication (RFC 1929)
- Optional proxy-through test with configurable target
- Human-readable error messages for all SOCKS5 reply codes
- SSRF protection — private IP targets are blocked
- Zero external dependencies — pure Python asyncio sockets
- Works with Dante, 3proxy, SSH tunnels, and other SOCKS5 servers
Common Questions
What protocols can I monitor?
PingZen supports 23 protocols: HTTP/HTTPS, WebSocket (WS/WSS), TCP, UDP, ICMP Ping, gRPC, DNS, WHOIS, TLS/SSL certificates, Email (SMTP/IMAP/POP3), FTP/FTPS, DNSBL, PageSpeed, SOCKS5, MTProxy, API Check, and Transaction. You can monitor websites, APIs, servers, databases, and any network service.
How fast can I get alerts?
Telegram alerts are delivered within 1-2 seconds of detection. Slack and Discord notifications arrive almost instantly. You can configure multiple alert channels for redundancy.
Can I organize monitors by project?
Yes! PingZen supports workspaces, which let you organize monitors by project, environment, or team. Each workspace can have its own alert configurations and team members.
Is there an API for automation?
Absolutely. PingZen provides a full REST API with OpenAPI documentation. You can create, update, and delete monitors programmatically.
How do status pages work?
Status pages are public, branded pages showing your services' uptime. You can display real-time status and allow customers to subscribe for updates.
What happens if I reach my monitor limit?
We'll notify you when approaching your limit. You can pause some monitors or contact us for increased capacity. We never stop monitoring without warning, ensuring your critical services stay protected.
Ready to stop missing downtime?
Join thousands of teams who trust PingZen. Setup takes 30 seconds.