NAV
cURL

Introduction

#   ^
#  / \    _               _
# / ^ \  |_) |  _   _ |  /     ._  |_   _  ._
#<     > |_) | (_) (_ |< \_ \/ |_) | | (/_ |
# \ v /                     /  |
#  \ /
#   v

Welcome to BlockCypher’s Ethereum API documentation! If you’re familiar with our Bitcoin endpoints, you’ll feel right at home with our Ethereum API. However, there are a few differences, and they stem in part from the fundamental differences between Bitcoin and Ethereum. In the most abstract sense, Bitcoin and Ethereum are cousins; they both have “blocks” of transactions linked together into a chain, they both use Proof of Work to reach consensus (for now, as Ethereum plans to move to Proof of Stake in a future release), they are both about decentralizing trust. But that’s where the similarities end. Here are just some of Ethereum’s differences:

In a nutshell, Bitcoin is about decentralized, trust-minimizing, sound money. Ethereum is about decentralized, trust-minimizing, sound computation. Much more detail about these differences can be read at the Ethereum Wiki here. You can find more information at the project’s webpage as well.

Documentation Structure

man curl | grep -A 3 "DESCRIPTION"

DESCRIPTION
curl is a tool to transfer data from or to a server, using one of the supported protocols (DICT, FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET and TFTP). The command is designed to work without user interaction.

In these docs you’ll find everything you need to start working with Ethereum with BlockCypher. For now, you’ll see cURL examples for interacting with the Ethereum blockchain, but we’ll add SDK examples as we support them.

Section Summaries

Changelog and Errors

Our documentation is powered by GitHub Pages and Slate, which makes viewing changes as simple as checking the git commit history. If there’s an error or you’d like to suggest a change, please consider submitting a pull request to benefit the broader BlockCypher community.

API Versions

All API calls are versioned, and the current BlockCypher API is v1. The BlockCypher Ethereum API is currently in beta, and we hope not to introduce any breaking changes, but until it’s out of beta we can’t make that guarantee until it’s stable.

RESTful Resources

curl -s https://api.blockcypher.com/v1/eth/main
{
  "name": "ETH.main",
  "height": 1663353,
  "hash": "863dda1124f2b438c607f5b8d00e8511f6f8d206b21aad3b9c460b8c5221e31b",
  "time": "2016-06-08T00:46:34.795856213Z",
  "latest_url": "https://api.blockcypher.com/v1/eth/main/blocks/863dda1124f2b438c607f5b8d00e8511f6f8d206b21aad3b9c460b8c5221e31b",
  "previous_hash": "783aa3ef1b45121ee5bc33acb6c5986d6132d04cf20c85ba256b155b2c196006",
  "previous_url": "https://api.blockcypher.com/v1/eth/main/blocks/783aa3ef1b45121ee5bc33acb6c5986d6132d04cf20c85ba256b155b2c196006",
  "peer_count": 52,
  "unconfirmed_count": 11924,
  "high_gas_price": 40000000000,
  "medium_gas_price": 20000000000,
  "low_gas_price": 5000000000,
  "last_fork_height": 1661588,
  "last_fork_hash": "79075d95aacc6ac50dbdf58da044af396ca97e09cbb31527809579cc96f1c8a7"
}

Almost all resources exist under a given blockchain, and follow this pattern:

https://api.blockcypher.com/$API_VERSION/$COIN/$CHAIN/

Currently, there’s only one version of the API (v1). For Ethereum, there are the available blockchains:

Coin Chain Resource
Ethereum Main api.blockcypher.com/v1/eth/main
BlockCypher Test api.blockcypher.com/v1/beth/test

Rate Limits and Tokens

# Adding your token as URL parameter
curl https://api.blockcypher.com/v1/eth/main?token=YOURTOKEN

# Checking your token's limits
curl https://api.blockcypher.com/v1/tokens/YOURTOKEN
{
"token": "YOURTOKEN",
"limits": {
    "api/hour": 10000,
    "api/second": 500,
    "hooks/hour": 5000,
    "confidence/hour": 1000,
    "hooks": 5000,
    "payments": 5000
},
"hits": {
    "api/hour": 280,
    "hooks/hour": 240,
    "confidence/hour": 100
}
}
# These are quite above the default limits, but if you'd like them, reach out at contact@blockcypher.com ;)

We want everyone to try BlockCypher with as little friction as possible, which is why you don’t need a token for any read-only GET calls. Please register for a user token if you want to use POST and DELETE calls. Once you have your token, you can append it to all your requests like any other URL parameter.

We do rate-limit our free tier, with or without a token (though tokens are required for Confidence lookups, WebHooks/Sockets, Payments, and any POST or DELETE calls):

On the accounts page, you’ll find paid plans starting at $75 a month (with a 10% discount if you pay with Bitcoin). To request higher limits or SLAs beyond what’s offered on the accounts page, please email us.

You can check your current limits and usage via a GET on the following endpoint, outside of our normal coin/chain pattern:

https://api.blockcypher.com/v1/tokens/YOURTOKEN

Batching

# Batching blocks 5, 6, and 7 from Ethereum
curl 'https://api.blockcypher.com/v1/eth/main/blocks/5;6;7'
[{
  "hash": "f37c632d361e0a93f08ba29b1a2c708d9caa3ee19d1ee8d2a02612bffe49f0a9",
  "height": 5,
  "chain": "ETH.main",
  "total": 0,
  "fees": 0,
  "size": 537,
  "ver": 0,
  "time": "2015-07-30T15:28:03Z",
  "received_time": "2015-07-30T15:28:03Z",
  "coinbase_addr": "05a56e2d52c817161883f50c441c3228cfe54d9f",
  "relayed_by": "",
  "nonce": 18134254966252788979,
  "n_tx": 0,
  "prev_block": "23adf5a3be0f5235b36941bcb29b62504278ec5b9cdfa277b992ba4a7a3cd3a2",
  "mrkl_root": "4470f3dc1cc8097394a4ae85302eac3368462b3c1cfa523ffca942c1dd478220",
  "txids": [],
  "depth": 1656648,
  "prev_block_url": "https://api.blockcypher.com/v1/eth/main/blocks/23adf5a3be0f5235b36941bcb29b62504278ec5b9cdfa277b992ba4a7a3cd3a2",
  "tx_url": "https://api.blockcypher.com/v1/eth/main/txs/"
},
{
  "hash": "1f1aed8e3694a067496c248e61879cda99b0709a1dfbacd0b693750df06b326e",
  "height": 6,
  "chain": "ETH.main",
  "total": 0,
  "fees": 0,
  "size": 537,
  "ver": 0,
  "time": "2015-07-30T15:28:27Z",
  "received_time": "2015-07-30T15:28:27Z",
  "coinbase_addr": "0193d941b50d91be6567c7ee1c0fe7af498b4137",
  "relayed_by": "",
  "nonce": 8915216988711600153,
  "n_tx": 0,
  "prev_block": "f37c632d361e0a93f08ba29b1a2c708d9caa3ee19d1ee8d2a02612bffe49f0a9",
  "mrkl_root": "c211464e6957ae62a33c2146cf36371222ea4557c42efe9c618971e09d056aae",
  "txids": [],
  "depth": 1656647,
  "prev_block_url": "https://api.blockcypher.com/v1/eth/main/blocks/f37c632d361e0a93f08ba29b1a2c708d9caa3ee19d1ee8d2a02612bffe49f0a9",
  "tx_url": "https://api.blockcypher.com/v1/eth/main/txs/"
},
{
  "hash": "e0c7c0b46e116b874354dce6f64b8581bd239186b03f30a978e3dc38656f723a",
  "height": 7,
  "chain": "ETH.main",
  "total": 0,
  "fees": 0,
  "size": 1078,
  "ver": 0,
  "time": "2015-07-30T15:28:30Z",
  "received_time": "2015-07-30T15:28:30Z",
  "coinbase_addr": "dd2f1e6e498202e86d8f5442af596580a4f03c2c",
  "relayed_by": "",
  "nonce": 13599487003767981,
  "n_tx": 0,
  "prev_block": "1f1aed8e3694a067496c248e61879cda99b0709a1dfbacd0b693750df06b326e",
  "mrkl_root": "ff8d97d9ca01ee59c793c4da2ba4ce8c31d358b42f216ab2f11af4bb097b6a2b",
  "uncles": [
    "4b8729311c5b59f418c5154fd54d85e6a8b42eabf83a1d3c05c754a8f10354cc"
  ],
  "txids": [],
  "depth": 1656646,
  "prev_block_url": "https://api.blockcypher.com/v1/eth/main/blocks/1f1aed8e3694a067496c248e61879cda99b0709a1dfbacd0b693750df06b326e",
  "tx_url": "https://api.blockcypher.com/v1/eth/main/txs/"
}]

All endpoints that can retrieve a single Object can be batched to return multiple objects. If you’re cURLing the API directly, batching simply requires appending each identifier to the previous one using a semicolon (check the code pane for an example). The results are aggregated in a JSON array.

When cURLing BlockCypher, batching also works when the identifiers aren’t the last part of the URL; e.g., this URL will return the balances of three separate addresses:

https://api.blockcypher.com/v1/btc/main/addrs/1J38WorKngZLJvA7qMin9g5jqUfTQUBZNE;1JP8FqoXtCMrR1sZc2McLWmHxENox1Y1PV;1ENn7XmqXNnReiQEFHhBGzfiv5gAyBj7r1/balance

Testing

To ease your development process, we offer an Ethereum-compatible internal testnet and faucet. It is identical in form and function to Ethereum mainnet (including the same address/account format and EVM). The chain is private (no data is broadcast, only BlockCypher mines the transactions).

In case you missed the Resources section, the BlockCypher Ethereum Testnet is accessible from this resource:

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

# Note resource change to beth/test instead of eth/main
# Make new address; returns private key/public key/address
curl -sX POST https://api.blockcypher.com/v1/beth/test/addrs?token=$YOURTOKEN
{
  "private": "a98e4f4181805a89322a1cff0da749fe297e3b44d18f17d55a86d4c64c9d5489",
  "public": "04ec8be2b66782caf8ba4158bf7a2027aaebdcd8a2dbcb52bd9f81668748671a0a3a5494bb85b0a10b3f52ac812246c8bc4c0269d92ef7d9e015090233044b40fe",
  "address": "1585a07efe60806132c994eb39b5f33f55a1eff8"
}

# Fund prior address with faucet, in wei
curl -sd '{"address": "1585a07efe60806132c994eb39b5f33f55a1eff8", "amount": 1000000000000000000}' https://api.blockcypher.com/v1/beth/test/faucet?token=$YOURTOKEN
{
  "tx_ref": "a4de50532f1a2b59cd50242ba98f5849aea691ae618c58efc05895cd7786a3d1"
}

Test Faucets

To help facilitate automated testing in your applications, a faucet endpoint is available on BlockCypher’s Ethereum Testnet. Calling the faucet endpoint, along with passing a valid address, will automatically create—and propagate—a new transaction funding the address with the amount you provide. You can then use the funded address to publish contracts, engage in other transactions, or to aid in automated testing.

