Wallet Intelligence

Addressable's cutting-edge Wallet Intelligence API seamlessly links on-chain wallet data to off-chain identities, enabling powerful insights across seven blockchain platforms. With unique clustering capabilities, it identifies multiple wallet addresses belonging to single users, unlocking critical use cases like conversion tracking, fraud detection, competitive analysis, and personalization. Built for real-time decision making at scale, our API helps you gain a deeper understanding of user demographics and transaction histories to drive smarter decisions and enhance security.

API Versioning

You are currently viewing documentation for Wallet Intelligence API v1

Base URL Format

All API endpoints are versioned using a URL path prefix. Please ensure you are using the correct version in your requests.

https://data-api.app.addressable.io/v1/

Authentication

In order to successfully request data from the Wallet Intelligence API, you must first acquire two things:

1. API Key

2. Bearer Token

Please reach out to your Addressable partner for your API Key.

You can acquire your Bearer Token programmatically, using your Username, Password and the Token URL.

Here is a Python code snippet demonstrating how to generate your Bearer Token using these three pieces of information.

import requests
generate_token_url = 'https://data-api.app.addressable.io/v1/generate_token'
params = {'username': '<your username goes here>', 'password': '<your password goes here>'}
token_response = requests.get(generate_token_url, params=params)
token = token_response.json()['token']

Once issued, your Bearer Token is valid for 60 minutes (1 hour)

Request Structure

Once you have acquired your API Key and Bearer Token, you are ready to request data from the Wallet Intelligence API.

All the data available through the API can be requested through the /wallets endpoint using the address parameter.

Here is a Python code snippet demonstrating how to submit a request for an address using your API Key and Bearer Token.

headers = {'x-api-key' : '<your api key goes here>', 'Authorization': f'Bearer {token}'}
params = {'address': '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'} # Vitalik.eth address!
wallet_api_url = 'https://data-api.app.addressable.io/v1/wallets?address={address}'
response = requests.get(wallet_api_url, params=params, headers=headers)

print(response.json())

Response Structure

A successful request to the API will return wallet addresses from various supported chains along with a comprehensive package of insights specific to those wallet addresses.

