Developers
Shell API Reference
17 Jul 2026

The machine interfaces of Keycard Shell: QR payload formats, the USB protocol, and the clear signing database. For the wallet-side view of these interfaces, see Integrate a Wallet with Keycard Shell.

Sign requests and responses travel as animated QR codes encoded with Blockchain Commons UR — a chain-agnostic transport. Each chain then defines its own UR payload types on top of it.

Ethereum / EVM (defined by EIP-4527):

  • crypto-hdkey — account export
  • eth-sign-request / eth-signature — transactions, messages and EIP-712 typed data

Bitcoin (defined by the Blockchain Commons specs):

  • crypto-account — account export
  • crypto-psbt — PSBT sign requests
note
crypto-multi-accounts, btc-sign-request and btc-signature are Keystone extensions. Shell can parse them for compatibility with wallets that use the Keystone protocol (e.g. Bitget), but they are not part of the core specs above.

The authoritative payload definitions are in the CDDL file: ur.cddl.

When USB data is enabled, Shell enumerates as a USB HID device (VID 0x1209, PID 0x21f7) and speaks an APDU-like protocol:

  • C-APDU format: CLA(0xe0) + INS + P1 + P2 + Lc + Data
  • Command chaining for payloads over 255 bytes
  • GET RESPONSE for multi-chunk responses (SW=0x61XX)
  • Commands include GET DEVICE INFO, GET PUBLIC, SIGN ETH TX, SIGN EIP-712, SIGN PSBT, and firmware/database updates

The full protocol specification and command list: USB.md.

Clear signing for contract calls uses an on-device database containing chains, ERC-20 metadata, and Ethereum ABIs.

Database builds are reproducible from the source JSON inputs; verify the hash (signature excluded) with tools/database-hash.py.

Shell firmware images are signed: the bootloader verifies a secp256k1 signature with an embedded public key before booting (bootloader verification code). Official devices only accept signed firmware updates — to run custom firmware, see Build Your Own Shell.

Last edited
17 Jul 2026