Partner API

Powerful REST API for seamless partner integrations. Build, connect, and automate with confidence.

v1.0 — stable

Overview

The Partner API lets partner applications check stock, view account details, and purchase Telegram accounts automatically — all via HTTP requests.

💡 All endpoints live under BASE_URL/api/v1/. The base URL is shown in your bot profile under Hamkorlik API.

Base URL

Example

https://api.vokky.uz

Authentication

Every request (except /api/v1/info) requires your personal API key. Get it from the bot: Profile → Hamkorlik API.

Pass your key via Header (recommended)

curl

curl https://api.vokky.uz/api/v1/balance \
  -H "X-API-Key: YOUR_API_KEY"

Or via query parameter

curl

curl "https://api.vokky.uz/api/v1/balance?api_key=YOUR_API_KEY"

Rate Limits

Limits are per API key, per 60-second rolling window.

Endpoint	Limit
All endpoints	60 requests / minute
POST /api/v1/buy	10 requests / minute

⚠️ Exceeding limits returns 429 Too Many Requests.

Error Codes

All errors return JSON with a status, code, and message field.

Error response

{
  "status": "error",
  "code":   401,
  "message": "Invalid API key."
}

200 Success

400 Bad Request — invalid or missing parameters

401 Unauthorized — missing or invalid API key

402 Payment Required — insufficient balance

404 Not Found — no accounts match your criteria

429 Too Many Requests — rate limit exceeded

503 Service Unavailable — purchase failed, retry

500 Internal Server Error

Endpoints

GET /api/v1/info Public — no auth required

Returns API metadata. Useful for checking if the server is alive.

Response

200 OK

{
  "status":  "success",
  "api":     "Partner API",
  "version": "1.0",
  "endpoints": { ... },
  "contact": "@support"
}

GET /api/v1/balance Get your balance

Returns your current bot balance, total spent, and order count.

Request

curl

curl https://api.vokky.uz/api/v1/balance \
  -H "X-API-Key: YOUR_API_KEY"

Response

200 OK

{
  "status":            "success",
  "user_id":           123456789,
  "balance":           150000.0,
  "balance_formatted": "150,000 so'm",
  "total_spent":       80000.0,
  "orders_count":      4
}

GET /api/v1/stock Available accounts by country

Returns the current number of available accounts for each country.

Request

curl

curl https://api.vokky.uz/api/v1/stock \
  -H "X-API-Key: YOUR_API_KEY"

Response

200 OK

{
  "status":          "success",
  "total_available": 247,
  "countries": {
    "UZ": 45,
    "RU": 102,
    "KZ": 31,
    "UA": 69
  }
}

GET /api/v1/item/{item_id} Get details for a specific account

Returns full details for a single LZT marketplace item including price in so'm.

Path Parameter

Parameter	Type	Description
item_id	integer	LZT item ID required

Request

curl

curl https://api.vokky.uz/api/v1/item/123456 \
  -H "X-API-Key: YOUR_API_KEY"

Response

200 OK

{
  "status": "success",
  "item": {
    "item_id":   123456,
    "title":    "Telegram | UZ | +998...",
    "price_rub": 85.0,
    "price_uzs": 12750,
    "country":  "UZ",
    "premium":  false,
    "spam_block": false,
    "contacts":  312,
    "chats":     5,
    "channels":  2
  }
}

POST /api/v1/buy Purchase an account

Purchases the cheapest available account for the given country. Balance is deducted automatically.

⚠️ This endpoint is limited to 10 requests per minute.

Request Body (JSON)

Field	Type	Description
country	string	2-letter country code (e.g. `"UZ"`, `"RU"`) required
max_price	integer	Max price in so'm optional
spam_allowed	boolean	Allow accounts with spam block. Default: `false` optional

Request

curl

curl -X POST https://api.vokky.uz/api/v1/buy \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "UZ",
    "max_price": 30000,
    "spam_allowed": false
  }'

Python example

python

import requests

response = requests.post(
    "https://api.vokky.uz/api/v1/buy",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"country": "UZ", "max_price": 30000}
)
data = response.json()
if data["status"] == "success":
    print("Login:", data["login"])
    print("Password:", data["password"])

Response

200 OK

{
  "status":            "success",
  "order_id":          42,
  "item_id":           123456,
  "title":             "Telegram | UZ | +998...",
  "country":           "UZ",
  "price_uzs":         12750,
  "remaining_balance": 137250,
  "login":             "+998901234567",
  "password":          "SecretPass123"
}

Status codes

200 Account purchased successfully

400 Missing or invalid country field

402 Insufficient balance

404 No accounts available for this country

429 Rate limit exceeded

503 Purchase failed (provider error), try again