Basic MultiSig Wallet API

Our Basic Multi-Signature addresses by default require two signatures for all withdrawals: yours, and Block.io's. This method provides exponentially higher security for your Wallets and applications than single-signature addresses. This way, you spend coins yourself, without trusting Block.io with your credentials. For private keys for your wallets, visit the Settings page on your dashboard.

If you require a more elaborate configuration to customize your applications' security, inquire about our Distributed Trust framework by going here. This framework allows up to 5 signatures per address. The use cases are endless!

Getting Started

First, you will need your API Keys, which we provide for Bitcoin, Dogecoin, Litecoin, and their Testnets. These API Keys are located in your Wallet. You are required to use an API Key when you interact with Block.io. It tells Block.io which network (e.g., Bitcoin) you wish to perform actions on.

Additionally, you are required to restrict API access to your own (secure) machines' IP addresses. That means you will explicitly allow access to IP addresses for machines that can access your account's API. If you do not know a machine's IP address, you can run the following on your machine's UNIX command-line:


$ curl --ipv4 'https://block.io/ip_echo' # IPv4
$ curl --ipv6 'https://block.io/ip_echo' # IPv6

Once you have the IP addresses, add them one by one via the Settings page.

You can access the API by making calls to links of this format:


https://block.io/api/v2/get_balance/?api_key=BITCOIN, DOGECOIN or LITECOIN API KEY
  

Actions for Handling Addresses

Get New Address

Returns a newly generated address, and its unique(!) label generated by Block.io. You can optionally specify a custom label.
You can also optionally specify the type of address you wish to generate.

Available address types for Bitcoin, and Litecoin are P2SH, and WITNESS_V0 (default). Dogecoin is limited to P2SH addresses at this time.

Note that use of Witness v0 addresses will save you significant amounts of network fees.


/api/v2/get_new_address/?api_key=API KEY
/api/v2/get_new_address/?api_key=API KEY&label=LABEL
/api/v2/get_new_address/?api_key=API KEY&address_type=ADDRESS TYPE
      

Get a new address with a random label

API KEY: (Your API Keys are in your Wallet)

Get a new address with a given label

API KEY: (Your API Keys are in your Wallet)

LABEL:

Get a low network fee address (type=witness_v0)

API KEY: (Your API Keys are in your Wallet)

ADDRESS TYPE:


Get Balance

Returns the balance of your entire Bitcoin, Litecoin, or Dogecoin account (i.e., the sum of balances of all addresses/users within it) as numbers to 8 decimal points, as strings.


/api/v2/get_balance/?api_key=API KEY
      

Get account balance

API KEY: (Your API Keys are in your Wallet)


Get My Addresses

Returns the (unarchived) addresses, their labels, user ids, and balances on your account. Upto 2500 addresses per page. Page parameter is optional.


/api/v2/get_my_addresses/?api_key=API KEY&page=PAGE NUMBER
      

Get my addresses

API KEY: (Your API Keys are in your Wallet)

PAGE:


Get Address Balance

Returns the balance of the specified addresses, or labels. Upto 2500 addresses/labels can be specified per request.

Can be used to query balances for external (non-account) addresses. If an external address' balance is returned, its user_id and label fields will be null.


/api/v2/get_address_balance/?api_key=API KEY&addresses=ADDRESS1,ADDRESS2,...
/api/v2/get_address_balance/?api_key=API KEY&labels=LABEL1,LABEl2,...
      

Get the balance of a given address

API KEY: (Your API Keys are in your Wallet)

ADDRESSES:

Get the balance of an address with a given label

API KEY: (Your API Keys are in your Wallet)

LABELS:


Get Address By Label

Returns the address specified by a label.


/api/v2/get_address_by_label/?api_key=API KEY&label=LABEL
  

Get the address for a given label

API KEY: (Your API Keys are in your Wallet)

LABEL:

Withdrawal Actions

Overview

Block.io eases your burden of storing information regarding users' addresses, and labels. Below, we provide various methods that allow you to make fine-grained transactions using your addresses. You can prepare transactions using any or specific addresses, or labels. You can send the specified amounts to up to 2500 destination addresses, or labels in a single API call.

Minimum Amounts You can prepare transactions for sending at least 0.02 DOGE, 0.00002 BTC, or 0.0002 LTC.

Block.io Fees Block.io does not charge fees (unless otherwise noted on the Settings page). You always pay your own network fees, however, which are in addition to the withdrawal amounts specified.

Network Fees The speed with which miners confirm your transaction depends on the network fees you pay, and the network fees you pay depend on the size of your transaction (in bytes). Larger transactions incur higher network fees. You can specify the priority for your transactions using an additional parameter priority={low,medium,high,custom} to adjust the network fee you wish to pay. Block.io will adjust appropriate network fees for priority={low,medium,high} automatically by monitoring the state of the relevant network. You can specify custom network fees using the parameters priority=custom and custom_network_fee=CUSTOM_NETWORK_FEE.

