Tatum
Search…
How to automatically scan for transactions at a blockchain address
This guide will teach you how to integrate any blockchain or crypto asset supported by Tatum into your application. The following fundamental operations must be performed to work with any blockchain:
  • Creating an address on the blockchain and preserving the private key for it. With an address, it is possible to receive and send cryptocurrencies.
  • The ability to list all the incoming and outgoing transactions at the specific address
  • Getting the current balance of the address
Those are the three main features that should be supported in any application. But on top of that, Tatum provides many enterprise-ready features that are nice to have and significantly enhance user experience.
  • Getting notifications when there is an incoming transaction to the blockchain address.
  • The ability to freeze funds at the address
  • The ability to temporarily block funds at the address
  • The ability to work with multiple blockchain addresses as one
Most of these additional features are not available on most blockchains. For example, it's not possible to get a list of transactions at a specific address on Bitcoin or Ethereum. To do that, you need to process every block and every transaction that occurred on the blockchain and make your own list in your database. Notifications about incoming transactions are not supported on almost any blockchain, but they are crucial for your application's users.
Did you know that you should generate a new blockchain address for every new incoming transaction on the Bitcoin blockchain? It increases the privacy of the owner of the address.
With Tatum's virtual accounts, it is super easy to utilize all of the above features. You create an account, connect one or multiple blockchain addresses to it, and the account automatically synchronizes all the incoming blockchain transactions at all connected addresses.

Creating an account

Every virtual account must have a defined currency. The currency cannot be changed in the future. During the creation of the account, xpub from the blockchain wallet must be entered. This is the first connection between the blockchain and the virtual account.
Optionally, every account can belong to a specific customer in Tatum. The customer inside Tatum is an entity containing information about your application's user, such as the customer's country of residence, accounting currency, etc. The customer is only created during the new account's creation, and the only required field is the external ID. This is an identifier of the user in your external system. More details are available in the API Reference.
This guide will show you how to set up and connect a virtual account on the Bitcoin blockchain. For more information on how to set up guides on UTXO blockchains, blockchains like XRP, and account-based blockchains, please refer to the respective guides in this section.
Use the following API endpoint to generate a virtual account from the xpub of a Bitcoin wallet.
JavaScript
cURL
1
import { Account, Currency, CreateAccount, createAccount } from "@tatumio/tatum";
2
import { config } from "dotenv";
3
4
config();
5
6
const createNewAccount = async () => {
7
const createAccountData: CreateAccount = {
8
currency: Currency.BTC,
9
xpub: wallet.address
10
};
11
const accoun: Account = await createAccount(createAccountData);
12
console.log(accoun);
13
};
14
15
createNewAccount();
Copied!
1
curl --location --request POST 'https://api-eu1.tatum.io/v3/ledger/account' \
2
--header 'x-api-key: YOUR_API_KEY' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"currency": "BTC",
6
"xpub": "tpubDE8GQ9vAXpwkp37PCCRUpCoeShpC4WiCcACxh8r3nnKjfRPRqw3w58EgkfNiBy1MaRqX1oAAxwAxauEUG7vWupSh5m15znGy7vE7aE6CWzb"
7
}'
Copied!
The response contains information about your newly generated virtual account.
Response
1
{
2
"currency": "BTC",
3
"active": true,
4
"balance": {
5
"accountBalance": "0",
6
"availableBalance": "0"
7
},
8
"frozen": false,
9
"xpub": "tpubDE8GQ9vAXpwkp37PCCRUpCoeShpC4WiCcACxh8r3nnKjfRPRqw3w58EgkfNiBy1MaRqX1oAAxwAxauEUG7vWupSh5m15znGy7vE7aE6CWzb",
10
"accountingCurrency": "EUR",
11
"id": "5fb7bdf6e96d9ab593e191a5"
12
}
Copied!

Generating a blockchain address and connecting it to the virtual account

Now that you've created a virtual account, you must synchronize it with the blockchain. Until you do, there is no blockchain address connected to the account, only a blockchain wallet from which addresses will be chosen.
To connect a specific address, you need to generate an address for the account using the create new deposit address endpoint.
JavaScript
cURL
1
import { generateDepositAddress, Address } from "@tatumio/tatum";
2
import { config } from "dotenv";
3
4
config();
5
6
const createNewDepositAddress = async () => {
7
const id = account.id;
8
const address: Address = await generateDepositAddress(id);
9
console.log(address);
10
};
11
12
createNewDepositAddress();
Copied!
1
curl --location --request POST 'https://api-eu1.tatum.io/v3/offchain/account/5fb7bdf6e96d9ab593e191a5/address' \
2
--header 'x-api-key: YOUR_API_KEY'
Copied!
The response will contain the blockchain address you have just generated.
Response
1
{
2
"xpub": "tpubDE8GQ9vAXpwkp37PCCRUpCoeShpC4WiCcACxh8r3nnKjfRPRqw3w58EgkfNiBy1MaRqX1oAAxwAxauEUG7vWupSh5m15znGy7vE7aE6CWzb",
3
"derivationKey": 1,
4
"address": "mgSXLa5sJHvBpYTKZ62aW9z2YWQNTJ59Zm",
5
"currency": "BTC"
6
}
Copied!
Any incoming blockchain transaction to this address will be automatically synchronized to the virtual account.
It is possible to enable webhook notifications for every incoming transaction to the virtual account.

Viewing a list of blockchain addresses connected to an account

It is possible to work with only one blockchain address connected to the account, but you can also connect as many addresses as you want. It is preferable for users of your application to be able to view the list of connected addresses. You can obtain them using the off-chain method Get all deposit addresses.
JavaScript
cURL
1
import { getDepositAddressesForAccount } from '@tatumio/tatum';
2
/**
3
* Get all deposit addresses generated for account.
4
* @param id - account ID
5
* @returns addresses detail - -
6
https://tatum.io/apidoc#operation/getAllDepositAddresses
7
*/
8
const addresses = getDepositAddressesForAccount ("5fb7bdf6e96d9ab593e191a5");
Copied!
1
curl --location --request GET 'https://api-eu1.tatum.io/v3/offchain/account/5fb7bdf6e96d9ab593e191a5/address' \
2
--header 'x-api-key: YOUR_API_KEY'
Copied!
The response will contain a list of all deposit addresses connected to the virtual account.
Response
1
[
2
{
3
"xpub": "tpubDE8GQ9vAXpwkp37PCCRUpCoeShpC4WiCcACxh8r3nnKjfRPRqw3w58EgkfNiBy1MaRqX1oAAxwAxauEUG7vWupSh5m15znGy7vE7aE6CWzb",
4
"derivationKey": 1,
5
"address": "mgSXLa5sJHvBpYTKZ62aW9z2YWQNTJ59Zm",
6
"currency": "BTC"
7
}
8
]
Copied!
And that's it. You've successfully created a virtual account and connected a blockchain address to it. With this simple operation, you have activated the automatic synchronization from the blockchain to the virtual account. Anytime you send a blockchain transaction to this address, it will be synced and visible in the account.
Last modified 20d ago