Card shuffling is one of the most scrutinised operations in online gambling. Regulators, players, and auditors all need confidence that the shuffle is fair - that no card position is more likely than any other, and that the outcome cannot be predicted or manipulated. This tutorial shows how to implement provably fair card shuffling using TrueEntropy's quantum shuffle endpoint.

The Problem with PRNG Shuffling

Most online card games shuffle decks using pseudo-random number generators. The standard approach is the Fisher-Yates algorithm - an O(n) shuffle that's mathematically proven to produce a uniform distribution provided the underlying random source is uniformly distributed.

That proviso is the critical weakness. A PRNG's output is deterministic - entirely determined by its internal state. If an attacker can observe enough outputs, they can reconstruct the state and predict every future shuffle. For a 52-card deck, there are 52! (approximately 8 × 10⁶⁷) possible orderings. Most PRNGs have internal states of 128 or 256 bits, which means they can produce at most 2²⁵⁶ (approximately 1.2 × 10⁷⁷) distinct sequences. While this is technically larger than 52!, the deterministic nature means the actual sequence is fixed once the seed is known.

Quantum randomness eliminates this attack surface entirely. (For more on why PRNGs fall short, see our article on why PRNGs are not enough.) Each random number is generated by a physical measurement that is fundamentally unpredictable - not because we lack information about the system, but because the information doesn't exist until the measurement occurs.

The Shuffle Endpoint

TrueEntropy provides a dedicated /v1/shuffle endpoint that implements Fisher-Yates shuffling with quantum entropy. You provide an array of items, and the API returns them in a cryptographically fair random order.

$ curl https://api.trueentropy.net/v1/shuffle \
  -X POST \
  -H "Authorization: Bearer te_live_..." \
  -H "Content-Type: application/json" \
  -d '{"items": ["A♠","2♠","3♠","4♠","5♠","6♠","7♠","8♠","9♠","10♠","J♠","Q♠","K♠","A♥","2♥","3♥"..."K♦"]}'

The response contains the shuffled array along with metadata confirming the quantum source:

{
  "data": {
    "shuffled": ["7♦", "Q♠", "3♥", "A♣", ...],
    "count": 52
  },
  "metadata": {
    "source": "quantum",
    "nist_verified": true
  }
}

How Fisher-Yates Works

The Fisher-Yates shuffle (also called the Knuth shuffle) works by iterating through the array from the last element to the second, and at each position i, swapping the element at position i with a randomly chosen element from positions 0 to i (inclusive).

The key property: if the random selection at each step is uniformly distributed, then every possible permutation of the array is equally likely. The algorithm requires exactly n−1 random selections for an array of n elements.

For a 52-card deck, that's 51 random numbers. In TrueEntropy's implementation, each of those 51 random numbers is derived from quantum entropy read from the binary pool file using rejection sampling to ensure uniform distribution within the required range.

Integration Example

Here's a practical example of shuffling a deck for a poker game using Python:

import requests

suits = ["♠", "♥", "♦", "♣"]
ranks = ["A","2","3","4","5","6","7","8","9","10","J","Q","K"]
deck = [f"{r}{s}" for s in suits for r in ranks]

resp = requests.post(
    "https://api.trueentropy.net/v1/shuffle",
    headers={"Authorization": "Bearer te_live_..."},
    json={"items": deck},
)

shuffled = resp.json()["data"]["shuffled"]
# Deal first 5 cards
hand = shuffled[:5]

UKGC Compliance: The Target

The UK Gambling Commission (UKGC) publishes Remote Technical Standards (RTS), with RTS 7 specifically addressing random number generation. See our UKGC RTS 7 documentation for details. RTS 7 requires that RNG systems used in gambling are tested and certified to demonstrate that outputs are unpredictable and statistically independent.

TrueEntropy is not yet UKGC-certified. Certification is a formal process that requires independent third-party testing by an accredited laboratory, documentation of the complete RNG methodology, and ongoing compliance monitoring. We are actively building toward UKGC compliance and have designed TrueEntropy's architecture with RTS 7 requirements in mind:

Statistical independence - Quantum measurements are physically independent events
Unpredictability - Quantum randomness is provably unpredictable by the laws of physics
Statistical testing - NIST SP 800-22 tests verify the quality of every batch
Audit trail - Every API response includes metadata identifying the quantum source and verification status

If you're building a gambling platform and considering TrueEntropy for your RNG, we'd welcome the conversation. UKGC compliance is a priority on our roadmap, and we're designing every component with certification in mind.

Why Quantum Shuffling Matters

For regulated industries, the source of randomness is not a technicality - it's a compliance requirement and a trust signal. Quantum shuffling with TrueEntropy provides a mathematically and physically grounded guarantee that your shuffles are fair, verifiable, and impossible to predict.

That's not a marketing claim. It's quantum mechanics.

Quantum Card Shuffling: Building Provably Fair Games with TrueEntropy