The WorldScore API allows you to verify users and access their reputation scores within the World (formerly Worldcoin) ecosystem. With 65,000+ verified unique humans, WorldScore provides the most comprehensive reputation layer for World mini apps.
Base URL: https://developer.worldscore.world/api/v1
All API endpoints (except /stats) require an API key. Include your key in the X-API-Key header:
curl -H "X-API-Key: ws_live_your_api_key_here" \
https://developer.worldscore.world/api/v1/score?wallet=0x...You can also pass the key as a query parameter: ?api_key=ws_live_...(less secure, not recommended for production).
The free tier allows 100 requests per minute per API key. Rate limit information is included in every response via headers:
| Header | Description |
|---|---|
| X-RateLimit-Limit | Maximum requests per window (100) |
| X-RateLimit-Remaining | Requests remaining in current window |
| X-RateLimit-Reset | ISO timestamp when the window resets |
The primary endpoint for retrieving a user's complete WorldScore data including reputation score, verified credentials, and score breakdown.
| Parameter | Type | Required | Description |
|---|---|---|---|
| wallet | string | Required | The user's World wallet address (0x...) |
{
"success": true,
"data": {
"walletAddress": "0x1234...abcd",
"username": "alice_world",
"totalScore": 750,
"isVerified": true,
"verificationLevel": "high", // "low" | "medium" | "high"
"credentials": {
"orbVerified": true, // 150 points
"emailVerified": true, // 40 points
"phoneVerified": true, // 60 points
"externalWallet": {
"connected": true,
"points": 100 // 10-100 based on balance
},
"babTokenHolder": false, // 100 points
"twitterVerified": true, // 50 points
"walletAnalysis": {
"completed": true,
"points": 60 // 10-90 based on WLD balance
},
"referrals": {
"count": 3,
"points": 50 // up to 100
}
},
"scoreBreakdown": {
"orbVerification": 150,
"externalWallet": 100,
"emailVerification": 40,
"phoneVerification": 60,
"twitterVerification": 50,
"babToken": 0,
"walletAnalysis": 60,
"referrals": 50
},
"memberSince": "2026-01-15T10:30:00.000Z",
"lastActive": "2026-07-29T14:22:00.000Z"
}
}A lightweight endpoint for simple boolean verification checks. Use this when you only need to know if a user is registered and their score level.
| Parameter | Type | Required | Description |
|---|---|---|---|
| wallet | string | Required | The user's World wallet address (0x...) |
{
"verified": true,
"score": 750,
"level": "high",
"username": "alice_world"
}Aggregate statistics about the WorldScore network. No API key required.
{
"success": true,
"data": {
"totalUsers": 65471,
"averageScore": 520,
"verifications": {
"emails": 48230,
"phones": 31540,
"babTokens": 8920
},
"scoreRange": { "min": 300, "max": 999 },
"lastUpdated": "2026-07-30T07:00:00.000Z"
}
}WorldScore ranges from 300 to 999. Here's how each verification credential contributes to the total score:
| Credential | Max Points | Details |
|---|---|---|
| ORB Verification | 150 | Must be verified via World Orb iris scan |
| External Wallet | 100 | $0 balance = 10pts, $1-$50 = 50pts, $50+ = 100pts |
| BAB Token | 100 | Must hold Binance BAB token in connected wallet |
| Wallet Analysis | 90 | 0 WLD = 10pts, 1-20 WLD = 30pts, 21-50 WLD = 60pts, 50+ WLD = 90pts |
| Phone Verification | 60 | Verify mobile number with OTP |
| X/Twitter | 50 | Connect and verify X/Twitter account |
| Email Verification | 40 | Verify email address |
| Referrals | 100 | 1st = 10pts, 2nd = 15pts, 3rd = 25pts, 4th = 50pts |
Base score: All users start with 300 points (ORB verified through World ID). Maximum achievable score is 999 with all verifications and 4+ referrals.
| Level | Score Range | Recommended Use |
|---|---|---|
| Low | 300 – 499 | Basic access, limited features |
| Medium | 500 – 699 | Standard access, moderate trust features |
| High | 700 – 999 | Full access, low/zero-collateral, premium features |
const response = await fetch(
"https://developer.worldscore.world/api/v1/score?wallet=0x1234...abcd",
{
headers: {
"X-API-Key": "ws_live_your_api_key_here",
},
}
);
const data = await response.json();
if (data.success && data.data) {
console.log("Score:", data.data.totalScore);
console.log("Level:", data.data.verificationLevel);
console.log("ORB Verified:", data.data.credentials.orbVerified);
// Gate access based on score
if (data.data.totalScore >= 600) {
console.log("User qualifies for premium features!");
}
}import requests
response = requests.get(
"https://developer.worldscore.world/api/v1/score",
params={"wallet": "0x1234...abcd"},
headers={"X-API-Key": "ws_live_your_api_key_here"}
)
data = response.json()
if data.get("success") and data.get("data"):
score = data["data"]["totalScore"]
level = data["data"]["verificationLevel"]
print(f"WorldScore: {score} ({level})")
# Check specific credentials
creds = data["data"]["credentials"]
if creds["orbVerified"] and creds["emailVerified"]:
print("User has strong identity verification")# Full score lookup
curl -X GET \
"https://developer.worldscore.world/api/v1/score?wallet=0x1234...abcd" \
-H "X-API-Key: ws_live_your_api_key_here"
# Quick verification check
curl -X GET \
"https://developer.worldscore.world/api/v1/verify?wallet=0x1234...abcd" \
-H "X-API-Key: ws_live_your_api_key_here"
# Public stats (no API key needed)
curl -X GET "https://developer.worldscore.world/api/v1/stats"The API uses standard HTTP status codes. All error responses include an error field with a human-readable message.
| Status | Meaning | Example |
|---|---|---|
200 | Success | Request completed. User may or may not exist. |
400 | Bad Request | Missing wallet parameter |
401 | Unauthorized | Missing or invalid API key |
429 | Rate Limited | Exceeded 100 requests/minute |
500 | Server Error | Internal error — try again later |
// Error response format
{
"error": "API key required",
"message": "Include your API key in the X-API-Key header or as api_key query parameter"
}