This example shows how to leverage the faucet to programmatically fund addresses.

Objects

# All cURL'd Objects are JSON:

{
    key: value,
    key: value,
}

Before diving into BlockCypher’s endpoints, this section details all the Objects exposed and expected by the API. Some of you might be more interested in the endpoints themselves, in which case, feel free to skip to the next section. For each Object there’s a description and a link to a germane API endpoint.

Blockchain

curl -s https://api.blockcypher.com/v1/eth/main
{
  "name": "ETH.main",
  "height": 1663099,
  "hash": "72c4b2773c41cc33fb7f708d1d410d4225706292b795e24e3f6f859927c0b932",
  "time": "2016-06-07T23:44:03.834909578Z",
  "latest_url": "https://api.blockcypher.com/v1/eth/main/blocks/72c4b2773c41cc33fb7f708d1d410d4225706292b795e24e3f6f859927c0b932",
  "previous_hash": "1060a6d4870aed200cb84c83c26203331f433d08f34c13b7de10c400866e43b1",
  "previous_url": "https://api.blockcypher.com/v1/eth/main/blocks/1060a6d4870aed200cb84c83c26203331f433d08f34c13b7de10c400866e43b1",
  "peer_count": 83,
  "unconfirmed_count": 11904,
  "high_gas_price": 40000000000,
  "medium_gas_price": 20000000000,
  "low_gas_price": 5000000000,
  "last_fork_height": 1661588,
  "last_fork_hash": "79075d95aacc6ac50dbdf58da044af396ca97e09cbb31527809579cc96f1c8a7"
}

A Blockchain represents the current state of the Ethereum blockchain. Typically returned from the Chain API endpoint.

Attribute Type Description
name string The name of the blockchain represented, in the form of $COIN.$CHAIN.
height integer The current height of the blockchain; i.e., the number of blocks in the blockchain.
hash string The hash of the latest confirmed block in the blockchain; in Ethereum, the hashing function is Keccak/SHA3.
time time The time of the latest update to the blockchain; typically when the latest block was added.
latest_url url The BlockCypher URL to query for more information on the latest confirmed block; returns a Block.
previous_hash string The hash of the second-to-latest confirmed block in the blockchain.
previous_url url The BlockCypher URL to query for more information on the second-to-latest confirmed block; returns a Block.
unconfirmed_count integer Number of unconfirmed transactions in memory pool (likely to be included in next block).
high_gas_price integer A rolling average of the gas price (in wei) for transactions to be confirmed within 1 to 2 blocks.
medium_gas_price integer A rolling average of the gas price (in wei) for transactions to be confirmed within 3 to 6 blocks.
low_gas_price integer A rolling average of the gas price (in wei) for transactions to be confirmed in 7 or more blocks.
last_fork_height integer Optional The current height of the latest fork to the blockchain; when no competing blockchain fork present, not returned with endpoints that return Blockchains.
last_fork_hash string Optional The hash of the latest confirmed block in the latest fork of the blockchain; when no competing blockchain fork present, not returned with endpoints that return Blockchains.

Block

curl -s https://api.blockcypher.com/v1/eth/main/blocks/7
{
  "hash": "e0c7c0b46e116b874354dce6f64b8581bd239186b03f30a978e3dc38656f723a",
  "height": 7,
  "chain": "ETH.main",
  "total": 0,
  "fees": 0,
  "size": 1078,
  "ver": 0,
  "time": "2015-07-30T15:28:30Z",
  "received_time": "2015-07-30T15:28:30Z",
  "coinbase_addr": "dd2f1e6e498202e86d8f5442af596580a4f03c2c",
  "relayed_by": "",
  "nonce": 13599487003767981,
  "n_tx": 0,
  "prev_block": "1f1aed8e3694a067496c248e61879cda99b0709a1dfbacd0b693750df06b326e",
  "mrkl_root": "ff8d97d9ca01ee59c793c4da2ba4ce8c31d358b42f216ab2f11af4bb097b6a2b",
  "uncles": [
    "4b8729311c5b59f418c5154fd54d85e6a8b42eabf83a1d3c05c754a8f10354cc"
  ],
  "txids": [],
    "internal_txids": [],
  "depth": 1656646,
  "prev_block_url": "https://api.blockcypher.com/v1/eth/main/blocks/1f1aed8e3694a067496c248e61879cda99b0709a1dfbacd0b693750df06b326e",
  "tx_url": "https://api.blockcypher.com/v1/eth/main/txs/"
}

A Block represents the current state of a particular block from a Blockchain. Typically returned from the Block Hash and Block Height endpoints.

Attribute Type Description
hash string The hash of the block; in Ethereum, the hashing function is Keccak/SHA3
height integer The height of the block in the blockchain; i.e., there are height earlier blocks in its blockchain.
depth integer The depth of the block in the blockchain; i.e., there are depth later blocks in its blockchain.
chain string The name of the blockchain represented, in the form of $COIN.$CHAIN
total integer The total number of wei transacted in this block.
fees integer The total number of fees—in wei—collected by miners in this block.
size integer Raw size of block (including header and all transactions) in bytes.
ver integer Block version.
time time Recorded time at which block was built.
received_time time The time BlockCypher’s servers receive the block.
coinbase_addr string The Ethereum address of the miner that received the coinbase and fee reward.
relayed_by string Address of the peer that sent BlockCypher’s servers this block.
nonce integer The number used by a miner to generate this block.
n_tx integer Number of transactions in this block.
prev_block string The hash of the previous block in the blockchain.
prev_block_url url The BlockCypher URL to query for more information on the previous block.
tx_url url The base BlockCypher URL to receive transaction details. To get more details about specific transactions, you must concatenate this URL with the desired transaction hash(es).
mrkl_root string The Merkle root of this block.
txids array[string] An array of transaction hashes in this block (initiated by externally controlled accounts). By default, only 20 are included.
internal_txids array[string] An array of internal transaction hashes (initiated by internal contracts) in this block. By default, only 20 are included.
next_txids url Optional If there are more transactions that couldn’t fit in the txids array, this is the BlockCypher URL to query the next set of transactions (within a Block object).
next_internal_txids url Optional If there are more internal transactions that couldn’t fit in the internal_txids array, this is the BlockCypher URL to query the next set of transactions (within a Block object).
uncles array[string] List of uncle blocks by hash included by the miner of this block. You can read more about uncles here.

TX

curl -s https://api.blockcypher.com/v1/eth/main/txs/8f39fb4940c084460da00a876a521ef2ba84ad6ea8d2f5628c9f1f8aeb395342
{
  "block_hash": "b35265965f6f14c5d692b2030922fce53067fc0e9d8c8490c31d4ecd3e46500c",
  "block_height": 1564040,
  "block_index": 0,
  "hash": "8f39fb4940c084460da00a876a521ef2ba84ad6ea8d2f5628c9f1f8aeb395342",
  "addresses": [
    "738d145faabb1e00cf5a017588a9c0f998318012",
    "4e9d8b4f18d984f6f0c88d07e4b39201e825cd17"
  ],
  "total": 10153153359437326,
  "fees": 1595580000000000,
  "size": 116,
  "gas_used": 79779,
  "gas_price": 20000000000,
  "relayed_by": "",
  "confirmed": "2016-05-22T12:43:00Z",
  "received": "2016-05-22T12:43:00Z",
  "ver": 0,
  "double_spend": false,
  "vin_sz": 1,
  "vout_sz": 1,
  "confirmations": 99100,
  "confidence": 1,
  "inputs": [
    {
      "sequence": 273,
      "addresses": [
        "738d145faabb1e00cf5a017588a9c0f998318012"
      ]
    }
  ],
  "outputs": [
    {
      "value": 10153153359437326,
      "script": "4e71d92d",
      "addresses": [
        "4e9d8b4f18d984f6f0c88d07e4b39201e825cd17"
      ]
    }
  ]
}

A TX represents the current state of a particular transaction from either a Block within a Blockchain, or an unconfirmed transaction that has yet to be included in a Block.

Attribute Type Description
block_height integer Height of the block that contains this transaction. If this is an unconfirmed transaction, it will equal -1.
hash string The hash of the transaction.
addresses array[string] Array of Ethereum addresses involved in the transaction.
total integer The total number of wei exchanged in this transaction.
fees integer The total number of fees—in wei—collected by miners in this transaction. Equal to gas_price * gas_used.
size integer The size of the transaction in bytes.
gas_used integer The amount of gas used by this transaction.
gas_price integer The price of gas—in wei—in this transaction.
relayed_by string Address of the peer that sent BlockCypher’s servers this transaction. May be empty.
received time Time this transaction was received by BlockCypher’s servers.
ver integer Version number of this transaction.
double_spend bool true if this is an attempted double spend; false otherwise.
vin_sz integer Total number of inputs in the transaction.
vout_sz integer Total number of outputs in the transaction.
confirmations integer Number of subsequent blocks, including the block the transaction is in. Unconfirmed transactions have 0 confirmations.
inputs Object An array object containing a single input with a sequence number (used as a nonce for account balances) and an Ethereum account address. Only contains one input in the array; we still use an array to maintain parity with the Bitcoin API.
outputs Object An array object containing a single output with value (in wei), script, and an Ethereum account address. Only contains one output in the array; we still use an array to maintain parity with the Bitcoin API.
internal_txids array[string] Optional If this transaction executed a contract which propagated its own subsequent transactions, then this array will be present, containing the hashes of those subsequent internal transactions.
parent_tx string Optional If this transaction was initiated by a contract, this field will be present, conveying the hash of the parent transaction that executed the contract resulting in this transaction (the inverse of an internal_txids hash).
confirmed time Optional Time at which transaction was included in a block; only present for confirmed transactions.
gas_limit integer Optional If creating a transaction, can optionally set a higher default gas limit (useful if your recepient is a contract). If not set, default is 21000 gas for external accounts and 80000 for contract accounts.
contract_creation bool Optional If true, this transaction was used to create a contract and contract account. Note that the contract address (in the outputs field) will be blank until the transaction is confirmed.
receive_count integer Optional Number of peers that have sent this transaction to BlockCypher; only present for unconfirmed transactions.
block_hash string Optional Hash of the block that contains this transaction; only present for confirmed transactions.
block_index integer Optional Canonical, zero-indexed location of this transaction in a block; only present for confirmed transactions.
double_of string Optional If this transaction is a double-spend (i.e. double_spend == true) then this is the hash of the transaction it’s double-spending.
execution_error string Optional If this transaction has an execution error, then this field will be included (e.g. “out of gas”).

TXRef

{
    "tx_hash": "ba44f568dc77d33893261c041994eeaef17d108a1845ccb9e376afea2acdd0e9",
    "block_height": 1648312,
    "tx_input_n": 0,
    "tx_output_n": -1,
    "value": 50420000000000000,
    "ref_balance": 2845236193385545395,
    "confirmations": 8342,
    "confirmed": "2016-06-05T12:47:08Z",
    "double_spend": false
}

