⚙️ REST API

The Wallet Intelligence API is a tool designed for developers who need to integrate Thirdwave's data directly into their applications or services. If you require high customization and control over the data, using the API directly is the best option. Get started below!

You can pull Wallet Intelligence data via the REST API from the following endpoints:

Single Wallet Requests: Retrieve data about an individual wallet.
Multi-Wallet Requests: Retrieve batch data for multiple wallets at once.
Token Balance Endpoints: Obtain the balances of ERC20 and native EVM tokens.

Single Wallet Requests

Use this endpoint to retrieve data about a single wallet.

Endpoint URL: https://api.thirdwavelabs.com/evm/wallets/{account}

Method: GET

Headers:

X-Api-Key: Your API Key

Path Parameters:

account: A single blockchain wallet address, e.g., "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

Response Field Categories

The Wallet Intelligence API offers four categories of information about wallets:

Attributes: Static characteristics of a wallet that don’t change over time. For example, the firstSeenAt attribute is a timestamp when the wallet first transacted on chain.
Metrics: Quantifiable measures that provide insights into a wallet's activity or performance. Standard wallet metrics include outboundTransactionValue, balance, and outboundTransactionCount.
Labels: Identifiers that categorize wallets based on their attributes, behaviors, or engagement patterns. Similar to tags, a wallet can have many labels, like botWarning or playsGames, to help developers identify wallets that meet specific criteria.
Scores: Calculated ratings based on custom combinations of attributes, metrics, and labels to help developers make informed decisions based on the wallet's onchain characteristics and actions. For example, hodlerScore is a useful indicator of a wallet's long-term participation in NFT projects.

For in-depth descriptions on data types, methodologies, and how to interpret results, refer to the Data Glossary.

Response Object

Field Name	Type	Description
firstSeenAt	TimeStamp	A timestamp indicating when the wallet first appeared on any EVM-compliant chain covered by Thirdwave. It serves as an indicator of the account's maturity and longevity in the ecosystem.
outboundTransactionCount	Integer	Total number of transactions that this wallet or account has executed over its lifetime, excluding received transactions.
balance	Float (USD)	Reflects the current USD value of all native and ERC20 tokens currently owned by a wallet, as calculated by the most recent token to USD conversion rate. If this wallet holds no tokens, the value will be zero.
outboundTransactionValue	Float (USD)	The amount of currency or tokens expended from the wallet or account over its lifetime, providing insights into expenditure behaviors or transactional habits.
hodlerScore	Integer	Measures a wallet's propensity to hold or flip NFTs based on its trading history, with scores ranging from 0 to 100. Updated daily.
engagementScore	Integer	Rating on a scale of 0 to 100 measuring onchain engagement, using transaction frequency, time since last activity, and outbound transaction value.
botWarning	Boolean (true/false)	A binary indicator flagging a wallet as a potential bot based on suspicious transaction patterns. A true response is returned when one or more transactionPatterns flags are true.
transactionPatterns	Object Array	Contains specific patterns or actions associated with automated or scripted accounts, with binary true/false flags. If one or more flags are true, it triggers botWarning to be true.
transactionPatterns.HIGH_VELOCITY	Boolean (true/false)	Detects automated actions based on transaction rates beyond human capacity.
transactionPatterns.TIMED	Boolean (true/false)	Identifies consistent timed activity, safeguarding against bot-driven activities.
transactionPatterns.CONTINUOUS	Boolean (true/false)	Detects uninterrupted and continuous engagement, differentiating human from automated interactions.
transactionPatterns.FUNDINGNETWORK	Boolean (true/false)	Flags funding from sources linked to multiple bot wallets.

Example Request

Request

curl -s \
--request GET 'https://api.thirdwavelabs.com/evm/wallets/0x828d3Fff01cf78C96495aB1bD2C1e1b1b2384A9a' \
--header 'X-Api-Key: YOUR_API_KEY'

Response

