Protocol Methods

blockchain.block.header

Return the block header at the given height.

Signature

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

Added 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. 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 chain:

"0100000085144a84488ea88d221c8bd6c059da090e88f8a2c99690ee55dbba4e00000000e11c48fecdd9e72510ca84f023370c9a38bf91ac5cae88019bee94d24528526344c36649ffff001d1d03e477"

With cp_height 8:

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

blockchain.block.headers

Return a chunk of block headers from the main chain.

Signature

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

Added in version 1.2.

Changed in version 1.4: cp_height parameter added

Changed in version 1.4.1.

Changed in version 1.6: response contains headers field instead of hex

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.

  • headers

    An array containing the binary block headers in-order; each header is a hexadecimal string. 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. (Recommended to be at least one difficulty retarget period, i.e. 2016)

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,
  "headers":
  [
    "0100000000000000000000000000000000000000000000000000000000000000000000003ba3edfd7a7b12b27ac72c3e67768f617fc81bc3888a51323a9fb8aa4b1e5e4a29ab5f49ffff001d1dac2b7c",
    "010000006fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000982051fd1e4ba744bbbe680e1fee14677ba1a3c3540bf7b1cdb606e857233e0e61bc6649ffff001d01e36299"
  ],
  "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, mode=None)

Changed in version 1.6: mode argument added

number

The number of blocks to target for confirmation.

mode

A string to pass to the bitcoind estimatesmartfee RPC as the estimate_mode parameter. Optional. If omitted, the corresponding parameter to the bitcoind RPC is also omitted, i.e. the default value is determined by bitcoind.

Result

The estimated transaction fee in whole 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

Note

This estimate typically comes from the Bitcoin daemon, which only updates its estimate when new blocks are mined. The server is free to cache this internally for performance reasons, however it SHOULD avoid sending stale estimates by e.g. invalidating the cache before notifying clients of a new block header.

blockchain.headers.subscribe

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

Signature

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 subscription, the client will receive a notification when a new block is found. The notification’s signature is:

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.

blockchain.scriptpubkey.get_balance

Return the confirmed and unconfirmed balances of a scriptPubKey.

Signature

blockchain.scriptpubkey.get_balance(scriptpubkey)

Added in version 1.7.

scriptpubkey

The scriptPubKey as a hexadecimal string.

Result

A dictionary with the following keys:

  • confirmed

    The confirmed balance, ignoring mempool events. An integer, in minimum coin units (satoshis). The sum of UTXO values at the current chaintip.

  • unconfirmed

    The mempool delta (compared to confirmed). An integer, in minimum coin units (satoshis). Note that it can also be negative.

Result Example

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

blockchain.scriptpubkey.get_history

Return the confirmed and unconfirmed history of a scriptPubKey.

Signature

blockchain.scriptpubkey.get_history(scriptpubkey)

Added in version 1.7.

scriptpubkey

The scriptPubKey as a hexadecimal string.

Result

A dictionary, always containing the following single key:

  • history

    A list of confirmed transactions in blockchain order, with the corresponding output of blockchain.scriptpubkey.get_mempool() (its history value) 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.scriptpubkey.get_mempool() for how mempool transactions are returned.

If the history of the scriptPubKey is too long (busy address, touched by thousands of txs), and so the server refuses to serve it, it SHOULD send a JSON-RPC error with integer code 10001 to communicate this to the client.

Result Examples

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

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

blockchain.scriptpubkey.get_mempool

Return the unconfirmed transactions of a scriptPubKey.

Signature

blockchain.scriptpubkey.get_mempool(scriptpubkey)

Added in version 1.7.

scriptpubkey

The scriptPubKey as a hexadecimal string.

Result

A dictionary, always containing the following single key:

  • history

    A list of mempool transactions. The order is the same as when computing the status of the scriptPubKey. 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

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

blockchain.scriptpubkey.listunspent

Return an ordered list of UTXOs sent to a scriptPubKey.

Signature

blockchain.scriptpubkey.listunspent(scriptpubkey)

Added in version 1.7.

scriptpubkey

The scriptPubKey as a hexadecimal string.

Result

A dictionary, always containing the following single key:

  • utxos

    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.

    • value

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

Warning

