本页目录

通用参数

大多数链和设备方法接收 params 对象；初始化、事件与生命周期方法有各自的签名。本页是地址、签名、设备方法的共用字段，不是每个方法都能收：openWalletSession 只要看到 useEmptyPassphrase、initSession、deviceId、passphraseState（包括 false 或从共用 defaults 展开进来）就会返回 CallMethodInvalidParameter。各链 / 设备方法页面只写自己独有的字段（path、coin、tx、message 等）。

本页是参数参考。调用生命周期见 Core API Guide。响应里的 ID（connectId、deviceId、uuid、session_id 等）见标识符。

参数	类型	作用	说明
`passphraseState`	`string`	把这次调用绑定到某个隐藏钱包	通过 `openWalletSession`（或已废弃的 `getPassphraseState`）拿一次；后续要留在同一钱包的调用都带上。不能和 `useEmptyPassphrase` 同时传。这是钱包指纹，不是固件 `session_id`。
`useEmptyPassphrase`	`boolean`	强制走标准钱包	避免残留的隐藏钱包会话悄悄改掉地址。不能和 `passphraseState` 同时传。
`initSession`	`boolean`	调用前强制初始化 session	兼容路径上搭配 `passphraseState`。新代码应优先 `openWalletSession({ mode })`，不要把 `mode` 和这个标志混在一次调用里。
`deriveCardano`	`boolean`	在设备上预派生 Cardano 子树	一个 session 里第一次调 Cardano 方法时设为 `true`。
`retryCount`	`number`	建立连接的重试上限	Core 在连接/初始化阶段使用，不会重放已完成或失败的签名操作。
`pollIntervalTime`	`number`	连接重试的轮询间隔（毫秒）	在连接阶段配合 `retryCount` 使用。
`timeout`	`number`	单次连接尝试超时（毫秒）	不设置签名或固件传输的超时。
`detectBootloaderDevice`	`boolean`	设备处于 Bootloader 时立刻失败	用在签名路径上。
`skipWebDevicePrompt`	`boolean`	跳过 WebUSB 设备选择弹窗	仅 WebUSB，复用之前的授权。
`keepSession`	`boolean`	调用结束后继续持有传输	控制 `Device.run()` 是否 `release()` 链路。这不是钱包身份，也不能用 `passphraseState` / `openWalletSession` 替代。USB 连续签名 / 检查后升级、Electron BLE 固件窗口仍需要它。

各传输方式差异

参数	WebUSB	Bridge	node-usb	Android BLE	iOS BLE	Desktop BLE
`skipWebDevicePrompt`	✅	—	—	—	—	—
`retryCount` / `pollIntervalTime` / `timeout`	建立连接	建立连接	建立连接	建立连接	建立连接	建立连接
`passphraseState` / `useEmptyPassphrase` / `initSession`	✅	✅	✅	✅	✅	✅
`deriveCardano` / `detectBootloaderDevice`	✅	✅	✅	✅	✅	✅

常见组合

标准钱包 —— 避免误触发隐藏钱包


await HardwareSDK.evmGetAddress(connectId, deviceId, {
  path: "m/44'/60'/0'/0/0",
  useEmptyPassphrase: true,
});

隐藏钱包 —— 多次调用复用绑定


const opened = await HardwareSDK.openWalletSession(connectId, {
  mode: 'select-hidden',
});
if (!opened.success) throw new Error(opened.payload.error);
if (opened.payload.walletType !== 'hidden') {
  throw new Error('A hidden wallet was not opened');
}
const hiddenWallet = {
  passphraseState: opened.payload.passphraseState,
};
 
await HardwareSDK.evmGetAddress(connectId, opened.payload.deviceId, {
  path: "m/44'/60'/0'/0/0",
  ...hiddenWallet,
});

已废弃的兼容路径：getPassphraseState(connectId, { initSession: true })，之后每次带 { initSession: true, passphraseState }。见钱包会话。

BLE 保守重试（仅搜设备 / 地址 / 签名）


const bleDefaults = {
  retryCount: 3,
  pollIntervalTime: 1000,
  timeout: 30_000,
};

不要把 bleDefaults 铺到 firmwareUpdateV2 / V3 / V4 上。见断线与重连。

HD Path

方法文档中的最小路径长度是 SDK 输入校验，不代表该长度的任意路径都受支持。固件还会校验各链的派生与硬化规则。

path: string | number[]，遵循 BIP44。ed25519 链（Solana、NEAR 等）必须全硬化。

链	示例路径	说明
EVM	`m/44'/60'/0'/0/0`	标准 EVM
BTC（Nested SegWit）	`m/49'/0'/0'/0/0`	Native SegWit 用 `84'`
Solana	`m/44'/501'/0'/0'`	全硬化
NEAR	`m/44'/397'/0'/0'/1'`	全硬化
Cardano	`m/1852'/1815'/0'/0/0`	质押路径 `.../2/0`
TRON	`m/44'/195'/0'/0/0`	EVM 风格路径

数组示例：[(44 | 0x80000000) >>> 0, (0 | 0x80000000) >>> 0, 0x80000000, 0, 0]

遇到 forbidden path：按对应链文档检查长度和硬化标记。

Protocol V1 在关闭 passphrase 保护时，select-hidden 可能返回标准钱包。保存或使用 passphraseState 前先检查 walletType。