Protocol Methods¶

blockchain.address.get_balance¶

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

Signature

blockchain.address.get_balance(address[, token_filter])¶

New in version 1.4.3.

Changed in version 1.5.0: Added optional arg: token_filter (BCH only)

address

The address as a Cash Address string (with or without prefix, case insensitive). Some server implementations do not support Legacy (base58) addresses and are not required to do so by this specification. However, Fulcrum does support both Legacy and Cash Address encodings.

token_filter (optional, BCH only)

A string, one of: "include_tokens", "exclude_tokens" or "tokens_only". This controls whether the balance also includes CashToken-containing UTXOs, whether to exclude them, or whether to return the balance for CashToken UTXOs only, respectively.

The default is "exclude_tokens" if the client negotiated version 1.4.x or below with the server. If the client negotiated version 1.5.0 or above, the default is "include_tokens".

Result

See blockchain.scripthash.get_balance().

blockchain.scripthash.get_first_use¶

Retrieve information on the first occurrence of a Bitcoin Cash address on the block chain.

Signature

blockchain.address.get_first_use(address)¶

New in version 1.5.2.

address

The address as a Cash Address string (with or without prefix, case insensitive). Some server implementations do not support Legacy (base58) addresses and are not required to do so by this specification. However, Fulcrum does support both Legacy and Cash Address encodings.

Result

As for blockchain.scripthash.get_first_use().

blockchain.address.get_history¶

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

Signature

blockchain.address.get_history(address, from_height=0, to_height=-1)¶

New in version 1.4.3.

Changed in version 1.5.1: Allow pagination of history (added from_height, to_height)

address

The address as a Cash Address string (with or without prefix, case insensitive). Some server implementations do not support Legacy (base58) addresses and are not required to do so by this specification. However, Fulcrum does support both Legacy and Cash Address encodings.

from_height

The first block height (inclusive) of the interval the client is interested in. A non-negative integer. Optional.

to_height

The last block height (exclusive) of the interval the client is interested in. A non-negative integer, or -1. Optional. A value of -1 means that the interval extends to the chaintip and also includes unconfirmed/mempool transactions (otherwise mempool txs are not included). from_height <= to_height must hold (for the purposes of this inequality and others here, treat a value of -1 as infinity).

Result

As for blockchain.scripthash.get_history().

blockchain.address.get_mempool¶

Return the unconfirmed transactions of a Bitcoin Cash address.

Signature

blockchain.address.get_mempool(address)¶

New in version 1.4.3.

address

The address as a Cash Address string (with or without prefix, case insensitive). Some server implementations do not support Legacy (base58) addresses and are not required to do so by this specification. However, Fulcrum does support both Legacy and Cash Address encodings.

Result

As for blockchain.scripthash.get_mempool().

blockchain.address.get_scripthash¶

Translate a Bitcoin Cash 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

blockchain.address.get_scripthash(address)¶

New in version 1.4.3.

address

The address as a Cash Address string (with or without prefix, case insensitive). Some server implementations do not support Legacy (base58) addresses and are not required to do so by this specification. However, Fulcrum does support both Legacy and Cash Address encodings.

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 address.

Signature

blockchain.address.listunspent(address[, token_filter])¶

New in version 1.4.3.

Changed in version 1.5.0: Added optional arg: token_filter (BCH only). token_data may appear in the result object if the UTXO contains a CashToken (BCH only).

address

The address as a Cash Address string (with or without prefix, case insensitive). Some server implementations do not support Legacy (base58) addresses and are not required to do so by this specification. However, Fulcrum does support both Legacy and Cash Address encodings.

token_filter (optional, BCH only)

A string, one of: "include_tokens", "exclude_tokens" or "tokens_only". This controls whether the results also include CashToken-containing UTXOs, whether to exclude them, or whether to return CashToken UTXOs only, respectively.

The default is "exclude_tokens" if the client negotiated version 1.4.x or below with the server. If the client negotiated version 1.5.0 or above, the default is "include_tokens".

Result

As for blockchain.scripthash.listunspent().

blockchain.address.unsubscribe¶

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

Signature

blockchain.address.unsubscribe(address)¶

New in version 1.4.3.

address