Transaction Batching You can send coins to upto 2500 destination addresses in a single transaction. We recommend using a single transaction to send coins to multiple recipients, wherever possible. This allows you to incur lower network fees overall, improves confirmation times for your transactions, as well as the health of the relevant network and its blockchain.

Ensuring Uniqueness of Withdrawals Since each transaction is created by you client-side, and signed by you client-side, you will monitor your own application's logic to ensure uniqueness of transactions.

Sequential vs. Parallel Execution When you prepare transactions, Block.io provides appropriate data for you to construct transactions client-side. If you execute transactions in parallel, you might be using the same coins (inputs) in two or more transactions. This will cause your transactions to fail (an error from Block.io when you submit signed transactions to Block.io) since each input can only be used once. To avoid this pitfall, you will execute your transactions sequentially (i.e., one after the other), rather than in parallel (i.e., simultaneously).

These methods support POST and GET, but only GET examples are shown below. We recommend using POST methods in your applications.

Please use one of our official libraries for Ruby, PHP, NodeJS, Python, or C# to create and sign transactions client-side. You can always make your own client-side software by using one of our official libraries as reference. You can find our libraries as open-source projects at our GitHub page.

Process for Executing Transactions ("Withdrawals")

When you wish to transact using your addresses ("withdraw coins"), you will perform the following steps:

1. Preparing Transaction You will first ask Block.io for data appropriate to create a transaction. You do this by supplying source addresses (addresses to withdraw coins from), destination addresses (addresses to which you wish to send coins), and optionally the transaction's priority for network fees, or custom network fees you wish to pay for your transaction. You do not need Block.io for this data since you can get this from any other source you deem fit yourself. However, the latter may be complicated for users.

2. Inspecting Prepared Transaction Data You will then inspect the data with which you will create your transaction. This means you are responsible for assuring the coins you spend ("inputs"), the coins to be received by a destination ("outputs"), network fees, etc. are as you wish them.

3. Creating and Signing Transaction You will then use the set of inputs and outputs you've prepared to create the transaction using the Bitcoin, Litecoin, Dogecoin, etc. networks' protocols. This is made easier by Block.io through our reference libraries for creating transactions client-side. Additionally, if you are not providing private keys yourself, your software will decrypt the appropriate private keys client-side using your Secret PIN, and then sign the transaction you've created.

4. Submitting the Transaction The unsigned transaction, and signatures you've generated in the previous step can then be submitted to Block.io. Block.io will double-check to ensure you are not accidentally paying exorbitant network fees, and that the signatures you've generated for your transaction are appropriate for the relevant network. If all tests pass, Block.io will append its own key's signature to your transaction if you only partially signed the transaction. Once the transaction you generated is fully signed, it will be broadcast to the relevant coin's peer-to-peer network. For fully signed transactions, you can submit your transaction to the appropriate peer-to-peer network yourself, without using Block.io's infrastructure.

The following information is for advanced developers. For developers using Ruby, NodeJS, Python, PHP, or C#, see our reference libraries' docs (scroll to top of this page).

Prepare Transaction

Retrieve data to send coins from any addresses in your account to up to 2500 destination addresses.


/api/v2/prepare_transaction/?api_key=API KEY&amounts=AMOUNT1,AMOUNT2,...&to_addresses=ADDRESS1,ADDRESS2,...
      


Prepare Transaction using Custom Network Fee

Retrieve data to send coins from any addresses in your account to up to 2500 destination addresses. Use custom network fee.


/api/v2/prepare_transaction/?api_key=API KEY&priority=custom&custom_network_fee=CUSTOM_NETWORK_FEE&amounts=AMOUNT1,AMOUNT2,...&to_addresses=ADDRESS1,ADDRESS2,...
      


Prepare Transaction using Specific Source Addresses

Retrieve data to send coins from up to 2500 addresses, to up to 2500 destination addresses.


/api/v2/prepare_transaction/?api_key=API KEY&from_addresses=ADDRESS1,ADDRESS2,...&to_addresses=ADDRESS1,ADDRESS2,...&amounts=AMOUNT1,AMOUNT2,...
  


Prepare Transaction using Specific Source Address Labels

Retrieve data to send coins from up to address labels, to up to 2500 destination addresses, or addresses labels.


/api/v2/prepare_transaction/?api_key=API KEY&from_labels=LABEL1,LABEL2,...&to_addresses=ADDRESS1,ADDRESS2,...&amounts=AMOUNT1,AMOUNT2,...
/api/v2/prepare_transaction/?api_key=API KEY&from_labels=LABEL1,LABEL2,...&to_labels=LABEL1,LABEL2,...&amounts=AMOUNT1,AMOUNT2,...
  

