Score

Returns the on-chain reputation score for a wallet, computed from its activity across 9 chains (Ethereum, Polygon, Arbitrum, Linea, Gnosis, Blast, Mantle, Berachain, Unichain), ENS identity, wallet age, and participation in reward programs. The score is independent of any specific point system — it reflects the wallet’s real on-chain history. Scores are cached for 30 days and refreshed daily by the scoring engine.

These are the chains the reputation score reads from. They are not where reward campaigns run. Rewards are deployed only on Somnia (Mainnet 5031, Testnet 50312) and Base (Mainnet 8453, Sepolia 84532). See Supported chains.

GET /api/score

Request

GET https://api.rewards.so/score?address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045
Authorization: Bearer rw_your_api_key

Query parameters

Parameter	Type	Required	Description
`address`	`string`	Yes	`0x` address (lowercase)
`force`	`boolean`	No	Set to `true` to bypass the 30-day cache and fetch a fresh score

Response `200`

{
  "id": "uuid",
  "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  "finalScore": 78,
  "breakdown": {
    "age_factor": 0.95,
    "activity_factor": 0.87,
    "wallet_age_days": 1842,
    "total_txs": 312,
    "chains_active": 5,
    "last_tx_days_ago": 2
  },
  "bonuses": {
    "ens": 5,
    "multichain": 3,
    "rewards": 8
  },
  "penalties": {
    "recency": 0,
    "humanity": 0,
    "bot": 0
  },
  "dataSources": {
    "etherscan": true,
    "rewards": true
  },
  "cached": true,
  "cachedAt": "2026-04-21T08:00:00.000Z"
}

Response fields

Field	Type	Description
`finalScore`	`number`	Reputation score from 0 to 100
`breakdown.age_factor`	`number`	Wallet age factor (0–1). Reaches 1.0 at 4+ years
`breakdown.activity_factor`	`number`	On-chain activity factor (0–1). Reaches 1.0 at 2000+ txs
`breakdown.wallet_age_days`	`number \| null`	Age of the wallet in days
`breakdown.total_txs`	`number`	Total transactions across all tracked chains
`breakdown.chains_active`	`number`	Number of chains with at least one transaction
`breakdown.last_tx_days_ago`	`number \| null`	Days since the last transaction
`bonuses.ens`	`number`	+5 if the wallet has a primary ENS or Base name
`bonuses.multichain`	`number`	+3 if active on 3+ chains
`bonuses.rewards`	`number`	0–10 based on percentile rank across reward programs
`penalties.recency`	`number`	-5 if no activity in the last 180 days
`penalties.humanity`	`number`	0–30 penalty for bot-like temporal patterns
`penalties.bot`	`number`	0–30 penalty for correlated blacklist signals
`dataSources.etherscan`	`boolean`	Whether on-chain data was available
`dataSources.rewards`	`boolean`	Whether rewards program data was available
`cached`	`boolean`	`true` if the score was served from cache
`cachedAt`	`string \| null`	ISO timestamp of when the score was cached

Errors

Status	Message	Cause
`400`	`Missing address`	No `address` query parameter
`401`	`Missing API key`	No `Authorization` header
`401`	`Invalid API key`	Key not found
`403`	`This API key does not have read permissions`	Key lacks `read` permission
`502`	`Score service returned no score`	Scoring backend returned a response but no score value
`503`	`Score service unavailable`	Scoring backend unreachable and no cached score

Scoring formula

rawScore = age_factor × activity_factor × 100
         + ens_bonus       (0 or +5)
         + multichain_bonus (0 or +3)
         + rewards_bonus    (0–10)
         - recency_penalty  (0 or -5)

finalScore = clamp(rawScore - bot_penalty - humanity_penalty, 0, 100)

A wallet with no activity gets a score near 0. A long-lived, multi-chain wallet with ENS and active reward program participation scores close to 100.

Code examples

curl "https://api.rewards.so/score?address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045" \
  -H "Authorization: Bearer rw_your_api_key"

type WalletScore = {
  id: string;
  address: string;
  finalScore: number;
  breakdown: {
    age_factor: number;
    activity_factor: number;
    wallet_age_days: number | null;
    total_txs: number;
    chains_active: number;
    last_tx_days_ago: number | null;
  };
  bonuses: { ens: number; multichain: number; rewards: number };
  penalties: { recency: number; humanity: number; bot: number };
  dataSources: { etherscan: boolean; rewards: boolean };
  cached: boolean;
  cachedAt: string | null;
};

async function getWalletScore(address: string, force = false): Promise<WalletScore> {
  const url = new URL("https://api.rewards.so/score");
  url.searchParams.set("address", address);
  if (force) url.searchParams.set("force", "true");

  const res = await fetch(url.toString(), {
    headers: { Authorization: `Bearer ${process.env.REWARDS_API_KEY}` },
  });

  if (!res.ok) {
    const { error } = await res.json();
    throw new Error(`Score API error: ${error}`);
  }

  return res.json();
}

// Check if a wallet is trustworthy before granting access
const score = await getWalletScore("0xd8da6bf26964af9d7eed9e03e53415d37aa96045");

if (score.finalScore < 30) {
  console.log("Low-reputation wallet — consider additional verification");
} else {
  console.log(`Score: ${score.finalScore}/100 — wallet age: ${score.breakdown.wallet_age_days}d`);
}

import os
import requests

def get_wallet_score(address: str, force: bool = False) -> dict:
    res = requests.get(
        "https://api.rewards.so/score",
        params={"address": address, **({"force": "true"} if force else {})},
        headers={"Authorization": f"Bearer {os.environ['REWARDS_API_KEY']}"},
    )
    res.raise_for_status()
    return res.json()

score = get_wallet_score("0xd8da6bf26964af9d7eed9e03e53415d37aa96045")
print(f"Score: {score['finalScore']}/100")
print(f"Chains active: {score['breakdown']['chains_active']}")
print(f"Bot penalty: {score['penalties']['bot']}")

Overview

Endpoints

GET /api/score

Request

Query parameters

Response `200`

Response fields

Errors

Scoring formula

Code examples

​GET /api/score

​Request

​Query parameters

​Response 200

​Response fields

​Errors

​Scoring formula

​Code examples

GET /api/score

Request

Query parameters

Response `200`

Response fields

Errors

Scoring formula

Code examples