Protocol Methods

This document embeds all methods supported by Rostrum. You can also navigate to individual methods from the navigation or search bar.

blockchain.address.decode

Decode a Bitcoin Cash or a Nexa address to its raw payload. This method is potentially useful for clients needing to see the encoded contents of a address but lacking the local libraries necessary to decode them.

Signature

Function: blockchain.address.decode(address)

Version added: Rostrum 7.0

• address

  Address encoded as a CashAddr string (with or without prefix). Legacy addresses (base58) are also supported.

Result

The decoded payload of the address and the type of data it represents.

Example Result

{
  "payload": "96cbbc84783888e4cc971ae8acf86dd3c1a41937",
  "type": "p2pkh",
  "is_token_aware": "false"
}

blockchain.address.get_balance

Return the confirmed and unconfirmed balances of a Bitcoin Cash address.

Signature

Function: blockchain.address.get_balance(address, { "include_tokens": true, ...})

Version added: 1.4.3

• address

  Address encoded as a CashAddr string (with or without prefix). Legacy addresses (base58) are also supported.

• filter

  Filter dict for what transactions/utxos are included in the result. Valid filters are:

  • include_tokens - Include all, including those with tokens (default: true).
  • tokens_only - Include only those that contain tokens (default: false).
  • exclude_tokens - Include only those without tokens (default: false).
  • offset - Skip the first n elements (default: 0)
  • limit - Return at most n elements. Use '0' for no limit (default: 0)

  For backward compatibility, include_tokens, tokens_only, and exclude_tokens can be passed as string instead of dict.

Result

See blockchain.scripthash.get_balance.

blockchain.address.get_first_use

Returns a first occurance of usage of scripthash as ouput on the blockchain.

See blockchain.scripthash.get_first_use.

Signature

Function: blockchain.scripthash.get_first_use(address, { "include_tokens": true, ...})

Version added: Added in Rostrum 1.2 (previously named ElectrsCash)

• address

  Address encoded as a CashAddr string (with or without prefix). Legacy addresses (base58) are also supported.

• filter

  Filter dict for what transactions/utxos are included in the result. Valid filters are:

  • from_height - Include from the given block height, inclusive (default: 0).
  • to_height - Include up to the given block height, exclusive. Use -1 to include mempool (default: -1).
  • include_tokens - Include all, including those with tokens (default: true).
  • tokens_only - Include only those that contain tokens (default: false).
  • exclude_tokens - Include only those without tokens (default: false).
  • offset - Skip the first n elements (default: 0)
  • limit - Return at most n elements. Use '0' for no limit (default: 0)

  For backward compatibility, include_tokens, tokens_only, and exclude_tokens can be passed as string instead of dict.

Result

See blockchain.scripthash.get_first_use.

blockchain.address.get_history

Return the confirmed and unconfirmed history of a Bitcoin Cash or Nexa address.

Signature

Function: blockchain.address.get_history(address, { "include_tokens": true, ...})

Version added: 1.4.3

• address

  Address encoded as a CashAddr string (with or without prefix). Legacy addresses (base58) are also supported.

• filter

  Filter dict for what transactions/utxos are included in the result. Valid filters are:

  • from_height - Include from the given block height, inclusive (default: 0).
  • to_height - Include up to the given block height, exclusive. Use -1 to include mempool (default: -1).
  • include_tokens - Include all, including those with tokens (default: true).
  • tokens_only - Include only those that contain tokens (default: false).
  • exclude_tokens - Include only those without tokens (default: false).
  • offset - Skip the first n elements (default: 0)
  • limit - Return at most n elements. Use '0' for no limit (default: 0)

  For backward compatibility, include_tokens, tokens_only, and exclude_tokens can be passed as string instead of dict.

Result

See blockchain.scripthash.get_history

blockchain.address.get_mempool

Return the unconfirmed transactions of a Bitcoin Cash or Nexa address.

Signature

Function: blockchain.address.get_mempool(address, { "include_tokens": true, ...})

Version added: 1.4.3

• address

  Address encoded as a CashAddr string (with or without prefix). Legacy addresses (base58) are also supported.

• filter

  Filter dict for what transactions/utxos are included in the result. Valid filters are:

  • include_tokens - Include all, including those with tokens (default: true).
  • tokens_only - Include only those that contain tokens (default: false).
  • exclude_tokens - Include only those without tokens (default: false).
  • offset - Skip the first n elements (default: 0)
  • limit - Return at most n elements. Use '0' for no limit (default: 0)

  For backward compatibility, include_tokens, tokens_only, and exclude_tokens can be passed as string instead of dict.

Result

As for blockchain.scripthash.get_mempool

blockchain.address.get_scripthash

Translate a Bitcoin Cash or a Nexa address to a script hash. This method is potentially useful for clients preferring to work with script hashes but lacking the local libraries necessary to generate them.

Signature

Function: blockchain.address.get_scripthash(address)

Version added: 1.4.3

• address

  Address encoded as a CashAddr string (with or without prefix). Legacy addresses (base58) are also supported.

Result

The unique 32-byte hex-encoded script hash that corresponds to the decoded address.

blockchain.address.listunspent

Return an ordered list of UTXOs sent to a Bitcoin Cash or Nexa address.

Signature

Function: blockchain.address.listunspent(address, { "include_tokens": true, ...})

Version added: 1.4.3

• address

  Address encoded as a CashAddr string (with or without prefix). Legacy addresses (base58) are also supported.

• filter

  Filter dict for what transactions/utxos are included in the result. Valid filters are:

  • from_height - Include from the given block height, inclusive (default: 0).
  • to_height - Include up to the given block height, exclusive. Use -1 to include mempool (default: -1).
  • include_tokens - Include all, including those with tokens (default: true).
  • tokens_only - Include only those that contain tokens (default: false).
  • exclude_tokens - Include only those without tokens (default: false).
  • offset - Skip the first n elements (default: 0)
  • limit - Return at most n elements. Use '0' for no limit (default: 0)

  For backward compatibility, include_tokens, tokens_only, and exclude_tokens can be passed as string instead of dict.

Result

As for blockchain.scripthash.listunspent

blockchain.address.subscribe

Subscribe to a Bitcoin Cash or Nexa address.

Signature

Function: blockchain.address.subscribe(address)

Version added: 1.4.3

• address

  Address encoded as a CashAddr string (with or without prefix). Legacy addresses (base58) are also supported.

Result

The status of the address.

Notifications

As this is a subcription, the client will receive a notification when the status of the address changes. Its signature is

Function: blockchain.address.subscribe(address, status)

Note
The address returned back to the client when notifying of status changes will be in the same encoding and style as was provided when subscribing. In effect, a whitespace-stripped version of the address string that the client provided will be sent back to the client when notifying, in order to make it easier for clients to track the notification.
It is unspecified what happens if a client subscribes to the same address using multiple encodings or styles, but it is RECOMMENDED that servers simply update their internal subscription tables on subsequent subscriptions to the same destination such that they honor the latest subscription only, and not subscribe clients multiple times to the same logical destination. For example, Rostrum server will simply update its table for how to refer to the subscription and send clients subsequent notifications using the latest encoding style of that particular address that the client last provided.
Similarly, if a client mixes blockchain.address.* and blockchain.scripthash.* calls to the server, it is RECOMMENDED that the server treat all addresses as equivalent to their scripthashes internally such that it is possible to subscribe by address and later unsubscribe by scripthash, for example.

blockchain.address.unsubscribe

Unsubscribe from a Bitcoin Cash or Nexa address, preventing future notifications if its status changes.

Signature

Function: blockchain.address.unsubscribe(address)

Version added: 1.4.3

• address

  Address encoded as a CashAddr string (with or without prefix). Legacy addresses (base58) are also supported.

Result

Returns True if the address was subscribed to, otherwise False. Note that False might be returned even for something subscribed to earlier, because the server can drop subscriptions in rare circumstances.

blockchain.block.get

Return the full block with given hash or at the given height.

Signature

Function: blockchain.block.get(height_or_hash)

Version added: Rostrum 8.1

hash_or_height

The blockhash as hex encoded string or the height of the block, a non-negative integer.

Result

The raw block as a hexadecimal string.

blockchain.block.header

Return the block header at the given height.

Signature

Function: blockchain.block.header(height, cp_height=0)

Version added: 1.3

Version changed: 1.4 cp_height parameter added

Version changed: 1.4.1

height

The height of the block, a non-negative integer.

cp_height

Checkpoint height, a non-negative integer. Ignored if zero, otherwise the following must hold:

height <= cp_height

Result

If cp_height is zero, the raw block header as a hexadecimal string.

Otherwise a dictionary with the following keys. This provides a proof that the given header is present in the blockchain; presumably the client has the merkle root hard-coded as a checkpoint.

• branch

  The merkle branch of header up to root, deepest pairing first.

• header

  The raw block header as a hexadecimal string. Starting with version 1.4.1, AuxPoW data (if present in the original header) is truncated.

• root

  The merkle root of all blockchain headers up to and including cp_height.

Example Result

With height 5 and cp_height 0 on the Bitcoin Cash chain:

"0100000085144a84488ea88d221c8bd6c059da090e88f8a2c99690ee55dbba4e00000000e11c48fecdd9e72510ca84f023370c9a38bf91ac5cae88019bee94d24528526344c36649ffff001d1d03e477"

With cp_height 8:

