DEV Community

Cover image for Giveaway Verification API: Check Retweets, Replies, Follows
XCROP
XCROP

Posted on Originally published at xcrop.io

Giveaway Verification API: Check Retweets, Replies, Follows

The Problem: Manual Verification Doesn't Scale

Running an airdrop, giveaway or NFT whitelist on X? You've probably seen the drill:

  1. Post a tweet: "Retweet + Reply (tag 3 friends) + Follow to enter"
  2. Thousands of entries flood in
  3. Now... how do you verify all of them?

Manually checking 5,000 retweets and 5,000 replies is impossible. Many projects resort to random selection (unfair) or trusting participants (exploitable). Bots and fake entries slip through

XCROP's Interaction Check API solves this. Seven dedicated endpoints let you programmatically verify every single participant (retweets, replies, quotes, follow relationships, and account-quality filters) in minutes

The 7 Interaction Check Endpoints

Endpoint What it checks Credits
GET /v2/tweets/:tweetId/check-retweet Did user retweet? 50
GET /v2/tweets/:tweetId/check-reply Did user reply? (+ tag verification) 50
GET /v2/tweets/:tweetId/check-quote Did user quote-tweet? (+ tag verification) 50
GET /v2/users/:username/check-qualified-account Account old enough / enough followers? 50
GET /v2/users/:username/check-qualified-name Display name contains required text? 50
GET /v2/users/check-follow Does user follow you? 50
GET /v2/users/:username/check-median-views Do people see the account's recent posts? (median views, filters bots) 200 to 400

Every endpoint returns a simple boolean result (qualified for the eligibility checks), no complex parsing needed

Note on likes: X removed public like visibility in June 2024, so like-checking is not offered. Use retweet, reply, and quote checks instead, plus the qualified-account checks above to filter bot entries by account age, follower count, or display-name requirements

Quick Start: Verify a Single User

import requests
import os

API_KEY = os.environ["XCROP_API_KEY"]
HEADERS = {"Authorization": "Bearer " + API_KEY}
BASE = "https://xcrop.io/api/v2"
TWEET_ID = "1893045621038174208"

# Check retweet
rt = requests.get(
    BASE + "/tweets/" + TWEET_ID + "/check-retweet",
    headers=HEADERS,
    params={"username": "alice_crypto"}
).json()
print("Retweeted:", rt["data"]["retweeted"])

# Check reply with 3 friend tags required
reply = requests.get(
    BASE + "/tweets/" + TWEET_ID + "/check-reply",
    headers=HEADERS,
    params={"username": "alice_crypto", "min_tags": 3}
).json()
print("Replied:", reply["data"]["replied"])
print("Tags met:", reply["data"]["tags_met"])

# Check follow relationship
follow = requests.get(
    BASE + "/users/check-follow",
    headers=HEADERS,
    params={"source": "alice_crypto", "target": "your_project"}
).json()
print("Follows you:", follow["data"]["source_follows_target"])
Enter fullscreen mode Exit fullscreen mode

Bulk Verification: Check All Participants

Here's a complete script to verify an entire airdrop campaign:

import requests
import time
import os
import json

API_KEY = os.environ["XCROP_API_KEY"]
HEADERS = {"Authorization": "Bearer " + API_KEY}
BASE = "https://xcrop.io/api/v2"

TWEET_ID = "1893045621038174208"
PROJECT_USERNAME = "your_project"
MIN_TAGS = 3

# List of participants (from your entry collection system)
participants = ["alice_crypto", "bob_defi", "charlie_nft"]  # ... thousands more

def verify_participant(username):
    """Check all conditions for a single participant."""
    result = {"username": username, "passed": False}

    # A 503 means the upstream read could not be completed, NOT that the user did nothing. Retry it
    # rather than reading a missing "data" key, or one bad minute disqualifies real entrants.
    def get(path, params, tries=3):
        for attempt in range(tries):
            resp = requests.get(BASE + path, headers=HEADERS, params=params)
            if resp.status_code == 503:
                time.sleep(int(resp.headers.get("Retry-After", 5)))
                continue
            resp.raise_for_status()
            return resp.json()["data"]
        raise RuntimeError("upstream busy for " + path)

    # 1. Check retweet
    result["retweeted"] = get(
        "/tweets/" + TWEET_ID + "/check-retweet", {"username": username}
    )["retweeted"]

    # 2. Check reply with friend tags
    reply = get(
        "/tweets/" + TWEET_ID + "/check-reply",
        {"username": username, "min_tags": MIN_TAGS}
    )
    result["replied"] = reply["replied"]
    result["tags_met"] = reply.get("tags_met", False)

    # 3. Check follow
    result["follows"] = get(
        "/users/check-follow", {"source": username, "target": PROJECT_USERNAME}
    )["source_follows_target"]

    # All conditions met?
    result["passed"] = (
        result["retweeted"]
        and result["replied"]
        and result["tags_met"]
        and result["follows"]
    )

    return result