The address as a Cash Address string (with or without prefix, case insensitive). Some server implementations do not support Legacy (base58) addresses and are not required to do so by this specification. However, Fulcrum does support both Legacy and Cash Address encodings.

Result

Returns true if the address was previously 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.header¶

Return the block header at the given height.

Signature

blockchain.block.header(height, cp_height=0)¶

New in version 1.3.

Changed in version 1.4: cp_height parameter added

Changed in version 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.

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.headers¶

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

Signature

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

New in version 1.2.

Changed in version 1.4: cp_height parameter added

Changed in version 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 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

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 daemon does not have enough information to make an estimate, the integer -1 is returned.

Example Result

0.00101079

blockchain.header.get¶

Retrieve a block header by its hash (or, optionally, its height).

Signature

blockchain.header.get(block_hash)¶

New in version 1.5.2.

block_hash

A 64-character hexadecimal string indicating the block hash of the block for which to retrieve the header. Optionally, this can also be a numeric value and in that case it will be interpreted as a block height.

Result

The height and header of the requested block. The result is a dictionary with two keys:

height

The height of the header, an integer.

hex

The binary header as a hexadecimal string.

Example Result

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

blockchain.headers.get_tip¶

Get the latest block’s height and header.

Signature

blockchain.headers.get_tip()¶

New in version 1.5.0.

Result

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

height

The height of the header, an integer.

hex

The binary header as a hexadecimal string.

Example Result

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

blockchain.headers.unsubscribe¶

Undoes the effects of a previous call to blockchain.headers.subscribe(), that is to say: unsubscribe from receiving block header notifications.

Signature

blockchain.headers.unsubscribe()¶

New in version 1.5.0.

Result

Returns true if the client was previously subscribed to receive block header notifications, otherwise false.

blockchain.relayfee¶

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

Signature

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.reusable.get_history¶

Return the confirmed transactions for an rpa_prefix.

Deprecated

This function is provided for compatibility with existing clients. Please use blockchain.rpa.get_history() in new code instead.

Signature

blockchain.reusable.get_history(from_height, count, rpa_prefix)¶

New in version 1.5.3.

Availability

Only provided by servers that advertise as having the RPA index enabled. That is, servers that have the "rpa" key present in their server.features() dictionary.

blockchain.reusable.get_mempool¶

Return the unconfirmed (mempool) transactions for an rpa_prefix.

Deprecated

This function is provided for compatibility with existing clients. Please use blockchain.rpa.get_mempool() in new code instead.

Signature

blockchain.reusable.get_mempool(rpa_prefix)¶

New in version 1.5.3.

Availability

Only provided by servers that advertise as having the RPA index enabled. That is, servers that have the "rpa" key present in their server.features() dictionary.

blockchain.rpa.get_history¶

Return the confirmed history of an rpa_prefix.

Signature

blockchain.rpa.get_history(rpa_prefix, from_height, to_height=-1)¶

New in version 1.5.3.

rpa_prefix

The RPA prefix for which to scan for history, as a hexadecimal string, e.g. "ff" or "ab" or "abc". Note that this prefix must respect the server’s server.features() prefix_bits_min (default: 8), so if the server is configured with 8, then "ff" will work but "f" will not, however if it is configured with 4, then "f" (a single nybble as a prefix) will work.

from_height

The first block height (inclusive) of the interval the client is interested in. A non-negative integer.

to_height

The last block height (exclusive) of the interval the client is interested in. A non-negative integer, or -1. Optional. A value of -1 means that the interval extends to the chaintip, or up to the server’s server.features() history_block_limit (default: 60), whichever is less. from_height <= to_height must hold (for the purposes of this inequality and others here, treat a value of -1 as infinity).

Availability

Only provided by servers that advertise as having the RPA index enabled. That is, servers that have the "rpa" key present in their server.features() dictionary.

Result

A list of confirmed transactions in blockchain order. Note that unlike blockchain.scripthash.get_history(), no mempool transactions are ever returned by this call. For mempool RPA transactions, use blockchain.rpa.get_mempool(). 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.

Result Examples

[
  {
    "height": 825000,
    "tx_hash": "acc3758bd2a26f869fcc67d48ff30b96464d476bca82c1cd6656e7d506816412"
  },
  {
    "height": 825008,
    "tx_hash": "f3e1bf48975b8d6060a9de8884296abb80be618dc00ae3cb2f6cee3085e09403"
  }
]

