ProxySoxyDocumentation
Contents

Proxy Soxy Partner API

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

  1. 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.
  2. Call GET https://api.soxydata.com/v1/whoami with Authorization: Bearer <key>. A regular bot key returns role: "client", environment: "live", sandbox: null.
  3. 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.
  4. 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.
  5. 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-.
  6. 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.

Renew or change credentials

{"kind":"renew","customer_ref":"buyer-42","order_id":"op-22222222222222222222222222222222","days":30}
{"kind":"credentials","customer_ref":"buyer-42","proxy_ids":["bott-example001","bott-example002"]}

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.

Buy proxies with UDP

{"kind":"purchase","country":"US","count":2,"days":30,"customer_ref":"buyer-42","udp":true}

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.

Add UDP to selected accesses

{"kind":"udp","customer_ref":"buyer-42","proxy_ids":["bott-example001","bott-example002"],"udp_mode":"connect"}

Or select the whole original purchase:

{"kind":"udp","customer_ref":"buyer-42","order_id":"op-22222222222222222222222222222222"}

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.

Example call

curl -X GET https://api.soxydata.com/v1/whoami \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en"

Responses

200Response; check the state in the body

Schema: WhoAmI

401Error Unauthorized; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
429Error RateLimited; inspect the response and the original operation state.

Schema: Error

