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:

1. Call endpoint → Get 402 response with payment details
2. Send 0.05 USDC to treasury wallet shown
3. Retry with header: x-payment-signature: YOUR_TX_SIGNATURE
4. 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

1. ALWAYS call the API — Never guess, never reuse old data
2. Check for API key first — Use Method 1 if $FAIRSCALE_API_KEY is set
3. Fall back to x402 — If no API key, use Method 2 (if agent has wallet)
4. Use exact endpoint — /score?wallet=ADDRESS
5. Translate user intent — Map plain English to features
6. Give verdicts — Users want yes/no answers, not data dumps
7. 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