In the case of pre-segwit legacy UTXOs, the satoshi value claimed by a server should be verified by the client by requesting the full funding transaction and parsing it to look for the output amount corresponding to tx_hash:tx_pos. This is necessary as the pre-segwit legacy sighash does not commit to the input amount, so the server could try to trick a client into burning their coins as fees. Note that it is not necessary to SPV-verify tx_hash, as the sighash commits to the txid, and the txid commits to the raw tx, from which we read out the satoshi amount.

Result Example

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

blockchain.scriptpubkey.subscribe

Subscribe to a scriptPubKey.

Signature

blockchain.scriptpubkey.subscribe(scriptpubkey)

Added in version 1.7.

scriptpubkey

The scriptPubKey as a hexadecimal string.

Result

The status of the scriptPubKey.

If the history of the scriptPubKey is too long (busy address, touched by thousands of txs), and so the server refuses to serve it, it SHOULD send a JSON-RPC error with integer code 10001 to communicate this to the client.

Notifications

The client will receive a notification when the status of the scriptPubKey changes.

The client MAY receive a notification even if the status did not change. One such example is a reorg changing the blockhash, but not the height, a relevant tx is mined in, in which case the client MUST get a notification.

Importantly, the notifications use script hash instead of scriptPubKey. The scripthash corresponds to the scriptPubKey from the original request. The client is expected to maintain a mapping scripthash->scriptpubkey, or similar, to be able to figure out what the notification refers to. Notably, this way servers do not have to store in memory the scriptpubkey corresponding to the original request (which can be up to 10 KB in size, as per Bitcoin consensus), only the scripthash (which is fixed size). Also, this limits upstream bandwidth usage of servers.

The signature is

blockchain.scriptpubkey.subscribe(scripthash, status)

blockchain.scriptpubkey.unsubscribe

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

Signature

blockchain.scriptpubkey.unsubscribe(scriptpubkey)

Added in version 1.7.

scriptpubkey

The scriptPubKey as a hexadecimal string.

Result

Returns True if the scriptpubkey 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.outpoint.subscribe

Subscribe to a transaction outpoint (TXO), to get notifications about its status. A status involves up to two transactions: the funding transaction that creates the TXO (as one of its outputs), and the spending transaction that uses it as an input (spends it).

Signature

blockchain.outpoint.subscribe(tx_hash, txout_idx, spk_hint)

Added in version 1.7.

tx_hash

The TXID of the funding transaction as a hexadecimal string. (sometimes called prevout_hash, in inputs)

txout_idx

The output index, a non-negative integer. (sometimes called prevout_n, in inputs)

spk_hint

The scriptPubKey (output script) corresponding to the outpoint (prevout), as a hexadecimal string. This helps the server find the outpoint. Behaviour is undefined if an incorrect value is provided.

Note

Full index servers might not need the parameter in practice but some lighter personal servers (such as EPS, BWT, Floresta) would not be able to serve the request without it. Clients should always know the spk_hint in practice, so having to send it is not expected to kill any use case.

Note

The server MAY automatically clean up subscriptions (unsubscribe the client) where the spending transaction is already deeply mined at a reorg-safe height (typically 100+ blocks deep). Similarly, the server MAY ignore new subscription requests if the spending tx is already mined at a reorg-safe height but it still MUST send the full response to the subscription request (just not the subsequent notifications - which likely would never trigger anyway without a deep reorg).

Result

The status of the TXO (taking the mempool into consideration). The output is a dictionary, containing some of the following items:

  • funder_height

    The integer height of the block the funding transaction was confirmed in. If the funding transaction is in the mempool; the value is 0 if all its inputs are confirmed, and -1 otherwise. This key must be present if and only if there exists a funding transaction (either in the best chain or in the mempool), regardless of spentness.

  • spender_txhash

    The TXID of the spending transaction as a hexadecimal string. This key is present if and only if there exists a spending transaction (either in the best chain or in the mempool).

  • spender_height

    The integer height of the block the spending transaction was confirmed in. If the spending transaction is in the mempool; the value is 0 if all its inputs are confirmed, and -1 otherwise. This key is present if and only if the spender_txhash key is present.

Result Examples

{}

{
  "funder_height": 1866594
}

{
  "funder_height": 1866594,
  "spender_txhash": "4a19a360f71814c566977114c49ccfeb8a7e4719eda26cee27fa504f3f02ca09",
  "spender_height": 0
}

Notifications

