Blockchain WebHooks Logo

Bitcoin Testnet API Documentation (Test Network)

TBTC API Docs - JSON

Overview

Blockchain WebHooks is a simple and reliable service which will POST transaction data to the URL you provide. Our WebHooks are triggered after the first confirmation occurs on the blockchain for that transaction. See the API Endpoints tab for detailed information on how to interact with the API.

Sign up to begin using our interactive API docs for testing.

Security

We recommend that you use a HTTPS callback URL. Also, we POST the transaction data to the exact url given when setting the WebHook, so this allows you add a parameter to the url and check on your server for the presense of this parameter, ensuring it was not modified.

Support

We're here to help! If you have any questions or concerns, contact us

Sign up to begin using our interactive API docs for testing.

Use this endpoint to watch a TBTC address for new transactions. It takes 3 parameters, address, callback_url, and post_on_confirmation (optional). The address is the TBTC address you'd like us to watch. The callback_url is where we will POST the transaction data payload, if a new confirmed transaction enters the block with the address you specified. post_on_confirmations is the number of transaction confirmations until we POST the transaction data to your callback URL. See below for more details.

URL Endpoint (with API token as query parameter)

https://blockchainwebhooks.com/api/tbtc/v1/webhooks/create?token=<api_token>

Method

POST

JSON Request Header Parameters

Content-Type: application/json

JSON Request Data Payload

{
"address": "<tbtc_address>",
"callback_url": "https://mydomain.com/callbacks"
"post_on_confirmation": 1
}

Request Attribute Details
Attribute Type Description
address string TBTC address which will trigger this webhook.
callback_url string When a new transaction associated with the address enters a block, we will POST the comprehensive transaction data to this URL.
post_on_confirmation (optional) integer Number of transaction confirmations until we POST the transaction data to your callback URL. Enter 1-100, default is 1. Example: If set to 6, we will wait until the new transaction has 6 confirmations before POSTing the transaction data to your URL.
JSON Response Payload (Success)

{
"id": "<webhook_id>",
"address": "<tbtc_address>",
"callback_url": "https://mydomain.com/callbacks"
"post_on_confirmation": 6
}

For error responses/codes, see Errors section below.

Triggered WebHook Example (returns transaction data payload)

Below is an example of the transaction payload that will be sent via HTTP POST. WebHooks are triggered if the address is part of a new transaction entering a block, as the sender or the receiver. We trigger the WebHook after the first transaction confirmation. This payload will be sent to the callback_url which you provided when creating the WebHook:

{
"webhook_id": "<webhook_id_which_triggered_this_callback>",
"webhook_address": "<btc_address_tied_to_webhook_id>",
"webhook_coin": "BTC",
"txid": "c3f11d1708ac20eff9137d4eadd62dd99d71ce22dc51bc51d4e5b83958d9596d",
"hash": "c3f11d1708ac20eff9137d4eadd62dd99d71ce22dc51bc51d4e5b83958d9596d",
"time": 1532667469,
"block_hash": "00000000000000039c7bddf69647024f301800d7031d868cfeee1cc3d5586c26",
"block_height": 1355653,
"blocktime": 1532667469,
"block_tx_index": 1
"all_addresses": [
    "mmQQv9mRSyoo79YxNbui5VpYCh9eYq81Ao",
    "mrZ45b9PHCP25EBgiCpVtbuVBfzvJR8HqQ"
],
"confirmations": 280,
"fees": 708000, # fees are in satoshis
"total_input_amt": 87475000, # in satoshis
"total_output_amt": 86767000, # in satoshis
"output_count": 1,
"outputs": [
    {
    "addresses": [
        "mrZ45b9PHCP25EBgiCpVtbuVBfzvJR8HqQ"
    ],
    "hex": "76a914790f0b7165352689de319d013cf1816b74bc2b2e88ac",
    "asm": "OP_DUP OP_HASH160 790f0b7165352689de319d013cf1816b74bc2b2e OP_EQUALVERIFY_OP_CHECKSIG",
    "value": 86767000,
    "script_type": "pubkeyhash",
    "reqSigs": 1
    }
],
"input_count": 1,
"inputs": [
    {
    "addresses": [
        "mmQQv9mRSyoo79YxNbui5VpYCh9eYq81Ao"
    ],
    "previous_hash": "aea4e741ff1ab58b9f4c6ac21455aae0ba201c0ddf12e93458590e45d7939ed3",
    "previous_hash_output_index": 0,
    "output_value": 87475000
    "script_type": "pubkeyhash",
    "scriptSig": {
        "asm": "3045022100ebb7ff7440eab2929048535...490a78bf42886d34125e06d7648b296c2"
        "hex": "483045022100ebb7ff7440eaba06fba50...c3db0ecef7efe02b5447f71f57abaa116"
    },
    "sequence": 4294967295,
    }
],
"version": 1,
"locktime": 0,
"size": 284,
"vsize": 284,
"hex": "0100000001d39e93d7450e595834e91f935u2gh...de319d013cf1816b74bcac00000000",
}

