Skip to content

Herald API

Jump to bottom
Jack Robison edited this page Oct 14, 2022 · 2 revisions

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}

    

    • 



              


          



  
          

            


            
Clone this wiki locally