A TXRef object represents summarized data about a transaction input or output. Typically found in an array within an Address object, which is usually returned from the standard Address Endpoint.

Attribute Type Description
block_height integer Height of the block that contains this transaction input/output. If it’s unconfirmed, this will equal -1.
tx_hash string The hash of the transaction containing this input/output.
tx_input_n integer Index of this input in the enclosing transaction. 0 if it’s an input, -1 if it’s an output.
tx_output_n integer Index of this output in the enclosing transaction. -1 if it’s an input, 0 if it’s an output.
value integer The value transfered by this input/output in wei exchanged in the enclosing transaction.
double_spend bool true if this is an attempted double spend; false otherwise.
confirmations integer Number of subsequent blocks, including the block the transaction is in. Unconfirmed transactions have 0 confirmations.
ref_balance integer Optional The past balance of the parent address the moment this transaction was confirmed. Not present for unconfirmed transactions.
confirmed time Optional Time at which transaction was included in a block; only present for confirmed transactions.
double_of string Optional If this transaction is a double-spend (i.e. double_spend == true) then this is the hash of the transaction it’s double-spending.

TXSkeleton

curl -sd '{"inputs":[{"addresses": ["1cc60c94254c0f0f0b957fb7c3dfed2d00e49a4c"]}],"outputs":[{"addresses": ["add42af7dd58b27e1e6ca5c4fdc01214b52d382f"], "value": 4200000000000000}]}' https://api.blockcypher.com/v1/eth/main/txs/new?token=YOURTOKEN
{
  "tx": {
    "block_height": -1,
    "block_index": 0,
    "hash": "5f32efeee4c1132df5aea5ac42735e0e21df995dd1cb0a4196eff4afc81ccb77",
    "addresses": [
      "1cc60c94254c0f0f0b957fb7c3dfed2d00e49a4c",
      "add42af7dd58b27e1e6ca5c4fdc01214b52d382f"
    ],
    "total": 4200000000000000,
    "fees": 861000000000000,
    "size": 44,
    "relayed_by": "",
    "received": "2016-06-07T06:41:25.396799578Z",
    "ver": 0,
    "double_spend": false,
    "vin_sz": 1,
    "vout_sz": 1,
    "inputs": [
      {
        "sequence": 2,
        "addresses": [
          "1cc60c94254c0f0f0b957fb7c3dfed2d00e49a4c"
        ]
      }
    ],
    "outputs": [
      {
        "value": 4200000000000000,
        "addresses": [
          "add42af7dd58b27e1e6ca5c4fdc01214b52d382f"
        ]
      }
    ]
  },
  "tosign": [
    "dd3c2cc1cf735ce5a3bbb5de7fb8f3ac2d9b6e6ec211ec6d8c03f098403e7736"
  ],
    "signatures": [],
    "errors": []
}

A TXSkeleton is a convenience/wrapper Object that’s used primarily when Creating Transactions through the New and Send endpoints.

Attribute Type Description
tx TX A temporary TX, usually returned fully filled.
tosign array[string] Array of hex-encoded data for you to sign, containing one element for you to sign. Still an array to maintain parity with the Bitcoin API.
signatures array[string] Array of signatures corresponding to all the data in tosign, typically provided by you. Only one signature is required.
errors array[“error”:string] Optional Array of errors in the form “error”:“description-of-error”. This is only returned if there was an error in any stage of transaction generation, and is usually accompanied by a HTTP 400 code.

Address

curl -s https://api.blockcypher.com/v1/eth/main/addrs/738d145faabb1e00cf5a017588a9c0f998318012
{
  "address": "738d145faabb1e00cf5a017588a9c0f998318012",
  "total_received": 9762206505909057760,
  "total_sent": 6916970312523512365,
  "balance": 2845236193385545395,
  "unconfirmed_balance": 0,
  "final_balance": 2845236193385545395,
  "n_tx": 702,
  "unconfirmed_n_tx": 0,
  "final_n_tx": 702,
  "txrefs": [
    {
      "tx_hash": "ba44f568dc77d33893261c041994eeaef17d108a1845ccb9e376afea2acdd0e9",
      "block_height": 1648312,
      "tx_input_n": 0,
      "tx_output_n": -1,
      "value": 50420000000000000,
      "ref_balance": 2845236193385545395,
      "confirmations": 8342,
      "confirmed": "2016-06-05T12:47:08Z",
      "double_spend": false
    },
    {
      "tx_hash": "99ec589ab8cb9498093c4d0c534bdcfd8bd04bfead1d869e3a79165a4f98af0d",
      "block_height": 1628712,
      "tx_input_n": 0,
      "tx_output_n": -1,
      "value": 10623553359437326,
      "ref_balance": 2895656193385545395,
      "confirmations": 27942,
      "confirmed": "2016-06-02T06:53:55Z",
      "double_spend": false
    },
    {
      "tx_hash": "20551685c6c311738da9f42019eb66fccd2cec4cc48e00d98967365d6ad77164",
      "block_height": 1628222,
      "tx_input_n": 0,
      "tx_output_n": -1,
      "value": 10623553359437326,
      "ref_balance": 2906279746744982721,
      "confirmations": 28432,
      "confirmed": "2016-06-02T05:02:50Z",
      "double_spend": false
    },
        ...
  ],
  "hasMore": true,
  "tx_url": "https://api.blockcypher.com/v1/eth/main/txs/"
}

An Address represents the state of an Ethereum address/account, containing information about the state of balances and transactions related to this address. Typically returned from the Address Balance and Address endpoints.

Attribute Type Description
address string The requested address.
total_received integer Total amount of confirmed wei received by this address.
total_sent integer Total amount of confirmed wei sent by this address.
balance integer Balance of confirmed wei on this address. (i.e., for transactions whose confirmations > 0).
unconfirmed_balance integer Balance of unconfirmed wei on this address. Can be negative (if unconfirmed transactions are just spending part of an address balance). Only unconfirmed transactions (haven’t made it into a block) are included in this calculation.
final_balance integer Total balance of wei, including confirmed and unconfirmed transactions, for this address.
n_tx integer Number of confirmed transactions on this address. Only transactions that have made it into a block (confirmations > 0) are counted.
unconfirmed_n_tx integer Number of unconfirmed transactions for this address. Only unconfirmed transactions (confirmations == 0) are counted.
final_n_tx integer Final number of transactions, including confirmed and unconfirmed transactions, for this address.
tx_url url Optional To retrieve base URL transactions. To get the full URL, concatenate this URL with a transaction’s hash.
txrefs array[TXRef] Optional Array of transaction summaries for this address. Usually only returned from the standard Address Endpoint.
unconfirmed_txrefs array[TXRef] Optional All unconfirmed transaction summaries for this address. Usually only returned from the standard Address Endpoint.
hasMore bool Optional If true, then the Address object contains more transactions than shown. Useful for determining whether to poll the API for more transaction information.

AddressKeychain

curl -sX POST https://api.blockcypher.com/v1/eth/main/addrs
{
    "private": "32605f9fbe224ebe621f88c33ae27099d4ce803e3b1cb5a1a3169790fd71beee",
    "public": "04d3e1b49ef16dcde23be535b621d15c83ff75ef097ae43f2ef7a98bcddbb402034ddb6a5ca781d7333ef988bb9a5cd98c1f407d8acf77a1a8a17a26899fa66be5",
    "address": "d543125acfc1e4d22f7f62aa5fbb2bb9a42bdb6d"
}

An AddressKeychain represents an associated collection of public and private keys alongside their respective Ethereum address. Generally returned and used with the Generate Address Endpoint.

Attribute Type Description
address string Standard address representation.
public string Hex-encoded Public key.
private string Hex-encoded Private key.

Contract

{
"solidity": "contract mortal {\n  /* Define variable owner of the type address*/\n    address owner;\n    /* this function is executed at initialization and sets the owner of the contract */\n    function mortal() { owner = msg.sender; }\n    /* Function to recover the funds on the contract */\n    function kill() { if (msg.sender == owner) suicide(owner); }\n}\n\ncontract greeter is mortal {\n    /* define variable greeting of the type string */\n    string greeting;\n    /* this runs when the contract is executed */\n    function greeter(string _greeting) public {\n        greeting = _greeting;\n    }\n    /* main function */\n    function greet() constant returns (string) {\n        return greeting;\n    }\n}",
"params": ["Hello BlockCypher Test"],
"publish": ["greeter"],
"private": "3ca40...",
"gas_limit": 500000
}

{
"name": "greeter",
"solidity": "contract mortal {\n  /* Define variable owner of the type address*/\n    address owner;\n    /* this function is executed at initialization and sets the owner of the contract */\n    function mortal() { owner = msg.sender; }\n    /* Function to recover the funds on the contract */\n    function kill() { if (msg.sender == owner) suicide(owner); }\n}\n\ncontract greeter is mortal {\n    /* define variable greeting of the type string */\n    string greeting;\n    /* this runs when the contract is executed */\n    function greeter(string _greeting) public {\n        greeting = _greeting;\n    }\n    /* main function */\n    function greet() constant returns (string) {\n        return greeting;\n    }\n}",
"bin": "606060405260405161023e38038061023e8339810160405280510160008054600160a060020a031916331790558060016000509080519060200190828054600181600116156101000203166002900490600052602060002090601f016020900481019282601f10609f57805160ff19168380011785555b50608e9291505b8082111560cc57600081558301607d565b50505061016e806100d06000396000f35b828001600101855582156076579182015b82811115607657825182600050559160200191906001019060b0565b509056606060405260e060020a600035046341c0e1b58114610026578063cfae321714610068575b005b6100246000543373ffffffffffffffffffffffffffffffffffffffff908116911614156101375760005473ffffffffffffffffffffffffffffffffffffffff16ff5b6100c9600060609081526001805460a06020601f6002600019610100868816150201909416939093049283018190040281016040526080828152929190828280156101645780601f1061013957610100808354040283529160200191610164565b60405180806020018281038252838181518152602001915080519060200190808383829060006004602084601f0104600f02600301f150905090810190601f1680156101295780820380516001836020036101000a031916815260200191505b509250505060405180910390f35b565b820191906000526020600020905b81548152906001019060200180831161014757829003601f168201915b505050505090509056",
"abi": [...],
"gas_limit": 500000,
"creation_tx_hash": "61474003e56d67aba6bf148c5ec361e3a3c1ceea37fe3ace7d87759b399292f9",
"address": "0eb688e79698d645df015cf2e9db5a6fe16357f1",
"params": [
    "Hello BlockCypher Test"
]
}

A Contract represents an embedded contract on the Ethereum blockchain, and is used with both creating and executing contracts in our Contract API. All the fields below are generally optional, but may be required depending on the particular contract endpoint you’re using.

