Offer free chances to win

We're offering app developers a chance to offer their users a chance to win big. It's just an API call, no onchain transaction required.

To get started, reach out to @patricklung on Telegram or @pl on Farcaster.

How this differs from cost-effective incentives

Note: Free to Play entries have much lower odds to win. Let's say the odds to win the jackpot are 1 in 1,000,000:

  • Tickets purchased as a cost-effective incentive are 1 in 1,000,000

  • Free to Play entries can vary. If we have 1,000 free to play entries, odds for a free to play entry to win is 1 in 1,000,000,000 (1/000000 * 1/1000).

Eligibility Rules

Frequency

A wallet is eligible to enter if:

  • It has no entry in the current active jackpot round, or

  • Its last entry (any round) was at least 6 hours ago.

All Ethereum addresses are validated and stored in lowercase.

Geo-Blocking

These countries need to be blocked: https://docs.megapot.io/appendix/faq#what-regions-are-geoblocked

Sybil Attack Protection

World mini app

Only verified humans should be eligible on World mini app. The sign-in implementation of World can get the verification level.

Farcaster and Base mini app

Only users with > 0.6 Neynar score should be eligible.

Authentication

All API requests require a valid API key. Please reach out to @patricklung on Telegram or @pl on Farcaster to get an API key.

Include your API key in one of these ways:

Header Method (Recommended) For example:

curl -H "apikey: YOUR_API_KEY" \
  "https://api.megapot.io/api/v1/daily-ticket-pool/active-round"

Query Parameter Method For example:

curl "https://api.megapot.io/api/v1/daily-ticket-pool/active-round?apikey=YOUR_API_KEY"

API Endpoints

Check eligibility

GET /api/v1/giveaways/daily-ticket-pool/{walletAddress}

Check eligibility for the provided wallet.

Response 200:

{
  "eligible": true,
  "currentRoundId": 123
}

If ineligible:

{
  "eligible": false,
  "error": "Try again later",
  "nextEligibleAt": "2025-01-01T12:34:56.000Z",
  "currentRoundId": 123
}

Errors:

  • 400 Invalid wallet address

  • 403 Forbidden (not in giveaways allowlist)

  • 500 Internal error

Check eligibility and claim an entry

POST /api/v1/giveaways/daily-ticket-pool/{walletAddress}

Check eligibility and, if eligible, insert an entry for the active round.

Request Body (optional):

  • refBypass (boolean): When true, bypasses the standard eligibility check and issues a free entry for the active round.

    • An active jackpot round is still required. If none exists, the request returns 400 with {"error":"No active jackpot round"}.

    • API key and giveaways allowlist are still enforced.

    • Accepted values: true/false booleans; also accepts string/number equivalents ("true", "1", 1).

Example body:

{ "refBypass": true }

Response 200 (eligible, inserted):

{
  "eligible": true,
  "entryId": 456,
  "currentRoundId": 123
}

Response 200 (not eligible):

{
  "eligible": false,
  "error": "Try again later",
  "nextEligibleAt": "2025-01-01T12:34:56.000Z",
  "currentRoundId": 123
}

Errors:

  • 400 Invalid wallet address or no active round

  • 403 Forbidden (not in giveaways allowlist)

  • 500 Internal error

Active Round

GET /api/v1/daily-ticket-pool/active-round

Returns the active round id, latest pool transaction (if any), all entries for the round, and totalEntries for the round.

Example Request:

curl -H "apikey: YOUR_API_KEY" \
  "https://api.megapot.io/api/v1/daily-ticket-pool/active-round"

Success Response:

{
  "roundId": 124,
  "transaction": { "id": 1, "transactionHash": "0x...", "blockNumber": 12345678, "timestamp": "..." },
  "entries": [ { "id": 1, "address": "0x...", "timestamp": "..." } ],
  "totalEntries": 42
}

Notes:

  • Returns { "message": "No active round" } with status 200 if there is no active round.

Active Round (Wallet Filter)

GET /api/v1/daily-ticket-pool/active-round/{walletAddress}

Returns the active round id, latest pool transaction (if any), entries for the provided wallet only, and totalEntries for the round (not filtered by wallet).

Parameters:

  • walletAddress (path parameter): Ethereum wallet address

Example Request:

curl -H "apikey: YOUR_API_KEY" \
  "https://api.megapot.io/api/v1/daily-ticket-pool/active-round/0x1234..."

Success Response:

{
  "roundId": 124,
  "transaction": { "id": 1, "transactionHash": "0x...", "blockNumber": 12345678, "timestamp": "..." },
  "entries": [ { "id": 7, "address": "0xabc...", "timestamp": "..." } ],
  "totalEntries": 42
}

Common Error Responses:

{ "error": "Invalid wallet address" }

Latest Completed Round

GET /api/v1/daily-ticket-pool/round

Returns latest completed round data: pool transaction, entries, totalEntries, and winner.

Example Request:

curl -H "apikey: YOUR_API_KEY" \
  "https://api.megapot.io/api/v1/daily-ticket-pool/round"

Success Response:

{
  "roundId": 123,
  "transaction": { "id": 9, "transactionHash": "0x...", "blockNumber": 12345000, "timestamp": "..." },
  "entries": [ ... ],
  "totalEntries": 37,
  "winner": { "id": 5, "address": "0x...", "timestamp": "..." }
}

Specific Round

GET /api/v1/daily-ticket-pool/round/{roundId}

Returns a specific round’s pool transaction, entries, and totalEntries. Includes winner only if the round is not active.

Parameters:

  • roundId (path parameter): Jackpot round id

Example Request:

curl -H "apikey: YOUR_API_KEY" \
  "https://api.megapot.io/api/v1/daily-ticket-pool/round/120"

Success Response:

{
  "roundId": 120,
  "transaction": { ... },
  "entries": [ ... ],
  "totalEntries": 10,
  "winner": { ... }
}

Common Error Responses:

{ "error": "Invalid round id" }
{ "error": "Round not found" }

Specific Round (Wallet Filter)

GET /api/v1/daily-ticket-pool/round/{roundId}/{walletAddress}

Returns a specific round’s pool transaction and entries for the provided wallet address only, plus totalEntries for the round (not filtered by wallet). Includes winner only if the round is not active.

Parameters:

  • roundId (path parameter): Jackpot round id

  • walletAddress (path parameter): Ethereum wallet address

Example Request:

curl -H "apikey: YOUR_API_KEY" \
  "https://api.megapot.io/api/v1/daily-ticket-pool/round/120/0x1234..."

Success Response:

{
  "roundId": 120,
  "transaction": { "id": 9, "transactionHash": "0x...", "blockNumber": 12345000, "timestamp": "..." },
  "entries": [ { "id": 5, "address": "0xabc...", "timestamp": "..." } ],
  "totalEntries": 10,
  "winner": { "id": 7, "address": "0xdef...", "timestamp": "..." }
}

Common Error Responses:

{ "error": "Invalid round id" }
{ "error": "Invalid wallet address" }
{ "error": "Round not found" }

Wallet Entries (All Rounds)

GET /api/v1/daily-ticket-pool/{walletAddress}

Returns all Daily Ticket Pool entries for the provided wallet across rounds.

Parameters:

  • walletAddress (path parameter): Ethereum wallet address

Example Request:

curl -H "apikey: YOUR_API_KEY" \
  "https://api.megapot.io/api/v1/daily-ticket-pool/0x1234..."

Success Response:

{
  "entries": [ { "id": 1, "address": "0xabc...", "jackpotRoundId": 123, "timestamp": "..." } ]
}

Common Error Responses:

{ "error": "Invalid wallet address" }

Error Codes

Status Code
Error Message
Description

400

Invalid wallet address

The provided wallet address is not in valid Ethereum format

400

Invalid round id

The provided round id is invalid

404

Round not found

The specified round does not exist

500

Internal server error

An unexpected error occurred on the server

Usage Examples

JavaScript/Node.js

const getActiveRound = async (apiKey) => {
  const response = await fetch(
    `https://api.megapot.io/api/v1/daily-ticket-pool/active-round`,
    {
      headers: { 'apikey': apiKey }
    }
  );
  return response.json();
};

const getWalletRoundEntries = async (roundId, walletAddress, apiKey) => {
  const response = await fetch(
    `https://api.megapot.io/api/v1/daily-ticket-pool/round/${roundId}/${walletAddress}`,
    {
      headers: { 'apikey': apiKey }
    }
  );
  return response.json();
};

Best Practices

  1. Validate wallet addresses before making API calls

  2. Implement appropriate error handling for all possible response scenarios

  3. Secure your API keys; avoid exposing them in client-side code or public repositories

  4. Implement rate limiting to avoid overwhelming the API

PrevioususeJackpotNextOffer cost-effective incentives

Last updated