The Problem: Manual Verification Doesn't Scale
Running an airdrop, giveaway or NFT whitelist on X? You've probably seen the drill:
- Post a tweet: "Retweet + Reply (tag 3 friends) + Follow to enter"
- Thousands of entries flood in
- 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"])
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)
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
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
};
}
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;
}
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
- Batch with delays: Add 100ms between requests to stay within rate limits
-
Run checks in parallel: Use
Promise.all(JS) orasyncio(Python) for 3 checks per user simultaneously - Cache results: Store verification results to avoid re-checking the same user
- Set a deadline: Run verification after the campaign ends, not during. This ensures all entries are captured
- Use min_tags wisely: Set it to match your campaign rules exactly. Don't over-require
- Handle edge cases: Some users change usernames or go private after entering. Catch errors gracefully
- 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)