The client will receive a notification when the status of the outpoint changes. That is, any event that changes any field of the status dictionary results in a notification. Some examples:

  • a funding/spending tx appearing in the mempool if there was no such tx when the client subscribed (note: the server MUST save the subscription even if the outpoint does not exist yet)

  • funding/spending tx height changing from -1 to 0 as its inputs got mined

  • funding/spending tx height changing from 0 to a (positive) block height when it gets mined

  • note that reorgs can change any of the status fields and result in notifications

  • note that mempool replacement (e.g. due to RBF) or mempool eviction (and potentially other mempool quirks) can also change some of the status fields and hence result in notifications

The client MAY receive a notification even if the status did not change. One such example is a reorg changing the blockhash, but not the height, a relevant tx is mined in, in which case the client MUST get a notification.

The signature of the notification is

blockchain.outpoint.subscribe(tx_hash, txout_idx, status)

Full JSON-RPC Example

Here is an example where the client sends a request, gets an immediate response, and then at some point later - while the connection is still open - receives a notification.

-> {
  "jsonrpc": "2.0",
  "id": 4,
  "method": "blockchain.outpoint.subscribe",
  "params": ["1872b27abc497492a775fe335abfe368af575733144a7ecd4b249d8fd885b3cf", 1, "0014da28b119a0687c045d87b604667f6773bdc30146"]
}
<- {
  "jsonrpc": "2.0",
  "result": {
    "funder_height": 1866594
  },
  "id": 4
}

# notification after broadcasting tx 4a19a360f71814c566977114c49ccfeb8a7e4719eda26cee27fa504f3f02ca09
<- {
  "jsonrpc": "2.0",
  "method": "blockchain.outpoint.subscribe",
  "params": [
    "1872b27abc497492a775fe335abfe368af575733144a7ecd4b249d8fd885b3cf",
    1,
    {
      "funder_height": 1866594,
      "spender_txhash": "4a19a360f71814c566977114c49ccfeb8a7e4719eda26cee27fa504f3f02ca09",
      "spender_height": 0
    }
  ]
}

blockchain.outpoint.get_status

Get the status of a transaction outpoint (TXO). Same as blockchain.outpoint.subscribe(), but without subscribing to future changes of status (i.e. no subsequent notifications).

Signature

blockchain.outpoint.get_status(tx_hash, txout_idx, spk_hint)

Added in version 1.7.

(same as blockchain.outpoint.subscribe())

Result

blockchain.outpoint.unsubscribe

Unsubscribe from a transaction outpoint (TXO), preventing future notifications if its status changes.

Signature

blockchain.outpoint.unsubscribe(tx_hash, txout_idx)

Added in version 1.7.

tx_hash

The TXID of the funding transaction as a hexadecimal string.

txout_idx

The output index, a non-negative integer.

Result

Returns True if the outpoint 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

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

Broadcast a package of transactions to the network (submitpackage). The package must consist of a child with its parents, and none of the parents may depend on one another. The package must be topologically sorted, with the child being the last element in the array.

Signature

blockchain.transaction.broadcast_package(raw_txs, verbose=false)

Added in version 1.6.

raw_txs

An array of raw transactions, each as a hexadecimal string.

verbose

Whether a verbose coin-specific response is required.

Result

If verbose is false:

A dictionary with the following keys:

  • success

    • Type: bool

    • Value: Indicating the result of the package submission

  • errors

    • Type: Optional[List[Dict]]

    • Value: Error message and txid (NOT wtxid) of transactions that were not accepted

If verbose is true:

The result is a bitcoind-specific dictionary – whatever bitcoind returns as response to the submitpackage (or equivalent) RPC. (example docs for Bitcoin Core)

As the exact structure and semantics depend on the bitcoind version (or alternative bitcoind, e.g. btcd), the electrum protocol can make no guarantees about it. Unlike the verbose=False result, which is guaranteed to be stable and can be relied upon, the verbose=True result should be considered experimental and better-suited for debugging.

Note

The exact relay behaviour might depend on the bitcoind version of the server.

Note

Server implementations should verify (e.g. by enforcing a minimum bitcoind version at runtime) that the backing bitcoind supports relay of transaction packages. For example, note that Bitcoin Core 26.0 already exposes the submitpackage RPC however it is effectively non-functional until Bitcoin Core 28.0.

Result Example

When verbose is false:

Successful broadcast:

{
  "success": true
}

With errors:

{
  "success": false,
  "errors":
  [
    {
      "txid": "ec6f295cd4b1b91f59cabb0ab8fdc7c76580db08be6426e465f75a69d82b9659",
      "error": "bad-txns-inputs-missingorspent"
    }
  ]
}

