1BITCOIND(1) User Commands BITCOIND(1)
2
6 bitcoind - manual page for bitcoind v25.1.0
7
9 bitcoind [options] Start Bitcoin Core
10
12 Bitcoin Core version v25.1.0
13
15 -?
16 Print this help message and exit
18 -alertnotify=<cmd>
20 Execute command when an alert is raised (%s in cmd is replaced
22 by message)
23 -assumevalid=<hex>
25 If this block is in the chain assume that it and its ancestors
27 are valid and potentially skip their script verification (0 to
28 verify all, default:
29 000000000000000000035c3f0d31e71a5ee24c5aaf3354689f65bd7b07dee632,
30 testnet:
31 0000000000000021bc50a89cde4870d4a81ffe0153b3c8de77b435a2fd3f6761,
32 signet:
33 0000004429ef154f7e00b4f6b46bfbe2d2678ecd351d95bbfca437ab9a5b84ec)
34 -blockfilterindex=<type>
36 Maintain an index of compact filters by block (default: 0, val‐
38 ues: basic). If <type> is not supplied or if <type> = 1, indexes
39 for all known types are enabled.
40 -blocknotify=<cmd>
42 Execute command when the best block changes (%s in cmd is re‐
44 placed by block hash)
45 -blockreconstructionextratxn=<n>
47 Extra transactions to keep in memory for compact block recon‐
49 structions (default: 100)
50 -blocksdir=<dir>
52 Specify directory to hold blocks subdirectory for *.dat files
54 (default: <datadir>)
55 -blocksonly
57 Whether to reject transactions from network peers. Automatic
59 broadcast and rebroadcast of any transactions from inbound peers
60 is disabled, unless the peer has the 'forcerelay' permission.
61 RPC transactions are not affected. (default: 0)
62 -coinstatsindex
64 Maintain coinstats index used by the gettxoutsetinfo RPC (de‐
66 fault: 0)
67 -conf=<file>
69 Specify path to read-only configuration file. Relative paths
71 will be prefixed by datadir location (only useable from command
72 line, not configuration file) (default: bitcoin.conf)
73 -daemon
75 Run in the background as a daemon and accept commands (default:
77 0)
78 -daemonwait
80 Wait for initialization to be finished before exiting. This im‐
82 plies -daemon (default: 0)
83 -datadir=<dir>
85 Specify data directory
87 -dbcache=<n>
89 Maximum database cache size <n> MiB (4 to 16384, default: 450).
91 In addition, unused mempool memory is shared for this cache (see
92 -maxmempool).
93 -debuglogfile=<file>
95 Specify location of debug log file (default: debug.log). Rela‐
97 tive paths will be prefixed by a net-specific datadir location.
98 Pass -nodebuglogfile to disable writing the log to a file.
99 -includeconf=<file>
101 Specify additional configuration file, relative to the -datadir
103 path (only useable from configuration file, not command line)
104 -loadblock=<file>
106 Imports blocks from external file on startup
108 -maxmempool=<n>
110 Keep the transaction memory pool below <n> megabytes (default:
112 300)
113 -maxorphantx=<n>
115 Keep at most <n> unconnectable transactions in memory (default:
117 100)
118 -mempoolexpiry=<n>
120 Do not keep transactions in the mempool longer than <n> hours
122 (default: 336)
123 -par=<n>
125 Set the number of script verification threads (-10 to 15, 0 =
127 auto, <0 = leave that many cores free, default: 0)
128 -persistmempool
130 Whether to save the mempool on shutdown and load on restart (de‐
132 fault: 1)
133 -pid=<file>
135 Specify pid file. Relative paths will be prefixed by a net-spe‐
137 cific datadir location. (default: bitcoind.pid)
138 -prune=<n>
140 Reduce storage requirements by enabling pruning (deleting) of
142 old blocks. This allows the pruneblockchain RPC to be called to
143 delete specific blocks and enables automatic pruning of old
144 blocks if a target size in MiB is provided. This mode is incom‐
145 patible with -txindex. Warning: Reverting this setting requires
146 re-downloading the entire blockchain. (default: 0 = disable
147 pruning blocks, 1 = allow manual pruning via RPC, >=550 = auto‐
148 matically prune block files to stay under the specified target
149 size in MiB)
150 -reindex
152 Rebuild chain state and block index from the blk*.dat files on
154 disk. This will also rebuild active optional indexes.
155 -reindex-chainstate
157 Rebuild chain state from the currently indexed blocks. When in
159 pruning mode or if blocks on disk might be corrupted, use full
160 -reindex instead. Deactivate all optional indexes before running
161 this.
162 -sandbox=<mode>
164 Use the experimental syscall sandbox in the specified mode
166 (-sandbox=log-and-abort or -sandbox=abort). Allow only expected
167 syscalls to be used by bitcoind. Note that this is an experimen‐
168 tal new feature that may cause bitcoind to exit or crash unex‐
169 pectedly: use with caution. In the "log-and-abort" mode the in‐
170 vocation of an unexpected syscall results in a debug handler be‐
171 ing invoked which will log the incident and terminate the pro‐
172 gram (without executing the unexpected syscall). In the "abort"
173 mode the invocation of an unexpected syscall results in the en‐
174 tire process being killed immediately by the kernel without exe‐
175 cuting the unexpected syscall.
176 -settings=<file>
178 Specify path to dynamic settings data file. Can be disabled with
180 -nosettings. File is written at runtime and not meant to be
181 edited by users (use bitcoin.conf instead for custom settings).
182 Relative paths will be prefixed by datadir location. (default:
183 settings.json)
184 -shutdownnotify=<cmd>
186 Execute command immediately before beginning shutdown. The need
188 for shutdown may be urgent, so be careful not to delay it long
189 (if the command doesn't require interaction with the server,
190 consider having it fork into the background).
191 -startupnotify=<cmd>
193 Execute command on startup.
195 -txindex
197 Maintain a full transaction index, used by the getrawtransaction
199 rpc call (default: 0)
200 -version
202 Print version and exit
204 Connection options:
206 -addnode=<ip>
208 Add a node to connect to and attempt to keep the connection open
210 (see the addnode RPC help for more info). This option can be
211 specified multiple times to add multiple nodes; connections are
212 limited to 8 at a time and are counted separately from the -max‐
213 connections limit.
214 -asmap=<file>
216 Specify asn mapping used for bucketing of the peers (default:
218 ip_asn.map). Relative paths will be prefixed by the net-specific
219 datadir location.
220 -bantime=<n>
222 Default duration (in seconds) of manually configured bans (de‐
224 fault: 86400)
225 -bind=<addr>[:<port>][=onion]
227 Bind to given address and always listen on it (default:
229 0.0.0.0). Use [host]:port notation for IPv6. Append =onion to
230 tag any incoming connections to that address and port as incom‐
231 ing Tor connections (default: 127.0.0.1:8334=onion, testnet:
232 127.0.0.1:18334=onion, signet: 127.0.0.1:38334=onion, regtest:
233 127.0.0.1:18445=onion)
234 -cjdnsreachable
236 If set, then this host is configured for CJDNS (connecting to
238 fc00::/8 addresses would lead us to the CJDNS network, see
239 doc/cjdns.md) (default: 0)
240 -connect=<ip>
242 Connect only to the specified node; -noconnect disables auto‐
244 matic connections (the rules for this peer are the same as for
245 -addnode). This option can be specified multiple times to con‐
246 nect to multiple nodes.
247 -discover
249 Discover own IP addresses (default: 1 when listening and no -ex‐
251 ternalip or -proxy)
252 -dns
254 Allow DNS lookups for -addnode, -seednode and -connect (default:
256 1)
257 -dnsseed
259 Query for peer addresses via DNS lookup, if low on addresses
261 (default: 1 unless -connect used or -maxconnections=0)
262 -externalip=<ip>
264 Specify your own public address
266 -fixedseeds
268 Allow fixed seeds if DNS seeds don't provide peers (default: 1)
270 -forcednsseed
272 Always query for peer addresses via DNS lookup (default: 0)
274 -i2pacceptincoming
276 Whether to accept inbound I2P connections (default: 1). Ignored
278 if -i2psam is not set. Listening for inbound I2P connections is
279 done through the SAM proxy, not by binding to a local address
280 and port.
281 -i2psam=<ip:port>
283 I2P SAM proxy to reach I2P peers and accept I2P connections (de‐
285 fault: none)
286 -listen
288 Accept connections from outside (default: 1 if no -proxy, -con‐
290 nect or -maxconnections=0)
291 -listenonion
293 Automatically create Tor onion service (default: 1)
295 -maxconnections=<n>
297 Maintain at most <n> connections to peers (default: 125). This
299 limit does not apply to connections manually added via -addnode
300 or the addnode RPC, which have a separate limit of 8.
301 -maxreceivebuffer=<n>
303 Maximum per-connection receive buffer, <n>*1000 bytes (default:
305 5000)
306 -maxsendbuffer=<n>
308 Maximum per-connection send buffer, <n>*1000 bytes (default:
310 1000)
311 -maxtimeadjustment
313 Maximum allowed median peer time offset adjustment. Local per‐
315 spective of time may be influenced by outbound peers forward or
316 backward by this amount (default: 4200 seconds).
317 -maxuploadtarget=<n>
319 Tries to keep outbound traffic under the given target per 24h.
321 Limit does not apply to peers with 'download' permission or
322 blocks created within past week. 0 = no limit (default: 0M). Op‐
323 tional suffix units [k|K|m|M|g|G|t|T] (default: M). Lowercase is
324 1000 base while uppercase is 1024 base
325 -natpmp
327 Use NAT-PMP to map the listening port (default: 0)
329 -networkactive
331 Enable all P2P network activity (default: 1). Can be changed by
333 the setnetworkactive RPC command
334 -onion=<ip:port>
336 Use separate SOCKS5 proxy to reach peers via Tor onion services,
338 set -noonion to disable (default: -proxy)
339 -onlynet=<net>
341 Make automatic outbound connections only to network <net> (ipv4,
343 ipv6, onion, i2p, cjdns). Inbound and manual connections are not
344 affected by this option. It can be specified multiple times to
345 allow multiple networks.
346 -peerblockfilters
348 Serve compact block filters to peers per BIP 157 (default: 0)
350 -peerbloomfilters
352 Support filtering of blocks and transaction with bloom filters
354 (default: 0)
355 -port=<port>
357 Listen for connections on <port>. Nodes not using the default
359 ports (default: 8333, testnet: 18333, signet: 38333, regtest:
360 18444) are unlikely to get incoming connections. Not relevant
361 for I2P (see doc/i2p.md).
362 -proxy=<ip:port>
364 Connect through SOCKS5 proxy, set -noproxy to disable (default:
366 disabled)
367 -proxyrandomize
369 Randomize credentials for every proxy connection. This enables
371 Tor stream isolation (default: 1)
372 -seednode=<ip>
374 Connect to a node to retrieve peer addresses, and disconnect.
376 This option can be specified multiple times to connect to multi‐
377 ple nodes.
378 -timeout=<n>
380 Specify socket connection timeout in milliseconds. If an initial
382 attempt to connect is unsuccessful after this amount of time,
383 drop it (minimum: 1, default: 5000)
384 -torcontrol=<ip>:<port>
386 Tor control port to use if onion listening enabled (default:
388 127.0.0.1:9051)
389 -torpassword=<pass>
391 Tor control port password (default: empty)
393 -upnp
395 Use UPnP to map the listening port (default: 1 when listening
397 and no -proxy)
398 -whitebind=<[permissions@]addr>
400 Bind to the given address and add permission flags to the peers
402 connecting to it. Use [host]:port notation for IPv6. Allowed
403 permissions: bloomfilter (allow requesting BIP37 filtered blocks
404 and transactions), noban (do not ban for misbehavior; implies
405 download), forcerelay (relay transactions that are already in
406 the mempool; implies relay), relay (relay even in -blocksonly
407 mode, and unlimited transaction announcements), mempool (allow
408 requesting BIP35 mempool contents), download (allow getheaders
409 during IBD, no disconnect after maxuploadtarget limit), addr
410 (responses to GETADDR avoid hitting the cache and contain random
411 records with the most up-to-date info). Specify multiple permis‐
412 sions separated by commas (default: download,noban,mempool,re‐
413 lay). Can be specified multiple times.
414 -whitelist=<[permissions@]IP address or network>
416 Add permission flags to the peers connecting from the given IP
418 address (e.g. 1.2.3.4) or CIDR-notated network (e.g.
419 1.2.3.0/24). Uses the same permissions as -whitebind. Can be
420 specified multiple times.
421 Wallet options:
423 -addresstype
425 What type of addresses to use ("legacy", "p2sh-segwit",
427 "bech32", or "bech32m", default: "bech32")
428 -avoidpartialspends
430 Group outputs by address, selecting many (possibly all) or none,
432 instead of selecting on a per-output basis. Privacy is improved
433 as addresses are mostly swept with fewer transactions and out‐
434 puts are aggregated in clean change addresses. It may result in
435 higher fees due to less optimal coin selection caused by this
436 added limitation and possibly a larger-than-necessary number of
437 inputs being used. Always enabled for wallets with "avoid_reuse"
438 enabled, otherwise default: 0.
439 -changetype
441 What type of change to use ("legacy", "p2sh-segwit", "bech32",
443 or "bech32m"). Default is "legacy" when -addresstype=legacy,
444 else it is an implementation detail.
445 -consolidatefeerate=<amt>
447 The maximum feerate (in BTC/kvB) at which transaction building
449 may use more inputs than strictly necessary so that the wallet's
450 UTXO pool can be reduced (default: 0.0001).
451 -disablewallet
453 Do not load the wallet and disable wallet RPC calls
455 -discardfee=<amt>
457 The fee rate (in BTC/kvB) that indicates your tolerance for dis‐
459 carding change by adding it to the fee (default: 0.0001). Note:
460 An output is discarded if it is dust at this rate, but we will
461 always discard up to the dust relay fee and a discard fee above
462 that is limited by the fee estimate for the longest target
463 -fallbackfee=<amt>
465 A fee rate (in BTC/kvB) that will be used when fee estimation
467 has insufficient data. 0 to entirely disable the fallbackfee
468 feature. (default: 0.00)
469 -keypool=<n>
471 Set key pool size to <n> (default: 1000). Warning: Smaller sizes
473 may increase the risk of losing funds when restoring from an old
474 backup, if none of the addresses in the original keypool have
475 been used.
476 -maxapsfee=<n>
478 Spend up to this amount in additional (absolute) fees (in BTC)
480 if it allows the use of partial spend avoidance (default: 0.00)
481 -mintxfee=<amt>
483 Fee rates (in BTC/kvB) smaller than this are considered zero fee
485 for transaction creation (default: 0.00001)
486 -paytxfee=<amt>
488 Fee rate (in BTC/kvB) to add to transactions you send (default:
490 0.00)
491 -signer=<cmd>
493 External signing tool, see doc/external-signer.md
495 -spendzeroconfchange
497 Spend unconfirmed change when sending transactions (default: 1)
499 -txconfirmtarget=<n>
501 If paytxfee is not set, include enough fee so transactions begin
503 confirmation on average within n blocks (default: 6)
504 -wallet=<path>
506 Specify wallet path to load at startup. Can be used multiple
508 times to load multiple wallets. Path is to a directory contain‐
509 ing wallet data and log files. If the path is not absolute, it
510 is interpreted relative to <walletdir>. This only loads existing
511 wallets and does not create new ones. For backwards compatibil‐
512 ity this also accepts names of existing top-level data files in
513 <walletdir>.
514 -walletbroadcast
516 Make the wallet broadcast transactions (default: 1)
518 -walletdir=<dir>
520 Specify directory to hold wallets (default: <datadir>/wallets if
522 it exists, otherwise <datadir>)
523 -walletnotify=<cmd>
525 Execute command when a wallet transaction changes. %s in cmd is
527 replaced by TxID, %w is replaced by wallet name, %b is replaced
528 by the hash of the block including the transaction (set to 'un‐
529 confirmed' if the transaction is not included) and %h is re‐
530 placed by the block height (-1 if not included). %w is not cur‐
531 rently implemented on windows. On systems where %w is supported,
532 it should NOT be quoted because this would break shell escaping
533 used to invoke the command.
534 -walletrbf
536 Send transactions with full-RBF opt-in enabled (RPC only, de‐
538 fault: 1)
539 ZeroMQ notification options:
541 -zmqpubhashblock=<address>
543 Enable publish hash block in <address>
545 -zmqpubhashblockhwm=<n>
547 Set publish hash block outbound message high water mark (de‐
549 fault: 1000)
550 -zmqpubhashtx=<address>
552 Enable publish hash transaction in <address>
554 -zmqpubhashtxhwm=<n>
556 Set publish hash transaction outbound message high water mark
558 (default: 1000)
559 -zmqpubrawblock=<address>
561 Enable publish raw block in <address>
563 -zmqpubrawblockhwm=<n>
565 Set publish raw block outbound message high water mark (default:
567 1000)
568 -zmqpubrawtx=<address>
570 Enable publish raw transaction in <address>
572 -zmqpubrawtxhwm=<n>
574 Set publish raw transaction outbound message high water mark
576 (default: 1000)
577 -zmqpubsequence=<address>
579 Enable publish hash block and tx sequence in <address>
581 -zmqpubsequencehwm=<n>
583 Set publish hash sequence message high water mark (default:
585 1000)
586 Debugging/Testing options:
588 -debug=<category>
590 Output debug and trace logging (default: -nodebug, supplying
592 <category> is optional). If <category> is not supplied or if
593 <category> = 1, output all debug and trace logging. <category>
594 can be: addrman, bench, blockstorage, cmpctblock, coindb, esti‐
595 matefee, http, i2p, ipc, leveldb, libevent, mempool, mempoolrej,
596 net, proxy, prune, qt, rand, reindex, rpc, scan, selectcoins,
597 tor, txreconciliation, util, validation, walletdb, zmq. This op‐
598 tion can be specified multiple times to output multiple cate‐
599 gories.
600 -debugexclude=<category>
602 Exclude debug and trace logging for a category. Can be used in
604 conjunction with -debug=1 to output debug and trace logging for
605 all categories except the specified category. This option can be
606 specified multiple times to exclude multiple categories.
607 -help-debug
609 Print help message with debugging options and exit
611 -logips
613 Include IP addresses in debug output (default: 0)
615 -logsourcelocations
617 Prepend debug output with name of the originating source loca‐
619 tion (source file, line number and function name) (default: 0)
620 -logthreadnames
622 Prepend debug output with name of the originating thread (only
624 available on platforms supporting thread_local) (default: 0)
625 -logtimestamps
627 Prepend debug output with timestamp (default: 1)
629 -maxtxfee=<amt>
631 Maximum total fees (in BTC) to use in a single wallet transac‐
633 tion; setting this too low may abort large transactions (de‐
634 fault: 0.10)
635 -printtoconsole
637 Send trace/debug info to console (default: 1 when no -daemon. To
639 disable logging to file, set -nodebuglogfile)
640 -shrinkdebugfile
642 Shrink debug.log file on client startup (default: 1 when no -de‐
644 bug)
645 -uacomment=<cmt>
647 Append comment to the user agent string
649 Chain selection options:
651 -chain=<chain>
653 Use the chain <chain> (default: main). Allowed values: main,
655 test, signet, regtest
656 -signet
658 Use the signet chain. Equivalent to -chain=signet. Note that the
660 network is defined by the -signetchallenge parameter
661 -signetchallenge
663 Blocks must satisfy the given script to be considered valid
665 (only for signet networks; defaults to the global default signet
666 test network challenge)
667 -signetseednode
669 Specify a seed node for the signet network, in the host‐
671 name[:port] format, e.g. sig.net:1234 (may be used multiple
672 times to specify multiple seed nodes; defaults to the global de‐
673 fault signet test network seed node(s))
674 -testnet
676 Use the test chain. Equivalent to -chain=test.
678 Node relay options:
680 -bytespersigop
682 Equivalent bytes per sigop in transactions for relay and mining
684 (default: 20)
685 -datacarrier
687 Relay and mine data carrier transactions (default: 1)
689 -datacarriersize
691 Maximum size of data in data carrier transactions we relay and
693 mine (default: 83)
694 -mempoolfullrbf
696 Accept transaction replace-by-fee without requiring replaceabil‐
698 ity signaling (default: 0)
699 -minrelaytxfee=<amt>
701 Fees (in BTC/kvB) smaller than this are considered zero fee for
703 relaying, mining and transaction creation (default: 0.00001)
704 -permitbaremultisig
706 Relay non-P2SH multisig (default: 1)
708 -whitelistforcerelay
710 Add 'forcerelay' permission to whitelisted inbound peers with
712 default permissions. This will relay transactions even if the
713 transactions were already in the mempool. (default: 0)
714 -whitelistrelay
716 Add 'relay' permission to whitelisted inbound peers with default
718 permissions. This will accept relayed transactions even when not
719 relaying transactions (default: 1)
720 Block creation options:
722 -blockmaxweight=<n>
724 Set maximum BIP141 block weight (default: 3996000)
726 -blockmintxfee=<amt>
728 Set lowest fee rate (in BTC/kvB) for transactions to be included
730 in block creation. (default: 0.00001)
731 RPC server options:
733 -rest
735 Accept public REST requests (default: 0)
737 -rpcallowip=<ip>
739 Allow JSON-RPC connections from specified source. Valid for <ip>
741 are a single IP (e.g. 1.2.3.4), a network/netmask (e.g.
742 1.2.3.4/255.255.255.0) or a network/CIDR (e.g. 1.2.3.4/24). This
743 option can be specified multiple times
744 -rpcauth=<userpw>
746 Username and HMAC-SHA-256 hashed password for JSON-RPC connec‐
748 tions. The field <userpw> comes in the format: <USER‐
749 NAME>:<SALT>$<HASH>. A canonical python script is included in
750 share/rpcauth. The client then connects normally using the rp‐
751 cuser=<USERNAME>/rpcpassword=<PASSWORD> pair of arguments. This
752 option can be specified multiple times
753 -rpcbind=<addr>[:port]
755 Bind to given address to listen for JSON-RPC connections. Do not
757 expose the RPC server to untrusted networks such as the public
758 internet! This option is ignored unless -rpcallowip is also
759 passed. Port is optional and overrides -rpcport. Use [host]:port
760 notation for IPv6. This option can be specified multiple times
761 (default: 127.0.0.1 and ::1 i.e., localhost)
762 -rpccookiefile=<loc>
764 Location of the auth cookie. Relative paths will be prefixed by
766 a net-specific datadir location. (default: data dir)
767 -rpcpassword=<pw>
769 Password for JSON-RPC connections
771 -rpcport=<port>
773 Listen for JSON-RPC connections on <port> (default: 8332, test‐
775 net: 18332, signet: 38332, regtest: 18443)
776 -rpcserialversion
778 Sets the serialization of raw transaction or block hex returned
780 in non-verbose mode, non-segwit(0) or segwit(1) (default: 1)
781 -rpcthreads=<n>
783 Set the number of threads to service RPC calls (default: 4)
785 -rpcuser=<user>
787 Username for JSON-RPC connections
789 -rpcwhitelist=<whitelist>
791 Set a whitelist to filter incoming RPC calls for a specific
793 user. The field <whitelist> comes in the format: <USERNAME>:<rpc
794 1>,<rpc 2>,...,<rpc n>. If multiple whitelists are set for a
795 given user, they are set-intersected. See -rpcwhitelistdefault
796 documentation for information on default whitelist behavior.
797 -rpcwhitelistdefault
799 Sets default behavior for rpc whitelisting. Unless rpcwhitelist‐
801 default is set to 0, if any -rpcwhitelist is set, the rpc server
802 acts as if all rpc users are subject to empty-unless-other‐
803 wise-specified whitelists. If rpcwhitelistdefault is set to 1
804 and no -rpcwhitelist is set, rpc server acts as if all rpc users
805 are subject to empty whitelists.
806 -server
808 Accept command line and JSON-RPC commands
810
812 Copyright (C) 2009-2023 The Bitcoin Core developers
813 Please contribute if you find Bitcoin Core useful. Visit <https://bit‐
815 coincore.org/> for further information about the software. The source
816 code is available from <https://github.com/bitcoin/bitcoin>.
817 This is experimental software. Distributed under the MIT software li‐
819 cense, see the accompanying file COPYING or <https://opensource.org/li‐
820 censes/MIT>
821bitcoind v25.1.0 October 2023 BITCOIND(1)