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

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 one or more integers in a range. Ranges are sampled without modulo bias.

Example

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

{
  "numbers": [42, 7, 91],
  "source": "anu",
  "request_id": "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
}

{
  "chosen": ["Bob"],
  "source": "nist",
  "request_id": "..."
}

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

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

{
  "hex": "3f9a2b8c...",
  "bytes_count": 32,
  "source": "anu",
  "request_id": "..."
}

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

401 — missing or invalid key.

403 — the plan does not include Business API.

429 — daily API limit exceeded.

500 — temporary service error. Retry with backoff.

Quantum randomness you can embed into your product

Overview

Authorization

Random endpoints

Giveaway endpoints

Verification and trust

Public verify URL

Audit trail

Resilience cascade

Errors

Ready to connect verifiable randomness?