Skip to main content
POST
/
api
/
cases
/
open
Open Case
curl --request POST \
  --url https://api.example.com/api/cases/open \
  --header 'Content-Type: application/json' \
  --data '
{
  "caseId": "<string>",
  "clientSeed": "<string>"
}
'
{
  "400": {},
  "401": {},
  "404": {},
  "winner": {
    "winner.id": "<string>",
    "winner.name": "<string>",
    "winner.value": 123,
    "winner.probability": 123,
    "winner.rarity": "<string>"
  },
  "fairness": {
    "fairness.server_seed_hash": "<string>",
    "fairness.client_seed": "<string>",
    "fairness.nonce": 123,
    "fairness.roll_value": 123
  }
}

​
Endpoint

POST /api/cases/open
Opens a case and returns a randomly selected item using the provably fair algorithm. The result is deterministic based on the server seed, client seed, and nonce.

​
Authentication

This endpoint requires authentication. Include a valid Supabase session token.

​
Request Body

​
caseId
string
required
The unique identifier of the case to open. Must exist in the database.
​
clientSeed
string
Optional custom client seed for this opening. If provided and different from the stored seed, it will be updated before the roll calculation.

​
Example Request

{
  "caseId": "550e8400-e29b-41d4-a716-446655440000",
  "clientSeed": "my-custom-seed-123"
}

​
Response

​
Success Response (200 OK)

​
winner
object
The item won from the case opening
​
winner.id
string
Unique identifier of the item
​
winner.name
string
Name of the item
​
winner.value
number
Monetary value of the item
​
winner.probability
number
Drop probability percentage (0-100)
​
winner.rarity
string
Rarity tier: legendary, epic, rare, or common
​
fairness
object
Provably fair verification data
​
fairness.server_seed_hash
string
SHA-256 hash of the server seed used for this roll
​
fairness.client_seed
string
The client seed used for this roll
​
fairness.nonce
number
The nonce value used for this roll (increments with each opening)
​
fairness.roll_value
number
The calculated roll value (0-1) used to determine the winner

​
Example Response

{
  "winner": {
    "id": "item-123",
    "name": "Dragon Lore AWP",
    "value": 2500.00,
    "probability": 0.5,
    "rarity": "legendary",
    "image_url": "https://..."
  },
  "fairness": {
    "server_seed_hash": "a3d5f8b2c1e4d7a9b6c3e1f4d7a9b6c3e1f4d7a9b6c3e1f4d7a9b6c3e1f4d7a9",
    "client_seed": "my-custom-seed-123",
    "nonce": 42,
    "roll_value": 0.00234
  }
}

​
Error Responses

​
401
Unauthorized
User is not authenticated
{
  "error": "Unauthorized"
}
​
404
Not Found
Case with the specified ID does not exist
{
  "error": "Case not found"
}
​
400
Bad Request
Case exists but has no items
{
  "error": "Case is empty"
}

​
Implementation Details

​
Roll Calculation

The endpoint performs the following steps:
  1. Validate User: Checks authentication via Supabase
  2. Fetch Case Data: Retrieves case and its items from the database
  3. Get/Create Seeds: Fetches user’s current seeds or creates initial ones
  4. Update Client Seed: If provided, updates the client seed
  5. Calculate Roll: Uses calculateRollResult(server_seed, client_seed, nonce + 1)
  6. Determine Winner: Selects item based on roll value and probability distribution
  7. Update Nonce: Increments nonce in database
  8. Record Roll: Stores audit trail in game_rolls table
  9. Return Result: Returns winner and fairness data

​
Rarity Mapping

Rarity tiers are determined by probability:
  • Legendary: probability < 1%
  • Epic: probability < 5%
  • Rare: probability < 20%
  • Common: probability >= 20%

​
Code Reference

Implementation: source/app/api/cases/open/route.ts:5

​
cURL Example

curl -X POST https://your-domain.com/api/cases/open \
  -H "Authorization: Bearer YOUR_SUPABASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "caseId": "550e8400-e29b-41d4-a716-446655440000",
    "clientSeed": "my-custom-seed-123"
  }'

​
Verification

After receiving the response, you can verify the fairness:
  1. Store the server_seed_hash, client_seed, and nonce
  2. Later, reveal the server_seed via the provably fair interface
  3. Verify that SHA256(server_seed) matches server_seed_hash
  4. Recalculate the roll using the revealed seeds and nonce
  5. Confirm the roll value produces the same winning item
See the Provably Fair Verification guide for detailed verification steps.

​
Implementation Notes

Balance and Inventory Management: The current implementation focuses on the provably fair roll calculation. Balance deduction and inventory management should be implemented as separate steps:
  • Check user balance before case opening
  • Deduct case price from user balance in a transaction
  • Add won item to user_items table
  • Record transaction in transactions table
The game_rolls table stores the actual server seed used for each roll, enabling users to verify fairness after the round completes.
The nonce automatically increments with each case opening, ensuring each roll is unique even with the same seeds.

Build docs developers (and LLMs) love

Get started for freeTalk to us