On this page
Hardware Control
A hardware-backed session uses a connected OneKey device for supported signing requests. The user reviews and confirms requests on the device. Device capabilities and transaction details available for review depend on the chain, firmware, and CLI version.
When To Escalate
| Flow | Hardware expectation |
|---|---|
| High-value transfer | User reviews recipient, amount, chain, and fee on the OneKey device. |
| Contract interaction | Agent runs simulation first, then the device displays clear-signing details when supported. |
| Swap execution | Agent quotes and builds first; device confirmation happens only after the user approves execution. |
| Hidden wallet | Passphrase mode is explicit so the agent does not guess whether a hidden wallet is active. |
| Device trust check | onekey device verify runs device verification. A successful check does not validate the safety of a transaction. |
Connect and Login
List connected devices:
onekey device searchAuthenticate with a hardware wallet:
onekey auth login --hardwareWhen multiple devices are connected, select one explicitly:
onekey auth login --hardware --device-id <uuid>Choose one passphrase mode for the intended wallet. These are alternatives, not a sequence:
| Mode | Wallet selection |
|---|---|
none | Standard wallet, with no passphrase. |
on-host | Hidden wallet, with passphrase entry on the host. Keep the passphrase out of agent messages and logs. |
on-device | Hidden wallet, with passphrase entry on a device that supports it. |
Inspect the installed CLI schema before selecting a mode. After login, verify the active address; a different passphrase selects a different wallet.
Active Session
Hardware-backed sessions are reported by onekey auth status as:
| Field | Expected value |
|---|---|
loginMethod | hardware |
walletKind | hw |
device | Connected OneKey device info |
passphraseMode | none, on_host, or on_device |
After login, follow-up commands use the active session automatically.
Device Lifecycle
Run only the action the user requested, after inspecting the installed CLI schema and explaining any setting change:
| Action | Command family |
|---|---|
| Verify the connected device | onekey device verify |
| Change the device PIN | onekey device change-pin |
| Change passphrase protection | onekey device toggle-passphrase |
| Inspect or change device settings | onekey device settings |
If a command is absent from onekey schema --list, report the unsupported command instead of guessing its parameters.
Do not bypass physical confirmation. If the device is locked, disconnected, asks for PIN or passphrase, or rejects a request, report that state and stop.