When verbose is true (exact structure depends on bitcoind impl and version, and should not be relied upon):

{                                   (json object)
  "package_msg" : "str",            (string) The transaction package result message. "success" indicates all transactions were accepted into or are already in the mempool.
  "tx-results" : {                  (json object) transaction results keyed by wtxid
    "wtxid" : {                     (json object) transaction wtxid
      "txid" : "hex",               (string) The transaction hash in hex
      "other-wtxid" : "hex",        (string, optional) The wtxid of a different transaction with the same txid but different witness found in the mempool. This means the submitted transaction was ignored.
      "vsize" : n,                  (numeric, optional) Sigops-adjusted virtual transaction size.
      "fees" : {                    (json object, optional) Transaction fees
        "base" : n,                 (numeric) transaction fee in BTC
        "effective-feerate" : n,    (numeric, optional) if the transaction was not already in the mempool, the effective feerate in BTC per KvB. For example, the package feerate and/or feerate with modified fees from prioritisetransaction.
        "effective-includes" : [    (json array, optional) if effective-feerate is provided, the wtxids of the transactions whose fees and vsizes are included in effective-feerate.
          "hex",                    (string) transaction wtxid in hex
          ...
        ]
      },
      "error" : "str"               (string, optional) The transaction error string, if it was rejected by the mempool
    },
    ...
  },
  "replaced-transactions" : [       (json array, optional) List of txids of replaced transactions
    "hex",                          (string) The transaction id
    ...
  ]
}

Note

If the input is malformed, notably if raw_txs is not a well-formed package, errors will be sent back as JSON RPC ERROR, as usual. Ultimately the distinction can depend on bitcoind. Compare examples (id=3 gets JSON RPC ERROR, but id=4 gets success=false with errors array):

<- {"id": 3, "method": "blockchain.transaction.broadcast_package", "params": [["02000000000102f758cda73a362840995d62d0079a22a11fc2652cb7740fffb8132486fe76fe730000000000fdffffff31b2d3d434d7c8f46b23a47aabc3c9498d4df5ffb9f13e13c3c3ecb52ab570b80000000000fdffffff02400d0300000000001600149f9aa3795e57c535d2f7b160ff023804c60fca6e30b3e80b00000000160014553a3b97c2cc7d3d4edeace3281ff038bd0676290247304402202c84cb82c94978b688154f06c3b91e64b99f2c2124d7c53004c81d23c4ce7e5102206a5c87986d1272140a8625a0fbd9926c2a93bf41517aca28615499140936109c0121027ba4d3ee6471a985307a37d09eb9a0a73c1a31b57616fe3e53a3d6d4540025190247304402203106d7622d3bcb415ae898558e8d414c337e2e7d4a485bbf4bffa8ba3bc620b802201340334f4d89e03735b3b183602ce4b3377225571ebbf18e97eaa24f3fcc5d4f0121027ba4d3ee6471a985307a37d09eb9a0a73c1a31b57616fe3e53a3d6d454002519a4090000", "02000000000101ab93b5c11c9a591b441de4228c942603a0479fa0d33a1a2bee72e75bd301c25e0000000000fdffffff01640c03000000000016001446116f48b60ad5b22377dcf951643e2e1aa3957a0247304402206002cc311d16b5cef7349bcd4174d3ae14d5741680ab81d7e24bc31c89634fd6022072d0d6b72c4ddbe62c527ebc5955677793cc13fe801ec22604d93bbc1b1f3291012102fb265cce2019e555fe23fb45e4cbc3d966bb399a52b2e93b808ad7961b426de1a4090000"]]}
-> {"jsonrpc":"2.0","error":{"code":1,"message":"the tx package was rejected by network rules.\n\npackage topology disallowed. not child-with-parents or parents depend on each other.."},"id":3}

