Introduction

BlockCypher runs the Main and Test Bitcoin, Litecoin and Dogecoin block chains. The BlockCypher API is a simple, mostly RESTful JSON API, accessed over HTTP or HTTPS from the api.blockcypher.com domain. All URLs are versioned. We provide push-style APIs using WebSockets and allow you to register a URL to POST to via WebHooks.

Alternatively, libraries native to multiple programming languages can be used.

Several code samples are provided throughout this documentation. If you would like to check them first, they're listed here:

Low volume access to our APIs is fully open but obtaining an API token is recommended to avoid rate limiting. Please contact us if you have any questions.

Language Specific Libraries

Multiple libraries exist for most mainstream programming languages, either provided by BlockCypher or by the community:

RESTful Resources

Most resources exist under a given block chain. The URLs to Bitcoin, Dogecoin, Litecoin, Uro and BlockCypher chains are:

https://api.blockcypher.com/v1/btc/main
https://api.blockcypher.com/v1/btc/test3
https://api.blockcypher.com/v1/doge/main
https://api.blockcypher.com/v1/ltc/main
https://api.blockcypher.com/v1/uro/main
https://api.blockcypher.com/v1/bcy/test

Opening the URL to Bitcoin Main will produce the following JSON document. It will show the current chain height, hashes and URLs of the last 2 blocks which are extracted in real-time from our API.



The samples in this documentation are in Javascript (browser or node.js) or can be accessed using the command line. Complete examples can be found in BlockCypher's Github documentation repository. For the command line, we use curl and json to illustrate.

For example, this shows the number of transactions in the latest block (see the Blockchain API section for more information):

$ curl -s http://api.blockcypher.com/v1/btc/main | json latest_url | xargs curl -s | json n_tx
267

Rate Limits

BlockCypher APIs can be used up to these rate limits:

  • Classic requests, up to 5 requests/sec and 600 requests/hr
  • WebHooks and WebSockets, up to 600 requests/hr

If you exceed a limit, an HTTP status code 429 will be returned. Please register for a user token if your usage can exceed those limits. Our future pricing plan will be tiered based on usage and volume. We will have a free tier and an extended free plan for our early users. To request higher limits or SLAs, please email us.

When you have a token, just pass it as a URL parameter to every single of youre requests, for example:

https://api.blockcypher.com/v1/btc/main?token=$USER_TOKEN

Batching

All the endpoints that can be used to retrieve a single object (an address, block, transaction, etc.) can also be used to retrieve multiple at once. Compose your URLs by appending each identifier to the previous using a semicolon as a separator. For example (click on the links to see non-abbreviated URLs):

http://api.blockcypher.com/v1/btc/main/blocks/5;6;7
http://api.blockcypher.com/v1/btc/main/addrs/1J38W...;1JP8F...;1ENn7X.../balance
http://api.blockcypher.com/v1/btc/main/txs/950d61...;6370d435...

The results are aggregated in a JSON array and may not be ordered, especially for bigger batches. This should not matter as the requested identifiers are always present in the returned objects.

Batching also works even when the identifiers arent the last part of the URL (like the address balance request above). The number of elements that can be retrieved at once is limited to 100.

Note: as the default rate limit per second is 5, larger batches will require you have an API token. To use larger batches please register.

Testing

We faciliate the testing of your applications in 2 different ways:

  • A BlockCypher test chain, supporting all our services as well as an automated faucet.
  • An automated faucet for the bitcoin testnet.

BlockCypher Test Block Chain

For automated testing, we recommend the use of our test block chain. It has characteristics very similar to Bitcoin's main chain but is more stable, offers faster confirmations and has a "faucet", which allows you to very easily get free coins for automated testing.

The only differences with the Bitcoin main chain are the following:

  • The chain is private (no data is broadcasted, only BlockCypher mines the transactions), making it much more predictable than the Bitcoin's testnet (which is frequently under attack).
  • New blocks get built every minute, confirming the transactions that have been created using our transaction API.
  • The prefix for standard addreses is 'B' or 'C' (0x1B). The prefix for multisig addresses is 'D' (0x1F).

This blockchain is available under the following URL:

https://api.blockcypher.com/v1/bcy/test

Test Faucets

In addition to all our APIs a faucet endpoint is available, which works both on our test chain and on the bitcoin testnet. Calling it passing an address will automatically create a new transaction funding the address with the provided amount.

The faucets can be used from your browser if you want to play with them before automating:

To use them programmatically, the following example demonstrates how to create a new test address and fund it with 100,000 of our coins:

$ curl -X POST http://api.blockcypher.com/v1/bcy/test/addrs?token=$TOKEN
{
"private": "26415016a2fb49f51aef161cb35bd537be07b75a6ac1e297d3b7a370cc85433b",
"public": "02c572d062fefcc8c3e1bf5016450addcedb89cd7e4507d8a323f327b4ad1018e0",
"address": "CFqoZmZ3ePwK5wnkhxJjJAQKJ82C7RJdmd"
}
$ curl -d '{"address": "CFqoZmZ3ePwK5wnkhxJjJAQKJ82C7RJdmd", "amount": 100000}' http://api.blockcypher.com/v1/bcy/test/faucet?token=$TOKEN
{
  "tx_ref": "02dbf5585d438a1cba82a9041dd815635a6b0df684225cb5271e11397a759479"
}

The exact same interaction can be achieved on the bitcoin testnet by replacing bcy/test with btc/test3 in all URLs above.

A token is required to use the faucet. On the BlockCypher test chain, the faucet will refuse to fund an address with more than 50 billion coins and will not fund more than 10 million coins at a time. On the bitcoin testnet those numbers are adjusted to 10 million and 500,000 testnet satoshis respectively.

Blockchain API

The Blockchain API allows you to access raw data from the block chain's transactions and blocks.

