Create new subscription

POST {{baseUrl}}/v3/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:

  • ACCOUNTINCOMINGBLOCKCHAINTRANSACTION - Enable HTTP POST JSON notifications on incoming blockchain transactions on off-chain accounts. This web hook will be invoked, when the transaction is credited to the ledger account. Transaction is credited, when it has sufficient amount of blockchain confirmations. For BTC, LTC, BCH, DOGE - 1 confirmation, ETH, ERC20 tokens, XLM, XRP, BNB - 1 confirmation. Request body of the POST request will be JSON object with attributes:
    {
      date: 1619176527481,
      amount: 0.005,
      currency: BTC,
      id: 6082ab462936b4478117c6a0,
      txId: 45af182a0ffab58e5ba32fee57b297b2260c6e23a1de5ddc76c7ee22d72dea99,
      blockHash: 45af182a0ffab58e5ba32fee57b297b2260c6e23a1de5ddc76c7ee22d72dea99, // hash of the block, might not be present all the time
      blockHeight: 12345,
      from: "SENDERADDRESS, // might not ebe present all the time, for UTXO based blockchains it's not there
    to:RECIPIENTADDRESSCONNECTEDTOLEDGERACCOUNT" // blockchain address of the recipient
    }
    1 credit will be debited for every monitored account every day.
  • ACCOUNTPENDINGBLOCKCHAINTRANSACTION - Enable HTTP POST JSON notifications on incoming blockchain transactions on off-chain accounts. This web hook will be invoked, when the transaction appears for the first time in the block, but is stil 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,
      id: 6082ab462936b4478117c6a0,
      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
    }
    1 credit will be debited for every monitored account every day.
  • CUSTOMERTRADEMATCH - 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.
  • TRANSACTIONINTHEBLOCK - 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.
  • KMSFAILEDTX - 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 messagefrom the KMS
    }
    10 credits will be debited every day.
  • OFFCHAINWITHDRAWAL - 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. 5 credits will be debited for every address registered for scanning every day.
  • ACCOUNTBALANCELIMIT - Report with all account balances above desired limit.
  • TRANSACTIONHISTORYREPORT - 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.79259, 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.
Result of the operation is subscription ID, which can be used to cancel subscription or obtain additional data connected to it like reports.

Request Body

{"type"=>"ACCOUNT_INCOMING_BLOCKCHAIN_TRANSACTION", "attr"=>{"id"=>"5e6be8e9e6aa436299950c41", "url"=>"https://webhook.tatum.io/account"}}

HEADERS

KeyDatatypeRequiredDescription
Content-Typestring

RESPONSES

status: OK

{"id":"5e68c66581f2ee32bc354087"}