Triggered WebHook Attributes
Attribute Type Description
webhook_id string Blockchain WebHook ID which triggered this callback.
webhook_address string Address tied to the WebHook ID.
webhook_coin string Coin symbol tied to WebHook ID.
txid string Transaction ID.
hash string Hash for transaction. Note: this will be the same as the txid for non-Segwit transactions, but different than txid for Segwit transactions.
time integer Unix transaction timestamp.
block_hash string Block hash for this transaction.
block_height integer Block height for this transaction.
blocktime integer Unix timestamp of block for this transaction.
block_tx_index integer Zero-based transaction index for this transaction in the block's transaction list. For example, if this tx was the 5th transaction in the block, the block_tx_index would be 4.
all_addresses array All input/output addresses contained in this transaction.
confirmations integer Number of confirmations for this transactions. Any amount over 6 is considered irreversible.
fees integer Fees for this transaction, in satoshis.
total_input_amt integer Total of all inputs for this transactions, in satoshis.
total_output_amt integer Total of all outputs for this transactions, in satoshis.
output_count integer Total number of outputs for this transaction.
outputs array Array of output hashes (see below for output hash details)
addresses array Address for output. (part of output hash)
hex string Hexadecimal data for output. (part of output hash)
asm string Assembly symbolic representation data for output. (part of output hash)
value integer Value of this output, in satoshis. (part of output hash)
script_type string Script type for this output. (part of output hash)
reqSigs integer Number of request signatures for this output. (part of output hash)
input_count integer Total number of inputs for this transaction.
inputs array input hashes (see below for input hash details)
addresses array Address for input. (part of input hash)
previous_hash string Every input is an unspent output of a different transactions. This is the previous unspent output hash for this input. (part of input hash)
previous_hash_output_index integer Output index for the "previous_hash" attribute above, zero-based. (part of input hash)
output_value integer Output value for this input, in satoshis. (part of input hash)
script_type string Script type for this input. (part of input hash)
sciptSig hash Scipt signature data for this input. More details below. (part of input hash)
asm string Assembly symbolic representation data for input. (part of scriptSig hash)
hex string Hexadecimal data for input. (part of scriptSig hash)
sequence integer Sequence number for this input. (part of input hash)
version integer Version for this transaction.
locktime integer Locktime for this transaction.
size integer Transaction size, in bytes.
vsize integer Virtual transaction size, in bytes.
hex string Transaction data in hexidecimal format.
URL Endpoint (with API token as query parameter)

https://blockchainwebhooks.com/api/tbtc/v1/webhooks/<webhook_id>?token=<api_token>

Method

GET

JSON Request Header Parameters

Content-Type: application/json

JSON Response Payload (Success)

{
"id": "SKEqtYqiengqviLDLmi1zVQin8vUmmQsrU0zBFY2l5vPOclscp",
"address": "16JDABa9gYTfQNK7YPVPghL98cGyGAZG1H",
"callback_url": "https://mydomain.com/callbacks"
"post_on_confirmation": 10
}

For error responses/codes, see Errors section below.

URL Endpoint (with API token as query parameter)

https://blockchainwebhooks.com/api/tbtc/v1/webhooks/<webhook_id>?token=<api_token>

Method

DELETE

JSON Request Header Parameters

Content-Type: application/json

JSON Response Payload (Success)

{
"id": "<webhook_id>",
"address": "<tbtc_address>",
"callback_url": "https://mydomain.com/callbacks"
"post_on_confirmation": 1
}

For error responses/codes, see Errors section below.

Use this endpoint to list all of your set WebHooks for any TBTC address. Refer to the endpoint below if you'd like to list all of your set WebHooks for all addresses.

Note: URL path is blockchainwebhooks.com/api/all/...

URL Endpoint (with API token as query parameter)

https://blockchainwebhooks.com/api/all/v1/webhooks/list/tbtc?token=<api_token>

Method

GET

JSON Request Header Parameters

Content-Type: application/json

JSON Response Payload (Success)

[
    {
    "id": "<webhook_id>",
    "address": "<tbtc_address>",
    "callback_url": "https://mydomain.com/callbacks"
    "coin": "TBTC"
    "post_on_confirmation": 6
    },
    {
    "id": "SKEqtYqiengqviLDLmi1zVQin8vUmmQsrU0zBFY2l5vPOclscp",
    "address": "3KwRZZrVitTewPiDE7c5yMdEcVUkC9U9CP",
    "callback_url": "https://mydomain.com/callbacks"
    "coin": "TBTC"
    "post_on_confirmation": 1
    }
]

For error responses/codes, see Errors section below.

Use this endpoint to list all of your set WebHooks for any cryptocurrency address. Refer to the endpoint above if you'd like to list all of your set WebHooks for any TBTC address.

Note: URL path is blockchainwebhooks.com/api/all/...

URL Endpoint (with API token as query parameter)

https://blockchainwebhooks.com/api/all/v1/webhooks/list?token=<api_token>

Method

GET

JSON Request Header Parameters

Content-Type: application/json

JSON Response Payload (Success)

[
    {
    "id": "<webhook_id>",
    "address": "<tbtc_address>",
    "callback_url": "https://mydomain.com/callbacks"
    "coin": "TBTC"
    "post_on_confirmation": 1
    },
    {
    "id": "SKEqtYqiengqviLDLmi1zVQin8vUmmQsrU0zBFY2l5vPOclscp",
    "address": "<btc_address>",
    "callback_url": "https://mydomain.com/callbacks"
    "coin": "BTC"
    "post_on_confirmation": 1
    }
]

For error responses/codes, see Errors section below.

Callback URL Failure

If a triggered WebHook fails, we will resend to your callback_url five times, waiting exponentially longer with each failure. To protect against stale callback urls, your WebHook will be deleted after 50 failed attempts, and we will send you one notification email per failed callback_url.

JSON Response Payload (Failure)

{
"error_message": "<error_message>",
}

HTTP Status Codes
Status Code Description
200 OK - request was successful
400 Bad Request - server cannot or will not process the request, see <error_message> for details.
429 Too Many Requests - max WebHook count or max requests per sec/hr has been reached.
500 Internal Server Error - Unexpected error has occurred.