API v2 Documentation

Authentication

Every request must include your API key as the key parameter. Obtain your key from the Dashboard under Settings → API Key.

All requests are POST to https://viralhub.io/api/v2 with Content-Type: application/x-www-form-urlencoded or application/json.

POST https://viralhub.io/api/v2

Example request

curl -X POST https://viralhub.io/api/v2 \
  -d "key=YOUR_API_KEY&action=balance"

Authentication error response

{ "error": "Invalid API key" }

All error responses return a JSON object with an error string. HTTP status remains 200 for API-level errors (prosmm-compatible behaviour).

Service List

Returns the full list of available services with their IDs, names, types, rates, and order limits.

Parameter	Value	Required
key	Your API key	Yes
action	`services`	Yes

cURL example

curl -X POST https://viralhub.io/api/v2 \
  -d "key=YOUR_API_KEY&action=services"

Example response

[
  {
    "service": 1,
    "name": "Telegram Channel Members",
    "type": "Default",
    "category": "Telegram",
    "rate": "0.80",
    "min": 100,
    "max": 500000,
    "refill": true,
    "cancel": false,
    "description": "Real-looking members, no password needed, fast delivery."
  },
  {
    "service": 2,
    "name": "Telegram Channel Members — HQ",
    "type": "Default",
    "category": "Telegram",
    "rate": "1.20",
    "min": 100,
    "max": 100000,
    "refill": true,
    "cancel": false,
    "description": "High-quality members, slower but more stable."
  }
]

Add Order

Place a new SMM order. Funds are deducted from your account balance immediately. For Custom Comments and Mentions order types, additional parameters are required.

Parameter	Description	Required
key	Your API key	Yes
action	`add`	Yes
service	Service ID (integer)	Yes
link	Target URL or username	Yes
quantity	Number of units to order (within service min/max)	Yes
runs	Drip-feed: number of runs (optional)	No
interval	Drip-feed: minutes between runs (optional)	No
comments	Newline-separated comments (Custom Comments type only)	Conditional

cURL example

curl -X POST https://viralhub.io/api/v2 \
  -d "key=YOUR_API_KEY&action=add&service=1&link=https://t.me/mychannel&quantity=1000"

Example response

{ "order": 23501 }

Error response

{ "error": "Incorrect quantity" }

Order Status

Retrieve the current status of a single order by its ID.

Parameter	Description	Required
key	Your API key	Yes
action	`status`	Yes
order	Order ID (integer)	Yes

cURL example

curl -X POST https://viralhub.io/api/v2 \
  -d "key=YOUR_API_KEY&action=status&order=23501"

Example response

{
  "charge":    "0.80",
  "start_count": 4234,
  "status":    "In progress",
  "remains":   300,
  "currency":  "USD"
}

Possible status values: Pending, In progress, Completed, Partial, Canceled, Processing.

Multiple Orders Status

Retrieve statuses for multiple orders in a single request. Pass a comma-separated list of order IDs.

Parameter	Description	Required
key	Your API key	Yes
action	`status`	Yes
orders	Comma-separated order IDs (max 100)	Yes

cURL example

curl -X POST https://viralhub.io/api/v2 \
  -d "key=YOUR_API_KEY&action=status&orders=23501,23502,23503"

Example response

{
  "23501": { "charge": "0.80", "start_count": 4234, "status": "Completed", "remains": 0,   "currency": "USD" },
  "23502": { "charge": "1.20", "start_count": 100,  "status": "In progress","remains": 450, "currency": "USD" },
  "23503": { "charge": "0.25", "start_count": 880,  "status": "Pending",    "remains": 200, "currency": "USD" }
}

User Balance

Returns the current account balance and currency for the authenticated API key.

Parameter	Value	Required
key	Your API key	Yes
action	`balance`	Yes

cURL example

curl -X POST https://viralhub.io/api/v2 \
  -d "key=YOUR_API_KEY&action=balance"

Example response

{ "balance": "47.50", "currency": "USD" }

Refill Order

Request a refill for an order that supports the refill feature. Only orders with refill: true on the service are eligible.

Parameter	Description	Required
key	Your API key	Yes
action	`refill`	Yes
order	Order ID to refill	Yes

cURL example

curl -X POST https://viralhub.io/api/v2 \
  -d "key=YOUR_API_KEY&action=refill&order=23501"

Example response

{ "refill": 1178 }

Refill Status

Check the status of a previously submitted refill request.

Parameter	Description	Required
key	Your API key	Yes
action	`refill_status`	Yes
refill	Refill ID returned from the refill action	Yes

cURL example

curl -X POST https://viralhub.io/api/v2 \
  -d "key=YOUR_API_KEY&action=refill_status&refill=1178"

Example response

{ "status": "Completed" }

Possible status values: Pending, In progress, Completed, Rejected.

Cancel Orders

Request cancellation for one or more orders. Only orders with cancel: true on the service are eligible. A partial refund is issued for the unfulfilled portion.

Parameter	Description	Required
key	Your API key	Yes
action	`cancel`	Yes
orders	Comma-separated order IDs (max 100)	Yes

cURL example

curl -X POST https://viralhub.io/api/v2 \
  -d "key=YOUR_API_KEY&action=cancel&orders=23502,23503"

Example response

[
  { "order": 23502, "cancel": { "status": "success" } },
  { "order": 23503, "cancel": { "status": "success" } }
]

Error — cancel not supported

{ "error": "Cancel not available for this service" }

Subscriptions

Subscriptions automatically place repeat orders on a schedule (e.g. daily views drip-feed). Manage them via the dashboard or API.

Parameter	Description	Required
key	Your API key	Yes
action	`subscriptions`	Yes

cURL example — list subscriptions

curl -X POST https://viralhub.io/api/v2 \
  -d "key=YOUR_API_KEY&action=subscriptions"

Example response

[
  {
    "id": 99,
    "service": 3,
    "link": "https://t.me/c/123456789/42",
    "quantity": 5000,
    "runs": 30,
    "interval": 1440,
    "remaining_runs": 22,
    "status": "Active",
    "created_at": "2026-04-01T08:00:00Z"
  }
]

To stop a subscription, visit the Dashboard under Orders → Subscriptions or contact support.