Setup wallet

Run wallet -h to see all available command line switches.

Setup your seed

Wallet is deterministic and the only thing you need to set it up is the seed password.
As long as you remember the password, you do not need to backup the wallet.
You can either enter this password each time when running the wallet, or you can store it in a file called .secret and never be asked to enter it again.

Using random seed

You do not need to use a memorable password. Instead you can create a random secret seed, e.g. using a command like this:
cat /dev/urandom | tr -cd a-zA-Z0-9 | head -c 43 > .secret

Note: using a password that you cannot memorize, make sure to have a backup of your .secret file.
Warning: See On trusting random generators for why using only a randomly generated value may be a bad idea.

Export public addresses

After you setup your wallet in a secured environment, you should export its public addresses.

In order to do this, just run wallet -l and your wallet's public addresses will be written to wallet.txt.

Security precautions

The seed password is your entire wallet and the function used to turn it into private keys is double SHA256^*, which is pretty easy to compute.
That is why it is very important for you to make sure that the password you're choosing will be resistant to brute force and dictionary attacks.
If you choose to use a memorable seed password (aka brain wallet), make it at least 20 characters long, preferably more than 30.
Avoid using words - especially such that can be found in a dictionary, as well as using simple sentences, or even more complex ones if they are known.

If you are affraid of forgetting the password and decide to write it down, try to describe it as a puzzle that only you can understad.
Avoid writing down the password as is.

Backups are a week point of the wallet's security, so having a memorable though uncrackable seed provides secure and convenient solution.
Moreover, by choosing a brain wallet you will not have to carry any wallet with you, making it impossible for anyone to see that you are carrying any coins.
See On trusting random generators for why the common objection to brain wallets is weaker than it sounds.

If you decide to store your seed in the .secret file, make sure to protect it accordingly (e.g. have the disk with it encrypted).

*) Wallets version 1.10.1 (or higher) support using an optional scrypt function to convert the password into private keys, making your brain wallet far more resistant to bruteforce attacks. See the scrypt config value (inside your wallet.cfg file) for more info.

BIP39 compatibility

Gocoin's HD wallet (type=4) can work with BIP39 mnemonics, in either direction: it can turn your seed password into a mnemonic that other wallets will accept, or it can take a mnemonic generated elsewhere and use it as the seed.
Note that all the BIP39 features require type=4 — with any other wallet type the tool will refuse to run.

Making your own wallet BIP39 compatible

Add a line like bip39=12 to your wallet.cfg file and the generated wallet will be BIP39 compatible, so you will be able to use it with the Gocoin wallet as well as with most of the other bitcoin wallets on the market.
The allowed word counts are 12, 15, 18, 21 and 24.

The only other thing you need to set up is the hdpath parameter, which in the most common case will be:
    type=4
    bip39=12
    hdpath=m/84'/0'/0'/0/0
    atype=bech32
    scrypt=15