blockchain.rpa.get_mempool¶

Return the unconfirmed (mempool) transactions for an rpa_prefix.

Signature

blockchain.rpa.get_mempool(rpa_prefix)¶

New in version 1.5.3.

rpa_prefix

The RPA prefix for which to scan for mempool transactions, as a hexadecimal string, e.g. "ff" or "ab" or "abc". Note that this prefix must respect the server’s server.features() prefix_bits_min (default: 8), so if the server is configured with 8, then "ff" will work but "f" will not, however if it is configured with 4, then "f" (a single nybble as a prefix) will work.

Availability

Only provided by servers that advertise as having the RPA index enabled. That is, servers that have the "rpa" key present in their server.features() dictionary.

Result

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

height

0 for transactions with no unconfirmed parents, -1 for transactions that have unconfirmed parents in the mempool.

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
  },
  {
    "tx_hash": "354a24a255488c28c9cdfe7134d1b86bb99bbcca2bc7996b9613990bed384cc8",
    "height": -1,
    "fee": 185
  }
]

blockchain.scripthash.get_balance¶

Return the confirmed and unconfirmed balances of a script hash.

Signature

blockchain.scripthash.get_balance(scripthash[, token_filter])¶

New in version 1.1.

Changed in version 1.5.0: Added optional arg: token_filter (BCH only)

scripthash

The script hash as a hexadecimal string.

token_filter (optional, BCH only)

A string, one of: "include_tokens", "exclude_tokens" or "tokens_only". This controls whether the balance also includes CashToken-containing UTXOs, whether to exclude them, or whether to return the balance for CashToken UTXOs only, respectively.

The default is "exclude_tokens" if the client negotiated version 1.4.x or below with the server. If the client negotiated version 1.5.0 or above, the default is "include_tokens".

Result

A dictionary with keys confirmed and unconfirmed. The value of each is the appropriate balance in satoshis. Note that on BCH, be sure to select the appropriate token_filter argument to retrieve the balance either including or omitting tokens or for tokens only.

Result Example

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

blockchain.scripthash.get_first_use¶

Retrieve information on the first occurrence of a script hash on the block chain.

Note: On block chians such as BTC that use natural ordering, the first occurrence of any script hash will always be it appearing in an output of a transaction (since an address must receive funds before it can spend them). For block chains such as Bitcoin Cash, this is not always the case due to CTOR (txid based sorting of block transactions).

Signature

blockchain.scripthash.get_first_use(scripthash)¶

New in version 1.5.2.

scripthash

The script hash as a hexadecimal string.

Result

If the script hash in question does not appear either on the block chain or in the mempool, then null is returned. Otherwise, a dictionary containing the following keys:

block_hash

The block hash of the block where this script hash first appears, as a hexadecimal string. If this script hash first appears in the mempool, then this will be all zeroes, e.g. 64 hexadecimal 0 digits.

height

The integer height of the block where this script hash first appears. If this script hash first appears in the mempool, then this will be 0.

Note: Unlike other protocol methods (such as blockchain.scripthash.get_mempool()), 0 is always used here for any mempool transaction irrespective of whether it has any unconfirmed parents or not.

tx_hash

The transaction hash where this script hash first appears, in hexadecimal.

Note: For multiple mempool transactions referencing the same script hash, an unspecified transaction will be arbitrarily chosen and it may not always be the first one that appeared in the mempool for this script hash.

Result Examples

{
  "block_hash": "000000000000032e1219acd8cdda073f5cbb42a216fede788ad4b555e7969a26",
  "height": 200004,
  "tx_hash": "acc3758bd2a26f869fcc67d48ff30b96464d476bca82c1cd6656e7d506816412"
}

{
  "block_hash": "0000000000000000000000000000000000000000000000000000000000000000",
  "height": 0,
  "tx_hash": "9fbed79a1e970343fcd39f4a2d830a6bde6de0754ed2da70f489d0303ed558ec"
}

blockchain.scripthash.get_history¶

Return the confirmed and unconfirmed history of a script hash.

Signature

blockchain.scripthash.get_history(scripthash, from_height=0, to_height=-1)¶

New in version 1.1.

