For developers

Proxy API

A REST API for your own software, scrapers and reseller panels: browse the catalog and stock, buy proxies from your balance, export lists in the format you need, renew and replace. Everything you can do in your account is one request away. Get your API key in your account, under «Account».

Base URL

https://truesocks.net/api/v1

Authorization

Authorization: Bearer <key>

For GET requests you can pass the key as a ?key=<key> parameter, but the header is safer: the key does not end up in logs and browser history.

Format

POST request bodies are JSON (Content-Type: application/json), responses are JSON in UTF-8. Dates are ISO 8601 in UTC.

Money

Russian rubles. Every amount is returned twice: in rubles (price: 149.5) and in kopecks (price_kopecks: 14950). Do your math in kopecks to avoid rounding errors.

Rate limits

120 requests per minute per key. Above that you get a 429 response. Many 401 and 429 responses in a row from one IP lead to a temporary one-hour IP block.

Quick start

Save your key to an environment variable, buy 2 IPv4 proxies in Germany for 30 days, then export them to a file:

export TRUESOCKS_KEY="your_key"

curl -X POST https://truesocks.net/api/v1/orders \
  -H "Authorization: Bearer $TRUESOCKS_KEY" -H "Content-Type: application/json" \
  -d '{"kind":"ipv4","country":"DE","days":30,"quantity":2}'

curl -H "Authorization: Bearer $TRUESOCKS_KEY" \
  "https://truesocks.net/api/v1/orders/843412/proxies?format=ip:port:user:pass" > proxies.txt

GET/api/v1/catalogCatalog: types, countries, plans and stock

A plan is type × country × term. The price is per unit (IP, GB or channel) for the whole term. stock shows how many can be delivered right now.

Parameter	Type	Description
kind	string	optional: filter by type (ipv4, ipv6, isp, resi, mobile, shared)
country	string	optional: filter by country, two-letter ISO code (DE, US, NL)

Request

curl -H "Authorization: Bearer $TRUESOCKS_KEY" "https://truesocks.net/api/v1/catalog?kind=ipv4&country=DE"

Response

{
  "currency": "RUB",
  "updated_at": "2026-10-23T12:00:00.000Z",
  "kinds": [
    { "id": "ipv4", "name": "Индивидуальные IPv4", "short": "IPv4",
      "tier": "business", "unit": "ip", "description": "...", "has_tariffs": true }
  ],
  "countries": [
    { "code": "DE", "name_ru": "Германия", "name_en": "Germany",
      "region": "Европа", "kinds": ["ipv4"] }
  ],
  "tariffs": [
    { "id": 1042, "kind": "ipv4", "country": "DE", "days": 30,
      "price": 149, "price_kopecks": 14900,
      "old_price": null, "old_price_kopecks": null,
      "min_qty": 1, "max_qty": 1000, "stock": 87, "hit": true }
  ],
  "discounts": [ { "kind": null, "min_qty": 10, "percent": 5 } ]
}

GET/api/v1/balanceBalance

Request

curl -H "Authorization: Bearer $TRUESOCKS_KEY" https://truesocks.net/api/v1/balance

Response

{ "balance": 1520.5, "balance_kopecks": 152050, "currency": "RUB" }

POST/api/v1/ordersBuy proxies

The cost is debited from your balance, and the proxies are delivered instantly in the response. If there are not enough addresses in stock, no order is created and nothing is charged. Specify the plan either by number (tariff_id from the catalog) or by kind + country + days.

Parameter	Type	Description
tariff_id	number	plan ID from /catalog (or kind, country, days)
kind	string	proxy type, e.g. ipv4
country	string	country code, e.g. DE
days	number	term in days, e.g. 30
quantity	number	number of IPs (gigabytes for residential proxies)
protocol	string	socks5 (default) or http
auth	string	login (default): username and password; ip: IP authorization
ips	string or array	for auth=ip: up to 20 comma-separated IPs
auto_renew	true/false	auto-renew for the same term from your balance one hour before expiry
comment	string	optional: your note (up to 200 characters)

Request

curl -X POST https://truesocks.net/api/v1/orders \
  -H "Authorization: Bearer $TRUESOCKS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"ipv4","country":"DE","days":30,"quantity":2,"protocol":"socks5","auto_renew":true}'

Response

HTTP/1.1 201 Created
{
  "order": {
    "num": 843412, "code": "TS-843412", "status": "active",
    "kind": "ipv4", "kind_name": "Индивидуальные IPv4",
    "country": "DE", "country_name": "Германия",
    "days": 30, "quantity": 2, "unit": "ip", "unit_label": "шт.",
    "unit_price": 149, "unit_price_kopecks": 14900, "discount_percent": 0,
    "charge": 298, "charge_kopecks": 29800, "refunded": 0, "refunded_kopecks": 0,
    "protocol": "socks5", "auth": "login", "allowed_ips": [], "auto_renew": true,
    "created_at": "2026-10-23T12:00:00.000Z", "expires_at": "2026-11-22T12:00:00.000Z",
    "proxies_active": 2,
    "proxies": [
      { "lease_id": "cm2x7l0a40001", "host": "185.10.20.31", "port": 8000,
        "http_port": 8000, "socks5_port": 8001,
        "username": "u7Hq", "password": "Kp29xT", "exit_ip": null, "city": null,
        "rotate_url": null, "status": "active", "expires_at": "2026-11-22T12:00:00.000Z" }
    ]
  },
  "balance": 1222.5, "balance_kopecks": 122250
}

GET/api/v1/ordersList orders

Parameter	Type	Description
status	string	active, expired, canceled, pending or all (default all)
limit	number	how many to return, 1-100 (default 50)
offset	number	how many to skip, for pagination

Request

