Package: bitcoinrpc
bitcoin-python-async-rpcLightweight Bitcoin async JSON-RPC Python client.Serves as a tiny layer between an application and a Bitcoin daemon, its primary usage
is querying the current state of Bitcoin blockchain, network stats, transactions...If you want complete Bitcoin experience in Python, consultpython-bitcoinlib.Installation$pipinstallbitcoinrpcSupported methodsHere is a list of supported methods, divided by their categories. Should you need
method not implemented, wrap the call inBitcoinRPC.acall(<your_method>, ...)coroutine.BlockchainMethodSupported?getbestblockhash✔getblock✔getblockchaininfo✔getblockcount✔getblockhash✔getblockheader✔getblockstats✔getchaintips✔getdifficulty✔getmempoolinfo✔getnetworkhashps✔MiningMethodSupported?getmininginfo✔NetworkMethodSupported?getconnectioncount✔getnetworkinfo✔Raw transactionsMethodSupported?analyzepsbt✔combinepsbt✔decodepsbt✔finalizepsbt✔getrawtransaction✔joinpsbts✔utxoupdatepsbt✔WalletMethodSupported?walletprocesspsbt✔UsageMinimal illustration (assuming Python 3.8+, where you can runasynccode in console)$ python -m asyncio
>>> import asyncio
>>>
>>> from bitcoinrpc import BitcoinRPC
>>> rpc = BitcoinRPC.from_config("http://localhost:18443", ("rpc_user", "rpc_passwd"))
>>> await rpc.getconnectioncount()
10
>>> await rpc.aclose()  # Clean-up resourceYou can also use theBitcoinRPCas an asynchronous context manager, which does
all the resource clean-up automatically, as the following example shows:$catbtc_rpc_minimal.pyimportasynciofrombitcoinrpcimportBitcoinRPCasyncdefmain():asyncwithBitcoinRPC.from_config("http://localhost:18443",("rpc_user","rpc_password"))asrpc:print(awaitrpc.getconnectioncount())if__name__=="__main__":asyncio.run(main())Running this script yields:$ python btc_rpc_minimal.py
10If you want customize the underlyinghttpx.AsyncClient, you can instantiate theBitcoinRPCwith one.
Consider the following script, where the client is configured to log every HTTP request before it is sent
out over the wire:$catbtc_custom_client.pyimportasyncioimporthttpxfrombitcoinrpcimportBitcoinRPCasyncdeflog_request(request:httpx.Request)->None:print(request.content)asyncdefmain()->None:client=httpx.AsyncClient(auth=("rpc_user","rpc_password"),event_hooks={"request":[log_request]})asyncwithBitcoinRPC(url="http://localhost:18443",client=client)asrpc:print(awaitrpc.getconnectioncount())if__name__=="__main__":asyncio.run(main())Running this script yields:$ python btc_custom_client.py 
b'{"jsonrpc":"2.0","id":1,"method":"getconnectioncount","params":[]}'
0TestingAContainerfileis provided as a means to build an OCI image of a Bitcoinregtestnode.
Build the image (podmanis used, butdockershould be fine too):$ podman build \
  -f Containerfile \
  --build-arg BTC_VERSION=v24.1 \
  -t bitcoin-regtest:v24.1 \
  -t bitcoin-regtest:latest \
  .and run it afterwards:$ podman run \
  --rm \
  -it \
  --mount=type=bind,src=./tests/bitcoin-regtest.conf,target=/home/rpc/.bitcoin/bitcoin.conf \
  -p 127.0.0.1:18443:18443 \
  --name bitcoin-regtest \
  localhost/bitcoin-regtest:v24.1which will expose the Bitcoinregtestnode on port 18443, accesible from localhost only, with RPC user/passwordrpc_user/rpc_password.After you are done testing, stop the container via:$ podman stop bitcoin-regtestIf you want to test against a different version of Bitcoin node, pass a differenttagin the build stage:$ podman build \
  -f Containerfile \
  --build-arg BTC_VERSION=v25.0 \
  -t bitcoin-regtest:v25.0 \
  -t bitcoin-regtest:latest \
  .Different settings of the Bitcoin node may be passed via mounting your custom configuration file, or optionally as "arguments" topodman run:$ podman run \
  --rm \
  -it \
  --mount=type=bind,src=<path/to/your/config_file>,target=/home/rpc/.bitcoin/bitcoin.conf \
  -p 127.0.0.1:18443:18443 \
  --name bitcoin-regtest \
  localhost/bitcoin-regtest:v24.1 <your> <args> ...Please, keep in mind that Bitcoin node compiled in the image is intended for testing & debugging purposes only! It may serve you as an inspiration for building
your own, production-ready Bitcoin node, but its intended usage is testing!For testing this library, installtox(preferably, in a fresh virtual environment).Afterwards, coding-style is enforced by running:(your-venv-with-tox) $ tox run -e lintersand tests corresponding are run (this example uses Python3.11)(your-venv-with-tox) $ tox run -e py311If you do not want to run tests marked as"integration", which denote those requiring the bitcoin regtest node to run, you can filter them out by:(your-venv-with-tox) $ tox run -e py311 -- -m 'not integration'Changelog2024/02/12 - 0.7.0: More robust handling of JSON-RPC 2.0 specification (thankshttps://github.com/joxerx!)Breaking change: change the handling of responses with non-2xx status codes in 'BitcoinRPC.acall'.
Previously, said errors would be raised directly via thehttpx.Response.raise_for_statusmethod.
Now,httpx.Response.raise_for_statusis used only when the server
returns an empty response, which may happen due to for example bad
authentication. In all other cases, defer the decision whether RPC
call was a success or a failure to the inspection of return JSON.2023/06/04 - 0.6.1: Add RPC methods, mainly concerned with PSBTs2023/06/01 - 0.6.0:BitcoinRPCis now instantiated with ahttpx.AsyncClientdirectly and an optionalcounterargument, which is a callable that may be used for distinguishing
the JSON-RPC requests. Old-style instantiation, withurland optional user/password tuple, is kept withinBitcoinRPC.from_configmethod.2021/12/28 - 0.5.0change the signature ofBitcoinRPCfromhost, port, ...tourl, ..., delegating the creation of the node url to the caller.LicenseMIT