Changed in version 1.5.1: Allow pagination of history (added from_height, to_height)

scripthash

The script hash as a hexadecimal string.

from_height

The first block height (inclusive) of the interval the client is interested in. A non-negative integer. Optional.

to_height

The last block height (exclusive) of the interval the client is interested in. A non-negative integer, or -1. Optional. A value of -1 means that the interval extends to the chaintip and also includes unconfirmed/mempool transactions (otherwise mempool txs are not included). from_height <= to_height must hold (for the purposes of this inequality and others here, treat a value of -1 as infinity).

Result

A list of confirmed transactions in blockchain order, with the output of blockchain.scripthash.get_mempool() appended to the list (mempool is appended only if to_height is -1). 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.

Note that as of Fulcrum 1.8.0 the transaction history for a script hash also includes transactions that involve sending/receiving CashTokens to/from that script hash.

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.

Signature

blockchain.scripthash.get_mempool(scripthash)¶

New in version 1.1.

scripthash

The script hash as a hexadecimal string.

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).

Note that as of Fulcrum 1.8.0 the mempool transactions for a script hash also include transactions that involve sending/receiving CashTokens to/from that script hash.

Result Example

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

blockchain.scripthash.listunspent¶

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

Signature

blockchain.scripthash.listunspent(scripthash[, token_filter])¶

New in version 1.1.

Changed in version 1.5.0: Added optional arg: token_filter (BCH only). token_data may appear in the result object if the UTXO contains a CashToken (BCH only).

scripthash

The script hash as a hexadecimal string.

token_filter (optional, BCH only)

A string, one of: "include_tokens", "exclude_tokens" or "tokens_only". This controls whether the results also include CashToken-containing UTXOs, whether to exclude them, or whether to return CashToken UTXOs only, respectively.

The default is "exclude_tokens" if the client negotiated version 1.4.x or below with the server. If the client negotiated version 1.5.0 or above, the default is "include_tokens".

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.

token_data (optional, BCH only)

A dictionary encapsulating the CashToken data for this output. This key will be missing from the dictionary if the unspent output does not have any token data on it.

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.

value

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

Result Example

[
  {
    "height": 37146,
    "tx_hash": "9f2c45a12db0144909b5db269415f7319179105982ac70ed80d76ea79d923ebf",
    "tx_pos": 0,
    "value": 45318048
  },
  {
    "height": 41696,
    "tx_hash": "3d2290c93436a3e964cfc2f0950174d8847b1fbe3946432c4784e168da0f019f",
    "tx_pos": 0,
    "value": 919195
  },
  {
    "height": 126184,
    "token_data": {
      "amount": "1000000",
      "category": "8fd6a2f713beaa5907a776b8b3060cddd1c6ff0588554c2364698ae271321ce9",
      "nft": {
        "capability": "minting",
        "commitment": "f00fd00fb33f"
       }
    },
    "tx_hash": "87489c43bae69c297bbaf65276573b0001c20c647a3d54d2842a4425ff87bacc",
    "tx_pos": 1,
    "value": 1000000
  },
  {
    "height": 0,
    "tx_hash": "42f83727115dc7e38b1311aae9c516d9956c16f6017149c9d4a98cc5e738952a",
    "tx_pos": 7,
    "value": 99999815
  }
]

blockchain.scripthash.unsubscribe¶

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

Signature

blockchain.scripthash.unsubscribe(scripthash)¶

New in version 1.4.2.

scripthash

The script hash as a hexadecimal string.

Result

Returns true if the scripthash was previously 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

blockchain.transaction.broadcast(raw_tx)¶

Changed in version 1.1: errors returned as JSON RPC errors rather than as a result.

raw_tx

The raw transaction as a hexadecimal string.

Result

The transaction hash as a hexadecimal string.

Note protocol version 1.0 (only) does not respond according to the JSON RPC specification if an error occurs. If the daemon rejects the transaction, the result is the error message string from the daemon, as if the call were successful. The client needs to determine if an error occurred by comparing the result to the expected transaction hash.

Result Examples

"a76242fce5753b4212f903ff33ac6fe66f2780f34bdb4b33b175a7815a11a98e"

Protocol version 1.0 returning an error as the result:

"258: txn-mempool-conflict"

blockchain.transaction.dsproof.get¶

