Scoring API

Lookup scores for individual addresses

Get Scores

Fetch scores and details for an ETH L1 address

GET https://rutherford.5.dev/api/scores/${address}

Path Parameters

Name	Type	Description
address*	String	Address to retrieve scores for. starting with 0x

200: OK Full data response

202: Accepted Enqueued, check back later for full data

Important The scores route will return 200 with the full data or 202 if the address has a large amount of data and data is not immediately available.

If you receive a 202, try again later. Data is usually available within 60 seconds. It is safe to call the route multiple times with the same address.

Responses

You'll receive your full data immediately if it's been cached recently or is able to be scored within 5s. Otherwise you'll receive the Job Enqueued response.

Full Data Response

See below for an example response and explanation of the response format. For more details or questions about how we score and index data, join our Discord.

// HTTP 200 OK
{
    "address": "0xFFFF....",
    "scores": {
        "whaleness": 1, // Asset score from 1 to 5.
        "hands": "new"
    },
    "labels": [ // See https://docs.5.dev/reference/2.5-intelligence-labels
        {"name" : "diamond"},
        {"name" : "five-diamond"},
        {"name" : "paperhands"},
        {"name" : "whale"},
        {"name" : "blue-chip"},
        {"name" : "smart-money"},
        {"name" : "top-minter"},
        {"name" : "top-trader"},
    ],
    "collectibles": [
        {
            "name": "Azuki",
            "quantity": 1,
            "openseaSlug": "azuki",
            "inTs": "2022-02-01T19:25:14.000Z",
            "floorPrice": 25.99
        },
        {
            "name": "Meebits",
            "quantity": 2,
            "openseaSlug": "meebits",
            "inTs": "2021-05-03T18:57:38.000Z",
            "floorPrice": 4.99
        },
        {
            "name": "TinyBoxes",
            "quantity": 5,
            "openseaSlug": "tinyboxes",
            "inTs": "2021-03-06T02:23:12.000Z",
            "floorPrice": null
        },
        {
            "name": "Chubbies",
            "quantity": 1,
            "openseaSlug": "chubbies",
            "inTs": "2021-03-21T00:54:02.000Z",
            "floorPrice": null
        }
    ],
    "coins": [
        {
            "symbol": "ETH",
            "contractAddress": null,
            "amount": 0.2,
            "nativeValue": 0.2,
            "usdValue": 690.02
        },
        {
            "symbol": "WETH",
            "name": "WETH",
            "contractAddress": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
            "amount": 3.2229455940746856,
            "nativeValue": 3.2229455940746856,
            "usdValue": 11119.4845941171
        },
        {
            "symbol": "USDC",
            "name": "USD Coin",
            "contractAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
            "amount": 1064.917938,
            "nativeValue": 0.30927346755396,
            "usdValue": 1064.917938
        },
    ],
    "portfolioStats": {
        "longestHoldDuration": 33451829.63;
        "averageHoldDuration": 8462957.4075;
        "oldestTransferIn": "2021-03-06T02:23:12.000Z"; 
        "newestTransferIn": "2022-02-01T19:25:14.000Z";
        "totalPortfolioValue": 34.712219061628645,
        "collectiblePortfolioValue": 30.98,
        "coinPortfolioValue": 3.732219061628644,
        "collectibleCount": 4

    },
    "lifetimeStats": {
        "longestHoldDuration": 33451829.63,
        "averageHoldDuration": 5372256.161;
        "firstTransferIn": "2021-01-18T12:09:54.000Z",
    },
    "transferCounts": {
        "mints": 4,
        "purchases": 2,
        "transfersIn": 0,
        "sales": 2,
        "flips": 2,
        "profitableFlips": 2,
        "transfersOut": 0
    }
}

Scores

An object with the following format:

{
  "whaleness": 1 | 2 | 3 | 4 | 5,
  "hands": 'new' | 'normie' | 'paper' | '1' | '2' | '3' | '4' | '5'
}

Whaleness

1. shrimp

2. fish

3. dolphin

4. shark

5. whale

Hands

• new: This user has not used NFTs

• paper: Very consistent pattern of mint/purchase and resale of NFTs

• normie: Not a consistent holder but not a repeat reseller

• 1: Holds with some resales, or new user with a pattern of holding

• 2: Holds with occasional resales

• 3: Long term pattern of holding

• 4: Very long term and firmly established pattern of holding

• 5: Extremely consistent pattern of holding

Collectibles

Currently held NFTs. An array of items with the following format:

{
  "name": string,
  "quantity": number,  // number of this collection that the user holds
  "openseaSlug": string,
  "inTs": string,  // iso 8601 datetime
  "floorPrice": number | null  // floor price of collection
}

Items are sorted by floorPrice * quantity in descending order. Where floorPrice is null, items are sorted by quantity in descending order.

Coins

Current Ether and ERC-20 balances. An array of items with the following format:

{
  "symbol": string,
  "name": string,
  "contractAddress": string,  // null for Ether
  "amount": number,
  "nativeValue": number | null,  // value in Ether
  "usdValue": number | null  // value in USD
}

Ether will always appear first and is always present in the response.

The remaining items are sorted by nativeValue in descending order. Where nativeValue is null, items are sorted by amount in descending order.

Portfolio Stats

An object with the following format:

{
  "longestHoldDuration": number | undefined;  // in seconds
  "averageHoldDuration": number | undefined;  // in seconds
  "oldestTransferIn": string | undefined;  // iso 8601 datetime
  "newestTransferIn": string | undefined;  // iso 8601 datetime
  "totalPortfolioValue": number;  // in Ether
  "collectiblePortfolioValue": number;  // in Ether
  "coinPortfolioValue": number;  // in Ether
  "collectibleCount": number;  // number of UNIQUE collections held
}

Lifetime Stats

An object with the following format:

{
  "longestHoldDuration": number || undefined;  // in seconds
  "averageHoldDuration": number || undefined;  // in seconds
  "firstTransferIn": string;  // iso 8601 datetime
}

Transfer Counts

An object with the following format:

{
  "mints": number;
  "purchases": number;
  "transfersIn": number;
  "sales": number;
  "transfersOut": number;
  "flips": number;  // sales of collectibles not transferred in
  "profitableFlips": number;
}

Job Enqueued Response

If an address requires a particularly large amount of data to process, we respond with a job id and immediately begin processing it in the background.

No action is needed when you receive this response. You do not need to keep track of the job id.

You should periodically retry the request and route will respond with the full score data when available. This is usually in 60 seconds or less.

// HTTP 202 Accepted
{
    jobId: '<uuid>'
}