Static proxies for your customers: purchase, renewal and UDP add-ons.
Get a key in the Proxy Soxy bot → proxy management. Check access, request the catalogue and price, confirm a purchase and retrieve credentials. The main contract is /v1/me/static/*: purchases use your Proxy Soxy balance after you explicitly enable API spending. You handle your customers' retail payments and markup.
Spending through this contract currently requires an RU account with a RUB balance. English documentation and Accept-Language: en do not enable USD payments. Static UDP can be purchased together with proxies or added later. These methods do not sell rotating traffic.
Amounts are integers in minor currency units: 1500 = RUB 15.00. Examples are not a price list. Store operation_id and consider fulfilment successful only when state=COMPLETED. Ignore unknown response fields and preserve identifiers exactly.
From key to result
Open the Proxy Soxy bot → proxy management → Help → API & integrations → General API → Create key. The RU entry is «Управление прокси»; the EN proxy-delivery button is “My proxies”. Store the secret on your integration server. Reopening the key screen shows the key identifier, not the secret.
Call GET https://api.soxydata.com/v1/whoami with Authorization: Bearer <key>. A regular bot key returns role: "client", environment: "live", sandbox: null.
On that key screen, select «Разрешить покупки…» (Allow purchases, in the RU bot) and confirm permission to buy using your Proxy Soxy balance. Issuing a key alone does not permit charges. Top up through the existing bot flow.
Read /me/static/catalog and /me/static/balance. Choose a country, term and quantity from the current catalogue. Request /me/static/quotes and show its total to the buyer.
Persist quote_id and your stable Idempotency-Key, then call /me/static/confirm. This is the purchase step. Store the returned operation_id, starting with op-.
Wait for state: "COMPLETED". Read /me/static/proxies, using the same customer_ref if provided at purchase, and select the operation’s proxy_ids. Reconcile an uncertain result instead of buying again.
Purchases, renewals and UDP through this contract currently require an RU account with a RUB balance. English text or Accept-Language: en does not change the currency. Omitting UDP keeps the ordinary purchase behavior. No public virtual-money sandbox is available.
For purchases use the RU bot and its account key. The EN bot supports key management and access reads, but its spending-permission button is hidden because new USD spending is unavailable. The bot determines the screen language; enable spending using the Russian button in the RU bot.
Safe first check
These samples make only GET requests: key verification, catalogue and balance. Enable API spending before the last two to establish the account binding. They do not buy, renew or print credentials.
# 1. Verify the regular bot-issued key.
: "${API_KEY:?Set API_KEY in your server environment}"
BASE="https://api.soxydata.com/v1"
curl --fail-with-body --max-time 30 -sS "$BASE/whoami" -H "Authorization: Bearer $API_KEY"
# 2. Catalogue — after enabling API spending.
curl --fail-with-body --max-time 30 -sS "$BASE/me/static/catalog" -H "Authorization: Bearer $API_KEY"
# 3. Read balance; no purchase.
curl --fail-with-body --max-time 30 -sS "$BASE/me/static/balance" -H "Authorization: Bearer $API_KEY"
<?php
// PHP 7.4+ with the curl extension.
$key = getenv('API_KEY');
if (!$key) throw new RuntimeException('Set API_KEY on your server');
function getApi(string $path): array {
global $key;
$ch = curl_init('https://api.soxydata.com/v1' . $path);
curl_setopt_array($ch, [CURLOPT_HTTPHEADER=>["Authorization: Bearer $key"],
CURLOPT_RETURNTRANSFER=>true, CURLOPT_TIMEOUT=>30, CURLOPT_FOLLOWLOCATION=>false]);
$raw = curl_exec($ch); $code = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($raw === false || $code !== 200) throw new RuntimeException("API HTTP $code");
return json_decode($raw, true);
}
// 1. Verify the regular bot-issued key.
echo json_encode(getApi('/whoami')), "\n";
// 2. Catalogue — after enabling API spending.
echo json_encode(getApi('/me/static/catalog')), "\n";
// 3. Read balance; no purchase.
echo json_encode(getApi('/me/static/balance')), "\n";
// Node.js 18+ (built-in fetch). Key and address come from the environment or the constants below.
const BASE = 'https://api.soxydata.com/v1';
const KEY = process.env.API_KEY;
if (!KEY) throw Error('Set API_KEY on your server');
async function get(path) {
const r = await fetch(BASE + path, {redirect:'error', signal:AbortSignal.timeout(30000),
headers:{Authorization:`Bearer ${KEY}`}});
const data = await r.json();
if (!r.ok) throw Error(`${r.status} ${data.error?.code || 'request_failed'}`);
return data;
}
(async () => {
// 1. Verify the regular bot-issued key.
console.log(await get('/whoami'));
// 2. Catalogue — after enabling API spending.
console.log(await get('/me/static/catalog'));
// 3. Read balance; no purchase.
console.log(await get('/me/static/balance'));
})().catch(e => { console.error(e.message); process.exitCode=1; });
# Python 3.8+, standard library only.
import json, os, urllib.request, urllib.error
BASE = "https://api.soxydata.com/v1"
KEY = os.environ["API_KEY"]
class NoRedirect(urllib.request.HTTPRedirectHandler):
def redirect_request(self, *args):
raise RuntimeError("redirect refused")
opener = urllib.request.build_opener(NoRedirect())
def get(path):
req = urllib.request.Request(BASE + path, headers={"Authorization":"Bearer " + KEY})
try:
with opener.open(req, timeout=30) as r:
return json.load(r)
except urllib.error.HTTPError as e:
raise RuntimeError("API HTTP " + str(e.code)) from None
# 1. Verify the regular bot-issued key.
print(json.dumps(get("/whoami")))
# 2. Catalogue — after enabling API spending.
print(json.dumps(get("/me/static/catalog")))
# 3. Read balance; no purchase.
print(json.dumps(get("/me/static/balance")))
Quote and purchase
All values below are examples. Select country, term and quantity from your catalogue. Your server assigns customer_ref; it is not a Telegram ID.
POST /v1/me/static/quotes
Authorization: Bearer <API-key>
Content-Type: application/json
{"kind":"purchase","country":"US","count":2,"days":30,"customer_ref":"buyer-42"}
The quote returns quote_id, amount_minor, currency and expires_at. Amounts are in kopeks; the quote lasts 120 seconds. Do not supply your own wholesale price. A quote does not reserve proxies.
POST /v1/me/static/confirm
Authorization: Bearer <API-key>
Content-Type: application/json
Idempotency-Key: shop-order-42-purchase-v1
{"quote_id":"q-11111111111111111111111111111111"}
Use the actual quote_id. After a lost response, repeat the same URL, idempotency key and quote_id. HTTP 200 can still contain a pending state.
GET /v1/me/static/operations/op-22222222222222222222222222222222
Authorization: Bearer <API-key>
GET /v1/me/static/proxies?customer_ref=buyer-42
Authorization: Bearer <API-key>
host:port:login:password uses the HTTP port returned by the API. For SOCKS5 use the same host and credentials, port 1081. Credentials can be read again with an authorized key. Do not expose them in logs or notifications.
Keys, permissions and limits
Issue your regular reseller key yourself: Proxy Soxy bot → proxy management → Help → API & integrations → General API → Create key. The RU entry is «Управление прокси». The button below an EN proxy-delivery message is “My proxies”.
The psx_live_… secret is shown once. Reopening the screen shows the identifier, issue date, Reissue and Revoke. Reissuing revokes the previous regular key: update all your integrations and Connect. Revocation disables the key but retains operation history. A lost secret cannot be displayed again.
API purchase permission: select «Разрешить покупки…» (Allow purchases, in the RU bot) on the key screen and confirm spending from your Proxy Soxy balance. Without this binding /me/static/* may return 403 asking you to enable API in the key screen. «Запретить покупки» (Disable purchases, in the RU bot) blocks new debits without revoking the key or disabling ordinary reads and Connect. A replacement key needs new consent. Continuing paid fulfilment has separate checks; never repeat an uncertain payment.
Use Authorization: Bearer … over HTTPS. Keep the key on your server, out of browsers, reseller buyers, URLs and logs. whoami verifies the key but neither returns its secret nor confirms spending permission.
For purchases use the RU bot and its account key. The EN bot supports key management and access reads, but its spending-permission button is hidden because new USD spending is unavailable. The bot determines the screen language; enable spending using the Russian button in the RU bot.
Live and test keys
The current interface issues a regular psx_live_… key with role client. There is no self-service psx_test_… button or public virtual-money test environment. Legacy support for environment: test does not turn a bot-issued key into a sandbox. /me/static/* does not accept such a key as a virtual wallet. Use reads, quotes and your own integration tests for non-spending checks; production confirm can charge real money.
Current limits
Group
Per-key limit
Ordinary GET requests, including /me/static/*
120 per 60 seconds
POST /me/static/*
30 per 60 seconds
Selected accesses per operation
Up to 100; product-specific bounds also apply
Connect session creation
10 per minute
Connect proxy polling
120 per hour, including 304
Capacity and quantity checks also apply before execution. On 429, follow Retry-After and details.limit / details.window_sec when present. Do not busy-poll operations.
Purchases, renewal, UDP and history
Owners and customers
Your key belongs to your account and Proxy Soxy purchasing balance. customer_ref is your stable customer reference: 1–64 characters from A-Za-z0-9._@+-. It is isolated within your account. It is not a Telegram ID or a notification recipient.
Without customer_ref, a purchase belongs to the payer. With it, accesses belong to that reseller customer. Use the same reference for reads, renewal and UDP. Do not combine different customers in one selection. A different account’s key cannot read these operations or credentials.
Prices, currency and terms
Top up through the existing Proxy Soxy bot flow; this contract has no balance top-up method. API and ordinary purchases use one balance. The API does not calculate your retail markup.
/catalog provides current products, terms and quantity bounds. A quote gives the exact amount. Changed prices or selected accesses do not silently produce a different charge: the request is refused or the operation needs reconciliation. After a debit, inspect its state.
Active coupons are not silently ignored: 409 with details.reason: active_coupon_requires_bot_checkout directs the coupon purchase to the bot. Uncertain pricing or an unverified discount also blocks pricing/spending. Quotes accept no custom exchange rate, currency, coupon or discount.
A regular renewal extends from the later of current expiry and renewal time. A released access cannot be renewed. Do not depend on the old “three days” promise: actual access state governs eligibility. UDP never extends the underlying proxy term.
Send either body to POST /v1/me/static/quotes, then confirm it with a separate stable idempotency key. order_id identifies the original completed API purchase. Select either order_id or proxy_ids, not both. Credential changes take neither days nor a custom password; the server generates it. Read the outcome and credentials again.
Request /quotes. It returns proxy_amount_minor, udp_amount_minor, total amount_minor, currency and expires_at. Then call /confirm: one operation and one debit. It becomes COMPLETED only after both proxies and all UDP entitlements are saved. Omit udp or use udp:false for the ordinary purchase.
After /quotes, use /confirm with a new key such as shop-order-42-udp-v1. Do not send country, count or days for the add-on: they come from the selected accesses. proxy_amount_minor=0; udp.lines contains each access’s price and end time. Ownership, activity, compatibility, paid term and existing entitlement are validated.
UDP pricing: currently RUB 15 per access per 30 days, prorated by uncovered seconds, rounding each line up to a kopek. Use the quote total, not your own formula. connect adds an absent or expired entitlement to an active proxy. It cannot buy an already active entitlement again. After a separate proxy renewal, use udp_mode: "extend" to cover the gap, provided an active UDP entitlement exists and the term has an uncovered part. The underlying proxy expiry does not change.
Read /me/static/proxies for udp.state, udp.until and udp.operation_id. active is a confirmed current entitlement; expired, suspended, not_connected and unknown are distinct. Unknown does not mean enabled. UDP uses SOCKS5 UDP ASSOCIATE with the same login, not an HTTP proxy; your client software must support this protocol.
Partial outcomes and recovery
For “proxies + UDP”, core_proxy_ids may identify created proxies before UDP is confirmed. items retains per-access results. This is not a complete bundle: wait for COMPLETED. For APPLYING, PAID_HELD, DEBIT_UNKNOWN or MANUAL_REVIEW, retain the original op-… and reconcile it. Do not create a replacement purchase or assume a refund.
History and notifications
Open proxy management → Purchase history to see API purchases, renewals and UDP marked API, under their original op-…. Cards and exports require authorization. Support can find an operation by op-…, payer ID, related access or proxy line. API operations do not receive invented ordinary bot-order numbers.
After COMPLETED, the payer receives a message in the linked Proxy Soxy bot with the operation, country, quantity, term, amount and purchase button. A proxy-plus-UDP purchase gets one final message; an add-on gets a separate message linked to the original accesses. Operators receive a notice in their configured channel without secrets. Delivery uses the Telegram API directly; it is a notification, not an additional purchase. Reseller customers are not messaged automatically.
The API notifications switch in history disables payer messages without disabling purchases. A delivery failure does not undo payment or fulfilment. /operations/{operationId}/notifications reports delivery state. Manual /notifications/retry is only for explicitly rejected payer deliveries and does not repeat the purchase. UNKNOWN is not resent blindly. Historical operations appear without a mass replay of old notices.
Methods
The main reseller flow uses a client key from the bot and /me/static/*. Connect and organization /orders are separate contracts: do not mix their fields, money or identifiers.
Paths below are relative to https://api.soxydata.com/v1. POST requests use Content-Type: application/json. Unknown quote fields and unsupported query parameters are rejected. operation_id starting with op- is the canonical API operation number; proxy_id is an individual access; psx- belongs to a legacy organization order.
GET/v1/whoami
Check the key
A regular bot key returns role=client, environment=live, sandbox=null and customer_id. No key secret is returned. This does not confirm spending permission.
{
"error": {
"code": "rate_limited",
"message": "rate limit exceeded for this key (120 per 60s)",
"details": {
"retry_after": 17,
"group": "read",
"limit": 120,
"window_sec": 60,
"request_id": "req-0bteryb170cjg33c"
}
}
}
GET/v1/me/proxies
Own proxies and credentials
Client key. Returns passwords on every authorized read. Own accesses only; use /me/static/proxies for customer_ref. ETag / If-None-Match returns 304 when unchanged.
{
"error": {
"code": "rate_limited",
"message": "rate limit exceeded for this key (120 per 60s)",
"details": {
"retry_after": 17,
"group": "read",
"limit": 120,
"window_sec": 60,
"request_id": "req-0bteryb170cjg33c"
}
}
}
POST/v1/me/connect/session
Open a ProxyData Connect session
Separate Connect application contract. Does not buy proxies. Returns a token, nodes, credentials and connect.allowed. Use token_expires_in, refresh_after and poll_after from the response. Keep the token private.
{
"error": {
"code": "rate_limited",
"message": "rate limit exceeded for this key (120 per 60s)",
"details": {
"retry_after": 17,
"group": "read",
"limit": 120,
"window_sec": 60,
"request_id": "req-0bteryb170cjg33c"
}
}
}
GET/v1/me/static/catalog
Catalogue and current prices
Countries, terms, products, prices and quantity limits. The catalogue reserves neither stock nor price; a quote gives the final total. Requires the key binding established when API spending is enabled.
{
"error": {
"code": "internal",
"message": "Request could not be completed",
"details": {
"request_id": "req-example"
}
}
}
GET/v1/me/static/balance
Proxy Soxy balance
The same purchasing balance as your Proxy Soxy account. balance_minor is kopeks when currency=RUB. wallet is a compatibility field, not a separate wallet.
{
"error": {
"code": "internal",
"message": "Request could not be completed",
"details": {
"request_id": "req-example"
}
}
}
GET/v1/me/static/proxies
Credentials and UDP entitlement
Without customer_ref, returns the payer’s own accesses. With customer_ref, returns only that customer within your account. Passwords are returned on every authorized read. port is HTTP; SOCKS5 uses the same host and credentials, port 1081. UDP requires SOCKS5 UDP ASSOCIATE and udp.state=active.
{
"error": {
"code": "internal",
"message": "Request could not be completed",
"details": {
"request_id": "req-example"
}
}
}
POST/v1/me/static/quotes
Quote a purchase, renewal or UDP
Does not debit or issue proxies. Quote lifetime: 120 seconds. Requires spending permission. purchase: country/count/days, optional udp=true. renew: days and selected accesses. credentials or udp: selection, no days. For udp, connect is the default; extend covers the gap after a separate proxy renewal.
{
"error": {
"code": "internal",
"message": "Request could not be completed",
"details": {
"request_id": "req-example"
}
}
}
POST/v1/me/static/confirm
Confirm a quote
Spending operation. Persist quote_id and Idempotency-Key first. Reusing the same key and quote_id returns the same operation. HTTP 200 does not mean COMPLETED. Price and availability are checked before debit.
Uses the original operation_id. May finish paid fulfilment without a new debit. Unverified payment remains unknown. Continuing fulfilment may require active spending permission. This is not a read-only GET or a refund request.
Only an explicitly FAILED payer delivery, with notifications enabled; at most four attempts in total. UNKNOWN and historical NOT_QUEUED are not retried. Does not debit or fulfil an order.
{
"error": {
"code": "internal",
"message": "Request could not be completed",
"details": {
"request_id": "req-example"
}
}
}
POST/v1/me/static/webhook
Configure a webhook
Public HTTPS URL on port 443, no redirects. url=null disables delivery. Configuration returns a new secret once. Requires spending permission; keep the secret on your server.
{
"error": {
"code": "internal",
"message": "Request could not be completed",
"details": {
"request_id": "req-example"
}
}
}
GET/v1/stock
Legacy-contract stock
Separate /orders contract: addresses counts exit IPs, max_batch limits a batch, quota reports headroom. Does not replace /me/static catalogue, pricing or balance.
{
"error": {
"code": "rate_limited",
"message": "rate limit exceeded for this key (120 per 60s)",
"details": {
"retry_after": 17,
"group": "read",
"limit": 120,
"window_sec": 60,
"request_id": "req-0bteryb170cjg33c"
}
}
}
POST/v1/orders
Create an organization order
Organization partner/reseller key only; a regular client key receives 403. Separate accounting and terms, not the /me/static balance. Returns credentials.
{
"error": {
"code": "idempotency_conflict",
"message": "this Idempotency-Key was already used for a different request",
"details": {
"reason": "different_request",
"request_id": "req-0bteryb170cjg33c"
}
}
}
429Error RateLimited; inspect the response and the original operation state.
{
"error": {
"code": "order_expired",
"message": "the order term and its grace period are over; renew it or create a new order",
"details": {
"proxies": [
"bott-3ogk4i5qfjwm"
],
"request_id": "req-0bteryb170cjg33c"
}
}
}
429Error RateLimited; inspect the response and the original operation state.
purchase: country/count/days; renew: days and exactly one of order_id/proxy_ids; credentials/udp: selection without days. udp=true is purchase-only. customer_ref must match the original purchase.
Field
Type
Description
kind*
any: purchase | renew | credentials | udp
udp
boolean
udp_mode
string: connect | extend
country
string
count
integer
days
integer
customer_ref
string
proxy_ids
array of string
order_id
string
operation_id of the completed original purchase, not a bot order number.
StaticQuote
Field
Type
Description
quote_id*
string
proxy_amount_minor
integer
Proxy component; returned for UDP operations.
udp_amount_minor
integer
UDP component, included in the total.
udp
object
UDP mode, price and per-access terms. lines[].order identifies an access; until/from/expires are Unix seconds. For a new purchase, issued terms are returned in items.
UDP mode, price and per-access terms. lines[].order identifies an access; until/from/expires are Unix seconds. For a new purchase, issued terms are returned in items.
amount_minor*
integer
Total in kopeks.
currency*
any: RUB
proxy_ids*
array of string
reason
string | null
needs_attention*
boolean
test_mode*
boolean
e.g. false
items
array of object
kind
any: purchase | renew | credentials | udp
customer_ref
string | null
created_at
integer
updated_at
integer
core_proxy_ids
array of string
retry
string
UDPRight
Paid UDP entitlement. unknown means confirmation is unavailable, not free access. until is Unix seconds. operation_id is null for an entitlement bought outside the API.
Field
Type
Description
state*
any: not_connected | active | expired | suspended | unknown
until*
integer | null
operation_id*
string | null
StaticProxy
Field
Type
Description
proxy_id*
string
e.g. "bott-tduaqez1ldye"
host*
string
e.g. "gate.example.invalid"
port*
integer
HTTP port. SOCKS5: same host, port 1081.
e.g. 3130
login*
string
e.g. "<proxy-login>"
password*
string
Available to the owner on every authorized read. Treat it as a secret.
e.g. "<proxy-password>"
country*
CountryCode
e.g. "DE"
country_name*
string
e.g. "Germany"
ip*
string
e.g. "192.0.2.10"
expires*
integer
e.g. 1794720000
expires_at*
string
active*
boolean
purchase*
string
Grouping identifier. For API purchases use the canonical operation_id from history and proxy_ids for matching.
e.g. "group-example"
udp*
UDPRight
Paid UDP entitlement. unknown means confirmation is unavailable, not free access. until is Unix seconds. operation_id is null for an entitlement bought outside the API.
StaticProxies
Field
Type
Description
customer_ref*
string | null
proxies*
array of StaticProxy
StaticBalance
Field
Type
Description
wallet*
string: BOT-T
Historical external field value. Means your Proxy Soxy balance; not another wallet or a third-party registration requirement.
currency*
string: RUB | USD
Currency of the bound account. Reading USD does not enable USD spending.
balance_minor*
integer
test_mode*
boolean
StaticOperationList
Field
Type
Description
items*
array of StaticOperation
next_cursor*
integer | null
StaticEvent
A /me/static event. data contains operation_id/proxy_ids or an access-state change. No passwords. created_at is Unix seconds.
Field
Type
Description
event_id*
string
type*
string
e.g. "order.issued"
created_at*
integer
data*
object
status
any: pending | delivered | dead
attempts
integer
StaticCatalogue
Use the returned products, terms and quantity bounds. Additional response fields may be added.
Inspect HTTP status, error.code, details, and an existing operation’s state and reason. Message text may change. Give support request_id when present, never keys or passwords.
HTTP
code
Meaning
What to do
400
invalid_request
Unsupported fields, format or selection.
Correct the request; do not retry it unchanged.
401
unauthorized
No valid key.
Check Bearer authentication; reissue a lost key in the bot.
403
forbidden
Wrong role, no spending permission, or operation unavailable to this account.
Check whoami, the key screen and RU/RUB eligibility. Do not bypass restrictions.
404
not_found
Object absent or not owned by the selected account.
Check op-…, proxy_ids and customer_ref.
409
idempotency_conflict
Operation, quote, price or entitlement conflict, or an unresolved purchase hold.
Inspect reason and the original operation. A new key does not resolve an uncertain payment.
409
out_of_stock
Matching resources unavailable.
Before debit, select another product; after an operation starts, establish its outcome first.
409
quota_exceeded
Capacity quota exhausted.
Check limits and operation state; preserve idempotency.
409
order_expired
Access state or term prevents the selected action.
Check renewal eligibility; changing a password does not restore a released access.
402
insufficient_balance
Verified spendable balance is below the required amount.
Top up your Proxy Soxy balance. Establish the previous operation’s outcome before another purchase.
429
rate_limited
Call or unit limit exceeded; inspect details.
Follow Retry-After; keep the same idempotency key.
500
internal
Request did not return normally; payment outcome may be uncertain.
Read and reconcile the original op-… without a new purchase.
UDP may be refused before debit for a foreign/expired access, an active entitlement with connect, no active entitlement or uncovered gap with extend, incompatible product, changed term/price/entitlement, unavailable route, denied spending or insufficient balance. Preserve the machine-readable reason when supplied. Do not report all these failures as insufficient balance.
A timeout, 5xx or partial result does not prove that no money was charged. Read and reconcile the original operation without a new purchase. COMPLETED is the final fulfilment success state. This contract does not provide a general automatic-refund API.
Idempotency and uncertain outcomes
Main /me/static contract
POST /me/static/confirm requires Idempotency-Key: 8–128 characters from A-Za-z0-9._-. Colons are not allowed here. Store it with quote_id before sending. One key represents one logical operation within the payer’s scope; do not generate another to recover an uncertain result.
Repeating the same quote_id returns the original operation and can continue safe execution. It returns current state, not necessarily a byte-for-byte replay of the first HTTP response. The same key with a different quote gives 409 idempotency_conflict. A completed operation is not charged or issued twice. The canonical journal has no automatic 30-day expiry; keep its ID in your records.
If confirm’s response is lost before you obtain operation_id, repeat that same confirm. If the ID is known, start with GET /operations/{operationId}, then use POST /operations/{operationId}/reconcile with {} when needed. Reconciliation can finish paid fulfilment and is not read-only. Do not change the key, create another quote for the same uncertain payment or infer payment solely from a balance change.
state
Meaning and action
CREATED, PREFLIGHT
Preparation; retry/reconcile the original operation
DEBIT_PENDING, DEBIT_UNKNOWN
Debit outcome is not confirmed; reconcile without paying again
PAID
Payment confirmed, fulfilment incomplete
PAID_HELD
Paid fulfilment held by a check; retain ID and inspect reason/permissions
APPLYING
Execution or its outcome is being reconciled
COMPLETED
All selected results confirmed; credentials may be delivered
DECLINED
Operation refused; inspect reason and establish the outcome before a new purchase
MANUAL_REVIEW
Partial/uncertain result requires review; do not repeat payment
items describes individual accesses. One successful item does not mean the complete purchase succeeded. Notification failure does not change purchase state.
Separate /orders contract
Legacy organization POST requests use a different key format: 1–64 characters from A-Za-z0-9_.:-, including colons. A completed HTTP response is retained for 30 days and a replay may carry Idempotency-Replayed: true. Reasons different_request and in_progress belong to this contract. Do not apply these header rules or retention periods to /me/static/confirm.
/me/static events and webhooks
Configure a public HTTPS receiver with POST /v1/me/static/webhook and {"url":"https://shop.example/webhooks/proxy-soxy"}. The response returns a new secret once. Reconfiguration replaces it; {"url":null} disables delivery. Private addresses, nonstandard ports and redirects are not supported.
Events: order.issued, order.renewed, order.udp_connected, order.connection_changed, order.availability_changed, order.expiring, order.expired. Some changes are observed periodically: immediate delivery or detection of every brief transition is not guaranteed. order.refunded is not advertised as an implemented event in this contract.
Access-change data may contain proxy_id, address and expiry instead of operation_id. No passwords are included. Fetch credentials through an authorized GET. Do not depend on Telegram or a webhook to determine purchase success.
Signature and duplicates
X-Soxy-Signature: t=<unix>,v1=<hex> contains HMAC-SHA256 of <t>.<raw UTF-8 body> using your secret. Compare in constant time before processing JSON and validate clock skew, for example within five minutes in either direction. X-Soxy-Event-Id matches event_id. Persist processed IDs and acknowledge duplicates successfully without repeating their effects.
<?php
// PHP: verify the webhook signature. Raw body from php://input, BEFORE json_decode.
function verifySoxySignature(string $header, string $rawBody, string $secret, int $toleranceSec = 300): bool {
if (!preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', trim($header), $m)) return false; // wrong format
$t = (int)$m[1];
if (abs(time() - $t) > $toleranceSec) return false; // too old
$expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
return hash_equals($expected, $m[2]); // constant time
}
$raw = file_get_contents('php://input');
if (!verifySoxySignature($_SERVER['HTTP_X_SOXY_SIGNATURE'] ?? '', $raw, $WEBHOOK_SECRET)) {
http_response_code(400); exit;
}
$event = json_decode($raw, true);
// dedupe by $event['event_id'], then process; reply 200 promptly
http_response_code(200);
// Node.js: verify the webhook signature. Read the RAW body before parsing JSON.
const crypto = require('crypto');
function verifySoxySignature(header, rawBody, secret, toleranceSec = 300) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(String(header || '').trim());
if (!m) return false; // wrong format
const t = Number(m[1]);
if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSec) return false; // too old
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
const given = Buffer.from(m[2], 'hex');
return expected.length === given.length && crypto.timingSafeEqual(expected, given);
}
// Express: raw body via express.raw, then verify, dedupe by event.event_id, process, answer 200.
// app.post('/hook', express.raw({ type: '*/*' }), (req, res) => {
// if (!verifySoxySignature(req.headers['x-soxy-signature'], req.body.toString('utf8'), SECRET)) return res.status(400).end();
// const event = JSON.parse(req.body);
// res.status(200).end();
// });
module.exports = { verifySoxySignature };
HTTP 2xx acknowledges delivery; redirects are unsupported. Reply promptly: an attempt is bounded to approximately eight seconds. A cycle permits up to eight attempts with delays, then becomes dead. GET /events/{eventId} lists attempts; POST /events/{eventId}/retry {} requeues the same dead event. Delivery may repeat; it does not represent another purchase.
The legacy organization /orders contract has a different data.order payload and configuration method. Keep these formats separate.
Other contracts and specification
Organization /orders and prepaid
This is a separate contract for existing configured organization keys (partner/reseller), not the quick start for a bot-issued key. It uses psx-…, /stock, /orders, and whole-order renewal and password changes. Its limits and prepaid accounting do not grant access to the Proxy Soxy balance in /me/static. A regular client key cannot create or modify organization orders; any permitted reads are limited to its own objects.
GET /orders/{id} omits passwords; creation and credential changes return them. This legacy-method restriction does not apply to /me/proxies or /me/static/proxies. Its event payload is data.order, not data.operation_id. A test-organization-key schema does not provide such an account to users.
Connect
/me/connect/session and /me/connect/proxies serve ProxyData Connect. They do not buy accesses or replace quotes. Check connect.allowed and the returned terms; do not assume unconditional free access. Keys and Connect tokens are secrets. A proxy’s UDP entitlement does not itself prove that a particular client application version supports UDP.
Machine-readable contract and examples
OpenAPI EN · OpenAPI RU describes installed methods. Read examples and SDK use an ordinary bot-issued key; download examples. Purchase examples require an explicit action in your application, not merely opening documentation. Responses may gain additional fields within v1. Secrets in examples are placeholders.