Release notes¶
Notable changes are documented here. CHANGELOG.md is the record behind them: this file says what a user has to act on, that one says what changed and why.
Versions are calendar versions, YYYY.M.D: the
number says when a release was cut, which is the useful thing to know about
a client whose recorded replies come from the Core versions of that month.
It promises nothing about compatibility, so a breaking change is announced
in this file — read it before upgrading, rather than a digit.
v2026.11.2¶
A signet challenge longer than 0xffff bytes derives its magic.
magic_from_signet_challengereturns it, where it raisedBtcRpcValueError, andassert_chain("signet", signet_challenge=...)accepts such a challenge. A node that reports one is compared like any other signet: a challenge other than the expected one raises theBtcRpcValueErrorof a disagreement, where it raisedFetchError. A caller that relied on the refusal checks the length itself.Core 28 and 29 are no longer checked.
integration-bitcoind.ymlasks a live node of Core 27.2, 30.4, 31.2 and 32.1: the majors Core maintains, and the JSON-RPC 1.1 boundary.
v2026.10.30¶
The empty signet challenge is a signet like any other.
magic_from_signet_challenge("")returns1406e058, the magic a Core node started with-signetchallenge=uses, where it raisedBtcRpcValueError.assert_chain("signet", signet_challenge="")passes against such a node. Expecting another challenge there raises theBtcRpcValueErrorof a disagreement, where it raisedFetchError. A caller that relied on the empty challenge being refused checks for it itself.Verifying this release names the signer without a ref. Its files are signed by btclib-org/.github’s
reusable-build.ymlat a pinned commit, not atmain, so the--signer-workflowending in@refs/heads/mainthat v2026.10.23’s SECURITY.md gave refuses them. SECURITY.md has the command, which also compares the repository by its id.
v2026.10.23¶
The refusals below raise different exceptions or say less. A caller that catches the old exceptions or matches the old messages has to change:
A credential or a wallet name that utf-8 cannot encode raises
BtcRpcValueError, and a cookie path the filesystem encoding refuses, or one with a NUL, raisesFetchError.auth_headerandfor_walletraised aUnicodeEncodeErrorholding the whole text, andcookie_authaUnicodeEncodeError, or aValueErrorfor the NUL. Catch the new types.A refusal names less. The path of a refused parameter shows
...for a name over 16 characters, where it showed the first 16. A non-integermax_body_sizeis named by its type. A non-finiteDecimalparameter readsnot a json number in the rpc params: a Decimal, without its value. A refused JSON number in a reply, and aDecimalparameter pastsys.get_int_max_str_digits, quote no token and no exponent. Match on the exception type, not on these messages.
v2026.10.17¶
Nothing to act on: the public API is the one v2026.10.8 shipped, and the module differs from it only in comments and a docstring.
SECURITY.md’s Limitations, not vulnerabilities says why the client adds no TLS of its own, and what keeps rpc credentials off the wire for a node that is not on loopback.
v2026.10.8¶
A refusal no longer quotes an rpc parameter of a type JSON cannot carry (GHSA-cg87-q4qx-qw8p). Every release on PyPI, v2026.8.6 to v2026.10.4, quoted an rpc parameter that is not a JSON value in the error of
call, and ofcall_raw,call_batchandRpcChannelwhere the release has them, so a wallet passphrase or a key passed asbytes, or as an object whosereprshows it, went wherever the error went. The refusals of a method, a wallet name, a parameter name, the jsonrpc marker, a REST path, a timeout, a signet challenge and a header quoted theirs too. A cookie file that is not ASCII, and a reply that is not UTF-8 or not JSON, chained an error that holds the whole file or reply. Upgrade, and treat a passphrase or key that such an error may have recorded, in a log, a report or a traceback, as exposed.A refusal now names a parameter by its type and path, as in
rpc parameter that is not a json value: a bytes at params[0]. A chain or network name of 16 characters or fewer is still shown, so that a typo stays visible; a longer one reads(too long to quote). A caller that matches on message text finds the value gone, the quote marks gone from the client’s chain name inassert_chain’s refusals, and no codec detail in a cookie or reply refusal.
v2026.10.4¶
Verifying a release’s attestation names a new signer and the tag.
gh attestation verifytakes--signer-workflow btclib-org/.github/.github/workflows/reusable-build.yml@refs/heads/mainand--source-ref refs/tags/v<version>; SECURITY.md has the command. SECURITY.md names the signer of an earlier release. The bundle is attached asv<version>.intoto.jsonl, notv<version>.attestation.jsonl.A url the client refuses is no longer repeated in the message (issue #575). Upgrade; a caller matching on the refusal text sees no url, and
expected http(s)where the scheme was named.A reply number with an exponent past
sys.get_int_max_str_digitsis aFetchError(issue #576). Raise the limit withsys.set_int_max_str_digitsif a node legitimately sends one; 0 lifts it.str()of anRpcErrorwrites non-printable characters of the node’s message as escapes (issue #577). Readargs[0]for the text as it arrived.A
cookie_paththat is not a regular file is aFetchError, a pipe that would deliver a cookie included (issue #579): point it at a file.The TLS key log is never written (issue #580).
SSLKEYLOGFILEis ignored by both transports.SSL_CERT_FILEandSSL_CERT_DIRstill choose the trust store. A program that replacesssl._create_default_https_contextto turn verification off finds it ignored: verification stays on, and such a caller passes atransportof its own, as does one that must not honour the two variables. On Python 3.11 and 3.12 a server certificate OpenSSL judges malformed (VERIFY_X509_STRICT) is refused, as on 3.13 and later; a node behind such a certificate needs the certificate replaced.A malformed header or url is a
BtcRpcValueError(issue #578).http_requestrefuses a header name that is not a token and a value with a CR, LF, NUL or a character latin-1 cannot encode; the client refuses a url with whitespace, control characters or a malformed IPv6 host when it is built. Both areBtcRpcValueError, aValueError, so a caller catching theValueErrorhttp.clientraised for a header needs no change.The transports do not repeat a malformed url (issue #616).
http_request,urlopen_transportandSessionTransportrefuse a url with whitespace or a control character, no host, a port that is no number, or a login, asBtcRpcValueError, and an error namesscheme://host[:port]and not the path or query. A caller that read the full url from aFetchErrorreads the host there and keeps its own copy of the rest. A credential goes in anAuthorizationheader.A url with a non-ASCII character is a
BtcRpcValueError(issue #619). The client,http_requestand the two transports refuse it, a host included: write an internationalized host in its ASCII form, for examplexn--bcher-kva.exampleforbücher.example.
v2026.9.29¶
Python 3.10 is no longer supported: requires-python is >=3.11. On 3.10
an installer resolves to v2026.9.24, the last release that runs there;
staying current means moving to 3.11 or later.
SessionTransport no longer sends a request a second time when a kept
connection closes after the request was written: that is a FetchError
like any other failure of the exchange, and a caller that wants an
idempotent call retried on it writes that retry.
SessionTransport(max_body_size=...) is a TypeError: the limit is each
call’s own max_body_size, which now reaches the session’s read as it
reaches the default transport’s.
v2026.9.24¶
Nothing to act on: the module is the one v2026.9.3 shipped, and its public surface did not move.
The GitHub release now carries a CycloneDX bill of materials,
bitcoin_core_rpc-2026.9.24.cdx.json, attested with the distribution
files. Its components list is empty, this distribution declaring no
dependency.
v2026.9.3¶
Nothing to act on: both additions to the public surface are opt-in.
BitcoinCoreRestClient reads Core’s -rest interface — get_bin for a
.bin path, get_json for a .json one, no credentials, sharing only
the transport and the chain vocabulary with BitcoinCoreRpcClient.
errors.py gains RPCErrorCode, an IntEnum naming Core’s own error
codes; RpcError.code stays a plain int, so nothing that already
reads it changes.
v2026.8.29¶
bitcoin_core_rpc is now a package of four modules —
errors.py, chains.py, transport.py, client.py — behind an
__init__.py that still answers every name import bitcoin_core_rpc did
before. Nothing in the public surface moved, so pip install or a
dependency bump is the whole of what this asks of you. If you took a copy
of the old single file rather than installing it, that copy is now the
only channel it will keep working through: this release is not a file to
replace it with.
Every public exception’s qualified name gained .errors in it — a
traceback now reads bitcoin_core_rpc.errors.RpcError, not
bitcoin_core_rpc.RpcError. except RpcError, isinstance and
unpickling all match on the class itself and do not see the difference;
a log line or a test asserting the name as text does.
v2026.8.20¶
Nothing to act on. Every change this cycle is repository tooling — workflows and CI configuration, recorded in CHANGELOG.md — and the library itself is unchanged since v2026.8.13.
v2026.8.13¶
from_chain("signet", verify_chain=True) now holds the node to the
default signet, where it accepted any node answering signet. Core
reports that one string for every signet there is, so the old check passed
for a node on somebody else’s chain. If that is your case, pass the
challenge you mean: from_chain("signet", verify_chain=True, signet_challenge=...), hex or bytes, as -signetchallenge takes it. The
comparison is of the p2p magic the challenge derives, so upper case and
lower case are the same challenge.
Two things are refused that were previously accepted, both of them a check
that would not be made: a signet_challenge with verify_chain off, and
one for a chain that is no signet. Both are BtcRpcValueError at the call,
before a client is built or a node is reached.
assert_chain(chain, signet_challenge=...) is that check as a method, for
a client built against an explicit url — a node on another host, or behind
a proxy — where from_chain was the only way to get it. Nothing to do if
you already call from_chain(verify_chain=True): that is now this method.
v2026.8.12¶
from_chain works on macOS and Windows. default_datadir answers Core’s
own datadir for the platform it runs on — %APPDATA%\Bitcoin on Windows,
~/Library/Application Support/Bitcoin on macOS, ~/.bitcoin on
everything else — where it answered the last of those everywhere, so on the
first two the derived cookie path was one no node writes and every bare
from_chain() failed with a “no such file” that reads as a node that is
down. Nothing to do to get the fix, and a caller passing cookie_path or
user/password is untouched: that path is derived only when neither was
given. What to check is a macOS or Windows setup that was made to agree
with the old answer — a node started with -datadir=~/.bitcoin there, or a
symlink standing in for one. It is still reachable, by the cookie_path
that setup no longer needs to be a workaround for.
from_chain’s refusal when there is no directory to derive from names
APPDATA now, that being the Windows base and one an environment can
simply not have. Only its wording changed; it is the same
BtcRpcValueError, for the same reason, and still names cookie_path as
the answer.
A cookie file that is not there raises CookieNotFoundError now, with the
message no rpc cookie file <path>: bitcoind writes one while it runs with its rpc server enabled. It is a FetchError, so except FetchError
catches it as before; code matching on the text has one to update, the case
previously arriving as unreadable rpc cookie file <path>: [Errno 2] No such file or directory. Everything else at that path — a directory, a mode
that excludes this user, a file that is no cookie — keeps the
unreadable message and the plain FetchError, that being a file to go and
look at where an absent cookie is a node to start.
cookie_path_from_chain(chain, datadir) is what derives such a path: the
datadir, the chain’s subdirectory and .cookie, which from_chain builds
its own with. Use it instead of assembling the path by hand wherever
from_chain does not do it for you — a node started with -datadir=
somewhere else, or one reached at a url of your own, which is the
constructor and derives nothing.
for_wallet on a client that is already a wallet endpoint raises
BtcRpcValueError now, where it appended a second one and built
/wallet/hot/wallet/cold — a path no node serves, so the call that used it
failed at the node. Derive every wallet’s client from the client built for
the node: node.for_wallet("hot") and node.for_wallet("cold"), not
node.for_wallet("hot").for_wallet("cold"). A url passed to the constructor
ending in /wallet/<name> is refused by the same check — pass the node’s
endpoint and let for_wallet add the wallet. A wallet named wallet is
unaffected: that is a name to add, not one already added.
The repository’s default branch is main, and it is the only one: master
was renamed to it and dev is gone. GitHub redirects the old links and
retargets open pull requests, so nothing breaks on its own; a clone follows
with git fetch origin && git remote set-head origin -a, and a branch
still based on dev is rebased onto main. The upstream url in the module
docstring — the one a vendored copy is asked to record beside itself —
names main, and the repository name this one was renamed from is
corrected with it.
v2026.8.8¶
The body of a failure is bounded by timeout now, not only by
MAX_ERROR_BODY_SIZE and the socket’s own per-recv timeout. A peer
answering with an error page that keeps sending, one octet inside that
per-packet limit at a time, no longer holds the call for as long as the
page takes to trickle in; it fails at the deadline instead, the way an
answer already did.
http_request’s own timeout is refused now where it used to reach the
socket layer unexamined: a 0, a negative number, True or a NaN
raises BtcRpcTypeError or BtcRpcValueError here, the same refusal
BitcoinCoreRpcClient already gave its own timeout and
request_timeout. Only a caller passing a transport of their own
straight to http_request reaches this — BitcoinCoreRpcClient never
forwarded a bad one to begin with.
v2026.8.7¶
The timeout now bounds the whole exchange rather than each socket
operation, so a call cannot outlive it by waiting on a peer that keeps
sending. If you fetch replies large enough to take longer than the timeout
to arrive — a big getblock over a slow link — raise request_timeout
for those calls; they would previously have succeeded under a timeout that
did not cover them.
Requests carry User-Agent: bitcoin-core-rpc, where they carried urllib’s
Python-urllib/3.x. Anything filtering or logging by user agent in front
of a node — a reverse proxy, a WAF rule — sees the new string.
Three arguments are refused now where they used to fail later or not at
all: a transport that is not callable, a cookie_path that is no path,
and a wallet_name that is not a string. Each raises BtcRpcTypeError at
the call that supplied it. The one to check for is
for_wallet(b"hot") — bytes built an endpoint before, from a name that
was never spelled that way, and is refused now.
Code matching on the text of a size refusal has three to update: they name
max_body_size now, as more than the max_body_size of 8001024 rather
than more than the 8001024 allowed.
Two exported functions are renamed, with no alias left behind:
core_chain_from_network is chain_from_network and
network_from_core_chain is network_from_chain. They take and return
what they always did.
Code matching on the text of an error has one more to check: an unknown
chain is now refused as unknown Core chain: ... everywhere, including
BitcoinCoreRpcClient.from_chain, which said unknown chain: ....
v2026.8.6¶
The first release. There is nothing to act on and nothing to migrate.
pip install bitcoin-core-rpc, or copy bitcoin_core_rpc/__init__.py — one
source file with nothing but the standard library behind it, which is what
makes the second option a supported one rather than a fallback.
If you are coming from python-bitcoinrpc’s AuthServiceProxy, or from the
copy of it Bitcoin Core’s test framework maintains, this is not a drop-in
replacement and does not try to be. Four things change, and the module
docstring spells each of them out with the reason:
a method is an argument, not an attribute
credentials leave the url
JSONRPCExceptionbecomes three exceptionsbatch_has no equivalent; a loop overcallis the replacement