{
  "data": {
    "address": "0x828d3fff01cf78c96495ab1bd2c1e1b1b2384a9a",
    "balance": 453.83,
    "botWarning": false,
    "engagementScore": 95,
    "firstSeenAt": "2021-02-11T19:51:10.000Z",
    "hodlerScore": 95,
    "outboundTransactionCount": "973",
    "outboundTransactionValue": 445014.864936489,
    "transactionPatterns": [
      {
        "key": "CONTINUOUS",
        "value": false
      },
      {
        "key": "HIGH_VELOCITY",
        "value": false
      },
      {
        "key": "SUSPICIOUS_WALLET_NETWORK",
        "value": false
      },
      {
        "key": "TIMED",
        "value": false
      }
    ]
  }
}

Multi-Wallet Requests

This endpoint allows you to retrieve a batch response for multiple wallets at once. Supports up to 10,000 wallets per request.

Endpoint URL: https://api.thirdwavelabs.com/evm/wallets/batch

Method: POST

Headers:

X-Api-Key: Your API Key
Content-Type: application/json

Path Parameters: An array of up to 10,000 wallet addresses:

[
    "0x606137dBaBaE484101C66e6De7d15Eb6D8161b19",
    "0x60d851A18d56120e35aCEFd9F0963D85E7B8C6f0",
    ...
    "0X5ED2EE075E8E9AFE1B9230EDC5493EC1C12EE9BF"
]

Request

curl \
--request POST 'https://api.thirdwavelabs.com/evm/wallets/batch' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '["0xd8da6bf26964af9d7eed9e03e53415d37aa96045","0x988527874C7E3f02115F89A6a97135c70B6a47Fc",...,"0x5f3fd252caa351a69f5c98b78fd0db71adfe5bea"]'

Response

[
    {
        "data": {
        "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
        "firstSeenAt": "2015-09-28T08:24:43.000Z",
        "balance": 3206079.16,
        "hodlerScore": 55,
        "engagementScore": 84,
        "botWarning": false,
        "outboundTransactionValue": 64270664.33,
        "outboundTransactionCount": "1244",
        "transactionPatterns": [
         { "key": "CONTINUOUS", "value": false },
         { "key": "HIGH_VELOCITY", "value": false },
         { "key": "SUSPICIOUS_WALLET_NETWORK", "value": false },
         { "key": "TIMED", "value": false }
         ]
    }
    },
    {
        "data": {
        "address": "0x988527874C7E3f02115F89A6a97135c70B6a47Fc",
        "firstSeenAt": "2021-09-14T12:15:40.000Z",
        "balance": 1476.61,
        "hodlerScore": 98,
        "engagementScore": 99,
        "botWarning": true,
        "outboundTransactionValue": 64270664.33,
        "outboundTransactionCount": "1244",
        "transactionPatterns": [
         { "key": "CONTINUOUS", "value": true },
         { "key": "HIGH_VELOCITY", "value": false },
         { "key": "SUSPICIOUS_WALLET_NETWORK", "value": true },
         { "key": "TIMED", "value": false }
         ]
    }
    },
    {
        ...
    },
    {
        "data": {
        "address": "0x5f3fd252caa351a69f5c98b78fd0db71adfe5bea",
        "firstSeenAt": "2024-04-11T07:18:39.000Z",
        "balance": 1.95,
        "hodlerScore": 63,
        "engagementScore": 22,
        "botWarning": false,
        "outboundTransactionValue": 1.56,
        "outboundTransactionCount": "5",
        "transactionPatterns": [
         { "key": "CONTINUOUS", "value": false },
         { "key": "HIGH_VELOCITY", "value": false },
         { "key": "SUSPICIOUS_WALLET_NETWORK", "value": false },
         { "key": "TIMED", "value": false }
         ]
    }
    }
]

Tip - Null responses

If a wallet doesn't exist, wasn't provided in the right format, or it's not on a suppported chain, then the response for that entry in the array will simply be null. If you see this error please check the format of address to ensure it is a blockchain wallet address. Response fields within the array may be null if the wallet does exist but there is no detected activity to populate that specific field.

Token Balance Endpoints

Provides the USD value of both ERC20 and native EVM tokens for a specified wallet. Token balances reflect recent data based on regular conversion rate updates from Coingecko, with native token rates updated every hour and ERC20 token rates every 3 hours. As a result, these values are not fully real-time but offer accurate snapshots within these intervals.

