💎
2.5 Intelligence Docs
  • Quick Start
  • 2.5 - Community Bots
    • Whitelist Manager Bot
    • NFT News Bot
    • 2.5 NFT Verification Bot
  • 2.5 - Marketplace Tracking Bots
    • NFT Sales & Listings Bot
    • Twitter Sales Bot
      • Custom API Key
    • Magic Eden Bot
    • ENS Sales Bot
    • Paras Sales Bot
    • Supported Marketplaces and Chains
  • 2.5 - NFT Activity Bots
    • NFT Wallet Tracker Bot
    • NFT Mint Bot
    • NFT Stats & Info Bot
  • 2.5 - Premium
    • ⭐Introduction
    • 🌟Custom Bots
    • ⭐Unlimited Tracking
    • ⭐Intelligence Reports
    • ⭐Dashboard
  • 2.5 - Intelligence Data
    • Introduction
    • Intelligence Labels
    • Scoring API
  • Previous Products
    • OpenSea Sales & Listings Bot
    • OpenSea Listing Bot
    • NFT Whitelist Wallet Bot
    • Web Publisher SDK
    • 2.5 Role Bot
Powered by GitBook
On this page
  • Get Scores
  • Fetch scores and details for an ETH L1 address
  • Responses
  1. 2.5 - Intelligence Data

Scoring API

Lookup scores for individual addresses

PreviousIntelligence LabelsNextOpenSea Sales & Listings Bot

Last updated 1 year ago

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

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 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, .

// 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>'
}
join our Discord
Job Enqueued