# /docs/system

import RunExample from '@/components/RunExample'

# 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.

<RunExample id="get-health" />

### `getFeatures` — full device info

<RunExample id="get-features" />

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

<RunExample id="list-devices" />

## Device management

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

### `applySettings` — rename, change passphrase, change auto-lock

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

### `changePin` — set or change the PIN

```ts
// 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

```ts
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

```ts
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

```ts
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

```ts
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:

```ts
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):

```ts
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.