The amounts=AMOUNT1,AMOUNT2,... and to_addresses=ADDRESS1,ADDRESS2,... parameters specify that destination ADDRESS1 will receive AMOUNT1, ADDRESS2 will receive AMOUNT2, etc. The source addresses (from_addresses=...) will need at least SUM(AMOUNT1,AMOUNT2...)+Network Fees in balances for this withdrawal to succeed.


Create and Sign Transaction

You will use the inputs, outputs, encrypted user key, input address data from the prepare transaction API responses.

Refer to one of our reference libraries (see above) which implement client-side logic to perform this step.


Submit Transaction

Once you have created the transaction client-side, and signed it client-side, you can submit it to Block.io for additional signatures and/or broadcasting to the peer-to-peer blockchain network.

Here's an example body of the data you will submit as a JSON object. It contains: the transaction type ("tx_type" from prepare transsaction API response), the fully signed or unsigned transaction in hexadecimal form ("tx_hex"), and an array of signatures for each signed input. For fully signed transactions, the "signatures" object will be null.


{
  "tx_type": "basic",
  "tx_hex": "010000000330063782af1e81eddbca00856ff646a6df8164585ae66c784924572f909a5d5d0000000000ffffffffd4ea031218137a06524a7c13c921a3d271fa97905d378e719927d6fedc48c3ad0000000000fffffffff05c2af854968d1d38b1a2e8b3982c13cb0b5dccebb09f09fb098bacce4dfa9f0100000000ffffffff0344d612000000000017a91410eb388a17a299ed87b8962e25efdb15f3cd86fe87393000000000000022002025e75758225bf2706fdd2dac763f0134fdea3be04a3f15414f9bde188280f72d147bfc000000000017a914108dc42df9d23e581d09a512cd38f58b48bd444d8700000000",
  "signatures": [
    {
      "input_index": 0,
      "public_key": "034309721935937713a2dd1c33c5c44a10a30674bebe0542aeb145ce4c9790e742",
      "signature": "3044022024d0b5749b7c198f5bc57a61e63dddf9b90b5c98ae53b063b647fb98c8be61090220794354afeaae1447fe9d60fb101990d55855ca90c5ac5290f4cb18aadf2ca65a"
    },
    {
      "input_index": 1,
      "public_key": "034309721935937713a2dd1c33c5c44a10a30674bebe0542aeb145ce4c9790e742",
      "signature": "3044022074abc51fc7f25405053de3e4f861ff75400a64053fe7ccb93cd15b642a428ea5022043ec5b19cabedfe164e1b05fbedb675c060ab5f6f390132442bf712289d29036"
    },
    {
      "input_index": 2,
      "public_key": "034309721935937713a2dd1c33c5c44a10a30674bebe0542aeb145ce4c9790e742",
      "signature": "304402201591e9a6fe6dee39da9883ed550d3fbe26f347fd2e1ad492f6a59643059d0b8102207c550357b459852d05577c5069391740267878c420e55e9aca47e1c672680348"
    }
  ]
}
  
$ curl https://block.io/api/v2/submit_transaction/?api_key=YOUR_API_KEY -d 'transaction_data=JSON_DATA_ABOVE' -H 'Content-Type: application/json'

Estimate Network Fee

Estimates the Network Fee you will need to pay when you execute a transaction. The Network Fee is required by the blockchain network, not Block.io.

When you change withdrawal parameters, the estimated network fees or lower/upper bounds for custom network fee may change as well.

Please use the same parameters as you would with any prepare transaction API call; only one example is given below.


/api/v2/get_network_fee_estimate/?api_key=API KEY&amounts=AMOUNT1,AMOUNT2,...&to_addresses=ADDRESS1,ADDRESS2,...
      

Estimate network fee for given transaction parameters

API KEY: (Your API Keys are in your Wallet)

AMOUNTS:

TO ADDRESSES:

Validate custom network fee for given transaction parameters

API KEY: (Your API Keys are in your Wallet)

AMOUNTS:

TO ADDRESSES:

PRIORITY:

CUSTOM NETWORK FEE:

Address Archival Actions

Archiving of addresses help you control account bloat due to a large number of addresses.

When an address is archived, it is:

  • Not displayed in your wallet dashboard.
  • Not included in the get_my_addresses API call.
  • Not used to get available account balance.
  • Not used as a withdrawal address, unless specified.

Address archival can greatly enhance the operational security of your applications by allowing you to move coins to new addresses without clogging your API call responses.

