Skip to main content

Public API Reference

Prizee Raffle provides a public REST API enabling developers, ecosystem aggregators, and analytics platforms to query lottery rounds, ticket statistics, verified draw outcomes, and on-chain proofs.

Overview & Authentication​

  • Format: Standard JSON responses over HTTPS.
  • Authentication: Public read endpoints (browsing rounds, historical draws, seed data) do not require authentication.
  • Protected Actions: User-specific endpoints (fetching user tickets, participating in campaigns) require a Bearer token in the request header:
Authorization: Bearer <auth_token>

Core Endpoints​

1. Rounds & Lotteries​

GET /api/lotteries​

Retrieves a list of all active, scheduled, and completed lottery rounds.

  • Query Parameters:
    • status: Filter by round status (scheduled, open, drawn, refunded).
    • mode: Filter by pool type (rolling_jackpot, fixed_lottery, task_reward). Create UI: Jackpot always posts rolling_jackpot (no single-draw fallback option) and Raffle (task_reward FCFS or random). fixed_lottery remains readable for legacy rounds.
  • Response Format:
[
  {
    "id": "673abc45f89123004e12ab89",
    "code": 104,
    "title": "Genesis Jackpot #104",
    "description": "Weekly rolling jackpot on Arc Testnet",
    "creatorName": "Prizee Core",
    "drawAt": "2026-09-10T12:00:00.000Z",
    "prizePool": 2500,
    "prizeKind": "usdc",
    "prizeLabel": "",
    "visibility": "public",
    "ticketPrice": 2,
    "poolMode": "rolling_jackpot",
    "currency": "USDC",
    "status": "scheduled",
    "escrowAddress": "0x39a1...44bc"
  }
]

GET /api/lotteries/:id​

Retrieves a round, including tasks, prizeKind (usdc | custom), prizeLabel / prizeNote, and visibility (public | unlisted). Unlisted rounds are omitted from the public list but this path still returns them.

POST /api/lotteries​

Creates a raffle or jackpot campaign (auth). Raffle custom prizes: prizeKind: "custom", prizeLabel required, basePrizePool 0, no seed. Task URLs must be X links matching the task kind.

PUT /api/lotteries/:id​

Creator edit of display fields, visibility, X tasks, and custom prize label/note. Cannot change prize/mode/deadline. Cannot switch custom → USDC after a winner exists.

PUT /api/lotteries/:id/reward-contact​

Winner of a custom raffle submits { telegram, x, wallet }. Status becomes submitted.

POST /api/lotteries/:id/reward-fulfill​

Creator marks that winner fulfilled.

GET /api/lotteries/:id/board​

Completers plus reward rows. Custom winners include contactTelegram, contactX, contactWallet, prizeLabel.

2. Tickets & Participation​

GET /api/tickets/my​

Retrieves tickets purchased by the authenticated user across active and historic rounds.

  • Response Format:
[
  {
    "id": "tkt_81726a",
    "roundId": "673abc45f89123004e12ab89",
    "numbers": [7, 14, 21, 33, 42, 51],
    "paymentTxHash": "0x892a...1234",
    "paidAmount": 2,
    "currency": "USDC",
    "createdAt": "2026-09-04T10:00:00.000Z"
  }
]

3. Draws & Verifiable Outcomes​

GET /api/draws​

Returns historic draw results, winning number sequences, and distribution records.

  • Response Format:
[
  {
    "id": "drw_554109",
    "roundCode": 104,
    "targetBlock": 1429810,
    "blockHash": "0x9f8b2c4a...77a1",
    "winningNumbers": [7, 14, 21, 33, 42, 51],
    "totalWinners": 3,
    "totalPrizePaid": 2500,
    "currency": "USDC",
    "settledAt": "2026-09-10T12:01:14.000Z"
  }
]

GET /api/draws/:id​

Returns detailed cryptographic verification data for a specific draw, including:

  • targetBlock: The agreed future block height on the Arc Network.
  • blockHash: The mined block hash seed.
  • seedSteps: The complete digit sequence mapping explaining how each winning number was derived.
  • winners: List of winning tickets and their corresponding payout amounts.