Back to Main Site

Quantum-Safe Provably Fair Deck API Documentation

Base URL:
https://api.provablyfairdeck.com/v1

Overview

The Quantum-Safe Provably Fair Deck API provides cryptographically secure, quantum-resistant endpoints for fair card shuffling, dealing, and verification in online games. All operations are transparent, auditable, and privacy-preserving.

Authentication

All endpoints require HTTPS. For production, use your API key in the X-API-Key header.

Endpoints

1. Create Game

// Request
POST /game
{
  "gameType": "poker",
  "maxPlayers": 6
}
// Response
{
  "gameId": "game_8f3a2b1c",
  "status": "waiting_for_players"
}

2. Register Player

// Request
POST /game/{gameId}/player
{
  "playerName": "Alice",
  "publicKey": "-----BEGIN PUBLIC KEY-----..."
}
// Response
{
  "playerId": "player_1a2b3c",
  "status": "registered"
}

3. Submit Seeds

// Request
POST /game/{gameId}/seeds
{
  "playerId": "player_1a2b3c",
  "playerSeed": "a1b2c3d4e5f6",
  "serverSeed": "z9y8x7w6v5u4"
}
// Response
{
  "status": "seeds_submitted",
  "combinedSeedHash": "b7e23ec29af..."
}

4. Shuffle Deck

// Request
POST /game/{gameId}/shuffle
{
  "initiatorId": "player_1a2b3c"
}
// Response
{
  "deckId": "deck_9d8c7b6a",
  "merkleRoot": "4e6f92d...abc",
  "encryptedDeck": [
    "u5t4h3f2...",
    "k2j3h4g5..."
  ]
}

5. Deal Card

// Request
POST /game/{gameId}/deal
{
  "playerId": "player_1a2b3c"
}
// Response
{
  "cardIndex": 5,
  "cardCiphertext": "u5t4h3f2...",
  "merkleProof": [
    "c9a1...", "f0d2...", "a7b3..."
  ]
}

6. Reveal Card

// Request
POST /game/{gameId}/reveal
{
  "playerId": "player_1a2b3c",
  "cardIndex": 5,
  "cardPlaintext": "8♠",
  "merkleProof": [
    "c9a1...", "f0d2...", "a7b3..."
  ]
}
// Response
{
  "verified": true,
  "message": "Card is valid and matches the committed deck."
}

7. Verify Deck

// Request
GET /game/{gameId}/deck
// Response
{
  "deck": [
    {
      "cardIndex": 0,
      "cardCiphertext": "u5t4h3f2..."
    },
    // ...
  ],
  "merkleRoot": "4e6f92d...abc"
}

Summary Table

Endpoint	Method	Description
/game	POST	Create a new game
/game/{gameId}/player	POST	Register a player
/game/{gameId}/seeds	POST	Submit player/server seeds
/game/{gameId}/shuffle	POST	Shuffle deck and commit
/game/{gameId}/deal	POST	Deal encrypted card
/game/{gameId}/reveal	POST	Reveal and verify card
/game/{gameId}/deck	GET	Get full deck for audit

For integration help, contact support@provablyfairdeck.com.