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: 4bytearray32-byte transaction-id
BitcoinScriptHashed: 9sha256sha256 (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: 1bytearrayThe raw transaction
BlockHeight: 7numberHeight 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: 20bytearrayThe 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: 1bytearray32-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: 0boolIndicator for a next question
TxId: 4bytearray32-byte transaction hash
Output_Index 21natural-numberthe 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: 0boolIndicator for a next question
BlockHeight: 7numberHeight of the block in the chain.
Tx_OffsetInBlock: 8natural-numberByte-offset in block
Output_Index 21natural-numberthe index of the output.
UnspentState: 26booleanTrue 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: 4bytearray32-byte transaction hash
Output_Index 21natural-numberthe 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: 26booleanTrue if unspent, false if not found in utxo.
BlockHeight: 7numberHeight of the block in the chain.
OffsetInBlock: 8natural-numberByte-offset in block
Output_Index 21natural-numberthe index of the output.
Amount 6positive-numberThe amount of satoshis this output holds.
OutputScript 23bytearrayFull 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: 4bytearray32-byte transaction-id
BitcoinScriptHashed: 9sha256sha256 (single) hash of the script-out (32 bytes)
filter options
FilterOutputIndex: 52number Only include 'output' items for this specific output-index.
Can be passed multiple times.
Include_TxId: 43boolReturn a txid field for selected transactions.
Include_OffsetInBlock: 44boolReturn offset in block field for selected transactions.
FullTransactionData: 45boolReturn full transaction data. Default true, unless one of the "Include" fields is true.
Include_Inputs: 46boolReturn all inputs for selected transactions
Include_OutputAmounts: 47boolReturn amounts (in Satoshi) for selected transactions
Include_OutputScripts: 48boolReturn out-scripts for selected transactions.
Include_Outputs: 49boolReturn all outputs for selected transactions.
Include_OutputAddresses: 50boolReturn output-addresses selected transactions, if they are p2pkh or p2pk.
Include_OutputScriptHash: 51boolReturn 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: 4bytearray32-byte transaction-id
MatchingOutIndex: 29numberWhen searching for an address, this indicates which output-index matched.
FirstSeenTime: 28numberThe UNIX-time (UTC) when this TX entered the mempool.
Transaction: 25bytearrayThe raw transaction
Tx_IN_TxId 20bytearray32-byte hash (sha256) of the spending txid that this input spends.
Tx_IN_OutIndex 21natural-numberindex input in transaction identified Tx_IN_TxID that this input is spending.
Tx_InputScript 22bytearrayFull input script. Typically pubkeys and signatures.
Tx_Out_Index 24natural-numberthe index of the output in the current transaction.
Tx_Out_Amount 6positive-numberThe amount of satoshis this output holds.
Tx_OutputScript 23bytearrayFull outputscript
DSProofId: 27bytearray32-byte double spend proof-id
separator: 0boolIndicator 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: 60numberCurrent tx count
MempoolBytes: 61numberSum of all tx sizes
MempoolUsage: 62numberTotal memory usage for the mempool
MaxMempool: 63numberMaximum memory usage for the mempool