Attribute Type Description
solidity string Solidity code of this contract; required when creating a contract. In responses, only returned with contracts initially compiled by BlockCypher.
params Array[string] Parameters for either contract creation or method execution.
publish Array[string] Named contract(s) to publish; necessary to specify when first creating a contract.
private string Private key associated with a funded Ethereum external account used to publish a contract or execute a method.
gas_limit int Maximum amount of gas to use in contract creation or method execution.
value int Amount (in wei) to transfer; can be used when creating a contract or calling a method.
name string Name of contract as published.
bin string Hex-encoded binary compilation of this contract.
abi ABI JSON-encoded ABI. Only returned with contracts initially compiled by BlockCypher.
address string Hex-encoded address of this contract.
created time Timestamp when this contract was confirmed in the Ethereum blockchain.
creation_tx_hash string Hex-encoded transaction hash that created this contract.
results Array[string] If this is a response from a calling a contract method, this array of results may appear if the method returns any.

Event

curl -s https://api.blockcypher.com/v1/eth/main/hooks/ce83d08f-7b86-4a6a-9b41-85507648f9c7?token=YOURTOKEN
{
  "id": "ce83d08f-7b86-4a6a-9b41-85507648f9c7",
  "token": "YOURTOKEN",
  "url": "https://my.domain.com/callbacks/new-tx",
  "callback_errors": 0,
  "address": "c5beef03aaa9548210b5550a62f7756efaa08ba3",
  "event": "unconfirmed-tx",
  "filter": "addr=c5beef03aaa9548210b5550a62f7756efaa08ba3\u0026event=unconfirmed-tx"
}

An Event represents a WebHooks or WebSockets-based notification request, as detailed in the Events & Hooks section of the documentation.

Attribute Type Description
id string Identifier of the event; generated when a new request is created.
event string Type of event; can be unconfirmed-tx, new-block, confirmed-tx, tx-confirmation, double-spend-tx.
hash string optional Only objects with a matching hash will be sent. The hash can either be for a block or a transaction.
address string optional Only transactions associated with the given address will be sent.
confirmations integer optional Used in concert with the tx-confirmation event type to set the number of confirmations desired for which to receive an update. You’ll receive an updated TX for every confirmation up to this amount. The maximum allowed is 10; if not set, it will default to 6.
url url optional Callback URL for this Event’s WebHook; not applicable for WebSockets usage.
callback_errors int Number of errors when attempting to POST to callback URL; not applicable for WebSockets usage.

Blockchain API

Blockchain docs here.

The first component—and highest level—of the BlockCypher Ethereum API allows you to query general information about Ethereum’s blockchain and blocks.

If you’re new to blockchains, you can think of the blockchain itself as an immutable, distributed ledger. Each block in the blockchain is like a “page” in the ledger containing information about transactions between parties. A great place to start understanding the mechanics behind blockchains is the original Bitcoin whitepaper. To get a handle on how Ethereum differs from Bitcoin, you can check the Ethereum project whitepaper.

Chain Endpoint

curl -s https://api.blockcypher.com/v1/eth/main
{
  "name": "ETH.main",
  "height": 1663350,
  "hash": "2dc3d6b080fbc78e576c8a0a7ccb52ca2af25b60c0df30ff82279fa41454729c",
  "time": "2016-06-08T00:46:10.101109766Z",
  "latest_url": "https://api.blockcypher.com/v1/eth/main/blocks/2dc3d6b080fbc78e576c8a0a7ccb52ca2af25b60c0df30ff82279fa41454729c",
  "previous_hash": "00709ed44e1ee2f2e5416c1e48bfd1a820e30aa14348b97d802d463f4ec940a6",
  "previous_url": "https://api.blockcypher.com/v1/eth/main/blocks/00709ed44e1ee2f2e5416c1e48bfd1a820e30aa14348b97d802d463f4ec940a6",
  "peer_count": 55,
  "unconfirmed_count": 11924,
  "high_gas_price": 40000000000,
  "medium_gas_price": 20000000000,
  "low_gas_price": 5000000000,
  "last_fork_height": 1661588,
  "last_fork_hash": "79075d95aacc6ac50dbdf58da044af396ca97e09cbb31527809579cc96f1c8a7"
}

General information about the Ethereum blockchain is available by GET-ing the base resource.

Resource Method Return Object
/ GET Blockchain

The returned object contains a litany of information, including its height, the time/hash of the latest block, and more. For Ethereum, the object includes information on gas_price, denoted in wei. Unlike Bitcoin, fees are determined by the computational execution cost of the transaction via gas; in order to prevent runaway contract execution, each operation in Ethereum’s Virtual Machine requires a fixed/known amount of gas. While the amount of gas is fixed for a given EVM operation, the price of gas fluctuates based on market demand on the Ethereum blockchain (similar to Bitcoin fees). For more detail, check this very helpful Stack Exchange explanation.

For more detailed information about the data returned, check the Blockchain object.

Block Hash Endpoint

curl -s https://api.blockcypher.com/v1/eth/main/blocks/b35265965f6f14c5d692b2030922fce53067fc0e9d8c8490c31d4ecd3e46500c
{
  "hash": "b35265965f6f14c5d692b2030922fce53067fc0e9d8c8490c31d4ecd3e46500c",
  "height": 1564040,
  "chain": "ETH.main",
  "total": 20306306718874652,
  "fees": 1595580000000000,
  "size": 661,
  "ver": 0,
  "time": "2016-05-22T12:43:00Z",
  "received_time": "2016-05-22T12:43:00Z",
  "coinbase_addr": "4bb96091ee9d802ed039c4d1a5f6216f90f81b01",
  "relayed_by": "",
  "nonce": 2464233431647216841,
  "n_tx": 1,
  "prev_block": "e52d8cd9bf52374fd47e9d9ed81d2702f9e6352455f0ac07000bd3682b70cde7",
  "mrkl_root": "23f82aa013765c42fbee7f4e57c22befd7aece689834d0d2d6e25208713efb6a",
  "txids": [
    "8f39fb4940c084460da00a876a521ef2ba84ad6ea8d2f5628c9f1f8aeb395342"
  ],
  "internal_txids": [
    "dd107c8488867fd53c0aa3bf1d8a478a077ec67af75842d24f1a64eb44e4d902",
    "9a98678d209910f70bded624f2c5c18ed17d417752072d41c5d61b42c277348c",
    "ad959961f46663f785e1e0a0b2656960b5d27061097c5092c4e68964bfaf0041",
    "5a23d74a484ec58b211264888846be6d7428c33be93223396eff3626e036a7f4",
    "73906b2f1a1d7fd17c77684e5e811ae8710e4a032501090da264712db7a48e7a",
    "53ce88e1cf98b37fb64c16121b4641dde65290838ce0bde6cb1c319df3ef8ff9",
    "29bc4e7fa2db28b0a2ef9e7a5e073cc7532e609f752b2eb0b5731b0c6b926a2c",
    "4a9afc5a680917955e781b890688143f56badc76785af98753d5267270d7d809"
  ],
  "depth": 92613,
  "prev_block_url": "https://api.blockcypher.com/v1/eth/main/blocks/e52d8cd9bf52374fd47e9d9ed81d2702f9e6352455f0ac07000bd3682b70cde7",
  "tx_url": "https://api.blockcypher.com/v1/eth/main/txs/"
}

If you want more data on a particular block, you can use the Block Hash endpoint.

Resource Method Return Object
/blocks/$BLOCK_HASH GET Block
Flag Type Effect
txstart integer Filters response to only include transaction hashes after txstart in the block.
limit integer Filters response to only include a maximum of limit transactions hashes in the block. Maximum value allowed is 500.

$BLOCK_HASH is a string representing the hash of the block you’re interested in querying, for example:

0000000000000000189bba3564a63772107b5673c940c16f12662b3e8546b412

The returned object contains information about the block, including its height, the total amount of wei transacted within it, the number of transactions in it, transaction hashes listed in the canonical order in which they appear in the block, and more. For more detail on the data returned, check the Block object.

Block Height Endpoint

curl -s https://api.blockcypher.com/v1/eth/main/blocks/7
{
  "hash": "e0c7c0b46e116b874354dce6f64b8581bd239186b03f30a978e3dc38656f723a",
  "height": 7,
  "chain": "ETH.main",
  "total": 0,
  "fees": 0,
  "size": 1078,
  "ver": 0,
  "time": "2015-07-30T15:28:30Z",
  "received_time": "2015-07-30T15:28:30Z",
  "coinbase_addr": "dd2f1e6e498202e86d8f5442af596580a4f03c2c",
  "relayed_by": "",
  "nonce": 13599487003767981,
  "n_tx": 0,
  "prev_block": "1f1aed8e3694a067496c248e61879cda99b0709a1dfbacd0b693750df06b326e",
  "mrkl_root": "ff8d97d9ca01ee59c793c4da2ba4ce8c31d358b42f216ab2f11af4bb097b6a2b",
  "uncles": [
    "4b8729311c5b59f418c5154fd54d85e6a8b42eabf83a1d3c05c754a8f10354cc"
  ],
  "txids": [],
  "depth": 1656646,
  "prev_block_url": "https://api.blockcypher.com/v1/eth/main/blocks/1f1aed8e3694a067496c248e61879cda99b0709a1dfbacd0b693750df06b326e",
  "tx_url": "https://api.blockcypher.com/v1/eth/main/txs/"
}

You can also query for information on a block using its height, using the same resource but with a different variable type.

Resource Method Return Object
/blocks/$BLOCK_HEIGHT GET Block
Flag Type Effect
txstart integer Filters response to only include transaction hashes after txstart in the block.
limit integer Filters response to only include a maximum of limit transactions hashes in the block. Maximum value allowed is 500.

BLOCK_HEIGHT is an integer representing the height of the block you’re interested in querying, for example:

1500000

As above, the returned object contains information about the block, including its hash, the total amount of wei transacted within it, the number of transactions in it, transaction hashes listed in the canonical order in which they appear in the block, and more. For more detail on the data returned, check the Block object.

Address API

BlockCypher’s Ethereum Address API allows you to look up information about public Ethereum addresses/accounts and generate your own low-value Ethereum addresses/public-private key pairs.

If you’re new to blockchains, you can think of public addresses as similar to bank account numbers in a traditional ledger. The biggest differences:

Address Balance Endpoint

curl -s https://api.blockcypher.com/v1/eth/main/addrs/738d145faabb1e00cf5a017588a9c0f998318012/balance
{
  "address": "738d145faabb1e00cf5a017588a9c0f998318012",
  "total_received": 9762206505909057760,
  "total_sent": 6916970312523512365,
  "balance": 2845236193385545395,
  "unconfirmed_balance": 0,
  "final_balance": 2845236193385545395,
  "n_tx": 702,
  "unconfirmed_n_tx": 0,
  "final_n_tx": 702
}

The Address Balance Endpoint is the simplest—and fastest—method to get a subset of information on a public address.

Resource Method Return Object
/addrs/$ADDRESS/balance GET Address

ADDRESS is a string representing the public address you’re interested in querying, for example:

738d145faabb1e00cf5a017588a9c0f998318012

