tatum-js
[](https://tatum.io) # 🚀 Tatum SDK – Your Gateway to Blockchain The Tatum SDK is a comprehensive TypeScript/JavaScript library designed to simplify blockchain application development. Whether you're monitoring blockchain addresses, making RPC calls, managing NFTs, or querying wallet balances and transactions, Tatum SDK streamlines the process with its robust features: - 🕵️♂️ **Blockchain Monitoring**: Easily track activities on any blockchain address. - 📞 **RPC Calls Simplified**: Interact with various blockchains through simplified RPC calls. - 🖼️ **NFT Insights**: Access detailed information on NFT balances, transactions, and ownership. - 💰 **Wallet Intelligence**: Get precise data on wallet balances and transaction history. [](https://github.com/tatumio/tatum-js) [](https://www.npmjs.com/package/@tatumio/tatum) [](https://github.com/tatumio/tatum-js/blob/master/LICENSE.txt) [](https://img.shields.io/github/actions/workflow/status/tatumio/tatum-js/build.yml?branch=master) --- 🔑 **Don't have an API key?** Unlock all networks, features, and monitor error logs & usage with ease. [Create API Key for FREE](https://dashboard.tatum.io) - Start building on Tatum with full access to our powerful suite of features. ## Tailored for Developers Engineered with a developer-first approach, Tatum SDK accelerates your blockchain application development, regardless of your experience level. Explore our [Documentation](https://docs.tatum.io) and [Getting Started Guide](https://github.com/tatumio/tatum-js#getting-started) to jumpstart your projects: - **Super fast development:** Start building blockchain applications in no time. - **No previous blockchain experience required:** Perfect for beginners and experts alike. - **One line of code:** Perform complex tasks with minimal effort. Need help or want to contribute? [Report Bugs](https://github.com/tatumio/tatum-js/issues/new?assignees=-&labels=bug&template=bug_report.yml), join our community, or collaborate on improvements. [](https://discord.gg/tatum) [](https://twitter.com/tatum_io) [](https://www.youtube.com/channel/UCF-OAfXNJ9h3U2ycHE1NGNw) ### 🔌 Perform Native RPC Calls Interact seamlessly with various blockchains through native RPC calls. Say goodbye to the hassle of juggling separate RPC clients for each blockchain. | Documentation | | --------------------------------------------------------------------------------------------------------- | | **EVM Blockchains** | | [Ethereum RPC](https://docs.tatum.io/docs/rpc/evm-blockchains/ethereum-rpc-documentation) | | [Polygon RPC](https://docs.tatum.io/docs/rpc/evm-blockchains/polygon-rpc-documentation) | | [Flare RPC](https://docs.tatum.io/docs/rpc/evm-blockchains/flare-rpc-documentation) | | [Haqq RPC](https://docs.tatum.io/docs/rpc/evm-blockchains/haqq-rpc-documentation) | | [Optimism RPC](https://docs.tatum.io/docs/rpc/evm-blockchains/optimism-rpc-documentation) | | [Horizen EON RPC](https://docs.tatum.io/docs/rpc/evm-blockchains/horizen-eon-rpc-documentation) | | [Arbitrum One RPC](https://docs.tatum.io/docs/rpc/evm-blockchains/arbitrum-rpc-documentation) | | [Chiliz RPC](https://docs.tatum.io/docs/rpc/evm-blockchains/chiliz-rpc-documentation) | | [Ethereum Classic RPC](https://docs.tatum.io/docs/rpc/evm-blockchains/ethereum-classic-rpc-documentation) | | [Klaytn RPC](https://docs.tatum.io/docs/rpc/evm-blockchains/klaytn-rpc-documentation) | | [Avalanche RPC](https://docs.tatum.io/docs/rpc/evm-blockchains/avalanche-rpc-documentation) | | [Celo RPC](https://docs.tatum.io/docs/rpc/evm-blockchains/celo-rpc-documentation) | | [XinFin RPC](https://docs.tatum.io/docs/rpc/evm-blockchains/xinfin-rpc-documentation) | | [Fantom RPC](https://docs.tatum.io/docs/rpc/evm-blockchains/fantom-rpc-documentation) | | [Base RPC](https://docs.tatum.io/docs/rpc/evm-blockchains/base-rpc-documentation) | | **UTXO Blockchains** | | [Bitcoin RPC](https://docs.tatum.io/docs/rpc/utxo-blockchains/bitcoin-rpc-documentation) | | [Litecoin RPC](https://docs.tatum.io/docs/rpc/utxo-blockchains/litecoin-rpc-documentation) | | [Dogecoin RPC](https://docs.tatum.io/docs/rpc/utxo-blockchains/dogecoin-rpc-documentation) | | [ZCash RPC](https://docs.tatum.io/docs/rpc/utxo-blockchains/zcash-rpc-documentation) | | [Bitcoin Cash RPC](https://docs.tatum.io/docs/rpc/utxo-blockchains/bitcion-cash-rpc-documentation) | | **Other Blockchains** | | [Solana RPC](https://docs.tatum.io/docs/rpc/solana-rpc-documentation) | | [XPR RPC](https://docs.tatum.io/docs/rpc/xrp-rpc-documentation) | | [Tron RPC](https://docs.tatum.io/docs/rpc/tron-rpc-documentation) | | [Eos RPC](https://docs.tatum.io/docs/rpc/eos-rpc-documentation) | | [Tezos RPC](https://docs.tatum.io/docs/rpc/tezos-rpc-documentation) | | [Agorand RPC](https://docs.tatum.io/docs/rpc/algo-rpc-documentation) | | [Cardano RPC](https://docs.tatum.io/docs/rpc/cardano-rpc-documentation) | | [Stellar RPC](https://docs.tatum.io/docs/rpc/stellar-rpc-documentation) | | [Iota RPC](https://docs.tatum.io/docs/rpc/iota-rpc-documentation) | | [Kadena RPC](https://docs.tatum.io/docs/rpc/kadena-rpc-documentation) | | [Rostrum RPC](https://docs.tatum.io/docs/rpc/rostrum-rpc-documentation) | | [Cronos RPC](https://docs.tatum.io/docs/rpc/cronos-rpc-documentation) | ### 🔔 Create Notifications Effortlessly monitor wallet activities. Set up real-time notifications for events like: | Documentation | | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | [Start monitoring of the address](https://docs.tatum.io/docs/notifications/notification-workflow/start-monitoring-of-the-address) | | [Stop monitoring of the address](https://docs.tatum.io/docs/notifications/notification-workflow/stop-monitoring-of-the-address) | | [Get all sent notifications](https://docs.tatum.io/docs/notifications/notification-workflow/get-all-sent-notifications) | | [Get all existing monitoring subscriptions](https://docs.tatum.io/docs/notifications/notification-workflow/get-all-existing-monitoring-subscriptions) | ### 👛 Access Wallet Information Through a single interface, obtain crucial wallet details such as balances, transaction history, and other pertinent information. | Documentation | | ----------------------------------------------------------------------------------------------------------------------------- | | [Get all assets the wallet holds](https://docs.tatum.io/docs/wallet-address-operations/get-all-assets-the-wallet-holds) | | [Get all transactions on the wallet](https://docs.tatum.io/docs/wallet-address-operations/get-all-transactions-on-the-wallet) | ### 🖼️ NFT Actions Dive into a comprehensive suite of actions related to non-fungible tokens (NFTs). | Documentation | | ------------------------------------------------------------------------------------------------------------------ | | [Get all NFTs the wallet holds](https://docs.tatum.io/docs/nfts/get-all-nfts-the-wallet-holds) | | [Get all NFTs in the NFT collection](https://docs.tatum.io/docs/nfts/get-all-nfts-in-the-nft-collection) | | [Trace the history of a specific NFT](https://docs.tatum.io/docs/nfts/trace-the-history-of-a-specific-nft) | | [Show the NFT history of a wallet](https://docs.tatum.io/docs/nfts/show-the-nft-history-of-a-wallet) | | [Create NFT Collection](https://docs.tatum.io/docs/nfts/create-nft-collection) | | [Create MultiToken NFT Collection](https://docs.tatum.io/docs/nfts/create-multitoken-nft-collection) | | [Retrieve the owner of the NFT](https://docs.tatum.io/docs/nfts/retrieve-the-owner-of-the-nft) | | [Check if the wallet owns a specific NFT](https://docs.tatum.io/docs/nfts/check-if-the-wallet-owns-a-specific-nft) | | [Get the metadata of a specific NFT](https://docs.tatum.io/docs/nfts/get-the-metadata-of-a-specific-nft) | ### 🪙 Fungible Tokens Explore the world of fungible tokens, manage their properties, and track your assets seamlessly. | Documentation | | ------------------------------------------------------------------------------------------------------------------------------- | | [Get all fungible tokens the wallet holds](https://docs.tatum.io/docs/fungible-tokens/get-all-fungible-tokens-the-wallet-holds) | | [Show fungible token history of a wallet](https://docs.tatum.io/docs/fungible-tokens/show-fungible-token-history-of-a-wallet) | | [Get metadata of a fungible token](https://docs.tatum.io/docs/fungible-tokens/get-metadata-of-a-fungible-token) | | [Create a fungible token](https://docs.tatum.io/docs/fungible-tokens/create-a-fungible-token) | ### 📁 IPFS Enables you as a developer to use IPFS to store and retrieve your media. | Documentation | | ------------------------------------------------------------------ | | [Upload file to IPFS](https://docs.tatum.io/docs/ipfs/upload-file) | ### ⛽ Fee Estimation Stay updated with real-time fee insights and ensure smooth transactions without overpaying. | Documentation | | ----------------------------------------------------------------------------------- | | [Fetch real-time fee data](https://docs.tatum.io/docs/fee-estimation/getcurrentfee) | ### 💻 Wallet Provider Integrate, transact, and manage assets using a secure and user-friendly wallet provider interface. | Documentation | | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [Connect a wallet](https://docs.tatum.io/docs/wallet-provider/metamask/connect-a-wallet) | | [Transfer native assets](https://docs.tatum.io/docs/wallet-provider/metamask/transfer-native-assets) | | [Transfer your NFT](https://docs.tatum.io/docs/wallet-provider/metamask/transfer-your-nft) | | [Create your NFT Collection](https://docs.tatum.io/docs/wallet-provider/metamask/create-your-nft-collection) | | [Create your Fungible Token](https://docs.tatum.io/docs/wallet-provider/metamask/create-your-fungible-token) | | [Create your NFT (ERC-1155 MultiToken) Collection](https://docs.tatum.io/docs/wallet-provider/metamask/create-your-nft-erc-1155-multitoken-collection) | | [Transfer fungible tokens like USDT](https://docs.tatum.io/docs/wallet-provider/metamask/transfer-fungible-tokens-like-usdt) | | [Approve the transfer of a fungible token like USDT](https://docs.tatum.io/docs/wallet-provider/metamask/approve-the-transfer-of-a-fungible-token-like-usdt) | | [Build your own custom transaction](https://docs.tatum.io/docs/wallet-provider/metamask/build-your-own-custom-transaction) | ### 💲 Exchange Rates Access the latest crypto exchange rates and supported currency information to stay ahead in the market. | Documentation | | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | [Get current exchange rate of the crypto asset](https://docs.tatum.io/docs/exchange-rates/get-current-exchange-rate-of-the-crypto-asset) | | [Get current rates for multiple crypto assets at once](https://docs.tatum.io/docs/exchange-rates/get-current-rates-for-multiple-crypto-assets-at-once) | | [Supported Crypto Currencies](https://docs.tatum.io/docs/exchange-rates/supported-crypto-currencies) | | [Supported Fiats](https://docs.tatum.io/docs/exchange-rates/supported-fiats) | ### 📘 Getting Started with TatumSDK This guide will lead you step by step, from basic setup and installation to harnessing the immense capabilities of our library. For a detailed walkthrough, check out the [Getting Started page](https://docs.tatum.io/sdk/get-started-with-tatum-sdk). ### 📊 TatumSDK Dashboard Experience powerful insights into your application's usage with the [Tatum Dashboard](https://dashboard.tatum.io/). It provides real-time analytics, user engagement metrics, and an intuitive interface, seamlessly integrating with TatumSDK for optimal app monitoring. ### 🌱 Always Evolving Our library is on a continuous journey of growth. We regularly add new features and extend support for more blockchains. It's the go-to choice for developers aiming to craft robust, scalable, and efficient blockchain apps without the overwhelming intricacies of diverse blockchain protocols. ## Prerequisites Before diving into TatumSDK, ensure that you have the following prerequisites installed: - **Node.js**: Ensure you have the latest LTS version installed. - **npm**: npm is bundled with Node.js, so installing Node.js should automatically install npm. ## Installation To install TatumSDK, simply run the following command in your terminal or command prompt: ### Install using [npm](https://www.npmjs.com/) ```console npm install @tatumio/tatum ``` ### Install using [yarn](https://yarnpkg.com/) ```console yarn add @tatumio/tatum ``` ### Install using [pnpm](https://pnpm.io/) ```console pnpm install @tatumio/tatum ``` ## Getting started ### Basic Usage Here's a brief overview of how to utilize TatumSDK for RPC calls and subscribing to notifications. ### Initialization Start by importing the TatumSDK library and initializing Ethereum client as follows: ```ts import { TatumSDK, Network, Ethereum } from '@tatumio/tatum' const tatum = await TatumSDK.init<Ethereum>({ network: Network.ETHEREUM }) // Destroy Tatum SDK - needed for stopping background jobs await tatum.destroy() ``` For more details, check out the [Get started documentation](https://docs.tatum.io/sdk/javascript-typescript-sdk). ### RPC Calls To make RPC calls, use the available methods to interact with Ethereum blockchain. For example, to fetch the balance of a specific Ethereum address: ```ts import { TatumSDK, Network, Ethereum } from '@tatumio/tatum' const tatum = await TatumSDK.init<Ethereum>({ network: Network.ETHEREUM }) const { result } = await tatum.rpc.getBalance('0x742d35Cc6634C0532925a3b844Bc454e4438f44e') console.log(`Balance: ${result}`) // Destroy Tatum SDK - needed for stopping background jobs await tatum.destroy() ``` For more details, check out the [RPC documentation](https://docs.tatum.io/docs/rpc). ### Subscribing to Notifications To subscribe to notifications for events related to a specified Ethereum address, choose a type of event you want to be notified about. We are going to use `addressEvent` as an example, which sends you notification about any transfer on the address - native ones, ERC20 tokens or NFTs. To subscribe to this event, use the following code: ```ts import { TatumSDK, Network, Ethereum } from '@tatumio/tatum' const tatum = await TatumSDK.init<Ethereum>({ network: Network.ETHEREUM }) const response = await tatum.notification.subscribe.addressEvent({ url: 'https://<YOUR_WEBHOOK_URL>', address: '0x690B9A9E9aa1C9dB991C7721a92d351Db4FaC990', }) console.log(response) // 🎉 Now your address is subscribed for any events! // Destroy Tatum SDK - needed for stopping background jobs await tatum.destroy() ``` For more details, check out the [Notifications documentation](https://docs.tatum.io/docs/notifications). ### Get NFT balance of a wallet Using TatumSDK, obtain the NFT balance of an address by calling the getNFTBalance method within the NFT submodule and passing the target address as an argument. This streamlined process efficiently retrieves the total number of NFTs owned by the specified address. To achieve this, use the following code: ```ts import { TatumSDK, Network, Ethereum, NftAddressBalance } from '@tatumio/tatum' const tatum = await TatumSDK.init<Ethereum>({ network: Network.ETHEREUM }) const balances: NftAddressBalance[] = await tatum.nft.getBalance({ addresses: ['0x53e8577c4347c365e4e0da5b57a589cb6f2ab849'], }) console.log(balances) // Destroy Tatum SDK - needed for stopping background jobs await tatum.destroy() ``` For more details, check out the [NFTs documentation](https://docs.tatum.io/docs/nfts). ### Connect to MetaMask and send transaction Using TatumSDK, it's possible to connect your browser application to MetaMask and perform transactions using it. To achieve this, use the following code: ```ts import { TatumSDK, Network, Ethereum, MetaMask } from '@tatumio/tatum' const tatum = await TatumSDK.init<Ethereum>({ network: Network.ETHEREUM }) const account: string = await tatum.walletProvider.use(MetaMask).getWallet() const txId: string = await tatum.walletProvider .use(MetaMask) .transferNative('0x53e8577C4347C365E4e0DA5B57A589cB6f2AB848', '1') console.log(txId) // Destroy Tatum SDK - needed for stopping background jobs await tatum.destroy() ``` For more details, check out the [Wallet Provider documentation](https://docs.tatum.io/docs/wallet-provider). ### Get exchange rates Using TatumSDK, obtain current fiat/crypto exchange rates To achieve this, use the following code: ```ts import { TatumSDK, Network, Ethereum } from '@tatumio/tatum' const tatum = await TatumSDK.init<Ethereum>({ network: Network.ETHEREUM }) const res = await tatum.rates.getCurrentRate('BTC', 'EUR') console.log(res.data) // Destroy Tatum SDK - needed for stopping background jobs await tatum.destroy() ``` For more details, check out the [Exchange Rates documentation](https://docs.tatum.io/docs/exchange-rates). ### Get current fees Using TatumSDK, you can obtain recommended fee/gas price for a blockchain. ```ts import { TatumSDK, Network, Ethereum } from '@tatumio/tatum' const tatum = await TatumSDK.init<Ethereum>({ network: Network.ETHEREUM_SEPOLIA, verbose: true, retryDelay: 1000, retryCount: 2, version: ApiVersion.V3, }) const result = await tatum.fee.getCurrentFee() console.log(result.data) // Destroy Tatum SDK - needed for stopping background jobs await tatum.destroy() ``` For more details, check out the [Fee Estimation documentation](https://docs.tatum.io/docs/fee-estimation). ### Get token balance Using TatumSDK, obtain all fungible token balances of an address by calling the getBalance method within the `token` submodule and passing the target address as an argument. This streamlined process efficiently retrieves all balances for fungible tokens that specified address holds. To achieve this, use the following code: ```ts import { TatumSDK, Network, Ethereum } from '@tatumio/tatum' const tatum = await TatumSDK.init<Ethereum>({ network: Network.ETHEREUM_SEPOLIA }) const { data: balances } = await tatum.token.getBalance({ addresses: ['0x2cbaf358c0af93096bd820ce57c26f0b7c6ec7ab'], }) console.log(balances) // Destroy Tatum SDK - needed for stopping background jobs await tatum.destroy() ``` For more details, check out the [Fungible Tokens documentation](https://docs.tatum.io/docs/fungible-tokens). ### Get all transactions on the wallet Using TatumSDK, you can obtain transaction history of the wallet. ```ts import { TatumSDK, Network, Ethereum } from '@tatumio/tatum' const tatum = await TatumSDK.init<Ethereum>({ network: Network.ETHEREUM_SEPOLIA }) const { data: txs } = await tatum.address.getTransactions({ address: '0x514d547c8ac8ccbec29b5144810454bd7d3625ca', }) console.log(txs) // Destroy Tatum SDK - needed for stopping background jobs await tatum.destroy() ``` For more details, check out the [Wallet address operations documentation](https://docs.tatum.io/docs/wallet-address-operations). ## RPC calls All RPC calls are implemented in the `tatum.rpc.*` submodule. See the [RPC API Reference](https://docs.tatum.io/docs/rpc-api-reference) for more about supported chains and methods. ### Distinguishing Between Archive and Full Nodes When interacting with the blockchain, it's essential to know whether a JSON RPC call requires an archive node or can be serviced by a full node. The distinction hinges on the type of data requested and the historical depth of that data. Here's a breakdown of the conditions under which a call is classified for an archive or a full node: #### Archive Node Calls Archive nodes store the entire history of the blockchain, including the state of all accounts at every block. Calls that require an archive node typically involve querying historical states. Conditions include: 1. **Calls to Methods `getCode` or `call`**: Always require an archive node because they may query the state at any block height. 2. **Calls Including `debug` or `trace` Methods**: These methods require historical data not available on full nodes. 3. **Parameters Indicating a Specific Block Number**: For following methods, if the call specifies a block number, it requires an archive node. This includes: - `getStorageAt` with a specific block number. - `getBalance` with a specific block number. - `getBlockByNumber` when a block number is specified. - `getLogs` calls where `fromBlock` or `toBlock` specify a block number other than the latest. #### Full Node Calls Any other calls not meeting the conditions for archive node calls can be serviced by a full node. These calls typically involve querying the current state of the blockchain. ### Status Pages This section provides a list of various blockchain network status pages, powered by Tatum. These links direct you to real-time status updates for each network. | Status Pages | | ------------------------------------------------------------------------------------------------------------ | | [bitcoin-mainnet.status.tatum.io](https://bitcoin-mainnet.status.tatum.io) | | [bitcoin-testnet.status.tatum.io](https://bitcoin-testnet.status.tatum.io) | | [bitcoin-testnet4.status.tatum.io](https://bitcoin-testnet4.status.tatum.io) | | [dogecoin-mainnet.status.tatum.io](https://dogecoin-mainnet.status.tatum.io) | | [dogecoin-testnet.status.tatum.io](https://dogecoin-testnet.status.tatum.io) | | [eos-mainnet-archive.status.tatum.io](https://eos-mainnet-archive.status.tatum.io) | | [ethereum-mainnet-archive.status.tatum.io](https://ethereum-mainnet-archive.status.tatum.io) | | [ethereum-mainnet.status.tatum.io](https://ethereum-mainnet.status.tatum.io) | | [ethereum-sepolia-archive.status.tatum.io](https://ethereum-sepolia-archive.status.tatum.io) | | [ethereum-holesky-archive.status.tatum.io](https://ethereum-holesky-archive.status.tatum.io) | | [ethereum-hoodi-archive.status.tatum.io](https://ethereum-hoodi-archive.status.tatum.io) | | [ethereum-mainnet.status.tatum.io](https://ethereum-mainnet.status.tatum.io) | | [flare-coston-archive.status.tatum.io](https://flare-coston-archive.status.tatum.io) | | [flare-coston2-archive.status.tatum.io](https://flare-coston2-archive.status.tatum.io) | | [flare-songbird-archive.status.tatum.io](https://flare-songbird-archive.status.tatum.io) | | [flare-mainnet-archive.status.tatum.io](https://flare-mainnet-archive.status.tatum.io) | | [haqq-mainnet-archive.status.tatum.io](https://haqq-mainnet-archive.status.tatum.io) | | [haqq-mainnet.status.tatum.io](https://haqq-mainnet.status.tatum.io) | | [haqq-testnet.status.tatum.io](https://haqq-testnet.status.tatum.io) | | [chiliz-mainnet.status.tatum.io](https://chiliz-mainnet.status.tatum.io) | | [chiliz-mainnet-archive.status.tatum.io](https://chiliz-mainnet-archive.status.tatum.io) | | [litecoin-mainnet.status.tatum.io](https://litecoin-mainnet.status.tatum.io) | | [litecoin-testnet.status.tatum.io](https://litecoin-testnet.status.tatum.io) | | [optimism-mainnet-archive.status.tatum.io](https://optimism-mainnet-archive.status.tatum.io) | | [polygon-mainnet-archive.status.tatum.io](https://polygon-mainnet-archive.status.tatum.io) | | [polygon-mainnet.status.tatum.io](https://polygon-mainnet.status.tatum.io) | | [horizen-eon-mainnet-archive.status.tatum.io](https://horizen-eon-mainnet-archive.status.tatum.io) | | [horizen-eon-gobi.status.tatum.io](https://horizen-eon-gobi.status.tatum.io) | | [bsc-mainnet-archive.status.tatum.io](https://bsc-mainnet-archive.status.tatum.io) | | [polygon-amoy-archive.status.tatum.io](https://polygon-amoy-archive.status.tatum.io) | | [polygon-amoy.status.tatum.io](https://polygon-amoy.status.tatum.io) | | [tron-mainnet-archive.status.tatum.io](https://tron-mainnet-archive.status.tatum.io) | | [arbitrum-one-mainnet-archive.status.tatum.io](https://arbitrum-one-mainnet-archive.status.tatum.io) | | [ethereum-classic-mainnet-archive.status.tatum.io](https://ethereum-classic-mainnet-archive.status.tatum.io) | | [zcash-mainnet.status.tatum.io](https://zcash-mainnet.status.tatum.io) | | [ripple-mainnet.status.tatum.io](https://ripple-mainnet.status.tatum.io) | | [ripple-testnet.status.tatum.io](https://ripple-testnet.status.tatum.io) | | [bitcoin-cash-mainnet.status.tatum.io](https://bitcoin-cash-mainnet.status.tatum.io) | | [kaia-mainnet.status.tatum.io](https://kaia-mainnet.status.tatum.io) | | [kaia-mainnet-archive.status.tatum.io](https://kaia-mainnet-archive.status.tatum.io) | | [klaytn-baobab.status.tatum.io](https://klaytn-baobab.status.tatum.io) | | [klaytn-baobab-archive.status.tatum.io](https://klaytn-baobab-archive.status.tatum.io) | | [avalanche-c-mainnet-archive.status.tatum.io](https://avalanche-c-mainnet-archive.status.tatum.io) | | [solana-mainnet.status.tatum.io](https://solana-mainnet.status.tatum.io) | | [solana-devnet.status.tatum.io](https://solana-devnet.status.tatum.io) | | [celo-mainnet-archive.status.tatum.io](https://celo-mainnet-archive.status.tatum.io) | | [celo-testnet-archive.status.tatum.io](https://celo-testnet-archive.status.tatum.io) | | [tezos-testnet.status.tatum.io](https://tezos-testnet.status.tatum.io) | | [tezos-mainnet.status.tatum.io](https://tezos-mainnet.status.tatum.io) | | [algorand-mainnet-algod.status.tatum.io](https://algorand-mainnet-algod.status.tatum.io) | | [algorand-testnet-algod.status.tatum.io](https://algorand-testnet-algod.status.tatum.io) | | [algorand-mainnet-indexer.status.tatum.io](https://algorand-mainnet-indexer.status.tatum.io) | | [algorand-testnet-indexer.status.tatum.io](https://algorand-testnet-indexer.status.tatum.io) | | [cardano-mainnet.status.tatum.io](https://cardano-mainnet.status.tatum.io) | | [cardano-preprod.status.tatum.io](https://cardano-preprod.status.tatum.io) | | [xinfin-mainnet-archive.status.tatum.io](https://xinfin-mainnet-archive.status.tatum.io) | | [stellar-mainnet-archive.status.tatum.io](https://stellar-mainnet-archive.status.tatum.io) | | [base-mainnet-archive.status.tatum.io](https://base-mainnet-archive.status.tatum.io) | | [kadena-mainnet.status.tatum.io](https://kadena-mainnet.status.tatum.io) | | [kadena-testnet.status.tatum.io](https://kadena-testnet.status.tatum.io) | | [rostrum-mainnet.status.tatum.io](https://rostrum-mainnet.status.tatum.io) | | [cronos-mainnet-archive.status.tatum.io](https://cronos-mainnet-archive.status.tatum.io) | | [fantom-mainnet-archive.status.tatum.io](https://fantom-mainnet-archive.status.tatum.io) | | [iota-mainnet.status.tatum.io](https://iota-mainnet.status.tatum.io) | ### Load Balancer Load balancer is used managing RPC calls to nodes in a blockchain network. It maintains a list of available nodes and their status, and it automatically selects the most responsive node for subsequent RPC calls. > **_For use of the Load Balancer, you don't need to know how it is working!._** Load Balancer works automatically in the background and selects the most responsive node for subsequent RPC calls. You can use the SDK without any knowledge of the Load Balancer. Load Balancer implementation is available in [LoadBalancerRpc.ts](https://github.com/tatumio/tatum-js/blob/master/src/service/rpc/generic/LoadBalancerRpc.ts) Using a load balancer to distribute traffic across multiple nodes, as opposed to routing all traffic to a single node, has several advantages: - **Improved Performance and Responsiveness:** Load balancers can distribute network or application traffic across several servers, which can help prevent any single server from becoming a bottleneck. As a result, users often experience faster response times. - **Scalability:** Load balancers enable you to handle larger amounts of traffic by simply adding more servers to the pool. This makes it easier to scale your infrastructure as your needs grow. - **Redundancy and High Availability:** If a server goes down, a load balancer can automatically reroute traffic to the remaining online servers. This ensures that your service remains available even in the face of hardware failures or other issues. - **Prevents Overloading of Nodes:** Load balancers can prevent any single server from being overloaded with too many requests, which can degrade the performance of the server and impact user experience. - **Efficient Use of Resources:** By distributing the load, you can make sure that all your servers are being used efficiently, rather than having some servers idle while others are overloaded. - **Flexibility and Maintenance:** With a load balancer, you can take servers offline for maintenance without disrupting service. The load balancer will simply stop sending traffic to the offline server. - **Better User Experience:** Ultimately, all of these benefits can lead to a better user experience, with faster response times and higher availability of services. #### Initialization At start the Load Balancer is initialized with a list of nodes. List of nodes are dynamically fetched from the remote server. There is also option to pass your custom list of nodes instead of the dynamic list. From the list of the nodes is randomly selected one node as a primary node, which is kept as a primary node until first load balancing is performed. The Load Balancer maintain lists of two types of nodes, normal and archive nodes. #### Load Balancing The load balancing process is running in the background and every minute it checks the status of all nodes in the list. The status of each node is determined by making a request to the node's URL and checking the response. The fastest responding node in each category is then selected as the active node for that normal and archive category. The selected nodes are then used for subsequent RPC calls. #### Error Handling If a RPC call fails, failure is logged, and the current active node is marked as failed, and load balancer selects a new active node. #### Destroy When you need to stop load balancer, you should can call `destroy` method. This method stops the load balancing process on the background. #### List of nodes The list of nodes is dynamically fetched from the remote server and it is defined for every blockchain. Here are the list of nodes for each blockchain: | Nodes List | | -------------------------------------------------------------------------------------------------------------------------- | | [rpc.tatum.io/bitcoin-mainnet/list.json](https://rpc.tatum.io/bitcoin-mainnet/list.json) | | [rpc.tatum.io/bitcoin-testnet/list.json](https://rpc.tatum.io/bitcoin-testnet/list.json) | | [rpc.tatum.io/dogecoin-mainnet/list.json](https://rpc.tatum.io/dogecoin-mainnet/list.json) | | [rpc.tatum.io/dogecoin-testnet/list.json](https://rpc.tatum.io/dogecoin-testnet/list.json) | | [rpc.tatum.io/eos-mainnet-archive/list.json](https://rpc.tatum.io/eos-mainnet-archive/list.json) | | [rpc.tatum.io/ethereum-mainnet-archive/list.json](https://rpc.tatum.io/ethereum-mainnet-archive/list.json) | | [rpc.tatum.io/ethereum-mainnet/list.json](https://rpc.tatum.io/ethereum-mainnet/list.json) | | [rpc.tatum.io/ethereum-hoodi-archive/list.json](https://rpc.tatum.io/ethereum-hoodi-archive/list.json) | | [rpc.tatum.io/ethereum-sepolia-archive/list.json](https://rpc.tatum.io/ethereum-sepolia-archive/list.json) | | [rpc.tatum.io/ethereum-holesky-archive/list.json](https://rpc.tatum.io/ethereum-holesky-archive/list.json) | | [rpc.tatum.io/ethereum-sepolia/list.json](https://rpc.tatum.io/ethereum-sepolia/list.json) | | [rpc.tatum.io/flare-coston-archive/list.json](https://rpc.tatum.io/flare-coston-archive/list.json) | | [rpc.tatum.io/flare-coston2-archive/list.json](https://rpc.tatum.io/flare-coston2-archive/list.json) | | [rpc.tatum.io/flare-mainnet-archive/list.json](https://rpc.tatum.io/flare-mainnet-archive/list.json) | | [rpc.tatum.io/flare-songbird-archive/list.json](https://rpc.tatum.io/flare-songbird-archive/list.json) | | [rpc.tatum.io/haqq-mainnet-archive/list.json](https://rpc.tatum.io/haqq-mainnet-archive/list.json) | | [rpc.tatum.io/haqq-mainnet/list.json](https://rpc.tatum.io/haqq-mainnet/list.json) | | [rpc.tatum.io/haqq-testnet/list.json](https://rpc.tatum.io/haqq-testnet/list.json) | | [rpc.tatum.io/chiliz-mainnet/list.json](https://rpc.tatum.io/chiliz-mainnet/list.json) | | [rpc.tatum.io/chiliz-mainnet-archive/list.json](https://rpc.tatum.io/chiliz-mainnet-archive/list.json) | | [rpc.tatum.io/litecoin-mainnet/list.json](https://rpc.tatum.io/litecoin-mainnet/list.json) | | [rpc.tatum.io/litecoin-testnet/list.json](https://rpc.tatum.io/litecoin-testnet/list.json) | | [rpc.tatum.io/optimism-mainnet-archive/list.json](https://rpc.tatum.io/optimism-mainnet-archive/list.json) | | [rpc.tatum.io/polygon-mainnet-archive/list.json](https://rpc.tatum.io/polygon-mainnet-archive/list.json) | | [rpc.tatum.io/polygon-mainnet/list.json](https://rpc.tatum.io/polygon-mainnet/list.json) | | [rpc.tatum.io/horizen-eon-mainnet-archive/list.json](https://rpc.tatum.io/horizen-eon-mainnet-archive/list.json) | | [rpc.tatum.io/horizen-eon-gobi/list.json](https://rpc.tatum.io/horizen-eon-gobi/list.json) | | [rpc.tatum.io/bsc-mainnet-archive/list.json](https://rpc.tatum.io/bsc-mainnet-archive/list.json) | | [rpc.tatum.io/polygon-amoy-archive/list.json](https://rpc.tatum.io/polygon-amoy-archive/list.json) | | [rpc.tatum.io/polygon-amoy/list.json](https://rpc.tatum.io/polygon-amoy/list.json) | | [rpc.tatum.io/tron-mainnet-archive/list.json](https://rpc.tatum.io/tron-mainnet-archive/list.json) | | [rpc.tatum.io/arbitrum-one-mainnet-archive/list.json](https://rpc.tatum.io/arbitrum-one-mainnet-archive/list.json) | | [rpc.tatum.io/ethereum-classic-mainnet-archive/list.json](https://rpc.tatum.io/ethereum-classic-mainnet-archive/list.json) | | [rpc.tatum.io/zcash-mainnet/list.json](https://rpc.tatum.io/zcash-mainnet/list.json) | | [rpc.tatum.io/ripple-mainnet/list.json](https://rpc.tatum.io/ripple-mainnet/list.json) | | [rpc.tatum.io/ripple-testnet/list.json](https://rpc.tatum.io/ripple-testnet/list.json) | | [rpc.tatum.io/kaia-mainnet/list.json](https://rpc.tatum.io/kaia-mainnet/list.json) | | [rpc.tatum.io/kaia-mainnet-archive/list.json](https://rpc.tatum.io/kaia-mainnet-archive/list.json) | | [rpc.tatum.io/klaytn-baobab/list.json](https://rpc.tatum.io/klaytn-baobab/list.json) | | [rpc.tatum.io/klaytn-baobab-archive/list.json](https://rpc.tatum.io/klaytn-baobab-archive/list.json) | | [rpc.tatum.io/bitcoin-cash-mainnet/list.json](https://rpc.tatum.io/bitcoin-cash-mainnet/list.json) | | [rpc.tatum.io/avalanche-c-mainnet-archive/list.json](https://rpc.tatum.io/avalanche-c-mainnet-archive/list.json) | | [rpc.tatum.io/solana-mainnet/list.json](https://rpc.tatum.io/solana-mainnet/list.json) | | [rpc.tatum.io/solana-devnet/list.json](https://rpc.tatum.io/solana-devnet/list.json) | | [rpc.tatum.io/celo-mainnet-archive/list.json](https://rpc.tatum.io/celo-mainnet-archive/list.json) | | [rpc.tatum.io/celo-testnet-archive/list.json](https://rpc.tatum.io/celo-testnet-archive/list.json) | | [rpc.tatum.io/tezos-testnet/list.json](https://rpc.tatum.io/tezos-testnet/list.json) | | [rpc.tatum.io/tezos-mainnet/list.json](https://rpc.tatum.io/tezos-mainnet/list.json) | | [rpc.tatum.io/algorand-mainnet-algod/list.json](https://rpc.tatum.io/algorand-mainnet-algod/list.json) | | [rpc.tatum.io/algorand-testnet-algod/list.json](https://rpc.tatum.io/algorand-testnet-algod/list.json) | | [rpc.tatum.io/algorand-mainnet-indexer/list.json](https://rpc.tatum.io/algorand-mainnet-indexer/list.json) | | [rpc.tatum.io/algorand-testnet-indexer/list.json](https://rpc.tatum.io/algorand-testnet-indexer/list.json) | | [rpc.tatum.io/cardano-mainnet/list.json](https://rpc.tatum.io/cardano-mainnet/list.json) | | [rpc.tatum.io/cardano-preprod/list.json](https://rpc.tatum.io/cardano-preprod/list.json) | | [rpc.tatum.io/xinfin-mainnet-archive/list.json](https://rpc.tatum.io/xinfin-mainnet-archive/list.json) | | [rpc.tatum.io/stellar-mainnet-archive/list.json](https://rpc.tatum.io/stellar-mainnet-archive/list.json) | | [rpc.tatum.io/base-mainnet-archive/list.json](https://rpc.tatum.io/base-mainnet-archive/list.json) | | [rpc.tatum.io/kadena-mainnet/list.json](https://rpc.tatum.io/kadena-mainnet/list.json) | | [rpc.tatum.io/kadena-testnet/list.json](https://rpc.tatum.io/kadena-testnet/list.json) | | [rpc.tatum.io/rostrum-mainnet/list.json](https://rpc.tatum.io/rostrum-mainnet/list.json) | | [rpc.tatum.io/cronos-mainnet-archive/list.json](https://rpc.tatum.io/cronos-mainnet-archive/list.json) | | [rpc.tatum.io/fantom-mainnet-archive/list.json](https://rpc.tatum.io/fantom-mainnet-archive/list.json) | | [rpc.tatum.io/iota-mainnet/list.json](https://rpc.tatum.io/iota-mainnet/list.json) | Following pattern defines the URL for fetching the list of nodes: ``` https://rpc.tatum.io/${network}/list.json ``` Networks enum is available in the [Network.ts](https://github.com/tatumio/tatum-js/blob/master/src/dto/Network.ts) For instance if we will need Bitcoin mainnet nodes, we will use this URL: ``` curl https://rpc.tatum.io/bitcoin-mainnet/list.json ``` The response is a list of nodes with their url, type (0 - normal, 1 - archive) and location. ```json [ { "location": "Sydney", "type": 0, "url": "https://02-sydney-007-01.rpc.tatum.io/" }, { "location": "Tokyo", "type": 0, "url": "https://02-tokyo-007-02.rpc.tatum.io/" }, { "location": "Dallas", "type": 0, "url": "https://02-dallas-007-03.rpc.tatum.io/" }, { "location": "Sao Paulo", "type": 0, "url": "https://02-saopaulo-007-04.rpc.tatum.io/" }, { "location": "Warsaw", "type": 0, "url": "https://01-warsaw-007-05.rpc.tatum.io/" } ] ``` Load Balancer selects from this list the most responsive node. ### Usage #### Default config ```typescript const tatum = await TatumSDK.init<Ethereum>({ network: Network.ETHEREUM }) const info = await tatum.rpc.chainId() tatum.rpc.destroy() ``` #### Custom RPC node list ```typescript const tatum = await TatumSDK.init<Ethereum>({ network: Network.ETHEREUM, rpc: { nodes: [ { url: 'https://api.tatum.io/v3/blockchain/node/ethereum-mainnet', type: RpcNodeType.NORMAL, }, ], allowedBlocksBehind: 20, oneTimeLoadBalancing: false, }, }) const info = await tatum.rpc.chainId() tatum.rpc.destroy() ``` ## Documentation - [Documentation and Guides](https://docs.tatum.io) to get started with Tatum SDK - [Documentation section](https://github.com/tatumio/tatum-js/tree/master/docs) for more details. ## Examples Explore various applications that utilize the Tatum SDK. These examples help illustrate the SDK's functionality and offer a starting point for developers looking to integrate similar features into their applications.  - [Metamask notifications](https://github.com/tatumio/example-apps/tree/master/Metamask/notifications) - [Metamask portfolio](https://github.com/tatumio/example-apps/tree/master/Metamask/portfolio) - [Metamask transfer](https://github.com/tatumio/example-apps/tree/master/Metamask/transfer) ## 🌐 Extension Ecosystem ### Quickstart Import any Tatum SDK extension to your project and start using it right away. ```typescript import { TatumSDK, Ethereum, Network, ApiVersion } from '@tatumio/tatum' import { HelloWorldExtension } from '@tatumio/hello-world' const tatumSdk = await TatumSDK.init<Ethereum>({ network: Network.ETHEREUM_SEPOLIA, configureExtensions: [HelloWorldExtension], }) ``` After that you can use the extension in your code with full intellisense. ```typescript await tatumSdk.extension(HelloWorldExtension).sayHello() ``` ### Wallet Providers Tatum SDK supports wallet provider extensions for various wallets. You can use them to integrate your application with the wallet of your choice. ```typescript import { TatumSDK, Ethereum, Network, ApiVersion } from '@tatumio/tatum' import { EvmWalletProvider } from '@tatumio/evm-wallet-provider' const tatumSdk = await TatumSDK.init<Ethereum>({ network: Network.ETHEREUM_SEPOLIA, configureWalletProviders: [EvmWalletProvider], }) ``` Usage for wallet providers is similar to the extensions. ```typescript await tatumSdk.walletProvider.use(EvmWalletProvider).getWallet() ``` 🔍 Check out our [built-in MetaMask wallet provider](./src/service/walletProvider/metaMask/metamask.wallet.provider.ts) 📚 **Learn more about Tatum SDK Extension ecosystem here - [Tatum SDK Extensions](https://github.com/tatumio/ecosystem-addons)** ## Legacy versions Older versions of the Tatum SDK has been moved to long living branches [`Tatum SDK V1`](https://github.com/tatumio/tatum-js/tree/v1) and [`Tatum SDK V2`](https://github.com/tatumio/tatum-js/tree/v2). ## 🤝 Contributing We appreciate your interest in contributing to the Tatum SDK. Here's a guide to help you make meaningful contributions: ### Local Testing Before making a pull request, ensure you've thoroughly tested your changes with a local client. ### Unit Tests Include unit test coverage for any new code you're adding. This helps in maintaining the quality and reliability of our SDK. ### Update the Changelog For every contribution, it's essential to document your changes in the changelog. The changelog keeps track of all the changes, updates, and fixes we make to our SDK. Use the provided format: ```markdown ## [Version Number] - YYYY.MM.DD ### Added/Updated/Fixed/Changed - Description of the change ``` For instance: ```markdown ## [3.0.10] - 2023.08.11 ### Added - New feature XYZ ``` ### Update `package.json` Before creating a pull request or releasing a new version, ensure the `version` in `package.json` is updated to reflect the new release number. ### Release Consideration Your changes will be released after merging the pull request. ### How to add support for new RPC chain - Add new chain to the [Network.ts](./src/dto/Network.ts) enum (Check also LOAD_BALANCER_NETWORKS constants) - Add new class to the [tatum.ts](./src/service/tatum/tatum.ts) file - Add new chain getClient method in the [Utils.ts](./src/util/util.shared.ts) file - Add new chain CURRENCY_NAMES and DECIMALS constants in the [constants.ts](./src/util/constant.ts) file - Update README.md with new chain for status page and list.json - Add E2E test --- 🙌 Thank you for helping make Tatum SDK better! Your contributions play a crucial role in its continuous improvement and growth. ### Bugs and feature requests Have a bug or a feature request? Please first read the issue guidelines and search for existing and closed issues. If your problem or idea is not addressed yet, please open a [new issue](https://github.com/tatumio/tatum-js/issues/new/choose).