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.