Engagement engines reference

Lootbox, raffle, jackpot, mini-game, tournament, journey — the engines that drive player retention.

Listing configured entities

EndpointReturns
GET /v1/lootboxLootbox templates
GET /v1/rafflesRaffle drops
GET /v1/jackpotsJackpot pools
GET /v1/mini-gamesMini-games
GET /v1/tournamentsTournaments
GET /v1/journeysLifecycle journeys

Lootbox

POST /v1/lootbox/<id>/open

Server-authoritative RNG. Weighted draw from the configured prize table. Posts a balanced WINZ credit to the player. Idempotent on idempotency_key.

POST /v1/lootbox/<id>/open
{ "user_id": "StarlordV7", "idempotency_key": "lb-open-1" }

# 201
{
  "open_id":           "…",
  "reward":            { "asset": "WINZ", "amount": 1500, "segment_label": "big" },
  "server_seed":       "…64 hex",
  "server_seed_hash":  "…64 hex",
  "deduped":           false
}
The server_seed_hash is committed before the draw; the server_seed reveals after. Anyone can recompute the weighted draw from (server_seed, prize_table) and verify the result.

Raffle

POST /v1/raffles/<id>/enter

Debits the configured WINZ ticket cost × tickets. 402 if insufficient balance.

{ "user_id": "StarlordV7", "tickets": 3, "idempotency_key": "raf-1" }
POST /v1/raffles/<id>/draw

Verifiable seeded RNG over the cumulative ticket pool. Marks the raffle completed. Credits the configured prize_winz to the winner.

# 201
{
  "draw_id":            "…",
  "winner_username":    "StarlordV7",
  "prize_winz":         5000,
  "winning_ticket_idx": 2,
  "total_tickets":      10,
  "server_seed":        "…",
  "server_seed_hash":   "…"
}

Jackpot

POST /v1/jackpots/<id>/contribute

The per-wager hook. Call from your wager-settlement pipeline with the already-computed contribution amount.

{
  "user_id":         "StarlordV7",
  "source_wager_id": "your-wager-uuid",
  "amount":          0.50,
  "idempotency_key": "jp-contrib-…"
}
POST /v1/jackpots/<id>/drop

Pay out the current pool. Pool resets to the configured seed_usd. Winner defaults to the last contributor; pass winner_user_id to override (e.g. for must-drop draws).

Mini-game

POST /v1/mini-games/<id>/play

Server-authoritative outcome resolution. Returns the prize segment, credits the WINZ reward. Idempotent.

# 201
{
  "play_id":           "…",
  "outcome":           { "segment_label": "100 WINZ", "amount": 100, "asset": "WINZ" },
  "server_seed":       "…",
  "server_seed_hash":  "…"
}

Tournament

POST /v1/tournaments/<id>/score

Per-wager hook. Default points = wagered × points_per_usd (from tournament config).

{ "user_id": "StarlordV7", "wagered": 50 }
GET /v1/tournaments/<id>/leaderboard?limit=N
POST /v1/tournaments/<id>/close

Distributes the prize pool by the configured prize_structure (default 50/30/20% to top 3) and marks the tournament completed. Idempotent.

Journey

POST /v1/journeys/event

Fire a lifecycle event. Every active journey whose trigger matches advances state. Terminal step grants the configured reward_winz, idempotent per (journey, user).

{ "user_id": "StarlordV7", "trigger": "first_deposit" }

# Response 200
{
  "affected": [
    {
      "journey_id":           "…",
      "journey_name":         "Welcome 3-step",
      "action":               "completed",
      "current_step":         3,
      "reward_winz_granted":  500
    }
  ]
}

Triggers may be platform-defined (signup, first_deposit, wager, dormant_7d, big_win, level_up) or custom strings you defined in the journey config.