{
  "branch": [
     "000000004ebadb55ee9096c9a2f8880e09da59c0d68b1c228da88e48844a1485",
     "96cbbc84783888e4cc971ae8acf86dd3c1a419370336bb3c634c97695a8c5ac9",
     "965ac94082cebbcffe458075651e9cc33ce703ab0115c72d9e8b1a9906b2b636",
     "89e5daa6950b895190716dd26054432b564ccdc2868188ba1da76de8e1dc7591"
     ],
  "header": "0100000085144a84488ea88d221c8bd6c059da090e88f8a2c99690ee55dbba4e00000000e11c48fecdd9e72510ca84f023370c9a38bf91ac5cae88019bee94d24528526344c36649ffff001d1d03e477",
  "root": "e347b1c43fd9b5415bf0d92708db8284b78daf4d0e24f9c3405f45feb85e25db"
}

blockchain.block.header_verbose

Return the block header at the given height with all fields decoded.

Signature

Function: blockchain.block.header_verbose(height_or_hash)

Version added: Rostrum 10.1

height_or_hash

The height of the block, a non-negative integer, or a blockhash.

Result

A block header with all of its fields decoded, in addition to median time past and header hex.

Example Result

Bitcoin CashNexa

{
  'bits': 545259519,
  'hash': '6f5b55854744733d8c1a99aef931c3b6f031f1bfb0428845a1849b80fc1b3ded',
  'height': 111,
  'hex': '00000020710155a76704894788fb8cca9ecac8805f3d0a734a1ee6d35dd625ff67dd6b4851a1389e8ef78148c9c7e965509125139222bda371dd2f9518eb196bd52bc6c60dedb065ffff7f2000000000',
  'mediantime': 1706093836,
  'merkleroot': 'c6c62bd56b19eb18952fdd71a3bd22921325915065e9c7c94881f78e9e38a151',
  'nonce': 0,
  'previousblockhash': '486bdd67ff25d65dd3e61e4a730a3d5f80c8ca9eca8cfb8847890467a7550171',
  'time': 1706093837,
  'version': 536870912
}

{
  'ancestorhash': 'd71ee431e307d12dfef31a6b21e071f1d5652c0eb6155c04e3222612c9d0b371',
  'bits': 545259519,
  'chainwork': '00000000000000000000000000000000000000000000000000000000000000e0',
  'feepoolamt': 0,
  'hash': '08abee10a905a482d40339aa4cc99902b4a201b19281ba23d4fcf64a0ec62e85',
  'height': 111,
  'hex': 'd14b2a495d2a38651f66c199b0e9680c59e4852227cfdc65d8b8a6cc47dfe502ffff7f2071b3d0c9122622e3045c15b60e2c65d5f171e0216b1af3fe2dd107e331e41ed7680fe515f6314078bd90009de3f5f456ef8c2b4c87e76a5fa6da14b784ae5a2b0000000000000000000000000000000000000000000000000000000000000000d3ecb0656fe000000000000000000000000000000000000000000000000000000000000000bd2b000000000000330000000405000000',
  'mediantime': 1706093778,
  'merkleroot': '2b5aae84b714daa65f6ae7874c2b8cef56f4f5e39d0090bd784031f615e50f68',
  'minerdata': '',
  'nonce': '05000000',
  'previousblockhash':
  '02e5df47cca6b8d865dccf272285e4590c68e9b099c1661f65382a5d492a4bd1',
  'size': 11197,
  'time': 1706093779,
  'txcount': 51,
  'txfilter': '0000000000000000000000000000000000000000000000000000000000000000',
  'utxocommitment': ''
}

blockchain.block.headers

Return a concatenated chunk of block headers from the main chain.

Signature

Function: blockchain.block.headers(start_height, count, cp_height=0)

Version added: 1.2

Version changed: 1.4 cp_height parameter added

Version changed: 1.4.1

start_height

The height of the first header requested, a non-negative integer.

count

The number of headers requested, a non-negative integer.

cp_height

Checkpoint height, a non-negative integer. Ignored if zero, otherwise the following must hold:

start_height + (count - 1) <= cp_height

Result

A dictionary with the following members:

• count

  The number of headers returned, between zero and the number requested. If the chain has not extended sufficiently far, only the available headers will be returned. If more headers than max were requested at most max will be returned.

• hex

  The binary block headers concatenated together in-order as a hexadecimal string. Starting with version 1.4.1, AuxPoW data (if present in the original header) is truncated if cp_height is nonzero.

• max

  The maximum number of headers the server will return in a single request.

The dictionary additionally has the following keys if count and cp_height are not zero. This provides a proof that all the given headers are present in the blockchain; presumably the client has the merkle root hard-coded as a checkpoint.

• root

  The merkle root of all blockchain headers up to and including cp_height.

• branch

  The merkle branch of the last returned header up to root, deepest pairing first.

Example Response

See here <cp_height example> for an example of root and branch keys.

{
  "count": 2,
  "hex": "0100000000000000000000000000000000000000000000000000000000000000000000003ba3edfd7a7b12b27ac72c3e67768f617fc81bc3888a51323a9fb8aa4b1e5e4a29ab5f49ffff001d1dac2b7c010000006fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000982051fd1e4ba744bbbe680e1fee14677ba1a3c3540bf7b1cdb606e857233e0e61bc6649ffff001d01e36299"
  "max": 2016
}

blockchain.estimatefee

Return the estimated transaction fee per kilobyte for a transaction to be confirmed within a certain number of blocks.

Signature

Function: blockchain.estimatefee(number) :::

number

The number of blocks to target for confirmation.

Result

The estimated transaction fee in coin units per kilobyte, as a floating point number. If the server does not have enough information to make an estimate, the integer -1 is returned.

Example Result

0.00101079

blockchain.headers.subscribe

Subscribe to receive block headers when a new block is found.

Signature

Function: blockchain.headers.subscribe()

Result

The header of the current block chain tip. The result is a dictionary with two members:

• hex

  The binary header as a hexadecimal string.

• height

  The height of the header, an integer.

Example Result

{
  "height": 520481,
  "hex": "00000020890208a0ae3a3892aa047c5468725846577cfcd9b512b50000000000000000005dc2b02f2d297a9064ee103036c14d678f9afc7e3d9409cf53fd58b82e938e8ecbeca05a2d2103188ce804c4"
}

Notifications

As this is a subcription, the client will receive a notification when a new block is found. The notification's signature is:

Function: blockchain.headers.subscribe(header)

• header

  See Result above.

Note
Should a new block arrive quickly, perhaps while the server is still processing prior blocks, the server may only notify of the most recent chain tip. The protocol does not guarantee notification of all intermediate block headers.
In a similar way the client must be prepared to handle chain reorganisations. Should a re-org happen the new chain tip will not sit directly on top of the prior chain tip. The client must be able to figure out the common ancestor block and request any missing block headers to acquire a consistent view of the chain state.
If a client subscribes multiple times, the subsequent subscriptions will be ignored and the client will continue to receive one notification per header.

See also

Get tip without subscribing with blockchain.headers.tip

blockchain.headers.tip

Get the latest block header (tip of the blockchain).

Signature

Function: blockchain.headers.tip()

Added: Rostrum 7.0

Result

The header of the current block chain tip. The result is a dictionary with two members:

• hex

  The binary header as a hexadecimal string.

• height

  The height of the header, an integer.

This call gives the same result as blockchain.headers.subscribe, but without starting to subscribe to headers.

Example Result

{
  "height": 520481,
  "hex": "00000020890208a0ae3a3892aa047c5468725846577cfcd9b512b50000000000000000005dc2b02f2d297a9064ee103036c14d678f9afc7e3d9409cf53fd58b82e938e8ecbeca05a2d2103188ce804c4"
}

blockchain.relayfee

Return the minimum fee a low-priority transaction must pay in order to be accepted to the daemon's memory pool.

Signature

Function: blockchain.relayfee()

Result

The fee in whole coin units (BTC, not satoshis for Bitcoin) as a floating point number.

Example Results

1e-05

0.0

blockchain.scripthash.get_balance

Return the confirmed and unconfirmed balances of a script hash.

Signature

Function: blockchain.scripthash.get_balance(scripthash, { "include_tokens": true, ...})

Version added: 1.1

• scripthash

  The script hash as a hexadecimal string.

• filter

  Filter dict for what transactions/utxos are included in the result. Valid filters are:

  • include_tokens - Include all, including those with tokens (default: true).
  • tokens_only - Include only those that contain tokens (default: false).
  • exclude_tokens - Include only those without tokens (default: false).
  • offset - Skip the first n elements (default: 0)
  • limit - Return at most n elements. Use '0' for no limit (default: 0)

  For backward compatibility, include_tokens, tokens_only, and exclude_tokens can be passed as string instead of dict.

Result

A dictionary with keys confirmed and unconfirmed. The value of each is the appropriate balance in satoshis.

Result Example

{
  "confirmed": 103873966,
  "unconfirmed": 236844
}

blockchain.scripthash.get_first_use

Returns a first occurance of usage of scripthash as ouput on the blockchain. Any transaction in a confirmed block may be returned, as long as it's the first block that contains use of scripthash.

If there are no matching transactions in the blockchain, but there are in the mempool, one of these are returned instead. In this case, the block hash returned is the hex representation of 0 and block height the numeric value 0