The returned object contains information about the address, including its balance in wei and the number of transactions associated with it. The endpoint omits any detailed transaction information, but if that isn’t required by your application, then it’s the fastest and preferred way to get public address information.

Address Endpoint

curl -s https://api.blockcypher.com/v1/eth/main/addrs/738d145faabb1e00cf5a017588a9c0f998318012
{
  "address": "738d145faabb1e00cf5a017588a9c0f998318012",
  "total_received": 9762206505909057760,
  "total_sent": 6916970312523512365,
  "balance": 2845236193385545395,
  "unconfirmed_balance": 0,
  "final_balance": 2845236193385545395,
  "n_tx": 702,
  "unconfirmed_n_tx": 0,
  "final_n_tx": 702,
  "txrefs": [
    {
      "tx_hash": "ba44f568dc77d33893261c041994eeaef17d108a1845ccb9e376afea2acdd0e9",
      "block_height": 1648312,
      "tx_input_n": 0,
      "tx_output_n": -1,
      "value": 50420000000000000,
      "ref_balance": 2845236193385545395,
      "confirmations": 8342,
      "confirmed": "2016-06-05T12:47:08Z",
      "double_spend": false
    },
    {
      "tx_hash": "99ec589ab8cb9498093c4d0c534bdcfd8bd04bfead1d869e3a79165a4f98af0d",
      "block_height": 1628712,
      "tx_input_n": 0,
      "tx_output_n": -1,
      "value": 10623553359437326,
      "ref_balance": 2895656193385545395,
      "confirmations": 27942,
      "confirmed": "2016-06-02T06:53:55Z",
      "double_spend": false
    },
    {
      "tx_hash": "20551685c6c311738da9f42019eb66fccd2cec4cc48e00d98967365d6ad77164",
      "block_height": 1628222,
      "tx_input_n": 0,
      "tx_output_n": -1,
      "value": 10623553359437326,
      "ref_balance": 2906279746744982721,
      "confirmations": 28432,
      "confirmed": "2016-06-02T05:02:50Z",
      "double_spend": false
    },
        ...
  ],
  "hasMore": true,
  "tx_url": "https://api.blockcypher.com/v1/eth/main/txs/"
}

The Address Endpoint returns more information about an address’ transactions than the Address Balance Endpoint, but sacrifices some response speed in the process.

Resource Method Return Object
/addrs/$ADDRESS GET Address
Flag Type Effect
before integer Filters response to only include transactions below before height in the blockchain.
after integer Filters response to only include transactions above after height in the blockchain.
limit integer limit sets the minimum number of returned TXRefs; there can be less if there are less than limit TXRefs associated with this address, but there can be more in the rare case of more TXRefs in the block at the bottom of your call. This ensures paging by block height never misses TXRefs. Defaults to 200, maximum is 2000.
confirmations integer If set, only returns the balance and TXRefs that have at least this number of confirmations.

ADDRESS is a string representing the public address (or wallet/HD wallet name) you’re interested in querying, for example:

738d145faabb1e00cf5a017588a9c0f998318012

The returned object contains information about the address, including its balance in wei, the number of transactions associated with it, and transaction summaries in descending order by block height.

Generate Address Endpoint

curl -sX POST https://api.blockcypher.com/v1/eth/main/addrs?token=YOURTOKEN
{
  "private": "44c984a089184a9a659e10210af360049f366a34f7f3cb253ac5cbfcb33f3d7c",
  "public": "04b7de9b47fc1fb278648266316dffe47cc7f5280b69b05b5770ad1624ee3da7647c98ade5e4c35b99e606535eaca54db0f913c8aa1fa7226f15b9996325d0989d",
  "address": "e3f7e628fff7589218d88ae1d6bcdac52fef2168"
}

The Generate Address endpoint allows you to generate private-public key-pairs along with an associated public address. No information is required with this POST request.

Resource Method Request Object Return Object
/addrs POST nil AddressKeychain

The returned object contains a private key, a public key, and a public address, all hex-encoded.

Transaction API

BlockCypher’s Ethereum Transaction API allows you to look up information about unconfirmed transactions, query transactions based on hash, and create and propagate your own transactions.

Unlike Bitcoin, Ethereum has no concept of UTXOs. Instead, addresses have a running balance, and use an ever-increasing sequence/nonce for every transaction to maintain proper address state. You can read more about this design decision here. Transaction signing and generation are also different in Ethereum, but for basic transactions, the process is very similar to our Bitcoin API.

Transaction Hash Endpoint

curl -s https://api.blockcypher.com/v1/eth/main/txs/8f39fb4940c084460da00a876a521ef2ba84ad6ea8d2f5628c9f1f8aeb395342
{
  "block_hash": "b35265965f6f14c5d692b2030922fce53067fc0e9d8c8490c31d4ecd3e46500c",
  "block_height": 1564040,
  "block_index": 0,
  "hash": "8f39fb4940c084460da00a876a521ef2ba84ad6ea8d2f5628c9f1f8aeb395342",
  "addresses": [
    "738d145faabb1e00cf5a017588a9c0f998318012",
    "4e9d8b4f18d984f6f0c88d07e4b39201e825cd17"
  ],
  "total": 10153153359437326,
  "fees": 1595580000000000,
  "size": 116,
  "relayed_by": "",
  "confirmed": "2016-05-22T12:43:00Z",
  "received": "2016-05-22T12:43:00Z",
  "ver": 0,
  "double_spend": false,
  "vin_sz": 1,
  "vout_sz": 1,
  "confirmations": 94919,
  "confidence": 1,
  "inputs": [
    {
      "sequence": 273,
      "addresses": [
        "738d145faabb1e00cf5a017588a9c0f998318012"
      ]
    }
  ],
  "outputs": [
    {
      "value": 10153153359437326,
      "script": "4e71d92d",
      "addresses": [
        "4e9d8b4f18d984f6f0c88d07e4b39201e825cd17"
      ]
    }
  ]
}

The Transaction Hash Endpoint returns detailed information about a given transaction based on its hash.

Resource Method Return Object
/txs/$TXHASH GET TX

TXHASH is a string representing the hex-encoded transaction hash you’re interested in querying, for example:

8f39fb4940c084460da00a876a521ef2ba84ad6ea8d2f5628c9f1f8aeb395342

The returned object contains detailed information about the transaction, including the value transfered, fees collected, date received, any scripts associated with an output, and more.

Unconfirmed Transactions Endpoint

curl -s https://api.blockcypher.com/v1/eth/main/txs
[
  {
    "block_height": -1,
    "block_index": 0,
    "hash": "1f5bd529e72f6aa5724b6a3971781909e5156dc60058ccdfea15419bef25f5dd",
    "addresses": [
      "70d84f9b00556bb41c04aa0205506345f43ba746",
      "f7b0b916b2849255a61127fc4a42b9dfeaddf7d6"
    ],
    "total": 972909140000000000,
    "fees": 1260000000000000,
    "size": 110,
    "relayed_by": "",
    "received": "2016-06-07T07:47:40.14486539Z",
    "ver": 0,
    "double_spend": false,
    "vin_sz": 1,
    "vout_sz": 1,
    "confirmations": 0,
    "inputs": [
      {
        "sequence": 19,
        "addresses": [
          "70d84f9b00556bb41c04aa0205506345f43ba746"
        ]
      }
    ],
    "outputs": [
      {
        "value": 972909140000000000,
        "addresses": [
          "f7b0b916b2849255a61127fc4a42b9dfeaddf7d6"
        ]
      }
    ]
  },
  {
    "block_height": -1,
    "block_index": 0,
    "hash": "1bd833698337fce44a7feedf6bbe78c90ada088389ebafcad0b56901def3c989",
    "addresses": [
      "a1b5f95be71ffa2f86adefcaa0028c46fe825161",
      "b7443c8bdff977234ed9394169f181f9e9851422"
    ],
    "total": 1000000000000000000,
    "fees": 2420000000000000,
    "size": 111,
    "relayed_by": "",
    "received": "2016-06-07T07:47:38.710195289Z",
    "ver": 0,
    "double_spend": false,
    "vin_sz": 1,
    "vout_sz": 1,
    "confirmations": 0,
    "inputs": [
      {
        "sequence": 68,
        "addresses": [
          "a1b5f95be71ffa2f86adefcaa0028c46fe825161"
        ]
      }
    ],
    "outputs": [
      {
        "value": 1000000000000000000,
        "addresses": [
          "b7443c8bdff977234ed9394169f181f9e9851422"
        ]
      }
    ]
  },
    ...
]

The Unconfirmed Transactions Endpoint returns an array of the latest transactions that haven’t been included in any blocks.

Resource Method Return Object
/txs GET Array[TX]

The returned object is an array of transactions that haven’t been included in blocks, arranged in reverse chronological order (latest is first, then older transactions follow).

Creating Transactions

Using BlockCypher’s API, you can push transactions to Ethereum in one of two ways:

In either case, for security reasons, we never take possession of your private keys.

curl -sd '{"inputs":[{"addresses": ["add42af7dd58b27e1e6ca5c4fdc01214b52d382f"]}],"outputs":[{"addresses": ["884bae20ee442a1d53a1d44b1067af42f896e541"], "value": 4200000000000000}]}' https://api.blockcypher.com/v1/eth/main/txs/new?token=YOURTOKEN

{
  "tx": {
    "block_height": -1,
    "block_index": 0,
    "hash": "9403244c6bcfe4063e7fb33138b02881d7a72ccdbd9c04d9abdff2b432d67ada",
    "addresses": [
      "add42af7dd58b27e1e6ca5c4fdc01214b52d382f",
      "884bae20ee442a1d53a1d44b1067af42f896e541"
    ],
    "total": 4200000000000000,
    "fees": 861000000000000,
    "size": 44,
    "gas_used": 0,
    "gas_price": 41000000000,
    "relayed_by": "",
    "received": "2016-06-08T01:32:35.573921633Z",
    "ver": 0,
    "double_spend": false,
    "vin_sz": 1,
    "vout_sz": 1,
    "inputs": [
      {
        "sequence": 0,
        "addresses": [
          "add42af7dd58b27e1e6ca5c4fdc01214b52d382f"
        ]
      }
    ],
    "outputs": [
      {
        "value": 4200000000000000,
        "addresses": [
          "884bae20ee442a1d53a1d44b1067af42f896e541"
        ]
      }
    ]
  },
  "tosign": [
    "a83f5bea598e0d217a03a2646d6c49edb2e99daf4537b2c09b008df76b77acec"
  ]
}

New Transaction Endpoint

To use BlockCypher’s two-endpoint transaction creation tool, first you need to provide the input address, output address, and value to transfer (in wei). Provide this in a partially-filled out TX request object.

Resource Method Request Object Return Object
/txs/new POST TX TXSkeleton

As you can see from the code example, you only need to provide a single public address within the addresses array of both the input and output of your TX request object. You also need to fill in the value with the amount you’d like to transfer from one address to another. Note that we only accept a single input and output address per Ethereum’s transaction model, and tosign only returns a single element in its array; we use arrays for parity with our Bitcoin API.