Note: the atype value only decides how the addresses are printed, but pick one that matches your hdpath (bech32 for m/84'), or the addresses listed by Gocoin will look different than the ones shown by the other wallet, even though the keys are the same.

We still advise to use the scrypt parameter with some high value, to make your secret even more bruteforce resistant.

After choosing (or generating) your seed, run wallet -words to see the mnemonic:
    wallet -words
The same seed password, with the same config, will always give you the same BIP39 mnemonic — which you can then use to set up another wallet (software or hardware) of your liking.

The config file does not need to be protected, but it does need to be remembered. The bip39 word count and the scrypt value both take part in creating the mnemonic, so changing either of them gives you a completely different set of words. The hdpath and hdsubs values do not affect the mnemonic — they only decide which keys get derived from it.

Note that you do not need to backup the words at all. The mnemonic is always recreated from your seed password, so backing up the content of your .secret file is enough — and such a backup is far less obvious about what it is. A sheet of paper with 24 english words on it says bitcoin wallet to anyone who finds it, while a line of text does not have to say anything.

You can go a step further and write it down as a puzzle that only you can solve (e.g. always swap 'a' with 'x', or 'e' with '3'), so that even somebody who knows what he is looking at cannot turn your backup into a wallet.

Warning: whatever rule you use, you have to be able to apply it years from now. One forgotten swap and the coins are gone. The same goes for the config — without the same bip39 and scrypt values, the very same .secret file will give you a different set of words.

Note: the mnemonic is derived from your seed password, so its strength is the strength of that password. Asking for 24 words instead of 12 does not make a weak password any stronger.

Using a mnemonic generated elsewhere

You can also do it the other way around. Having a 12/15/18/21/24 word mnemonic, save it as your .secret file and put bip39=-1 in the config file, to instruct the Gocoin wallet that .secret contains a BIP39 mnemonic and not a seed password:
    type=4
    bip39=-1
    hdpath=m/84'/0'/0'/0/0
    atype=bech32
Then you will be able to use the Gocoin wallet (and the Gocoin client, if you wish) with seed phrases generated elsewhere. Remember to also set up hdpath.

The file is parsed leniently: the case does not matter and anything that is not a letter is treated as a separator, so line numbers or one word per line will not break it.
If your mnemonic is protected with a BIP39 password (the so called 25th word), run the wallet with the -p39 switch and you will be asked for it.

Note: scrypt cannot be used in this mode and the wallet will refuse to start if you try. A mnemonic has to be converted to the seed exactly as BIP39 defines it, or the keys would not match the ones from any other wallet.

Warning: a mnemonic generated by another device carries that device's entropy, with all its problems — see On trusting random generators. Gocoin has no way of telling how random the words you give it really are.

Importing other private keys

You can import keys from your existing bitcoin wallet, as well as keys generated by other tools (all kind of key/address generators).

The key that you want to import must be in base58 encoded format, which looks somehow like 5KJvsngHeMpm884wtkJNzQGaCErckhHJBGFsvd3VyK5qMZXj3hS. To export a private key from the official bitcoin wallet use dumprivkey RPC command. To import such a key into your Gocoin wallet, just store the base58 encoded value in a text file named .others (each key must be in a separate line). You can also place a key's label in each line, after a space.

The imported keys will extend the key pool of the deterministic ones (that come from your password-seed). After Importing each new key, you should redo wallet -l to get an updated wallet.txt for your client.

Optional: setup your node with the wallet file

Having wallet.txt file generated at the wallet machine, use Wallet page of WebUI and store the content of this file as a wallet in your browser. You can choose any name you want and you can change labels for the addresses.

On trusting random generators

There are claims that brain wallets are not secure because "brains cannot be a good source of entropy".
That is true, but it is only half of the picture — the other half is what the alternative asks you to trust.

A random number generator is the one component whose output cannot be verified. A correct generator and a broken or backdoored one produce output that is statistically indistinguishable; there is no test that tells them apart. When the generator lives inside a CPU instruction or a secure element, you cannot inspect it either: nothing lets you rule out that what looks like noise is a cipher stream, keyed with a value known to whoever designed the silicon.

Bugs alone have a long record, and bitcoin has paid for most of them.
In August 2013 a weakness in Android's SecureRandom made wallets reuse the same random value when signing — and in ECDSA, two signatures sharing one random value give away the private key to anyone reading the blockchain. Bitcoin Wallet, Mycelium, BitcoinSpinner and the blockchain.info app were all affected, and the coins were taken.
In December 2014 blockchain.info's web wallet broke the same way: every key it produced that day was reproducible, and a white hat had to sweep the funds himself to keep them from thieves. Months later the same company's Android app was found fetching its entropy from random.org over plain HTTP — after random.org switched to HTTPS, the "random" bytes were the text of a redirect error.
Add the Debian OpenSSL key generation flaw (2008), the browser and BitcoinJS weaknesses behind "Randstorm" that touched wallets created between 2011 and 2015, and Libbitcoin's bx seed seeded with a 32-bit timestamp — "Milk Sad", 2023.

The most expensive case so far came in July 2026. Because of a build configuration mistake made in March 2021, Coldcard hardware wallets had been seeding keys from a deterministic PRNG derived from the chip ID and a timer instead of the hardware RNG: roughly 40 bits of effective entropy on the Mk3. An attacker re-derived the keys offline and swept over 1,000 BTC from some 1,200 addresses within the hour, without touching a single device. That firmware had been open source and publicly reviewable for five years.

Nothing above needs to be sabotage — just ordinary mistakes that nobody spotted, because there is nothing to spot: broken output looks exactly like good output. Which is why deliberate weakening is not a hypothetical concern either. The documents released by Edward Snowden described BULLRUN, a programme aimed at covertly introducing weaknesses into encryption standards and products. Its best documented subject is Dual_EC_DRBG, a random generator that the NSA pushed into the NIST SP 800-90 standard: slower and more biased than the three alternatives beside it, and built so that whoever chose its two constants could predict its entire output. Cryptographers said so publicly in 2007; it was shipped as the default generator in a major commercial crypto library anyway; NIST told everyone to stop using it in 2013. There is still no document in which anyone admits inserting the backdoor — and that is exactly the point. With a random generator, you never get the proof.

The conclusion is not that you should trust your imagination over /dev/urandom. It is that you should not have to trust either one alone. Entropy that you contribute yourself cannot be taken away from you by a vendor's bug or by a backdoor, so combine the two sources — the result is as strong as the better of them:
( head -c 128 /dev/urandom ; head -n 1 ) | sha256sum | head -c 64 > .secret
The command waits for you to type your own input (may as well come from dice rolls) and press Enter, then writes 256 bits of seed. Note that it deliberately reads your input from the keyboard instead of taking it as an argument — anything you type on the command line ends up stored in your shell history file.

Your own contribution must be unpredictable, not merely hard for you to recall. Rolling a casino die 50 times, or flipping a coin 128 times, gives you entropy you can actually count. An invented sentence is worth far less — but it is not worth zero, and it is entropy that no manufacturer, standards body or supply chain could have known in advance. Enabling the scrypt option makes each guess expensive, which raises the value of whatever entropy you do have.

← back to Security precautions