Free To Play

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

Validate wallet addresses before making API calls
Implement appropriate error handling for all possible response scenarios
Secure your API keys; avoid exposing them in client-side code or public repositories
Implement rate limiting to avoid overwhelming the API

Overview

Deep dive

Developers

Appendix

Legal

How this differs from cost-effective incentives

Eligibility Rules

Frequency

Geo-Blocking

Sybil Attack Protection

World mini app

Farcaster and Base mini app

Authentication

API Endpoints

Check eligibility

Check eligibility and claim an entry

Active Round

Active Round (Wallet Filter)

Latest Completed Round

Specific Round

Specific Round (Wallet Filter)

Wallet Entries (All Rounds)

Error Codes

Usage Examples

JavaScript/Node.js

Best Practices

​How this differs from cost-effective incentives

​Eligibility Rules

​Frequency

​Geo-Blocking

​Sybil Attack Protection

​World mini app

​Farcaster and Base mini app

​Authentication

​API Endpoints

​Check eligibility

​Check eligibility and claim an entry

​Active Round

​Active Round (Wallet Filter)

​Latest Completed Round

​Specific Round

​Specific Round (Wallet Filter)

​Wallet Entries (All Rounds)

​Error Codes

​Usage Examples

​JavaScript/Node.js

​Best Practices

How this differs from cost-effective incentives

Eligibility Rules

Frequency

Geo-Blocking

Sybil Attack Protection

World mini app

Farcaster and Base mini app

Authentication

API Endpoints

Check eligibility

Check eligibility and claim an entry

Active Round

Active Round (Wallet Filter)

Latest Completed Round

Specific Round

Specific Round (Wallet Filter)

Wallet Entries (All Rounds)

Error Codes

Usage Examples

JavaScript/Node.js

Best Practices