Returns information on a double-spend proof. The query can be by either tx_hash or dspid.

Signature

blockchain.transaction.dsproof.get(hash)¶

New in version 1.4.5.

hash

The transaction hash (or dspid) as a hexadecimal string.

Result

If the transaction in question has an associated dsproof, then a JSON object. Otherwise null.

Example Results:

{
  "dspid": "587d18bf8a64ede9c7450fdaeab27b9b3c46cfa8948f4c145f889601153c56b0",
  "txid": "5b59ce35093fbd13549cd6f203d4b5b01762d70e75b8e9733dfc463e0ff8cc13",
  "hex": "410c56078977120e828e4aacdd813a818d17c47d94183aa176d62c805d47697dddddf46c2ab68ee1e46a3e17aa7da548c38ec43416422d433b1782eb3298356df441",
  "outpoint": {
    "txid": "f6e2a16ba665d5402dad147fe35872961bc6961da62345a2171ee001cfcf7600",
    "vout": 0
  },
  "descendants": [
    "36fbb099e6de59d23477727e3199c65caae35ded957660f56fc681a6d81d5570",
    "5b59ce35093fbd13549cd6f203d4b5b01762d70e75b8e9733dfc463e0ff8cc13"
  ]
}

blockchain.transaction.dsproof.list¶

List all of the transactions that currently have double-spend proofs associated with them.

Signature

blockchain.transaction.dsproof.list()¶

New in version 1.4.5.

Result

A JSON array of hexadecimal strings. May be empty. Each string is a transaction hash of an in-mempool transaction that has a double-spend proof associated with it. Each of the hashes appearing in the list may be given as an argument to blockchain.transaction.dsproof.get() in order to obtain the associated double-spend proof for that transaction.

Example Results:

[
  "e67cc122f3c28a4243c3a1b14b38a9474c22ba928af9a194ca2b85426f0fd1bb",
  "077f0cc2439f2e48567c72eeeba5a447f8649c00c3d18ab6516eccfd4119726f",
  "ccc2f0d90b7067a83566024d4df842f0b6cb8180e18d642fcc85cae8acadbd58"
]

blockchain.transaction.dsproof.unsubscribe¶

Unsubscribe from receiving any further dsproof notifications for a transaction.

Signature

blockchain.transaction.dsproof.unsubscribe(tx_hash)¶

New in version 1.4.5.

tx_hash

The transaction hash as a hexadecimal string.

Result

Returns true if the transaction was previously subscribed-to for dsproof notifications, 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.get¶

Return a raw transaction.

Signature

blockchain.transaction.get(tx_hash, verbose=false)¶

Changed in version 1.1: ignored argument height removed

Changed in version 1.2: verbose argument added

tx_hash

The transaction hash as a hexadecimal string.

verbose

Whether a verbose coin-specific response is required.

Result

If verbose is false:

The raw transaction as a hexadecimal string.

If verbose is true:

The result is a coin-specific dictionary – whatever the coin daemon returns when asked for a verbose form of the raw transaction.

Example Results

When verbose is false:

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

When verbose is true:

