Partner Free Tickets

Overview

The Partner Free Tickets API allows partners to distribute free Megapot jackpot tickets to eligible users. This API provides two main functions: checking eligibility and purchasing tickets on behalf of users.

Get Started

Reach out to @patricklung on Telegram to get more info about setting up a partner account or running a giveaway.

Authentication

All API requests require a valid partner API key. Include your API key in one of these ways:

Header Method (Recommended):

curl -H "apikey: YOUR_PARTNER_API_KEY" \
  "https://api.megapot.io/api/v1/giveaways/partner-free-tickets/0x1234..."

Query Parameter Method:

curl "https://api.megapot.io/api/v1/giveaways/partner-free-tickets/0x1234...?apikey=YOUR_PARTNER_API_KEY"

API Endpoints

Check Eligibility

GET /api/v1/giveaways/partner-free-tickets/{walletAddress}

Checks if a wallet address is eligible to receive a free ticket from your partner account.

Parameters:

• walletAddress (path parameter): The Ethereum wallet address to check

Example Request:

curl -H "apikey: YOUR_PARTNER_API_KEY" \
  "https://api.megapot.io/api/v1/giveaways/partner-free-tickets/0x1234..."

Success Response (Eligible):

{
  "eligible": true
}

Success Response (Not Eligible):

{
  "eligible": false,
  "error": "Wallet limit has been reached"
}

Common Error Responses:

{
  "eligible": false,
  "error": "Invalid API key or Partner not found"
}

{
  "eligible": false,
  "error": "Free tickets limit has been reached"
}

{
  "error": "Invalid wallet address"
}

Purchase Free Ticket

POST /api/v1/giveaways/partner-free-tickets/{walletAddress}

Purchases a free ticket on behalf of the specified wallet address if eligible.

Parameters:

• walletAddress (path parameter): The Ethereum wallet address to receive the ticket

Example Request:

curl -X POST \
  -H "apikey: YOUR_PARTNER_API_KEY" \
  "https://api.megapot.io/api/v1/giveaways/partner-free-tickets/0x1234..."

Success Response:

{
  "success": true,
  "receipt": "0x1234...",
  "message": "Free ticket purchased successfully"
}

Error Response (Not Eligible):

{
  "eligible": false,
  "error": "Wallet limit has been reached"
}

Error Response (Transaction Failed):

{
  "error": "Transaction simulation failed"
}

Error Codes

Status Code	Error Message	Description
400	Invalid wallet address	The provided wallet address is not in valid Ethereum format
401	Invalid API key or Partner not found	The API key is invalid or the partner account doesn't exist
500	Internal server error	An unexpected error occurred on the server

Eligibility Rules

A wallet is eligible for a free ticket if ALL of the following conditions are met:

1. Valid Wallet Address: Must be a properly formatted Ethereum address

2. Partner Has Tickets: Your partner account must have remaining tickets (quantityLeft > 0)

3. Wallet Limit Not Reached: The wallet hasn't received the maximum allowed tickets from your partner account

4. Valid API Key: The provided API key must be associated with an active partner account

Usage Examples

JavaScript/Node.js

const checkEligibility = async (walletAddress, apiKey) => {
  const response = await fetch(
    `https://api.megapot.io/api/v1/giveaways/partner-free-tickets/${walletAddress}`,
    {
      headers: {
        'apikey': apiKey
      }
    }
  );
  
  const data = await response.json();
  return data;
};

const purchaseTicket = async (walletAddress, apiKey) => {
  const response = await fetch(
    `https://api.megapot.io/api/v1/giveaways/partner-free-tickets/${walletAddress}`,
    {
      method: 'POST',
      headers: {
        'apikey': apiKey
      }
    }
  );
  
  const data = await response.json();
  return data;
};

// Usage
const walletAddress = '0x1234...';
const apiKey = 'your_partner_api_key';

// Check eligibility first
const eligibility = await checkEligibility(walletAddress, apiKey);
if (eligibility.eligible) {
  // Purchase ticket
  const purchase = await purchaseTicket(walletAddress, apiKey);
  console.log('Transaction hash:', purchase.receipt);
}

Best Practices

1. Always Check Eligibility First: Use the GET endpoint to check eligibility before attempting to purchase tickets

2. Handle Errors Gracefully: Implement proper error handling for all possible response scenarios

3. Validate Wallet Addresses: Ensure wallet addresses are in valid Ethereum format before making API calls

4. Monitor Your Limits: Keep track of your remaining ticket quantity and per-wallet limits

5. Secure API Keys: Never expose your API key in client-side code or public repositories

6. Rate Limiting: Implement appropriate rate limiting in your applications to avoid overwhelming the API