As a return object, you’ll receive a TXSkeleton containing a slightly-more complete TX alongside data you need to sign in the tosign array. You’ll need this object for the next steps of the transaction creation process.

# next, you sign the data returned in the tosign array locally
# here we're using our signer tool (https://github.com/blockcypher/btcutils/tree/master/signer), but any ECDSA secp256k1 signing tool should work (Ethereum uses the same ECDSA curve as Bitcoin for transaction signatures)
# $PRIVATEKEY here is a hex-encoded private key corresponding to the input from address add42af7dd58b27e1e6ca5c4fdc01214b52d382f

./signer a83f5bea598e0d217a03a2646d6c49edb2e99daf4537b2c09b008df76b77acec $PRIVATEKEY 
3045022100bc04ce017622f9830f955dbd8fafb65c5a72306a674711e507200f5f198954c90220581bc05e2658c258a985d914a158f89f44144a2e082837955b218d12a43a6a38

Locally Sign Your Transaction

With your TXSkeleton returned from the New Transaction Endpoint, you now need to use your private key to sign the data provided in the tosign array.

Digital signing can be a difficult process, and is where the majority of issues arise when dealing with cryptocurrency transactions. Ethereum uses the same elliptic curve as Bitcoin (secp256k1), so any Bitcoin signing library that fits with your workflow should suffice. If you want to experiment with client-side signing, consider using our signer tool.

# the request body is truncated because it's huge, but it's the same as the returned object from above plus the signature
curl -sd '{"tx": {...}, "tosign": [ "a83f5bea598e0d217a03a2646d6c49edb2e99daf4537b2c09b008df76b77acec" ], "signatures": [ "3045022100bc04ce017622f9830f955dbd8fafb65c5a72306a674711e507200f5f198954c90220581bc05e2658c258a985d914a158f89f44144a2e082837955b218d12a43a6a38" ]}' https://api.blockcypher.com/v1/eth/main/txs/send?token=YOURTOKEN

{
  "tx": {
    "block_height": -1,
    "block_index": 0,
    "hash": "85725e97d83ec7ce3888ca74d68b7820640f80d6380b9e1c565f61f5409acf50",
    "addresses": [
      "add42af7dd58b27e1e6ca5c4fdc01214b52d382f",
      "884bae20ee442a1d53a1d44b1067af42f896e541"
    ],
    "total": 4200000000000000,
    "fees": 861000000000000,
    "size": 109,
    "gas_used": 0,
    "gas_price": 41000000000,
    "relayed_by": "",
    "received": "2016-06-08T02:38:59.691331763Z",
    "ver": 0,
    "double_spend": false,
    "vin_sz": 1,
    "vout_sz": 1,
    "inputs": [
      {
        "sequence": 0,
        "addresses": [
          "add42af7dd58b27e1e6ca5c4fdc01214b52d382f"
        ]
      }
    ],
    "outputs": [
      {
        "value": 4200000000000000,
        "addresses": [
          "884bae20ee442a1d53a1d44b1067af42f896e541"
        ]
      }
    ]
  }
}

Send Transaction Endpoint

Once you’ve finished signing the tosign data locally, put that (hex-encoded) data into the signatures array of the TXSkeleton. Unlike Bitcoin, you don’t need to include the signing accounts public key, as on Ethereum this is derived using the tosign data and signature data. But you must include the tosign data in addition to the signatures array for that derivation to work.

Resource Method Request Object Return Object
/txs/send POST TXSkeleton TXSkeleton

If the transaction was successful, you’ll receive a TXSkeleton with the completed TX (which contains its final hash) and an HTTP Status Code 201.

Decode Raw Transaction Endpoint

curl -sd '{"tx":"f86b808504e3b2920082520894add42af7dd58b27e1e6ca5c4fdc01214b52d382f870bdccd84e7b000801ba0b86360f1c2d2b38421a80e71bf4cf54371bc9aa62f81c925484c6557b44b13f1a07b5690150c10a3947225fb612162c90ccfaefde99f7d363a8013e3eead0e55dd"}' https://api.blockcypher.com/v1/eth/main/txs/decode?token=YOURTOKEN
{
  "block_height": -1,
  "block_index": 0,
  "hash": "a88cca4dd97e028d7199028888156c4dad9936a2cbdfe8262fb12a252e16d4f1",
  "addresses": [
    "7ea7eb1c8b0fba77964c561f9b7494a87534aa15",
    "add42af7dd58b27e1e6ca5c4fdc01214b52d382f"
  ],
  "total": 3339000000000000,
  "fees": 441000000000000,
  "size": 109,
  "gas_used": 0,
  "gas_price": 21000000000,
  "relayed_by": "54.213.170.147",
  "received": "2016-06-08T06:18:08.181893896Z",
  "ver": 0,
  "double_spend": false,
  "vin_sz": 1,
  "vout_sz": 1,
  "confirmations": 0,
  "inputs": [
    {
      "sequence": 0,
      "addresses": [
        "7ea7eb1c8b0fba77964c561f9b7494a87534aa15"
      ]
    }
  ],
  "outputs": [
    {
      "value": 3339000000000000,
      "addresses": [
        "add42af7dd58b27e1e6ca5c4fdc01214b52d382f"
      ]
    }
  ]
}

We also offer the ability to decode raw transactions without sending propagating them to the network; perhaps you want to double-check another client library or confirm that another service is sending proper transactions.

Resource Method Request Object Return Object
/txs/decode POST {“tx”:$TXHEX} TX

$TXHEX is a hex-encoded raw representation of your transaction, for example:

f86b808504e3b2920082520894add42af7dd58b27e1e6ca5c4fdc01214b52d382f870bdccd84e7b000801ba0b86360f1c2d2b38421a80e71bf4cf54371bc9aa62f81c925484c6557b44b13f1a07b5690150c10a3947225fb612162c90ccfaefde99f7d363a8013e3eead0e55dd

If it succeeds, you’ll receive your decoded TX object.

Push Raw Transaction Endpoint

curl -sd '{"tx":"f86b808504e3b2920082520894add42af7dd58b27e1e6ca5c4fdc01214b52d382f870bdccd84e7b000801ba0b86360f1c2d2b38421a80e71bf4cf54371bc9aa62f81c925484c6557b44b13f1a07b5690150c10a3947225fb612162c90ccfaefde99f7d363a8013e3eead0e55dd"}' https://api.blockcypher.com/v1/eth/main/txs/push?token=YOURTOKEN
{
  "block_height": -1,
  "block_index": 0,
  "hash": "a88cca4dd97e028d7199028888156c4dad9936a2cbdfe8262fb12a252e16d4f1",
  "addresses": [
    "7ea7eb1c8b0fba77964c561f9b7494a87534aa15",
    "add42af7dd58b27e1e6ca5c4fdc01214b52d382f"
  ],
  "total": 3339000000000000,
  "fees": 441000000000000,
  "size": 109,
  "gas_used": 0,
  "gas_price": 21000000000,
  "relayed_by": "54.213.170.147",
  "received": "2016-06-08T06:18:08.181893896Z",
  "ver": 0,
  "double_spend": false,
  "vin_sz": 1,
  "vout_sz": 1,
  "confirmations": 0,
  "inputs": [
    {
      "sequence": 0,
      "addresses": [
        "7ea7eb1c8b0fba77964c561f9b7494a87534aa15"
      ]
    }
  ],
  "outputs": [
    {
      "value": 3339000000000000,
      "addresses": [
        "add42af7dd58b27e1e6ca5c4fdc01214b52d382f"
      ]
    }
  ]
}

If you’d prefer to use your own transaction library instead of the recommended path of our two-endpoint transaction generation we’re still happy to help you propagate your raw transactions. Simply send your raw hex-encoded transaction to this endpoint and we’ll leverage our well-connected network to propagate your transaction faster than anywhere else.

Resource Method Request Object Return Object
/txs/push POST {“tx”:$TXHEX} TX

$TXHEX is a hex-encoded raw representation of your transaction, for example:

f86b808504e3b2920082520894add42af7dd58b27e1e6ca5c4fdc01214b52d382f870bdccd84e7b000801ba0b86360f1c2d2b38421a80e71bf4cf54371bc9aa62f81c925484c6557b44b13f1a07b5690150c10a3947225fb612162c90ccfaefde99f7d363a8013e3eead0e55dd

If it succeeds, you’ll receive a decoded TX object and an HTTP Status Code 201. You can then use the hash to track its progress on the network.

Contract API

Compared to other blockchains, contracts lie at the heart of Ethereum’s unique value proposition. Contracts can be expressively programmed in languages like Solidity; if you’re not familiar with Ethereum’s contract language you should definitely start there.

We offer a number of API endpoints that significantly simplify contract creation and method calling. Via the methods below, you can embed new contracts into the Ethereum blockchain, check their code and ABI, and initiate contract methods and execution. Essentially, we provide a JSON/HTTP binding for your Ethereum contracts.

With great power comes great responsibility; in other words, it’s easier to shoot yourself in the foot with Ethereum. Don’t The DAO it. Follow best security and safety practices when coding your smart contracts.

Create Contract Endpoint

