Notification subscriptions

Endpoints to handle subscriptions to the Tatum Platform. Subscriptions allow users to enable some additional features or reports that are not enabled by default, like outgoing off-chain transaction scanning, accounts with balances above the limit, etc.

Create new subscription

2 credits for API call. Every type of subscription has different credit pricing.


Create new subscription as a HTTP Web Hook. Currently Tatum support multiple subscription types:

  • ADDRESS_TRANSACTION - Enable HTTP POST JSON notifications for any blockchain transactions at the specified address.
    This webhook will be sent when a transaction arrives to or is sent from the blockchain address specified in the call - this applies to both incoming/outgoing transactions in the native currency of the blockchain as well as any incoming/outgoing transactions for any type of token. Free community plans can monitor up to 10 addresses per plan.

    Please refer to the availability and consumption table below.
    Chain Testnet/Mainnet Token assets support Plan limitation Credit consumption / day / address
    Solana Yes/Yes SOL, SPL and NFTs Free plans - 10 addresses across all blockchains, Paid plans - unlimited addresses across all blockchains 50 credits / day / address
    Terra Luna Yes/Yes LUNA, KRW, USD and all other assets Free plans - 10 addresses across all blockchains, Paid plans - unlimited addresses across all blockchains 30 credits / day / address
    EOS Yes/Yes EOS and all other eosio.token assets Free plans - 10 addresses across all blockchains, Paid plans - unlimited addresses across all blockchains 40 credits / day / address
    Ethereum Yes/Yes ETH, Internal transfers, ERC20, ERC721, ERC1155 Free plans - 10 addresses across all blockchains, Paid plans - unlimited addresses across all blockchains 25 credits / day / address
    Polygon Yes/Yes MATIC, ERC20, ERC721, ERC1155 Free plans - 10 addresses across all blockchains, Paid plans - unlimited addresses across all blockchains 40 credits / day / address
    Celo Yes/Yes CELO, Internal transfers, ERC20, ERC721, ERC1155 Free plans - 10 addresses across all blockchains, Paid plans - unlimited addresses across all blockchains 25 credits / day / address
    Klaytn Yes/Yes Klay, ERC20, ERC721, ERC1155 Free plans - 10 addresses across all blockchains, Paid plans - unlimited addresses across all blockchains 25 credits / day / address
    Bitcoin Yes/Yes BTC Free plans - 10 addresses across all blockchains, Paid plans - unlimited addresses across all blockchains 20 credits / day / address
    Litecoin Yes/Yes LTC Free plans - 10 addresses across all blockchains, Paid plans - unlimited addresses across all blockchains 20 credits / day / address
    Bitcoin Cash Yes/Yes BCH, only incoming transactions Free plans - 10 addresses across all blockchains, Paid plans - unlimited addresses across all blockchains 20 credits / day / address
    Dogecoin Yes/Yes DOGE, only incoming transactions Free plans - 10 addresses across all blockchains, Paid plans - unlimited addresses across all blockchains 20 credits / day / address
    Tron Yes/Yes Tron, TRC10/TRC20 Free plans - 10 addresses across all blockchains, Paid plans - unlimited addresses across all blockchains 30 credits / day / address
    Binance Smart Chain Yes/Yes BSC, BEP20, ERC721, ERC1155 Free plans - 10 addresses across all blockchains, Paid plans - unlimited addresses across all blockchains 40 credits / day / address
    Lisk Yes/Yes LISK Free plans - 10 addresses across all blockchains, Paid plans - unlimited addresses across all blockchains 25 credits / day / address
    Request body of the POST request will be JSON object with attributes:
    {
      "address": "FykfMwA9WNShzPJbbb9DNXsfgDgS3XZzWiFgrVXfWoPJ", // address on which the transaction occurs. For EVM chains, this is recipient address
      "txId": "2rdy3YCZHSwvpWtuDom1d4Jjy5UU9STLxF3ffXau6GToReDkfw8wEgX541fvzvh6btVC5D8iNapcKTXfPsoDBk7A", // transaction id
      "blockNumber": 110827114, // block number
      "asset": "3gUeeR3BfVhukYJMwtHownRtRkGcf1bvwiV8TbKMZBVz", // Asset of transaction, for token assets it is address of that token, for native name of the native asset like SOL
      "amount": "1", // amount of the asset that was credited (+) or debited (-) from the address. In case of EVM chains, amount is always positive when counterAddress is present
      "tokenId": "1", // ID of the transferred token, if it is ERC721 / ERC1155
      "type": "token", // type of transaction, could be 'native' or 'token'
      "counterAddress": undefined // optional counter party address of the transaction. For EVM chains, this is recipient address
    }
    5 credits will be debited for every fired webhook.
  • ACCOUNT_INCOMING_BLOCKCHAIN_TRANSACTION - Enable HTTP POST JSON notifications on incoming blockchain transactions on virtual accounts. This web hook will be invoked, when the transaction is credited to the virtual account. Transaction is credited, when it has sufficient amount of blockchain confirmations. For BTC, LTC, BCH, DOGE - 2 confirmations, others - 1 confirmation. Request body of the POST request will be JSON object with attributes:
    {
      "date": 1619176527481,
      "amount": "0.005",
      "currency": "BTC",
      "accountId": "6082ab462936b4478117c6a0",
      "reference: "c9875708-4ba3-41c9-a4cd-271048b41b9a", // ledger transaction reference
      "txId": "45af182a0ffab58e5ba32fee57b297b2260c6e23a1de5ddc76c7ee22d72dea99",
      "blockHash": "45af182a0ffab58e5ba32fee57b297b2260c6e23a1de5ddc76c7ee22d72dea99", // hash of the block, might not be present all the time
      "blockHeight": 12345,
      "from": "SENDER_ADDRESS", // might not ebe present all the time, for UTXO based blockchains it's not there
      "to": "RECIPIENT_ADDRESS_CONNECTED_TO_LEDGER_ACCOUNT", // blockchain address of the recipient
      "index": 5 // for UTXO based chains (BTC,LTC,DOGE,BCH,ADA) this is the index of the output in the transaction
    }
    1 credit will be debited for every monitored account every day.
  • ACCOUNT_PENDING_BLOCKCHAIN_TRANSACTION - Enable HTTP POST JSON notifications on incoming blockchain transactions on virtual accounts. This web hook will be invoked, when the transaction appears for the first time in the block - it has 1 confirmation, but is still not credited to the ledger account, because it does not have enough confirmations. This web hook is invoked only for BTC, LTC, DOGE and BCH accounts. Request body of the POST request will be JSON object with attributes:
    {
      "date": 1619176527481,
      "amount": "0.005",
      "currency": "BTC",
      "accountId": "6082ab462936b4478117c6a0",
      "reference: "c9875708-4ba3-41c9-a4cd-271048b41b9a", // ledger transaction reference
      "txId": "45af182a0ffab58e5ba32fee57b297b2260c6e23a1de5ddc76c7ee22d72dea99",
      "blockHash": "45af182a0ffab58e5ba32fee57b297b2260c6e23a1de5ddc76c7ee22d72dea99", // hash of the block, might not be present all the time
      "blockHeight": 12345,
      "from": "SENDER_ADDRESS", // might not ebe present all the time, for UTXO based blockchains it's not there
      "to": "RECIPIENT_ADDRESS_CONNECTED_TO_LEDGER_ACCOUNT", // blockchain address of the recipient
      "index": 5 // for UTXO based chains (BTC,LTC,DOGE,BCH,ADA) this is the index of the output in the transaction
    }
    1 credit will be debited for every monitored account every day.
  • CUSTOMER_TRADE_MATCH - Enable HTTP POST JSON notifications on closed trade, which occurs on any customer account. This web hook will be invoked, when the open trade is filled and closed. Works also for the Trade Futures. If is triggered by the futures, bool field expiredWithoutMatch is present. Request body of the POST request will be JSON object with attributes:
    {
      "created": 1619176527481,
      "amount": "0.005",
      "price": "0.02",
      "type": "SELL",
      "pair": "VC_CHF/VC_CHF3",
      "id": "6082ab462936b4478117c6a0", // id of the trade
      "currency1AccountId": "6082ab462936b4478117c6a0",
      "currency2AccountId": "6082ab512936b4478117c6a2",
      "fee": null,
      "feeAccountId": null,
      "isMaker": true,
      "expiredWithoutMatch": false
    }
    10 credits will be debited for every monitored customer every day.
  • CUSTOMER_PARTIAL_TRADE_MATCH - Enable HTTP POST JSON notifications on partialy filled trade, which occurs on any customer account. This web hook will be invoked, when the open trade is partialy filled. Request body of the POST request will be JSON object with attributes:
    {
      "created": 1619176527481,
      "amount": "0.005",
      "price": "0.02",
      "type": "SELL",
      "pair": "VC_CHF/VC_CHF3",
      "id": "6082ab462936b4478117c6a0", // id of the trade
      "currency1AccountId": "6082ab462936b4478117c6a0",
      "currency2AccountId": "6082ab512936b4478117c6a2",
      "fee": null,
      "feeAccountId": null,
      "isMaker": true,
      "expiredWithoutMatch": false
    }
    10 credits will be debited for every monitored customer every day.
  • TRANSACTION_IN_THE_BLOCK - Enable HTTP POST JSON notifications on ledger => blockchain transaction, when transaction is included in the block. This web hook will be invoked, when the outgoing transaction is included in the block. Request body of the POST request will be JSON object with attributes:
      {
        "txId": "0x026f4f05b972c09279111da13dfd20d8df04eff436d7f604cd97b9ffaa690567",
        "reference": "90270634-5b07-4fad-b17b-f82899953533",
        "accountId": "6086ed0744c45b24d4fbd039",
        "currency": "BSC",
        "withdrawalId": "608fe5b73a893234ba379ab2",
        "address": "0x8ce4e40889a13971681391AAd29E88eFAF91f784",
        "amount": "0.1",
        "blockHeight": 8517664
      }
    10 credits will be debited every day, 1 credit for every included transaction notified via web hook.
  • KMS_FAILED_TX - Enable HTTP POST JSON notifications on error during KMS signature process. This web hook will be invoked, when the Tatum KMS receives error during processing transactions. Request body of the POST request will be JSON object with attributes:
    {
      "signatureId": "6082ab462936b4478117c6a0",
      "error": "Error message from the KMS"
    }
    10 credits will be debited every day.
  • KMS_COMPLETED_TX - Enable HTTP POST JSON notifications on successful completion of KMS signature process. This web hook will be invoked, when the Tatum KMS sudessfully completes the signature during processing transactions. Request body of the POST request will be JSON object with attributes:
    {
      "signatureId": "6082ab462936b4478117c6a0",
      "txId": "0x7bb7d3b90567e89f999f2e3d263bc3738a018dbbcfa9f5397678cf17cdf0235f"
    }
    10 credits will be debited every day.
  • OFFCHAIN_WITHDRAWAL - Off-chain scanning of outgoing transactions for BTC, BCH, LTC, DOGE and ETH blockchains - by default addresses in registered for off-chain scanning are synchronized only against incoming transactions. By enabling this feature, off-chain accounts with connected blockchain addresses will be scanned also for outgoing transactions. This transaction wil be recorder to the ledger and account balance will be decreased - don't use it if you perform your own transactions from the account to the blockchain.
    20 credits will be debited for every address registered for scanning every day.
  • ACCOUNT_BALANCE_LIMIT - Report with all account balances above desired limit.
  • TRANSACTION_HISTORY_REPORT - Report with all ledger transactions for last X hours, where X is set by the subscription attribute as interval. Maximum number of transactions returned by this report is 20000. Transactions are obtained from the time of the invocation of the GET method to obtain report - X hours.
