Scoring API
Lookup scores for individual addresses
get
https://rutherford.5.dev/api/scores/
${address}
Fetch scores and details for an ETH L1 address
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.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.
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
}
}
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 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
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.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.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
}
An object with the following format:
{
"longestHoldDuration": number || undefined; // in seconds
"averageHoldDuration": number || undefined; // in seconds
"firstTransferIn": string; // iso 8601 datetime
}
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;
}
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>'
}