Skip to main content

Public API Reference

Prizee LOTTERY 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).
  • 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,
    "ticketPrice": 2,
    "poolMode": "rolling_jackpot",
    "currency": "USDC",
    "status": "scheduled",
    "escrowAddress": "0x39a1...44bc"
  }
]

GET /api/lotteries/:id​

Retrieves comprehensive details for a specific lottery round, including social task requirements, prize breakdown, and participating numbers.

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.