Device & System

The sdk.system namespace covers everything about the device itself: reading its state, managing the PIN, and initializing or wiping it. All methods are grouped under sdk.system.info (read-only) and sdk.system.device (mutating).

Reading device state

getHealth — no auth required

The only call that works without pairing. Useful for detecting whether the desktop application is running at all.

const health = await sdk.system.info.getHealth()

getFeatures — full device info

const features = await sdk.system.info.getFeatures()

The returned DeviceFeatures object includes:

• model, firmware_variant, firmware_hash
• major_version, minor_version, patch_version
• device_id, label, language
• initialized, pin_protection, passphrase_protection, bootloader_mode
• pin_cached, passphrase_cached, wipe_code_protection
• auto_lock_delay_ms
• policies[] — named policy flags

getDevices — list connected devices

const { devices, total } = await sdk.system.info.getDevices()

Device management

These methods mutate device state and require user confirmation on the device.

applySettings — rename, change passphrase, change auto-lock

await sdk.system.device.applySettings({
  label: 'My KeepKey',
  use_passphrase: true,
  autolock_delay_ms: 300000, // 5 minutes
})

changePin — set or change the PIN

// Start a PIN change flow. User enters new PIN on device.
await sdk.system.device.changePin()
 
// Remove the PIN entirely (discouraged)
await sdk.system.device.changePin(true)

wipe — erase all secrets

await sdk.system.device.wipe()

Wipes the seed, PIN, and all settings. User must confirm on device. This is irreversible — make sure the user has their recovery phrase written down first.

resetDevice — initialize a new device

await sdk.system.device.resetDevice({
  word_count: 12, // or 18 or 24
  label: 'New Device',
  pin_protection: true,
  passphrase_protection: false,
})

The user writes down the seed shown on the device screen.

recoverDevice — restore from a seed phrase

await sdk.system.device.recoverDevice({
  word_count: 24,
  label: 'Restored Device',
  pin_protection: true,
})

The user enters each word on the device (cipher input for security).

clearSession — force re-entry of PIN

await sdk.system.device.clearSession()

Forces the user to re-enter their PIN on the next sensitive call. Useful for “logout” UIs in apps that pair once and run for hours.

Deriving public keys

Single path:

const { xpub } = await sdk.system.info.getPublicKey({
  address_n: [0x80000054, 0x80000000, 0x80000000], // m/84'/0'/0'
  coin_name: 'Bitcoin',
  script_type: 'p2wpkh',
})

Batch (preferred for portfolios):

const result = await sdk.xpub.getPublicKeys([
  { address_n: [0x80000054, 0x80000000, 0x80000000], coin: 'Bitcoin', script_type: 'p2wpkh' },
  { address_n: [0x8000002C, 0x8000003C, 0x80000000], coin: 'Ethereum', type: 'address' },
])

The server caches pubkey results, so repeated calls for the same path return instantly.