{
  "blockhash": "0000000000000000015a4f37ece911e5e3549f988e855548ce7494a0a08b2ad6",
  "blocktime": 1520074861,
  "confirmations": 679,
  "hash": "36a3692a41a8ac60b73f7f41ee23f5c917413e5b2fad9e44b34865bd0d601a3d",
  "hex": "01000000015bb9142c960a838329694d3fe9ba08c2a6421c5158d8f7044cb7c48006c1b484000000006a4730440220229ea5359a63c2b83a713fcc20d8c41b20d48fe639a639d2a8246a137f29d0fc02201de12de9c056912a4e581a62d12fb5f43ee6c08ed0238c32a1ee769213ca8b8b412103bcf9a004f1f7a9a8d8acce7b51c983233d107329ff7c4fb53e44c855dbe1f6a4feffffff02c6b68200000000001976a9141041fb024bd7a1338ef1959026bbba860064fe5f88ac50a8cf00000000001976a91445dac110239a7a3814535c15858b939211f8529888ac61ee0700",
  "locktime": 519777,
  "size": 225,
  "time": 1520074861,
  "txid": "36a3692a41a8ac60b73f7f41ee23f5c917413e5b2fad9e44b34865bd0d601a3d",
  "version": 1,
  "vin": [ {
    "scriptSig": {
      "asm": "30440220229ea5359a63c2b83a713fcc20d8c41b20d48fe639a639d2a8246a137f29d0fc02201de12de9c056912a4e581a62d12fb5f43ee6c08ed0238c32a1ee769213ca8b8b[ALL|FORKID] 03bcf9a004f1f7a9a8d8acce7b51c983233d107329ff7c4fb53e44c855dbe1f6a4",
      "hex": "4730440220229ea5359a63c2b83a713fcc20d8c41b20d48fe639a639d2a8246a137f29d0fc02201de12de9c056912a4e581a62d12fb5f43ee6c08ed0238c32a1ee769213ca8b8b412103bcf9a004f1f7a9a8d8acce7b51c983233d107329ff7c4fb53e44c855dbe1f6a4"
    },
    "sequence": 4294967294,
    "txid": "84b4c10680c4b74c04f7d858511c42a6c208bae93f4d692983830a962c14b95b",
    "vout": 0}],
  "vout": [ { "n": 0,
             "scriptPubKey": { "addresses": [ "12UxrUZ6tyTLoR1rT1N4nuCgS9DDURTJgP"],
                               "asm": "OP_DUP OP_HASH160 1041fb024bd7a1338ef1959026bbba860064fe5f OP_EQUALVERIFY OP_CHECKSIG",
                               "hex": "76a9141041fb024bd7a1338ef1959026bbba860064fe5f88ac",
                               "reqSigs": 1,
                               "type": "pubkeyhash"},
             "value": 0.0856647},
           { "n": 1,
             "scriptPubKey": { "addresses": [ "17NMgYPrguizvpJmB1Sz62ZHeeFydBYbZJ"],
                               "asm": "OP_DUP OP_HASH160 45dac110239a7a3814535c15858b939211f85298 OP_EQUALVERIFY OP_CHECKSIG",
                               "hex": "76a91445dac110239a7a3814535c15858b939211f8529888ac",
                               "reqSigs": 1,
                               "type": "pubkeyhash"},
             "value": 0.1360904}]}

blockchain.transaction.get_confirmed_blockhash¶

Returns the block hash of the block that contains a particular transaction.

Signature

blockchain.transaction.get_confirmed_blockhash(tx_hash, include_header=false)¶

New in version 1.5.2.

tx_hash

The transaction hash as a hexadecimal string.

include_header

Whether to also return the block header in the results dictionary (default false if unspecified).

Result

If this transaction is unknown or is in the mempool, a JSON-RPC error result will be returned. If the transaction is confirmed in a block, a dictionary will be returned with the following keys:

block_hash

The block hash as a hexadecimal string.

block_header (optional, only if include_header=true)

The binary block header as a hexadecimal string.

block_height

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

Result Examples

{
  "block_hash": "0000000000000000000058ae65224f518d755d99afd512536c81dee2359dbcdb",
  "block_height": 816182
}

{
  "block_hash": "00000000000000000001522da9f02d2707dd91139f32a89d515e537384ecf2b1",
  "block_header": "00400020780506d9aeaf379e2c61f7e4b1c14c55dfb88c844581000000000000000000004818be123cf187c2eed198bc8eeed8b83c896d50b31948a625153c337a6c126aca454e65948104173ae18f28",
  "block_height": 816153
}

blockchain.transaction.get_height¶

Returns the block height for a confirmed transaction, or 0 for a mempool transaction, given its hash.

Signature

blockchain.transaction.get_height(tx_hash)¶

New in version 1.4.5.

tx_hash

The transaction hash as a hexadecimal string.

Result

Either a numeric value or null.

Numeric values > 0

The transaction is confirmed at this block height.

Numeric values == 0

The transaction is not confirmed but is in the mempool.

null

The transaction is unknown.

blockchain.transaction.get_merkle¶

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

Signature

blockchain.transaction.get_merkle(tx_hash[, height])¶

Changed in version 1.4.5: height is no longer required and is now optional

tx_hash

The transaction hash as a hexadecimal string.

height (optional in 1.4.5 or above)