Field	Type	Description
address	string	The blockchain wallet address
chain_id	integer	Unique identifier of the blockchain associated with the wallet address
user_agent_os	array<string>	Operating systems used by this wallet address for transactions
platforms	array<string>	Device or software platforms this wallet address interacted with in the last 30 days
social_platforms	array<string>	Social networks the wallet address user interacted with in the last 30 days
primal_country_iso2	string	Two-letter country code (ISO 3166-1 alpha-2) representing the primary location of wallet activity in the last 30 days
web2_marketing_sources	array<string>	Attributed marketing channels and referrers of wallet’s interactions tracked by Addressable. Please see How Attribution Works
wallet_name	string	Web3 domain name (if any) associated with this wallet address
tags	array<string>	Profile segments assigned to the wallet based on activity patterns
min_ts_ice	integer	Unix timestamp of the wallet’s first blockchain transaction
max_ts_ice	integer	Unix timestamp of the wallet’s last blockchain transaction
min_ts_out	integer	Unix timestamp of the wallet’s first outgoing transaction
max_ts_out	integer	Unix timestamp of the wallet’s last outgoing transaction
min_ts_in	integer	Unix timestamp of the wallet’s first incoming transaction
max_ts_in	integer	Unix timestamp of the wallet’s last incoming transaction
min_ts_tot	integer	Unix timestamp of the first transaction among min_ts_ice, min_ts_in, min_ts_out
max_ts_tot	integer	Unix timestamp of the last transaction among max_ts_ice, max_ts_in, min_ts_out
activity_hours_7_days	map<string, integer>	Hourly aggregation of wallet activity over the last 7 days
activity_hours_30_days	map<string, integer>	Hourly aggregation of wallet activity over the last 30 days
transactions_7_days	integer	Total number of transactions in the last 7 days
transactions_30_days	integer	Total number of transactions in the last 30 days
transactions_3_months	integer	Total number of transactions in the last 3 months
transactions_year	integer	Total number of transactions in the last 12 months
daily_transactions	map<string, integer>	Daily aggregation of wallet transactions per day over the last 30 days (t0 = Today minus 30)
top_holdings_erc20	array<object>	Account balance data of the wallet's top 10 ERC20 holdings by amount_usd
top_holdings_nft	array<object>	Account balance data of the wallet's top 10 NFT holdings by amount
number_of_erc20_tokens	integer	Total count of ERC20 tokens held by the wallet
number_of_erc721_tokens	integer	Total count of ERC721 tokens (NFTs) held by the wallet
number_of_erc1155_tokens	integer	Total count of ERC1155 tokens held by the wallet
total_balance_usd	number	Total USD holdings of wallet
top_traded_dapps_yesterdays	array<object>	List of top 10 decentralized applications the wallet transacted with yesterday
primary_country	string	Full name of the country where most wallet activity originated in the last 30 days
all_countries	array<string>	List of all countries where wallet activity was detected in the last 30 days
languages	array<string>	List of languages associated with the wallet user's activity in the last 30 days
platforms_30_days	map<string, integer>	Number of days with at least one activity per platform in the last 30 days
social_platforms_30_days	array<string>	Social platforms with at least one interaction in the last 30 days
first_seen_channel	string	First marketing or interaction channel observed for this wallet in the last 30 days
first_seen_domain	string	First web domain the wallet was observed interacting with in the last 30 days
last_seen_channel	string	Most recent channel the wallet was observed interacting with in the last 30 days
last_seen_domain	string	Most recent web domain the wallet was observed interacting with in the last 30 days
platform_percentages_30_days	map<string, number>	Distribution of wallet activity across platforms by percentage in the last 30 days
wallet_age_in_days	integer	Age of the wallet in days since its first transaction
top_traded_dapps_30_days	array<object>	List of top 10 decentralized applications the wallet transacted with in the last 30 days
wallet_providers	array<string>	List of wallet providers associated with this address
days_since_last_activity	integer	Number of days elapsed since the wallet's most recent activity

Object Structures

top_holdings_erc20 Object

Field	Type	Description
name	string	Token name
amount	number	Token quantity
symbol	string	Token symbol
amount_usd	number	Token value in USD
erc_standard	string	ERC token standard

top_holdings_nft Object

Field	Type	Description
name	string	NFT collection name
amount	integer	Number of NFTs held
symbol	string	Collection symbol
token_id	array<string>	List of specific token IDs held
erc_standard	string	ERC token standard (721 or 1155)

top_traded_dapps Object

Field	Type	Description
address	string	Contract address of the decentralized application
name	string	Name of the decentralized application
n_transactions	integer	Number of transactions with this decentralized application

Sample Response