In case of unsuccesful web hook response status - other then 2xx - web hook is repeated 9 more times with exponential backoff. Parameters are T = 15 * 2.7925^9, where 15 is interval in s, backoff rate is 2.7925 and 9 is current number of retries. Last web hook is fired after 24 hours approximatelly. After last failed attempt, web hook is deleted from our system. The 2xx response must be returned in 10 seconds after web hook is fired.
Result of the operation is subscription ID, which can be used to cancel subscription or obtain additional data connected to it like reports.

SecurityX-API-Key
Request
Request Body schema: application/json
One of:
type
required
string

Type of the subscription.

Value: "ADDRESS_TRANSACTION"
required
object

Additional attributes based on the subscription type.

address
required
string [ 13 .. 128 ] characters

Blockchain address to watch.

chain
required
string

Blockchain of the address.

Enum: "SOL" "BTC" "LTC" "DOGE" "ETH" "MATIC" "KLAY" "LUNA" "CELO" "BCH" "EOS"
url
required
string <= 500 characters

URL of the endpoint, where HTTP POST request will be sent, when transaction is detected on the address.

Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

403

Forbidden. The request is authenticated, but it is not possible to required perform operation due to logical error or invalid permissions.

500

Internal server error. There was an error on the server while processing the request.

post/v3/subscription
Request samples
application/json
{}
Response samples
application/json
{
  • "id": "5e68c66581f2ee32bc354087"
}

