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 private ledger and the accounts created there, 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 account in the private ledger must have a defined currency. 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 ledger.

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.

Request
Response
Request
curl --location --request POST 'https://api-eu1.tatum.io/v3/ledger/account' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"currency": "BTC",
"xpub": "tpubDE8GQ9vAXpwkp37PCCRUpCoeShpC4WiCcACxh8r3nnKjfRPRqw3w58EgkfNiBy1MaRqX1oAAxwAxauEUG7vWupSh5m15znGy7vE7aE6CWzb"
}'
Response
{
"currency": "BTC",
"active": true,
"balance": {
"accountBalance": "0",
"availableBalance": "0"
},
"frozen": false,
"xpub": "tpubDE8GQ9vAXpwkp37PCCRUpCoeShpC4WiCcACxh8r3nnKjfRPRqw3w58EgkfNiBy1MaRqX1oAAxwAxauEUG7vWupSh5m15znGy7vE7aE6CWzb",
"accountingCurrency": "EUR",
"id": "5fb7bdf6e96d9ab593e191a5"
}

Generating a blockchain address and connecting it to the ledger account

When the account has been created, it is not yet synchronized with the blockchain. There is no blockchain address connected to it, 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 this off-chain method: Generate address for the account.

Request
Response
Request
curl --location --request POST 'https://api-eu1.tatum.io/v3/offchain/account/5fb7bdf6e96d9ab593e191a5/address' \
--header 'x-api-key: YOUR_API_KEY'
Response
{
"xpub": "tpubDE8GQ9vAXpwkp37PCCRUpCoeShpC4WiCcACxh8r3nnKjfRPRqw3w58EgkfNiBy1MaRqX1oAAxwAxauEUG7vWupSh5m15znGy7vE7aE6CWzb",
"derivationKey": 1,
"address": "mgSXLa5sJHvBpYTKZ62aW9z2YWQNTJ59Zm",
"currency": "BTC"
}

The result is a blockchain address has been connected to the ledger account. Any incoming blockchain transaction to this address will be automatically synchronized to the private ledger.

It is possible to enable webhook notifications for every incoming transaction to the ledger 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.

Request
Response
Request
curl --location --request GET 'https://api-eu1.tatum.io/v3/offchain/account/5fb7bdf6e96d9ab593e191a5/address' \
--header 'x-api-key: YOUR_API_KEY'
Response
[
{
"xpub": "tpubDE8GQ9vAXpwkp37PCCRUpCoeShpC4WiCcACxh8r3nnKjfRPRqw3w58EgkfNiBy1MaRqX1oAAxwAxauEUG7vWupSh5m15znGy7vE7aE6CWzb",
"derivationKey": 1,
"address": "mgSXLa5sJHvBpYTKZ62aW9z2YWQNTJ59Zm",
"currency": "BTC"
}
]

And that's it. You've successfully created an account and connected a blockchain address to it. With this simple operation, you have activated the automatic synchronization from the blockchain to the ledger. Anytime you send a blockchain transaction to this address, it will be synced and visible in the ledger.