README.md
1# Coldcard CLI and Python Interface Library
2
3Coldcard is a Cheap, Ultra-secure & Opensource Hardware Wallet for #Bitcoin.
4
5Get yours at [ColdcardWallet.com](http://coldcardwallet.com)
6
7This is the python code and command-line utilities you need to communicate with it over USB.
8
9## Setup For Everyday Use
10
11- `pip install 'ckcc-protocol[cli]'`
12
13This installs a single helpful command line program: `ckcc`
14
15If you just want the python library, use:
16
17- `pip install ckcc-protocol`
18
19
20## Setup If You Might Change the Code
21
22- do a git checkout
23- probably make a fresh virtual env
24- run:
25
26```
27pip install -r requirements.txt
28pip install --editable '.[cli]'
29```
30
31## Requirements
32
33- python 3.6 or higher
34- `hidapi` for USB HID access in a portable way.
35- see `requirements.txt` file for more details.
36
37
38# CLI Examples
39
40## Command Arguments
41
42```
43% ckcc
44Usage: ckcc [OPTIONS] COMMAND [ARGS]...
45
46Options:
47 -s, --serial HEX Operate on specific unit (default: first found)
48 -x, --simulator Connect to the simulator via Unix socket
49 -P, --plaintext Disable USB link-layer encryption
50 --help Show this message and exit.
51
52Commands:
53 addr Show the human version of an address
54 auth Indicate specific user is present (for HSM).
55 backup Creates 7z encrypted backup file after prompting user to...
56 bag Factory: set or read bag number -- single use only!
57 chain Get which blockchain (Bitcoin/Testnet) is configured.
58 debug Start interactive (local) debug session
59 eval Simulator only: eval a python statement
60 exec Simulator only: exec a python script
61 get-locker Get the value held in the Storage Locker (not Bitcoin...
62 hsm Get current status of HSM feature.
63 hsm-start Enable Hardware Security Module (HSM) mode.
64 list List all attached Coldcard devices
65 local-conf Generate the 6-digit code needed for a specific PSBT file to...
66 logout Securely logout of device (will require replug to start over)
67 msg Sign a short text message
68 multisig Create a skeleton file which defines a multisig wallet.
69 p2sh Show a multisig payment address on-screen.
70 pass Provide a BIP39 passphrase
71 pubkey Get the public key for a derivation path Dump 33-byte...
72 reboot Reboot coldcard, force relogin and start over
73 sign Approve a spending transaction by signing it on Coldcard
74 test Test USB connection (debug/dev)
75 upgrade Send firmware file (.dfu) and trigger upgrade process
76 upload Send file to Coldcard (PSBT transaction or firmware)
77 user Create a new user on the Coldcard for HSM policy (also...
78 version Get the version of the firmware installed
79 xfp Get the fingerprint for this wallet (master level)
80 xpub Get the XPUB for this wallet (master level, or any derivation)
81```
82
83
84## Message Signing
85
86```
87% ckcc msg --help
88Usage: ckcc msg [OPTIONS] MESSAGE
89
90 Sign a short text message
91
92Options:
93 -p, --path TEXT Derivation for key to use
94 -v, --verbose Include fancy ascii armour
95 -j, --just-sig Just the signature itself, nothing more
96 -s, --segwit Address in segwit native (p2wpkh, bech32)
97 -w, --wrap Address in segwit wrapped in P2SH (p2wpkh)
98 --help Show this message and exit.
99
100% ckcc msg "Hello Coldcard" -p m/34/23/33
101Waiting for OK on the Coldcard...
102Hello Coldcard
1031KSXaNHh3G4sfTMsp9q8CmACeqsJn46drd
104H4mTuwMUdnu3MyMA+6aJ3hiAF4L0WBDZFseTEno511hNN8/THIeM4GW4SnrcJJhS3WxMZEWFdEIZDSP+H5aIcao=
105```
106
107## Transaction Signing
108
109```
110% ckcc sign --help
111Usage: ckcc sign [OPTIONS] PSBT_IN [PSBT_OUT]
112
113 Approve a spending transaction by signing it on Coldcard
114
115Options:
116 -v, --verbose Show more details
117 -f, --finalize Show final signed transaction, ready for transmission
118 -z, --visualize Show text of Coldcard's interpretation of the transaction
119 (does not create transaction, no interaction needed)
120 -s, --signed Include a signature over visualization text
121 -x, --hex Write out (signed) PSBT in hexidecimal
122 -6, --base64 Write out (signed) PSBT encoded in base64
123 --help Show this message and exit.
124
125% (... acquire PSBT file for what you want to do ...)
126
127% ckcc sign example.psbt out.psbt
1285071 bytes (start @ 0) to send from 'example.psbt'
129Uploading [####################################] 100%
130Waiting for OK on the Coldcard...
131Ok! Downloading result (5119 bytes)
132
133% hexdump -C out.psbt | head -3
13400000000 70 73 62 74 ff 01 00 fd 22 04 02 00 00 00 04 3f |psbt...."......?|
13500000010 ee 16 30 9d 14 82 36 dd c8 3e 9e 4f 94 47 83 00 |..0...6..>.O.G..|
13600000020 c2 23 e1 06 22 1b 02 0e bd c8 1c 71 79 7d 3c 02 |.#.."......qy}<.|
13700000030 00 00 00 00 fe ff ff ff 4c 85 a0 2c 80 cb 2c 01 |........L..,..,.|
138
139```
140
141
142