List all active subscriptions

1 credit per API call.


List all active subscriptions.

SecurityX-API-Key
Request
query Parameters
pageSize
required
number [ 1 .. 50 ]

Max number of items per page is 50.

Example: pageSize=10
offset
number

Offset to obtain next page of the data.

Example: offset=0
address
string

Value for filtering by address

Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

500

Internal server error. There was an error on the server while processing the request.

get/v3/subscription
Request samples
curl -i -X GET \
  'https://api-eu1.tatum.io/v3/subscription?pageSize=10&offset=0&address=string' \
  -H 'x-api-key: YOUR_API_KEY_HERE'
Response samples
application/json
[
  • {
    }
]

Enable HMAC webhook digest

2 credits per API call.


Enable HMAC hash ID on the fired webhooks from Tatum API. In order to make sure that a webhook is sent by us, we have the possibility to sign it with the HMAC Sha512 Hex algorithm.
To verify that a webhook is sent by us

  1. Get a webhook x-payload-hash header value and payload as it is as a JSON file.
  2. Convert the HTTP webhook body to stringify JSON without any spaces. In JavaScript, you would do it like this
    JSON.stringify(req.body)
  3. Perform calculations on your side to create a digest using Secret Key, webhook payload in bytes and HMAC SHA512 algorithm. JavaScript example:
    require('crypto').createHmac('sha512', hmacSecret).update(JSON.stringify(req.body)).digest('base64')
    .
  4. Compare x-payload-hash header value with calculated digest as a Base64 string.
