- Flowee the Hub/
- Service API overview
- Service/Blockchain
- Service/Live Transactions
- Service/Mining
- Service/Util
- Service/RegTest
- Service/Hub Control
- Service/Indexer
- Service/AddressMonitor
- Service/TransactionMonitor
- Service/BlockNotification
- Service/Double Spend
- Service/System
- Protocol Spec
- Example Message
Flowee the Hub — API documentation
Service/Live Transactions
Live Transaction Service
Whereas most of the APIs are about historical (unchanging) records, this service provides several APIs for live data, data that can change as time moves on.
Transactions in Bitcoin Cash are collected in a mempool before they are mined in a block, this service allows you to fetch transactions from that pool (and recently mined blocks) and to submit new transactions you want to submit for mining.
Transactions that have been mined create outputs that hold money which can be spent by the owner of that money. This information is collected in the unspent-transaction-outputs database (in short UTXO DB). This service provides querying features for the UTXO.
This service uses service ID 2.
Messages
GetTransaction
Allow fetching a transaction from the mempool. You can fetch either on the txid, in which case a direct match is expected either in the mempool or in the most recent (last 6) blocks.
When searching on txid and nothing is found, an error message is returned via command failed message-type).
Alternatively, since Hub version 2021.02 you can pass in a BitcoinScriptHashed value as a representing a bitcoin-address, and search the mempool based on it. If nothing is found, an empty message will be returned.
To use a BitcoinScriptHashed tag which is a sha256, send as a 32-byte bytearray. matches happen not exactly on address, but on the entire output-script. The entire output script is hashed giving a nice constant size identifier we use instead of an address.
This fetches a transaction, returning an error (see hub) message if it is not found.
Hub / API. sId=2 mId=0 | ||
|---|---|---|
TxId: 4 | bytearray | 32-byte transaction-id |
BitcoinScriptHashed: 9 | sha256 | sha256 (single) hash of the script-out (32 bytes) |
GetTransactionReply
When a transaction was found it is returned using this reply message. Notice that we never return more than one transaction, use SearchMempool to get more detailed results.
Since Hub version 2021.02 the blockHeight field has been added.
Hub / API. sId=2 mId=1 | ||
|---|---|---|
BytesData: 1 | bytearray | The raw transaction |
BlockHeight: 7 | number | Height of the block if mined. Since 2021.2 |
SendTransaction
Offer to the network this message. The node will fully validate (check if it is well formatted, fully complete and spending existing money) before it will continue to share the message with the rest of the Bitcoin Cash network.
If the transaction could not be accepted for any reason, we reply with a command failed message from the Hub service.
Hub / API. sId=2 mId=2 | ||
|---|---|---|
Transaction: 20 | bytearray | The raw transaction |
SendTransactionReply
To confirm sending of the transaction a reply is created with the txid (sha256 hash) that has been accepted by the peer.
Hub / API. sId=2 mId=3 | ||
|---|---|---|
BytesData: 1 | bytearray | 32-byte transaction Id |
IsUnspent
Since 2019.06
The UTXO database can be queried using this method.
All queries have to be done based on the spending transaction ID (a sha256) combined with the output index (base-zero). If the output has been spent (or never existed) you will get a simple ‘false’ in your reply, if the output is unspent you will receive the block-height and the offset-in-block pair which you can use to get the full transaction from the historical record using GetTransaction method from the Blockchain service.
Also notice the GetUnspentOutput request below which gives you the actual output data in one go.
Hub / API. sId=2 mId=4 | ||
|---|---|---|
separator: 0 | bool | Indicator for a next question |
TxId: 4 | bytearray | 32-byte transaction hash |
Output_Index 21 | natural-number | the index of the output. |
In one message many requests can be stored, each separated by a Separator flag (which is a single byte).
IsUnspentReply
Since 2019.06
For each request the Unspent bool will always be returned, and the BlockHeight and Tx_OffsetInBlock will be included only when the output was found in the UTXO.
The request could have multiple lookups, each separated by a Separator. The answer will have the same number in the same order.
Hub / API. sId=2 mId=5 | ||
|---|---|---|
separator: 0 | bool | Indicator for a next question |
BlockHeight: 7 | number | Height of the block in the chain. |
Tx_OffsetInBlock: 8 | natural-number | Byte-offset in block |
Output_Index 21 | natural-number | the index of the output. |
UnspentState: 26 | boolean | True if unspent, false if not found in utxo. |
GetUnspentOutput
Since 2019.06
This message is identical to the one in IsUnspent, except that it will result in a reply that includes more data.
Hub / API. sId=2 mId=6 | ||
|---|---|---|
TxId: 4 | bytearray | 32-byte transaction hash |
Output_Index 21 | natural-number | the index of the output. |
GetUnspentOutputReply
Since 2019.06
For each request the Unspent bool will always be returned, the other values will only be included when the output was found in the UTXO.
The request could have multiple lookups, each separated by a Separator. The answer will have the same number in the same order.
Hub / API. sId=2 mId=7 | ||
|---|---|---|
UnspentState: 26 | boolean | True if unspent, false if not found in utxo. |
BlockHeight: 7 | number | Height of the block in the chain. |
OffsetInBlock: 8 | natural-number | Byte-offset in block |
Output_Index 21 | natural-number | the index of the output. |
Amount 6 | positive-number | The amount of satoshis this output holds. |
OutputScript 23 | bytearray | Full outputscript |
SearchMempool
Since 2021.01
This allows a search based on TxId or output-script-hash for mempool transactions. We include double spend proof info when available in the reply.
Hub / API. sId=2 mId=8 | ||
|---|---|---|
TxId: 4 | bytearray | 32-byte transaction-id |
BitcoinScriptHashed: 9 | sha256 | sha256 (single) hash of the script-out (32 bytes) |
| filter options | ||
FilterOutputIndex: 52 | number | Only include 'output' items for this specific output-index. Can be passed multiple times. |
Include_TxId: 43 | bool | Return a txid field for selected transactions. |
Include_OffsetInBlock: 44 | bool | Return offset in block field for selected transactions. |
FullTransactionData: 45 | bool | Return full transaction data. Default true, unless one of the "Include" fields is true. |
Include_Inputs: 46 | bool | Return all inputs for selected transactions |
Include_OutputAmounts: 47 | bool | Return amounts (in Satoshi) for selected transactions |
Include_OutputScripts: 48 | bool | Return out-scripts for selected transactions. |
Include_Outputs: 49 | bool | Return all outputs for selected transactions. |
Include_OutputAddresses:
50 | bool | Return output-addresses selected transactions, if they are p2pkh or p2pk. |
Include_OutputScriptHash: 51 | bool | Return output-script hashed. Supports all payment types. |
SearchMempoolReply
The answer includes all results, delimited by a Separator item.
Hub / API. sId=2 mId=9 | ||
|---|---|---|
TxId: 4 | bytearray | 32-byte transaction-id |
MatchingOutIndex: 29 | number | When searching for an address, this indicates which output-index matched. |
FirstSeenTime: 28 | number | The UNIX-time (UTC) when this TX entered the mempool. |
Transaction: 25 | bytearray | The raw transaction |
Tx_IN_TxId 20 | bytearray | 32-byte hash (sha256) of the spending txid that this input spends. |
Tx_IN_OutIndex 21 | natural-number | index input in transaction identified Tx_IN_TxID that this input is spending. |
Tx_InputScript 22 | bytearray | Full input script. Typically pubkeys and signatures. |
Tx_Out_Index 24 | natural-number | the index of the output in the current transaction. |
Tx_Out_Amount 6 | positive-number | The amount of satoshis this output holds. |
Tx_OutputScript 23 | bytearray | Full outputscript |
DSProofId: 27 | bytearray | 32-byte double spend proof-id |
separator: 0 | bool | Indicator to start the next answer |
GetMempoolInfo
Since 2021.01
The request does not take any options.
Hub / API. sId=2 mId=10 |
|---|
GetMempoolInfoReply
This reply contains several fields.
Hub / API. sId=2 mId=11 | ||
|---|---|---|
MempoolSize: 60 | number | Current tx count |
MempoolBytes: 61 | number | Sum of all tx sizes |
MempoolUsage: 62 | number | Total memory usage for the mempool |
MaxMempool: 63 | number | Maximum memory usage for the mempool |