Herald API Specification

Herald uses the stratum protocol used by bitcoin. Over stratum it provides many of the electrum APIs common to other blockchains as well as some LBRY specific ones.

Format

Stratum protocol is based on JSON-RPC 2.0 (although it doesn't include "jsonrpc" information in every message). Each message has to end with a line end character (\n).

A typical request looks like this:

   { "id": 0, "method":"some.stratum.method", "params": [] }

id begins at 0 and every message has its unique id number
list and description of possible methods is below
params is an array, e.g.: [ "1myfirstaddress", "1mysecondaddress", "1andonemoreaddress" ]

Responses are similar:

   { "id": 0, "result": "616be06545e5dd7daec52338858b6674d29ee6234ff1d50120f060f79630543c"}

id is copied from the request message (this way client can pair each response to one of his requests)

result can be:

null
a string (as shown above)
a hash map, e.g.:

    { "nonce": 1122273605, "timestamp": 1407651121, "version": 2, "bits": 406305378 }

an array of hash maps, e.g.:

     [ { "tx_hash:
     "b87bc42725143f37558a0b41a664786d9e991ba89d43a53844ed7b3752545d4f",
     "height": 314847 }, { "tx_hash":
     "616be06545e5dd7daec52338858b6674d29ee6234ff1d50120f060f79630543c",
     "height": 314853 } ]

a base64 encoded protobuf (string)

Subscriptions

The following APIs are for subscriptions:

blockchain.address.subscribe notifies whenever an address is touched, ie it received a new tx or one of its txs has been spent - in mempool or in a new block.
blockchain.address.unsubscribe
blockchain.scripthash.subscribe
blockchain.scripthash.unsubscribe
blockchain.headers.subscribe notifies with new block headers as new blocks are found
server.peers.subscribe notifies when the hub peers (federated hubs) changes

Methods

blockchain.address.get_history

echo -e -n '{ "id": 0, "method":"blockchain.address.get_history", "params": ["bEaiqayiRLt4A1m423LRWJW42CtPzSLVox"]}\n' | timeout 2 nc 10.100.20.20 50001 -i 1

{"jsonrpc":"2.0","result":[{"tx_hash":"d22e243be78d4dd4b5fcbebf800dcebc066b1df1b042b363910e5f507d1d61f6","height":682018}],"id":0}

blockchain.address.get_mempool

echo -e -n '{ "id": 0, "method":"blockchain.address.get_mempool", "params": ["bEaiqayiRLt4A1m423LRWJW42CtPzSLVox"]}\n' | timeout 2 nc 10.100.20.20 50001 -i 1

blockchain.address.listunspent

echo -e -n '{ "id": 0, "method":"blockchain.address.listunspent", "params": ["bEaiqayiRLt4A1m423LRWJW42CtPzSLVox"]}\n' | timeout 2 nc 10.100.20.20 50001 -i 1

{"jsonrpc":"2.0","result":[{"tx_hash":"d22e243be78d4dd4b5fcbebf800dcebc066b1df1b042b363910e5f507d1d61f6","tx_pos":1,"height":682018,"value":383600}],"id":0}

blockchain.address.getbalance

echo -e -n '{ "id": 0, "method":"blockchain.address.getbalance", "params": ["bEaiqayiRLt4A1m423LRWJW42CtPzSLVox"]}\n' | timeout 2 nc 10.100.20.20 50001 -i 1

{"jsonrpc":"2.0","result":{"confirmed":383600,"unconfirmed":0},"id":0}

blockchain.scripthash.get_history
blockchain.scripthash.get_mempool
blockchain.scripthash.get_balance
blockchain.scripthash.listunspent
blockchain.block.get_chunk
blockchain.block.get_header
blockchain.block.headers
blockchain.block.get_server_height
blockchain.claimtrie.search Returns an Outputs protobuf result

blockchain.claimtrie.resolve Returns an Outputs protobuf result

echo -e -n '{ "id": 0, "method":"blockchain.claimtrie.resolve", "params": ["lbry://@lbrytech:19/hubba-hubba:6"]}\n' | timeout 2 nc 10.100.20.20 50001 -i 1

{"jsonrpc":"2.0","result":"CqABCiBiN5OmXDN7dwLrwYVmDswlflCvI6ZsjO5C9XeUH79u9xjy4kc6eAomCiAUuKn9XeBuKaZUKHdxSKPEcUEr3L5u5Y7+XfEVFMCbvRjdv0IaDWh1YmJhLWh1YmJhIzYiGkBsYnJ5dGVjaCMxOS9odWJiYS1odWJiYSM2KAEw6eFHOOnhR0Dy4kdI8ovIAVgIoAHXuMDU\/A6oAZe0g9T8DhJnCiAUuKn9XeBuKaZUKHdxSKPEcUEr3L5u5Y7+XfEVFMCbvRjdv0I6PxoMQGxicnl0ZWNoIzE5IgxAbGJyeXRlY2gjMTkoATC4kSw42YwsQN2\/Qkjd6MIBUBWgAcD4s\/ITqAHAlpGqEg==","id":0}

blockchain.claimtrie.getclaimbyid Returns an Outputs protobuf result

echo -e -n '{ "id": 0, "method":"blockchain.claimtrie.getclaimbyid", "params": ["6b38744341412a6abcf5cf3ac215ade64907905b"]}\n' | timeout 2 nc 10.100.20.20 50001 -i 1

{"jsonrpc":"2.0","result":"CqABCiBiN5OmXDN7dwLrwYVmDswlflCvI6ZsjO5C9XeUH79u9xjy4kc6eAomCiAUuKn9XeBuKaZUKHdxSKPEcUEr3L5u5Y7+XfEVFMCbvRjdv0IaDWh1YmJhLWh1YmJhIzYiGkBsYnJ5dGVjaCMxOS9odWJiYS1odWJiYSM2KAEw6eFHOOnhR0Dy4kdI8ovIAVgIoAHXuMDU\/A6oAZe0g9T8DhJnCiAUuKn9XeBuKaZUKHdxSKPEcUEr3L5u5Y7+XfEVFMCbvRjdv0I6PxoMQGxicnl0ZWNoIzE5IgxAbGJyeXRlY2gjMTkoATC4kSw42YwsQN2\/Qkjd6MIBUBWgAcD4s\/ITqAHAlpGqEg==","id":0}

blockchain.transaction.broadcast
blockchain.transaction.get

blockchain.transaction.get_batch

echo -e -n '{ "id": 0, "method":"blockchain.transaction.get_batch", "params": ["d22e243be78d4dd4b5fcbebf800dcebc066b1df1b042b363910e5f507d1d61f6"]}\n' | timeout 2 nc 10.100.20.20 50001 -i 1

{"jsonrpc":"2.0","result":{"d22e243be78d4dd4b5fcbebf800dcebc066b1df1b042b363910e5f507d1d61f6":["010000000282a2750b0a78cb74f427438dfe569aad05020caaad0d1aa58e8c01ccaf25bcfa000000006a47304402207dc3309ae0be9078e1363d76b23533b8c6ff0f15853d98d7162359dce29c6ec4022074837d3f402edb83f004e4ce8bd6cf57aacf3b2e485f2bbba426293fd65cab0701210268b787a2cd3fbdd5c3b1fc9daa9fecd0c5e7cad7490a83a62d2adf3a75d96fc6ffffffffa5d4d2f2633876a48889d64810028b7e33cf157977f5872706baaf264814d2ca010000006b483045022100ba04f06c15330fc3cdc06475f99094833c27d931d917ecb24a7782c6e3271658022040a77d504c198128e125a9b5e5c6432b36967bbd91667184b170eda4cf94632501210255d29e1ec9c61c2c42d4c5419e1ae96121edaa380ec1bc763d2f402d50fe59c1ffffffff024054890000000000fd5c01b705406c627279141af0d12eeeb2b95f2298e3dfeeacfa926a83da3f4d22010012ba010a583056301006072a8648ce3d020106052b8104000a03420004bf069ae512dcfc6aca2c04b983dbc983be0e3111e3d15366851a5938f509a13936d15822e89839397acf0634eecf755bf0525c2516c68b91c5ca15b887296bbf120e68656c6c6f406c6272792e636f6d1a1068747470733a2f2f6c6272792e636f6d223c2a3a68747470733a2f2f737065652e63682f342f36386631613839612d623664662d343634662d613438312d3038383562333466666161352e6a706742044c425259523c2a3a68747470733a2f2f737065652e63682f382f38356239343635342d646263332d346635342d623035342d6631633538373337396637352e706e675a044c4252595a044e6577735a0a626c6f636b636861696e5a0663727970746f6d6d76a914fadd6786cb77bd115a3fc9a10f9dd2a81bdb3a7288ac70da0500000000001976a914145254f61071e77c6802b1bc6c08648ceb7cd34688ac00000000",{"block_height":682018,"merkle":["1c76ac5c97d2d00deb4b891065a7cbfe0c405801e9a0035d4c4c7c9179ad3431","ef69ca48645347096b3b3b6f25c926756e88aad0d3a4b125cd081ebb4e8c197d","5e5951947cb31c33f053361d149b26c59f598af01c24b21af580987023425497","7e4e2684427205f5623f41325ed21279685b909125e21f7cb4f7e417b2857d89","212d7086b78968f4052175bee267d6c2f9942f3153edc5ca5162315387f85fde","0bd91a08621bc471afe73f5d6b41a74569c9f2c800718c22c2f7c4e9402a35ba"],"pos":48}]},"id":0}

blockchain.transaction.info

echo -e -n '{ "id": 0, "method":"blockchain.transaction.info", "params": ["d22e243be78d4dd4b5fcbebf800dcebc066b1df1b042b363910e5f507d1d61f6"]}\n' | timeout 2 nc 10.100.20.20 50001 -i 1

{"jsonrpc":"2.0","result":["010000000282a2750b0a78cb74f427438dfe569aad05020caaad0d1aa58e8c01ccaf25bcfa000000006a47304402207dc3309ae0be9078e1363d76b23533b8c6ff0f15853d98d7162359dce29c6ec4022074837d3f402edb83f004e4ce8bd6cf57aacf3b2e485f2bbba426293fd65cab0701210268b787a2cd3fbdd5c3b1fc9daa9fecd0c5e7cad7490a83a62d2adf3a75d96fc6ffffffffa5d4d2f2633876a48889d64810028b7e33cf157977f5872706baaf264814d2ca010000006b483045022100ba04f06c15330fc3cdc06475f99094833c27d931d917ecb24a7782c6e3271658022040a77d504c198128e125a9b5e5c6432b36967bbd91667184b170eda4cf94632501210255d29e1ec9c61c2c42d4c5419e1ae96121edaa380ec1bc763d2f402d50fe59c1ffffffff024054890000000000fd5c01b705406c627279141af0d12eeeb2b95f2298e3dfeeacfa926a83da3f4d22010012ba010a583056301006072a8648ce3d020106052b8104000a03420004bf069ae512dcfc6aca2c04b983dbc983be0e3111e3d15366851a5938f509a13936d15822e89839397acf0634eecf755bf0525c2516c68b91c5ca15b887296bbf120e68656c6c6f406c6272792e636f6d1a1068747470733a2f2f6c6272792e636f6d223c2a3a68747470733a2f2f737065652e63682f342f36386631613839612d623664662d343634662d613438312d3038383562333466666161352e6a706742044c425259523c2a3a68747470733a2f2f737065652e63682f382f38356239343635342d646263332d346635342d623035342d6631633538373337396637352e706e675a044c4252595a044e6577735a0a626c6f636b636861696e5a0663727970746f6d6d76a914fadd6786cb77bd115a3fc9a10f9dd2a81bdb3a7288ac70da0500000000001976a914145254f61071e77c6802b1bc6c08648ceb7cd34688ac00000000",{"block_height":682018,"merkle":["1c76ac5c97d2d00deb4b891065a7cbfe0c405801e9a0035d4c4c7c9179ad3431","ef69ca48645347096b3b3b6f25c926756e88aad0d3a4b125cd081ebb4e8c197d","5e5951947cb31c33f053361d149b26c59f598af01c24b21af580987023425497","7e4e2684427205f5623f41325ed21279685b909125e21f7cb4f7e417b2857d89","212d7086b78968f4052175bee267d6c2f9942f3153edc5ca5162315387f85fde","0bd91a08621bc471afe73f5d6b41a74569c9f2c800718c22c2f7c4e9402a35ba"],"pos":48}],"id":0}

blockchain.transaction.get_merkle

blockchain.transaction.get_height

echo -e -n '{ "id": 0, "method":"blockchain.transaction.get_height", "params": ["d22e243be78d4dd4b5fcbebf800dcebc066b1df1b042b363910e5f507d1d61f6"]}\n' | timeout 2 nc 10.100.20.20 50001 -i 1

blockchain.estimatefee
blockchain.relayfee
mempool.get_fee_histogram
server.ping
server.banner
server.payment_address
server.donation_address

server.features

echo -e -n '{ "id": 0, "method":"server.features", "params": []}\n' | timeout 2 nc spv19.lbry.com 50001 -i 1

{"jsonrpc":"2.0","result":{"hosts":{},"pruning":null,"server_version":"0.107.0","protocol_min":"0.54.0","protocol_max":"0.199.0","genesis_hash":"9c89283ba0f3227f6c03b70216b9f665f0118d5e0fa729cedf4fb34d6a34f463","description":"","payment_address":"","donation_address":"","daily_fee":"0","hash_function":"sha256","trending_algorithm":"fast_ar"},"id":0}

server.version

echo -e -n '{ "id": 0, "method":"server.version", "params": []}\n' | timeout 2 nc spv19.lbry.com 50001 -i 1

{"jsonrpc":"2.0","result":["0.107.0","0.54.0"],"id":0}