Score Endpoint

GET /score

The flagship human-scoring endpoint. Returns everything you'd see on the FairScale dashboard in one call: a final fairscore (0–100), tier, badges, recommended actions, humanity signal, and the full on-chain feature fingerprint.

Most integrators only need this endpoint. The /fairScore, /walletScore, and /socialScore endpoints are single-number shortcuts for lightweight use cases.

Endpoint

GET https://api.fairscale.xyz/score?wallet=WALLET_ADDRESS

Parameter	Type	Required	Description
`wallet`	string	Yes	Solana wallet address
`twitter`	string	No	X/Twitter handle to bind to the wallet and enrich social score

Header	Required	Description
`fairkey`	Yes	API key (or use x402 payment)

Cache: 15 minutes. Force recomputation with /newScore (same parameters).

Example Response

Verified against api.fairscale.xyz/score on 2026-04-17:

{
  "wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "fairscore_base": 24.3,
  "social_score": 61.7,
  "peer_score": 0.0,
  "fairscore": 27.5,
  "verified_human": false,
  "tier": "silver",
  "badges": [
    { "id": "lst_staker",       "label": "LST Staker",       "description": "Holds Liquid Staking Tokens",   "tier": "gold" },
    { "id": "sol_maxi",         "label": "SOL Maxi",         "description": "Strong SOL holder",              "tier": "gold" },
    { "id": "no_dumper",        "label": "No Instant Dumps", "description": "Never panic sells",              "tier": "silver" },
    { "id": "social_connected", "label": "Social Connected", "description": "Verified Twitter account",       "tier": "bronze" },
    { "id": "active_tweeter",   "label": "Active Tweeter",   "description": "20+ tweets in 30 days",          "tier": "bronze" },
    { "id": "content_creator",  "label": "Content Creator",  "description": "60%+ original tweets",           "tier": "gold" },
    { "id": "positive_vibes",   "label": "Positive Vibes",   "description": "High sentiment & positivity",    "tier": "gold" }
  ],
  "actions": [
    { "id": "increase_lst",         "label": "Increase LST Holdings", "description": "Top scorers hold 50%+ of portfolio in LST", "priority": "medium", "cta": "Stake More →" },
    { "id": "hold_longer",          "label": "Hold Positions Longer", "description": "Diamond hands hold for 30+ days",           "priority": "medium", "cta": "Learn More →" },
    { "id": "diversify_platforms",  "label": "Try More Platforms",    "description": "Explore Jupiter, Raydium, Orca, and more",  "priority": "low",    "cta": "Discover DEXes →" }
  ],
  "timestamp": "2026-04-17T11:59:04.121417Z",
  "features": {
    "lst_percentile_score":    47.5,
    "major_percentile_score":  42.5,
    "native_sol_percentile":   98.37,
    "stable_percentile_score": 98.58,
    "tx_count":                0,
    "active_days":             0,
    "median_gap_hours":        24,
    "tempo_cv":                0,
    "burst_ratio":             0,
    "net_sol_flow_30d":        0,
    "median_hold_days":        0,
    "no_instant_dumps":        1,
    "conviction_ratio":        0,
    "platform_diversity":      0,
    "wallet_age_score":        0
  }
}

Top-Level Fields

Field	Type	Description
`wallet`	string	Echoes the requested wallet
`fairscore`	number	Final blended score, `0–100`. `0.50 · base + 0.20 · social + 0.30 · peer`
`fairscore_base`	number	Raw on-chain score from the neural network (features only)
`social_score`	number	Social reputation (X activity, tone, CTA/shill ratio, follower quality). `0` if no X handle linked.
`peer_score`	number	Peer-review score from the FairScale vouch graph. `0` if no vouches received.
`verified_human`	boolean	`true` if the wallet has a VeryAI ZK palm-scan humanity attestation
`tier`	enum	`bronze` · `silver` · `gold` · `platinum` · `diamond`
`badges`	Badge[]	Earned behavioural badges (see below)
`actions`	Action[]	Recommended next steps to improve the score
`cached`	boolean	Present on cache-hit responses only. `true` if served from the 15-min cache.
`timestamp`	string	ISO-8601 UTC scoring timestamp
`features`	object	On-chain feature fingerprint — 15 fields, see Features

Badge

{ id: string; label: string; description: string; tier: "bronze"|"silver"|"gold"|"platinum" }

Action

{ id: string; label: string; description: string; priority: "high"|"medium"|"low"; cta: string }

Features

The features object returns 15 on-chain signals, all engineered to be comparable across wallets. Percentile-ranked fields are 0–100 (higher is stronger). Raw counts and durations use their natural units.

