Multisig API

Multisig API is currently only available only in Coinbase API v1. Support for API v2 will be added shortly.

Coinbase multisig accounts are HDM accounts under the hood. HDM stands for hierarchical deterministic multi signature. It is defined by two Bitcoin Improvement Proposals (BIP): BIP16 and BIP32.

Each Coinbase multisig account internally keeps track of multiple HD accounts. Addresses at the same index for each HD account are combined into one multisig address in the HDM account.

Warning: Keep in mind that this API is considered an advanced feature for people knowledgeable about Bitcoin. Only you have the keys needed to sign transactions, so if you lose them, you lose the bitcoins.

Creating a multisig account

You can create a multisig account like you would any other account, except that you provide the (extended) public keys for it.

Here we are creating a 2 of 3 multisig account:

POST /api/v1/accounts

{
  "account": {
    "name": "Multisig Wallet",
    "type": "multisig",
    "m": 2,
    "xpubkeys": [
      "xpub661MyMwAqRbcFo8WEPnst2sE8MTLe9DszR7eYhtkVuiUskpAggETvYQeSBWTuwoxZrZvf18w75AzfjLhzihWGagvcMa4J9nDWjmiD2UrAEF",
      "xpub661MyMwAqRbcEezXDATCwfxbet7ZYA8cyfh2FDckA85S5Tg5NjzjnPeikzJgj2noBvxTEPNkMwq8RMCuBhiL7sRv29ZtMft2KbKwTcc48uu",
      "xpub661MyMwAqRbcEnKbXcCqD2GT1di5zQxVqoHPAgHNe8dv5JP8gWmDproS6kFHJnLZd23tWevhdn4urGJ6b264DfTGKr8zjmYDjyDTi9U7iyT"
    ]
  }
}

You can use any of the BIP32 implementations or go to BIP32.org to create your keypairs.

You will need to input the master extended public keys (node path m) when you create a multisig account. This enables us to create new child public keys for you.

After creating the multisig account, you can then list your accounts and see the newly created multisig account listed.

Funding a multisig account

You can fund your multisig account like any other Coinbase account.

You can transfer funds from your other Coinbase accounts using our the ‘Transfer Bitcoin’ button on your accounts page or use the send_money API call, or just by sending bitcoins to an address associated with this account. You can always get a new receive address through the API.

Spending from a multisig account

Once you have funds in your multisig account, you can spend them.

Coinbase makes this process easier by storing redeem scripts for you and by generating transactions with the necessary inputs and outputs.

The process of spending works like this:

  1. You tell Coinbase you’d like to spend from your account by issuing a send_money API call.
  2. You fetch the sighashes of all the inputs.
  3. You sign the sighashes on your local computer.
  4. You upload the signed sighashes back to Coinbase.
  5. If the transaction is deemed signed and valid, Coinbase propagates the transaction.

Signing transactions

To sign a transaction you will need to sign it with the number of keys necessary. You specified this as m when creating the multisig account.

When you have created a pending transaction and have its ID, you can call the sighashes call.

This returns the sighashes for each input that is included in this transaction.

{
  "transaction": {
    "id": "53f3d9e0cbf034354a000132",
    "inputs": [
      {
        "input": {
          "index": 0,
          "sighash": "39ff838374b640f2047218d2f0c9e2e44668b431bc173ca17b081ccc556887f2",
          "address": {
            "address": "2N4LNG6w2E54cmmRbuHi5QgDuSVYzQVkZXJ",
            "addresses": [
              {
                "address": {
                  "address": "1DKnVf35bHvyazKd5RcvtDjpR6UDL7mE8n",
                  "node_path": "m/4"
                }
              },
              {
                "address": {
                  "address": "18stcVaAdZnoxfuZeHwgjaCphGK291Xe6n",
                  "node_path": "m/4"
                }
              },
              {
                "address": {
                  "address": "13oQ7SZBwfySZFWZFxLyL5YN2vtVscQcsf",
                  "node_path": "m/4"
                }
              }
            ]
          }
        }
      }
    ]
  }
}

Note the node_path for each input. This gives you instructions on which key to fetch from your HD account. In this case we need the 5th key of the first order (m/4).

You will need the regular Bitcoin private key of these keys to sign the sighash.

Remember, you need to provide the m number of signatures for each input.

Signing the sighash

In the above example, we need the keypair at m/4. We can use BIP32.org to get it, as long as we have the master extended private key.

Multisig_bip32org

One of the ways to sign, is to use bitcoin-ruby. We first set the bitcoin network to mainnet and initialize a key instance from the private key in WIF format:

> Bitcoin.network = :bitcoin
> key = Bitcoin::Key.from_base58 'KzBiHuppeydWZBR12hUvkoCwU7aA1xF9sV7JeGRzQrseKZQBT7EQ'
=> #, @pubkey_compressed=true>

Now we can take the sighash and sign it. Note that you need to sign the binary form of it.

> sighash_hex = "39ff838374b640f2047218d2f0c9e2e44668b431bc173ca17b081ccc556887f2"
> sighash = [sighash_hex].pack("H*")
=> "9\xFF\x83\x83t\xB6@\xF2\x04r\x18\xD2\xF0\xC9\xE2\xE4Fh\xB41\xBC\x17<\xA1{\b\x1C\xCCUh\x87\xF2"
> sig = key.sign sighash
=> "0E\x02 \\\xA0ps\xF9dg\xFAY\xBA\xC5\xF0\xF0\xC4j\x10\xBF_\x9D\x03\xE0\x7F\x03\xCD0\f\x14R-\x7F$V\x02!\x00\xBD\xC7\xA1\xBA\xF8\xA6sV\xDB\x04\xEF\x89Yl\x95\f\xAEL\xDB#S<\xBA\xAE~\xC1\x8BK\xB0\xCA\xBB\xC9"
> sig_hex = sig.unpack("H*")[0]
=> "304502205ca07073f96467fa59bac5f0f0c46a10bf5f9d03e07f03cd300c14522d7f2456022100bdc7a1baf8a67356db04ef89596c950cae4cdb23533cbaae7ec18b4bb0cabbc9"

In sig_hex you now have 1 of 2 signatures needed to sign this transaction. Repeat the process for the 2nd signature.

Sending transactions

Now that you have the signatures, you can upload the signatures to send the transaction. If the signatures are good, Coinbase will complete the transaction and propagate it to the Bitcoin network.