The height at which it was confirmed, an integer. As of version 1.4.5 of the protocol, this second argument may be omitted, however if it is included the lookup may return the results slightly faster since an extra database lookup is avoided on the server-side.

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

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

New in version 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.transaction.unsubscribe¶

Unsubscribe from a transaction, preventing future notifications if its confirmation status changes.

Signature

blockchain.transaction.unsubscribe(tx_hash)¶

New in version 1.4.5.

tx_hash

The transaction hash as a hexadecimal string.

Result

Returns true if the transaction was previously 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.utxo.get_info¶

Return information for an unspent transaction output.

Signature

blockchain.utxo.get_info(tx_hash, out_n)¶

New in version 1.4.4.

Changed in version 1.5.0: token_data may appear in the result object if the UTXO contains a CashToken (BCH only)

tx_hash

The UTXO’s transaction hash as a hexadecimal string.

out_n

The UTXO’s transaction output number. This should be a number in the range 0 <= out_n <= 65535

Result

If the UTXO in question does not exist or is spent, null is returned. Otherwise, a dictionary will be returned containing the following keys:

confirmed_height

(Optional) The integer height of the block the UTXO’s transaction was confirmed in. This key will be missing from the dictionary if the transaction is in the mempool and is not yet confirmed.

scripthash

The output’s destination script hash as a hexadecimal string.

token_data (optional, BCH only)

A dictionary encapsulating the CashToken data for this output. This key will be missing from the dictionary if the unspent output does not have any token data on it.

value

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

Result Example

{
  "confirmed_height": 602123,
  "scripthash": "1c1e184c97abc87626c497b95f755df1025f48b9c27d037ea335677c57f38e5c",
  "value": 45318048
}

On 1.5.0 or above, for a token-containing output on BCH:

{
  "confirmed_height": 126184,
  "scripthash": "726205b2b758bd656b400cf5356fdec733528e93fc5f0a578592ab862539f327",
  "token_data": {
    "amount": "1000000",
    "category": "8fd6a2f713beaa5907a776b8b3060cddd1c6ff0588554c2364698ae271321ce9",
    "nft": {
      "capability": "minting",
      "commitment": "f00fd00fb33f"
    }
  },
  "value": 1000000
}

daemon.passthrough¶

Invokes an RPC method on the bitcoin daemon’s own RPC server, and returns the result.

Signature

daemon.passthrough(dictionary)¶

New in version 1.5.2.

dictionary

Unlike other Electrum Cash protocol methods, which accept a JSON-RPC array as positional arguments, this RPC requires a dictionary under the JSON-RPC "params" key for the request. The contents of this dictionary is itself a nested JSON-RPC pseudo-request, of the form: {"method": "...", "params": [...]}

Note

This method is not available by default on most servers and must be explicitly enabled by the server admin, since it allows for any client to call into the bitcoind RPC in an unrestricted fashion, which is not secure nor safe to do for a public network. It is only documented here for advanced usages of the server for private networks wishing to use this method.

Result

The JSON-RPC "result" that was returned by the demon is sent back to the client verbatim.

Example

--> Client sends:
{
  "id": 1,
  "method": "daemon.passthrough",
  "params": {
    "method": "getdsproofscore",
    "params": [
      "d3aac244e46f4bc5e2140a07496a179624b42d12600bfeafc358154ec89a720c"
    ]
  }
}

<-- Client receives:
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": 1.0
}

mempool.get_fee_histogram¶

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

Signature

mempool.get_fee_histogram()¶

New in version 1.2.

Result

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

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

server.add_peer(features)¶

New in version 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.donation_address¶

Return a server donation address.

Signature

server.donation_address()¶

Result

A string.

Example Result

"1BWwXJH3q6PRsizBkSGm2Uw4Sz1urZ5sCj"

server.features¶

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

Signature

server.features()¶

Changed in version 1.4.2: hosts key is no longer required, but recommended.

Changed in version 1.4.5: dsproof key added (optional).

Changed in version 1.5.0: cashtokens key added (optional).

