Skip to main content

⚙️ Start with REST API

The Thirdwave API as a tool for accessing and leveraging Wallet Intelligence data is best suited 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! Check out an overview of all the Thirdwave tools for accessing Wallet Intelligence data here if you aren't sure the API is right for you.

Request Parameters​

Single Wallet Request​

Use this endpoint to get single wallet responses in real-time.

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. "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

Multiple Wallets Batch Request​

This endpoint allows you to retrieve a batch response for multiple wallets at once, which can be particularly useful for analyzing a group of wallets. To use this endpoint, provide an array of addresses in the POST body of your request. Once the request is submitted, you will receive an array of objects in response. This endpoint supports up to 10,000 addresses per request. Smaller batches will provide a response in close to real-time, while larger batches may take a few seconds to minutes.

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 blockchain wallet addresses up to 10K

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

Response Field Categories​

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

  • Attributes are 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 are quantifiable measures that provide insights into a wallet's activity or performance. Standard wallet metrics include outboundTransactionValue balance and outboundTransactionCount

  • Labels are 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 are 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.

See Glossary for in depth descriptions on data types, methodologies, and how to interpret results.

Response Object​

FieldTypeDescription
firstSeenAtTimeStampA timestamp indicating when the wallet first appeared on any EVM-compliant chain convered by Thirdwave. It serves as an indicator of the account's maturity and longevity in the ecosystem, often influencing trustworthiness or credibility assessments.
outboundTransactionCountIntegerTotal number of transactions that this wallet or account has executed over its lifetime. Note, this metric does not include received transactions.
balanceFloat (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 doesn't hold any tokens, the value will be zero. If this wallet does hold tokens but no conversion rates can be found, then the value will be zero as well.
outboundTransactionValueFloat (USD)The amount of currency or tokens expended from the wallet or account over its lifetime. It sheds light on the account's consumption patterns, providing insights into expenditure behaviors or transactional habits.
hodlerScoreIntegerMeasures a wallet's propensity to hold or flip NFTs based on its trading history. Scores range from 0 to 100, where 0 indicates repeated behavior of immediately flipping all NFTs and 100 denotes repeated behavior of still holding all NFTs. Scores are updated daily.
engagementScoreIntegerRating on scale of 0 to 100 measuring on chain engagement for a wallet using transaction frequency, time since last activity, and outbound transaction value. Wallets with high scores demonstrate deeper and higher-value engagement patterns, indicating higher retention and spending potential. In contrast, lower scores suggest minimal activity and a higher likelihood of churn.
botWarningBoolean (true/false)A binary indicator that flags a wallet as a potential bot based on suspicious transaction patterns. A true response is returned when any 1 or more of the transactionPatterns = true. This helps developers identify and mitigate automated activity within their system, enhancing security and maintaining a genuine user experience.
transactionPatternsObject ArraySpecific actions or patterns typically exhibited by automated or scripted accounts (bots). These actions might include repetitive or scripted transactions, consistent patterns, or behaviors that align with programmed instructions rather than natural human interaction. These are all binary true/false flags and when 1 or more of these flags is true, this will trigger botWarning to be true.
transactionPatterns.HIGH_VELOCITYBoolean (true/false)Analyzes transaction rates to detect automated actions beyond human capacity.
transactionPatterns.TIMEDBoolean (true/false)Profiles consistent timed activity, identifying automated behavior to safeguard against bot-driven activities.
transactionPatterns.CONTINUOUSBoolean (true/false)Classifies uninterrupted and perpetual engagement, distinguishing genuine user interactions from automated engagements, bolstering platform security against disruptive bot activities.
transactionPatterns.FUNDINGNETWORKBoolean (true/false)Flags suspicious funding from sources linked to multiple bot wallets.

Single Wallet Example​

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
      }
    ]
  }
}

Multiple Wallets Example​

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.

Error handling​

400 Bad Request: Indicates that the server cannot process the request due to invalid syntax or a client-side error, such as incorrect input data or missing parameters.

401 Unauthorized: Denotes that access to the requested resource is restricted due to missing or invalid authentication credentials, like an expired or incorrect API key/token.

404 Not Found: Indicates that the requested wallet address does not exist on the server, often due to a wrong URL/path or an entity not being available.

429 Too Many Requests: Occurs when the user has sent too many requests within a specific time frame, exceeding the defined rate limits or throttling constraints.

500 Internal Server Error: Signifies an unexpected server-side error that prevents the server from fulfilling the request, often due to a programming or configuration issue.

503 Service Unavailable: Indicates that the server is temporarily unable to handle the request due to maintenance, overload, or unavailability of resources.

504 Gateway Timeout: Occurs when the server acting as a gateway or proxy does not receive a timely response from an upstream server, leading to a timeout in processing the request.

For further information or support on error messages, please join the Telegram group.

Ideas? Comments? Questions?​

Our roadmap is prioritized based on developer feedback. Please don’t hesitate to reach out to any of the following channels: