Introduction
WhatsOnChain provides access to Bitcoin SV blocks, transactions, address activity, On Chain data, stats and much more via simple REST API.
You can also use this API to broadcast transactions.
Supported Networks:
- Mainnet
- Testnet
- STN
##### ##### ,,,,,,,,,,,,,,, #################
###### ###### ,,,,,,,,,,,,, #####################
##### ##### ,,,,,,,,,,,,, #######################
##### ,,, ### ### ,,, ####
##### #### ,,,, ### ### ,,,,
##### #### ,,,, ### ### ,,,,
##### #### ,,,, # # ,,,, ####
################# ,,,,,,,,,,,,,,,,,,,,,,,,,, ################
################# ,,,,,,,,,,,,,,,,,,,,,,, ################
################# ,,,,,,,,,,,,,,,,,,, ###############
Authentication
At this stage no authentication is required.
Rate Limits
Up to 3 requests/sec. Need more? Please let us know in the WoC devs telegram channel or send us an email at [email protected]
Health
Get api status
curl "https://api.whatsonchain.com/v1/bsv/main/woc"
The above request returns below plain text response:
"Whats On Chain"
Simple endpoint to show that the API server is up and running
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/woc
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main , test or stn |
Chain Info
Get blockchain info
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/chain/info"
Response JSON structure:
{
"chain": "main",
"blocks": 635302,
"headers": 635299,
"bestblockhash": "000000000000000002a40d7410a6c08109521c14f4cf354e7b352b4eab8aa4ea",
"difficulty": 287310033717.7086,
"mediantime": 1589703256,
"verificationprogress": 0.9999754124031851,
"pruned": false,
"chainwork": "0000000000000000000000000000000000000000010969f724913e0fe59377f4"
}
This endpoint retrieves information about the state of the chain for the selected network.
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/chain/info
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main , test or stn |
Get circulating supply
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/circulatingsupply"
Response:
18227675
This endpoint retrieves the circulating supply of BSV.
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/circulatingsupply
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main |
Get chain tips
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/chain/tips"
Response JSON structure:
[
{
"height": 721622,
"hash": "000000000000000005693b8ef945a19fd269d2b19ebbad74e3d98d4427b2f1e0",
"branchlen": 0,
"status": "active"
},
{
"height": 721213,
"hash": "00000000000000000478d6745b0f4060f1a00c143846a99b2dd6e1ee0e7492a0",
"branchlen": 1,
"status": "valid-fork"
},
...
]
This endpoint retrieves information about all known tips in the block tree.
Possible values for status:
- invalid: This branch contains at least one invalid block
- headers-only: Not all blocks for this branch are available, but the headers are valid
- valid-headers: All blocks are available for this branch, but they were never fully validated
- valid-fork: This branch is not part of the active chain, but is fully validated
- active: This is the tip of the active main chain, which is certainly valid
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/chain/tips
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main |
Block
Get by hash
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/block/hash/000000000000000004a288072ebb35e37233f419918f9783d499979cb6ac33eb"
Response JSON structure:
{
"hash": "000000000000000004a288072ebb35e37233f419918f9783d499979cb6ac33eb",
"confirmations": 89,
"size": 14421,
"height": 575045,
"version": 536928256,
"versionHex": "2000e000",
"merkleroot": "4ebcba09addd720991d03473f39dce4b9a72cc164e505cd446687a54df9b1585",
"txcount": 5,
"tx": [
"bb146889d71357667c58a37258f40b0521a6ba7a259fbfa721b747d55567551a",
"c7e8317b48e72644e2b83c87c54f61bcda82326392f969a097fb801aed69b500",
"fd39debc631cf1a97702052fa60303d53062d6f2c1b624ab1f5fc0d20233736f",
"65cb37947ccb7c5b7cc4ac36a200613bfc39a7f7c6c0314a23dbcc5b3908b5b8",
"0f9d562702259822778193ff46f0c6d5e4aa744a433982770d3134e2bf454d10"
],
"time": 1553416668,
"mediantime": 1553414858,
"nonce": 87914848,
"bits": "180997ee",
"difficulty": 114608607557.4425,
"chainwork": "000000000000000000000000000000000000000000ddf5d385546872bab7dc01",
"previousblockhash": "00000000000000000988156c7075dc9147a5b62922f1310862e8b9000d46dd9b",
"nextblockhash": "00000000000000000112b36a37c10235fa0c991f680bc5482ba9692e0ae697db",
"coinbaseTx": {
"hex": "01000000010000000000000000000000000000000000000000000000000000000000000000ffffffff220345c6082f626d67706f6f6c2e636f6d2f473173717918707a8aae4a936f101e0000ffffffff018ed9814a000000001976a91485770ad0ee64a4f3ee4027e199c32f876e03a2d988ac00000000",
"txid": "bb146889d71357667c58a37258f40b0521a6ba7a259fbfa721b747d55567551a",
"hash": "bb146889d71357667c58a37258f40b0521a6ba7a259fbfa721b747d55567551a",
"size": 119,
"version": 1,
"locktime": 0,
"vin": [
{
"txid": "",
"vout": 0,
"scriptSig": {
"asm": "",
"hex": ""
},
"sequence": 4294967295,
"coinbase": "0345c6082f626d67706f6f6c2e636f6d2f473173717918707a8aae4a936f101e0000"
}
],
"vout": [
{
"value": 12.50023822,
"n": 0,
"scriptPubKey": {
"asm": "OP_DUP OP_HASH160 85770ad0ee64a4f3ee4027e199c32f876e03a2d9 OP_EQUALVERIFY OP_CHECKSIG",
"hex": "76a91485770ad0ee64a4f3ee4027e199c32f876e03a2d988ac",
"reqSigs": 1,
"type": 0,
"addresses": ["1DAhUiQxHzL1oAusoUDdUM89spXuAG1sqy"],
"opReturn": null
}
}
],
"blockhash": "000000000000000004a288072ebb35e37233f419918f9783d499979cb6ac33eb",
"confirmations": 89,
"time": 1553416668,
"blocktime": 1553416668
},
"totalFees": 0.0002382199999999557,
"miner": "Bmgpool",
"pages": null
}
This endpoint retrieves the block details of a given hash.
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/block/hash/<hash>
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main , test or stn |
hash | The hash of the block to retrieve |
Get by height
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/block/height/575191"
Response JSON structure:
{
"hash": "0000000000000000091216c46973d82db057a6f9911352892b7769ed517681c3",
"confirmations": 1,
"size": 611,
"height": 575191,
"version": 536870912,
"versionHex": "20000000",
"merkleroot": "95a920b1002bed05379a0d2650bb13eb216138f28ee80172f4cf21048528dc60",
"txcount": 3,
"tx": [
"c1d32f28baa27a376ba977f6a8de6ce0a87041157cef0274b20bfda2b0d8df96",
"7e0ba1980522125f1f40d19a249ab3ae036001b991776813d25aebe08e8b8a50",
"5c4d44b9b8d2ec6e0835ac90f206cecb26bf51033f31d4c659975b7534853409"
],
"time": 1553501874,
"mediantime": 1553499038,
"nonce": 2482491775,
"bits": "180978d5",
"difficulty": 116078424449.9863,
"chainwork": "000000000000000000000000000000000000000000de04fc280ef3a599fbadde",
"previousblockhash": "00000000000000000012ce7f4bbce3346ac438ab7fdcb6fa5440db9857856a7f",
"nextblockhash": "",
"coinbaseTx": {
"hex": "01000000010000000000000000000000000000000000000000000000000000000000000000ffffffff1c03d7c6082f7376706f6f6c2e636f6d2f3edff034600055b8467f0040ffffffff01247e814a000000001976a914492558fb8ca71a3591316d095afc0f20ef7d42f788ac00000000",
"txid": "c1d32f28baa27a376ba977f6a8de6ce0a87041157cef0274b20bfda2b0d8df96",
"hash": "c1d32f28baa27a376ba977f6a8de6ce0a87041157cef0274b20bfda2b0d8df96",
"size": 113,
"version": 1,
"locktime": 0,
"vin": [
{
"txid": "",
"vout": 0,
"scriptSig": {
"asm": "",
"hex": ""
},
"sequence": 4294967295,
"coinbase": "03d7c6082f7376706f6f6c2e636f6d2f3edff034600055b8467f0040"
}
],
"vout": [
{
"value": 12.5000042,
"n": 0,
"scriptPubKey": {
"asm": "OP_DUP OP_HASH160 492558fb8ca71a3591316d095afc0f20ef7d42f7 OP_EQUALVERIFY OP_CHECKSIG",
"hex": "76a914492558fb8ca71a3591316d095afc0f20ef7d42f788ac",
"reqSigs": 1,
"type": 0,
"addresses": ["17fm4xevwDh3XRHv9UoqYrVgPMbwcGHsUs"],
"opReturn": null
}
}
],
"blockhash": "0000000000000000091216c46973d82db057a6f9911352892b7769ed517681c3",
"confirmations": 1,
"time": 1553501874,
"blocktime": 1553501874
},
"totalFees": 0.000004199999999343618,
"miner": "SVpool",
"pages": null
}
This endpoint retrieves the block details of a given block height.
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/block/height/<height>
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main , test or stn |
height | The height of the block to retrieve |
Get block pages
If the block has more that 100 transactions the page URIs will be provided in the pages element when getting a block by hash or height.
Example pages element in Get block by height or hash response
{
"hash": "000000000000000004a288072ebb35e37233f419918f9783d499979cb6ac33eb",
...
"pages": {
"uri": [
"/block/hash/000000000000000000885a4d8e9912f085b42288adc58b3ee5830a7da9f4fef4/page/1",
"/block/hash/000000000000000000885a4d8e9912f085b42288adc58b3ee5830a7da9f4fef4/page/2",
...
],
"size": 50000
}
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/block/hash/000000000000000000885a4d8e9912f085b42288adc58b3ee5830a7da9f4fef4/page/1"
Response JSON structure:
[
"89b4e01ea1ab27edb6ea66899637b526faebeb42ca0302ff9ed916670f1330fe",
"1097bfc9b1f586352a1ab29afd27c1f89e0a5d9790ea08a2b2a7d988ea6f2cfe",
....
]
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/block/hash/<hash>/page/<number>
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main , test or stn |
hash | The hash of the block to retrieve |
number | Page number |
Get header by hash
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/block/000000000000000004a288072ebb35e37233f419918f9783d499979cb6ac33eb/header"
Response JSON structure:
{
"hash": "000000000000000004a288072ebb35e37233f419918f9783d499979cb6ac33eb",
"confirmations": 68461,
"height": 575045,
"version": 536928256,
"versionHex": "2000e000",
"merkleroot": "4ebcba09addd720991d03473f39dce4b9a72cc164e505cd446687a54df9b1585",
"time": 1553416668,
"mediantime": 1553414858,
"nonce": 87914848,
"bits": "180997ee",
"difficulty": 114608607557.4425,
"chainwork": "000000000000000000000000000000000000000000ddf5d385546872bab7dc01",
"previousblockhash": "00000000000000000988156c7075dc9147a5b62922f1310862e8b9000d46dd9b",
"nextblockhash": "00000000000000000112b36a37c10235fa0c991f680bc5482ba9692e0ae697db"
}
This endpoint retrieves the block header details of a given hash.
Use '?format=block-headers-client' as a query parameter for the block-headers-client response format.
Possible values for the status when the block-headers-client format is requested:
- active: Block is part of the current active chain.
- orphaned: Block is not part the current active chain.
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/block/<hash>/header
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main , test or stn |
hash | The hash of the block to retrieve |
Get headers
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/block/headers"
Response JSON structure:
[
{
"hash": "00000000000000000091302d4e60d7f795891ed6355da673bf48179b5d6bb8bf",
"confirmations": 1,
"height": 643505,
"version": 536870912,
"versionHex": "20000000",
"merkleroot": "c842e7a774687c83b801c6e7c00344e9c6691f5ed9512c9b21c752821cb6e11e",
"time": 1594656963,
"mediantime": 1594632849,
"nonce": 1235689794,
"bits": "180322f4",
"difficulty": 350544350572.5941,
"chainwork": "000000000000000000000000000000000000000001115d6ba65662692dd816d6",
"previousblockhash": "000000000000000001a49ccb1c689f0cb2d1a29942ca0631027f9cef221cc5a8",
"nextblockhash": ""
},
{
"hash": "000000000000000001a49ccb1c689f0cb2d1a29942ca0631027f9cef221cc5a8",
"confirmations": 2,
"height": 643504,
"version": 545259520,
"versionHex": "20800000",
"merkleroot": "4b4336460f3f61bfec51608a986f765a9dbd5f9662159cba91a8e7725116cf1d",
"time": 1594653910,
"mediantime": 1594629833,
"nonce": 701438478,
"bits": "1802d84a",
"difficulty": 386482093768.0359,
"chainwork": "000000000000000000000000000000000000000001115d1a07f27698a9ee58d8",
"previousblockhash": "0000000000000000014ad36062380b1d86a84c98fc97eee672f96e3f5f8c2528",
"nextblockhash": "00000000000000000091302d4e60d7f795891ed6355da673bf48179b5d6bb8bf"
},
...
]
This endpoint retrieves the last 10 block headers.
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/block/headers
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main , test or stn |
Transaction
Get by tx hash
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/tx/hash/c1d32f28baa27a376ba977f6a8de6ce0a87041157cef0274b20bfda2b0d8df96"
Response JSON structure:
{
"txid": "c1d32f28baa27a376ba977f6a8de6ce0a87041157cef0274b20bfda2b0d8df96",
"hash": "c1d32f28baa27a376ba977f6a8de6ce0a87041157cef0274b20bfda2b0d8df96",
"size": 113,
"version": 1,
"locktime": 0,
"vin": [
{
"txid": "",
"vout": 0,
"scriptSig": {
"asm": "... ",
"hex": "..."
},
"sequence": 4294967295,
"coinbase": "03d7c6082f7376706f6f6c2e636f6d2f3edff034600055b8467f0040"
}
],
"vout": [
{
"value": 12.5000042,
"n": 0,
"scriptPubKey": {
"asm": "OP_DUP OP_HASH160 492558fb8ca71a3591316d095afc0f20ef7d42f7 OP_EQUALVERIFY OP_CHECKSIG", // (max 100 KB)
"hex": "76a914492558fb8ca71a3591316d095afc0f20ef7d42f788ac", // (max 100 KB)
"reqSigs": 1,
"type": 0,
"addresses": ["17fm4xevwDh3XRHv9UoqYrVgPMbwcGHsUs"],
"opReturn": null,
"isTruncated": false
}
}
],
"blockhash": "0000000000000000091216c46973d82db057a6f9911352892b7769ed517681c3",
"confirmations": 2,
"time": 1553501874,
"blocktime": 1553501874
}
This endpoint retrieves the transaction details for a given transaction hash.
In the response body, if any output hex size (vout[x].scriptPubKey.hex) exceeds 100KB then data for
vout[x].scriptPubKey.hex and
vout[x].scriptPubKey.asm
is truncated and a flag vout[x].scriptPubKey.isTruncated is set to true.
A separate endpoint get raw transaction output data can be used to fetch the full hex data if required by the client application.
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/tx/hash/<hash>
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main , test or stn |
hash | The hash/txId of the transaction to retrieve |
Broadcast transaction
curl --location --request POST "https://api.whatsonchain.com/v1/bsv/main/tx/raw" \
--header "Content-Type: application/json" \
--data "{\"txhex\": \"hex...\" }"
The JSON structure for the above post request:
{
"txhex": "hex..."
}
Broadcast transaction using this endpoint. Get txid in response or error msg from the node with header content-type: text/plain.
HTTP Request
POST https://api.whatsonchain.com/v1/bsv/<network>/tx/raw
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main , test or stn |
Request Body
Parameter | Description |
---|---|
txhex | Raw transaction data in hex |
Bulk transaction details
curl --location --request POST "https://api.whatsonchain.com/v1/bsv/main/txs" \
--header "Content-Type: application/json" \
--data "{\"txids\" : [\"294cd1ebd5689fdee03509f92c32184c0f52f037d4046af250229b97e0c8f1aa\",\"91f68c2c598bc73812dd32d60ab67005eac498bef5f0c45b822b3c9468ba3258\" ] }"
The JSON structure for the above post request:
{
"txids": [
"294cd1ebd5689fdee03509f92c32184c0f52f037d4046af250229b97e0c8f1aa",
"91f68c2c598bc73812dd32d60ab67005eac498bef5f0c45b822b3c9468ba3258"
]
}
Fetch details for multiple transactions in single request
- Max 20 transactions per request
HTTP Request
POST https://api.whatsonchain.com/v1/bsv/<network>/txs
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main , test or stn |
Bulk transaction status
curl --location --request POST "https://api.whatsonchain.com/v1/bsv/main/txs/status" \
--header "Content-Type: application/json" \
--data "{\"txids\" : [\"294cd1ebd5689fdee03509f92c32184c0f52f037d4046af250229b97e0c8f1aa\",\"91f68c2c598bc73812dd32d60ab67005eac498bef5f0c45b822b3c9468ba3258\" ] }"
The JSON structure for the above post request:
{
"txids": [
"294cd1ebd5689fdee03509f92c32184c0f52f037d4046af250229b97e0c8f1aa",
"91f68c2c598bc73812dd32d60ab67005eac498bef5f0c45b822b3c9468ba3258"
]
}
Response JSON structure:
[
{
"txid": "294cd1ebd5689fdee03509f92c32184c0f52f037d4046af250229b97e0c8f1aa",
"blockhash": "000000000000000004b5ce6670f2ff27354a1e87d0a01bf61f3307f4ccd358b5",
"blockheight": 612251,
"blocktime": 1575841517,
"confirmations": 86479
},
{
"txid": "91f68c2c598bc73812dd32d60ab67005eac498bef5f0c45b822b3c9468ba3258",
"blockhash": "000000000000000002e8d4b4c0385abd195709c82f16d9917f081b70000e8804",
"blockheight": 617279,
"blocktime": 1578837295,
"confirmations": 81451
}
]
Get multiple transactions status in a single request
- Max 20 transactions per request
HTTP Request
POST https://api.whatsonchain.com/v1/bsv/<network>/txs/status
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main or test |
Decode transaction
curl --location --request POST "https://api.whatsonchain.com/v1/bsv/main/tx/decode" \
--header "Content-Type: application/json" \
--data "{\"txhex\": \"hex...\" }"
Post request body JSON structure:
{
"txhex": "hex..."
}
Response JSON structure:
{
"txid": "c203094f5bacd5d5dcabb997adab1923b3ec9b91667ff230cac51504e34a382d",
"hash": "c203094f5bacd5d5dcabb997adab1923b3ec9b91667ff230cac51504e34a382d",
"version": 1,
"size": 111,
"locktime": 0,
"vin": [
{
"coinbase": "03fc3b092f7376706f6f6c2e636f6d2f49a4a636f07dad7dc7c30100",
"sequence": 4294967295
}
],
"vout": [
{
"value": 12.52346603,
"n": 0,
"scriptPubKey": {
"asm": "OP_HASH160 1314c7eace4d4da3f65a1341197bb58038aa9dbc OP_EQUAL",
"hex": "a9141314c7eace4d4da3f65a1341197bb58038aa9dbc87",
"reqSigs": 1,
"type": "scripthash",
"addresses": ["33Ruf5AZhSPHSCGbYiuu3xG5V3HvoNFfby"]
}
}
],
"hex": "01000000010000000000000000000000000000000000000000000000000000000000000000ffffffff1c03fc3b092f7376706f6f6c2e636f6d2f49a4a636f07dad7dc7c30100ffffffff01eb4aa54a0000000017a9141314c7eace4d4da3f65a1341197bb58038aa9dbc8700000000"
}
Decode raw transaction using this endpoint. Get json in response or error msg from node.
HTTP Request
POST https://api.whatsonchain.com/v1/bsv/<network>/tx/decode
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main , test or stn |
Request Body
Parameter | Description |
---|---|
txhex | Raw transaction data in hex |
Download receipt
curl --location --request GET "https://main.whatsonchain.com/receipt/4bdbdb7483c1c7ef48cda78ee4141af7cf15f94e10324e0bcac43c29394ea4a9"
Download transaction receipt (PDF)
HTTP Request
GET https://<network>.whatsonchain.com/receipt/<hash>
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main , test or stn |
hash | The hash/txId of the transaction |
Get raw transaction data
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/tx/c1d32f28baa27a376ba977f6a8de6ce0a87041157cef0274b20bfda2b0d8df96/hex"
Get raw transaction data in hex
Response with header content-type: text/plain:
01000000010000000000000000000000000000000000000000000000000000000000000000ffffffff1c03d7c6082f7376706f6f6c2e636f6d2f3edff034600055b8467f0040ffffffff01247e814a000000001976a914492558fb8ca71a3591316d095afc0f20ef7d42f788ac00000000
This endpoint returns raw hex for the transaction with given hash
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/tx/<hash>/hex
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main or test |
hash | The hash/txId of the transaction |
Bulk raw transaction data
curl --location --request POST "https://api.whatsonchain.com/v1/bsv/main/txs/hex" \
--header "Content-Type: application/json" \
--data "{\"txids\" : [\"294cd1ebd5689fdee03509f92c32184c0f52f037d4046af250229b97e0c8f1aa\",\"91f68c2c598bc73812dd32d60ab67005eac498bef5f0c45b822b3c9468ba3258\" ] }"
The JSON structure for the above post request:
{
"txids": [
"294cd1ebd5689fdee03509f92c32184c0f52f037d4046af250229b97e0c8f1aa",
"91f68c2c598bc73812dd32d60ab67005eac498bef5f0c45b822b3c9468ba3258"
]
}
Response JSON structure:
[
{
"txid": "294cd1ebd5689fdee03509f92c32184c0f52f037d4046af250229b97e0c8f1aa",
"hex": "0100000001...00000000",
"blockhash": "000000000000000004b5ce6670f2ff27354a1e87d0a01bf61f3307f4ccd358b5",
"blockheight": 612251,
"blocktime": 1575841517,
"confirmations": 86479
},
{
"txid": "91f68c2c598bc73812dd32d60ab67005eac498bef5f0c45b822b3c9468ba3258",
"hex": "0100000001...00000000",
"blockhash": "000000000000000002e8d4b4c0385abd195709c82f16d9917f081b70000e8804",
"blockheight": 617279,
"blocktime": 1578837295,
"confirmations": 81451
}
]
Get multiple transactions raw data in hex in a single request
- Max 20 transactions per request
HTTP Request
POST https://api.whatsonchain.com/v1/bsv/<network>/txs/hex
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main or test |
Get raw transaction output data
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/tx/c1d32f28baa27a376ba977f6a8de6ce0a87041157cef0274b20bfda2b0d8df96/out/0/hex"
Get raw transaction vout data in hex
Response with header content-type: text/plain:
76a914492558fb8ca71a3591316d095afc0f20ef7d42f788ac
This endpoint returns raw hex for the transaction output of the given hash and index
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/tx/<hash>/out/<index>/hex
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main or test |
hash | The hash/txId of the transaction |
index | Output/Vout index |
Get merkle proof
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/tx/c1d32f28baa27a376ba977f6a8de6ce0a87041157cef0274b20bfda2b0d8df96/proof"
Response JSON structure:
[
{
"blockHash": "0000000000000000091216c46973d82db057a6f9911352892b7769ed517681c3",
"branches": [
{
"hash": "7e0ba1980522125f1f40d19a249ab3ae036001b991776813d25aebe08e8b8a50",
"pos": "R"
},
{
"hash": "1e3a5a8946e0caf07006f6c4f76773d7e474d4f240a276844f866bd09820adb3",
"pos": "R"
}
],
"hash": "c1d32f28baa27a376ba977f6a8de6ce0a87041157cef0274b20bfda2b0d8df96",
"merkleRoot": "95a920b1002bed05379a0d2650bb13eb216138f28ee80172f4cf21048528dc60"
}
]
This endpoint returns merkle the branch for a confirmed transaction
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/tx/<hash>/proof
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main or test |
hash | The hash/txId of the transaction |
Mempool
Get mempool info
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/mempool/info"
Response JSON structure:
{
"bytes": 444832,
"maxmempool": 8196000000,
"mempoolminfee": 0,
"size": 142,
"usage": 647072
}
This endpoint retrieves various info about the node's mempool for the selected network.
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/mempool/info
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main , test or stn |
Get mempool transactions
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/mempool/raw"
Response JSON structure:
[
"0b0911bcb1f762634ed3ee171694d68049420c730296a7a592b29d46919c7739",
"195c95162a7f73f2ff9d4a5d8894f63ec44712b3b69fe1c3e53464048c6a39e3",
...
]
This endpoint retrieve list of transaction ids from the node's mempool for the selected network.
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/mempool/raw
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main , test or stn |
Address
Get address info
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/address/16ZqP5Tb22KJuvSAbjNkoiZs13mmRmexZA/info"
Response JSON structure:
{
"address": "16ZqP5Tb22KJuvSAbjNkoiZs13mmRmexZA",
"ismine": false,
"isscript": false,
"isvalid": true,
"iswatchonly": false,
"scriptPubKey": "76a9143d0e5368bdadddca108a0fe44739919274c726c788ac"
}
This endpoint retrieves various address info.
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/address/<address>/info
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main or test |
address | address |
Get balance
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/address/1GJ3x5bcEnKMnzNFPPELDfXUCwKEaLHM5H/balance"
Response JSON structure:
{
"confirmed":533134093647,
"unconfirmed":0
}
This endpoint retrieves confirmed and unconfirmed address balance.
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/address/<address>/balance
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main or test |
address | address |
Bulk balance
curl --location --request POST "https://api.whatsonchain.com/v1/bsv/main/addresses/balance" \
--header "Content-Type: application/json" \
--data "{\"addresses\" : [\"16ZBEb7pp6mx5EAGrdeKivztd5eRJFuvYP\",\"1KGHhLTQaPr4LErrvbAuGE62yPpDoRwrob\" ] }"
The JSON structure for the above post request:
{
"addresses":
[
"16ZBEb7pp6mx5EAGrdeKivztd5eRJFuvYP",
"1KGHhLTQaPr4LErrvbAuGE62yPpDoRwrob"
]
}
Response JSON structure:
[
{
"address": "16ZBEb7pp6mx5EAGrdeKivztd5eRJFuvYP",
"balance": {
"confirmed": 450000,
"unconfirmed": 0
},
"error": ""
},
{
"address": "1KGHhLTQaPr4LErrvbAuGE62yPpDoRwrob",
"balance": {
"confirmed": 0,
"unconfirmed": 0
},
"error": ""
}
]
Fetch confirmed and unconfirmed balance for multiple addresses in a single request
- Max 20 addresses per request
HTTP Request
POST https://api.whatsonchain.com/v1/bsv/<network>/addresses/balance
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main , test or stn |
Get history
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/address/1GJ3x5bcEnKMnzNFPPELDfXUCwKEaLHM5H/history"
Response JSON structure:
[
{
"tx_hash": "2b5ccedd76ba0d524d95ecce1c8a76e5888e0f13591734be0169ba0220c69208",
"height": 573216
},
{
"tx_hash": "7fe815e14b32aaaecc2cca7ed605ed612b532765710917cb711ea71cf55e36b5",
"height": 573229
},
{
"tx_hash": "b28dd1723d0d1fa6e4b2875f7419028c1c1441fc02469aebc444c0a42d0bac3f",
"height": 573230
},
...
]
This endpoint retrieves confirmed and unconfirmed address transactions.
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/address/<address>/history
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main or test |
address | address |
Get unspent transactions
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/address/1GJ3x5bcEnKMnzNFPPELDfXUCwKEaLHM5H/unspent"
Response JSON structure:
[
{
"height": 578325,
"tx_pos": 0,
"tx_hash": "62824e3af3d01113e9bce8b73576b833990d231357bd718385958c21d50bbddd",
"value": 1250020815
},
{
"height": 578326,
"tx_pos": 0,
"tx_hash": "4b008a10eebcf70f384442e4e3147bc76c6e4f764b516b208e148d700b965deb",
"value": 1251827826
},
...
]
This endpoint retrieves ordered list of UTXOs.
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/address/<address>/unspent
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main or test |
address | address |
Bulk unspent transactions
curl --location --request POST "https://api.whatsonchain.com/v1/bsv/main/addresses/unspent" \
--header "Content-Type: application/json" \
--data "{\"addresses\" : [\"16ZBEb7pp6mx5EAGrdeKivztd5eRJFuvYP\",\"1KGHhLTQaPr4LErrvbAuGE62yPpDoRwrob\" ] }"
The JSON structure for the above post request:
{
"addresses":
[
"16ZBEb7pp6mx5EAGrdeKivztd5eRJFuvYP",
"1KGHhLTQaPr4LErrvbAuGE62yPpDoRwrob"
]
}
Response JSON structure:
[
{
"address": "16ZBEb7pp6mx5EAGrdeKivztd5eRJFuvYP",
"unspent": [
{
"height": 657540,
"tx_pos": 1,
"tx_hash": "d75485c2329a533fd06b5f55a3f21644741c0258f2974d5d989e946a0bb4357f",
"value": 25000000
},
{
"height": 657542,
"tx_pos": 1,
"tx_hash": "55a656d50327ec3237fa6e821ab62294695cfd508d631dc9b04dc3a395cf0a37",
"value": 25000000
}
],
"error": ""
},
{
"address": "1KGHhLTQaPr4LErrvbAuGE62yPpDoRwrob",
"unspent": [
{
"height": 658133,
"tx_pos": 1,
"tx_hash": "7ae43aac97396bc99616d8273c6cd9b57f017d6d49aca742fbc8c214fee49fa7",
"value": 25000000
},
{
"height": 658134,
"tx_pos": 1,
"tx_hash": "5b25a56bbb959f9cf4b3e48dbbe412bf5cc85e655d27f87c3bfb07aa6aa01518",
"value": 25000000
}
],
"error": ""
}
]
Fetch UTXOs for multiple addresses in a single request
- Max 20 addresses per request
HTTP Request
POST https://api.whatsonchain.com/v1/bsv/<network>/addresses/unspent
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main, test or stn |
Download statement
curl --location --request GET "https://main.whatsonchain.com/statement/16ZqP5Tb22KJuvSAbjNkoiZs13mmRmexZA"
Download address statement (PDF)
HTTP Request
GET https://<network>.whatsonchain.com/statement/<address>
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main or test |
address | address |
Script
Get script history
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/script/995ea8d0f752f41cdd99bb9d54cb004709e04c7dc4088bcbbbb9ea5c390a43c3/history"
Response JSON structure:
[
{
"tx_hash": "52dfceb815ad129a0fd946e3d665f44fa61f068135b9f38b05d3c697e11bad48",
"height": 620539
},
{
"tx_hash": "4ec3b63d764558303eda720e8e51f69bbcfe81376075657313fb587306f8a9b0",
"height": 620539
}
]
This endpoint retrieves confirmed and unconfirmed script transactions.
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/script/<scriptHash>/history
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main or test |
scriptHash | Script hash: Sha256 hash of the binary bytes of the locking script (ScriptPubKey), expressed as a hexadecimal string. |
Get script unspent transactions
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/script/995ea8d0f752f41cdd99bb9d54cb004709e04c7dc4088bcbbbb9ea5c390a43c3/unspent"
Response JSON structure:
[
{
"height": 578325,
"tx_pos": 0,
"tx_hash": "62824e3af3d01113e9bce8b73576b833990d231357bd718385958c21d50bbddd",
"value": 1250020815
},
{
"height": 578326,
"tx_pos": 0,
"tx_hash": "4b008a10eebcf70f384442e4e3147bc76c6e4f764b516b208e148d700b965deb",
"value": 1251827826
},
...
]
This endpoint retrieves ordered list of UTXOs.
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/script/<scriptHash>/unspent
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main or test |
scriptHash | Script hash: Sha256 hash of the binary bytes of the locking script (ScriptPubKey), expressed as a hexadecimal string. |
Bulk script unspent transactions
curl --location --request POST "https://api.whatsonchain.com/v1/bsv/main/scripts/unspent" \
--header "Content-Type: application/json" \
--data "{\"scripts\" : [\"f814a7c3a40164aacc440871e8b7b14eb6a45f0ca7dcbeaea709edc83274c5e7\",\"995ea8d0f752f41cdd99bb9d54cb004709e04c7dc4088bcbbbb9ea5c390a43c3\" ] }"
The JSON structure for the above post request:
{
"scripts": [
"f814a7c3a40164aacc440871e8b7b14eb6a45f0ca7dcbeaea709edc83274c5e7",
"995ea8d0f752f41cdd99bb9d54cb004709e04c7dc4088bcbbbb9ea5c390a43c3"
]
}
Response JSON structure:
[
{
"script": "f814a7c3a40164aacc440871e8b7b14eb6a45f0ca7dcbeaea709edc83274c5e7",
"unspent": [
{
"height": 620539,
"tx_pos": 0,
"tx_hash": "4ec3b63d764558303eda720e8e51f69bbcfe81376075657313fb587306f8a9b0",
"value": 450000
}
],
"error": ""
},
{
"script": "995ea8d0f752f41cdd99bb9d54cb004709e04c7dc4088bcbbbb9ea5c390a43c3",
"unspent": [],
"error": ""
}
]
Fetch UTXOs for multiple scripts in a single request
- Max 20 scripts per request
HTTP Request
POST https://api.whatsonchain.com/v1/bsv/<network>/scripts/unspent
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main, test or stn |
Exchange Rate
Get exchange rate
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/exchangerate"
Response:
{
"currency": "USD",
"rate": "229.31633333333335"
}
This endpoint provides exchange rate for BSV.
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/exchangerate
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main |
TAAL Merchant API
Get fee quote
This endpoint is used to get the different fees quoted by a miner. It returns a JSONEnvelope with a payload that contains the fees charged by a specific BSV miner. The purpose of the envelope is to ensure strict consistency in the message content for the purpose of signing responses.
More details at : https://docs.taal.com
HTTP Request
Url: https://mapi.taal.com/mapi/feeQuote
Submit transaction
This endpoint is used to send a raw transaction to TAAL for inclusion in the next block that the TAAL creates. It returns a JSONEnvelope with a payload that contains the response to the transaction submission. The purpose of the envelope is to ensure strict consistency in the message content for the purpose of signing responses.
More details at : https://developers.taal.com
HTTP Request
Url: https://mapi.taal.com/mapi/tx
Query transaction status
This endpoint is used to check the current status of a previously submitted transaction. It returns a JSONEnvelope with a payload that contains the transaction status. The purpose of the envelope is to ensure strict consistency in the message content for the purpose of signing responses.
More details at : https://developers.taal.com
HTTP Request
Url: https://mapi.taal.com/mapi/tx/{hash:[0-9a-fA-F]+}
STAS Tokens (Beta)
STAS is a token protocol that consists of a bitcoin script for locking / unlocking bitcoin transaction outputs.
More details at : https://docs.taal.com
Get all tokens
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/tokens"
Response JSON structure:
{
"tokens": [
{
"description": "-",
"image": "https://firebasestorage.googleapis.com/v0/b/musicartstaging/o/nftAssets%2F3e75ba7e-fa51-4efb-a483-3b2c71bab180_250x250?alt=media",
"name": "fdsfs",
"properties": {
"issuer": {
"email": "[email protected]",
"governing_law": "England and Wales",
"issuer_country": "UK",
"jurisdiction": "UK",
"legal_form": "Limited",
"organisation": "Calekta Limited"
},
"legal": {
"terms": "\u00a9 2020 TAAL TECHNOLOGIES SEZC\nALL RIGHTS RESERVED. ANY USE OF THIS SOFTWARE IS SUBJECT TO TERMS AND CONDITIONS OF LICENSE. USE OF THIS SOFTWARE WITHOUT LICENSE CONSTITUTES INFRINGEMENT OF INTELLECTUAL PROPERTY. FOR LICENSE DETAILS OF THE SOFTWARE, PLEASE REFER TO: www.taal.com/stas-token-license-agreement"
}
},
"protocol": "STAS",
"schema_id": "NFT1.0/MA",
"symbol": "ujtVA5",
"token_id": "7bfb2ae7e878d107191259c1be72cf116da3f59d"
},
{
"token_id": "2",
"protocol": "STAS",
"ticker": "CIPS",
....
}
]
}
This endpoint retrieves list of supported tokens with metadata.
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/tokens
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main |
Get token by Id
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/token/c402bc341157265f5f8a747c11099847056a229a/test1124"
Response JSON structure:
{
"token": {
"contract_txs": [
"72ae93f5fdc5a4fa5abfab780d7d1c8ad988d25ae34578b80dce5ff9e5c3db03"
],
"description": "generating stas token",
"image": "https://firebasestorage.googleapis.com/v0/b/nftdev/o/nftTemp%2FWL1DdD?alt=media",
"issuance_txs": [
"b00bcc9dfc7dd483ff989f3d1d3f091b23e88ca2207c9e15788e3e84a5b10c8b"
],
"name": "test",
"properties": {
"issuer": {
"email": "[email protected]",
"governing_law": "US",
"issuer_country": "US",
"jurisdiction": "US",
"legal_form": "Limited",
"organisation": "vaionex corp."
},
"legal": {
"terms": "test"
}
},
"protocol": "STAS",
"schema_id": "NFT1.0/MA",
"symbol": "test1124",
"token_id": "c402bc341157265f5f8a747c11099847056a229a",
"tx_count": 3
}
}
This endpoint retrieves token metadata including contract and issuance details.
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/token/<tokenId>/<symbol>
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main |
tokenId | unique id of the token |
symbol | symbol used in the registration of the token |
Get token UTXOs for address
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/address/1GJ3x5bcEnKMnzNFPPELDfXUCwKEaLHM5H/tokens/unspent"
Response JSON structure:
{
"address": "1JsQieDaYUg5pSRtpeEQhTv3buHvSX7WH4",
"utxos": [
{
"amount": 2000,
"index": 1,
"redeemAddr": "c402bc341157265f5f8a747c11099847056a229a",
"symbol": "test1124",
"txid": "cf3968e6950286cf94aa9efb7a1cc1b9c74190d159ff6d2a4dc7d9feb6e50c55"
}
]
}
This endpoint retrieves address token UTXOs.
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/address/<address>/tokens/unspent
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main |
address | address |
Get address token balance
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/address/1JsQieDaYUg5pSRtpeEQhTv3buHvSX7WH4/tokens"
Response JSON structure:
{
"address": "1JsQieDaYUg5pSRtpeEQhTv3buHvSX7WH4",
"tokens": [
{
"balance": 0,
"image": "https://firebasestorage.googleapis.com/v0/b/nftdev/o/nftTemp%2FWL1DdD?alt=media",
"protocol": "STAS",
"redeemAddr": "c402bc341157265f5f8a747c11099847056a229a",
"symbol": "test2"
},
{
"balance": -2000,
"image": "https://firebasestorage.googleapis.com/v0/b/nftdev/o/nftTemp%2FWL1DdD?alt=media",
"protocol": "STAS",
"redeemAddr": "c402bc341157265f5f8a747c11099847056a229a",
"symbol": "test1124"
}
]
}
This endpoint retrieves address token balance.
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/address/<address>/tokens
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main |
address | address |
Get token transactions
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/token/c402bc341157265f5f8a747c11099847056a229a/test1124/tx"
Response JSON structure:
{
"redeem_addr": "c402bc341157265f5f8a747c11099847056a229a",
"symbol": "test1124",
"txs": [
"cf3968e6950286cf94aa9efb7a1cc1b9c74190d159ff6d2a4dc7d9feb6e50c55",
"b00bcc9dfc7dd483ff989f3d1d3f091b23e88ca2207c9e15788e3e84a5b10c8b",
"72ae93f5fdc5a4fa5abfab780d7d1c8ad988d25ae34578b80dce5ff9e5c3db03"
]
}
This endpoint retrieves token transactions.
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/token/<tokenId>/<symbol>/tx
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main |
tokenId | unique id of the token |
symbol | symbol used in the registration of the token |
Get Token output Details
curl --location --request GET "wget -O- https://api.whatsonchain.com/v1/bsv/main/token/tx/cf3968e6950286cf94aa9efb7a1cc1b9c74190d159ff6d2a4dc7d9feb6e50c55/out/1"
Response JSON structure:
{
"has_data": true,
"icon_url": "https://firebasestorage.googleapis.com/v0/b/nftdev/o/nftTemp%2FWL1DdD?alt=media",
"index": 1,
"is_splittable": true,
"symbol": "test1124",
"token_id": "c402bc341157265f5f8a747c11099847056a229a",
"txid": "cf3968e6950286cf94aa9efb7a1cc1b9c74190d159ff6d2a4dc7d9feb6e50c55",
"value": 2000
}
This endpoint returns details of valid token output or Not Found (404) for invalid token output.
HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/token/tx/<txid>/out/<index>
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main |
hash | The hash/txId of the transaction |
index | Output/Vout index |
Search
Get explorer links
curl -X POST https://api.whatsonchain.com/v1/bsv/main/search/links -H 'Content-Type: application/json' -d '{ "query": "1GJ3x5bcEnKMnzNFPPELDfXUCwKEaLHM5H"
}'
Response JSON structure:
{
"results": [
{
"type": "address",
"url": "https://whatsonchain.com/address/1GJ3x5bcEnKMnzNFPPELDfXUCwKEaLHM5H"
}
]
}
This endpoint identifies whether the posted query text is a block hash, txid or address and responds with WoC links. Ideal for extending customized search in apps.
HTTP Request
POST https://api.whatsonchain.com/v1/bsv/<network>/search/links
URL Parameters
Parameter | Description |
---|---|
network | Selected network: main , test or stn |
address | address |
Request Body
Parameter | Description |
---|---|
query | Text to search |
WoC Widgets
You can embed aspects of the WhatsOnChian Home, Transaction or Block pages in any application.
Located in the WhatsOnChain.com "Tools" Menu, you can find the "Widget Creator".
Using the Widget Creator tool you can toggle sections of the selected page and can immediately see what it will look like in the preview section.
Based on the selected options, a URL and HTML code is generated for the integration into any website or application.
On Chain Data
Coming Soon... Stay tuned!!
Get OP_RETURN data by tx hash
Coming Soon... Stay tuned!!
Stats
Coming Soon... Stay tuned!!
WebSockets (Beta)
Simple js example using centrifuge client:
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
<script type="text/javascript" src="https://cdn.jsdelivr.net/gh/centrifugal/[email protected]/dist/centrifuge.min.js"></script>
<script type="text/javascript">
$(function () {
const centrifuge = new Centrifuge('wss://socket.whatsonchain.com/blockheaders');
centrifuge.on('publish', function(message) {
console.log('Data: '+ JSON.stringify(message.data, null, 2))
});
centrifuge.on('disconnect', function(ctx){
console.log('Disconnected: ' + ctx.reason + (ctx.reconnect?", will try to reconnect":", won't try to reconnect"));
});
centrifuge.on('connect', function(ctx){
console.log('Connected with client ID ' + ctx.client + ' over ' + ctx.transport );
});
centrifuge.connect();
});
</script>
Simple js example using websocket API client:
<script type="text/javascript">
window.addEventListener('load', function() {
let clientID;
let reconnect = true;
let numFailures = 0;
function connect() {
// Subscribe to multiple channels
const ws = new WebSocket('wss://socket.whatsonchain.com/websocket?channels=woc:chainStats');
ws.onopen = function(e) {
numFailures = 0;
console.log("websocket: connection open",e);
// This is required to trigger connect on server side.
ws.send(JSON.stringify({}));
};
ws.onerror = function(e) {
numFailures++;
console.log("websocket: connection error: ", e);
};
ws.onclose = function (e) {
if (!reconnect) {
return;
}
setTimeout(function () {
console.log("websocket: connection reconnecting");
connect();
}, Math.min(numFailures * 1000, 20000));
}
ws.onmessage = function(e) {
console.log("websocket: new message");
processData(e.data);
};
}
connect();
function processData(rawData) {
if (rawData.length === 0) {
console.log("--> ping");
return
}
console.log("--> " + rawData);
const data = JSON.parse(rawData);
const pushType = data.type || 0;
switch (pushType) {
case 0:
console.log("new data from a channel " + data.channel + ": " + JSON.stringify(data.data));
break;
case 6:
clientID = data.data.client;
let subscriptions = [];
const subs = data.data.subs;
if (subs) {
for (const m in subs) {
if (subs.hasOwnProperty(m)) {
subscriptions.push(m);
}
}
}
console.log("connected with client ID " + clientID + " and subscriptions: " + JSON.stringify(subscriptions));
break;
case 7:
clientID = null;
if (!data.data.reconnect) {
reconnect = false;
ws.close();
console.log("disconnected from a server, won't reconnect");
} else {
console.log("disconnected from a server, will reconnect");
}
break;
case 3:
console.log("unsubscribed from a channel " + data.channel);
break;
case 5:
console.log("subscribed to a channel " + data.channel);
break;
default:
console.log("unsupported push type " + data.type);
}
}
});
</script>
We recommend the centrifuge websocket client side libraries below:
- centrifuge-js – for a browser, NodeJS and React Native
- centrifuge-go - for Go language
- centrifuge-mobile - for iOS/Android with
centrifuge-go
as basis and gomobile - centrifuge-dart - for Dart and Flutter
- centrifuge-swift – for native iOS development
- centrifuge-java – for native Android development and general Java
Non-centrifuge clients connect to separate endpoints specified in each section.
Supported Networks:
- Mainnet
- Testnet
New block header event
Receive new block header events in real time.
Data JSON structure:
{
"hash": "0000000000000000010cb155a44577ff3541940ec4355c026dc2706fb7e261d6",
"confirmations": 4,
"size": 1229956,
"height": 676421,
"version": 541065216,
"versionHex": "20400000",
"merkleroot": "e2f64e87c0362314b65dc28b4367c41d904c22b891b652951779336ef735386b",
"txcount": 654,
"time": 1614534798,
"mediantime": 1614527058,
"nonce": 610133701,
"bits": "180d359d",
"difficulty": 83235621087.7299,
"chainwork": "00000000000000000000000000000000000000000127d3854a414d8ec8f53190",
"previousblockhash": "00000000000000000428ca33597675bd85f5a2ef464ba25e4db7b4a74d898d33",
"nextblockhash": "00000000000000000cb40c1d850dece5cd3747e08a1e4066ef887251388c4ae6",
"coinbaseTx": {
"hex": "01000000010000000000000000000000000000000000000000000000000000000000000000ffffffff410345520a2f7461616c2e636f6d2f506c656173652070617920302e3520736174732f627974652c20696e666f407461616c2e636f6d6eead6b0ad91f2ce86be0400ffffffff0176674325000000001976a9148e9170be3f733a9773c907517fb9b786f1c884c688ac00000000",
"txid": "13686a10870d23b4c94642bf0b78d6630e2640fc0de83bc30af835d96bb17482",
"hash": "13686a10870d23b4c94642bf0b78d6630e2640fc0de83bc30af835d96bb17482",
"size": 150,
"version": 1,
"locktime": 0,
"vin": [
{
"coinbase": "0345520a2f7461616c2e636f6d2f506c656173652070617920302e3520736174732f627974652c20696e666f407461616c2e636f6d6eead6b0ad91f2ce86be0400",
"sequence": 4294967295
}
],
"vout": [
{
"value": 6.2517439,
"n": 0,
"scriptPubKey": {
"asm": "OP_DUP OP_HASH160 8e9170be3f733a9773c907517fb9b786f1c884c6 OP_EQUALVERIFY OP_CHECKSIG",
"hex": "76a9148e9170be3f733a9773c907517fb9b786f1c884c688ac",
"reqSigs": 1,
"type": "pubkeyhash",
"addresses": [
"1DzqBck9oyCBzxJbbje2s15deZis6BeATi"
],
"isTruncated": false
}
}
],
"blockhash": "0000000000000000010cb155a44577ff3541940ec4355c026dc2706fb7e261d6",
"confirmations": 4,
"time": 1614534798,
"blocktime": 1614534798
}
}
URL
- Mainnet:
wss://socket.whatsonchain.com/websocket?channels=woc:blockHeader
- Testnet:
wss://socket-testnet.whatsonchain.com/websocket?channels=woc:blockHeader
URL - for centrifuge clients
- Mainnet:
wss://socket.whatsonchain.com/blockheaders
- Testnet:
wss://socket-testnet.whatsonchain.com/blockheaders
Block headers history
Stream block headers starting at a pre-specified block height.
Data JSON structure:
{
"hash": "000000000000000007dde2992ff13fdaba5473341af1c45d0c19c86deb4c732a",
"confirmations": 1,
"size": 3449218,
"height": 676417,
"version": 536870912,
"versionHex": "20000000",
"merkleroot": "df1fe3b56cacd2f4063fbe41d15b51071c72d5748d265f4e61793db79ce0d8ff",
"txcount": 8859,
"time": 1614529458,
"mediantime": 1614524118,
"nonce": 347880361,
"bits": "180d6633",
"difficulty": 82056657294.07133,
"chainwork": "00000000000000000000000000000000000000000127d3376e97bb73257c98c5",
"previousblockhash": "00000000000000000b04692ac2bf62654e2ea577476e20ea74eb9e5b53f0ed48",
"nextblockhash": ""
}
URL
- Mainnet:
wss://socket.whatsonchain.com/websocket/history?from=<blockHeight>
- Testnet:
wss://socket-testnet.whatsonchain.com/websocket/history?from=<blockHeight>
URL - for centrifuge clients
- Mainnet:
wss://socket.whatsonchain.com/blockheaders/history?from=<blockHeight>
- Testnet:
wss://socket-testnet.whatsonchain.com/blockheaders/history?from=<blockHeight>
Block transactions
Stream transactions from a block height and transaction index.
- hex, vin and vout values are not published for the message size greater than 10MB. Recommended to fetch details for such transactions using these REST endpoints using the published txid value.
Data JSON structure:
{
"txid": "20ac30f5aa6aebc0f9e532f32a9691bf7faa332c755d6aea1fd3f6ba36d195e8",
"hash": "20ac30f5aa6aebc0f9e532f32a9691bf7faa332c755d6aea1fd3f6ba36d195e8",
"size": 219,
"version": 2,
"locktime": 0,
"vin": [
{
"txid": "15b416adf871f9285788ebf36b67714d9e49f413f3a3f083d80e01535bd40433",
"vout": 1,
"scriptSig": {
"asm": "304402204ac1d9f22f09044f66aa6055835b19d5617c19ef180422683b9d168da272e40d022078d3e876f7134eb29cd9e26081feae70f393a1aa3e9926307233f1c419bd1eb641 02a3089907380f086e9d5616ef6e62876a2777ea0c5abca785b15ef92d173afdff",
"hex": "47304402204ac1d9f22f09044f66aa6055835b19d5617c19ef180422683b9d168da272e40d022078d3e876f7134eb29cd9e26081feae70f393a1aa3e9926307233f1c419bd1eb6412102a3089907380f086e9d5616ef6e62876a2777ea0c5abca785b15ef92d173afdff"
},
"sequence": 4294967295
}
],
"vout": [
{
"value": 0,
"n": 0,
"scriptPubKey": {
"asm": "OP_FALSE OP_RETURN 39366665313633626131303138386636",
"hex": "006a1039366665313633626131303138386636",
"type": "nulldata",
"isTruncated": false
}
},
{
"value": 0.00007511,
"n": 1,
"scriptPubKey": {
"asm": "OP_DUP OP_HASH160 966a0c69734d51307ba0bcfcd9092b51addfaf78 OP_EQUALVERIFY OP_CHECKSIG",
"hex": "76a914966a0c69734d51307ba0bcfcd9092b51addfaf7888ac",
"reqSigs": 1,
"type": "pubkeyhash",
"addresses": [
"1EiKQ9qiAkjDn86JvUt6aJpZvETq8uim2D"
],
"isTruncated": false
}
}
]
}
URL
- Mainnet:
wss://socket.whatsonchain.com/websocket/transactions?from=<blockHeight>&txIndex={txIndex}&to=<blockHeight>&format={hex|json}
- Testnet:
wss://socket-testnet.whatsonchain.com/websocket/transactions?from=<blockHeight>&txIndex={txIndex}&to=<blockHeight>&format={hex|json}
URL - for centrifuge clients
- Mainnet:
wss://socket.whatsonchain.com/block/transactions?from=<blockHeight>&txIndex={txIndex}&to=<blockHeight>&format={hex|json}
- Testnet:
wss://socket-testnet.whatsonchain.com/block/transactions?from=<blockHeight>&txIndex={txIndex}&to=<blockHeight>&format={hex|json}
URL Parameters
Parameter | Description |
---|---|
blockHeight | The height of the block. |
txIndex | Index of a transaction as a starting point in the first block to deliver. Default value 0. |
format | hex or json. If hex, the response will include transaction hex and metadata. If json, hex is excluded. Default value json. |
Mempool transactions
Receive mempool transactions in real time.
- Mempool transactions are collected from multiple nodes.
- Client side should be idempotent because duplicate transaction events are not guaranteed to have been removed.
- hex, vin and vout values are not published for the message size greater than 10MB. Recommended to fetch details for such transactions using these REST endpoints using the published txid value.
Data JSON structure:
{
"hex": "02 ...",
"txid": "20ac30f5aa6aebc0f9e532f32a9691bf7faa332c755d6aea1fd3f6ba36d195e8",
"hash": "20ac30f5aa6aebc0f9e532f32a9691bf7faa332c755d6aea1fd3f6ba36d195e8",
"size": 219,
"version": 2,
"locktime": 0,
"vin": [
{
"txid": "15b416adf871f9285788ebf36b67714d9e49f413f3a3f083d80e01535bd40433",
"vout": 1,
"scriptSig": {
"asm": "304402204ac1d9f22f09044f66aa6055835b19d5617c19ef180422683b9d168da272e40d022078d3e876f7134eb29cd9e26081feae70f393a1aa3e9926307233f1c419bd1eb641 02a3089907380f086e9d5616ef6e62876a2777ea0c5abca785b15ef92d173afdff",
"hex": "47304402204ac1d9f22f09044f66aa6055835b19d5617c19ef180422683b9d168da272e40d022078d3e876f7134eb29cd9e26081feae70f393a1aa3e9926307233f1c419bd1eb6412102a3089907380f086e9d5616ef6e62876a2777ea0c5abca785b15ef92d173afdff"
},
"sequence": 4294967295
}
],
"vout": [
{
"value": 0,
"n": 0,
"scriptPubKey": {
"asm": "OP_FALSE OP_RETURN 39366665313633626131303138386636",
"hex": "006a1039366665313633626131303138386636",
"type": "nulldata",
"isTruncated": false
}
},
{
"value": 0.00007511,
"n": 1,
"scriptPubKey": {
"asm": "OP_DUP OP_HASH160 966a0c69734d51307ba0bcfcd9092b51addfaf78 OP_EQUALVERIFY OP_CHECKSIG",
"hex": "76a914966a0c69734d51307ba0bcfcd9092b51addfaf7888ac",
"reqSigs": 1,
"type": "pubkeyhash",
"addresses": [
"1EiKQ9qiAkjDn86JvUt6aJpZvETq8uim2D"
],
"isTruncated": false
}
}
]
}
URL
- Mainnet:
wss://socket.whatsonchain.com/websocket?channels=woc:mempoolTx?filter=<filter1,filter2,...>
- Testnet:
wss://socket-testnet.whatsonchain.com/websocket?channels=woc:mempoolTx?filter=<filter1,filter2,...>
URL - for centrifuge clients
- Mainnet:
wss://socket.whatsonchain.com/mempool?filter=<filter1,filter2,...>
- Testnet:
wss://socket-testnet.whatsonchain.com/mempool?filter=<filter1,filter2,...>
URL Parameters
Parameter | Description |
---|---|
filter | filter transactions based on the output (vout) types. Available filters: nulldata, multisig, pubkey, pubkeyhash, scripthash, nonstandard |
Confirmed transactions
Receive confirmed transactions in real time.
Data JSON structure:
- Confirmed transactions are collected from multiple nodes.
- Client side should be idempotent because duplicate transaction events are not guaranteed to have been removed.
- hex,vin and vout values are not published for the transactions size greater than 1 MB. Recommended to fetch details for such transactions using these REST endpoints using the published txid value.
{
"hex": "01 ...",
"txid": "651dd0bc40520dfc5927b8b9a6fbb0d3d7ff7314fae28d6c5ddad66e1f75ffff",
"hash": "651dd0bc40520dfc5927b8b9a6fbb0d3d7ff7314fae28d6c5ddad66e1f75ffff",
"size": 442,
"version": 1,
"locktime": 0,
"vin": [
{
"txid": "719f1f2e79c29f30d60b106518f29abcab0e3d17fc79731c7bc37504130eb91d",
"vout": 2,
"scriptSig": {
"asm": "30450221008117adcf9c88330b85efa6772ba6b8cecccc473ecea8160494885cec46abefe302202fa8f1469dd070ecc2713f1e55117bb245e14e4f9f4a6f1f54ecdde2cfad875941 02569ec180c4917405a9f285260804e5d34c696218edc7fa818e9c7f414e2cbcc4",
"hex": "4830450221008117adcf9c88330b85efa6772ba6b8cecccc473ecea8160494885cec46abefe302202fa8f1469dd070ecc2713f1e55117bb245e14e4f9f4a6f1f54ecdde2cfad8759412102569ec180c4917405a9f285260804e5d34c696218edc7fa818e9c7f414e2cbcc4"
},
"sequence": 4294967295
}
],
"vout": [
{
"value": 0.00003822,
"n": 0,
"scriptPubKey": {
"asm": "OP_DUP OP_HASH160 09cc4559bdcb84cb35c107743f0dbb10d66679cc OP_EQUALVERIFY OP_CHECKSIG",
"hex": "76a91409cc4559bdcb84cb35c107743f0dbb10d66679cc88ac",
"reqSigs": 1,
"type": "pubkeyhash",
"addresses": [
"1tonicZQwN2BNKhVwPXqh8ez3q56y1EYw"
],
"isTruncated": false
}
},
{
"value": 0.00038224,
"n": 1,
"scriptPubKey": {
"asm": "OP_DUP OP_HASH160 b8cba27cbf0357e1e74ede6b4ac17f49aa297991 OP_EQUALVERIFY OP_CHECKSIG",
"hex": "76a914b8cba27cbf0357e1e74ede6b4ac17f49aa29799188ac",
"reqSigs": 1,
"type": "pubkeyhash",
"addresses": [
"1Hr7H5vdaxordBEu9CJxnfD2NNWEnwEfih"
],
"isTruncated": false
}
},
...
],
"blockhash": "00000000000000000045876574d74d4006b8b821525135720a0a12343986a14a",
"confirmations": 1,
"time": 1616419527,
"blocktime": 1616419527,
"blockheight": 679542
}
URL
- Mainnet:
wss://socket.whatsonchain.com/websocket?channels=woc:confirmedTx?filter=<filter1,filter2,...>
- Testnet:
wss://socket-testnet.whatsonchain.com/websocket?channels=woc:confirmedTx?filter=<filter1,filter2,...>
URL - for centrifuge clients
- Mainnet:
wss://socket.whatsonchain.com/confirmed?filter=<filter1,filter2,...>
- Testnet:
wss://socket-testnet.whatsonchain.com/confirmed?filter=<filter1,filter2,...>
URL Parameters
Parameter | Description |
---|---|
filter | filter transactions based output (vout) types. Available filters: nulldata, multisig, pubkey, pubkeyhash, scripthash, nonstandard |
Chain Stats
Receive common chain stats every 10 seconds.
Data JSON structure:
{
"chainSummary":{
"blocks":691040,
"bestblockhash":"000000000000000006f693315876096d472a8313780df342905e1003a6cf0b70",
"difficulty":102522924402.0986,
"chainwork":"0000000000000000000000000000000000000000012cfa97321f921dab48da26",
"networkhashps":650555175336335400,
"circulatingSupply":18756500,
"mempoolSize":6554,
"mempoolBytes":16540861,
"mempoolUsage":26650576,
"exchangeRate":{
"currency":"USD",
"rate":"170.70749999999998"
}
},
"latestBlocks":[
{
"hash":"000000000000000006f693315876096d472a8313780df342905e1003a6cf0b70",
"confirmations":1,
"size":208141,
"height":691040,
"version":538968064,
"versionHex":"20200000",
"merkleroot":"e3454f52b6715dcf4db5d8c8f237344ef6bd6d415d6e754a3b4b1083cd3ab48c",
"txcount":102,
"time":1623330613,
"mediantime":1623328816,
"nonce":3022302528,
"bits":"180ab971",
"difficulty":102522924402.0986,
"chainwork":"0000000000000000000000000000000000000000012cfa97321f921dab48da26",
"previousblockhash":"0000000000000000013ab5705e150967a057f807f396628231a7ceaa11a0bac1",
"nextblockhash":"",
"coinbaseTx":{...},
"totalFees":0.0009790499999997593
},
{...},
...
]
}
URL
- Mainnet:
wss://socket.whatsonchain.com/websocket?channels=woc:chainStats
- Testnet:
wss://socket-testnet.whatsonchain.com/websocket?channels=woc:chainStats
URL - for centrifuge clients
- Mainnet:
wss://socket.whatsonchain.com/stats
- Testnet:
wss://socket-testnet.whatsonchain.com/stats
Customized events
If your application needs customized/filtered events via websockets, please let us know in the WoC devs telegram channel or send us an email at [email protected]
Change log
- 15/04/2019
- New
- Get Health
- Get block by hash
- Get block by height
- Get block pages
- Get transactions by hash
- Broadcast transactions
- New
- 22/04/2019
- New
- Get chain info
- Get mempool info
- Get mempool transactions
- Get address info
- New
- 19/05/2019
- New
- Get address balance
- Get address history
- Get address UTXOs
- Get explorer links
- New
- 23/06/2019
- New
- Download address statement
- Download transaction receipt
- Fixed
- Broadcast transaction endpoint now returns txid on success or error msg from node on failure
- New
- 21/10/2019
- New
- Decode raw transaction
- New
- 09/11/2019
- New
- Get merkle proof
- New
- 18/11/2019
- New
- Bulk Broadcast transactions
- New
- 18/01/2020
- New
- Bulk transaction details
- Get circulating supply
- Community Libraries
- New
- 03/02/2020
- Changes
- Removing support of STN network from address balance, history and UTXOs endpoints
- Removing hex field from response body of Get transaction by hash request
- Limiting vout[x].scriptPubKey.asm and vout[x].scriptPubKey.hex size to return max 100KB in response body of Get transaction by hash
- Adding vout[x].scriptPubKey.isTruncated flag, if data size is more than 100KB in vout[x].scriptPubKey.hex
- Removing old merkle proof endpoint */tx/{txid}/merkleproof
- New
- Changes
- 08/03/2020
- New
- Enabled Get raw transaction data (hex) for testnet
- Enabled Get raw transaction output data by index (hex) for testnet
- Get script history
- Get script unspent transactions
- Get exchange rate
- New
- 25/05/2020
- New
- Merchant API - Get Fee Quotes from multiple transaction processors
- Merchant API - Submit tx to a transaction processor
- Merchant API - Request Transaction status from a transaction processor
- Merchant API - Get Fee Quotes from multiple transaction processors
- New
- 13/07/2020
- 26/11/2020
- 02/03/2021
- Changes
- Deprecating WoC Merchant API. Recommended to switch to TAAL Merchant API
- Deprecating WoC Bulk Broadcast. Recommended to switch to TAAL Merchant API
- New
- Adding TAAL Merchant API details
- WebSockets - New block header event
- WebSockets - Block headers history
- Changes
- 22/03/2021
- New
- WebSockets - Mempool transactions
- WebSockets - Confirmed transactions
- WebSockets - Customized events
- New
- 14/06/2021
- New
- WebSockets - Chain Stats
- WebSockets - Extending support for non-centrifuge clients
- New
- 17/06/2021
- New
- WebSockets - Adding testnet support
- New
- 03/08/2021
- 10/01/2022
- 02/03/2022
- New
- WebSockets - Block transactions
- New
- 11/05/2022
- New
- STAS Token endpoints
- WebSockets - Options to filter Mempool transactions by the output type
- WebSockets - Options to filter Confirmed transactions by the output type
- WoC Widgets
- New
Community Libraries
Awesome community-maintained libraries
.---. .---.
.---|___| .-. |~~~|
.--|===| B |_ |_| |~~~|--.
| |===| I |'\ .---!~| .--| |--|
| | | T |.'\ |===| |--|%%| W | |
| | | C |\.'\ | S | |__| | O |py|
|go| | O | \ \ |===| |==| | C | |
| | | I | \.'\ | V |_|__| |~~~|__|
| |===| N | \.'\|===|~|--|%%|~~~|--|
^--^---'---^ `-'`---^-^--^--^---'--'
Golang
Description | Link |
---|---|
Go Wrapper for WoC API by MrZ | GitHub |
Go Wrapper for bitcoin RPC by Simon Ordish | GitHub |
Python
Description | Link |
---|---|
Python3 Wrapper for WOC API by AustEcon | GitHub |
Node.js
Description | Link |
---|---|
JS Wrapper for WoC API by baryon | npmjs |
Example: How to verify merkle proofs by Simon Ordish | Gist |