API Reference

Buy verified USA numbers programmatically and fetch OTP codes — built for automation.

Base URL: https://xthonvirtual.store/api/v2Format: JSONAuth: API key

Authentication#

Send your personal API key in a header with every request. Grab it from the bot under 🔑 API.

HTTP

X-API-Key: YOUR_API_KEY

All responses share one envelope: { "ok": boolean, "data": …, "message": string｜null }. On failure ok is false and message says why.

Quick start#

Check your balance, then: list services → buy → poll for the code.

cURL

curl "https://xthonvirtual.store/api/v2/balance" -H "X-API-Key: YOUR_API_KEY"

Endpoints#

GET /balance

Returns the caller's current balance and bonus tier.

cURL

curl -X GET "https://xthonvirtual.store/api/v2/balance" \
  -H "X-API-Key: YOUR_API_KEY"

JSON

{
  "ok": true,
  "data": { "balance": "12.50", "bonus": 10 }
}

GET /services

Lists active services. The price already includes your bonus discount.

cURL

curl -X GET "https://xthonvirtual.store/api/v2/services" \
  -H "X-API-Key: YOUR_API_KEY"

JSON

{
  "ok": true,
  "data": [
    {
      "id": "8f3c…",
      "name": "USA Telegram",
      "price": "1.20",
      "stock": 42
    }
  ]
}

POST /services/{service_id}/buy

Reserves one number from a service and charges your balance. Returns a transaction you then poll for the code.

cURL

curl -X POST "https://xthonvirtual.store/api/v2/services/{service_id}/buy" \
  -H "X-API-Key: YOUR_API_KEY"

JSON

{
  "ok": true,
  "data": {
    "id": "tx_91a…",
    "status": "PENDING",
    "price": "1.20",
    "number": "+15550001",
    "service": "USA Telegram",
    "code": null
  }
}

GET /transactions/{transaction_id}

Fetches a transaction (number) you own.

cURL

curl -X GET "https://xthonvirtual.store/api/v2/transactions/{transaction_id}" \
  -H "X-API-Key: YOUR_API_KEY"

JSON

{
  "ok": true,
  "data": {
    "id": "tx_91a…",
    "status": "PENDING",
    "number": "+15550001",
    "code": null
  }
}

GET /transactions/{transaction_id}/code

Polls for the verification code. Returns code: null with a message until it arrives.

cURL

curl -X GET "https://xthonvirtual.store/api/v2/transactions/{transaction_id}/code" \
  -H "X-API-Key: YOUR_API_KEY"

JSON

{
  "ok": true,
  "data": {
    "id": "tx_91a…",
    "status": "SUCCEEDED",
    "code": "54321"
  }
}

POST /transactions/{transaction_id}/cancel

Refunds a PENDING number that never received a code, returning the balance.

cURL

curl -X POST "https://xthonvirtual.store/api/v2/transactions/{transaction_id}/cancel" \
  -H "X-API-Key: YOUR_API_KEY"

JSON

{
  "ok": true,
  "data": { "refunded": "1.20" }
}

Errors#

Status	Meaning
`200`	Success
`401`	Missing or invalid API key
`402`	Insufficient balance
`404`	Not found
`409`	Out of stock

✨ Xthon Virtual — Beyond LIMITS