Changed in version 1.5.3: rpa key added (optional).

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 Cash 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 (ws://) connectivity is not provided.

wss_port

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

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

dsproof

A boolean value. If present and set to true, then the server has double-spend proof support, and it supports the blockchain.transaction.dsproof.* set of RPC methods. If this key is missing or false, then the server does not support dsproofs.

cashtokens

A boolean value. If present and set to true, then the server has CashToken support, and it may return additional token_data in UTXO-related results from some of its RPC methods. If this key is missing or false, then the server does not support CashTokens.

rpa

An optional dictionary. If present and not null, it indicates that the server supports the reusable payment address RPCs such as blockchain.rpa.get_history(). The keys in the dictionary have the following meanings:

history_block_limit

Server configured limit on the number of blocks one can request to scan in a single blockchain.rpa.get_history() (or deprecated blockchain.reusable.get_history()) RPC call. The server will not scan more blocks than this value for any individual request and results will be truncated to respect this limit.

max_history

Server configured limit on the maximum number of elements one can receive in one blockchain.rpa.get_history() (or deprecated blockchain.reusable.get_history()) RPC call. The server will not return a JSON array exceeding this number of items, and it may truncate results to this limit or return nothing at all for requests that would produce results exceeeding this limit.

prefix_bits

The number of bits that are indexed for rpa_prefix searching. Requests cannot specify an rpa_prefix with bit-length longer than this limit.

prefix_bits_min

The minimum number of bits that clients can specify when searching by prefix in calls such as blockchain.rpa.get_history(). Requests cannot specify an rpa_prefix with bit-length smaller than this value.

starting_height

The first block height which is indexed by this server for RPA-related RPC calls. Prefix searching of blocks before this height will always yield empty results.

Example Result

{
    "genesis_hash": "000000000933ea01ad0ee984209779baaec3ced90fa3f408719526f8d77f4943",
    "hosts": {"14.3.140.101": {"tcp_port": 51001, "ssl_port": 51002}},
    "protocol_max": "1.5.3",
    "protocol_min": "1.4",
    "pruning": null,
    "server_version": "Fulcrum 1.10.0",
    "hash_function": "sha256",
    "dsproof": true,
    "cashtokens": true,
    "rpa": {
        "history_block_limit": 60,
        "max_history": 125000,
        "prefix_bits": 16,
        "prefix_bits_min": 8,
        "starting_height" :825000
    }
}

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

server.ping()¶

New in version 1.2.

Result

Returns null.

server.version¶

Identify the client to the server and negotiate the protocol version. Only the first server.version() message is accepted.

Signature

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 4.2.12", ["1.4", "1.4.5"])

Example Result:

["Fulcrum 1.9.0", "1.4.5"]

Protocol Methods¶

blockchain.address.get_balance¶

blockchain.scripthash.get_first_use¶

blockchain.address.get_history¶

blockchain.address.get_mempool¶

blockchain.address.get_scripthash¶

blockchain.address.listunspent¶

blockchain.address.subscribe¶

blockchain.address.unsubscribe¶

blockchain.block.header¶

blockchain.block.headers¶

blockchain.estimatefee¶

blockchain.header.get¶

blockchain.headers.get_tip¶

blockchain.headers.subscribe¶

blockchain.headers.unsubscribe¶

blockchain.relayfee¶

blockchain.reusable.get_history¶

blockchain.reusable.get_mempool¶

blockchain.rpa.get_history¶

blockchain.rpa.get_mempool¶

blockchain.scripthash.get_balance¶

blockchain.scripthash.get_first_use¶

blockchain.scripthash.get_history¶

blockchain.scripthash.get_mempool¶

blockchain.scripthash.listunspent¶

blockchain.scripthash.subscribe¶

blockchain.scripthash.unsubscribe¶

blockchain.transaction.broadcast¶

blockchain.transaction.dsproof.get¶

blockchain.transaction.dsproof.list¶

blockchain.transaction.dsproof.subscribe¶

blockchain.transaction.dsproof.unsubscribe¶

blockchain.transaction.get¶

blockchain.transaction.get_confirmed_blockhash¶

blockchain.transaction.get_height¶

blockchain.transaction.get_merkle¶

blockchain.transaction.id_from_pos¶

blockchain.transaction.subscribe¶

blockchain.transaction.unsubscribe¶

blockchain.utxo.get_info¶

daemon.passthrough¶

mempool.get_fee_histogram¶

server.add_peer¶

server.banner¶

server.donation_address¶

server.features¶

server.peers.subscribe¶

server.ping¶

server.version¶