@thirdwavelabs/web

INTRODUCTION

The Thirdwave JS SDK provides a service to lookup data about EVM wallets on the Ethereum, Binance, Polygon, Arbitrum, and Base chains. The SDK can be used in a browser via @thirdwavelabs/web or in a node environment with @thirdwavelabs/node.

GETTING STARTED

Installing the SDK and creating an API key are required before constructing a Thirdwave wallet service object.

Installation

Node

yarn add @thirdwavelabs/core @thirdwavelabs/node

# Or

npm install @thirdwavelabs/core @thirdwavelabs/node

Web

yarn add @thirdwavelabs/core @thirdwavelabs/web

# Or

npm install @thirdwavelabs/core @thirdwavelabs/web

Create an API key

Go to Thirdwave Lab's homepage to signup and create an access key. Once created, use the key as an argument to the wallet service class constructor.

Initialize SDK

Create a transport object and pass it to the ThirdwaveEvmWalletService constructor. This transport object represents a connection to Thirdwave's API. Keep a reference to it to make wallet lookups faster by reusing a connection.

import { ThirdwaveEvmWalletService } from '@thirdwavelabs/core';
import { createThirdwaveTransport } from '@thirdwavelabs/node';

const transport = createThirdwaveTransport({
  accessToken: 'twv_********************',
});

const service = new ThirdwaveEvmWalletService(transport);

USAGE

Retrieve a wallet

const wallet = await service.getOne('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045');
console.log(wallet);

Retrieve many wallets

getMany returns an AsyncGenerator that can be iterated upon with the for await syntax.

const  wallets = service.getMany([
  '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
  '0xceB69F6342eCE283b2F5c9088Ff249B5d0Ae66ea',
]);

for  await (const  wallet  in  wallets) {
  // typeof wallet is ThirdwaveEvmWallet
  console.log(wallet);
}

ThirdwaveEVMWallet Properties

See our documentation site for more detailed descriptions.

Property	Type	Description
address	string	String representation of the wallet's address.
balance	number	Current balance in USD of the wallet.
botWarning	boolean	Indicates whether one more transaction patterns indicates the wallet exhibits bot-like behavior (e.g. not human).
engagementScore	number	Rating on scale of 0 to 100 measuring on chain engagement for a wallet using transaction frequency, time since last activity, and outbound transaction value. See documentation site for more detail.
erc20TokenBalance	number	The total sum in USD of all ERC20 tokens held by this wallet across Arbitrum, Base, Binance, Ethereum, Polygon chains.
erc20TokenHoldings	Array	List of ERC20 holdings held across Arbitrum, Base, Binance, Ethereum, Polygon chains.
firstSeenAt	Date	A timestamp indicating when the wallet first appeared on any EVM-compliant chain convered by Thirdwave. See documentation site for more detail.
hodlerScore	number	A score from 0 to 100 measuring a wallet's propensity to hold or flip NFTs based on its trading history. See documentation site for more detail.
nativeTokenBalance	number	The total sum of native currency held across Arbitrum, Base, Binance, Ethereum, Polygon chains.
nativeTokenHoldings	Array	List of native holdings by blockchain.
outboundTransactionCount	bigint	Total number of transactions that this wallet or account has executed over its lifetime. Note, this metric does not include received transactions.
outboundTransactionValue	number	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.
transactionPatterns	Array	A list of transaction patterns indicating whether the wallet exhibits bot-like behavior.

ThirdwaveEVMWallet Functions

Function	Description
getErc20TokenBalanceForBlockchain	Get the wallet's balance for a particular blockchain.
getNativeTokenBalanceForBlockchain	Get the wallet's native balance for a particular blockchain.
hasTransactionPattern	Check if the wallet exhibits a particular transaction pattern.
toJson	Convert the wallet to JSON.
toJsonString	Convert the wallet to a JSON string.

ACKNOWLEDGEMENTS

Thanks to the teams at buf for their amazing work on connect-es.