{"id":14980191,"url":"https://github.com/bibajz/bitcoin-python-async-rpc","last_synced_at":"2025-07-04T23:04:56.470Z","repository":{"id":45249113,"uuid":"255687421","full_name":"bibajz/bitcoin-python-async-rpc","owner":"bibajz","description":"Minimal Bitcoin JSON-RPC Python asynchronous client","archived":false,"fork":false,"pushed_at":"2024-02-11T23:35:41.000Z","size":38,"stargazers_count":34,"open_issues_count":4,"forks_count":13,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-01T19:11:20.356Z","etag":null,"topics":["async","bitcoin","cryptocurrency","python","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bibajz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-14T18:08:07.000Z","updated_at":"2024-12-04T03:51:19.000Z","dependencies_parsed_at":"2024-02-10T15:28:22.485Z","dependency_job_id":"256969e1-31cc-4c37-a2c8-4402b30b0ecc","html_url":"https://github.com/bibajz/bitcoin-python-async-rpc","commit_stats":{"total_commits":29,"total_committers":2,"mean_commits":14.5,"dds":0.03448275862068961,"last_synced_commit":"0debc78eef63a47bfb1fb6b4273bebc5d3e03659"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bibajz%2Fbitcoin-python-async-rpc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bibajz%2Fbitcoin-python-async-rpc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bibajz%2Fbitcoin-python-async-rpc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bibajz%2Fbitcoin-python-async-rpc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bibajz","download_url":"https://codeload.github.com/bibajz/bitcoin-python-async-rpc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238737999,"owners_count":19522288,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["async","bitcoin","cryptocurrency","python","python3"],"created_at":"2024-09-24T14:01:25.698Z","updated_at":"2025-02-13T21:31:24.110Z","avatar_url":"https://github.com/bibajz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bitcoin-python-async-rpc\nLightweight Bitcoin async JSON-RPC Python client.\n\nServes as a tiny layer between an application and a Bitcoin daemon, its primary usage\nis querying the current state of Bitcoin blockchain, network stats, transactions...\n\nIf you want complete Bitcoin experience in Python, consult\n[python-bitcoinlib](https://github.com/petertodd/python-bitcoinlib).\n\n## Installation\n```bash\n$ pip install bitcoinrpc\n```\n\n## Supported methods\nHere is a list of supported methods, divided by their categories. Should you need\nmethod not implemented, wrap the call in `BitcoinRPC.acall(\u003cyour_method\u003e, ...)` coroutine.\n\n### Blockchain\n\n|   Method   |   Supported?     |\n|------------|:----------------:|\n| `getbestblockhash` | ✔ |\n| `getblock` | ✔ |\n| `getblockchaininfo` | ✔ |\n| `getblockcount` | ✔ |\n| `getblockhash` | ✔ |\n| `getblockheader` | ✔ |\n| `getblockstats` | ✔ |\n| `getchaintips` | ✔ |\n| `getdifficulty` | ✔ |\n| `getmempoolinfo` | ✔ |\n| `getnetworkhashps` | ✔ |\n\n### Mining\n\n|   Method   |   Supported?     |\n|------------|:----------------:|\n| `getmininginfo` | ✔ |\n\n### Network\n\n|   Method   |   Supported?     |\n|------------|:----------------:|\n| `getconnectioncount` | ✔ |\n| `getnetworkinfo` | ✔ |\n\n### Raw transactions\n\n|   Method   |   Supported?     |\n|------------|:----------------:|\n| `analyzepsbt` | ✔ |\n| `combinepsbt` | ✔ |\n| `decodepsbt` | ✔ |\n| `finalizepsbt` | ✔ |\n| `getrawtransaction` | ✔ |\n| `joinpsbts` | ✔ |\n| `utxoupdatepsbt` | ✔ |\n\n### Wallet\n\n|   Method   |   Supported?     |\n|------------|:----------------:|\n| `walletprocesspsbt` | ✔ |\n\n## Usage\nMinimal illustration (assuming Python 3.8+, where you can run `async` code in console)\n\n```\n$ python -m asyncio\n\u003e\u003e\u003e import asyncio\n\u003e\u003e\u003e\n\u003e\u003e\u003e from bitcoinrpc import BitcoinRPC\n\u003e\u003e\u003e rpc = BitcoinRPC.from_config(\"http://localhost:18443\", (\"rpc_user\", \"rpc_passwd\"))\n\u003e\u003e\u003e await rpc.getconnectioncount()\n10\n\u003e\u003e\u003e await rpc.aclose()  # Clean-up resource\n```\n\nYou can also use the `BitcoinRPC` as an asynchronous context manager, which does\nall the resource clean-up automatically, as the following example shows:\n\n```python\n$ cat btc_rpc_minimal.py\nimport asyncio\n\nfrom bitcoinrpc import BitcoinRPC\n\n\nasync def main():\n    async with BitcoinRPC.from_config(\"http://localhost:18443\", (\"rpc_user\", \"rpc_password\")) as rpc:\n        print(await rpc.getconnectioncount())\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\nRunning this script yields:\n```\n$ python btc_rpc_minimal.py\n10\n```\n\nIf you want customize the underlying `httpx.AsyncClient`, you can instantiate the `BitcoinRPC` with one.\nConsider the following script, where the client is configured to log every HTTP request before it is sent\nout over the wire:\n\n```python\n$ cat btc_custom_client.py\nimport asyncio\n\nimport httpx\n\nfrom bitcoinrpc import BitcoinRPC\n\n\nasync def log_request(request: httpx.Request) -\u003e None:\n    print(request.content)\n\n\nasync def main() -\u003e None:\n    client = httpx.AsyncClient(auth=(\"rpc_user\", \"rpc_password\"), event_hooks={\"request\": [log_request]})\n    async with BitcoinRPC(url=\"http://localhost:18443\", client=client) as rpc:\n        print(await rpc.getconnectioncount())\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\nRunning this script yields:\n\n```\n$ python btc_custom_client.py \nb'{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"getconnectioncount\",\"params\":[]}'\n0\n```\n\n## Testing\n\nA `Containerfile` is provided as a means to build an OCI image of a Bitcoin `regtest` node.\nBuild the image (`podman` is used, but `docker` should be fine too):\n\n```\n$ podman build \\\n  -f Containerfile \\\n  --build-arg BTC_VERSION=v24.1 \\\n  -t bitcoin-regtest:v24.1 \\\n  -t bitcoin-regtest:latest \\\n  .\n```\n\nand run it afterwards:\n\n```\n$ podman run \\\n  --rm \\\n  -it \\\n  --mount=type=bind,src=./tests/bitcoin-regtest.conf,target=/home/rpc/.bitcoin/bitcoin.conf \\\n  -p 127.0.0.1:18443:18443 \\\n  --name bitcoin-regtest \\\n  localhost/bitcoin-regtest:v24.1\n```\n\nwhich will expose the Bitcoin `regtest` node on port 18443, accesible from localhost only, with RPC user/password `rpc_user/rpc_password`.\n\nAfter you are done testing, stop the container via:\n\n```\n$ podman stop bitcoin-regtest\n```\n\n---\n\nIf you want to test against a different version of Bitcoin node, pass a different [tag](https://github.com/bitcoin/bitcoin/tags) in the build stage:\n\n```\n$ podman build \\\n  -f Containerfile \\\n  --build-arg BTC_VERSION=v25.0 \\\n  -t bitcoin-regtest:v25.0 \\\n  -t bitcoin-regtest:latest \\\n  .\n```\n\n---\n\nDifferent settings of the Bitcoin node may be passed via mounting your custom configuration file, or optionally as \"arguments\" to `podman run`:\n\n\n```\n$ podman run \\\n  --rm \\\n  -it \\\n  --mount=type=bind,src=\u003cpath/to/your/config_file\u003e,target=/home/rpc/.bitcoin/bitcoin.conf \\\n  -p 127.0.0.1:18443:18443 \\\n  --name bitcoin-regtest \\\n  localhost/bitcoin-regtest:v24.1 \u003cyour\u003e \u003cargs\u003e ...\n```\n\n---\n\nPlease, keep in mind that Bitcoin node compiled in the image is intended for testing \u0026 debugging purposes only! It may serve you as an inspiration for building\nyour own, production-ready Bitcoin node, but its intended usage is testing!\n\n---\n\nFor testing this library, install `tox` (preferably, in a fresh virtual environment).\n\nAfterwards, coding-style is enforced by running:\n\n```\n(your-venv-with-tox) $ tox run -e linters\n```\n\nand tests corresponding are run (this example uses Python3.11)\n\n```\n(your-venv-with-tox) $ tox run -e py311\n```\n\nIf 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:\n\n```\n(your-venv-with-tox) $ tox run -e py311 -- -m 'not integration'\n```\n\n\n## Changelog\n\n- **2024/02/12 - 0.7.0**: More robust handling of JSON-RPC 2.0 specification (thanks https://github.com/joxerx !)\n  * **Breaking change**: change the handling of responses with non-2xx status codes in 'BitcoinRPC.acall'.\n    Previously, said errors would be raised directly via the `httpx.Response.raise_for_status` method.\n    Now, `httpx.Response.raise_for_status` is used only when the server\n    returns an empty response, which may happen due to for example bad\n    authentication. In all other cases, defer the decision whether RPC\n    call was a success or a failure to the inspection of return JSON.\n- **2023/06/04 - 0.6.1**: Add RPC methods, mainly concerned with PSBTs\n- **2023/06/01 - 0.6.0**:\n  * `BitcoinRPC` is now instantiated with a `httpx.AsyncClient` directly and an optional `counter` argument, which is a callable that may be used for distinguishing\n    the JSON-RPC requests. Old-style instantiation, with `url` and optional user/password tuple, is kept within `BitcoinRPC.from_config` method.\n\n- **2021/12/28 - 0.5.0** change the signature of `BitcoinRPC` from `host, port, ...` to `url, ...`, delegating the creation of the node url to the caller.\n\n## License\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbibajz%2Fbitcoin-python-async-rpc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbibajz%2Fbitcoin-python-async-rpc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbibajz%2Fbitcoin-python-async-rpc/lists"}