SecurityX-API-Key
Request
Request Body schema: application/json
hmacSecret
string <= 100 characters

Your HMAC secret password, which is used for signing the webhook payload.

Responses
204

OK

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

500

Internal server error. There was an error on the server while processing the request.

put/v3/subscription
Request samples
application/json
{
  • "hmacSecret": "1f7f7c0c-3906-4aa1-9dfe-4b67c43918f6"
}
Response samples
application/json
{
  • "errorCode": "subscription.not.active",
  • "message": "Subscription not active anymore.",
  • "statusCode": 401
}

Disable HMAC webhook digest

2 credits per API call.


Disable HMAC hash ID on the fired webhooks from Tatum API.

SecurityX-API-Key
Responses
204

OK

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

500

Internal server error. There was an error on the server while processing the request.

delete/v3/subscription
Request samples
curl -i -X DELETE \
  https://api-eu1.tatum.io/v3/subscription \
  -H 'x-api-key: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "errorCode": "subscription.not.active",
  • "message": "Subscription not active anymore.",
  • "statusCode": 401
}

Count of found entities for get webhook request

1 credit per API call.


Count of subscriptions that were found from /v3/subscription

SecurityX-API-Key
Request
query Parameters
pageSize
required
number [ 1 .. 50 ]

Max number of items per page is 50.