# Verify all participants
verified = []
for i, user in enumerate(participants):
    try:
        result = verify_participant(user)
        verified.append(result)
        status = "PASS" if result["passed"] else "FAIL"
        print("[" + str(i + 1) + "/" + str(len(participants)) + "] @" + user + ": " + status)
    except Exception as e:
        print("[" + str(i + 1) + "] @" + user + ": ERROR - " + str(e))
    time.sleep(0.1)  # Be gentle with rate limits

# Results
winners = [r for r in verified if r["passed"]]
print("\nTotal checked:", len(verified))
print("Qualified:", len(winners))
print("Disqualified:", len(verified) - len(winners))

# Save results
with open("airdrop_results.json", "w") as f:
    json.dump({"winners": winners, "all": verified}, f, indent=2)
Enter fullscreen mode Exit fullscreen mode

Tag Verification: Prevent Fake Entries

A common giveaway rule is "Reply and tag 3 friends." The check-reply and check-quote endpoints support the min_tags parameter to verify this automatically:

# Require at least 3 friend tags in the reply
response = requests.get(
    BASE + "/tweets/" + TWEET_ID + "/check-reply",
    headers=HEADERS,
    params={"username": "alice_crypto", "min_tags": 3}
).json()

data = response["data"]
print("Replied:", data["replied"])
print("Tags required:", data["tags_required"])  # 3
print("Tags found:", data["tags_found"])         # 4
print("Tags met:", data["tags_met"])             # True
Enter fullscreen mode Exit fullscreen mode

The tag count excludes the original tweet author. So if your tweet is from @project and Alice replies "@project @bob @carol @dave", the tag count is 3 (bob, carol, dave), not 4

Whitelist Verification at Submission Time

Checking everyone after the deadline suits a giveaway. NFT whitelists usually work the other way: a participant connects a wallet, enters an X handle and expects a pass or fail on the spot. The same endpoints cover that flow, called from your backend when the form is submitted:

// Run this in your form handler on the server. Calling XCROP from the browser would expose your API key.
async function checkWhitelistTasks(handle) {
  const headers = { Authorization: "Bearer " + process.env.XCROP_API_KEY };
  const base = "https://xcrop.io/api/v2";

  // 503 = the upstream read did not complete. It is not a "no", so it must not read as one.
  const get = async (url) => {
    const r = await fetch(url, { headers });
    const body = await r.json();
    // 503 = read did not complete, retry. 422 = the account itself cannot be read (protected, suspended,
    // withheld), so retrying never helps. Neither is billed, and neither means "the user did nothing".
    if (!r.ok) throw new Error(body.code || ("HTTP " + r.status));
    return body.data;
  };

  const [follow, retweet, reply] = await Promise.all([
    get(base + "/users/check-follow?source=" + handle + "&target=your_project"),
    get(base + "/tweets/" + TWEET_ID + "/check-retweet?username=" + handle),
    get(base + "/tweets/" + TWEET_ID + "/check-reply?username=" + handle + "&min_tags=2"),
  ]);

  // Report each task separately so the user knows what to fix.
  return {
    follows: follow.source_follows_target,
    retweeted: retweet.retweeted,
    replied: reply.verified, // replied AND met min_tags
  };
}
Enter fullscreen mode Exit fullscreen mode

A few things matter once a real person is waiting on the answer:

  • Use a timeout and retry once. Most checks return in under 3 seconds, but the odd one is slower. One quiet retry is better than showing a failure
  • Say which task is missing. "You still need to retweet" gets a resubmission. A bare "not eligible" gets a support ticket
  • Re-check before the snapshot. Some people unfollow right after they are approved. Run the bulk script above once more before you lock the list
  • Plan for launch day. The Pro plan allows 600 requests per minute, which is about 200 three-task submissions a minute