ERC20 Token Holdings

Request
Use this endpoint to get the list and balances of current ERC20 token holdings of a wallet.

Endpoint URL: https://api.thirdwavelabs.com/evm/wallets/:address/erc20_tokens
Method: GET
Headers: X-Api-Key: Your API Key
Path Parameters: address – A single blockchain wallet address. (e.g., "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")

Response Object

{
    "data": [
        {
            "address": "HEX String",
            "blockchain": "String",
            "balance": "Float (USD)"
        },
        {
            "address": "HEX String",
            "blockchain": "String",
            "balance": "Float (USD)"
        }
    ]
}

Fields

Field	Type	Description
blockchain	String	The specific blockchain network where the ERC20 token resides.
tokenAddress	HEX string	The unique contract address of the ERC20 token, represented as a hexadecimal string.
tokenBalance	Float (USD)	The current USD value of the ERC20 token currently owned by the wallet, as calculated by the most recent token-to-USD conversion rate.

Example Request

curl -s \
--request GET 'https://api.thirdwavelabs.com/evm/wallets/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/erc20_tokens' \
--header 'X-Api-Key: YOUR_API_KEY'

Example Response

{
    "data": [
        {
            "address": "0x7Fc66500c84A76Ad7e9c93437bFc5Ac33E2DDaE9",
            "blockchain": "ethereum",
            "balance": "14323.87"
        },
        {
            "address": "0xfc5e67888c97b4a8ff507c7fa9854e0b95a5a8d0",
            "blockchain": "polygon",
            "balance": "294.56"
        }
    ]
}

EVM Native Token Holdings

Request
Use this endpoint to get the list and balances of current native EVM token holdings of a wallet.

Endpoint URL: https://api.thirdwavelabs.com/evm/wallets/:address/native_tokens
Method: GET
Headers: X-Api-Key: Your API Key
Path Parameters: address – A single blockchain wallet address. (e.g., "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")

Response Object

{
    "data": [
        {
            "blockchain": "ETH",
            "balance": "1005.90"
        },
        {
            "blockchain": "BNB",
            "balance": "176.61"
        }
    ]
}

Fields

Field	Type	Description
blockchain	String	The specific blockchain network where the native EVM token resides.
tokenBalance	Float (USD)	The current USD value of the native EVM token currently owned by the wallet, as calculated by the most recent token-to-USD conversion rate.

Example Request

curl -s \
--request GET 'https://api.thirdwavelabs.com/evm/wallets/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/native_tokens' \
--header 'X-Api-Key: YOUR_API_KEY'

Example Response

{
	"data": [
		{
			"blockchain": "ETH",
			"balance": "1005.90"
		},
		{
			"blockchain": "BNB",
			"balance": "176.61"
		}
	]
}

Error Handling

400 Bad Request: Incorrect input data.
401 Unauthorized: Invalid API Key.
404 Not Found: Wallet address doesn’t exist.
429 Too Many Requests: Rate limit exceeded.
500 Internal Server Error: Unexpected error.
503 Service Unavailable: Server overload.

Other Resources

Check out these other pages to learn more about how to get the most out of Wallet Intelligence:

Tools Overview - Choose the best access method.
Use Cases - Step-by-step Wallet Intelligence use cases.
FAQs - Review commonly asked questions.
Glossary - Get detailed definitions & methodologies for Wallet Intelligence fields as well as general terminology.
Contact Us - See all the different ways to contact our team for support.

⚙️ REST API

Single Wallet Requests​

Response Field Categories​

Response Object​

Example Request​

Request​

Response​

Multi-Wallet Requests​

Request​

Response​

Token Balance Endpoints​

ERC20 Token Holdings​

Example Request​

Example Response​

EVM Native Token Holdings​

Fields​

Example Request​

Example Response​

Error Handling​

Other Resources​

Single Wallet Requests

Response Field Categories

Response Object

Example Request

Request

Response

Multi-Wallet Requests

Request

Response

Token Balance Endpoints

ERC20 Token Holdings

Example Request

Example Response

EVM Native Token Holdings

Fields

Example Request

Example Response

Error Handling

Other Resources