Example: pageSize=10
offset
number

Offset to obtain next page of the data.

Example: offset=0
address
string

Value for filtering by address

Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

500

Internal server error. There was an error on the server while processing the request.

get/v3/subscription/count
Request samples
curl -i -X GET \
  'https://api-eu1.tatum.io/v3/subscription/count?pageSize=10&offset=0&address=string' \
  -H 'x-api-key: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "total": 20
}

Cancel existing subscription

1 credit for API call


Cancel existing subscription.

SecurityX-API-Key
Request
path Parameters
id
required
string

Subscription ID

Example: 5e68c66581f2ee32bc354087
Responses
204

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

500

Internal server error. There was an error on the server while processing the request.

delete/v3/subscription/{id}
Request samples
curl -i -X DELETE \
  'https://api-eu1.tatum.io/v3/subscription/{id}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "errorCode": "validation.failed",
  • "message": "Request validation failed. Please see data for additional information.",
  • "statusCode": 400,
  • "data": [
    ]
}

Obtain report for subscription

1 credit for API call. Based on the required report type, additional credits may be charged.


Obtain report from subscription based on its type. Following reports are supported:

  • ACCOUNT_BALANCE_LIMIT - obtain list of all ledger accounts with account balance above the limit. 1 credit per 50 returned records is charged.
  • TRANSACTION_HISTORY_REPORT - obtain list of all ledger transaction for last X hours from the time of invocation. 1 credit per 50 returned records is charged.

SecurityX-API-Key
Request
path Parameters
id
required
string

Subscription ID

Example: 5e68c66581f2ee32bc354087
Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

403

Forbidden. The request is authenticated, but it is not possible to required perform operation due to logical error or invalid permissions.

500

Internal server error. There was an error on the server while processing the request.

get/v3/subscription/report/{id}
Request samples
curl -i -X GET \
  'https://api-eu1.tatum.io/v3/subscription/report/{id}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'
Response samples
application/json
[ ]

List all executed webhooks

1 credit per API call.


List all webhooks.

SecurityX-API-Key
Request
query Parameters
pageSize
required
number [ 1 .. 50 ]

Max number of items per page is 50.

Example: pageSize=10
offset
number

Offset to obtain the next page of data.

Example: offset=0
direction
string

Direction of sorting

Enum: "asc" "desc"
Example: direction=asc
failed
boolean

Flag indicating whether the webhook was successful or not

Example: failed=false
Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

500

Internal server error. There was an error on the server while processing the request.

get/v3/subscription/webhook
Request samples
curl -i -X GET \
  'https://api-eu1.tatum.io/v3/subscription/webhook?pageSize=10&offset=0&direction=asc&failed=false' \
  -H 'x-api-key: YOUR_API_KEY_HERE'
Response samples
application/json
[
  • {
    }
]

Count of found entities for get webhook request

1 credit per API call.


Count of webhooks that were found from /v3/subscription/webhook

SecurityX-API-Key
Request
query Parameters
pageSize
required
number [ 1 .. 50 ]

Max number of items per page is 50.

Example: pageSize=10
offset
number

Offset to obtain the next page of data.

Example: offset=0
direction
string

Direction of sorting

Enum: "asc" "desc"
Example: direction=asc
failed
boolean

Flag indicating whether the webhook was successful or not

Example: failed=false
Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

500

Internal server error. There was an error on the server while processing the request.

get/v3/subscription/webhook/count
Request samples
curl -i -X GET \
  'https://api-eu1.tatum.io/v3/subscription/webhook/count?pageSize=10&offset=0&direction=asc&failed=false' \
  -H 'x-api-key: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "total": 20
}