Business API Docs — Quantum Random Bot

Overview

Quantum Random Bot Business API gives your product access to verifiable randomness and giveaway workflows without a manual Telegram flow.

Every important result can be tied to a public Certificate ID, verify URL and PDF certificate for participants, legal teams, sponsors or internal audit.

Authorization

Every request requires the Authorization: Bearer <key> header. The key is created inside the bot on the Business plan.

The plaintext key is shown only once at creation. Store it as a secret and never send it to a client browser.

Authorization: Bearer qrng_xxxxxxxxxxxxxxxxx

Request IDs

X-Request-ID is the technical identifier for one HTTP request. Send your own identifier of up to 128 ASCII letters, digits or . _ : - characters, or omit the header and the server will generate one. The response returns the effective X-Request-ID, including handled API errors.

request_id in JSON identifies an individual QRNG operation that obtained randomness. It is different from X-Request-ID and is used to verify the randomness source.

qrng_request_ids contains every QRNG identifier when one HTTP request performs multiple operations. For example, /random/int with count=3 returns three values; request_id then contains the identifier of the final operation.

When contacting support, send the X-Request-ID from the response header. For questions about a specific random result, also include request_id or qrng_request_ids from the JSON body.

Request:
X-Request-ID: order-2026-00042

Response:
X-Request-ID: order-2026-00042

Random endpoints

GET /api/v1/me key information +

Returns the current API key plan, limits and usage statistics.

Example

{
  "plan": "business",
  "key_prefix": "qrng_J5b8aB",
  "requests_today": 42,
  "daily_limit": 1000
}

GET /api/v1/random/int integer without modulo bias +

Generates 1 to 100 integers in the inclusive min–max range. min must be less than max, and the range span must not exceed 1,000,000,000. Values are sampled without modulo bias.

Example

GET /api/v1/random/int?min=1&max=100&count=3

{
  "numbers": [42, 7, 91],
  "count": 3,
  "range": {"min": 1, "max": 100},
  "qrng_source": "anu",
  "request_id": "c46bd22a-de82-466e-9571-8fc56d655b3e",
  "qrng_request_ids": [
    "8f3d9251-33ad-4930-a6f3-115740b5e7d1",
    "68f0348e-a965-4e7a-a121-80f3be21d108",
    "c46bd22a-de82-466e-9571-8fc56d655b3e"
  ]
}

POST /api/v1/random/choice selection from a list +

Selects one or more items from a list.

Example

{
  "items": ["Alice", "Bob", "Charlie"],
  "count": 1,
  "unique": true
}

{
  "chosen": ["Bob"],
  "count": 1,
  "from_total": 3,
  "qrng_source": "nist",
  "request_id": "2d2babbb-5cc4-4a63-b514-6505836c78bd"
}

POST /api/v1/random/shuffle Fisher-Yates shuffle +

Shuffles an array using Fisher-Yates and a quantum randomness source.

Example

{
  "items": ["A", "B", "C", "D"]
}

{
  "shuffled": ["C", "A", "D", "B"],
  "count": 4,
  "qrng_source": "anu",
  "request_id": "31d20e70-da21-4773-b979-460ab68eacc2"
}

GET /api/v1/random/bytes random bytes +

Returns hex bytes for tokens and keys: secure system entropy with quantum-mix when an external source is available.

Example

GET /api/v1/random/bytes?n=32&format=hex

{
  "bytes": "3f9a2b8c...",
  "format": "hex",
  "length": 32,
  "qrng_source": "anu",
  "request_id": "51c8d364-6a66-405c-ad8b-af6bd14c5160",
  "pool": "crypto"
}

Giveaway endpoints

GET /api/v1/giveaways create and list giveaways +

Returns or creates giveaways linked to the user or API key.

Example

{
  "giveaways": [
    {
      "public_id": "A1B2C3D4",
      "title": "My Giveaway",
      "status": "active",
      "participants_count": 500
    }
  ],
  "total": 1
}

POST /api/v1/giveaways create and list giveaways +

Returns or creates giveaways linked to the user or API key.

Example

{
  "title": "My API Giveaway",
  "winners_count": 3,
  "description": "Optional campaign copy"
}

POST /api/v1/giveaways/{id}/draw winner selection +

Runs winner selection and returns data for public verification.

Example

{
  "winners": [
    {"username": "alice", "telegram_id": 123456}
  ],
  "certificate_id": "17d58bb5...",
  "verify_url": "https://quantum-bot.space/verify/17d58bb5...",
  "qrng_source": "anu",
  "request_id": "..."
}

GET /api/v1/giveaways/{id}/participants.csv CSV export +

CSV report for sponsors, legal teams, accounting and internal audit.

Example

telegram_id,username,first_name,joined_at,is_winner
123456,alice,Alice,2026-05-05T12:00:00,true
789012,bob,Bob,2026-05-05T12:05:00,false

Verification and trust

Public verify URL

Participants open the certificate page and see the source, algorithm, hash and winners.

Audit trail

Business receives enough data for reporting and internal result review.

Resilience cascade

If one external source is unavailable, the request moves to the next level and the used source is recorded.

Errors

400 — invalid request parameters or body.

401 — missing, invalid or revoked key.

403 — the plan does not include Business API or the resource belongs to another user.

404 — requested resource not found.

422 — a parameter has an invalid type or format.

429 — daily API limit exceeded.

500 — unexpected internal service error.

503 — the QRNG service is temporarily unavailable. Retry with exponential backoff.

Quantum randomness you can embed into your product

Overview

Authorization

Request IDs

Random endpoints

Giveaway endpoints

Verification and trust

Public verify URL

Audit trail

Resilience cascade

Errors

Ready to connect verifiable randomness?