curl -H "Authorization: Bearer $TRUESOCKS_KEY" "https://truesocks.net/api/v1/orders?status=active"

Response

{
  "total": 3, "limit": 50, "offset": 0,
  "orders": [ { "num": 843412, "code": "TS-843412", "status": "active", "kind": "ipv4", "country": "DE",
                "quantity": 2, "expires_at": "2026-11-22T12:00:00.000Z",
                "auto_renew": true, "proxies_active": 2, "...": "..." } ]
}

GET/api/v1/orders/{num}Order with its proxy list

The same fields as on purchase, plus proxies: only the proxies that are active right now (after a replacement, the new ones). {num} is the order number (843412) or the code shown in your account (TS-843412), in all /orders/{num} methods.

Request

curl -H "Authorization: Bearer $TRUESOCKS_KEY" https://truesocks.net/api/v1/orders/843412

Response

{ "order": { "num": 843412, "code": "TS-843412", "status": "active", "...": "...", "proxies": [ ... ] } }

GET/api/v1/orders/{num}/proxiesExport proxies in the format you need

With the format parameter, the response is plain text with one proxy per line, ready to save to a file. Without format, you get JSON.

Parameter	Type	Description
format	string	ip:port:user:pass \| user:pass@ip:port \| ip:port@user:pass \| url \| ip:port
protocol	string	http or socks5: port and scheme for url (defaults to the order protocol)

Request

curl -H "Authorization: Bearer $TRUESOCKS_KEY" \
  "https://truesocks.net/api/v1/orders/843412/proxies?format=url&protocol=socks5" > proxies.txt

Response

Content-Type: text/plain; charset=utf-8

socks5://u7Hq:[email protected]:8001
socks5://Lm3a:[email protected]:8001

POST/api/v1/orders/{num}/renewRenew an order

Debits the cost from your balance and extends the term of all proxies in the order. Addresses and credentials stay the same. Available terms are the plans of the same type and country in /catalog.

Parameter	Type	Description
days	number	how many days to renew for (defaults to the order term)

Request

curl -X POST https://truesocks.net/api/v1/orders/843412/renew \
  -H "Authorization: Bearer $TRUESOCKS_KEY" -H "Content-Type: application/json" \
  -d '{"days":30}'

Response

{
  "order": { "num": 843412, "code": "TS-843412", "expires_at": "2026-12-22T12:00:00.000Z", "...": "..." },
  "renewal": { "days": 30, "charge": 298, "charge_kopecks": 29800 },
  "balance": 924.5, "balance_kopecks": 92450
}

POST/api/v1/orders/{num}/auto-renewTurn auto-renewal on or off

One hour before expiry, the order is renewed for the same term from your balance. If the balance is too low, auto-renewal is turned off and we notify you by e-mail and in Telegram.

Parameter	Type	Description
enabled	true/false	turn on or off

Request

curl -X POST https://truesocks.net/api/v1/orders/843412/auto-renew \
  -H "Authorization: Bearer $TRUESOCKS_KEY" -H "Content-Type: application/json" \
  -d '{"enabled":true}'

Response

{ "num": 843412, "code": "TS-843412", "auto_renew": true }

POST/api/v1/leases/{lease_id}/replaceReplace a proxy that does not work

Free within 24 hours after purchase, up to the number of proxies in the order. Take lease_id from the proxies list. The new proxy has the same country and type, and the term stays the same.

Parameter	Type	Description
reason	string	what is wrong, e.g. «connection timeout» (optional)

Request

curl -X POST https://truesocks.net/api/v1/leases/cm2x7l0a40001/replace \
  -H "Authorization: Bearer $TRUESOCKS_KEY" -H "Content-Type: application/json" \
  -d '{"reason":"timeout"}'

Response

{ "replaced_lease_id": "cm2x7l0a40001", "order": 843412, "order_code": "TS-843412",
  "proxy": { "lease_id": "cm2x9p1b70007", "host": "185.10.20.58", "port": 8000, "...": "..." } }

Errors

On error you get an HTTP status and JSON with a human-readable message and a machine-readable code. The message text is in Russian, so rely on the code field in your logic. Nothing is ever charged when an error occurs.

HTTP/1.1 402 Payment Required
{ "error": "Недостаточно средств на балансе", "code": "insufficient_funds" }

HTTP	code	When
400	bad_request	invalid parameters or the request body is not JSON
401	unauthorized	missing or invalid key, or the account is blocked
402	insufficient_funds	insufficient balance
404	not_found	order or proxy not found (or it belongs to another account)
409	out_of_stock	the requested quantity is out of stock, nothing was charged
422	tariff_unavailable	the plan is no longer sold or this renewal term does not exist
422	invalid_quantity	quantity is outside the allowed min_qty-max_qty range
422	invalid_ips	invalid IP in ips or more than 20 of them
422	order_error	another reason for refusal, see the text in the error field
429	rate_limited	rate limit exceeded
500	internal	error on our side, please retry later

Export formats

format	Example line
ip:port:user:pass	185.10.20.31:8000:u7Hq:Kp29xT
user:pass@ip:port	u7Hq:[email protected]:8000
ip:port@user:pass	185.10.20.31:8000@u7Hq:Kp29xT
url	socks5://u7Hq:[email protected]:8001
ip:port	185.10.20.31:8000 (for IP authorization)

If HTTP and SOCKS5 run on different ports, the port depends on the protocol parameter. In JSON, both ports are returned in the http_port and socks5_port fields. For orders with IP authorization, the username and password are not included in text formats.

Notifications

We notify you about delivery, renewal, failed auto-renewal, upcoming expiry (3 days ahead) and expiry by e-mail and in your linked Telegram. Integration questions go to support: Telegram or [email protected].