Guides
SupportStatusSign UpLogin

KMS General FAQ

Suggest Edits

Running Multiple KMS Instances

Q: We are setting up development and pre-production configuration on a single server. Can we start KMS twice with separate paths?

Example:

tatum-kms daemon --path=/path/to/wallet/store/directory/wallet.dat

# Running KMS for Development:
docker run -d --env-file .env -v $HOME:/root/.tatumrc tatumio/tatum-kms daemon --period 10 --chain=MATIC --testnet

# Running KMS for Pre-production:
docker run -d --env-file .env-pre-prod -v $HOME:/root/.tatumrc tatumio/tatum-kms daemon --period 10 --chain=MATIC --external-url={{URL}}

A: Yes, with caveats.

  • You must use different .env files (.env for dev and .env-pre-prod for pre-production).
  • Each instance must have a unique wallet.dat file (e.g., wallet-dev.dat and wallet-preProd.dat).
  • Each instance should have its own API key to avoid conflicts.
  • Use the --path parameter to explicitly separate wallet storage per environment.
  • Refer to the KMS repository for details: Tatum KMS GitHub.

Four-Eyes Principle in KMS Daemon

Q: Can you give an example of the four-eyes principle in KMS Daemon? What parameters should we set and how should we do this?
A: This is implemented via an additional API call where you validate whether a transaction should be signed. You can use a REST API listener to enforce this check before signing occurs.

📘

Note

Find additional information about the 4 eye principle and Mainnet errors in this article.

Storage and Backup

Q: Where are the private keys stored?
A: Inside wallet.dat file - encrypted in JSON file in KMS-specific format

Q: If we generate several wallets does it create several [wallet.dat]?
A: No. All wallets are in one wallet.dat file

Q: Can we restore a Tatum wallet on a different server using backup wallet.dat and password?
A: Yes, as long as you have the encrypted wallet.dat file and the correct password.

📘

Note

High Availability & Failover

Q: Can we run two KMS setups in "daemon mode" from two isolated servers, but with the same [wallet.dat] file to have high availability and failover?
A: Yes, but ensure that both KMS instances do not attempt to write to the same wallet.dat file simultaneously to avoid corruption.

Security & Password Management

Q: Can the KMS password be changed?
A: No, password changes are not currently supported.

KMS with AWS

Q: How can I set up KMS with AWS?

A: Configure AWS access credentials using: TATUM_KMS_AWS_ACCESS_KEY_ID and TATUM_KMS_AWS_SECRET_ACCESS_KEY

Mnemonic Recovery & Transactions

Q: If we generate new mnemonic phrases in KMS, do previously generated mnemonics remain valid?

A: Yes, previously generated mnemonics remain valid and can still be used.

Q: I am getting an Error 403: "Unable to broadcast transaction", with "16: mandatory-script-verify-flag-failed...". What’s wrong?

A: Verify that the signature ID is correct:

  • For BTC-based chains, use a key-based signature ID instead of a mnemonic-based one.

Azure Key Vault Integration

Q: How can I make KMS work inside a Linux container while accessing an Azure Key Vault for password retrieval?

A: Follow the implementation details at: Tatum KMS GitHub. Look for: 

if (flags.azure) { ... }

Blockchain-Specific Questions

Q: How do I use TRON (TRX) and TRC tokens with KMS?
A: Use TRON for all TRX and TRC20 token transfers. The blockchain supports both TRC-10 and TRC-20 tokens natively.

Q: I sent a transaction with incorrect data. Every time KMS runs, it keeps trying to execute and fails. What can I do?
A: Delete the unsuccessful transaction via this endpoint.

📘

Note

Find more about Tron and common KMS errors in this article.

Language & API Compatibility

Q: I want to work with KMS on PHP. Is that possible?
A: Yes. Start KMS in Docker mode on a server and then you can the Tatum API in any language like PHP to do the transfers.

Gas Pump & Fees

Q: How do I link KMS tx signature with Gas Pump?
A: Check the following article.

Q: What is the cost for each KMS signature withdrawal?
A: 4 credits per transaction:

  • 2 credits per signature request
  • 2 credits for broadcasting

Exporting Wallet Data

Q: How can I export to file the wallet?
A: Run the following command:

tatum-kms export --path=/pathtodirectory/wallet.dat

Updated 17 days ago