{
  "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.

Example call

curl -X GET https://api.soxydata.com/v1/me/proxies \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en"

Responses

200Response; check the state in the body

Schema: ClientProxies

304Error; inspect error.code and the original operation
401Error Unauthorized; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
403Error Forbidden; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "forbidden",
    "message": "order creation requires a partner key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
429Error RateLimited; inspect the response and the original operation state.

Schema: Error

{
  "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.

Request body (optional)

FieldTypeDescription
client_versionstring
e.g. "1.1.0"
platformstring
e.g. "windows"
instancestring

Example call

curl -X POST https://api.soxydata.com/v1/me/connect/session \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en" \
  -H "Content-Type: application/json" \
  -d '{}'

Responses

200Response; check the state in the body

Schema: ConnectSession

401Error Unauthorized; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
403Error Forbidden; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "forbidden",
    "message": "order creation requires a partner key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
429Error RateLimited; inspect the response and the original operation state.

Schema: Error

{
  "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/connect/proxies

Refresh the Connect list

Client key and valid Connect permission. Supports If-None-Match and 304.

Example call

curl -X GET https://api.soxydata.com/v1/me/connect/proxies \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en"

Responses

200Response; check the state in the body

Schema: ConnectProxies

304Error; inspect error.code and the original operation
401Error Unauthorized; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
403Error Forbidden; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "forbidden",
    "message": "order creation requires a partner key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
429Error RateLimited; inspect the response and the original operation state.

Schema: Error

{
  "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.

Example call

curl -X GET https://api.soxydata.com/v1/me/static/catalog \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en"

Responses

200Response; check the state in the body

Schema: StaticCatalogue

400Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Error; inspect error.code and the original operation

Schema: Error

{
  "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.

Example call

curl -X GET https://api.soxydata.com/v1/me/static/balance \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en"

Responses

200Response; check the state in the body

Schema: StaticBalance

400Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Error; inspect error.code and the original operation

Schema: Error

{
  "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.

Parameters

NameInTypeDescription
customer_refquerystring

Example call

curl -X GET https://api.soxydata.com/v1/me/static/proxies \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en"

Responses

200Response; check the state in the body

Schema: StaticProxies

400Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Error; inspect error.code and the original operation

Schema: Error

{
  "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.

Request body

StaticQuoteInput

Example call

curl -X POST https://api.soxydata.com/v1/me/static/quotes \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en" \
  -H "Content-Type: application/json" \
  -d '{"kind":"purchase","country":"US","count":2,"days":30,"customer_ref":"buyer-42"}'

Responses

200Response; check the state in the body

Schema: StaticQuote

400Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Error; inspect error.code and the original operation

Schema: Error

{
  "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.

Parameters

NameInTypeDescription
Idempotency-Key*headerstring

Request body

FieldTypeDescription
quote_id*string

Example call

curl -X POST https://api.soxydata.com/v1/me/static/confirm \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en" \
  -H "Idempotency-Key: pay-88412-a3f9" \
  -H "Content-Type: application/json" \
  -d '{"quote_id":"q-11111111111111111111111111111111"}'

Responses

200Response; check the state in the body

Schema: StaticOperation

400Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "internal",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}

GET /v1/me/static/operations

API operation history

Purchases, renewals, credential changes and UDP operations belonging to the key owner. Returns items and next_cursor; follow the cursor until null.

Parameters

NameInTypeDescription
cursorqueryinteger

Example call

curl -X GET https://api.soxydata.com/v1/me/static/operations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en"

Responses

200Response; check the state in the body

Schema: StaticOperationList

400Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "internal",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}

GET /v1/me/static/operations/{operationId}

Original operation state

Read without debit, fulfilment or notification resend. Foreign and absent operations return 404.

Parameters

NameInTypeDescription
operationId*pathstring

Example call

curl -X GET https://api.soxydata.com/v1/me/static/operations/op-22222222222222222222222222222222 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en"

Responses

200Response; check the state in the body

Schema: StaticOperation

400Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "internal",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}

POST /v1/me/static/operations/{operationId}/reconcile

Reconcile an uncertain result

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.

Parameters

NameInTypeDescription
operationId*pathstring

Request body

object

Example call

curl -X POST https://api.soxydata.com/v1/me/static/operations/op-22222222222222222222222222222222/reconcile \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en" \
  -H "Content-Type: application/json" \
  -d '{}'

Responses

200Response; check the state in the body

Schema: StaticOperation

400Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "internal",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}

GET /v1/me/static/operations/{operationId}/notifications

Notification delivery state

Payer and operator delivery states; does not send. ACCEPTED means acceptance by the delivery API, not that a person has read it.

Parameters

NameInTypeDescription
operationId*pathstring

Example call

curl -X GET https://api.soxydata.com/v1/me/static/operations/op-22222222222222222222222222222222/notifications \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en"

Responses

200Response; check the state in the body
400Request rejected

Schema: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Request rejected

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Request rejected

Schema: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Request rejected

Schema: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Request rejected

Schema: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Request rejected

Schema: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Unknown response

Schema: Error

{
  "error": {
    "code": "internal",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}

POST /v1/me/static/operations/{operationId}/notifications/retry

Retry a rejected payer notification

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.

Parameters

NameInTypeDescription
operationId*pathstring

Request body

object

Example call

curl -X POST https://api.soxydata.com/v1/me/static/operations/op-22222222222222222222222222222222/notifications/retry \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en" \
  -H "Content-Type: application/json" \
  -d '{}'

Responses

200Response; check the state in the body
400Request rejected

Schema: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Request rejected

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Request rejected

Schema: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Request rejected

Schema: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Request rejected

Schema: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Unknown response

Schema: Error

{
  "error": {
    "code": "internal",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}

GET /v1/me/static/events

List events

items and next_cursor. Events belong only to your account.

Parameters

NameInTypeDescription
cursorqueryinteger

Example call

curl -X GET https://api.soxydata.com/v1/me/static/events \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en"

Responses

200Response; check the state in the body
400Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "internal",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}

GET /v1/me/static/events/{eventId}

Event and delivery attempts

Returns event, attempts and next_cursor.

Parameters

NameInTypeDescription
eventId*pathstring
cursorqueryinteger

Example call

curl -X GET https://api.soxydata.com/v1/me/static/events/evt-33333333333333333333333333333333 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en"

Responses

200Response; check the state in the body
400Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "internal",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}

POST /v1/me/static/events/{eventId}/retry

Retry delivery of a dead event

Preserves event_id; does not repeat a purchase. Pending/delivered events are not recreated. The receiver must deduplicate by event_id.

Parameters

NameInTypeDescription
eventId*pathstring

Request body

object

Example call

curl -X POST https://api.soxydata.com/v1/me/static/events/evt-33333333333333333333333333333333/retry \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en" \
  -H "Content-Type: application/json" \
  -d '{}'

Responses

200Response; check the state in the body
400Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Error; inspect error.code and the original operation

Schema: Error

{
  "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.

Request body

FieldTypeDescription
url*string | null

Example call

curl -X POST https://api.soxydata.com/v1/me/static/webhook \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://shop.example/webhooks/proxy-soxy"}'

Responses

200Response; check the state in the body
400Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "invalid_request",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
401Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
403Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "forbidden",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
404Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "not_found",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
409Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
429Error; inspect error.code and the original operation

Schema: Error

{
  "error": {
    "code": "rate_limited",
    "message": "Request could not be completed",
    "details": {
      "request_id": "req-example"
    }
  }
}
500Error; inspect error.code and the original operation

Schema: Error

{
  "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.

Example call

curl -X GET https://api.soxydata.com/v1/stock \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en"

Responses

200Response; check the state in the body

Schema: Stock

401Error Unauthorized; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
429Error RateLimited; inspect the response and the original operation state.

Schema: Error

{
  "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/orders

Organization-contract orders

Lists legacy orders accessible to this key. Find op-… operations in /me/static/operations, not here.

Parameters

NameInTypeDescription
customer_refquerystring
statusquerystring: active | expired | all default active
countryqueryCountryCode
limitqueryinteger default 50
cursorquerystring

Example call

curl -X GET https://api.soxydata.com/v1/orders \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en"

Responses

200Response; check the state in the body

Schema: OrderList

400Error BadRequest; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "invalid_request",
    "message": "invalid request: count, days",
    "details": {
      "fields": [
        {
          "field": "count",
          "message": "integer between 1 and 100"
        },
        {
          "field": "days",
          "message": "one of 7, 30, 90"
        }
      ],
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
401Error Unauthorized; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
429Error RateLimited; inspect the response and the original operation state.

Schema: Error

{
  "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.

Parameters

NameInTypeDescription
Idempotency-Key*headerstring

Request body

CreateOrderRequest

Example call

curl -X POST https://api.soxydata.com/v1/orders \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en" \
  -H "Idempotency-Key: pay-88412-a3f9" \
  -H "Content-Type: application/json" \
  -d '{"country":"DE","count":5,"days":30,"customer_ref":"site-user-88412"}'

Responses

201Response; check the state in the body

Schema: CreateOrderResponse

400Error BadRequest; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "invalid_request",
    "message": "invalid request: count, days",
    "details": {
      "fields": [
        {
          "field": "count",
          "message": "integer between 1 and 100"
        },
        {
          "field": "days",
          "message": "one of 7, 30, 90"
        }
      ],
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
401Error Unauthorized; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
402Error InsufficientBalance; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "insufficient_balance",
    "message": "insufficient prepaid balance; nothing was issued or charged",
    "details": {
      "required_minor": 17500,
      "balance_minor": 1000,
      "currency": "RUB",
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
403Error Forbidden; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "forbidden",
    "message": "order creation requires a partner key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
409Error CreateConflict; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "out_of_stock",
    "message": "no addresses available in DE",
    "details": {
      "country": "DE",
      "available": 0,
      "reason": "addresses",
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
429Error RateLimited; inspect the response and the original operation state.

Schema: Error

{
  "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"
    }
  }
}
500Error Internal; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "internal",
    "message": "internal error",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}

GET /v1/orders/{orderId}

Organization order

A psx-… identifier, not op-…. Current addresses without passwords.

Example call

curl -X GET https://api.soxydata.com/v1/orders/psx-7fa2c9d14b03 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en"

Responses

200Response; check the state in the body

Schema: Order

401Error Unauthorized; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
404Error NotFound; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "not_found",
    "message": "no such order",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
429Error RateLimited; inspect the response and the original operation state.

Schema: Error

{
  "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/{orderId}/renew

Renew an organization order

Organization key only. Renews existing accesses under that contract. Released accesses cannot be renewed. For op-… use quote kind=renew instead.

Parameters

NameInTypeDescription
Idempotency-Key*headerstring

Request body

RenewRequest

Example call

curl -X POST https://api.soxydata.com/v1/orders/psx-7fa2c9d14b03/renew \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en" \
  -H "Idempotency-Key: pay-88412-a3f9" \
  -H "Content-Type: application/json" \
  -d '{"days":30}'

Responses

200Response; check the state in the body

Schema: RenewResponse

400Error BadRequest; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "invalid_request",
    "message": "invalid request: count, days",
    "details": {
      "fields": [
        {
          "field": "count",
          "message": "integer between 1 and 100"
        },
        {
          "field": "days",
          "message": "one of 7, 30, 90"
        }
      ],
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
401Error Unauthorized; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
402Error InsufficientBalance; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "insufficient_balance",
    "message": "insufficient prepaid balance; nothing was issued or charged",
    "details": {
      "required_minor": 17500,
      "balance_minor": 1000,
      "currency": "RUB",
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
403Error Forbidden; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "forbidden",
    "message": "order creation requires a partner key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
404Error NotFound; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "not_found",
    "message": "no such order",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
409Error IdempotencyConflict; inspect the response and the original operation state.

Schema: Error

{
  "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.

Schema: Error

{
  "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/{orderId}/credentials

Change organization-order passwords

Organization key only. Changes the selected order’s password and returns credentials. For /me/static use kind=credentials and selected accesses.

Parameters

NameInTypeDescription
Idempotency-Key*headerstring

Request body (optional)

CredentialsRequest

Example call

curl -X POST https://api.soxydata.com/v1/orders/psx-7fa2c9d14b03/credentials \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept-Language: en" \
  -H "Idempotency-Key: pay-88412-a3f9" \
  -H "Content-Type: application/json" \
  -d '{}'

Responses

200Response; check the state in the body

Schema: CredentialsResponse

400Error BadRequest; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "invalid_request",
    "message": "invalid request: count, days",
    "details": {
      "fields": [
        {
          "field": "count",
          "message": "integer between 1 and 100"
        },
        {
          "field": "days",
          "message": "one of 7, 30, 90"
        }
      ],
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
401Error Unauthorized; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
403Error Forbidden; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "forbidden",
    "message": "order creation requires a partner key",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
404Error NotFound; inspect the response and the original operation state.

Schema: Error

{
  "error": {
    "code": "not_found",
    "message": "no such order",
    "details": {
      "request_id": "req-0bteryb170cjg33c"
    }
  }
}
409Error CredentialsConflict; inspect the response and the original operation state.

Schema: Error

{
  "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.

Schema: Error

{
  "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"
    }
  }
}

Schemas

WhoAmI

FieldTypeDescription
partner_id*string
e.g. "prt-example"
role*string: partner | reseller | client
environment*string: live | test
sandbox*object | nullnull for a regular live key. test belongs to a separate legacy contract; the bot does not offer self-service test keys or virtual payments.
e.g. null
FieldTypeDescription
proxies_maxinteger
e.g. 5
daysarray of integer
e.g. [7]
rate_limitsobject
customer_idstring | null
e.g. "cus-example"
api_version*string
e.g. "v1"

CountryCode

string

OrderId

string

Proxy

Proxy in the separate /orders contract. Password is included on creation/change, not GET /orders/{id}. This does not restrict /me/static/proxies.

FieldTypeDescription
proxy_id*string
e.g. "bott-3ogk4i5qfjwm"
host*string
e.g. "gate1024.psnode.me"
port*integer
e.g. 3130
ip*string
e.g. "192.0.2.10"
country*CountryCode
e.g. "DE"
login*string
e.g. "<proxy-login>"
passwordstring
e.g. "<proxy-password>"

Order

FieldTypeDescription
id*OrderId
e.g. "psx-7fa2c9d14b03"
status*string: active | expired
country*CountryCode
e.g. "DE"
count*integer
days*integer
created_at*string
expires_at*string
customer_id*string
e.g. "cus-4b81e0a2"
customer_refstring
e.g. "site-user-88412"
country_name*string
e.g. "Germany"
days_leftinteger
e.g. 24
active_countinteger
price_minorinteger
e.g. 17500
currencystring
e.g. "RUB"
proxiesarray of Proxy

OrderWithPassword

FieldTypeDescription
id*OrderId
e.g. "psx-7fa2c9d14b03"
status*string: active | expired
country*CountryCode
e.g. "DE"
count*integer
days*integer
created_at*string
expires_at*string
customer_id*string
e.g. "cus-4b81e0a2"
customer_refstring
e.g. "site-user-88412"
country_name*string
e.g. "Germany"
days_leftinteger
e.g. 24
active_countinteger
price_minorinteger
e.g. 17500
currencystring
e.g. "RUB"
proxiesarray of Proxy

CreateOrderRequest

FieldTypeDescription
country*CountryCode
e.g. "DE"
count*integer
days*integer: 7 | 30 | 90
customer_ref*string
passwordstring
e.g. "<proxy-password>"

CreateOrderResponse

FieldTypeDescription
order*OrderWithPassword
balance_minor_afterinteger | null

OrderList

FieldTypeDescription
orders*array of Order
next_cursor*string | null

ClientProxy

FieldTypeDescription
proxy_id*string
e.g. "bott-tduaqez1ldye"
host*string
e.g. "gate.example.invalid"
port*integerHTTP port. SOCKS5: same host, port 1081.
e.g. 3130
login*string
e.g. "<proxy-login>"
password*stringAvailable 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*stringGrouping identifier. For API purchases use the canonical operation_id from history and proxy_ids for matching.
e.g. "group-example"

ClientProxies

FieldTypeDescription
proxies*array of ClientProxy
count*integer
e.g. 3
etag*string
e.g. "\"a1b2c3d4e5f60718293a\""

ConnectState

FieldTypeDescription
allowed*boolean
e.g. true
until*integer | null

ConnectNode

FieldTypeDescription
ip*string
e.g. "192.0.2.10"
port*integer
e.g. 443
sni*string
e.g. "soxy-entry"
transport*string: mtls | mwss
pathstring
e.g. "/ws"

ConnectSession

FieldTypeDescription
acct*string
e.g. "acct-bp2xznodclu0"
connect*ConnectState
tunnel*object
FieldTypeDescription
username*string
e.g. "acct-bp2xznodclu0"
token*string
e.g. "pdt_c3f1…"
token_expires_in*integer
e.g. 21600
refresh_after*integer
e.g. 10800
nodes*array of ConnectNode
gateway*string
e.g. "192.0.2.10:3130"
proxies*array of ClientProxy
etag*string
e.g. "\"a1b2c3d4e5f60718293a\""
poll_after*integer
e.g. 60

ConnectProxies

FieldTypeDescription
connect*ConnectState
proxies*array of ClientProxy
etag*string
e.g. "\"d4e5f6a7b8c90a1b2c3d\""
poll_after*integer
e.g. 60

Stock

FieldTypeDescription
countries*array of object
FieldTypeDescription
code*CountryCode
e.g. "DE"
name*string
e.g. "Germany"
addresses*integer
e.g. 69
max_batch*integer
e.g. 100
quota*object
FieldTypeDescription
scope*string: partner | test_key
e.g. "partner"
proxies_max*integer | null
e.g. 3000
proxies_live*integer
e.g. 120
proxies_pending*integer
e.g. 0
proxies_available*integer | null
e.g. 2880
next_free_at*string | null
generated_at*string

RenewRequest

FieldTypeDescription
days*integer: 7 | 30 | 90

RenewResponse

FieldTypeDescription
order*Order
renewal*object
FieldTypeDescription
days*integer
e.g. 30
count*integer
e.g. 5
price_minor*integer
e.g. 15750
balance_minor_afterinteger | null

CredentialsRequest

FieldTypeDescription
passwordstring
e.g. "<proxy-password>"

CredentialsResponse

FieldTypeDescription
order*OrderWithPassword

WebhookEvent

Separate legacy /orders payload. Do not use it in place of StaticEvent.

FieldTypeDescription
event_id*string
e.g. "evt-9c1f3a8e2b04"
type*string: order.issued
created_at*string
data*object
FieldTypeDescription
order*Order

Error

FieldTypeDescription
error*object
FieldTypeDescription
code*string: invalid_request | unauthorized | forbidden | not_found | idempotency_conflict | out_of_stock | quota_exceeded | order_expired | insufficient_balance | rate_limited | internal
message*string
detailsobject

StaticQuoteInput

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.

FieldTypeDescription
kind*any: purchase | renew | credentials | udp
udpboolean
udp_modestring: connect | extend
countrystring
countinteger
daysinteger
customer_refstring
proxy_idsarray of string
order_idstringoperation_id of the completed original purchase, not a bot order number.

StaticQuote

FieldTypeDescription
quote_id*string
proxy_amount_minorintegerProxy component; returned for UDP operations.
udp_amount_minorintegerUDP component, included in the total.
udpobjectUDP 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*integerTotal in kopeks.
currency*any: RUB
expires_at*integer
test_mode*boolean
e.g. false
proxy_idsarray of string
kindany: purchase | renew | credentials | udp
customer_refstring | null
countinteger

StaticOperation

FieldTypeDescription
operation_id*string
state*any: CREATED | PREFLIGHT | DEBIT_PENDING | DEBIT_UNKNOWN | PAID | PAID_HELD | APPLYING | COMPLETED | DECLINED | MANUAL_REVIEW
proxy_amount_minorintegerProxy component; returned for UDP operations.
udp_amount_minorintegerUDP component, included in the total.
udpobjectUDP 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*integerTotal in kopeks.
currency*any: RUB
proxy_ids*array of string
reasonstring | null
needs_attention*boolean
test_mode*boolean
e.g. false
itemsarray of object
kindany: purchase | renew | credentials | udp
customer_refstring | null
created_atinteger
updated_atinteger
core_proxy_idsarray of string
retrystring

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.

FieldTypeDescription
state*any: not_connected | active | expired | suspended | unknown
until*integer | null
operation_id*string | null

StaticProxy

FieldTypeDescription
proxy_id*string
e.g. "bott-tduaqez1ldye"
host*string
e.g. "gate.example.invalid"
port*integerHTTP port. SOCKS5: same host, port 1081.
e.g. 3130
login*string
e.g. "<proxy-login>"
password*stringAvailable 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*stringGrouping identifier. For API purchases use the canonical operation_id from history and proxy_ids for matching.
e.g. "group-example"
udp*UDPRightPaid 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

FieldTypeDescription
customer_ref*string | null
proxies*array of StaticProxy

StaticBalance

FieldTypeDescription
wallet*string: BOT-THistorical external field value. Means your Proxy Soxy balance; not another wallet or a third-party registration requirement.
currency*string: RUB | USDCurrency of the bound account. Reading USD does not enable USD spending.
balance_minor*integer
test_mode*boolean

StaticOperationList

FieldTypeDescription
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.

FieldTypeDescription
event_id*string
type*string
e.g. "order.issued"
created_at*integer
data*object
statusany: pending | delivered | dead
attemptsinteger

StaticCatalogue

Use the returned products, terms and quantity bounds. Additional response fields may be added.

FieldTypeDescription
productstring: static
protocolsarray of string
currencystring
countriesarray of object
FieldTypeDescription
countrystring
addressesinteger
indexed_addressesinteger
daysarray of integer
renewalobject
purchase_productsarray | null
purchase_availableboolean
max_countinteger
stock_is_reservationboolean
geo_versionany
health_checked_atany
pricing_versionstring

Errors

{"error":{"code":"forbidden","message":"API spending disabled","details":{"request_id":"req-example"}}}

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.

HTTPcodeMeaningWhat to do
400invalid_requestUnsupported fields, format or selection.Correct the request; do not retry it unchanged.
401unauthorizedNo valid key.Check Bearer authentication; reissue a lost key in the bot.
403forbiddenWrong role, no spending permission, or operation unavailable to this account.Check whoami, the key screen and RU/RUB eligibility. Do not bypass restrictions.
404not_foundObject absent or not owned by the selected account.Check op-…, proxy_ids and customer_ref.
409idempotency_conflictOperation, 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.
409out_of_stockMatching resources unavailable.Before debit, select another product; after an operation starts, establish its outcome first.
409quota_exceededCapacity quota exhausted.Check limits and operation state; preserve idempotency.
409order_expiredAccess state or term prevents the selected action.Check renewal eligibility; changing a password does not restore a released access.
402insufficient_balanceVerified spendable balance is below the required amount.Top up your Proxy Soxy balance. Establish the previous operation’s outcome before another purchase.
429rate_limitedCall or unit limit exceeded; inspect details.Follow Retry-After; keep the same idempotency key.
500internalRequest 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.

{"event_id":"evt-33333333333333333333333333333333","type":"order.issued","created_at":1794720000,"data":{"operation_id":"op-22222222222222222222222222222222","proxy_ids":["bott-example001"],"customer_ref":"buyer-42"}}

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.