JavaScript / Node.js Example

const API_KEY = process.env.XCROP_API_KEY;
const BASE = "https://xcrop.io/api/v2";
const TWEET_ID = "1893045621038174208";

async function checkInteractions(username) {
  const headers = { Authorization: "Bearer " + API_KEY };

  // 503 = the upstream read did not complete. It is not a "no", so it must not read as one.
  const get = async (url) => {
    const r = await fetch(url, { headers });
    const body = await r.json();
    // 503 = read did not complete, retry. 422 = the account itself cannot be read (protected, suspended,
    // withheld), so retrying never helps. Neither is billed, and neither means "the user did nothing".
    if (!r.ok) throw new Error(body.code || ("HTTP " + r.status));
    return body.data;
  };

  const [retweet, reply, relationship] = await Promise.all([
    get(BASE + "/tweets/" + TWEET_ID + "/check-retweet?username=" + username),
    get(BASE + "/tweets/" + TWEET_ID + "/check-reply?username=" + username + "&min_tags=3"),
    get(BASE + "/users/check-follow?source=" + username + "&target=your_project"),
  ]);

  return {
    username,
    retweeted: retweet.retweeted,
    replied: reply.replied,
    tags_met: reply.tags_met,
    follows: relationship.source_follows_target,
    qualified: retweet.retweeted && reply.replied && reply.tags_met && relationship.source_follows_target,
  };
}

// Verify participants in parallel (batches of 10)
async function verifyAll(participants) {
  const results = [];
  for (let i = 0; i < participants.length; i += 10) {
    const batch = participants.slice(i, i + 10);
    const batchResults = await Promise.all(batch.map(checkInteractions));
    results.push(...batchResults);
    console.log("Checked " + results.length + "/" + participants.length);
  }
  return results;
}
Enter fullscreen mode Exit fullscreen mode

Cost Estimation

Each interaction check costs 50 credits (the median views check is the exception: 200 to 400 credits by posts read). Here's what a typical campaign costs:

Campaign size Checks per user Total requests Credits Cost (Pro)
1,000 users 3 (RT + Reply + Follow) 3,000 150K $0.75
5,000 users 3 15,000 750K $3.75
5,000 users 2 (RT + Reply) 10,000 500K $2.50
10,000 users 3 30,000 1.5M $7.50

That works out to about $0.25 per 1,000 checks on Pro (50,000 credits), or about $0.35 on Basic

With the Pro plan ($9.90/month or $95.04/yr if you pay yearly, includes 2M credits), you can verify ~13,000 users with all 3 checks included in your monthly allowance

Pay as You Go credit packs start at $2.90 for 400K credits (~2,600 full verifications)

Best Practices

  1. Batch with delays: Add 100ms between requests to stay within rate limits
  2. Run checks in parallel: Use Promise.all (JS) or asyncio (Python) for 3 checks per user simultaneously
  3. Cache results: Store verification results to avoid re-checking the same user
  4. Set a deadline: Run verification after the campaign ends, not during. This ensures all entries are captured
  5. Use min_tags wisely: Set it to match your campaign rules exactly. Don't over-require
  6. Handle edge cases: Some users change usernames or go private after entering. Catch errors gracefully
  7. Export results: Save to JSON/CSV for transparency and dispute resolution

FAQ

How do I check if a user retweeted a tweet with an API?

Call GET /v2/tweets/:tweetId/check-retweet with the username. It returns retweeted as true or false and costs 50 credits. Replies (check-reply), quotes (check-quote) and follows (check-follow) work the same way

Can I use this to verify an NFT whitelist?

Yes. Call the checks from your backend when someone submits their X handle, tell them which task is still missing, and run the checks again before the final snapshot, since some people unfollow after they are approved

How much does giveaway verification cost?

Each check costs 50 credits, about $0.25 per 1,000 checks on the Pro plan. Verifying 1,000 entrants on retweet, reply and follow is 150,000 credits, roughly $0.75

Can the API check likes?

No. X made likes private in June 2024, so no API can verify them reliably. Use retweet, reply, quote and follow checks instead


Originally published on the XCROP blog.

Top comments (0)