Portfolio Composition — "What does the wallet actually hold?"

Field	Type	Unit	Meaning
`native_sol_percentile`	number	percentile	Native SOL holdings vs. the population
`major_percentile_score`	number	percentile	Blue-chip token holdings (JUP, JTO, BONK, HNT, …)
`stable_percentile_score`	number	percentile	Stablecoin holdings (USDC, USDT)
`lst_percentile_score`	number	percentile	Liquid staking token holdings (mSOL, jitoSOL, …)

Capital Flow — "Accumulating or exiting?"

Field	Type	Unit	Meaning
`net_sol_flow_30d`	number	SOL	Inflow – outflow over the last 30 d

Holding Conviction — "Hold with conviction or flip fast?"

Field	Type	Unit	Meaning
`median_hold_days`	number	days	Median position hold time
`conviction_ratio`	number	0–1 ratio	Share of positions held > 7 days
`no_instant_dumps`	number	0 / 1	`1` if the wallet never flipped a position in under 1 hour

Activity Tempo — "How often, how consistently?"

Field	Type	Unit	Meaning
`tx_count`	number	count	Transactions in the 30 d window
`active_days`	number	count	Distinct calendar days with activity
`median_gap_hours`	number	hours	Median time between consecutive transactions

Trading Behaviour — "Human-like or bot-like?"

Field	Type	Unit	Meaning
`tempo_cv`	number	coefficient	Variance in inter-transaction gaps — humans irregular, bots metronomic
`burst_ratio`	number	0–1 ratio	Share of trades within < 1 h of the previous — bot-likelihood indicator

Breadth — "One-trick pony or explorer?"

Field	Type	Unit	Meaning
`platform_diversity`	number	count	Distinct protocols / platforms used
`wallet_age_score`	number	percentile	Wallet age rank — older wallets score higher

Trust Pillars (derived)

The dashboard groups these 15 features and the earned badges into five human-readable pillars. The API does not return pillars directly — they're derived from the features and badges you already get. The SDK ships a helper (client.insights.pillars) that reproduces the dashboard logic.

Pillar	Question it answers	Driven by
Economy	Can they put capital where their mouth is?	`major_`, `stable_`, `native_sol_`, `lst_percentile_score`
Risk	Will they stick around or dump and run?	`median_hold_days`, `conviction_ratio`, `no_instant_dumps`
Activity	Are they a real participant or a ghost?	`tx_count`, `active_days`, `median_gap_hours`
Diversification	Do they explore or stick to one thing?	`platform_diversity`, `wallet_age_score`
Social	Does anyone actually know them?	`social_score`, `peer_score`, linked X handle

Each pillar resolves to High / Medium / Low. See the SDK guide for the derivation helper.

Humanity Index (derived)

A 0–100 score expressing confidence that the wallet is operated by a human, not a bot or Sybil. Derived client-side:

If verified_human === true → score is 100, tier is verified_human. VeryAI has ZK-attested the wallet owner via palm scan.
Otherwise → a weighted combination of tempo_cv (timing variance — humans irregular, bots metronomic), burst_ratio (clustered trades), conviction_ratio, no_instant_dumps, and social signals produces a likely_human / unverified label.

The SDK helper client.insights.humanityIndex(score) returns { score, tier }.

Tiers

Tier	FairScore	Meaning
`diamond`	85–100	Elite long-term user
`platinum`	70–84	Highly trusted, active
`gold`	55–69	Solid track record
`silver`	40–54	Building reputation
`bronze`	0–39	Limited history / risk signals

Example Request

curl -X GET "https://api.fairscale.xyz/score?wallet=7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" \
  -H "fairkey: YOUR_API_KEY"

With social linking:

curl -X GET "https://api.fairscale.xyz/score?wallet=WALLET&twitter=handle" \
  -H "fairkey: YOUR_API_KEY"

Errors

Status	Meaning
400	Missing or invalid wallet
401	Invalid / missing `fairkey`
402	No fairkey and no x402 payment
429	Rate limit exceeded
502	Scoring engine unreachable

Score Endpoint

Score Endpoint

Endpoint

Example Response

Top-Level Fields

Badge

Action

Features

Portfolio Composition — "What does the wallet actually hold?"

Capital Flow — "Accumulating or exiting?"

Holding Conviction — "Hold with conviction or flip fast?"

Activity Tempo — "How often, how consistently?"

Trading Behaviour — "Human-like or bot-like?"

Breadth — "One-trick pony or explorer?"

Trust Pillars (derived)

Humanity Index (derived)

Tiers

Example Request

Errors

See Also