<- {"id": 4, "method": "blockchain.transaction.broadcast_package", "params": [["0200000000010148d372010d796a89f12864b5c86495d67bce98cb9ac3ba652bf811aa6b82c36c0000000000fdffffff01d20c030000000000160014e437538b7f13871562066babd1fbab72b4fba958024730440220662e4d917c0af3b37dd0bad65c9b46ba2a1504cd4f1346f35c0020f6d0edbd0e02207b44f98612bd3f58164385f4a572af2a2f471c924f6569aa6f3ddcaaa0e57753012103c3172a9f8820681c62b8bf28961988a4642b33f4920b9da14b06965c7fff83fd68090000", "02000000000101ab93b5c11c9a591b441de4228c942603a0479fa0d33a1a2bee72e75bd301c25e0000000000fdffffff014e0c03000000000016001446116f48b60ad5b22377dcf951643e2e1aa3957a0247304402202850349c76c41b801c429feaee96d773788b478c1cf051e967824fe504e5948902204bbede1252490c06c38feb206266aaf126937f6a3bc0a16d038fabde9781c6fd012102fb265cce2019e555fe23fb45e4cbc3d966bb399a52b2e93b808ad7961b426de1a4090000"]]}
-> {"jsonrpc":"2.0","result":{"success":false,"errors":[{"txid":"c13d8d63284853d3417a150cfddcfc62d31cab4b311c9322cb43f979a518ac3a","error":"insufficient fee, rejecting replacement c13d8d63284853d3417a150cfddcfc62d31cab4b311c9322cb43f979a518ac3a, not enough additional fees to relay; 0.00000022 < 0.0000011"}]},"id":4}

blockchain.transaction.testmempoolaccept

Returns result of mempool acceptance tests indicating if transaction(s) would be accepted by mempool. This checks if txs violate the consensus or policy rules.

If multiple txs are passed in, parents must come before children and package policies apply: the transactions cannot conflict with any mempool txs or each other. However the txs do not necessarily need to be related to each other or form a “package”.

Signature

blockchain.transaction.testmempoolaccept(raw_txs)

Added in version 1.7.

raw_txs

An array of raw transactions, each as a hexadecimal string. The maximum number of transactions allowed depends on the bitcoind version of the server, but SHOULD be at least 25.

Result

A json array containing the mempool acceptance test result (a dictionary) for each raw tx, in the same order they were passed in.

Transactions that cannot be fully validated due to failures in other transactions will not contain an ‘allowed’ field.

The per-tx dict has the following keys:

  • txid (always)

    • Type: str

    • Value: The transaction hash in hex

  • wtxid (always)

    • Type: str

    • Value: The transaction witness hash in hex

  • allowed (optional)

    • Type: bool

    • Value: Whether this tx would be accepted to the mempool. If not present, the tx was not fully validated due to a failure in another tx in the list.

  • reason (optional)

    • Type: str

    • Value: Rejection reason or error message describing why the tx would not be accepted into the mempool. Only present if “allowed” is either false or missing, but even then its presence is optional. This message is arbitrary free-from human-readable text, no guarantees re stability or contents at all. This is only there to help debugging.

Result Example

Single tx, allowed:

[
    {
        'txid': 'f2f5f9e7a189d97367b4449705e0567408b4d2f3b6ee03119fa7bc7a96313bfc',
        'wtxid': '9091e488dded52875f308f1305b1beec73cf0c646644c58c1a161170a33ce7e6',
        'allowed': true
    }
]

Two txs, allowed:

[
    {
        'txid': 'f2f5f9e7a189d97367b4449705e0567408b4d2f3b6ee03119fa7bc7a96313bfc',
        'wtxid': '9091e488dded52875f308f1305b1beec73cf0c646644c58c1a161170a33ce7e6',
        'allowed': true
    },
    {
        'txid': '0b3e3cacd0be5156711eeff30c4124168b3be9890c297b1c02d47a66e2a6f61b',
        'wtxid': '779a2ffd065ad5243b85c5d716815186607cf0195a604a8cd668ef2093986b4a',
        'allowed': true
    }
]

Single tx, rejected:

[
    {
        'txid': '9c42f84b2fcdaff676ba25d9d4941741cc0d1a01cce0c23fdc4c0b2afa38431c',
        'wtxid': 'b3b1045327a9bd21850f07f639a784653c69d7d82b0341829cb8afcb2c0f881e',
        'allowed': false,
        'reason': 'missing-inputs'
    }
]

Two txs, first tx would be okay, but second is not:

[
    {
        'txid': '5cd0bd7d93e1bbd8269563c1d081e893ed4efbd4bf74ad369ce8569e78928a3e',
        'wtxid': 'ca0404678d8301cdbbcb96c619acc92b54b6fb82c6a9c4c1d6a2f9b0004d1559'},
    {
        'txid': 'd79a54959ac68c592687ac1c040f4b2ba223cb18f36552a42beaab776d6305ed',
        'wtxid': '83996a7f65d8a52238b83d6123fe908ff98ab48db762d201dbf9efbbf67bd4cc',
        'allowed': false,
        'reason': 'min relay fee not met, 0 < 15'
    }
]