If there are no matching transactions in the blockchain or on the mempool, an error is returned.

Rationale for requiring the scripthash being an output is to allow wallets to verify the response without having to fetch the input transactions. There cannot exist earlier occurances of scripthash being used as input, an ouput must exist first.

Signature

Function: blockchain.block.get_first_use(scripthash, { "include_tokens": true, ...})

Version added: Rostrum 1.2 (previously named ElectrsCash)

• scripthash

The script hash as a hexadecimal string.

• filter

  Filter dict for what transactions/utxos are included in the result. Valid filters are:

  • from_height - Include from the given block height, inclusive (default: 0).
  • to_height - Include up to the given block height, exclusive. Use -1 to include mempool (default: -1).
  • include_tokens - Include all, including those with tokens (default: true).
  • tokens_only - Include only those that contain tokens (default: false).
  • exclude_tokens - Include only those without tokens (default: false).
  • offset - Skip the first n elements (default: 0)
  • limit - Return at most n elements. Use '0' for no limit (default: 0)

  For backward compatibility, include_tokens, tokens_only, and exclude_tokens can be passed as string instead of dict.

Result

A dictionary with the following keys.

• height

The block height of the block where the first occurance of scripthash exists.

Block height is 0 if the first occurance is in the mempool.

• block_hash

The block hash of the block where the first occurance of scripthash exists.

Block hash is hex of 0 if the first occurance is in the mempool.

• tx_hash

A hash of single transaction containing the scripthash in its output.

Example Result

With scripthash 273139c9327743dccc1030fc8d009e63e41e147c6b0449913d2dea5b71eef230 on the Bitcoin Cash chain:

 {
    'block_hash': '000000000000000002a04f56505ef459e1edd21fb3725524116fdaedf3a4d0ab',
    'block_height': 597843,
    'tx_hash': 'cef9c1485f166e92adf0b5d42e4ad202e4f5f9e2e7a072d0a6864c61c2cd6fa0'
  }

blockchain.scripthash.get_history

Return the confirmed and unconfirmed history of a script hash

Signature

Function: blockchain.scripthash.get_history(scripthash, { "include_tokens": true, ...})

Version added: 1.1

• scripthash

The script hash as a hexadecimal string.

• filter

  Filter dict for what transactions/utxos are included in the result. Valid filters are:

  • from_height - Include from the given block height, inclusive (default: 0).
  • to_height - Include up to the given block height, exclusive. Use -1 to include mempool (default: -1).
  • include_tokens - Include all, including those with tokens (default: true).
  • tokens_only - Include only those that contain tokens (default: false).
  • exclude_tokens - Include only those without tokens (default: false).
  • offset - Skip the first n elements (default: 0)
  • limit - Return at most n elements. Use '0' for no limit (default: 0)

  For backward compatibility, include_tokens, tokens_only, and exclude_tokens can be passed as string instead of dict.

Result

A list of confirmed transactions in blockchain order, with the output of blockchain.scripthash.get_mempool appended to the list. Each confirmed transaction is a dictionary with the following keys:

• height

  The integer height of the block the transaction was confirmed in.

• tx_hash

  The transaction hash in hexadecimal.

See blockchain.scripthash.get_mempool for how mempool transactions are returned.

Result Examples

[
  {
    "height": 200004,
    "tx_hash": "acc3758bd2a26f869fcc67d48ff30b96464d476bca82c1cd6656e7d506816412"
  },
  {
    "height": 215008,
    "tx_hash": "f3e1bf48975b8d6060a9de8884296abb80be618dc00ae3cb2f6cee3085e09403"
  }
]

[
  {
    "fee": 20000,
    "height": 0,
    "tx_hash": "9fbed79a1e970343fcd39f4a2d830a6bde6de0754ed2da70f489d0303ed558ec"
  }
]

blockchain.scripthash.get_mempool

Return the unconfirmed transactions of a script hash <script hashes>.

Signature

Function: blockchain.scripthash.get_mempool(scripthash, { "include_tokens": true, ...})

Version added: 1.1

• scripthash

The script hash as a hexadecimal string.

• filter

  Filter dict for what transactions/utxos are included in the result. Valid filters are:

  • include_tokens - Include all, including those with tokens (default: true).
  • tokens_only - Include only those that contain tokens (default: false).
  • exclude_tokens - Include only those without tokens (default: false).
  • offset - Skip the first n elements (default: 0)
  • limit - Return at most n elements. Use '0' for no limit (default: 0)

  For backward compatibility, include_tokens, tokens_only, and exclude_tokens can be passed as string instead of dict.

Result

A list of mempool transactions in arbitrary order. Each mempool transaction is a dictionary with the following keys:

• height

  0 if all inputs are confirmed, and -1 otherwise.

• tx_hash

  The transaction hash in hexadecimal.

• fee

  The transaction fee in minimum coin units (satoshis).

Result Example

[
  {
    "tx_hash": "45381031132c57b2ff1cbe8d8d3920cf9ed25efd9a0beb764bdb2f24c7d1c7e3",
    "height": 0,
    "fee": 24310
  }
]

blockchain.scripthash.listunspent

Return an ordered list of UTXOs sent to a script hash.

Signature

Function: blockchain.scripthash.listunspent(scripthash, { "include_tokens": true, ...})

Version added: 1.1

• scripthash

The script hash as a hexadecimal string.

• filter

  Filter dict for what transactions/utxos are included in the result. Valid filters are:

  • from_height - Include from the given block height, inclusive (default: 0).
  • to_height - Include up to the given block height, exclusive. Use -1 to include mempool (default: -1).
  • include_tokens - Include all, including those with tokens (default: true).
  • tokens_only - Include only those that contain tokens (default: false).
  • exclude_tokens - Include only those without tokens (default: false).
  • offset - Skip the first n elements (default: 0)
  • limit - Return at most n elements. Use '0' for no limit (default: 0)

  For backward compatibility, include_tokens, tokens_only, and exclude_tokens can be passed as string instead of dict.

Result

A list of unspent outputs in blockchain order. This function takes the mempool into account. Mempool transactions paying to the address are included at the end of the list in an undefined order. Any output that is spent in the mempool does not appear. Each output is a dictionary with the following keys:

• height

  The integer height of the block the transaction was confirmed in. 0 if the transaction is in the mempool.

• tx_pos

  The zero-based index of the output in the transaction's list of outputs.

• tx_hash

  The output's transaction hash as a hexadecimal string. The hash is little-endian encoded (same as bitcoind RPC).

• value

  The output's value in minimum coin units (satoshis).

• outpoint_hash

  Hash of utxo (hash of transaction idem + output index)

Result Example

[
  {
    "tx_pos": 0,
    "value": 45318048,
    "tx_hash": "9f2c45a12db0144909b5db269415f7319179105982ac70ed80d76ea79d923ebf",
    "height": 437146,
    "outpoint_hash": "fbd96943e964abb082845fd67e89e2689e649d9ddec496605d214c131e91025e"
  },
  {
    "tx_pos": 0,
    "value": 919195,
    "tx_hash": "3d2290c93436a3e964cfc2f0950174d8847b1fbe3946432c4784e168da0f019f",
    "height": 441696,
    "outpoint_hash": "65a867e6d7da3f3986f8fe67fda311a60ac5c9b43e9f28326646f0d3f10381aa"
  }
]

blockchain.scripthash.subscribe

Subscribe to a script hash.

Signature

Function: blockchain.scripthash.subscribe(scripthash)

Version added: 1.1

scripthash

The script hash as a hexadecimal string.

Result

The status <status> of the script hash.

Notifications

The client will receive a notification when the status <status> of the script hash changes. Its signature is

Function: blockchain.scripthash.subscribe(scripthash, status)

blockchain.scripthash.unsubscribe

Unsubscribe from a script hash, preventing future notifications if its status changes.

Signature

Function: blockchain.scripthash.unsubscribe(scripthash)

Version added: 1.4.2

scripthash

The script hash as a hexadecimal string.

Result

Returns True if the scripthash was subscribed to, otherwise False. Note that False might be returned even for something subscribed to earlier, because the server can drop subscriptions in rare circumstances.

blockchain.transaction.broadcast

Broadcast a transaction to the network.

Signature

Function: blockchain.transaction.broadcast(raw_tx)

raw_tx

The raw transaction as a hexadecimal string.

Result

On Bitcoin Cash the transaction hash (aka txid) as a hexadecimal string. On Nexa the transaction idem (txidem) as a hexadecimal string.

Result Examples

"a76242fce5753b4212f903ff33ac6fe66f2780f34bdb4b33b175a7815a11a98e"

blockchain.transaction.get

Return a raw transaction.

Signature

Function: blockchain.transaction.get(tx_hash, verbose=false)

tx_hash

The transaction hash as a hexadecimal string. On Nexa, this can be either the txid or txidem. However, if called by txidem, then the node must have txindex enabled. Rostrum does not have an internal txidem index.

verbose

Return a dictionary of a decoded transaction.

Result

Bitcoin CashNexa

If verbose is false: The raw transaction as a hexadecimal string. If verbose is true: The result is a dictionary of a decoded transaction.

If transaction does not exist on blockhain or in the mempool, an error is returned.

