Authentication#
All of our API requests are authenticated by providing your API key in the headers.{
"x-api-key": "your-key-here"
}
Verifying Provenance#
In order to be sure that any public key returned from the API is the correct public key from the HSM Cluster, most queries will return a provenance signatures.Each wallet (HD wallet) allows you to create many public keys. e.g wallet A might have a sub-wallet for an EVM address. This EVM address has a public key. The public key is then used to create the on chain address.The point of verifying the provnance is to ensure the address is what you expect. E.g. Image you create a subwallet with address 0xdead. You may wish to send funds to your own address so you use the API to return your address and send funds to it. Image that someone hacks your network and changes that adress to 0xattack. You may then send funds to the wrong address.In order to protect from this each HSM is initialised with a provnance private key. This is a key that only the HSM Clusters contain. As such whenever the HSM creates a new public key it will sign the key (plus some other data) with the provnenace private key.If you use the shared use HSM Clusters the provnenace key can be seen below. If you use your own HSM you'll need to get in touch to understand how the process to extract the HSM provenance public key works.To do so API users will receive a signature over the encoding of some of the returned data (depends on the request)To verify API users will need to use TrustVault's public key for the environment and cluster the wallet is held in.NB: There are many clusters. Your cluster is returned in the WalletInfo section of the SubWallet query; speak to your account manager if you are unsure.Production Public Key#
uk-online-1: 041cbce9985c7627f67b60b65cd1921fc79cbbc5b38a8c5702579d9573dd3b90f4e8c189679f1911335fd753510706d66c9c76147b961b085e25e3742e02524b01Pre-production Public Key#
uk-online-1: 040e177769d4302f6cb0a1229d13d106ad9eb7ea53042bfb24cf4eb572ced1c13da2621b202cfd475e2847d6e380bd00b747a6dacf99381dc9e99bc567b4edf994These keys can also be found in our postman docs.You can verify our Production Public Key by querying the provenance-public-key.bitpandacustody.com dns TXT record.
This can be done using a command line tool like dig.dig provenance-public-key.bitpandacustody.com TXT
Verifying a provenance signature in code#
If you use the TrustVault Node.js SDK, createSubWallet checks the provenance signature for you. If you call the GraphQL API directly, you must check it yourself before you use a returned public key or address.The HSM signs a DER-encoded structure that contains the wallet ID, the HD path and the public key:TrustVaultPublicKeyProvenance ::= SEQUENCE {
walletId PrintableString, -- the wallet ID, e.g. "5d169161-...-17988eb391c5" (not the sub-wallet ID)
path SEQUENCE OF INTEGER, -- the HD path, e.g. ["0x8000002c", ...] as integers
publicKey OCTET STRING -- the 65-byte uncompressed public key (04-prefixed)
}
1.
DER-encode walletId, path and publicKey as shown above.
2.
Hash the encoded bytes with SHA-256.
3.
Verify trustVaultProvenanceSignature against the hash. The signature is 64 bytes, r followed by s, as hex. Use ECDSA on the P-256 (secp256r1) curve and the provenance public key for your environment and cluster.
4.
Only if the signature is valid, derive the address from the verified public key yourself. Use your chain's library, for example computeAddress in ethers.js for EVM chains. Check that the address matches unverifiedAddress, and never use unverifiedAddress directly.
crypto module (Node 16 or later):If the check returns false, do not use the public key or address. Contact Support.Safely Storing your Instruction Key#
Do not hard code your key in scripts or config files. We recommend you use products like AWS Key Management Service to safely manage your keys.Modified at 2026-10-29 12:46:11
