# Ludax proxy authentication: guide for AI assistants

> Give this file to your AI assistant (ChatGPT, Claude, Cursor, Copilot) and it can set up Ludax proxies in any language or tool. Human-readable version: https://ludaxproxy.com/docs/proxy-authentication

You are helping a developer log in to Ludax residential proxies. Ludax uses standard Basic proxy authentication: a username and a password, sent by the client with every connection. There is no SDK, no API key and no IP allowlist. Follow the rules below exactly; they come from the gateways' behaviour.

## Connection string

```
http://<PREFIX>-<ACCOUNT>[-AE-<PROFILE>]:<PASSWORD>[-session-<TOKEN>-time-<MINUTES>[-sameip]][-country-<cc>[-state-<code>[-city-<name>]]]@<GATEWAY>
```

- **Username:** the product prefix (`resi-` or `premi-`), then the developer's account name from the dashboard (Generate), for example `resi-lx_k3m9q2p7xa`. The account name is `lx_` and 10 characters, the same for every plan. Never invent one: ask the developer, or use a placeholder such as `YOUR_USERNAME`.
- **Password:** the plan's own password (16 hexadecimal characters, one per plan), then the options, in this order: `-session-<TOKEN>-time-<MINUTES>`, then `-country-<cc>`, `-state-<code>`, `-city-<name>` (and `-asn-<number>`, `-os-<device>` on Premium). Use a placeholder such as `YOUR_PASSWORD`, or read it from an environment variable. Never put options in the username.
- **Sessions:** without `-session-` every new connection leaves from a new IP. `-session-<TOKEN>-time-<MINUTES>` keeps one IP for every connection that sends the same token (TOKEN: 3 to 24 letters or digits; MINUTES: 1 to 1000; Premium holds a session at least 3 minutes). Always send `-time-`: without it a session lasts 1 minute. On the TLS gateways add `-sameip` after the time, or only the browser profile is held.
- **Location:** `-country-` takes a lower-case ISO code (`us`, `de`, `jp`); `-state-` and `-city-` follow it (`-country-de-state-by-city-munich`); on Premium the state is its name without spaces (`-country-us-state-illinois-city-chicago`), in any of 219 countries. `-os-` (Premium) takes `windows`, `android`, `ios` or `macos`. With no free exit in that city or region the request falls back to the country. Codes for every country: https://ludaxproxy.com/locations
- **The port picks the product:** a plan's password works only on its own product's gateway, and the prefix must match it.
- Ludax credentials contain only letters, digits, `_` and `-`; values with `@`, `:` or `/` must be percent-encoded in a URL.
- `-AE-<PROFILE>` (for example `-AE-chrome154`) goes at the end of the username on the TLS gateways only, which also need the Ludax CA: https://ludaxproxy.com/downloads/ludax-ca.crt

## Products and gateways in force

| Product | Username prefix | HTTP and HTTPS | SOCKS5 | Browser TLS | Sticky session |
| --- | --- | --- | --- | --- | --- |
| Residential | `resi-` | `gw.ludaxproxy.com:7777` | `gw.ludaxproxy.com:7575` | No | up to 1000 min |
| Residential TLS | `resi-` | `gw.ludaxproxy.com:9999` | none | Yes | up to 1000 min |
| Residential Premium | `premi-` | `gw.ludaxproxy.com:8080` | `gw.ludaxproxy.com:1080` | No | up to 1000 min |
| Residential Premium TLS | `premi-` | `gw.ludaxproxy.com:8081` | none | Yes | up to 1000 min |

## Tool-specific rules

- **curl:** `curl -x "http://USER:PASS@host:port" URL`, or `-x host:port -U USER:PASS`. SOCKS5: `--socks5-hostname`.
- **Environment variables:** `HTTP_PROXY` and `HTTPS_PROXY` with the full URL; curl, Python requests and Go read them.
- **Java HttpClient:** set `System.setProperty("jdk.http.auth.tunneling.disabledSchemes", "")` before the first request (or `-Djdk.http.auth.tunneling.disabledSchemes=`), and pass the login through an `Authenticator`; without the property Java will not send Basic proxy credentials inside an HTTPS tunnel and gets 407.
- **C# HttpClient:** `new WebProxy("http://host:port") { Credentials = new NetworkCredential(user, pass) }` in an `HttpClientHandler`.
- **Node.js:** built-in fetch ignores `agent`; use undici's `ProxyAgent` as `dispatcher`: https://ludaxproxy.com/docs/nodejs.md
- **Chrome / Selenium:** `--proxy-server` takes no credentials; answer the login through DevTools: https://ludaxproxy.com/docs/selenium.md
- **Playwright:** `proxy: { server, username, password }`: https://ludaxproxy.com/docs/playwright.md

## Check the connection

`GET https://api.ludaxproxy.com/whoami` through the proxy returns JSON: `ip`, `country` (full name), `type`, `tls_profile` (the browser the TLS handshake matches) and `latency_ms`. Add `?full=1` for a `debug` block with the JA4 fingerprint, the HTTP/2 fingerprint, the ASN and the User-Agent that arrived.

## Errors