{
  "hex" : "data",       (string) The serialized, hex-encoded data for 'txid'
  "txid" : "id",        (string) The transaction id (same as provided)
  "hash" : "id",        (string) The transaction hash
  "size" : n,             (numeric) The serialized transaction size
  "version" : n,          (numeric) The version
  "locktime" : ttt,       (numeric) The lock time
  "vin" : [               (array of json objects)
     {
       "coinbase":        (string|null) Contains scriptsig hex when coinbase input
       "txid": "id",      (string) The transaction id
       "vout": n,         (numeric)
       "scriptSig": {     (json object) The script
         "asm": "asm",    (string) asm
         "hex": "hex"     (string) hex
       },
       "sequence": n      (numeric) The script sequence number
       "value" : x.xxx,     (numeric) The input value in BCH
       "value_coins" : x.xxx,     (numeric) The input value in BCH
       "value_satoshi" : n,   (numeric) The input value in BCH in satoshis
     }
     ,...
  ],
  "vout" : [              (array of json objects)
     {
       "value" : x.xxx,            (numeric) The output value in BCH
       "value_coins" : x.xxx,      (numeric) The output value in BCH
       "value_satoshi" : n,        (numeric) The output value in BCH in satoshis
       "n" : n,                    (numeric) index
       "scriptPubKey" : {          (json object)
         "asm" : "asm",          (string) the asm
         "hex" : "hex",          (string) the hex
         "type" : "pubkeyhash",  (string) The type, eg 'pubkeyhash'
         "addresses" : [           (json array of string)
           "address"        (string) Bitcoin Cash address
           ,...
         ]
       },
       "tokenData" : {             (json object optional)
         "category" : "hex",       (string) token id
         "amount" : "xxx",         (string) fungible amount (is a string to support >53-bit amounts)
         "nft" : {                 (json object optional)
           "capability" : "xxx",   (string) one of "none", "mutable", "minting"
           "commitment" : "hex"    (string) NFT commitment
         }
       }
     }
     ,...
  ],
  "blockhash" : "hash",   (string) the block hash
  "confirmations" : n,      (numeric) The confirmations
  "time" : ttt,             (numeric) The transaction time in seconds since epoch (Jan 1 1970 GMT)
  "blocktime" : ttt,        (numeric) The block time in seconds since epoch (Jan 1 1970 GMT)
  "fee" : x.xxx,            (numeric) Transaction fee in BCH
  "fee_satoshi" : n,        (numeric) Transaction fee in BCH in satoshis
}

If verbose is false: The raw transaction as a hexadecimal string. If verbose is true: The result is a dictionary of a decoded transaction.

If transaction does not exist on blockhain or in the mempool, an error is returned.

{
  "hex" : "data",       (string) The serialized, hex-encoded data for 'txid'
  "txid" : "id",        (string) The transaction id (same as provided)
  "txidem": "idem",     (string) The transaction idem
  "hash" : "id",        (string) The transaction hash
  "size" : n,             (numeric) The serialized transaction size
  "version" : n,          (numeric) The version
  "locktime" : ttt,       (numeric) The lock time
  "vin" : [               (array of json objects)
     {
       "scriptSig": {     (json object) The script
         "asm": "asm",    (string) asm
         "hex": "hex"     (string) hex
       },
       "sequence": n      (numeric) The script sequence number
       "value" : x.xxx,     (numeric) The input value in NEX
       "value_coins" : x.xxx,     (numeric) The input value in NEX
       "value_satoshi" : n,   (numeric) The input value in NEX in satoshis
       "outpoint" "hash"  (string) The outpoint hash
       "addresses" : [           (json array of string)
          "address"        (string) Nexa address
          ,...
        ]
       "group": "token"       (string) The group ID encoded as cashaddr
       "groupQuantity": n     (numeric|null) The output value of group tokens
       "groupAuthority": n    (numeric|null) The group authority bits
     }
     ,...
  ],
  "vout" : [              (array of json objects)
     {
       "value" : x.xxx,            (numeric) The output value in NEX
       "value_coins" : x.xxx,      (numeric) The output value in NEX
       "value_satoshi" : n,        (numeric) The output value in NEX in satoshis
       "n" : n,                    (numeric) index
       "scriptPubKey" : {          (json object)
         "asm" : "asm",          (string) the asm
         "hex" : "hex",          (string) the hex
         "type" : "pubkeyhash",  (string) The type, eg 'pubkeyhash'
         "addresses" : [           (json array of string)
           "address"        (string) Nexa address
           ,...
         ]
       },
       "group": "token"       (string) The group ID encoded as cashaddr
       "groupQuantity": n     (numeric|null) The output value of group tokens
       "groupAuthority": n    (numeric|null) The group authority bits
       "token_id_hex": "id"   (string) The group ID as hex
       "scriptHash": "scripthash" (string|null) The scripthash of script template
       "argsHash": "argshash" (string|null) The argument hash of script template
       "outpoint_hash": "hex" (string) Hash of utxo (hash of transaction idem + output index)
     }
     ,...
  ],
  "blockhash" : "hash",   (string) the block hash
  "confirmations" : n,      (numeric) The confirmations
  "time" : ttt,             (numeric) The transaction time in seconds since epoch (Jan 1 1970 GMT)
  "blocktime" : ttt,        (numeric) The block time in seconds since epoch (Jan 1 1970 GMT)
  "fee" : x.xxx,            (numeric) Transaction fee in NEX
  "fee_satoshi" : n,        (numeric) Transaction fee in NEX in satoshis
}

Example Results

When verbose is false:

"01000000015bb9142c960a838329694d3fe9ba08c2a6421c5158d8f7044cb7c48006c1b48"
"4000000006a4730440220229ea5359a63c2b83a713fcc20d8c41b20d48fe639a639d2a824"
"6a137f29d0fc02201de12de9c056912a4e581a62d12fb5f43ee6c08ed0238c32a1ee76921"
"3ca8b8b412103bcf9a004f1f7a9a8d8acce7b51c983233d107329ff7c4fb53e44c855dbe1"
"f6a4feffffff02c6b68200000000001976a9141041fb024bd7a1338ef1959026bbba86006"
"4fe5f88ac50a8cf00000000001976a91445dac110239a7a3814535c15858b939211f85298"
"88ac61ee0700"

When verbose is true on Bitcoin Cash:

{
  "blockhash": "00000000000000000389720f75be0c139b11307d258ef20461d3829a0b6eaa5a",
  "blocktime": 1609802384,
  "confirmations": 97828,
  "hash": "513a9982488969ff80204b1ae6b5135b9e28516c52f658dc64b607b521af8c78",
  "height": 668904,
  "hex": "01000000017c7644abb7c34294416307c5010bd9077d75ea93930ea19d888c229ce136a11201000000644151fe1d606f3e02ebed01d436429229ec199b47c67220ae58fbf034d3b6e2f90e263477a925f5ba9cd98cadb0cf7193608da6a5cd597b43fa71adc0631441f168412103dae2be8889698de9913ca48a394e6dc49cfcc47919139b2f74dd05b8058731defeffffff030000000000000000136a11424553542052454345495054204556455275380000000000001976a9143dcff26ceba80f2aa0c5e762964f50002ba137bc88ac7c390000000000001976a914f40a3047ee2b1efc3c89072d798b9c3cb4fa374d88ace7340a00",
  "locktime": 668903,
  "size": 247,
  "time": 1609802384,
  "txid": "513a9982488969ff80204b1ae6b5135b9e28516c52f658dc64b607b521af8c78",
  "version": 1,
  "vin": [
    {
      "coinbase": null,
      "scriptSig": {
        "asm": "OP_PUSHBYTES_65 51fe1d606f3e02ebed01d436429229ec199b47c67220ae58fbf034d3b6e2f90e263477a925f5ba9cd98cadb0cf7193608da6a5cd597b43fa71adc0631441f16841 OP_PUSHBYTES_33 03dae2be8889698de9913ca48a394e6dc49cfcc47919139b2f74dd05b8058731de",
        "hex": "4151fe1d606f3e02ebed01d436429229ec199b47c67220ae58fbf034d3b6e2f90e263477a925f5ba9cd98cadb0cf7193608da6a5cd597b43fa71adc0631441f168412103dae2be8889698de9913ca48a394e6dc49cfcc47919139b2f74dd05b8058731de"
      },
      "sequence": 4294967294,
      "txid": "12a136e19c228c889da10e9393ea757d07d90b01c50763419442c3b7ab44767c",
      "vout": 1
      "value_coin": 0.00014453,
      "value_satoshi": 14453
    }
  ],
  "vout": [
    {
      "n": 0,
      "scriptPubKey": {
        "addresses": [],
        "asm": "OP_RETURN OP_PUSHBYTES_17 4245535420524543454950542045564552",
        "hex": "6a114245535420524543454950542045564552",
        "type": "nulldata"
      },
      "value": 0.0,
      "value_coin": 0.0,
      "value_satoshi": 0
    },
    {
      "n": 1,
      "scriptPubKey": {
        "addresses": [
          "bitcoincash:qq7ulunvaw5q724qchnk99j02qqzhgfhhsa7twn8mt"
        ],
        "asm": "OP_DUP OP_HASH160 OP_PUSHBYTES_20 3dcff26ceba80f2aa0c5e762964f50002ba137bc OP_EQUALVERIFY OP_CHECKSIG",
        "hex": "76a9143dcff26ceba80f2aa0c5e762964f50002ba137bc88ac",
        "type": "pubkeyhash"
      },
      "value": 0.00014453,
      "value_coin": 0.00014453,
      "value_satoshi": 14453
    },
    {
      "n": 2,
      "scriptPubKey": {
        "addresses": [
          "bitcoincash:qr6q5vz8ac43alpu3yrj67vtns7tf73hf5073aed46"
        ],
        "asm": "OP_DUP OP_HASH160 OP_PUSHBYTES_20 f40a3047ee2b1efc3c89072d798b9c3cb4fa374d OP_EQUALVERIFY OP_CHECKSIG",
        "hex": "76a914f40a3047ee2b1efc3c89072d798b9c3cb4fa374d88ac",
        "type": "pubkeyhash"
      },
      "value": 0.00014716,
      "value_coin": 0.00014716,
      "value_satoshi": 14716
    }
  ]
}

