kbarbel640-del FairScale — Reputation Intelligence for Solana
Docs: https://docs.fairscale.xyz
TWO ACCESS METHODS
Method 1: API Key (Recommended)
Use if you have a FairScale API key.
GET https://api.fairscale.xyz/score?wallet=WALLET_ADDRESS
Header: fairkey: YOUR_API_KEY
Example:
curl "https://api.fairscale.xyz/score?wallet=GFTVQdZumAnBRbmaRgN9n3Z5qH5nXvjMZXJ3EyqP32Tn" \
-H "fairkey: YOUR_API_KEY"
Get your key: https://sales.fairscale.xyz
Method 2: x402 Micropayments (For Agents with Wallets)
No API key needed. Pay $0.05 USDC per call.
GET https://x402.fairscale.xyz/score?wallet=WALLET_ADDRESS
Flow:
- Call endpoint → Get 402 response with payment details
- Send 0.05 USDC to treasury wallet shown
- Retry with header:
x-payment-signature: YOUR_TX_SIGNATURE - Get wallet data
Pricing:
| Request | Price |
|---|---|
| Single wallet | $0.05 USDC |
| Batch (10 wallets) | $0.40 USDC |
WHICH METHOD TO USE
| Situation | Use |
|---|---|
| Have API key configured | Method 1 (API Key) |
| Agent has Solana wallet with USDC | Method 2 (x402) |
| No API key, no wallet | Cannot access — need one or the other |
Check for API key first. If $FAIRSCALE_API_KEY is set, use Method 1. Otherwise, try Method 2.
RESPONSE FIELDS
| Field | Use |
|---|---|
fairscore |
The score (0-100) — USE THIS |
tier |
bronze / silver / gold / platinum |
badges |
Array — list each badge.label |
features |
Object — raw metrics for custom logic |
QUICK RESPONSE FORMAT
For simple "check this wallet" requests:
📊 FairScore: [fairscore]/100 | Tier: [tier]
[✅ TRUSTED | ⚡ MODERATE | ⚠️ CAUTION | 🚨 HIGH RISK]
🏅 Badges: [badge labels]
Risk thresholds:
- ≥60 → ✅ TRUSTED
- 40-59 → ⚡ MODERATE
- 20-39 → ⚠️ CAUTION
- <20 → 🚨 HIGH RISK
NATURAL LANGUAGE → FEATURES
When users ask in plain English, translate to the right features:
| User asks | Check these | Logic |
|---|---|---|
| "trustworthy?" | fairscore |
≥60 = yes |
| "whale?" / "deep pockets?" | lst_percentile_score, stable_percentile_score, native_sol_percentile |
All >70 = whale |
| "bot?" / "sybil?" | burst_ratio, platform_diversity |
burst >50 OR diversity <20 = bot |
| "diamond hands?" | conviction_ratio, no_instant_dumps |
conviction >60 = yes |
| "active user?" | active_days, tx_count, platform_diversity |
All >40 = active |
| "OG?" / "veteran?" | wallet_age_score |
>70 = OG |
| "airdrop eligible?" | wallet_age_score >50, platform_diversity >30, burst_ratio <30 |
All must pass |
| "creditworthy?" | conviction_ratio, no_instant_dumps, wallet_age_score |
All >50 = yes |
RESPONSE EXAMPLES
"Is this a whale?"
🐋 Whale Check: GFTVQd...P32Tn
💰 LST Holdings: 97.7% — Top 3%
💵 Stablecoins: 27.5% — Low
◎ Native SOL: 45.2% — Moderate
Verdict: 🟡 PARTIAL WHALE — Heavy DeFi, not cash-rich.
"Is this a bot?"
🤖 Bot Check: GFTVQd...P32Tn
⚡ Burst Ratio: 16.8% — Organic ✅
🌐 Platforms: 96.6% — Diverse ✅
Verdict: ✅ HUMAN — Not a bot.
"Airdrop eligible?"
🎁 Airdrop Check: GFTVQd...P32Tn
📅 Age: 79.2% ✅
🌐 Diversity: 96.6% ✅
🤖 Burst: 16.8% ✅
Verdict: ✅ ELIGIBLE
CUSTOM CRITERIA
When users define their own rules:
"Only wallets with conviction > 70"
🔧 Custom Check: GFTVQd...P32Tn
• Conviction > 70%: ❌ 69.7%
Verdict: ❌ FAILS
ALL FEATURES
| Feature | Description |
|---|---|
fairscore |
Overall score (0-100) |
tier |
bronze/silver/gold/platinum |
wallet_age_score |
Account age percentile |
tx_count |
Transaction count percentile |
active_days |
Active days percentile |
platform_diversity |
DeFi protocols used |
conviction_ratio |
Holding behavior |
burst_ratio |
Bot-like patterns (high = bad) |
no_instant_dumps |
Doesn't quick-sell |
lst_percentile_score |
LST holdings |
stable_percentile_score |
Stablecoin holdings |
native_sol_percentile |
SOL balance |
net_sol_flow_30d |
Accumulating or draining |
CRITICAL RULES
- ALWAYS call the API — Never guess, never reuse old data
- Check for API key first — Use Method 1 if
$FAIRSCALE_API_KEYis set - Fall back to x402 — If no API key, use Method 2 (if agent has wallet)
- Use exact endpoint —
/score?wallet=ADDRESS - Translate user intent — Map plain English to features
- Give verdicts — Users want yes/no answers, not data dumps
- If API fails — Say "❌ Couldn't fetch data. Try again."
Never invent data. Never guess. Always call the API.
LINKS
- Docs: https://docs.fairscale.xyz
- API Key: https://sales.fairscale.xyz
- Twitter: @FairScaleXYZ