# Check solidity compilation via non-published test
# Using "greeter" contract solidity example, the "hello world" of Ethereum
cat testGreeter.json
{
  "solidity": "contract mortal {\n  /* Define variable owner of the type address*/\n    address owner;\n    /* this function is executed at initialization and sets the owner of the contract */\n    function mortal() { owner = msg.sender; }\n    /* Function to recover the funds on the contract */\n    function kill() { if (msg.sender == owner) suicide(owner); }\n}\n\ncontract greeter is mortal {\n    /* define variable greeting of the type string */\n    string greeting;\n    /* this runs when the contract is executed */\n    function greeter(string _greeting) public {\n        greeting = _greeting;\n    }\n    /* main function */\n    function greet() constant returns (string) {\n        return greeting;\n    }\n}",
  "params": ["Hello BlockCypher Test"]
}
curl -sd @testGreeter.json https://api.blockcypher.com/v1/eth/main/contracts?token=YOURTOKEN
[
  {
    "name": "greeter",
    "solidity": "contract mortal {\n  /* Define variable owner of the type address*/\n    address owner;\n    /* this function is executed at initialization and sets the owner of the contract */\n    function mortal() { owner = msg.sender; }\n    /* Function to recover the funds on the contract */\n    function kill() { if (msg.sender == owner) suicide(owner); }\n}\n\ncontract greeter is mortal {\n    /* define variable greeting of the type string */\n    string greeting;\n    /* this runs when the contract is executed */\n    function greeter(string _greeting) public {\n        greeting = _greeting;\n    }\n    /* main function */\n    function greet() constant returns (string) {\n        return greeting;\n    }\n}",
    "bin": "606060405260405161023e38038061023e8339810160405280510160008054600160a060020a031916331790558060016000509080519060200190828054600181600116156101000203166002900490600052602060002090601f016020900481019282601f10609f57805160ff19168380011785555b50608e9291505b8082111560cc57600081558301607d565b50505061016e806100d06000396000f35b828001600101855582156076579182015b82811115607657825182600050559160200191906001019060b0565b509056606060405260e060020a600035046341c0e1b58114610026578063cfae321714610068575b005b6100246000543373ffffffffffffffffffffffffffffffffffffffff908116911614156101375760005473ffffffffffffffffffffffffffffffffffffffff16ff5b6100c9600060609081526001805460a06020601f6002600019610100868816150201909416939093049283018190040281016040526080828152929190828280156101645780601f1061013957610100808354040283529160200191610164565b60405180806020018281038252838181518152602001915080519060200190808383829060006004602084601f0104600f02600301f150905090810190601f1680156101295780820380516001836020036101000a031916815260200191505b509250505060405180910390f35b565b820191906000526020600020905b81548152906001019060200180831161014757829003601f168201915b505050505090509056",
    "abi": [
      {
        "constant": false,
        "inputs": [],
        "name": "kill",
        "outputs": [],
        "type": "function"
      },
      {
        "constant": true,
        "inputs": [],
        "name": "greet",
        "outputs": [
          {
            "name": "",
            "type": "string"
          }
        ],
        "type": "function"
      },
      {
        "inputs": [
          {
            "name": "_greeting",
            "type": "string"
          }
        ],
        "type": "constructor"
      }
    ],
    "params": [
      "Hello BlockCypher Test"
    ]
  },
  {
    "name": "mortal",
    "solidity": "contract mortal {\n  /* Define variable owner of the type address*/\n    address owner;\n    /* this function is executed at initialization and sets the owner of the contract */\n    function mortal() { owner = msg.sender; }\n    /* Function to recover the funds on the contract */\n    function kill() { if (msg.sender == owner) suicide(owner); }\n}\n\ncontract greeter is mortal {\n    /* define variable greeting of the type string */\n    string greeting;\n    /* this runs when the contract is executed */\n    function greeter(string _greeting) public {\n        greeting = _greeting;\n    }\n    /* main function */\n    function greet() constant returns (string) {\n        return greeting;\n    }\n}",
    "bin": "606060405260008054600160a060020a03191633179055605c8060226000396000f3606060405260e060020a600035046341c0e1b58114601a575b005b60186000543373ffffffffffffffffffffffffffffffffffffffff90811691161415605a5760005473ffffffffffffffffffffffffffffffffffffffff16ff5b56",
    "abi": [
      {
        "constant": false,
        "inputs": [],
        "name": "kill",
        "outputs": [],
        "type": "function"
      },
      {
        "inputs": [],
        "type": "constructor"
      }
    ],
    "params": [
      "Hello BlockCypher Test"
    ]
  }
]

# Now publish the greeter contract 
cat publishGreeter.json
{
  "solidity": "contract mortal {\n  /* Define variable owner of the type address*/\n    address owner;\n    /* this function is executed at initialization and sets the owner of the contract */\n    function mortal() { owner = msg.sender; }\n    /* Function to recover the funds on the contract */\n    function kill() { if (msg.sender == owner) suicide(owner); }\n}\n\ncontract greeter is mortal {\n    /* define variable greeting of the type string */\n    string greeting;\n    /* this runs when the contract is executed */\n    function greeter(string _greeting) public {\n        greeting = _greeting;\n    }\n    /* main function */\n    function greet() constant returns (string) {\n        return greeting;\n    }\n}",
  "params": ["Hello BlockCypher Test"],
  "publish": ["greeter"],
  "private": "3ca40...",
  "gas_limit": 500000
}
curl -d @publishGreeter.json https://api.blockcypher.com/v1/eth/main/contracts?token=YOURTOKEN
[
  {
    "name": "greeter",
    "solidity": "contract mortal {\n  /* Define variable owner of the type address*/\n    address owner;\n    /* this function is executed at initialization and sets the owner of the contract */\n    function mortal() { owner = msg.sender; }\n    /* Function to recover the funds on the contract */\n    function kill() { if (msg.sender == owner) suicide(owner); }\n}\n\ncontract greeter is mortal {\n    /* define variable greeting of the type string */\n    string greeting;\n    /* this runs when the contract is executed */\n    function greeter(string _greeting) public {\n        greeting = _greeting;\n    }\n    /* main function */\n    function greet() constant returns (string) {\n        return greeting;\n    }\n}",
    "bin": "606060405260405161023e38038061023e8339810160405280510160008054600160a060020a031916331790558060016000509080519060200190828054600181600116156101000203166002900490600052602060002090601f016020900481019282601f10609f57805160ff19168380011785555b50608e9291505b8082111560cc57600081558301607d565b50505061016e806100d06000396000f35b828001600101855582156076579182015b82811115607657825182600050559160200191906001019060b0565b509056606060405260e060020a600035046341c0e1b58114610026578063cfae321714610068575b005b6100246000543373ffffffffffffffffffffffffffffffffffffffff908116911614156101375760005473ffffffffffffffffffffffffffffffffffffffff16ff5b6100c9600060609081526001805460a06020601f6002600019610100868816150201909416939093049283018190040281016040526080828152929190828280156101645780601f1061013957610100808354040283529160200191610164565b60405180806020018281038252838181518152602001915080519060200190808383829060006004602084601f0104600f02600301f150905090810190601f1680156101295780820380516001836020036101000a031916815260200191505b509250505060405180910390f35b565b820191906000526020600020905b81548152906001019060200180831161014757829003601f168201915b505050505090509056",
    "abi": [
      {
        "constant": false,
        "inputs": [],
        "name": "kill",
        "outputs": [],
        "type": "function"
      },
      {
        "constant": true,
        "inputs": [],
        "name": "greet",
        "outputs": [
          {
            "name": "",
            "type": "string"
          }
        ],
        "type": "function"
      },
      {
        "inputs": [
          {
            "name": "_greeting",
            "type": "string"
          }
        ],
        "type": "constructor"
      }
    ],
    "gas_limit": 500000,
    "creation_tx_hash": "61474003e56d67aba6bf148c5ec361e3a3c1ceea37fe3ace7d87759b399292f9",
    "address": "0eb688e79698d645df015cf2e9db5a6fe16357f1",
    "params": [
      "Hello BlockCypher Test"
    ]
  },
  {
    "name": "mortal",
    "solidity": "contract mortal {\n  /* Define variable owner of the type address*/\n    address owner;\n    /* this function is executed at initialization and sets the owner of the contract */\n    function mortal() { owner = msg.sender; }\n    /* Function to recover the funds on the contract */\n    function kill() { if (msg.sender == owner) suicide(owner); }\n}\n\ncontract greeter is mortal {\n    /* define variable greeting of the type string */\n    string greeting;\n    /* this runs when the contract is executed */\n    function greeter(string _greeting) public {\n        greeting = _greeting;\n    }\n    /* main function */\n    function greet() constant returns (string) {\n        return greeting;\n    }\n}",
    "bin": "606060405260008054600160a060020a03191633179055605c8060226000396000f3606060405260e060020a600035046341c0e1b58114601a575b005b60186000543373ffffffffffffffffffffffffffffffffffffffff90811691161415605a5760005473ffffffffffffffffffffffffffffffffffffffff16ff5b56",
    "abi": [
      {
        "constant": false,
        "inputs": [],
        "name": "kill",
        "outputs": [],
        "type": "function"
      },
      {
        "inputs": [],
        "type": "constructor"
      }
    ],
    "gas_limit": 500000,
    "params": [
      "Hello BlockCypher Test"
    ]
  }
]

# you can check the creation_tx_hash to see that the contract was published
curl -s https://api.blockcypher.com/v1/eth/main/txs/61474003e56d67aba6bf148c5ec361e3a3c1ceea37fe3ace7d87759b399292f9
{
  "block_hash": "fcd88715c95e6082612ab673ae3053d8bbfc51ca0b00aa82974ea4d139010015",
  "block_height": 1917071,
  "block_index": 0,
  "hash": "61474003e56d67aba6bf148c5ec361e3a3c1ceea37fe3ace7d87759b399292f9",
  "addresses": [
    "e2d7871ca37379ea18d259cdf3592fe032183d94"
  ],
  "total": 0,
  "fees": 8448706000000000,
  "size": 756,
  "gas_used": 206066,
  "gas_price": 41000000000,
  "contract_creation": true,
  "relayed_by": "",
  "confirmed": "2016-07-20T01:54:50Z",
  "received": "2016-07-20T01:54:50Z",
  "ver": 0,
  "double_spend": false,
  "vin_sz": 1,
  "vout_sz": 1,
  "confirmations": 5,
  "confidence": 1,
  "inputs": [
    {
      "sequence": 7,
      "addresses": [
        "e2d7871ca37379ea18d259cdf3592fe032183d94"
      ]
    }
  ],
  "outputs": [
    {
      "value": 0,
      "script": "606060405260405161023e38038061023e8339810160405280510160008054600160a060020a031916331790558060016000509080519060200190828054600181600116156101000203166002900490600052602060002090601f016020900481019282601f10609f57805160ff19168380011785555b50608e9291505b8082111560cc57600081558301607d565b50505061016e806100d06000396000f35b828001600101855582156076579182015b82811115607657825182600050559160200191906001019060b0565b509056606060405260e060020a600035046341c0e1b58114610026578063cfae321714610068575b005b6100246000543373ffffffffffffffffffffffffffffffffffffffff908116911614156101375760005473ffffffffffffffffffffffffffffffffffffffff16ff5b6100c9600060609081526001805460a06020601f6002600019610100868816150201909416939093049283018190040281016040526080828152929190828280156101645780601f1061013957610100808354040283529160200191610164565b60405180806020018281038252838181518152602001915080519060200190808383829060006004602084601f0104600f02600301f150905090810190601f1680156101295780820380516001836020036101000a031916815260200191505b509250505060405180910390f35b565b820191906000526020600020905b81548152906001019060200180831161014757829003601f168201915b5050505050905090560000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000001648656c6c6f20426c6f636b437970686572205465737400000000000000000000",
      "addresses": [
        "0eb688e79698d645df015cf2e9db5a6fe16357f1"
      ]
    }
  ]
}

The Create Contract Endpoint allows you to submit your solidity code and params to check raw serialized binary compilation and ABI. It’s an easy to validate your contract compiles before pushing it to the Ethereum blockchain.

If you include a private key (associated with a funded Ethereum external account), gas_limit, and contract(s) to publish, BlockCypher will embed the contract into the blockchain and return the transaction hash that created the contract and the contract address. Find both of those properties under the returned contract object as address and creation_tx_hash.

The params property lets you provide arguments to the contract constructor. If your contract has no constructor or the constructor takes no arguments, this property can be omitted.

You can optionally include value in wei to transfer to the contract on creation.

Note that for now both the contract solidity source and the ABI are made publicly available for anyone with the contract hash. We will support making the source private to your token in the future. However note that all contracts on the public Ethereum blockchain can be seen in binary form and it’s only a matter of time before good decompilers surface.