blockchain.transaction.get_confirmed_blockhash

Returns the blockhash of a block the transaction confirmed in. Returns error if transaction is not confirmed (or does not exist).

Signature

Function: blockchain.transaction.get_confirmed_blockhash(tx_hash)`

Version added: Rostrum

tx_hash

The transaction hash as a hexadecimal string.

Result

A dictionary with the following keys:

• block_hash

  The hash of the block in which the transaction was confirmed.

• block_height

  The height of the block in which the transaction was confirmed.

Example result

{
'block_hash': '000000000000000002a04f56505ef459e1edd21fb3725524116fdaedf3a4d0ab',
'block_height': 597843,
}

blockchain.transaction.get_merkle

Return the merkle branch to a confirmed transaction given its hash and height.

Signature

Function: blockchain.transaction.get_merkle(tx_hash, height (optional))

tx_hash

The transaction hash as a hexadecimal string.

height

The height at which it was confirmed, an integer. This argument is optional (ROSTRUM ONLY)

Result

A dictionary with the following keys:

• block_height

  The height of the block the transaction was confirmed in.

• merkle

  A list of transaction hashes the current hash is paired with, recursively, in order to trace up to obtain merkle root of the block, deepest pairing first.

• pos

  The 0-based index of the position of the transaction in the ordered list of transactions in the block.

Result Example

{
  "merkle":
  [
    "713d6c7e6ce7bbea708d61162231eaa8ecb31c4c5dd84f81c20409a90069cb24",
    "03dbaec78d4a52fbaf3c7aa5d3fccd9d8654f323940716ddf5ee2e4bda458fde",
    "e670224b23f156c27993ac3071940c0ff865b812e21e0a162fe7a005d6e57851",
    "369a1619a67c3108a8850118602e3669455c70cdcdb89248b64cc6325575b885",
    "4756688678644dcb27d62931f04013254a62aeee5dec139d1aac9f7b1f318112",
    "7b97e73abc043836fd890555bfce54757d387943a6860e5450525e8e9ab46be5",
    "61505055e8b639b7c64fd58bce6fc5c2378b92e025a02583303f69930091b1c3",
    "27a654ff1895385ac14a574a0415d3bbba9ec23a8774f22ec20d53dd0b5386ff",
    "5312ed87933075e60a9511857d23d460a085f3b6e9e5e565ad2443d223cfccdc",
    "94f60b14a9f106440a197054936e6fb92abbd69d6059b38fdf79b33fc864fca0",
    "2d64851151550e8c4d337f335ee28874401d55b358a66f1bafab2c3e9f48773d"
  ],
  "block_height": 450538,
  "pos": 710
}

blockchain.transaction.id_from_pos

Return a transaction hash and optionally a merkle proof, given a block height and a position in the block.

Signature

Function: blockchain.transaction.id_from_pos(height, tx_pos, merkle=false)

Version added: 1.4

height

The main chain block height, a non-negative integer.

tx_pos

A zero-based index of the transaction in the given block, an integer.

merkle

Whether a merkle proof should also be returned, a boolean.

Result

If merkle is false, the transaction hash as a hexadecimal string. If true, a dictionary with the following keys:

• tx_hash

  The transaction hash as a hexadecimal string.

• merkle

  A list of transaction hashes the current hash is paired with, recursively, in order to trace up to obtain merkle root of the block, deepest pairing first.

Example Results

When merkle is false:

"fc12dfcb4723715a456c6984e298e00c479706067da81be969e8085544b0ba08"

When merkle is true:

{
  "tx_hash": "fc12dfcb4723715a456c6984e298e00c479706067da81be969e8085544b0ba08",
  "merkle":
  [
    "928c4275dfd6270349e76aa5a49b355eefeb9e31ffbe95dd75fed81d219a23f8",
    "5f35bfb3d5ef2ba19e105dcd976928e675945b9b82d98a93d71cbad0e714d04e",
    "f136bcffeeed8844d54f90fc3ce79ce827cd8f019cf1d18470f72e4680f99207",
    "6539b8ab33cedf98c31d4e5addfe40995ff96c4ea5257620dfbf86b34ce005ab",
    "7ecc598708186b0b5bd10404f5aeb8a1a35fd91d1febbb2aac2d018954885b1e",
    "a263aae6c470b9cde03b90675998ff6116f3132163911fafbeeb7843095d3b41",
    "c203983baffe527edb4da836bc46e3607b9a36fa2c6cb60c1027f0964d971b29",
    "306d89790df94c4632d652d142207f53746729a7809caa1c294b895a76ce34a9",
    "c0b4eff21eea5e7974fe93c62b5aab51ed8f8d3adad4583c7a84a98f9e428f04",
    "f0bd9d2d4c4cf00a1dd7ab3b48bbbb4218477313591284dcc2d7ca0aaa444e8d",
    "503d3349648b985c1b571f59059e4da55a57b0163b08cc50379d73be80c4c8f3"
  ]
}

blockchain.utxo.get

Returns data on a specified output of specific transaction. Returns error if transaction or output does not exist.

If the output is spent, information about the spender is provided. This allows a SPV client to call blockchain.transaction.get\_merkle to generate a merkle branch, proving that it is spent.

Bitcoin CashNexa

Signature

Function: blockchain.utxo.get(tx_hash, output_index)

Version added: Rostrum 7.0

Update Rostrum 8.1: Add token details and scriptpukey

tx_hash

The transaction ID as hexadecimal string.

output_index

The vout position in the transaction.

Result

A dictionary with the following keys:

• status

State of the utxo. A string that is "spent" or "unspent".

• height

The height the utxo was confirmed in. If it is unconfirmed, the value is 0 if all inputs are confirmed, and -1 otherwise.

• value

The output’s value in minimum coin units (satoshis).

• scripthash

The scriphash of the output scriptPubKey.

• scriptpubkey

The locking script of the utxo as hex.

• spent

The transaction spending the utxo with the following keys:

• tx_pos

The zero-based index of the input in the transaction’s list of inputs. Null if utxo is unspent.

• tx_hash

The transaction ID. Null if utxo is unspent.

• height

The height the transaction was confirmed in. If it is unconfirmed, the value is 0 if all inputs are confirmed, and -1 otherwise. Null if utxo is unspent.

• spent

The transaction spending the utxo with the following keys:

• token_id

The token id as hex. Null if none.

• token_amount

The amount of token in utxo. Null if none.

• commitment

The token commitment. Null if none.

• token_bitfield

The token bitfield. Null if none.

Example Results

{
    "addresses": [
        "bchreg:qzpdwa6c69vwnlj8h7q72sff7nk4tm8mfvktd2hhud",
        "bchreg:zzpdwa6c69vwnlj8h7q72sff7nk4tm8mfv3p75e3r7"
    ],
    "amount": 100000000,
    "commitment": "",
    "height": 0,
    "scripthash": "4cb67fb08b4fd1b2f6b35cb7a785f65b6b00bbb34c84d982775dc20577dbc47f",
    "scriptpubkey": "76a91482d77758d158e9fe47bf81e54129f4ed55ecfb4b88ac",
    "spent": {
        "height": 0,
        "tx_hash": "39e0533673aab846837b9ca5959cc545a87c7be0f6f85a4b6cf2706599eb9fee",
        "tx_pos": 0
    },
    "status": "spent",
    "token_amount": 42,
    "token_bitfield": 16,
    "token_id": "a0482e92a868e389cba6ff0d75664389eb2194d4bc48cfb15bd4dec89bab51e9"
}

Function: blockchain.utxo.get(outpoint_hash)

Version added: Rostrum 7.0

Update Rostrum 8.1: Add group details and scriptpukey

outpoint_hash

Hash of utxo (hash of transaction idem + output index)

Result

A dictionary with the following keys:

• status

State of the utxo. A string that is "spent" or "unspent".

• height

The height the utxo was confirmed in. If it is unconfirmed, the value is 0 if all inputs are confirmed, and -1 otherwise.

• value

The output’s value in minimum coin units (satoshis).

• scripthash

The scriphash of the output scriptPubKey.

• scriptpubkey

The locking script of the utxo as hex.

• spent

The transaction spending the utxo with the following keys:

• tx_pos

The zero-based index of the input in the transaction’s list of inputs. Null if utxo is unspent.

• tx_hash

The transaction ID. Null if utxo is unspent.

• height

The height the transaction was confirmed in. If it is unconfirmed, the value is 0 if all inputs are confirmed, and -1 otherwise. Null if utxo is unspent.

• tx_idem

The transaction idem of the utxo.

• tx_pos

The output index of the utxo.

• group

The group ID as cashaddr. Null if none.

• token_id_hex

The group ID as hex. Null if none.

• group_quantity

The amount of group in utxo. Null if none.

• template_scripthash

The template scripthash. Null if not template type utxo.

• template_argumenthash

The template argumenthash. Null if not template type utxo.

Example Results

{
    "addresses": [
        "nexareg:nqtsq5g5zshfe4kt90x9l7s43v5ts86l4gptwxw07rysgtdr"
    ],
    "amount": 546,
    "group": "nexareg:tqex0rdvw0fy7j4308j3k3sqpnnqy6j825cl4evmazeutql6ycqqqne3ew470",
    "group_authority": 0,
    "group_quantity": 42,
    "height": -1,
    "scripthash": "8cfc801e08cbb086a42f4b3c698b9b64c0a60cdc4b0af07d2742ac6b1828f547",
    "scriptpubkey": "2032678dac73d24f4ab179e51b46000ce6026a475531fae59be8b3c583fa260000022a005114142e9cd6cb2bcc5ffa158b28b81f5faa02b719cf",
    "spent": {
        "height": null,
        "tx_hash": null,
        "tx_pos": null
    },
    "status": "unspent",
    "template_argumenthash": "142e9cd6cb2bcc5ffa158b28b81f5faa02b719cf",
    "template_scripthash": "pay2pubkeytemplate",
    "token_id_hex": "32678dac73d24f4ab179e51b46000ce6026a475531fae59be8b3c583fa260000",
    "tx_hash": "25958055aa367ca4f16824a3c14d2fe6a7b297f4147316fdeac05a5a91354027",
    "tx_idem": "ed35b780d602e50ff601d7d1b24a1d6d88a937923eef4fb7591300d41718b49a",
    "tx_pos": 0
}

cashaccount.query.name

BCH ONLY.

Requires that it has been enabled in rostrum with the cashaccount_activation_height parameter.

Returns the transactions registering a cashaccount at blockheight. Note that height is absolute blockheight and you need to add the cashaccount block modification value yourself.

The cashaccount block modification value for Bitcoin Cash is 563620.

For example, to lookup dagur#216, call blockchain.query.name("dagur", 216 + 563620)

Signature

Function BCH: cashaccount.query.name(name, height)

Version added: ROSTRUM ONLY. This function is a extension added to rostrum and may not be available on other electrum server implementations.

name

Cash account name

height

Block height for registration (without cashaccount offset subtracted)

Result

A dictionary with the following keys:

• blockhash

Block hash of the block that the cash account was confirmed in.

• height

Block height of the block that the cash account was confirmed in.

• tx

A hex string of the transaction containing the cash account.

Example Results

For query blockchain.query.name('dagur', 563836)

{
    'blockhash': '000000000000000003c73e50b9de6317c4d2b2ac5f3c1253b01e61a6e329219a',
    'height': 563836,
    'tx': '0100000001bca903bbc429218234857628b382e8aa8e3bfa74c5b59628ad053284e50bf6ac010000006b4830450221009bbd0a96ef5ef33e09c4fce7fafd2add714ebe05d87a9cb6c826b863d0e99225022039d77b8bd9c8067636e64d6f1aeeeeb8b816bbc875afd04cef9eb299df83b7d64121037a291b1a7f21b03b2a5120434b7a06b61944e0edc1337c76d737d0b5fa1c871fffffffff020000000000000000226a040101010105646167757215018c092ec2cbd842e89432c7c53b54db3a958c83a575f00d00000000001976a914dfdd3e914d73fee85ad40cd71430327f0404c15488ac00000000'
}

mempool.count

Return the number of transactions in the mempool.

Signature

Function: blockchain.mempool.count()

Version added: Rostrum 9.0

Result

Dictionary with mempool count

Example Results

{
    "count": 546
}

mempool.get

Fetch a list of transactions in the mempool

Signature

Function: blockchain.mempool.get(filter (optional))

• filter

  Filter what transactions are returned. Filter is a dictionary with the following options as keys:

  • scriptsig - Value hex string. Include transactions that partially matches scriptsig in inputs.
  • scriptpubkey - Value in hex. Include transaction that partially matches scriptpubkey in outputs.
  • operation - Set to 'union' to include results matching any filter; 'except' to include results matching all (default: 'except').

Version added: Rostrum 10.1

Version history: Rostrum 11: Added 'scriptpubkey' and 'operation'

Result

Dictionary with transaction list

Example Results

{
    "transactions":  ["6ba738f581968c915a097015fc32d4c951a222d8209a21b0163399bf57622027", "dbbe9a005b0f53eea5b63e3a4f5a36758cd736259d8036c39a4e5a3d7838b1a5"]
}

mempool.get_fee_histogram

Return a histogram of the fee rates paid by transactions in the memory pool, weighted by transaction size.

Signature

Function: mempool.get_fee_histogram()

Version added: 1.2

Result

The histogram is an array of [fee, vsize] pairs, where is the cumulative virtual size of mempool transactions with a fee rate in the interval [, ], and > .

Fee intervals may have variable size. The choice of appropriate intervals is currently not part of the protocol.

Example Result

[[12, 128812], [4, 92524], [2, 6478638], [1, 22890421]]

server.add_peer

A newly-started server uses this call to get itself into other servers\' peers lists. It sould not be used by wallet clients.

Signature

Function: server.add_peer(features)

Version added: 1.1

• features

  The same information that a call to the sender\'s server.features RPC call would return.

Result

A boolean indicating whether the request was tentatively accepted. The requesting server will appear in server.peers.subscribe when further sanity checks complete successfully.

server.banner

Return a banner to be shown in the Electrum console.

Signature

Function: server.banner()

Result

A string.

Example Result

"Welcome to Rostrum!"

server.donation_address

Return a server donation address.

Signature

Function: server.donation_address()

Result

A string.

Example Result

"1BWwXJH3q6PRsizBkSGm2Uw4Sz1urZ5sCj"

server.features

Return a list of features and services supported by the server.

Signature

Function: server.features()

Version changed: 1.4.2 hosts key is no longer required, but recommended.

Result

A dictionary of keys and values. Each key represents a feature or service of the server, and the value gives additional information.

The following features MUST be reported by the server. Additional key-value pairs may be returned.

• genesis_hash

  The hash of the genesis block. This is used to detect if a peer is connected to one serving a different network.

• hash_function

  The hash function the server uses for script hashing. The client must use this function to hash pay-to-scripts to produce script hashes to send to the server. The default is "sha256". "sha256" is currently the only acceptable value.

• server_version

  A string that identifies the server software. Should be the same as the result to the server.version RPC call.

• protocol_max

• protocol_min

  Strings that are the minimum and maximum Electrum protocol versions this server speaks. Example: "1.1".

• pruning

  An integer, the pruning limit. Omit or set to null if there is no pruning limit. Should be the same as what would suffix the letter p in the IRC real name.

The following features are RECOMMENDED that be reported by the servers.

• hosts

  A dictionary, keyed by host name, that this server can be reached at. If this dictionary is missing, then this is a way to signal to other servers that while this host is reachable, it does not wish to peer with other servers. A server SHOULD stop peering with a peer if it sees the hosts dictionary for its peer is empty and/or no longer contains the expected route (e.g. hostname). Normally this dictionary will only contain a single entry; other entries can be used in case there are other connection routes (e.g. Tor).

  The value for a host is itself a dictionary, with the following optional keys:

  • ssl_port

    An integer. Omit or set to null if SSL connectivity is not provided.

  • tcp_port

    An integer. Omit or set to null if TCP connectivity is not provided.

  • ws_port

    An integer. Omit or set to null if Web Socket () connectivity is not provided.

  • wss_port

    An integer. Omit or set to null if Web Socket Secure () connectivity is not provided.

  A server should ignore information provided about any host other than the one it connected to.

Example Result

{
    "genesis_hash": "000000000933ea01ad0ee984209779baaec3ced90fa3f408719526f8d77f4943",
    "hosts": {"14.3.140.101": {"tcp_port": 51001, "ssl_port": 51002}},
    "protocol_max": "1.0",
    "protocol_min": "1.0",
    "pruning": null,
    "server_version": "ElectrumX 1.0.17",
    "hash_function": "sha256"
}

server.peers.subscribe

Return a list of peer servers. Despite the name this is not a subscription and the server must send no notifications.

Signature

Function: server.peers.subscribe()

Result

An array of peer servers, each returned as a 3-element array. For example:

["107.150.45.210",
 "e.anonyhost.org",
 ["v1.0", "p10000", "t", "s995"]]

The first element is the IP address, the second is the host name (which might also be an IP address), and the third is a list of server features. Each feature and starts with a letter. \'v\' indicates the server maximum protocol version, \'p\' its pruning limit and is omitted if it does not prune, \'t\' is the TCP port number, and \'s\' is the SSL port number. If a port is not given for \'s\' or \'t\' the default port for the coin network is implied. If \'s\' or \'t\' is missing then the server does not support that transport.

server.ping

Ping the server to ensure it is responding, and to keep the session alive. The server may disconnect clients that have sent no requests for roughly 10 minutes.

Signature

Function: server.ping() :::

Version added: 1.2 :::

Result

Returns null.

server.version

Identify the client to the server and negotiate the protocol version. Only the first server.version{.interpreted-text role="func"} message is accepted.

Signature

Function: server.version(client_name=\"\", protocol_version=\"1.4\")

• client_name

  A string identifying the connecting client software.

• protocol_version

  An array [protocol_min, protocol_max], each of which is a string. If protocol_min and protocol_max are the same, they can be passed as a single string rather than as an array of two strings, as for the default value.

The server should use the highest protocol version both support:

version = min(client.protocol_max, server.protocol_max)

If this is below the value:

max(client.protocol_min, server.protocol_min)

then there is no protocol version in common and the server must close the connection. Otherwise it should send a response appropriate for that protocol version.

Result

An array of 2 strings:

[server_software_version, protocol_version]

identifying the server and the protocol version that will be used for future communication.

Example:

server.version("Electron Cash 3.3.6", ["1.2", "1.4"])

Example Result:

["Rostrum 2.2.3", "1.4"]

token.address.get_balance

Return the confirmed and unconfirmed balances of tokens in a Bitcoin Cash or Nexa address.

Signature

Function: token.address.get_balance(address, cursor (optional), token (optional))

Version added: Rostrum 6.0

• address

  Address encoded as a CashAddr string (with or without prefix). Legacy addresses (base58) are also supported.

• cursor

  Placeholder for pagination.

• token

  Token ID as cashaddr encoded or hexadecimal string. If provided, will filter out transactions that do not include token.

Result

See token.scripthash.get_balance.

token.address.get_history

Return the confirmed and unconfirmed token history of a Nexa or Bitcoin Cash address.

Signature

Function: token.address.get_history(address, cursor (optional), token (optional), filter { "from_height": 0, ...} (optional))

Version added: Rostrum 6.0

• address

  Address encoded as a CashAddr string (with or without prefix). Legacy addresses (base58) are also supported.

• cursor

  Placeholder for pagination.

• token

  Token ID as cashaddr encoded or hexadecimal string. If provided, will filter out transactions that do not include token.

• filter

  Filter dict for what transactions/utxos are included in the result. Valid filters are:

  • from_height - Include from the given block height, inclusive (default: 0).
  • to_height - Include up to the given block height, exclusive. Use -1 to include mempool (default: -1).

Result

See token.scripthash.get_history

token.address.get_mempool

Return the unconfirmed token transactions of a Nexa or Bitcoin Cash address.

Signature

Function: token.address.get_mempool(address, cursor (optional), token (optional), filter { "from_height": 0, ...} (optional))

Version added: Rostrum 6.0

• address

  Address encoded as a CashAddr string (with or without prefix). Legacy addresses (base58) are also supported.

• cursor

  Placeholder for pagination.

• token

  Token ID as cashaddr encoded or hexadecimal string. If provided, will filter out transactions that do not include token.

• filter

  Filter dict for what transactions/utxos are included in the result. Valid filters are:

  • offset - Skip the first n elements (default: 0)
  • limit - Return at most n elements. Use '0' for no limit (default: 0)

Result

As for token.scripthash.get_mempool

token.address.listunspent

Return an list of token UTXOs sent to a Nexa or Bitcoin Cash address.

Signature

Function: token.address.listunspent(address, cursor (optional), token (optional))

Version added: Rostrum 6.0

• address

  Address encoded as a CashAddr string (with or without prefix). Legacy addresses (base58) are also supported.

• cursor

  Placeholder for pagination.

• token

  Token ID as cashaddr encoded or hexadecimal string. If provided, will filter out transactions that do not include token.

Result

As for token.scripthash.listunspent

token.genesis.info

Info from token creation transaction.

Bitcoin CashNexa

Signature

Function: token.genesis.info(token)

Version added: Rostrum 6.0

• token

  Token ID as a hexadecimal string.

Result Example

    {
        "tx_hash": "503a3af8363d506c18d99efe538122947911038b5b4f8a0d62d6127e548bb13c",
        "height": 102,
        "bcmr": {
            "hash": "cef3a7be7f95f3c27f393c74c99a2c1f1f8c658d3cd973c5ff3c266c7133aa38",
            "uris": [
                "https://example.org/bcmr.json"
            ]
        },
        "crc20": {
            "symbol": "SYMBOL",
            "name": "Token Name"
            "decimals": 8,
            "genesis_out": "f8a0d62d6127e548bb13c503a3af8363d506c18d99efe538122947911038b5b4"
        }
    }

Signature

Function: token.genesis.info(token)

Version added: Rostrum 6.0

• token

  Token ID as cashaddr encoded or hexadecimal string.

Result

Dictionary of token details.

Note: The decimal_places can be null, this happens if token description has encoded a value for decimal places, but the encoded value is invalid (not a number, or a number larger than 18 decimal places). If decimal_places is not encoded into the token description, this implies 0.

Note: Genesis must be confirmed for rostrum to detect it.

Result Example

    {
        "document_hash": "cef3a7be7f95f3c27f393c74c99a2c1f1f8c658d3cd973c5ff3c266c7133aa38",
        "document_url": "https://example.org",
        "decimal_places": 10,
        "height": 102,
        "name": "TEST",
        "ticker": "TEST",
        "group: "nexareg:tzfl3s4qp4hzvjf2t6cy2eeyc67896pyflhlx6na382t2sapmyqqq3z44qjuc",
        "token_id_hex": 93f8c2a00d6e26492a5eb0456724c6bc72e8244feff36a7d89d4b543a1d90000,
        "txid": "503a3af8363d506c18d99efe538122947911038b5b4f8a0d62d6127e548bb13c",
        "txidem": "316862b66bf34ab6a7c24f6714e91ced836b50b540a5f40cf6f94499f14d322d"
        "op_return": ""6a0438564c05065449434b455209536f6d65204e616d651368747470733a2f2f6578616d706c652e6f726720ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff5b
    }

token.nft.list

Return list of all NFT's minted from a specified parent token.

Bitcoin CashNexa

Signature

Function: token.nft.list(token, cursor (optional))

Version added: Rostrum 7.0

• token

  Token ID as cashaddr encoded or hexadecimal string. If provided, will filter out transactions that do not include token.

• cursor

  Placeholder for pagination.

Result

A list of all NFT's minted from given token ID.

• nft

List of NFT dictionaries with the following keys:

• token_id

The token identifier as a hexadecimal string

• commitment

  The NFT commitment as a hexadecimal string

• cursor

  Null if it was the last (or the full) result set. If there are more results to fetch, call the method again with this cursor value to get next set of results.

Result Examples

{
"nft": [
    {
    "token_id": "9fbed79a1e970343fcd39f4a2d830a6bde6de0754ed2da70f489d0303ed558ec6bca82c1",
    "commitment": "c0754a"
    },
],
"cursor": null
}

Signature

Function: token.nft.list(token, cursor (optional))

Version added: Rostrum 7.0

• token

  Token ID as cashaddr encoded or hexadecimal string. If provided, will filter out transactions that do not include token.

• cursor

  Placeholder for pagination.

Result

A list of all NFT's minted from parent ID.

• nft

List of NFT dictionaries with the following keys:

• group

The token identifier as cashaddr

• token_id_hex

The token identifier as a hexadecimal string

• cursor

  Null if it was the last (or the full) result set. If there are more results to fetch, call the method again with this cursor value to get next set of results.

Result Examples

{
"nft": [
    {
    "group": "nexareg:tzfl3s4qp4hzvjf2t6cy2eeyc67896pyflhlx6na382t2sapmyqqq3z44qjuc",
    "token_id_hex": "9fbed79a1e970343fcd39f4a2d830a6bde6de0754ed2da70f489d0303ed558ec6bca82c1"
    },
],
"cursor": null
}

token.scripthash.get_balance

Return the confirmed and unconfirmed balances of tokens in a script hash. Token is optional, if provided, will filter on token.

Signature

Function: token.scripthash.get_balance(scripthash, cursor (optional), token (optional))

Version added: Rostrum 6.0

• scripthash

  The script hash as a hexadecimal string.

• cursor

  If the address has a large amount of tokens, the results may be paginated. The cursor is null if this result was the last (or the full) result set. If there are more results to fetch, call the method again with this cursor value to get next set of results.

• token (optional)

  Token ID as cashaddr encoded or hexadecimal string. If provided, will filter out transactions that do not include token.

Result

Dictionary of keys confirmed and unconfirmed. The value of each is dict of tokens and the amount in given scripthash.

Result Example

{
  "confirmed": {
    "3c469e9d6c5875d37a43f353d4f88e61fcf812c66eee3457465a40b0da4153e0": 103873966
  },
  "unconfirmed": {
    "3c469e9d6c5875d37a43f353d4f88e61fcf812c66eee3457465a40b0da4153e0": 236844
  },
  "cursor": "t1S7vY94La"
}

token.scripthash.get_history

Return the confirmed and unconfirmed token history of a script hash

Signature

Function: token.scripthash.get_history(scripthash, cursor (optional), token (optional), { "from_height": 0, ...} (optional))

Version added: Rostrum 6.0.

• scripthash

  The script hash as a hexadecimal string.

• cursor

  Placeholder for pagination.

• token

  Token ID as cashaddr encoded or hexadecimal string. If provided, will filter out transactions that do not include token.

• filter

  Filter dict for what transactions/utxos are included in the result. Valid filters are:

  • from_height - Include from the given block height, inclusive (default: 0).
  • to_height - Include up to the given block height, exclusive. Use -1 to include mempool (default: -1).

Result

A dictionary with a cursor and a list of confirmed transactions in blockchain order, including mempool. Each confirmed transaction is an array with the following keys:

• height

  The integer height of the block the transaction was confirmed in.

• tx_hash

  The transaction hash in hexadecimal.

See token.scripthash.get_mempool for how mempool transactions are returned.

If the cursor is non-null, this denotes that the history retuned is incomplete and suggests the client call the same query again with cursor provided for continuation of history. If cursor is null, it denotes the latest history entry is provided in current response.

Result Examples

{
  "transactions": [
  {
    "height": 200004,
    "tx_hash": "acc3758bd2a26f869fcc67d48ff30b96464d476bca82c1cd6656e7d506816412"
  },
  {
    "height": 215008,
    "tx_hash": "f3e1bf48975b8d6060a9de8884296abb80be618dc00ae3cb2f6cee3085e09403"
  {,
  {
    "fee": 20000,
    "height": 0,
    "tx_hash": "9fbed79a1e970343fcd39f4a2d830a6bde6de0754ed2da70f489d0303ed558ec"
  }],
  "cursor": "t1S7vY94La"
}

token.scripthash.get_mempool

Return the unconfirmed token transactions of a script hash.

Signature

Function: token.scripthash.get_mempool(scripthash, cursor (optional), token (optional))

Version added: Rostrum 6.0

• scripthash

  The script hash as a hexadecimal string.

• cursor (optional)

  Null or string. If null, indicates that all histoy is requested. If a cursor is provided from an earlier call, history is continued from last transaction in earlier call.

• token (optional)

• Token ID as cashaddr encoded or hexadecimal string. If provided, will filter out transactions that do not include token.

Result

A dictionary with a transaction list of mempool transactions in arbitrary order. Each mempool transaction is a dictionary with the following keys:

• height

  0 if all inputs are confirmed, and -1 otherwise.

• tx_hash

  The transaction hash in hexadecimal.

• fee

  The transaction fee in minimum coin units (satoshis).

• cursor

  Null if it was the last (or the full) result set. If there are more results to fetch, call the method again with this cursor value to get next set of results.

Result Example

{
    "transactions": [
    {
        "tx_hash": "45381031132c57b2ff1cbe8d8d3920cf9ed25efd9a0beb764bdb2f24c7d1c7e3",
        "height": 0,
        "fee": 24310
    }
    ],
    "cursor": "t1S7vY94La"
]

token.scripthash.listunspent

Return an list of token UTXOs sent to a script hash.

Bitcoin CashNexa

Signature

Function: token.scripthash.listunspent(scripthash, cursor (optional), token (optional))

Version added: Rostrum 6.0

Updated in: Rostrum 10.1 -- Added 'commitment' to result.

• scripthash

  The script hash as a hexadecimal string.

• cursor (optional)

  Null or string. If null, indicates that full list of unspent is requested.

• token (optional)

• Token ID as hexadecimal string. If provided, will filter out transactions that do not include token.

Result

A list of unspent token outputs. This function takes the mempool into account. Mempool transactions paying to the address are included at the in an undefined order. Any output that is spent in the mempool does not appear.

• unspent

List of each output in a dictionary with the following keys:

• height

The integer height of the block the transaction was confirmed in. 0 if the transaction is in the mempool.

• tx_pos

The zero-based index of the output in the transaction's list of outputs.

• tx_hash

The output's transaction hash as a hexadecimal string. The hash is little-endian encoded (same as bitcoind RPC).

• value

The output's value in minimum coin units (satoshis).

• token_id

The token identifier as a hexadecimal string (aka category)

• token_amount

The token amount in utxo

• commitment

If the output holds an commitment, the commitment as a hexadecimal string.

• cursor

  Null if it was the last (or the full) result set. If there are more results to fetch, call the method again with this cursor value to get next set of results.

Result Example

{
  "unspent": [
    {
      "tx_pos": 0,
      "value": 546,
      "tx_hash": "9f2c45a12db0144909b5db269415f7319179105982ac70ed80d76ea79d923ebf",
      "height": 437146,
      "token_id": "5c087b9f1824d38c14e42d84c7bb9502da4a63b81cdb9b49e71bbe3b46c83111",
      "token_amount": 42,
      "commitment": "f0a3"
    },
    {
      "tx_pos": 0,
      "value": 546,
      "tx_hash": "3d2290c93436a3e964cfc2f0950174d8847b1fbe3946432c4784e168da0f019f",
      "height": 441696,
      "token_id": "8f6bda419cc2181a201731973aa3f965d79ea10da7bf3c23fd9b61dbf9e3dca7",
      "token_amount": 11,
    }
  ],
  "cursor": "201731973aa3f"
}

Signature

Function: token.scripthash.listunspent(scripthash, cursor (optional), token (optional))

Version added: Rostrum 6.0

• scripthash

  The script hash as a hexadecimal string.

• cursor (optional)

  Null or string. If null, indicates that full list of unspent is requested.

• token (optional)

• Token ID as cashaddr encoded or hexadecimal string. If provided, will filter out transactions that do not include token.

Result

A list of unspent token outputs. This function takes the mempool into account. Mempool transactions paying to the address are included at the in an undefined order. Any output that is spent in the mempool does not appear.

• unspent

List of each output in a dictionary with the following keys:

• height

The integer height of the block the transaction was confirmed in. 0 if the transaction is in the mempool.

• tx_pos

The zero-based index of the output in the transaction's list of outputs.

• tx_hash

The output's transaction hash as a hexadecimal string. The hash is little-endian encoded (same as bitcoind RPC).

• value

The output's value in minimum coin units (satoshis).

• token_id_hex

The token identifier as a hexadecimal string

• group

The token identifier as cashaddr

• token_amount

The token amount in utxo

• outpoint_hash

Hash of utxo (hash of transaction idem + output index)

• cursor

  Null if it was the last (or the full) result set. If there are more results to fetch, call the method again with this cursor value to get next set of results.

Result Example

{
  "unspent": [
    {
      "tx_pos": 0,
      "value": 546,
      "tx_hash": "9f2c45a12db0144909b5db269415f7319179105982ac70ed80d76ea79d923ebf",
      "height": 437146,
      "token_id_hex": "5c087b9f1824d38c14e42d84c7bb9502da4a63b81cdb9b49e71bbe3b46c83111",
      "group": "nexareg:tzfl3s4qp4hzvjf2t6cy2eeyc67896pyflhlx6na382t2sapmyqqq3z44qjuc",
      "token_amount": 42,
      "outpoint_hash": "65a867e6d7da3f3986f8fe67fda311a60ac5c9b43e9f28326646f0d3f10381aa"
    },
    {
      "tx_pos": 0,
      "value": 546,
      "tx_hash": "3d2290c93436a3e964cfc2f0950174d8847b1fbe3946432c4784e168da0f019f",
      "height": 441696,
      "token_id_hex": "8f6bda419cc2181a201731973aa3f965d79ea10da7bf3c23fd9b61dbf9e3dca7",
      "group": "nexareg:tzfl3s4qp4hzvjf2t6cy2eeyc67896pyflhlx6na382t2sapmyqqq3z44qjuc",
      "token_amount": 11,
      "outpoint_hash": "2af3d1897865d2c4d265ba4c6da9720f29ed471653722a8093b56ab208bcfa42"
    }
  ],
  "cursor": "201731973aa3f"
}

token.transaction.get_history

Bitcoin CashNexa

Return all confirmed and unconfirmed token transaction history of a given token.

If no commitment is provided, full history, including all commitments (NFTs) is returned. To exclude all NFT's, pass empty string to commitment. Note that this will also exclude genesis if it mints NFT.

Signature

Function: token.transaction.get_history(token, cursor (optional), commitment (optional))

Version added: Rostrum 6.0

• token

  Token ID as cashaddr encoded or hexadecimal string. If provided, will filter out transactions that do not include token.

• cursor

  Placeholder for pagination.

• commitment (optional)

  Null or hexadecimal string. If specified, the history for the given NFT is fetched.

Return all confirmed and unconfirmed token transaction history of a given token.

When a parent Token ID is passed, subgroup transactions are not included.

Signature

Function: token.transaction.get_history(token, cursor (optional))

Version added: Rostrum 6.0

• token

  Token ID as cashaddr encoded or hexadecimal string. If provided, will filter out transactions that do not include token.

• cursor

  Placeholder for pagination.

Result

A list of unconfirmed and confirmed transactions. Unconfirmed transactions are returned first in no specific order. Confirmed transactions are returned by latest confirmed first.

• history

List of transaction, dictionaries with the following keys:

• height

The integer height of the block the transaction was confirmed in.

• tx_hash

The transaction hash in hexadecimal.

• cursor

  Null if it was the last (or the full) result set. If there are more results to fetch, call the method again with this cursor value to get next set of results.

Result Examples

{
  "history": [
    {
      "height": 0,
      "tx_hash": "9fbed79a1e970343fcd39f4a2d830a6bde6de0754ed2da70f489d0303ed558ec"
    },
    {
      "height": 200004,
      "tx_hash": "acc3758bd2a26f869fcc67d48ff30b96464d476bca82c1cd6656e7d506816412"
    },
    {
      "height": 215008,
      "tx_hash": "f3e1bf48975b8d6060a9de8884296abb80be618dc00ae3cb2f6cee3085e09403"
    },
  ],
  "cursor": "2012d830a6a3f"
}