Three main resources make up the Blockchain API (all GETs under https://api.blockcypher.com):

Name URL Pattern Example Description
Chain /v1/{coin}/{chain} /v1/btc/main Returns the current state of the specified block chain, including height and the two latest blocks.
Block /v1/{coin}/{chain}/blocks/{hash|height} /v1/btc/main/blocks/293000 All details about a given block, including transaction hashes. Can be retrieved either by block height or block hash.
Transaction /v1/{coin}/{chain}/txs /v1/btc/main/txs An array of the latest unconfirmed transactions received. Page through results by passing the date of the oldest received transaction to a before URL parameter.
Transaction /v1/{coin}/{chain}/txs/{hash} /v1/btc/main/txs/f854aeba... All details about a given transaction, including involved addresses, inputs and outputs.
Transaction Confidence /v1/{coin}/{chain}/txs/{hash}/confidence /v1/btc/main/txs/f854aeba.../confidence Transaction confidence information (see Zero Confirmations).

Chains

Currently, we support the main and test Bitcoin and Litecoin block chains. Depending on market demands, we'll add additional block chains and alt coins. Please contact us if interested.

A request to a given chain returns the following properties:

Property Example (abbreviated URLs and hashes) Description
name BTC.main Chain name
latest 0000...974f Hash of the latest block in the chain.
previous 0000...1d66 Hash of the second to last block in the chain.
latest_url .../v1/btc/main/blocks/0000...974f URL to retrieve information on the latest block in the chain.
previous_url .../v1/btc/main/blocks/0000...1d66 URL to retrieve information on the second to last block in the chain.

Blocks

Blocks are located under a chain's URL. The most interesting properties of blocks are:

Property Example (abbreviated URLs and hashes) Description
hash 0000...35fa Block hash. Can be used as a unique identifier.
height 293268 The height of the block is the distance from the root of the chain, the genesis block at height = 0.
depth 11 The depth is the distance from the latest block in the chain, or how many blocks have been found after this one.
chain BTC.main The name of the chain the block is from.
total 448188159094 The total amount in satoshis transacted in this block. Divide by 10^8 to obtain the number of bitcoins.
fees 13383533 Amount of fees, in satoshis, collected by miners on this block.
time 2014-03-30T18:52:44Z Recorded time at which the block was built. (Note: miners rarely post accurate clock times).
received_time 2014-03-30T18:52:36.539Z The time BlockCypher's servers receive the block. Our servers' time is continuously adjusted and accurate.
bits 419486617 The block-encoded difficulty target, for more information see https://en.bitcoin.it/wiki/Difficulty
nonce 1225187768 Number used to generate this block. Incremented by miners to allow variation in the header (and hence its hash).
n_tx 579 Number of transactions in this block.
prev_block 0000...35fa Hash of the block previous to this one.
prev_block_url .../v1/btc/main/blocks/0000...35fa URL for the previous block's details.
tx_url https://api.blockcypher.com/v1/btc/main/txs/ To retrieve base URL transactions. To get the full URL, concatenate this URL with the transaction's hash.
txids ["96d8...4f6ab", "3b2c...12bb", "7fa2...90d1", ...] Array of transaction hashes included in this block. By default, we only return the 20 first transactions. To obtain more, use the next_txids URL or the txstart and limit url query string parameters.
next_txids .../v1/btc/main/blocks/0000...7b72?txstart=20&limit=20 URL to get the same block information with the next 20 transactions.

Here's a sample return document for a given block:

https://api.blockcypher.com/v1/btc/main/blocks/294322
{
    "hash": "0000000000000000189bba3564a63772107b5673c940c16f12662b3e8546b412",
    "height": 294322,
    "chain": "BTC.main",
    "total": 1146783914,
    "fees": 130999,
    "ver": 2,
    "time": "2014-04-05T07:49:18Z",
    "received": "2014-04-05T07:49:30.981Z",
    "bits": 419486617,
    "nonce": 1225187768,
    "n_tx": 10,
    "prev_block": "0000000000000000ced0958bd27720b71d32c5847e40660aaca39f33c298abb0",
    "mrkl_root": "359d624d37aee1efa5662b7f5dbc390e996d561afc8148e8d716cf6ad765a952",
    "txids": [
      "32b3b86e40d996b1f281e24e8d4af2ceacbf874c4038369cc21baa807409b277",
      "1579f716359ba1a207f70248135f5e5fadf539be1dcf5300613aedcb6577d287",
      "dd1f183348eb41eaaa9ecf8012f9cca3ecbae41a6349f0cc4bfd2b1a497fa3d0",
      "749d12ccd180968b82aef4c271ca4effdf981d9b5d12523264457c9d4e6fa78e",
      "c4fe2ee16b8e3067d3d95caf7944011f4959781288b807df8bf853b7f80ed97c",
      "5a2114675265522d2b7ce8a7874cfa7a22ccc3fb6566a8599d6432c6805b1b5f",
      "077d851c8240671de80caa8be9f5285201c08a70edc5a45a9cd35fe7eaebf5e1",
      "6202cc55fbd9130e065c9294a5b2e061c26f3d2c8df56c32da605d9f183103f9",
      "ad3e7aa1c33f1d3e1c105d94f7b1542808da07bbe66b9621b050104a85dbf650",
      "36cc61016b9d1bd69768666f287db1edaa9b292fb442f152af7099305677230e"
    ],
    "prev_block_url": "http://api.blockcypher.com/v1/btc/main/blocks/0000000000000000ced0958bd27720b71d32c5847e40...",
    "tx_url": "http://api.blockcypher.com/v1/btc/main/txs/"
  }

Transactions

Transactions can be confirmed into a block, in a pool of non-confirmed transactions, or orphaned. Confirmed transactions transfer a certain amount of bitcoin from previous transactions (referenced by inputs and controlled by a set of addresses) to a set of target addresses.

The main properties in a transaction are:

Property Example (abbreviated URLs and hashes) Description
block_hash 0000...35fa Hash of the block the transaction is in. Only exists for confirmed transactions.
block_height 293331 Height of the block the transaction is in. Only exists for confirmed transactions.
hash 9a20...9e84 Hash of the transaction. While hashes are reasonably unique, using them as identifiers may be unsafe.
addresses ["1EJFhJDvS2ncpPotz6Lb3mGGchHfr3zgXv", "1N32Ts6eA2YHrcUjwZnzmPsLUnThZ6bDbb"] Array of Bitcoin addresses involved in the transaction.
total 22180950000 Total amount exchanged in this transaction, in satoshis.
fees 10000 Fees collected by miners in the transaction, in satoshis.
hex 0100000002a35... Hex encoded bytes of the raw transaction (as sent over the network). Only included when the includeHex URL property is set to true.
relayed_by 50.154.237.192:8333 Address of the peer that sent us this transaction.
received 2014-03-31T04:23:44.833536145Z When the transaction was received by BlockCypher servers.
confirmations 5 Number of subsequent blocks, including the block the transaction is in. Unconfirmed transactions have 0 for confirmation.
confirmed 2014-03-31T04:25:12.93471948Z Date at which the transaction was included in a block, in ISO format.
preference high How likely is this transaction to make it to the next block, reflects the preference level miners have to include this transaction. Can be high, medium or low.
double_spend false Whether the transaction is a double spend (see Zero Confirmations).
double_of a672f0... If the transaction is a double spend, what transaction it's double-spending (see Zero Confirmations).
receive_count 42 Unconfirmed transactions only. The number of peers that have sent this transaction to us (see Zero Confirmations).
confidence 0.98819 Unconfirmed transactions only. Confidence this transaction will be confirmed (see Zero Confirmations).
vin_sz 1 Total number of inputs
vout_sz 2 Total number of outputs
inputs (see below) Array of inputs, limited to 20. Use paging to get more inputs (see section on blocks) with instart and limit URL parameters.
outputs (see below) Array of outputs, limited to 20. Use paging to get more outputs (see section on blocks) with outstart and limit URL parameters.

Inputs and outputs rely on scripts. When executed, they define if the transaction is valid and what type of transaction it is. We recognize 6 types of transaction scripts:

  1. Pay-to-pubkey-hash (most common transaction transferring to a public key hash)
  2. Pay-to-multi-pubkey-hash (multi-signatures transaction)
  3. Pay-to-pubkey (used for mining transactions)
  4. Pay-to-script-hash (used for transactions relying on arbitrary scripts, rarely used)
  5. Null-data, sometimes called op-return (used to embed small chunks of data in the block chain)
  6. Empty (no script present, mostly used for the input of a mining transaction)
  7. Unknown (non-standard script)

Transaction inputs have the following properties:

Property Example (abbreviated URLs and hashes) Description
prev_hash 0000...35fa Hash of the transaction for which an output is being spent by this input. Does not exist for coinbase transactions.
output_index 1 Index in the previous transaction of the output being spent. Does not exist for coinbase transactions.
output_value 1 Value of the output being spent. Does not exist for coinbase transactions.
age 26 Number of confirmations since the transaction referenced by this input was included in the blockchain. Only present for unconfirmed transactions for now.
script_type pay-to-pubkey-hash Script type in the transaction output being spent.
addresses ["1CjPR7Z5ZSyWk6WtXvSFgkptmpoi4UM9BC"] Addresses referenced in the transaction output being spent.
script 76a914...ac Raw hexadecimal encoding of the script.
script 76a914...ac Raw hexadecimal encoding of the spent output script.

Transaction outputs have the following properties:

Property Example (abbreviated URLs and hashes) Description
value 2508682714 Value transferred by the transaction output, in satoshi.
script_type pay-to-pubkey-hash Script type for this output.
addresses ["1CjPR7Z5ZSyWk6WtXvSFgkptmpoi4UM9BC"] Addresses where the value is being transfered to.
script 76a914...ac Raw hexadecimal encoding of the script.
spent_by b4735a06... Hash of the transaction that spent this output, if it was spent.

Here's a sample return document for a given confirmed transaction:

https://api.blockcypher.com/v1/btc/main/txs/793fafe4223bc6808578ea8fed3d9f8e76cf50b3170857b0d15e244e1db00deb
{

  "block_hash": "000000000000000000ac026fd6989ee5fc2e103073bf529eb50d45d5badf1f2b",
  "block_height": 337875,
  "hash": "793fafe4223bc6808578ea8fed3d9f8e76cf50b3170857b0d15e244e1db00deb",
  "addresses": [
    "15dRT5Fo8ucT6duoCzr2MGcoBxRFh4XnRq",
    "1BcQMbuuwEwns1eDLF2UPckgKUestou6wP",
    "1NJKqCVJrEknQUder6Lo8vU3uttLY8dY9H"
  ],
  "total": 586290000,
  "fees": 0,
  "preference": "low",
  "relayed_by": "192.99.37.171:8333",
  "confirmed": "2015-01-07T06:22:16Z",
  "received": "2015-01-07T06:06:04.875Z",
  "ver": 1,
  "lock_time": 0,
  "double_spend": false,
  "vin_sz": 1,
  "vout_sz": 2,
  "confirmations": 2,
  "inputs": [
    {
      "prev_hash": "6fdfda7573bf7fe9cf963c00d2801c171433161f53012a926f3d5367e5412ef0",
      "output_index": 0,
      "script": "483045022100a653b228a1114cca173db9df65d903df0260085d405c80f31c3bf032b1bac82d02200387aed659600321254d76e34c9e3060a30ca60d0ab1d8e102abc0e8e394c456012103319bb8ece54c494683350579128adc53e0effec53dc5b0c7a43c8167b14846c3",
      "output_value": 586290000,
      "addresses": [
        "1BcQMbuuwEwns1eDLF2UPckgKUestou6wP"
      ],
      "script_type": "pay-to-pubkey-hash"
    }
  ],
  "outputs": [
    {
      "value": 468380000,
      "script": "76a91432c3e32015d44c1da701db01f5014a14ba08f2ea88ac",
      "spent_by": "",
      "addresses": [
        "15dRT5Fo8ucT6duoCzr2MGcoBxRFh4XnRq"
      ],
      "script_type": "pay-to-pubkey-hash"
    },
    {
      "value": 117910000,
      "script": "76a914e9a16ea0978029093c2cd145994fce5b0c48471788ac",
      "spent_by": "",
      "addresses": [
        "1NJKqCVJrEknQUder6Lo8vU3uttLY8dY9H"
      ],
      "script_type": "pay-to-pubkey-hash"
    }
  ]

}

Zero Confirmations and Double Spending

To help you deal with zero confirmation (aka unconfirmed) transactions and the risk of double spending, we provide 2 additional transaction properties:

  • receive_count: the number of nodes in the bitcoin network we've received that transaction from so far, indicates how many nodes, at the minimum, accepted this transaction.
  • confidence: the percentage chance (between 0 and 1) that a transaction will make it into a block over time, which accounts for double-spend or transaction loss. Note that it doesn't indicate how fast the confirmation will happen.
  • preference: level of preference miners will have to include this transaction in their block, a high preference means the transaction is very likely to be confirmed in the next block, a low preference means it's likely to take several blocks (>6).

The confidence is calculated based on elapsed time as well as the receive count and is based on several public research results. As BlockCypher pools resources for many users, we're always connected to a statistically significant number of nodes on the network (and offer connections in return). While maintaining those connections, we can also assess whether a given node has received a particular transaction. By monitoring the propagation of transactions across the network, we can calculate its probability to be the "winning" transaction at any given point in time, if a double-spend was attempted.

In addition, 2 other properties indicate when a double-spend has been detected:

  • double_spend: a boolean indicating whether this transaction is a double spend.
  • double_spend_tx: the hash of the other transaction involved in the double spend attempt.

These properties are added to any unconfirmed transactions when retrieved either through the blockchain API or the address API. To be notified when a double spending attempt occurs, also see our double spend webhook.

{
  "block_height": -1,
  "hash": "fb0f7c206fe465a4482424784313361b892ad5492acd8f742fe01d0d9d263e3a",
  "addresses": [
    "1N19eR7QJDcMXvixsUGtbzC6oQuhDEej7F",
    "1C7GfnxGBQg5sKBEFUiFUuzGtx7w3U9zT9"
  ],
  "total": 1350000,
  "fees": 10000,
  "preference": "high",
  "relayed_by": "50.154.237.192:8333",
  "confirmed": "0001-01-01T00:00:00Z",
  "received": "2014-08-27T20:35:29.661215369Z",
  "ver": 1,
  "lock_time": 0,
  "double_spend": false,
  "confirmations": 0,
  "receive_count": 249,
  "confidence": 0.9966294647709607,
  ...
  "inputs": [...],
  "outputs": [...]
}

Finally, note that these measures are mitigation strategies you can rely on if you need fast transaction confirmations. They're not a bulletproof way to secure unconfirmed transactions and double spending attacks, even extremely unlikely, can still occur. Block chain confirmations ultimately provide the highest level of security.

Address API

Addresses are identifiers used to send and receive payments. A collection resource and a detail resource make up the Address API. A wallet name can also be used with this API.

Name URL Pattern Method Description
Address /v1/{coin}/{chain}/addrs/{hash}
( /v1/btc/main/addrs/1DEP8i... )
GET All details about a given address/wallet, including all inputs and outputs affecting it. Allows retrieval of unspents (UTXO) using the unspentOnly=true URL parameter. A wallet name can be used instead of an address, which will return aggregated (summed) details for all addresses in the wallet.
Full Address Transactions /v1/{coin}/{chain}/addrs/{hash}/full
( /v1/btc/main/addrs/1DEP8i.../full )
GET All details about a given address/wallet, including full transaction information. More comprehensive than the previous endpoint but slower (as it returns more data).
Address /v1/{coin}/{chain}/addrs/{hash}/balance
( /v1/btc/main/addrs/1DEP8i.../balance )
GET Only balance and number of transactions for a given address/wallet.
Addresses /v1/{coin}/{chain}/addrs
(/v1/btc/main/addrs)
POST Returns a newly generated address with the corresponding public and private keys or calculate the multisig address from a set of public keys.

Address Details

The Address API details gives you the transactions inputs and outputs, amount transferred, and current balance for any address. For transactions in addresses as for standalone transactions, we consider a transaction confirmed (and hence part of the confirmed balance) if the transaction is in a block, regardless of whether the block is the latest or 50 blocks old.

To get only the unspent transactions, append ?unspentOnly=true to the address URL.

While the simple address endpoint will return transactions inputs and outputs (see below for description), the full address transactions endpoint will return complete transactions in the format described in the transaction Blockchain API section. While this sometimes may be more convenient, it also has the potential of being slower, especially when an address includes very large transactions (just due to the time to transfer the data).

A request to a given address returns the following properties:

Property Example (abbreviated URLs and hashes) Description
address 1PuwQ6uWXNeGcEnLCAXmRJozdLZ9M4NWQ7 The requested address.
total_received 283181777 Total amount, in satoshis, received by this address.
total_sent 283181777 Total amount, in satoshis, sent by this address.
balance 12550020000 Balance on the specified address, in satoshi. This is the difference between outputs and inputs on this address, for transactions that have been included into a block (confirmations > 0)
unconfirmed_balance -100000000 Balance of unconfirmed transactions for this address, in satoshi. Can be negative (if unconfirmed transactions are just spending.). Only unconfirmed transactions (haven't made it into a block) are included.
final_balance 124500020000 Balance including confirmed and unconfirmed transactions for this address, in satoshi.
n_tx 12 Number of confirmed transactions on the specified address. Only transactions that have made it into a block (confirmations > 0) are counted.
unconfirmed_n_tx 2 Number of unconfirmed transactions for this address. Only unconfirmed transactions (haven't made it into a block) are counted.
final_n_tx 14 Final number of transactions, including unconfirmed transactions, for this address.
tx_url https://api.blockcypher.com/v1/btc/main/txs/ To retrieve base URL transactions. To get the full URL, concatenate this URL with the transaction's hash.
txrefs [...] All transaction inputs and outputs for the specified address.
unconfirmed_txrefs [...] All unconfirmed transaction inputs and outputs for the specified address.

The arrays of transaction inputs or outputs reference in txrefs and unconfirmed_txrefs have the following properties:

Property Example (abbreviated URLs and hashes) Description
tx_hash 0d7ac056a... One of the transaction hashes for the specified address.
block_height 292781 Height of the block for the transaction.
confirmations 1092 Number of confirmations for the transaction.
tx_input_n 1 Index of the input in the transaction. It's a negative number for an output.
tx_output_n -1 Index of the output in the transaction. It's a negative number for an input.
value 28318177 The value transferred by the particular input or output.
preference high How likely is the transaction to make it to the next block, reflects the preference level miners have to include this transaction. Can be high, medium or low.
confirmed 2015-05-12T17:54:46Z Time at which the transaction was confirmed (made it into a block).
spent true Is 'true' if the output was spent.
spent_by b4735a06... Hash of the transaction that spent this output, if it was spent.
double_spend false Whether the transaction is a double spend (see Zero Confirmations).
double_of a672f0... If the transaction is a double spend, what transaction it's double-spending (see Zero Confirmations).
receive_count 42 Unconfirmed transactions only. The number of peers that have sent this transaction to us (see Zero Confirmations).
confidence 0.98819 Unconfirmed transactions only. Confidence this transaction will be confirmed (see Zero Confirmations).
received 2015-05-12T17:54:06.693796609Z Unconfirmed transactions only. Time at which the transaction was received by our peers.

To page on the result when there are too many transaction inputs and outputs, use a before URL parameter passing the block height transactions should be older than. Typically, to achieve paging, this will be the block height of the last returned transaction in the txrefs array. For example:

http://api.blockcypher.com/v1/btc/main/addrs/1J38WorKngZLJvA7qMin9g5jqUfTQUBZNE?unspentOnly=true&before=300000

Here's a sample return document for a given address:

http://api.blockcypher.com/v1/btc/main/addrs/1PuwQ6uWXNeGcEnLCAXmRJozdLZ9M4NWQ7
{
  "address": "1PuwQ6uWXNeGcEnLCAXmRJozdLZ9M4NWQ7",
  "total_received": 283181777,
  "total_sent": 283181777,
  "balance": 0,
  "unconfirmed_balance": 0,
  "final_balance": 0,
  "n_tx": 2,
  "unconfirmed_n_tx": 0,
  "final_n_tx": 2,
  "txrefs": [
    {
      "tx_hash": "0d7ac056a96ffc200f53f2a64291a967e5f696c43997f877ef42cb871bb07231",
      "block_height": 278670,
      "tx_input_n": 1,
      "tx_output_n": -1,
      "value": 283181777,
      "spent": false,
      "confirmations": 62385,
      "confirmed": "2014-01-05T04:08:17Z",
      "double_spend": false
    },
    {
      "tx_hash": "baee4a85bcc1109fd4133602e6900e13b1b084c617ee75d25418ee3f3e84dcea",
      "block_height": 278564,
      "tx_input_n": -1,
      "tx_output_n": 0,
      "value": 283181777,
      "spent": true,
      "spent_by": "0d7ac056a96ffc200f53f2a64291a967e5f696c43997f877ef42cb871bb07231",
      "confirmations": 62491,
      "confirmed": "2014-01-04T11:51:33Z",
      "double_spend": false
    }
  ],
  "tx_url": "https://api.blockcypher.com/v1/btc/main/txs/"
}

Address Generation

The address generation endpoint allows you to either:

  • Generate a brand new set of private key, public key and address.
  • Compute a multisig address from a set of public keys.

The generation API returns a private key (immediately discarded by our servers), for security reasons please always use HTTPS to use this resource. No information is required in the POST request, the following information will be returned:

Property Example (abbreviated URLs and hashes) Description
address 181w71oR7nTEsKducLBTUJkdbTvLDQzymL Standard address representation.
public 028b3b3fc5d437... Public key.
private 028b3b3fc5d437... Private key.
wif L2wW7Aq... Wallet import format, a common encoding for the private key.
pubkeys [] Array of public keys to provide to generate a multisig address.
script_type multisig-2-of-3 Type of multisig script to generate a multisig address for.

To get a newly generated address:

curl -X POST http://api.blockcypher.com/v1/btc/test3/addrs
{
  "private": "86751cb880a9a1addcc3b67979976158dd800afe9d14b68349921299b20c94dd",
  "public": "03866586fbe3652eb219c5ed99c3fc72d125472248183f966e0673be08a1c543de",
  "address": "n1ucSDLByN5GLLQuE7BMrtTWHwHtkaVkfA",
  "wif": "cS64ygfjWjN73S78oUbJQeikDn9uS7KNWS1PL7NqeBUuF4UobnAy"
}

To generate a multisig address from a set of public keys:


$ curl -d '{"pubkeys": ["02c716d071a76cbf0d29c29cacfec76e0ef8116b37389fb7a3e76d6d32cf59f4d3",
                        "033ef4d5165637d99b673bcdbb7ead359cee6afd7aaf78d3da9d2392ee4102c8ea",
                        "022b8934cc41e76cb4286b9f3ed57e2d27798395b04dd23711981a77dc216df8ca"],
            "script_type": "multisig-2-of-3"}' \
            https://api.blockcypher.com/v1/btc/main/addrs

Address Wallet API

The wallet API groups multiple addresses under a single name. It only holds public information and does not require any private key. A wallet can be created, deleted and have a new address added. Addresses can be added and removed from a wallet. The wallet itself can have any custom name as long as it does not start with the standard address prefix (1 or 3 for Bitcoin).

Wallets can be leveraged by the Address API, just by using their name as an address. They can also be used with the WebSockets and WebHooks API and with the Transactions API, in which case a user token is mandatory. In general, using a wallet instead of an address with an API will have the effect of using the set of addresses in the wallet with the API. See each API for more details.

Name URL Pattern Method Description
Create Wallet /v1/{coin}/{chain}/wallets (/v1/btc/main/wallets) POST Creates a new wallet identified by name and associates addresses with it.
Addresses /v1/{coin}/{chain}/wallets/{name}/addresses (/v1/btc/main/wallets/alice/addresses) GET All addresses in a given wallet.
Add Addresses /v1/{coin}/{chain}/wallets/{name}/addresses/ (/v1/btc/main/wallets/alice/addresses) POST Associates addresses with the wallet.
Remove Addresses /v1/{coin}/{chain}/wallets/{name}/addresss/ (/v1/btc/main/wallets/alice/addreses) DELETE addresses will no longer be associated with the wallet.
Generate Address /v1/{coin}/{chain}/wallets/{name}/addresses/generate (/v1/btc/main/wallets/alice/addresses/generate) POST A new address is generated similar to Address Generation and associated it with the given wallet.
Delete /v1/{coin}/{chain}/wallets/{name}/ (/v1/btc/main/wallets/alice/) DELETE Deletes the wallet (removes the association between name and any addresses).

Wallet

To create a new wallet:

POST https://api.blockcypher.com/v1/btc/main/wallets
{
  "name": "alice",
  "addresses": ["1JcX75oraJEmzXXHpDjRctw3BX6qDmFM8e"]
}

To add an address:

POST https://api.blockcypher.com/v1/btc/main/wallet/alice/addresses
{
  "addresses": ["13cj1QtfW61kQHoqXm3khVRYPJrgQiRM6j"]
}

After which querying the wallet like would your query any address will produce the wallet balance, transaction count, transaction details, etc.

curl https://api.blockcypher.com/v1/btc/main/wallets/alice?token=$TOKEN

WebSockets and WebHooks

Events

Crypto-currencies are highly transactional systems. Usage patterns require knowing when an event occurs: e.g., when a transaction is included into a block get its first confirmation. We provide push APIs to facilitate those use cases (instead of polling resources).

We support both WebSockets and WebHooks:

  • WebSockets - used typically in client applications when a web server is not already running: e.g., a web page displaying the most recent transactions or a wallet app updating its UI when a transaction has been confirmed. Websockets are less reliable in longer interactions (over several hours) because they require a connection to stay open.
  • WebHooks - the most reliable way to get notified but requires running a web server to receive the calls. We automatically retry HTTP requests 3 times.

Both WebSockets and WebHooks can forward the following events:

  • unconfirmed-tx: Triggered for every new transaction before it goes into a block; basically, for every unconfirmed transactions. The payload is the unconfirmed transaction.
  • new-block: Triggered for every new block added to the main chain. The payload is the block.
  • confirmed-tx: Triggered for every new transaction making it into a new block on the main chain; basically, for every first transaction confirmation. This is equivalent to listening to the above events and fetching each transaction in the block. The payload is the confirmed transaction.
  • tx-confirmation: Simplifies listening to confirmations on all transactions for a given address up to a provided threshold. Sends first the unconfirmed transaction and then the transaction for each confirmation. Use the "confirmations" property to specify the number of confirmations desired (maximum 10, default 6).
  • double-spend-tx: Triggered any time a double spend is detected. The payload is the transaction that triggered the even and the hash of the transaction that it's trying to double spend is included in its double_spend_tx property.

Note: events like unconfirmed-tx can produce a lot data. Make sure you register first and use a token, otherwise events may stop being sent as you exceed rate limits.

To subscribe to an event, send a document with the following format:

{
  "event": "unconfirmed-tx",
  "address": "15qx9ug952GWGTNn7Uiv6vode4RcGrRemh",
  "token": "b972c4c0-180f-11e4-8c21-0800200c9a66"
}

The token is optional and is the value we provide you (see rate limits). Currently supported properties are:

Key Example Description
event "event": "new-block" Type of event to receive. See above for the supported event types.
hash "hash": "346a5...b77e5" (abbreviated) Only objects with a matching hash will be sent. The hash can either be for a block or a transaction.
wallet_name "wallet_name": "alice" Only transactions associated with the given wallet will be sent. If used, it requires a user token.
token "token": "myusertoken" Required if wallet_name is used.
address "address": "1CjPR7Z5ZSyWk6WtXvSFgkptmpoi4UM9BC" Only transactions associated with the given address will be sent. A wallet name can also be used instead of an address, which will then match on any address in the wallet.
script "script": "pay-to-script-hash" Only transactions with an output script of the provided type will be sent. The recognized types of scripts are: pay-to-pubkey-hash, pay-to-multi-pubkey-hash, pay-to-pubkey, pay-to-script-hash, null-data (sometimes called OP_RETURN), empty or unknown.

Depending on the provided properties, the message content will be either a transaction or a block.

WebSockets

Opening a WebSocket to listen to our feeds is easy:

new WebSocket("wss://socket.blockcypher.com/v1/btc/main");

The code may differ if you're not programming in Javascript but the URL will be identical. Once the socket is opened, the JSON document describing the event of interest should be sent.

In addition to standard events, websockets accept a ping event. If you send the following, you will receive the same message back with "ping" replaced by "pong":

{
  "event": "ping"
}

A regular ping (i.e. every 20 seconds) allows the websocket to stay connected for a longer period of time.

Example

In this example, using a WebSocket, we will subscribe to all pooled transactions (new transactions that have not been confirmed). We open a new WebSocket and send the filter we're interested in. Upon notification of new transactions, we format them and add them into the page.



WebHooks

WebHooks have the same interaction format but with two key differences:

  • The JSON document describing the event subscription should be sent using a POST request to https://api.blockcypher.com/v1/btc/main/hooks and include an additional property containing the URL to be called.
  • The transaction or block associated with the event you subscribed to will be POSTed to the provided URL. The POST request will also include a X-EventType and a X-EventId HTTP header specifying the type of and id of the webhook which triggered the request.

See above for all the different type of events you can listen to with a WebHook. To create a new WebHook:

POST https://api.blockcypher.com/v1/btc/main/hooks
{
  "event": "new-block",
  "url": "https://my.domain.com/callbacks/new-block"
  "token": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

To secure the endpoint at the callback URL you give to us and prevent a potential attacker from calling it, we recommend you append a secret as a URL parameter to that URL. We will call you leaving the URL unchanged, which allows you to test for that parameter. For example:

https://my.domain.com/api/callbacks/doublespend?secret=justbetweenus

The use of https is also recommended to prevent eavesdropper from potentially capturing the secret.

A simple way to test a WebHook is to use curl and requestb.in. First go to requestb.in and create a new bin. Then use curl to create a BlockCypher WebHook that will POST to your bin. For example to get every new block:

$ curl -H "Content-Type: application/json" -d '{"event":"new-block", "url": "http://requestb.in/YOUR_BIN"}' https://api.blockcypher.com/v1/btc/main/hooks

For an example of using WebHooks written in node.js, refer to our sample.

If calling the URL configured in a WebHook fails, it will be retried 3 times. If a WebHook fails to deliver 50 distinct events, the WebHook will be disabled.

Name URL Pattern Example Method Description
Create /v1/{coin}/{chain}/hooks /v1/btc/main/hooks POST Creates a new webhook, returned its information along with its id.
List /v1/{coin}/{chain}/hooks?token={token} /v1/btc/main/hooks?token=14df7860-eb44-11e3-ac10-0800200c9a66 GET Returns an array of webhooks associated with the provided token.
Get /v1/{coin}/{chain}/hooks/{id} /v1/btc/main/hooks/399d0923-e920-48ee-8928-2051cbfbc369 GET Gets the details of a webhook using its id.
Delete /v1/{coin}/{chain}/hooks/{id} /v1/btc/main/hooks/399d0923-e920-48ee-8928-2051cbfbc369 DELETE Deletes a webhook using its id.

Payments and Forwarding

Summary

Our payment API is the easiest way to accept payments securely without the need to create accounts for your users. It's also a generic way to automatically transfer value from one address to another. The 2 main use cases are:

  • Generate payment-specific addresses for which funds will automatically transfer to a main merchant address.
  • Easily fund a multisig address from any wallet by providing a using a classic address that will automatically transfer to the multisig.

We do not take a fee on payment forwarding, (other than the required 0.1 mBTC miner fee), payments are free. However as part of your own services, you can include a fee that will also be automatically transfered to your own address in the same transaction.

Note: by default, all payments will be debited with a 10,000 satoshis mining fee. The amount of the fee is configurable. But for very small payments, if the amount sent is even lower than the fees, the forward will fail.

To create a basic payment forwarding:

POST https://api.blockcypher.com/v1/btc/main/payments
{
  "destination": "15qx9ug952GWGTNn7Uiv6vode4RcGrRemh",
  "callback_url": "https://my.domain.com/callbacks/new-block"
  "token": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

This will return the same document, adding the input address the payment should be directed to:

{
  "input_address": "16uKw7GsQSzfMaVTcT7tpFQkd7Rh9qcXWX",
  "destination": "15qx9ug952GWGTNn7Uiv6vode4RcGrRemh",
  "callback_url": "https://my.domain.com/callbacks/payments",
  "id": "399d0923-e920-48ee-8928-2051cbfbc369",
  "token": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Any money sent to 16uKw... will from then on be automatically transferred to 15qx9... In addition, the callback_url will be invoked with a POST request anytime a payment is made, providing a payment summary:

{
  "value": 100000000,
  "input_address": "16uKw7GsQSzfMaVTcT7tpFQkd7Rh9qcXWX",
  "input_transaction_hash": "39bed5d007d7ccf3ff0c150b580bc73d6f7e8c988063953da3ef964761b28b0d",
  "transaction_hash": "1aa6103d8dfc067ad42c4b9a5b157d0fc403b85064d852abbc162bb274cd9def"
}

A quick and easy way to test payments is to use curl to create a simple one without a callback (replace with your own address):

$ curl -d '{"destination": "17astdTmG8zzVmry8mV8A7atAr3XefEgRX"}' https://api.blockcypher.com/v1/btc/main/payments

Send some money to the returned input_address and watch it being instantly forwarded to your desintation address.

As previously mentioned, you may include an address you control to collect processing fees as part of your own service. The processing fee can be either a fixed fee in satoshis or a percentage of the whole amount. The mining fee will always be perceived on the processing fee (if large enough). Here is an example POST request to create a payment collecting a 10% fee:

POST https://api.blockcypher.com/v1/btc/main/payments
{
  "destination": "15qx9ug952GWGTNn7Uiv6vode4RcGrRemh",
  "callback_url": "https://my.domain.com/callbacks/new-block"
  "process_fees_address": "1LWw6FdzNUcX8bnekMMZ7eofcGF7SXmbrL",
  "process_fees_percent": 0.1,
  "token": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Details

The following endpoints are available for payments:

Name URL Pattern Example Method Description
Create /v1/{coin}/{chain}/payments /v1/btc/main/payments POST Sets up a new payment, returning the input_address that will automatically forward to the destination address as well as the payment id.
List /v1/{coin}/{chain}/payments?token={token} /v1/btc/main/payments?token=14df7860-eb44-11e3-ac10-0800200c9a66 GET Returns an array of payments associated with the provided token with their ids.
Delete /v1/{coin}/{chain}/payments/{id} /v1/btc/main/payments/399d0923-e920-48ee-8928-2051cbfbc369 DELETE Deletes a payment using its id.

A payment can have the following properties:

Property Example (abbreviated URLs and hashes) Description
id 399d0923-e920-48ee-8928-2051cbfbc369 Identifier of the payment forwarding, generated when a new payment is created.
token f47ac10b-58cc-4372-a567-0e02b2c3d479 User token, mandatory.
destination 15qx9ug952GWGTNn7Uiv6vode4RcGrRemh The destination address money will automatically be forwarded to. Required.
input_address 16uKw7GsQSzfMaVTcT7tpFQkd7Rh9qcXWX The address the payment should be made to to be forwarded, generated when the payment forwarding is created.
process_fees_address 16uKw7GsQSzfMaVTcT7tpFQkd7Rh9qcXWX Address to forward processing fees to, if specified. Allows you to perceive a fee for your own services. A satoshi amount or percentage are required if specified.
process_fees_satoshis 100000 Fixed processing fee amount to be sent to the fee address. A fixed satoshi amount or a percentage is required if a processing fee address has been provided.
process_fees_percent 0.05 Percentage of the transaction to be sent to the fee address. A fixed satoshi amount or a percentage is required if a processing fee address has been provided.
callback_url https://my.domain.com/callbacks/payments The URL to call anytime a new payment is forwarded. Optional.
enable_confirmations true Whether to also call the callback_url with subsequent confirmations of the forwarding transactions. Automatically sets up a WebHook.
mining_fees_satoshis 5000 Mining fees amount to include in the forward transaction, in satoshis. Default to 10,000.
transactions ["39bed5d...", "1aa6103..."] History of forwarding transactions for this payment.

When a new payment is forwarded, the document sent to you at the callback_url will have the following properties:

Property Example (abbreviated URLs and hashes) Description
value 100000000 Amount sent to the destination address, in Satoshi.
input_address 16uKw7GsQSzfMaVTcT7tpFQkd7Rh9qcXWX The address the payment was originally sent to.
destination 15qx9ug952GWGTNn7Uiv6vode4RcGrRemh The address the payment amount is being forwarded to.
input_transaction_hash 39bed5d... The transaction hash that credited the input address.
transaction_hash 1aa6103... The transaction hash of the generated transaction that forwards the payment from the input address to the destination.

Creating Transactions

Generic Transactions

There are 2 ways to send a generic transaction using our API:

  • Build the transaction yourself (using a 3rd party library) and push the raw hex-encoded string. We will broadcast to the network and track it for you.
  • Create the transaction with our API, the 2 addresses and the amount.

For security reasons, we do not keep any private keys, you are the only one who can sign transactions. Using our API, creating a transaction from scratch is a 3-step process:

  1. We build the unsigned transaction and the data to sign it from basic information: an input address or wallet name, an output address, and the value transferred.
  2. You sign the transaction data.
  3. We finish building the transaction, broadcast it over the peer-to-peer network, and send it back to you.

This is accomplished with two simple POST requests and a third one which allows you to push raw hexadecimal transactions:

Name URL Pattern Example Method Description
New /v1/{coin}/{chain}/txs/new /v1/btc/main/txs/new POST Takes transaction information and returns a partially built transaction with the data to sign.
Send /v1/{coin}/{chain}/txs/send /v1/btc/main/txs/send POST Takes the partially built transaction, signed data and public keys. Returns the completed transaction and transmits it over the network.
Push /v1/{coin}/{chain}/txs/push /v1/btc/main/txs/push POST If you're already building your own signed transaction, allows you to validate them and transmit them over the network. Takes the transaction's hex-encoded string in a {"tx": "12A45F67..."} JSON wrapper.
Decode /v1/{coin}/{chain}/txs/decode /v1/btc/main/txs/decode POST Decodes a hex-encoded raw transaction into a transaction JSON. Takes the transaction's hex-encoded string in a {"tx": "12A45F67..."} JSON wrapper. Does not do any additional processing (does not push).

When a transaction has been successfully sent (using the Send or Push endpoints), an HTTP status of 201 is returned.

Transaction Skeleton

A partially filled transaction is needed to create a full transaction. We require at least one input with a minimum of one address and at least one output with an address and value (in satoshis). For example:

{
  "inputs": [
    {"addresses": ["181w71oR7nTEsKducLBTUJkdbTvLDQzymL"]}
  ],
  "outputs": [
    {"addresses": ["1FGAsJFNgWvFz2tWQAnRq8S6fVX9Zmuxje"], "value": 4000000000}
  ]
}

You can also use a wallet name as input. This is equivalent to an array of all addresses in the wallet. This requires a user token.

{
  "inputs": [
    {"wallet_name": "alice_wallet", "wallet_token": "myusertoken"}
  ],
  "outputs": [
    {"addresses": ["1FGAsJFNgWvFz2tWQAnRq8S6fVX9Zmuxje"], "value": 4000000000}
  ]
}

We build the full set of inputs using unspent transactions from the input address(es) or wallet and fill up a temporary, unsigned transaction. Passing a negative value (like -1) will automatically generate a sweep, transferring the entire balance of the input address (minus potential fees).

By default, we allow spending from unconfirmed transactions. So unconfirmed transactions may be used as inputs of your transactions. To disable spending from unconfirmed transactions and force the selection of only confirmed inputs, provide a "confirmations" property of value 1.

{
  "confirmations": 1,
  "inputs": [
    {"addresses": ["181w71oR7nTEsKducLBTUJkdbTvLDQzymL"]}
  ],
  "outputs": [
    {"addresses": ["1FGAsJFNgWvFz2tWQAnRq8S6fVX9Zmuxje"], "value": 4000000000}
  ]
}

The document returned by a call to new uses the following format:

Property Example (abbreviated URLs and hashes) Description
errors [{"error": ""Address 1DEP... with balance 4271116 does not have enough funds to transfer 500000000."}] Array of errors encountered while generating the transaction. If the generation is successful, nothing will appear.
tx tx: {...} Temporary transaction, fully filled up except for the input scripts (requires signature).
tosign ["04779733bb...", "0396ea6f1b..."] Array of hexadecimal-encoded data to sign, one for each generated input.
signatures ["bcd2c363a2...", "dc621478..."] Array of hexadecimal-encoded signatures you need to provide.
pubkeys ["02c8d29d...", "02c8d29d..."] The public key for each generated input (in general, repeat the public key corresponding to the provided input address).

Note that low transaction fees are automatically included as required to ensure your transaction will be relayed.

Since the transaction is not yet complete yet, the transaction hash is a temporary one. The final hash will be calculated and returned with the completed transaction.

You may also provide inputs filled from the prev_hash and output_index properties. In this case, we use your inputs as provided and will not attempt to generate them from the address. Fees and change will still be inserted appropriately.

Finally, additional control over the generated script can be achieved by setting the script_type property, in particular for multisig outputs (which are pay-to-script-hash).

  1. pay-to-pubkey-hash (most common transaction transferring to a public key hash)
  2. pay-to-multi-pubkey-hash (multi-signatures transaction)
  3. pay-to-pubkey (used for mining transactions)
  4. pay-to-script-hash (used for transactions relying on arbitrary scripts, rarely used)
  5. null-data, sometimes called op-return (used to embed small chunks of data in the block chain)
  6. empty (no script present, mostly used for the input of a mining transaction)
  7. unknown (non-standard script)
Example

The following example will create 2 inputs because 2 previous transactions must be used for the requested amount. It also creates 2 outputs, one for the required transaction and another for the change.

POST https://api.blockcypher.com/v1/btc/main/txs/new
> {
>   "inputs": [
>     {"addresses": ["1DEP8i3QJCsomS4BSMY2RpU1upv62aGvhD"]}
>   ],
>   "outputs": [
>     {"addresses": ["1FGAsJFNgWvFz2tWQAnRq8S6fVX9Zmuxje"], "value": 500000}
>   ] 
> }
{
  "tx": {
    "block_height": -1,
    "hash": "f961dea839fd69653547a0308360de67846a49d3593f7459773e27af8d9f5ec0",
    "addresses": [
      "1DEP8i3QJCsomS4BSMY2RpU1upv62aGvhD",
      "1FGAsJFNgWvFz2tWQAnRq8S6fVX9Zmuxje",
    ],
    "total": 661116,
    "fees": 10000,
    "received": "2014-04-20T23:52:21.069978821Z",
    "ver": 1,
    "lock_time": 0,
    "vin_sz": 2,
    "vout_sz": 2,
    "confirmed": 0,
    "inputs": [
      {
        "prev_hash": "0c83c8321537a7c79dc6214788944ba6cd5ea76f0594453b6251fcf1856f2e4b",
        "output_index": 0,
        "script": "",
        "output_value": 171116,
        "addresses": [
          "1DEP8i3QJCsomS4BSMY2RpU1upv62aGvhD"
        ],
        "script_type": "pay-to-pubkey-hash"
      },
      {
        "prev_hash": "995a50e05d197be88d4da74160b4bcd2c363ebb1a49f95e572667d580bc70aba",
        "output_index": 0,
        "script": "",
        "output_value": 500000,
        "addresses": [
          "1DEP8i3QJCsomS4BSMY2RpU1upv62aGvhD"
        ],
        "script_type": "pay-to-pubkey-hash"
      }
    ],
    "outputs": [
      {
        "value": 500000,
        "script": "76a9149c703cb3e9f1a2a154e548b3acafd0054d4835a788ac",
        "addresses": [
          "1FGAsJFNgWvFz2tWQAnRq8S6fVX9Zmuxje"
        ],
        "script_type": "pay-to-pubkey-hash"
      },
      {
        "value": 161116,
        "script": "76a9148629647bd642a2372d846a7660e210c8414f047c88ac",
        "addresses": [
          "1DEP8i3QJCsomS4BSMY2RpU1upv62aGvhD"
        ],
        "script_type": "pay-to-pubkey-hash"
      }
    ]
  },
  "tosign": [
    "04779733bba8085dd86c21d86c8f9e786a1124751c42061d4c539229a07c4464",
    "0396ea6f1bf7493e738339bd720267e7281144b222343ffe4167e00792c62ff2"
  ]
}

Error Handling

When something is wrong with the provided transaction, the server will reply with a 400 HTTP error code. It will also return a JSON document that includes the transaction and an errors section listing the different issues that were encountered. If you're experiencing any difficulty, please check the returned errors.

{
  "tx": { ... },
  "errors": [
    {"error": "..."}
  ]
}

The most common issue is the absence of confirmed unspent outputs to build the transaction from. By default, spending unconfirmed transactions isn't enabled, so you may not be able to issue a 2nd transaction until the first has been confirmed. To enable spending from unconfirmed transactions, in the partially filled transaction provided to the new endpoint add "confirmations: -1".

The second most common issue is to use uncompressed public keys when compressed public keys were used to generate the address. If the script generated can't be verified, try passing compressed public keys instead.

Change and Fees

No matter the type of transaction built, the change (leftover from the inputs once all outputs are credited the requested amount) will generally be credited to the address referenced in the first transaction input. An additional output will be created to set this up.

To force change to be credited to a specific address, set the change_address property on the transaction skeleton provided to the transaction API.

Fee calculation in cryptocurrencies can be complex. We provide 2 different ways for you to control the fees included in your transactions:

  • Set the preference property in your transaction skeleton to "high", "medium" or "low". This will calculate and include appropriate fees for your transaction to be included in the next 1-2 blocks, 3-5 blocks or 5 or more blocks respectively. The default fee calculation is based on a high preference. A preference set to "zero" will set no fee.
  • Force the fee to a desired amount by setting it in the fees property of the transaction skeleton. Note that a fee too low may result in an error for some transactions that would require it.

Fees are required for many transactions and you can't easily determine whether a transaction will require a fee. If you still want to generate a 0-fee transaction, use the "zero" preference to test whether it is valid first. We will return an error if the transaction require a fee, at which point you can set the preference to a higher level accordingly.

To learn more about fees, bitcoinfees.com is a good resource.

Micro Transactions

Micro transactions have the following characteristics:

  • The value is between 2000 satoshis (~0.5 cents) and 4000000 satoshis (~$9).
  • BlockCypher pays the mining fees (up to your first 8,000 transactions).
  • Transactions are guaranted by BlockCypher as soon as our confidence factor reaches 99% (after 8 sec on average).

Getting Started

To facilitate testing and integration in cases where addresses only have low value (which is very common for micro-transactions), we allow passing a private key so we can directly build, sign and send the transaction. Passing a change address is also supported to mitigate long-term risks. In all other cases, passing only the public key and signing yourself is recommended for security reasons (see security considerations).

The simplest way to send a micro-transaction is the following, passing a hex-encoded private key (again keep in mind that passing your private key is discouraged for everything but low-value wallets):

curl -H "Content-Type: application/json" \
     -d '{"from_private": "...", "to_address": "...", "value_satoshis": 500000,
          "wait_guarantee": true, "token": "..."}' \
     https://api.blockcypher.com/v1/btc/main/txs/micro

This call will hold until the transaction confidence has reached 99%. When it returns the transaction is guaranteed by our services. The response will also include a hash property which is the hash of the broadcasted transaction.

The same can be achieved securely for higher value addresses by providing the public key instead. You will have to sign the required data returned by the microtx endpoint to complete the transaction (see Signing and Sending). Here is an example command-line session on bitcoin's testnet:

# the returned document includes the hex to sign
$ curl -X POST https://api.blockcypher.com/v1/btc/test3/txs/micro?from_pubkey=03bb31...&to_address=mrS8...&value_satoshis=5000&token=...
{
  "from_pubkey": "03bb318b00de944086fad67ab78a832eb1bf26916053ecd3b14a3f48f9fbe0821f",
  "to_address": "mrS82nWF3TCfhafSaKnmUUktGNYuTZn1Ap",
  "value_satoshis": 5000,
  "tosign": [
    "a1b1d20af6588531dd3812921221ac1b49496f5b05a63e50e78365c0a3d208d7"
  ],
  "token": "477a17a15d55b408038404a46c059ef9"
}
# any signing library should work, here we use the tool at
# https://github.com/blockcypher/btcutils/tree/master/signer
$ ./signer a1b1d20af6588531dd3812921221ac1b49496f5b05a63e50e78365c0a3d208d7 $PRIVATE_KEY
3045022100...
# we build a json document including our original transaction and simply adding the generated signature
$ cat microtx_signed.json 
{
  "from_pubkey": "03bb318b00de944086fad67ab78a832eb1bf26916053ecd3b14a3f48f9fbe0821f",
  "to_address": "mrS82nWF3TCfhafSaKnmUUktGNYuTZn1Ap",
  "value_satoshis": 5000,
  "token": "477a17a15d55b408038404a46c059ef9",
  "signatures": [
    "3045022100..."
  ]
}
# calling the microtx endpoint again this time passing the signatures will send the transaction
$ curl -H "Content-Type: application/json" -d @microtx_signed.json https://api.blockcypher.com/v1/btc/test3/txs/micro
{
  "from_pubkey": "03bb318b00de944086fad67ab78a832eb1bf26916053ecd3b14a3f48f9fbe0821f",
  "to_address": "mrS82nWF3TCfhafSaKnmUUktGNYuTZn1Ap",
  "value_satoshis": 5000,
  "hash": "1611421e265a831f108fc004b02b293ee381c8bfdc01e52a717cc154f7173904"
}

Note that the public keys as well as the signatures are hex-encoded.

Micro Transaction Properties

The properties for micro-transactions can either be provided in a JSON document or in the URL query string. They're sent as a POST to the /txs/micro endpoint.

When initiating a micro-transaction using the public key, the response to a POST on the endpoint will return an array of hex-encoded data that should be signed. The signatures should be sent back using the same request as previous, adding the signatures property (send Signing and Sending for more details).

Name Example Description
from_pubkey 03bb318b00... Hex-encoded public key to send the coins from.
from_private 1af97b1f... Hex-encoded private key to send the coins from.
from_wif L4hgYtQ9... WIF encoding of the private key to send the coins from.
to_address 1GGdUQcS1f2ynd9MbDyxHJmKBWPKKtKDX9 Target address that will receive the coins.
change_address 1FY2VfGAfrkLLkFkENrDCiqFhbNxHjhRU1 Address to use to send back the change. Defaults to the address calculated from the input public or private keys.
value_satoshis 10000 Amount transferred in satoshis.
wait_guarantee true Wait for the transaction to be guaranteed by BlockCypher (usually ~8 sec). If false will return as soon as the transaction is broadcasted.
token Your API token.
tosign ["ab125a...", "9f034de..."] Data to sign after having initiated the micro-transaction. Sent in reply to a micro-transaction passing the pubkey.
signatures ["3045...", "3046..."] Hex-encoded signatures to send back after having received the data to sign.
hash 3cf5c1fb0443... The hash of the finalized transaction, once sent.

Only the transaction value, the target address, your API token and one of the from pubkey, private or wif are required.

Security Considerations

In general, sending any private key to an outside service is a bad security practice and is discouraged. However security and ease of use are often in opposition. When it comes to deciding whether to pass a private key for micro-transactions is a reasonable tradeoff, the following should be considered:

  • The private key data is sent in a JSON document over SSL, protecting against eavesdroppers.
  • We never log or keep any private key. They're just present on our systems during the time of signing.
  • The use of a different change addresses is encouraged, so the money gets transferred to another private key (potentially over several uses).
  • Regardless of the above, never pass a private key for addresses with high value. The micro-transaction API is meant for low-value transactions and low-value addresses.

Finally, the option of passing private keys is only offered because signing on the client side can be difficult depending on the environment. We hope that using this information, you will make the right tradeoff for your situation.

Signing and Sending

Use your private key(s) to sign each of the data strings provided (decode them to byte arrays and use ECDSA). Return the signatures as hex-encoded strings in a signatures array property inserted in the previous document.

{
  "tx": { ... },
  "tosign": [
    "04779733bba8085dd86c21d86c8f9e786a1124751c42061d4c539229a07c4464",
    "0396ea6f1bf7493e738339bd720267e7281144b222343ffe4167e00792c62ff2"
  ],
  "signatures": [
    "3045022100e91585519a9b637e122558644b67d6e9de618f906943aaeb00c95d3...",
    "304502207df92c19101048de8a8a4fcb2cfb62ac937dfc6cf34c7fc8465336bfc..."
  ],
  "pubkeys": [
    "02c8d29d8c8afb4725d25a1ec496aeddc36fa9eb6f0e014bfc21742fc3d78cb438",
    "02c8d29d8c8afb4725d25a1ec496aeddc36fa9eb6f0e014bfc21742fc3d78cb438"
  ]
}

Note: for multisig transactions, the pubkeys are already provided which each input so they should not be included again.

Additionally, for each input the public key matching the input address must be provided because the input address cannot be calculated from the address. In general, repeat the public key for the address provided in the transaction skeleton input.

Here's an example showing how to sign the transaction in Javascript using the bitcoinjs library:


  var key     = new bitcoin.ECKey(bigi.fromHex(source.private), true);
  var pubkeys = [];
  var signatures  = newtx.tosign.map(function(tosign) {
    pubkeys.push(source.public);
    return key.sign(new buffer.Buffer(tosign, "hex")).toDER().toString("hex");
  });
  newtx.signatures  = signatures;
  newtx.pubkeys     = pubkeys;

Once signatures are inserted, POST the resulting document to the send resource (under /v1/{coin}/{chain}/txs/send for generic transacions, /v1/{coin}/{chain}/txs/microtx for micro-transactions). The same document will be returned with the finalized transaction. If no errors are returned, your transaction was successfully issued and broadcasted across the network.

See our full sample to issue a transaction on testnet from your browser.

Validating the Data to Sign

To protect yourself further from a potential malicious attack on our services, you may want to validate the data we're asking you to sign. Unfortunately it's impossible drectly as the data is hashed twice using SHA256 so you can't get back to the original transaction. To allow you to still validate, the includeToSignTx URL property is accepted on the call the txs/new. An additional tosign_tx array will be returned that you can use in the following way:

  • Hashing the hex-encoded string twice using SHA256 should give you back the corresponding tosign data.
  • Decoding the hex-encoded string using our txs/decode endpoint (or an independent source) should give you output addresses and amounts that match your transaction skeleton.

Note that the Bitcoin signature algorithm does not necessarily preserve inputs. Inputs other than the one you're signing are usually empty and the input you're signing will have a different script.

Following is a full example using the command line (or this gist for the full non-abbreviated session). The hashes returned on Mac OS may be wrong due to a bug in xxd.


$ curl -d '{"inputs": [{"addresses": ["mtWg6ccLiZWw2Et7E5UqmHsYgrAi5wqiov"]}],
            "outputs":[{"addresses": ["mzUqjgiGc3Mqh5zMiP5vXDNd7Hwx3K1xCU"], "value": 25000}]}' \
            https://api.blockcypher.com/v1/btc/test3/txs/new?includeToSignTx=true
{
  "tx": { ... },
  "tosign_tx": [
    "0100000001fc6e024dc7e9caa6d5530db88c712b7220d25a9ed5a052b7fd183c4ecdc21a91010000001976a9148e8c1d4adef86c11154fd04b5012306715fd4baf88acffffffff02a8610000000000001976a914d004156436b38ef464b01286cdc9c4b36c99c68788ac38dd6501000000001976a9148e8c1d4adef86c11154fd04b5012306715fd4baf88ac0000000001000000"
  ],
  "tosign": [
    "b365bef9aae17e0d35963217d65915a2a00bc782f1bb1be5061a18d92063309e"
  ]
}

# Check the tosign_tx data (replace abbreviated string with above data) with decode to validate
# inputs and outputs. Note that you can also use an independent source to do this verification
# (like other APIs or Bitcoin Core).
$ curl -d '{"tx": "0100000001fc6e..."}' https://api.blockcypher.com/v1/btc/test3/txs/decode

# Validate that tosign is equal to tosign_tx after 2 rounds of sha256 hashing
$ echo -n "0100000001fc6e..." | xxd -r -p | shasum -a 256 -b
f80804283c023d50bdf3ba6a4f938dc2e65767b8aa55414ea6aae9ef410a55a6 *-
$ echo -n "f80804283c023d50bdf3ba6a4f938dc2e65767b8aa55414ea6aae9ef410a55a6" | xxd -r -p | shasum -a 256 -b
b365bef9aae17e0d35963217d65915a2a00bc782f1bb1be5061a18d92063309e *-

Multisig Transactions

Our multiple signature transaction API works similarly to our classic transaction API with a few differences:

  • A script type of multisig-N-of-M must be set (with N and M replaced by actual numbers, like multisig-2-of-3).
  • Public keys must be provided instead of addresses for the multisig inputs or outputs.

Note that if you simply want to generate a multisig address from the different public keys instead of a whole transaction, our address generation endpoint will help you do that.

For a multisig interaction to happen, first the multisig address has to be sent some money using a transaction that includes M public keys in its output. Then that transaction can be spent by another by repeatedly issuing the required N number of signature. The interaction can be broken down as follows:

  1. Call the txs/new endpoint to create a funding transaction. For a 2-of-3 transaction:
    {
        "inputs": [{"addresses": [sourceAddr]}],
        "outputs": [{
          "addresses"   : [pubkey1, pubkey2, pubkey3],
          "script_type" : "multisig-2-of-3",
          "value"       : 250000,
        }]
      }
  2. Sign the returned hex string and post it with the transaction to txs/send. The multisig address is now funded.

To spend the previous transaction, each party (e.g., 3 in a 3-of-4 multisig) needs to send a new signed multisig transaction, specifying the public keys and script_type for input and the receiving address as output:

  1. Call the txs/new endpoint to create the spending transaction. For example:
    {
      "inputs": [{
        "addresses"   : [pubkey1, pubkey2, pubkey3],
        "script_type" : "multisig-2-of-3"
      }],
      "outputs": [{
        "addresses" : [destAddr],
        "value"     : 150000
      }]
    }
  2. Sign the returned hex string and post it with the transaction to txs/send. We correlate each call based on the pubkeys/destination/amount and will send the transaction automatically once we have enough signatures.

Alternatively, instead of having each party call our API, you may also share the hex string to sign and provide the required signatures all at once. Note that in all cases, the order in which the public keys are provided matters and should be consistent, as required for Bitcoin P2SH transactions. Remaining funds (change) will be sent back to the multisig address.

See our full Javascript sample for how to issue a 2 out of 3 multisig transaction.

Note: if you're using a blockexplorer to check a transaction, be aware that blockchain.info does not support pay-to-script transactions and will not show the transaction until it's confirmed. We recommend using our block explorer instead.