How to work with Tatum-KMS

3 min readFeb 5, 2022

We are going to learn how to use Tatum KMS. It is recommended not to call Tatum API with private keys or mnemonic, only signatures id!

In this tutorial we’ll work with Bitcoin testnet.

1. Generate a mnemonic wallet

tatum-kms --path=wallet.dat --testnet generatemanagedwallet BTC{
  "xxx-59be-4792-81c5-yyy": {
    "mnemonic": "list of long words",
    "xpub": "tpubBCDEF",
    "chain": "BTC",
    "testnet": true
  }
}

2. Create the private key

Now generate a new private key for our wallet from step 1.

tatum-kms --path=wallet.dat --testnet getprivatekey xxx-59be-4792–81c5-yyy 0{
  "privateKey": "XXXNAV3tX3vWPG4uThixuqdYYY"
}

3. Create the address from the private key

Generate a new address from the private key from step 2. You can use that address to receive Bitcoins.

tatum-kms --path=wallet.dat --testnet getaddress xxx-59be-4792–81c5-yyy 0{
  "address": "AAAA3JPvMuwgpKovMTjBBB"
}

4. Store private key to the wallet

tatum-kms --path=wallet.dat --testnet storemanagedprivatekey BTCEnter private key to store:XXXNAV3tX3vWPG4uThixuqdYYY -> (this is private key from step 2)
Enter password to access wallet store:******{
  "signatureId": "QQQ-4b41-4ec9-b66c-WWW"
}

Now my wallet looks like this:

tatum-kms --path=wallet.dat --testnet export 
Enter the password to access wallet store:******{
  "QQQ-4b41-4ec9-b66c-WWW": {
    "privateKey": "XXXNAV3tX3vWPG4uThixuqdYYY",
    "chain": "BTC",
    "testnet": true
  },
  "xxx-59be-4792-81c5-yyy": {
    "mnemonic": "list of long words",
    "xpub": "tpubBCDEF",
    "chain": "BTC",
    "testnet": true
  }
}

5. Send some test BTC to your new address

For example, I use https://play.google.com/store/apps/details?id=de.schildbach.wallet_test to handle testnet Bitcoins, like sending and receiving.

Your new address from step 3 is: AAAA3JPvMuwgpKovMTjBBB

6. Make a transaction

Now you can send bitcoins from your address to any other address- You can follow the tutorial from here https://docs.tatum.io/tutorials/how-to-securely-store-private-keys#send-a-bitcoin-transaction but I’ll show you here how to do it

6.a. Send API request to Tatum to make a transaction

curl --location --request POST 'https://api-eu1.tatum.io/v3/bitcoin/transaction' \
--header 'x-api-key: your-tesnet-api-key-from-tatum' \
--header 'Content-Type: application/json' \
--data-raw '{
    "fromAddress": [
        {
            "address": "AAAA3JPvMuwgpKovMTjBBB", -> FROM STEP 3
            "signatureId": "QQQ-4b41-4ec9-b66c-WWW" -> FROM STEP 4
        }
    ],
    "to": [
        {
            "address": "any-existing-testnet-bitcoin-address",
            "value": 0.00001 -> AMOUNT OF BTC TO SEND
        }
    ]
}'

6.b. Run Tatum-KMS in daemon mode

Daemon mode is basically background mode, Tatum-KMS will work in the background and listen to the pending transaction

tatum-kms daemon --path=wallet.dat --testnet --chain=BTC --api-key=your-testnet-api-key --period=10

Tatum KMS will pick up pending transactions from step 6.a. and it will output something like:

Processing pending transaction - {
"withdrawalId": null,
"chain": "BTC",
"serializedTransaction": "{\"hash\":\"81e62bdfbfc7bcb66c2a2f17335d033fd98b84c1188a7bb379a2dce9f1cda989\",\"version\":2,\"inputs\":[{\"prevTxId\":\"121702fd7acd1b2cca6bd19658009140730ba26ca67cd222c00f952a111e11f4\",\"outputIndex\":0,\"sequenceNumber\":4294967295,\"script\":\"\",\"scriptString\":\"\",\"output\":{\"satoshis\":2000,\"script\":\"76a914c8e668ee829837a2355c1e234a41f53f86b8156c88ac\"}}],\"outputs\":[{\"satoshis\":1000,\"script\":\"001487c70889f0a1d2f632d216a01472dde71f062aa7\"}],\"nLockTime\":0}",
"hashes": [
"b8eb99cd-ba04-4031-a65f-11d6420ebdd1"
],
"index": null,
"withdrawalResponses": null,
"id": "61fe7c68cf2fbc595cbb89dd"
}.

6.c. Get transaction details

Note that “61fe7c68cf2fbc595cbb89dd” below is the same one from output in 6.b. under key “id”.

curl --request GET \
  --url https://api-eu1.tatum.io/v3/kms/61fe7c68cf2fbc595cbb89dd \
  --header 'x-api-key: your-testnet-api-key-from-tatum'

It will output something like

{
  "withdrawalId": null,
  "chain": "BTC",
  "serializedTransaction": "{\"hash\":\"81e62bdfbfc7bcb66c2a2f17335d033fd98b84c1188a7bb379a2dce9f1cda989\",\"version\":2,\"inputs\":[{\"prevTxId\":\"121702fd7acd1b2cca6bd19658009140730ba26ca67cd222c00f952a111e11f4\",\"outputIndex\":0,\"sequenceNumber\":4294967295,\"script\":\"\",\"scriptString\":\"\",\"output\":{\"satoshis\":2000,\"script\":\"76a914c8e668ee829837a2355c1e234a41f53f86b8156c88ac\"}}],\"outputs\":[{\"satoshis\":1000,\"script\":\"001487c70889f0a1d2f632d216a01472dde71f062aa7\"}],\"nLockTime\":0}",
  "hashes": [
    "b8eb99cd-ba04-4031-a65f-11d6420ebdd1"
  ],
  "index": null,
  "withdrawalResponses": null,
  "txId": "f7572ef070d381612b7594940cc73ec008e796b37a73ff031f3855d2a23c9ade",
  "id": "61fe7c68cf2fbc595cbb89dd"
}

So you see there is txId: f7572ef070d381612b7594940cc73ec008e796b37a73ff031f3855d2a23c9ade and you can track it like this https://live.blockcypher.com/btc-testnet/tx/f7572ef070d381612b7594940cc73ec008e796b37a73ff031f3855d2a23c9ade/

6.d. Other Tatum KMS API calls

You can find other API calls like the one from 6.c. here https://tatum.io/apidoc.php#operation/GetPendingTransactionsToSign

The end

That should be it. I hope you have a better understanding of how to use Tatum KMS.