Resource Method Request Object Return Object
/contracts POST Contract Array[Contract]

Get Contract Address Endpoint


# and/or, check the contract address. if it was created by blockcypher, we'll return the code and ABI as well.
curl -s https://api.blockcypher.com/v1/eth/main/contracts/0eb688e79698d645df015cf2e9db5a6fe16357f1?token=YOURTOKEN
{
  "solidity": "contract mortal {\n  /* Define variable owner of the type address*/\n    address owner;\n    /* this function is executed at initialization and sets the owner of the contract */\n    function mortal() { owner = msg.sender; }\n    /* Function to recover the funds on the contract */\n    function kill() { if (msg.sender == owner) suicide(owner); }\n}\n\ncontract greeter is mortal {\n    /* define variable greeting of the type string */\n    string greeting;\n    /* this runs when the contract is executed */\n    function greeter(string _greeting) public {\n        greeting = _greeting;\n    }\n    /* main function */\n    function greet() constant returns (string) {\n        return greeting;\n    }\n}",
  "bin": "606060405260405161023e38038061023e8339810160405280510160008054600160a060020a031916331790558060016000509080519060200190828054600181600116156101000203166002900490600052602060002090601f016020900481019282601f10609f57805160ff19168380011785555b50608e9291505b8082111560cc57600081558301607d565b50505061016e806100d06000396000f35b828001600101855582156076579182015b82811115607657825182600050559160200191906001019060b0565b509056606060405260e060020a600035046341c0e1b58114610026578063cfae321714610068575b005b6100246000543373ffffffffffffffffffffffffffffffffffffffff908116911614156101375760005473ffffffffffffffffffffffffffffffffffffffff16ff5b6100c9600060609081526001805460a06020601f6002600019610100868816150201909416939093049283018190040281016040526080828152929190828280156101645780601f1061013957610100808354040283529160200191610164565b60405180806020018281038252838181518152602001915080519060200190808383829060006004602084601f0104600f02600301f150905090810190601f1680156101295780820380516001836020036101000a031916815260200191505b509250505060405180910390f35b565b820191906000526020600020905b81548152906001019060200180831161014757829003601f168201915b5050505050905090560000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000001648656c6c6f20426c6f636b437970686572205465737400000000000000000000",
  "abi": "[{\"constant\":false,\"inputs\":[],\"name\":\"kill\",\"outputs\":[],\"type\":\"function\"},{\"constant\":true,\"inputs\":[],\"name\":\"greet\",\"outputs\":[{\"name\":\"\",\"type\":\"string\"}],\"type\":\"function\"},{\"inputs\":[{\"name\":\"_greeting\",\"type\":\"string\"}],\"type\":\"constructor\"}]",
  "creation_tx_hash": "61474003e56d67aba6bf148c5ec361e3a3c1ceea37fe3ace7d87759b399292f9",
  "created": "2016-07-20T01:54:50Z",
  "address": "0eb688e79698d645df015cf2e9db5a6fe16357f1"
}
Resource Method Return Object
/contract/$ADDRESS GET Contract

ADDRESS is a string representing the contract address you’re interested in querying, for example:

0eb688e79698d645df015cf2e9db5a6fe16357f1

The returned object contains information about the contract; if you deployed the contract with BlockCypher, it will return solidity and abi as well.

Call Contract Method Endpoint

# call the greet method, using your own private key and gas amount to fund
cat call.json
{
    "private": "3ca40...",
    "gas_limit": 20000 
}
curl -d @call.json -s https://api.blockcypher.com/v1/eth/main/contracts/0eb688e79698d645df015cf2e9db5a6fe16357f1/greet?token=YOURTOKEN
{
  "gas_limit": 20000,
  "address": "0eb688e79698d645df015cf2e9db5a6fe16357f1",
  "results": [
    "Hello BlockCypher Test"
  ]
}

# use the same private key/gas amount to call the "kill" method, which causes the contract to create an internal_tx to refund the initial private key
curl -d @call.json -s https://api.blockcypher.com/v1/eth/main/contracts/0eb688e79698d645df015cf2e9db5a6fe16357f1/kill?token=YOURTOKEN
{"error": "Error calling contract: Gas value too low, intrinsic gas required is 53272.."}

# whoops! let's try upping the gas
cat call.json
{
    "private": "3ca40...",
    "gas_limit": 100000 
}
curl -d @call.json -s https://api.blockcypher.com/v1/eth/main/contracts/0eb688e79698d645df015cf2e9db5a6fe16357f1/kill?token=YOURTOKEN
{
  "gas_limit": 100000,
  "call_tx_hash": "42dc5862aeedf1001db37c404c8dc922918167589aba1e0b19c6a9372eedb294",
  "address": "0eb688e79698d645df015cf2e9db5a6fe16357f1"
}

The Call Contract Method endpoint makes every method in your contracts callable simply via an HTTP request. It’s a binding that translates a published contract into a set of endpoints (one for each method) and a provided JSON array into a set of arguments to invoke a given method.

To call a method on a given contract, you must include a private key associated with a funded external account and a specified gas_limit in your request object. params are optionally accepted if the contract method allows them. Make sure the JSON types your provide match your contract signature (string, number, etc.). You can optionally include value in wei to transfer to this contract method.

The Call Contract endpoint will check the contract ABI to determine whether the method has been declared “constant”. If so, no transaction will be created and no gas will be consumed. The method is just called locally on our servers and won’t be registered on the blockchain. Otherwise, we will build the call transaction to invoke the method on the Ethereum blockchain and propagate it on the network. Keep in mind that in that case, you will need to wait for the call transaction to be included in a block to see its effects.

Resource Method Request Object Return Object
/contracts/$ADDRESS/$METHOD POST Contract Contract

ADDRESS is a string representing the contract address you’re interested in querying, for example:

0eb688e79698d645df015cf2e9db5a6fe16357f1

METHOD is a string representing a declared method from the above contract; in the above example, the options are:

greet

or

kill

Events and Hooks

Ethereum is a highly transactional system. Many usage patterns require knowing when an event occurs: i.e., when a transaction is included into a block, when an address is updated, etc. Instead of requiring you to continuously poll resources, we provide push APIs to facilitate those use cases, and support WebHooks for that express purpose.

Types of Events

We support a number of different event types, and you can filter your notification requests depending on how you structure your Event request object.

Event Description
unconfirmed-tx Triggered for every new transaction BlockCypher receives before it’s confirmed in a block; basically, for every unconfirmed transaction. The payload is an unconfirmed TX.
new-block Triggered for every new block. The payload is a Block.
confirmed-tx Triggered for every new transaction making it into a new block; in other words, for every first transaction confirmation. This is equivalent to listening to the new-block event and fetching each transaction (or filtered transaction) in the new Block. The payload is a confirmed TX.
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 within the Event to manually specify the number of confirmations desired (maximum 10, defaults to 6). The payload is a TX.
double-spend-tx Triggered any time a double spend is detected by BlockCypher. The payload is the TX that triggered the event; the hash of the transaction that it’s trying to double spend is included in its double_spend_tx property.

Using WebHooks

For WebHooks, the JSON Event should be sent using a POST request to the “create webhook endpoint” and include a url property to denote where payloads should be delivered. The TX or Block associated with the Event will be POSTed to the provided url. The POSTed payload will also include X-EventType and X-EventId metadata in the HTTP header specifying the event type and id of the WebHook which triggered the payload.

We retry individual payloads to your url five times; if one fails, we wait exponentially between retries: 1 second, 2s, 4s, 8s, 16s. In order to protect against stale callback urls, your Event will be deleted if it reaches 50 aggregate callback_errors from failed payloads.

Create WebHook Endpoint

curl -sd '{"event": "unconfirmed-tx", "address": "c5beef03aaa9548210b5550a62f7756efaa08ba3", "url": "https://my.domain.com/callbacks/new-tx"}' https://api.blockcypher.com/v1/eth/main/hooks?token=YOURTOKEN
{
  "id": "ce83d08f-7b86-4a6a-9b41-85507648f9c7",
  "token": "YOURTOKEN",
  "url": "https://my.domain.com/callbacks/new-tx",
  "callback_errors": 0,
  "address": "c5beef03aaa9548210b5550a62f7756efaa08ba3",
  "event": "unconfirmed-tx",
  "filter": "addr=c5beef03aaa9548210b5550a62f7756efaa08ba3\u0026event=unconfirmed-tx"
}

Using a partially filled out Event, you can create a WebHook using this resource. Check the Event object description and types of events to understand the available options.

Resource Method Request Object Return Object
/hooks POST Event Event

If successful, it will return the Event with a newly generated id.

List WebHooks Endpoint

curl -s https://api.blockcypher.com/v1/eth/main/hooks?token=YOURTOKEN
[
  {
    "id": "ce83d08f-7b86-4a6a-9b41-85507648f9c7",
    "token": "YOURTOKEN",
    "url": "https://my.domain.com/callbacks/new-tx",
    "callback_errors": 0,
    "address": "c5beef03aaa9548210b5550a62f7756efaa08ba3",
    "event": "unconfirmed-tx",
    "filter": "addr=c5beef03aaa9548210b5550a62f7756efaa08ba3\u0026event=unconfirmed-tx"
  }
]

This resource lists your currently active events, according to the base resource and $YOURTOKEN.

Resource Method Return Object
/hooks?token=$YOURTOKEN GET Array[Event]

WebHook ID Endpoint

curl -s https://api.blockcypher.com/v1/eth/main/hooks/ce83d08f-7b86-4a6a-9b41-85507648f9c7?token=YOURTOKEN
{
  "id": "ce83d08f-7b86-4a6a-9b41-85507648f9c7",
  "token": "YOURTOKEN",
  "url": "https://my.domain.com/callbacks/new-tx",
  "callback_errors": 0,
  "address": "c5beef03aaa9548210b5550a62f7756efaa08ba3",
  "event": "unconfirmed-tx",
  "filter": "addr=c5beef03aaa9548210b5550a62f7756efaa08ba3\u0026event=unconfirmed-tx"
}

This resource returns an Event based on its generated id.

Resource Method Return Object
/hooks/$WEBHOOKID GET Event

WEBHOOKID is a string representing the event’s generated id, for example:

ce83d08f-7b86-4a6a-9b41-85507648f9c7

Delete WebHook Endpoint

# Piping into grep to get status code
curl -X DELETE -Is https://api.blockcypher.com/v1/eth/main/hooks/ce83d08f-7b86-4a6a-9b41-85507648f9c7?token=YOURTOKEN | grep "HTTP/1.1"
HTTP/1.1 204 No Content

This resource deletes an active Event based on its id. Remember to include your token, or the request will fail.

Resource Method Return Object
/hooks/$WEBHOOKID DELETE nil

WEBHOOKID is a string representing the event’s generated id, for example:

ce83d08f-7b86-4a6a-9b41-85507648f9c7

If successful, it won’t return any objects, but will respond with an HTTP Status Code 204.