{
    "wallets":
    [
        {
            "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
            "chain_id": 1,
            "user_agent_os":
            [
                "Android",
                "Chrome OS",
                "Linux",
                "Mac OS X",
                "Windows",
                "iOS"
            ],
            "platforms":
            [
                "Desktop",
                "Mobile"
            ],
            "social_platforms":
            [
                "Twitter",
                "Youtube"
            ],
            "primal_country_iso2": "GB",
            "web2_marketing_sources":
            [
                "Organic Search - www.google.com",
                "Organic Social - X Embedded Link",
                "Referrals - dappradar.com",
                "Referrals - warpcast.com",
                "Referrals - etherscan.io",
                "Organic Social - X Profile Click",
                "Organic Social - www.youtube.com",
                "Organic Search - keep.google.com",
                "Referrals - www.abs.xyz",
                "Organic Search - www.google.com.hk",
                "Referrals - my.soniclabs.com"
            ],
            "min_ts_ice": 1443722885,
            "max_ts_ice": 1743196403,
            "min_ts_out": 1443722885,
            "max_ts_out": 1743008555,
            "min_ts_in": 1443428683,
            "max_ts_in": 1743357071,
            "min_ts_tot": 1443428683,
            "max_ts_tot": 1743357071,
            "activity_hours_7_days":
            {
                "00": 0,
                "01": 0,
                "02": 0,
                "03": 0,
                "04": 0,
                "05": 0,
                "06": 0,
                "07": 0,
                "08": 0,
                "09": 0,
                "10": 0,
                "11": 0,
                "12": 0,
                "13": 0,
                "14": 0,
                "15": 0,
                "16": 0,
                "17": 1,
                "18": 0,
                "19": 0,
                "20": 0,
                "21": 1,
                "22": 0,
                "23": 0
            },
            "activity_hours_30_days":
            {
                "00": 0,
                "01": 0,
                "02": 2,
                "03": 1,
                "04": 9,
                "05": 1,
                "06": 2,
                "07": 0,
                "08": 0,
                "09": 0,
                "10": 0,
                "11": 0,
                "12": 0,
                "13": 1,
                "14": 0,
                "15": 0,
                "16": 0,
                "17": 1,
                "18": 0,
                "19": 1,
                "20": 0,
                "21": 1,
                "22": 0,
                "23": 0
            },
            "transactions_7_days": 2,
            "transactions_30_days": 19,
            "transactions_3_months": 90,
            "transactions_year": 313,
            "daily_transactions":
            {
                "t0": 0,
                "t1": 0,
                "t2": 0,
                "t3": 1,
                "t4": 0,
                "t5": 1,
                "t6": 0,
                "t7": 0,
                "t8": 0,
                "t9": 0,
                "t10": 0,
                "t11": 0,
                "t12": 0,
                "t13": 12,
                "t14": 0,
                "t15": 0,
                "t16": 0,
                "t17": 0,
                "t18": 1,
                "t19": 0,
                "t20": 0,
                "t21": 0,
                "t22": 0,
                "t23": 0,
                "t24": 0,
                "t25": 0,
                "t26": 0,
                "t27": 0,
                "t28": 0,
                "t29": 1
            },
            "top_holdings_erc20":
            [
                {
                    "name": "Baby Neiro",
                    "amount": 2147483647,
                    "symbol": "BabyNeiro",
                    "amount_usd": 15328926.06622459,
                    "erc_standard": "ERC20"
                },
                {
                    "name": "WhiteRock",
                    "amount": 2147483647,
                    "symbol": "WHITE",
                    "amount_usd": 7255534.168699433,
                    "erc_standard": "ERC20"
                },
                {
                    "name": "MOO DENG",
                    "amount": 2147483647,
                    "symbol": "MOODENG",
                    "amount_usd": 1048154.3710938414,
                    "erc_standard": "ERC20"
                },
                {
                    "name": "Dai Stablecoin",
                    "amount": 317203.0,
                    "symbol": "DAI",
                    "amount_usd": 317201.66872744757,
                    "erc_standard": "ERC20"
                },
                {
                    "name": "Dohrnii",
                    "amount": 5000.0,
                    "symbol": "DHN",
                    "amount_usd": 172832.61326892662,
                    "erc_standard": "ERC20"
                },
                {
                    "name": "OMGToken",
                    "amount": 123647.0,
                    "symbol": "OMG",
                    "amount_usd": 26081.66511706053,
                    "erc_standard": "ERC20"
                },
                {
                    "name": "ETHEREUM IS GOOD",
                    "amount": 250000000,
                    "symbol": "EBULL",
                    "amount_usd": 23262.436501323155,
                    "erc_standard": "ERC20"
                },
                {
                    "name": "Ethereum Name Service",
                    "amount": 1144.0,
                    "symbol": "ENS",
                    "amount_usd": 18297.508978340375,
                    "erc_standard": "ERC20"
                },
                {
                    "name": "USD Coin",
                    "amount": 12999.0,
                    "symbol": "USDC",
                    "amount_usd": 12999.921602012299,
                    "erc_standard": "ERC20"
                },
                {
                    "name": "laikaCTO",
                    "amount": 200000000,
                    "symbol": "laika",
                    "amount_usd": 7355.141016908444,
                    "erc_standard": "ERC20"
                }
            ],
            "top_holdings_nft":
            [
                {
                    "name": "Ethereum Name Service",
                    "amount": 424,
                    "symbol": "ENS",
                    "token_id":
                    [
                        "74481930497801679782979805597155678018362992166714802362506889922792265996967",
                        "40854335592281779147368291490257069102316565960635416178454141923169517258473",
                        "66080057564383363079578701704521412678991955510031339909001493531937345034165",
                        "...",
                        "51462145666241207470964329999130427189030214946591225485456513185798772029146",
                        "104091194179714615977240274011438909631792641773420468905005880127643596822864",
                        "58724798076055449282850230595171994771009527170557920842071621498584953790324",
                        "43944039825831553872908122188214684205530071693640052903619886398974524619490"
                    ],
                    "erc_standard": "ERC721"
                },
                {
                    "amount": 39,
                    "token_id":
                    [
                        "2275",
                        "2703",
                        "...",
                        "8178",
                        "7795",
                        "6682",
                        "6561",
                        "8999",
                        "6004"
                    ],
                    "erc_standard": "ERC721"
                },
                {
                    "name": "POAP",
                    "amount": 19,
                    "symbol": "The Proof of Attendance Protocol",
                    "token_id":
                    [
                        "114",
                        "144",
                        "...",
                        "5313",
                        "5314"
                    ],
                    "erc_standard": "ERC721"
                },
                {
                    "name": "Soulda",
                    "amount": 11,
                    "symbol": "SOULDA16",
                    "token_id":
                    [
                        "2575",
                        "2585",
                        "...",
                        "7258",
                        "7600"
                    ],
                    "erc_standard": "ERC721"
                },
                {
                    "name": "Art Blocks",
                    "amount": 7,
                    "symbol": "BLOCKS",
                    "token_id":
                    [
                        "265000506",
                        "...",
                        "268000057"
                    ],
                    "erc_standard": "ERC721"
                },
                {
                    "name": "Uniswap V3 Positions NFT-V1",
                    "amount": 5,
                    "symbol": "UNI-V3-POS",
                    "token_id":
                    [
                        "112161",
                        "...",
                        "953024"
                    ],
                    "erc_standard": "ERC721"
                },
                {
                    "amount": 4,
                    "token_id":
                    [
                        "190",
                        "192",
                        "191",
                        "193"
                    ],
                    "erc_standard": "ERC721"
                },
                {
                    "amount": 4,
                    "token_id":
                    [
                        "3775",
                        "1315",
                        "191",
                        "3941"
                    ],
                    "erc_standard": "ERC721"
                },
                {
                    "amount": 3,
                    "token_id":
                    [
                        "2174",
                        "3209",
                        "2173"
                    ],
                    "erc_standard": "ERC721"
                },
                {
                    "name": "1337 skulls",
                    "amount": 2,
                    "symbol": "1337skulls",
                    "token_id":
                    [
                        "375",
                        "6444"
                    ],
                    "erc_standard": "ERC721"
                }
            ],
            "number_of_erc20_tokens": null,
            "number_of_erc721_tokens": null,
            "number_of_erc1155_tokens": null,
            "total_balance_usd": null,
            "top_traded_dapps_yesterdays":
            {},
            "primary_country": "United Kingdom",
            "all_countries":
            [
                "South Korea",
                "Thailand",
                "...",
                "Malaysia",
                "Indonesia",
                "Israel"
            ],
            "languages":
            [
                "English",
                "Croatian",
                "Polish",
                "French",
                "Spanish",
                "Korean",
                "Japanese",
                "Arabic"
            ],
            "platforms_30_days":
            {
                "desktop": 13
            },
            "social_platforms_30_days":
            [],
            "platform_percentages_30_days":
            {
                "desktop": 1.0
            },
            "first_seen_channel": "Referrals",
            "first_seen_domain": "warpcast.com",
            "last_seen_channel": "Referrals",
            "last_seen_domain": "warpcast.com",
            "tags":
            [
                "Liquidity Provider",
                "Swapper"
            ],
            "wallet_name": null
        },
        "..."
	]
}