| What the client sees | Meaning | What to do |
| --- | --- | --- |
| `407 Proxy Authentication Required` | Wrong username or password, a prefix that does not match the gateway, options in the username, another plan's password, or a plan used up or expired | Stop and fix the credentials. Never retry a 407 in a loop |
| The connection closes with no answer | 30 failed logins in 5 minutes block the client IP for 10 minutes | Fix the credentials, wait 10 minutes. Requests without credentials (the normal first challenge) do not count |
| `403 Forbidden` with `X-Ludax-Blocked: blocklist` | The site is on the plan's Block Domain list (dashboard, Generate → Block Domain) | Do not retry; the developer removes the entry if the site is needed |
| `502 Bad Gateway` | The exit dropped or could not reach the site | Retry with a short backoff |

## Tested examples

The same code as on https://ludaxproxy.com/docs/proxy-authentication. Replace `lx_k3m9q2p7xa` and `YOUR_PASSWORD` with the developer's credentials.

### curl

```bash
# the whole login in the proxy URL
curl -x "http://resi-lx_k3m9q2p7xa:YOUR_PASSWORD-country-us@gw.ludaxproxy.com:7777" \
     https://api.ludaxproxy.com/whoami

# or the login on its own
curl -x "http://gw.ludaxproxy.com:7777" -U "resi-lx_k3m9q2p7xa:YOUR_PASSWORD-country-us" \
     https://api.ludaxproxy.com/whoami
```

### Environment variables

```bash
# macOS and Linux (Windows PowerShell: $env:HTTPS_PROXY = "http://...")
export HTTP_PROXY="http://resi-lx_k3m9q2p7xa:YOUR_PASSWORD-country-us@gw.ludaxproxy.com:7777"
export HTTPS_PROXY="$HTTP_PROXY"

# curl, Python requests, Go and many command-line tools now use the proxy on their own
curl https://api.ludaxproxy.com/whoami
```

### Python (requests)

```python
import requests  # pip install requests

proxy = "http://resi-lx_k3m9q2p7xa:YOUR_PASSWORD-country-us@gw.ludaxproxy.com:7777"

r = requests.get("https://api.ludaxproxy.com/whoami",
                 proxies={"http": proxy, "https": proxy}, timeout=30)
print(r.json())
```

### Node.js (undici)

```javascript
import { fetch, ProxyAgent } from "undici"; // npm install undici

const proxy = new ProxyAgent("http://resi-lx_k3m9q2p7xa:YOUR_PASSWORD-country-us@gw.ludaxproxy.com:7777");

const res = await fetch("https://api.ludaxproxy.com/whoami", { dispatcher: proxy });
console.log(await res.json());
```

### Go

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"net/url"
)

func main() {
	proxy, _ := url.Parse("http://resi-lx_k3m9q2p7xa:YOUR_PASSWORD-country-us@gw.ludaxproxy.com:7777")
	client := &http.Client{Transport: &http.Transport{Proxy: http.ProxyURL(proxy)}}

	resp, err := client.Get("https://api.ludaxproxy.com/whoami")
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}
```

### PHP (cURL)

```php
<?php
$ch = curl_init("https://api.ludaxproxy.com/whoami");
curl_setopt_array($ch, [
    CURLOPT_PROXY => "http://gw.ludaxproxy.com:7777",
    CURLOPT_PROXYUSERPWD => "resi-lx_k3m9q2p7xa:YOUR_PASSWORD-country-us",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
echo curl_exec($ch);
```

### Java (HttpClient)

```java
import java.net.*;
import java.net.http.*;

public class Request {
  public static void main(String[] args) throws Exception {
    // Java turns Basic proxy login off for HTTPS tunnels by default: turn it back on first
    System.setProperty("jdk.http.auth.tunneling.disabledSchemes", "");

    URI gateway = URI.create("http://gw.ludaxproxy.com:7777");
    HttpClient client = HttpClient.newBuilder()
        .proxy(ProxySelector.of(new InetSocketAddress(gateway.getHost(), gateway.getPort())))
        .authenticator(new Authenticator() {
          @Override
          protected PasswordAuthentication getPasswordAuthentication() {
            return new PasswordAuthentication(
                "resi-lx_k3m9q2p7xa", "YOUR_PASSWORD-country-us".toCharArray());
          }
        })
        .build();

    HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.ludaxproxy.com/whoami")).build();
    System.out.println(client.send(request, HttpResponse.BodyHandlers.ofString()).body());
  }
}
```

### C# (HttpClient)

```csharp
using System.Net;

var handler = new HttpClientHandler
{
    Proxy = new WebProxy("http://gw.ludaxproxy.com:7777")
    {
        Credentials = new NetworkCredential("resi-lx_k3m9q2p7xa", "YOUR_PASSWORD-country-us"),
    },
};
using var client = new HttpClient(handler);
Console.WriteLine(await client.GetStringAsync("https://api.ludaxproxy.com/whoami"));
```

## Plans and help

- Prepaid, no subscription: 1 GB of Residential Proxies costs $0.99. The smallest plan is the test; there is no free trial. Every plan: https://ludaxproxy.com/pricing
- Credentials: dashboard, Generate (https://ludaxproxy.com/dashboard). A plan's password can be reset there.
- Full reference: https://ludaxproxy.com/docs. Whole site for AI: https://ludaxproxy.com/llms.txt
- Support: Telegram https://t.me/LudaxProxy, email support@ludaxproxy.com.