Two txs, that already conflict with each other. This illustrates the “allowed” field might not be present in any item:

[
    {
        'txid': 'd79a54959ac68c592687ac1c040f4b2ba223cb18f36552a42beaab776d6305ed',
        'wtxid': '83996a7f65d8a52238b83d6123fe908ff98ab48db762d201dbf9efbbf67bd4cc',
        'reason': 'conflict-in-package'
    },
    {
        'txid': '30aa0fb6174fcc6593235301aa7887227958952238f306131b4dbcab6af33c2f',
        'wtxid': '7ff9fcbf25721c19b04468c5c2f218d950e3b6446e7e1a564fc01304d3c3e3f2',
        'reason': 'conflict-in-package'
    }
]

Note

The client implicitly trusts the server NOT to broadcast the txs. Conversely, for the blockchain.transaction.broadcast RPC, the client trusts the server to DO broadcast the tx.

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 the verbose bitcoind response is required.

Result

If verbose is false:

The raw transaction as a hexadecimal string.

If verbose is true:

The result is a bitcoind-specific dictionary – whatever bitcoind 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_merkle

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

Signature

blockchain.transaction.get_merkle(tx_hash, height)

tx_hash

The transaction hash as a hexadecimal string.

height

The height at which it was confirmed, an integer.

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)

Added 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"
  ]
}

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

Added in version 1.2.

Result

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

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

fee uses sat/vbyte as unit, and must be a non-negative integer or float.

vsize uses vbyte as unit, and must be a non-negative integer.

Example Results

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

[[59.5, 30324], [40.1, 34305], [35.0, 38459], [29.3, 41270], [27.0, 45167], [24.3, 53512], [22.9, 53488], [21.8, 70279], [20.0, 65328], [18.2, 72180], [18.1, 5254], [18.0, 191579], [16.5, 103640], [15.7, 106715], [15.1, 141776], [14.0, 183261], [13.5, 166496], [11.8, 166050], [11.1, 242436], [9.2, 184043], [7.1, 202137], [5.2, 222011], [4.8, 344788], [4.6, 17101], [4.5, 1696864], [4.1, 598001], [4.0, 32688687], [3.9, 505192], [3.8, 38417], [3.7, 2944970], [3.3, 693364], [3.2, 726373], [3.1, 308878], [3.0, 11884957], [2.6, 996967], [2.3, 822802], [2.2, 9075547], [2.1, 12149801], [2.0, 16387874], [1.4, 873120], [1.3, 3493364], [1.1, 2302460], [1.0, 23204633]]

mempool.get_info

Returns details on the active state of the TX memory pool.

Signature

mempool.get_info()

Added in version 1.6.

Result

A dictionary with the following keys:

  • mempoolminfee

    • Type: floating point number

    • Value:

      Dynamic minimum fee rate in BTC/kvB for tx to be accepted given current conditions. The maximum of minrelaytxfee and minimum mempool fee, in BTC/kvB.

  • minrelaytxfee

    • Type: floating point number

    • Value: Static operator-configurable minimum relay fee for transactions, in BTC/kvB.

  • incrementalrelayfee

    • Type: floating point number

    • Value: Static operator-configurable minimum fee rate increment for mempool limiting or replacement, in BTC/kvB.

Example Result

{
    "mempoolminfee": 0.00001000,
    "minrelaytxfee": 0.00001000,
    "incrementalrelayfee": 0.00001000
}

mempool.recent

Return a list of the last 10 transactions to enter the mempool, in arbitrary order. Each transaction object contains simplified overview data, with the following fields: txid, fee and vsize.

Signature

mempool.recent()

Added in version 1.7.

Result

An array of dictionaries, each with the following keys:

  • txid

    • Type: hex string

    • Value: The transaction hash as a hexadecimal string.

  • fee

    • Type: integer

    • Value: The fee paid by the transaction, in satoshis.

  • vsize

    • Type: integer

    • Value: The virtual size of the transaction, in vbytes.

Note

The server should do a best-effort attempt at including txs that just very recently entered the mempool, however most-recent-ness is not guaranteed.

Note

The result might contain fewer than 10 items if the mempool is close to empty.