As of 07/04/2020, addresses that receive coins (other than from your own account's addresses) will be unarchived automatically.

Archive Addresses

Archives upto 100 addresses in a single API call. Addresses can be specified by their labels.


/api/v2/archive_addresses/?api_key=API KEY&addresses=ADDRESS1,ADDRESS2,...
/api/v2/archive_addresses/?api_key=API KEY&labels=LABEL1,LABEl2,...
      

Archive an address on your account

API KEY: (Your API Keys are in your Wallet)

ADDRESSES:


Unarchive Addresses

Unarchives upto 100 addresses in a single API call. Addresses can be specified by their labels.


/api/v2/unarchive_addresses/?api_key=API KEY&addresses=ADDRESS1,ADDRESS2,...
/api/v2/unarchive_addresses/?api_key=API KEY&labels=LABEL1,LABEl2,...
      

Unarchive an address on your account

API KEY: (Your API Keys are in your Wallet)

ADDRESSES:


Get My Archived Addresses

Returns your archived addresses, their labels, and user ids on your account. Upto 2500 addresses per page. Page parameter is optional.


/api/v2/get_my_archived_addresses/?api_key=API KEY&page=PAGE NUMBER
      

Get my archived addresses

API KEY: (Your API Keys are in your Wallet)

PAGE:

Misc. Actions

Get Current Price

Returns the prices from the largest exchanges for Bitcoin, Dogecoin, or Litecoin, specified by the API Key. Specifying the base currency is optional.


/api/v2/get_current_price/?api_key=API KEY
/api/v2/get_current_price/?api_key=API KEY&price_base=BASE CURRENCY

Get current price of Bitcoin, Dogecoin, or Litecoin in all base currencies

API KEY: (Your API Keys are in your Wallet)

Get current price of Bitcoin, Dogecoin, or Litecoin in a given base currency

API KEY: (Your API Keys are in your Wallet)

PRICE BASE:

Get Transactions

Returns various data for the last 25 transactions spent or received. You can optionally specify a before_tx parameter to get earlier transactions.

You can use this method to query for addresses that are not on your account.

Each result provides a confidence rating that shows the network's belief in the transaction's viability. This is useful if you need to validate transactions quickly (for e.g., in retail store settings) without waiting for confirmations. We recommend waiting for confidence ratings to reach 0.90-0.99 for unconfirmed transactions if you need to validate it. For unconfirmed transactions, you are also provided with the number of nodes (propagated_by_nodes) on the Network that approve of the given unconfirmed transaction (out of 150 sampled nodes).

If a double spend is detected for an unconfirmed transaction, its confidence rating falls to 0.0.


/api/v2/get_transactions/?api_key=API KEY&type=sent
/api/v2/get_transactions/?api_key=API KEY&type=received

/api/v2/get_transactions/?api_key=API KEY&type=sent&before_tx=TXID
/api/v2/get_transactions/?api_key=API KEY&type=received&before_tx=TXID

/api/v2/get_transactions/?api_key=API KEY&type=received&addresses=ADDRESS1,ADDRESS2,...
/api/v2/get_transactions/?api_key=API KEY&type=received&user_ids=USERID1,USERID2,...
/api/v2/get_transactions/?api_key=API KEY&type=received&labels=LABEL1,LABEL2,...

/api/v2/get_transactions/?api_key=API KEY&type=sent&before_tx=TXID&addresses=ADDRESS1,ADDRESS2,...
/api/v2/get_transactions/?api_key=API KEY&type=received&before_tx=TXID&addresses=ADDRESS1,ADDRESS2,...

...
      

Get the last 25 transactions for all addresses

API KEY: (Your API Keys are in your Wallet)

TYPE:

Get the last 25 transactions for specific addresses

API KEY: (Your API Keys are in your Wallet)

TYPE:

ADDRESSES:

Get 25 transactions for all addresses before a transaction occurred

API KEY: (Your API Keys are in your Wallet)

TYPE:

BEFORE TX:

Get Raw Transaction

Returns the raw data, including transaction hex, for a given transaction ID.


/api/v2/get_raw_transaction/?api_key=API KEY&txid=TXID
      

Get raw data for a single transaction

API KEY: (Your API Keys are in your Wallet)

TXID:

Validate Address

Returns whether a single specified address is valid for the network, or not.


/api/v2/is_valid_address/?api_key=API KEY&address=ADDRESS
      

Validate a single address

API KEY: (Your API Keys are in your Wallet)

ADDRESS:

Account Info

Returns basic information about your account, such as its current Plan, number of addresses created, number of daily API requests used, etc. API Key agnostic.


/api/v2/get_account_info/?api_key=API KEY
      

Get current account info/status

API KEY: (Your API Keys are in your Wallet)

Decode Raw Transaction

Returns the decoded raw transaction for a given transaction in hexadecimal form.


/api/v2/decode_raw_transaction/?api_key=API KEY&tx_hex=TX_HEX
      

Decode a single transaction from its hexadecimal form

API KEY: (Your API Keys are in your Wallet)

TX HEX: