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
address*
String
Address to retrieve scores for. starting with 0x
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
shrimp
fish
dolphin
shark
whale
Hands
new: This user has not used NFTspaper: Very consistent pattern of mint/purchase and resale of NFTsnormie: Not a consistent holder but not a repeat reseller1: Holds with some resales, or new user with a pattern of holding2: Holds with occasional resales3: Long term pattern of holding4: Very long term and firmly established pattern of holding5: 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>'
}Last updated