Example Result

[
    {
        txid: "4b93c138293a7e3dfea6f0a63d944890b5ba571b03cc22d8c66995535e90dce8",
        fee: 18277,
        vsize: 2585
    },
    {
        txid: "47182935123ae4e28d6a227a6076deaef222885d1d67e17e1ea02dd69013e5db",
        fee: 877,
        vsize: 143
    },
    ...
]

server.add_peer

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

Signature

server.add_peer(features)

Added 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.banner

Return a banner to be shown in the Electrum console.

Signature

server.banner()

Result

A string.

Example Result

"Welcome to Electrum!"

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.7: removed hash_function field from result

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.

  • hosts

    A dictionary, keyed by host name, that this server can be reached at. Normally this will only have 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.

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

  • genesis_hash

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

  • server_version

    A string that identifies the server software. Should be the same as the first element of 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.

Note

pruning indicates how many spent transaction-history entries per address the server may retain. It is not related to bitcoind’s block pruning.

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",
}

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

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

Besides keeping the TCP connection alive, this can also be used to obfuscate traffic patterns.

This method can be sent either as a JSON-RPC “Request” or as a JSON-RPC “Notification”. If sent as a notification, the receiver is expected not to respond. This is useful to mimic the traffic pattern of a “useful” notification.

Unlike with other methods, these notifications are not sent as a consequence of prior subscriptions. We simply abuse the JSON-RPC “Notification” mechanism to allow sending an “unrequested” message that does not warrant a response. Both the client and the server MUST tolerate receiving this as an unrequested notification.

Note The client can send this method either as “Request” or as “Notification”. The server is only allowed to send it as “Notification”. There seems to be no useful traffic pattern that could be mimicked by allowing the server to send this as a request (and getting the client to respond). If one arises, we could relax this in a future version. Allowing the client to send it as “Notification” can be useful as an alternative way to pad its outgoing traffic, in case it does not have direct access to the lower-level JSON-RPC stream to inject whitespaces.

Signature

server.ping(pong_len=0, data='')

Added in version 1.2.

Changed in version 1.7: both parties are now allowed to send this and significant changes to signature/fields

  • pong_len

    The number of hex characters the other party should send in the data part of the response. A non-negative integer.

  • data

    A hexadecimal string (but can be odd-length). Its value is to be ignored by the recipient.

Result

A dictionary with the following keys:

  • data

    A hexadecimal string (but can be odd-length). Its value is to be ignored by the recipient. However, the length MUST match the pong_len that was requested.

Notifications

server.ping(data='')

  • data

    See Result above.

Note The data fields should support reasonably long strings, at least as long as would be needed to encode the largest consensus-valid transaction. No limits here would mean an easy DOS-vector and waste of bandwidth using pong_len. The client could already send or request transactions using other protocol methods, so limiting below that does not make sense.

Full JSON-RPC Examples

-> {
  "jsonrpc": "2.0",
  "id": 4,
  "method": "server.ping",
  "params": [0, "deadbeefdeadbeefdeadbeefdeadbeef"]
}
<- {
  "jsonrpc": "2.0",
  "result": {"data": ""},
  "id": 4
}

-> {
  "jsonrpc": "2.0",
  "id": 4,
  "method": "server.ping",
  "params": [5]
}
<- {
  "jsonrpc": "2.0",
  "result": {"data": "00000"},
  "id": 4
}

-> {
  "jsonrpc": "2.0",
  "method": "server.ping",
  "params": ["deadbeefdeadbeefdeadbeefdeadbeef"]
}
(No response. This was a notification.)

server.version

Identify the client to the server and negotiate the protocol version. This must be the first message sent on the wire. Only the first server.version() message is accepted.

Signature

server.version(client_name='', protocol_version='1.4')

Changed in version 1.6: server must tolerate and ignore extraneous args

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

Extraneous unknown args MUST be tolerated and ignored by the server, to allow for future extensions.

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("Electrum 3.0.6", ["1.1", "1.2"])

Example Result:

["ElectrumX 1.2.1", "1.2"]

Example

Redundant unknown arguments MUST be ignored and tolerated by the server:

server.version("electrum/4.6.2", ["1.4", "1.6"], "trailing_garbage1", 9999.9, "dd": {})

Example Result:

["ElectrumX 1.18.0", "1.4"]

Some more stuff for altcoins

Protocol Methods (for altcoins)