btcDeriveContextHash

Derive a 32-byte Babylon context hash on the device for the selected Bitcoin key, application, context and network. The response contains a sensitive secret for your application to use.

Available in SDK 1.2.8-alpha.6. Requires Classic 1s or Classic 1s Pure firmware 3.21.0 or later and Protocol V1. Other device families and Protocol V2 are not supported.


const result = await HardwareSDK.btcDeriveContextHash(connectId, deviceId, params);

01 Prepare context02 Confirm on device03 Use the secret

Before you call

Initialize the SDK and select a device.
Register UI event handlers and explicitly select the intended wallet session.
Obtain user approval for the requesting application and its origin before calling. appName is caller-supplied; your application must establish which site or application is requesting access.

Params

connectIdstringrequired

The connection identifier returned by device discovery.

deviceIdstringrequired

The wallet identity returned by getDeviceState or openWalletSession.

params.pathstring | number[]required

BIP32 path of the connected Bitcoin key, with at least 3 components. Script type is inferred from the path. Use the connected key’s path, not the internal IKM derivation path.

params.appNamestringrequired

1–64 ASCII characters matching [a-z0-9-].

params.contextstringrequired

Lowercase, even-length hex without a 0x prefix, representing 1–1024 bytes. Empty context is invalid. The SDK sends the decoded bytes to the device.

params.networkstringrequired

Exactly bitcoin-mainnet, bitcoin-testnet, bitcoin-signet or bitcoin-regtest. Testnet3 and testnet4 both use bitcoin-testnet. Network is not inferred from the path.

Optional common params

Example

This fragment assumes an initialized SDK and a selected standard wallet. Replace the sample path, appName, context and network with the values approved by your user. The context below is illustrative hex-encoded data.


const result = await HardwareSDK.btcDeriveContextHash(connectId, deviceId, {
  path: "m/84'/0'/0'/0/0",
  appName: 'babylon-example',
  context: '48656c6c6f',
  network: 'bitcoin-mainnet',
  useEmptyPassphrase: true,
});
 
if (result.success === false) throw new Error(result.payload.error);
const secret = result.payload.secret;
// Use only for the approved application and context. Do not log or persist it.

The example explicitly selects the standard wallet with useEmptyPassphrase: true. For a hidden wallet, pass the same passphraseState used when confirming the connected Bitcoin account. The normal PIN, passphrase and device-confirmation flow still applies.

Response

Check success before reading the payload. On success, payload.secret is a 64-character lowercase hex string (32 bytes). The tabs below show response types, not real secret values.

Success


type SuccessResponse = {
  success: true;
  payload: {
    secret: string; // 64 lowercase hexadecimal characters (32 bytes)
  };
};

Errors and secret handling

Invalid path, appName, context or network returns CallMethodInvalidParameter (405) before the derivation command is sent. Unsupported device families or Protocol V2 return DeviceNotSupportMethod (415); firmware below 3.21.0 requires an upgrade.

Device cancellation returns the standard success: false response. Stop the request and handle payload.error and payload.code before attempting another call.

The SDK returns the actual secret to your application. Treat it as sensitive: keep it out of logs, telemetry, the clipboard and persistent storage. Derivation runs on the device; the internal wallet key is not exported.